Add a simple CI workflow: TypeScript lint and cargo check

.kiro/specs/ci-workflow-gaps/.config.kiro

@@ -0,0 +1 @@
+{"specId": "8a94958a-9861-4602-9055-fe1f500825d6", "workflowType": "requirements-first", "specType": "feature"}

.kiro/specs/ci-workflow-gaps/design.md

@@ -0,0 +1,200 @@
+# Design Document: CI Workflow Gaps
+
+## Overview
+
+This design closes three gaps left open after the initial `ci.yml` merge (issue #19):
+
+1. **Branch trigger** — add `phase-1-scaffold` to the `on.push.branches` and `on.pull_request.branches` lists so the workflow fires on that branch too.
+2. **Inline comments** — annotate `ci.yml` with YAML comments that tell contributors where and how to add new steps.
+3. **CI documentation** — insert a "CI / Continuous Integration" section into `CONTRIBUTING.md` covering what runs, when it runs, and how to replicate it locally.
+
+All changes are purely textual edits to two existing files. No new source code, dependencies, or infrastructure is introduced.
+
+---
+
+## Architecture
+
+No architectural changes are required. The feature operates entirely at the repository-metadata layer:
+
+```
+Repository root
+├── .github/
+│   └── workflows/
+│       └── ci.yml          ← edit: branch triggers + inline comments
+└── CONTRIBUTING.md         ← edit: add CI section
+```
+
+The GitHub Actions runtime interprets `ci.yml` declaratively; the runner topology (ubuntu-latest, the job matrix, caching) is unchanged.
+
+---
+
+## Components and Interfaces
+
+### Component 1: `ci.yml` — Branch Triggers
+
+**Location**: `.github/workflows/ci.yml`, `on` block (lines 3–7).
+
+**Current state**:
+```yaml
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+```
+
+**Target state**:
+```yaml
+on:
+  push:
+    branches: [ "main", "phase-1-scaffold" ]
+  pull_request:
+    branches: [ "main", "phase-1-scaffold" ]
+```
+
+**Interface contract**: GitHub Actions evaluates the `branches` list as an ordered set of glob patterns. Adding a literal branch name has no side-effects on existing triggers.
+
+---
+
+### Component 2: `ci.yml` — Inline Comments
+
+**Location**: `.github/workflows/ci.yml`, `steps` block.
+
+Two comment zones are required:
+
+1. **Top-of-steps comment** — immediately above the first step, explaining the purpose of the job and inviting extension.
+2. **End-of-steps comment** — after the last step (`Vitest Check`), marking the point where new steps should be inserted and giving a concrete example.
+
+Example placement:
+
+```yaml
+    steps:
+    # ─── Core checks ────────────────────────────────────────────────────────────
+    # To add a new step (e.g., a build or integration-test step), append it below
+    # the last existing step, following the same `- name: / run:` pattern.
+    - uses: actions/checkout@v4
+    ...
+    - name: Vitest Check
+      run: npx vitest run
+
+    # ─── Add new steps here ──────────────────────────────────────────────────────
+    # Example:
+    #   - name: Build Tauri App
+    #     run: npm run tauri build -- --debug
+```
+
+**Constraint**: Every existing step name, `run` command, `working-directory`, and `uses` directive must remain byte-for-byte identical after this edit.
+
+---
+
+### Component 3: `CONTRIBUTING.md` — CI Section
+
+**Location**: `CONTRIBUTING.md`.
+
+**Insertion point**: After the existing "🧪 Verification Checks" section and before the "🔀 Pull Request Process" section. This placement is logical because a contributor reading the verification steps will naturally want to know how those same steps are enforced automatically.
+
+**Section content requirements** (from Requirements 3.1–3.4):
+
+| Item | Content |
+|---|---|
+| Heading | `## 🤖 CI / Continuous Integration` |
+| When CI runs | Every push to `main` and `phase-1-scaffold`; every PR targeting those branches |
+| Checks listed | Rust Clippy, Rust tests, Rust format check, TypeScript type check, ESLint check, Vitest tests |
+| Local commands | Exact commands to reproduce each check |
+
+**Target section**:
+
+```markdown
+## 🤖 CI / Continuous Integration
+
+CI runs automatically via GitHub Actions on every **pull request** and every **push to `main` or `phase-1-scaffold`**.
+
+### What CI checks
+
+| Check | Tool |
+|---|---|
+| Rust linting | `cargo clippy --all-targets --all-features -- -D warnings` |
+| Rust tests | `cargo test --all` |
+| Rust formatting | `cargo fmt --check` |
+| TypeScript types | `npx tsc --noEmit` |
+| ESLint | `npx eslint . --max-warnings 0` |
+| Frontend tests | `npx vitest run` |
+
+### Running CI checks locally
+
+Run the following from the repository root to replicate every CI check:
+
+```bash
+# Rust checks (run from src-tauri/)
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all
+cargo fmt --check
+
+# Frontend checks (run from repo root)
+npx tsc --noEmit
+npx eslint . --max-warnings 0
+npx vitest run
+```
+
+If all commands exit with code 0, your branch will pass CI.
+```
+
+**Constraint**: The five existing sections (Prerequisites, Development Setup, Code Style & Guidelines, Verification Checks, Pull Request Process) must remain present and unmodified.
+
+---
+
+## Data Models
+
+No data models are introduced. The only data artefacts are:
+
+- A YAML scalar list (`branches`) in `ci.yml` — extended with one string element per trigger type.
+- A Markdown string (the new CI section) — inserted into `CONTRIBUTING.md`.
+
+---
+
+## Error Handling
+
+| Scenario | Mitigation |
+|---|---|
+| YAML parse error after edit | Validate `ci.yml` with `yamllint` or GitHub's workflow linter before merging |
+| Accidental removal of existing steps | Review the diff to confirm all original step blocks are present |
+| Markdown rendering issues | Preview `CONTRIBUTING.md` in a Markdown renderer before merging |
+| Branch name typo in trigger | Cross-check the exact branch name against `git branch -a` output |
+
+---
+
+## Testing Strategy
+
+Property-based testing does **not** apply to this feature. All acceptance criteria are structural/configuration checks on two files — they verify presence or absence of specific textual content in a YAML file and a Markdown file. The input space does not vary meaningfully; running 100 iterations would not surface additional defects. Appropriate test strategies are:
+
+### Smoke tests (manual or CI-based)
+
+These checks should be performed before merging the PR:
+
+1. **Branch trigger check** (Requirements 1.1–1.3)
+   - Parse `ci.yml` and assert `on.push.branches` equals `["main", "phase-1-scaffold"]`.
+   - Assert `on.pull_request.branches` equals `["main", "phase-1-scaffold"]`.
+
+2. **Inline comment check** (Requirements 2.1–2.2)
+   - Assert the `steps` block contains at least two YAML comment lines (`#`) that reference adding or extending steps.
+
+3. **Existing steps preservation** (Requirement 2.3)
+   - Assert all six original step names (`Rust Clippy`, `Rust Tests`, `Rust Format`, `TypeScript Check`, `ESLint Check`, `Vitest Check`) remain present.
+
+4. **CI section heading** (Requirement 3.1)
+   - Assert `CONTRIBUTING.md` contains the heading `CI / Continuous Integration`.
+
+5. **CI section content** (Requirements 3.2–3.4)
+   - Assert the section names all six checks.
+   - Assert the section mentions `pull request`, `main`, and `phase-1-scaffold`.
+   - Assert the section contains code blocks with the six local commands.
+
+6. **Existing CONTRIBUTING sections preserved** (Requirement 3.5)
+   - Assert all five original headings remain present in `CONTRIBUTING.md`.
+
+### Manual review checklist
+
+- [ ] `ci.yml` YAML is valid (no syntax errors).
+- [ ] Workflow is readable and comments are clear to a first-time contributor.
+- [ ] `CONTRIBUTING.md` renders correctly in GitHub's Markdown viewer.
+- [ ] New CI section sits between "Verification Checks" and "Pull Request Process".

.kiro/specs/ci-workflow-gaps/requirements.md

@@ -0,0 +1,57 @@
+# Requirements Document
+
+## Introduction
+
+The CNTRL Browser project has an existing `ci.yml` GitHub Actions workflow that runs lint and test checks on the `main` branch. Three gaps remain from the original issue (#19) that need to be addressed:
+
+1. The workflow does not trigger on the `phase-1-scaffold` branch.
+2. The workflow file contains no inline comments guiding contributors on how to extend it.
+3. `CONTRIBUTING.md` has no CI section explaining what CI does, when it runs, or how to replicate its checks locally.
+
+This feature closes those three gaps through targeted edits to `.github/workflows/ci.yml` and `CONTRIBUTING.md`.
+
+## Glossary
+
+- **CI_Workflow**: The GitHub Actions workflow defined in `.github/workflows/ci.yml`.
+- **CONTRIBUTING_Doc**: The contributor guide located at `CONTRIBUTING.md` in the repository root.
+- **Branch_Trigger**: The `on.push.branches` and `on.pull_request.branches` lists in `ci.yml` that determine which branches activate the workflow.
+- **Inline_Comment**: A YAML line comment (prefixed with `#`) placed inside `ci.yml` to explain the purpose of a section or how to extend it.
+- **CI_Section**: A dedicated Markdown section in `CONTRIBUTING_Doc` describing CI behaviour and local equivalents.
+
+## Requirements
+
+### Requirement 1: Branch Trigger Coverage
+
+**User Story:** As a contributor working on the `phase-1-scaffold` branch, I want CI to run on my pushes and pull requests, so that I receive the same automated feedback as contributors targeting `main`.
+
+#### Acceptance Criteria
+
+1. WHEN a push is made to the `phase-1-scaffold` branch, THE CI_Workflow SHALL execute the `test-and-lint` job.
+2. WHEN a pull request targets the `phase-1-scaffold` branch, THE CI_Workflow SHALL execute the `test-and-lint` job.
+3. THE CI_Workflow SHALL continue to execute the `test-and-lint` job on pushes to `main` and on pull requests targeting `main`.
+
+---
+
+### Requirement 2: Inline Contributor Guidance in ci.yml
+
+**User Story:** As a new contributor, I want inline comments in `ci.yml` explaining where and how to add new steps, so that I can extend the workflow without needing to consult external documentation.
+
+#### Acceptance Criteria
+
+1. THE CI_Workflow file SHALL contain at least one Inline_Comment explaining that additional steps (such as build or integration tests) can be appended after the existing steps.
+2. THE CI_Workflow file SHALL contain at least one Inline_Comment identifying the location within the `steps` list where a new step should be added.
+3. WHEN the CI_Workflow file is modified to add the comments, THE existing step names, commands, and job structure SHALL remain unchanged.
+
+---
+
+### Requirement 3: CI Documentation in CONTRIBUTING.md
+
+**User Story:** As a contributor, I want a CI section in `CONTRIBUTING.md` explaining what CI checks run, when they run, and how to reproduce them locally, so that I can understand and meet CI requirements before opening a pull request.
+
+#### Acceptance Criteria
+
+1. THE CONTRIBUTING_Doc SHALL contain a CI_Section with a heading titled "CI / Continuous Integration".
+2. THE CI_Section SHALL list each check that CI runs: Rust Clippy, Rust tests, Rust format check, TypeScript type check, ESLint check, and Vitest tests.
+3. THE CI_Section SHALL state that CI runs automatically on every pull request and on every push to `main` and `phase-1-scaffold`.
+4. THE CI_Section SHALL provide the exact local shell commands a contributor can run to reproduce each CI check.
+5. WHEN `CONTRIBUTING.md` is modified to add the CI_Section, THE existing sections (Prerequisites, Development Setup, Code Style, Verification Checks, Pull Request Process) SHALL remain unchanged.

.kiro/specs/ci-workflow-gaps/tasks.md

@@ -0,0 +1,56 @@
+# Implementation Plan: CI Workflow Gaps
+
+## Overview
+
+Three targeted file edits close the remaining gaps from issue #19:
+1. Extend the branch trigger list in `ci.yml`.
+2. Add inline contributor-guidance comments to `ci.yml`.
+3. Add a CI section to `CONTRIBUTING.md`.
+
+All tasks involve editing existing files only — no new files, dependencies, or infrastructure.
+
+## Tasks
+
+- [ ] 1. Add `phase-1-scaffold` to branch triggers in `ci.yml`
+  - In `.github/workflows/ci.yml`, locate the `on.push.branches` list and add `"phase-1-scaffold"` as a second element: `[ "main", "phase-1-scaffold" ]`.
+  - Apply the identical change to the `on.pull_request.branches` list.
+  - Verify the file parses as valid YAML after the edit.
+  - _Requirements: 1.1, 1.2, 1.3_
+
+- [ ] 2. Add inline comments to `ci.yml`
+  - Immediately above the first step (`uses: actions/checkout@v4`), insert a block of YAML comments that:
+    - Describe the purpose of the `steps` section at a glance.
+    - Tell contributors they can append new steps below the last existing step.
+    - Show the `- name: / run:` pattern as a brief example.
+  - After the last step (`Vitest Check`), insert a clearly marked comment block that says "Add new steps here" and shows a concrete example step (e.g., a Tauri debug build).
+  - Confirm all original step names, `run` commands, `working-directory` fields, and `uses` directives are byte-for-byte unchanged.
+  - _Requirements: 2.1, 2.2, 2.3_
+
+- [ ] 3. Checkpoint — validate ci.yml
+  - Ensure all tests pass, ask the user if questions arise.
+  - Confirm `ci.yml` is valid YAML (no parse errors).
+  - Confirm `on.push.branches` and `on.pull_request.branches` each contain exactly `["main", "phase-1-scaffold"]`.
+  - Confirm all six original step names are still present.
+
+- [ ] 4. Add CI section to `CONTRIBUTING.md`
+  - Open `CONTRIBUTING.md` and locate the position between the "🧪 Verification Checks" section and the "🔀 Pull Request Process" section.
+  - Insert a new section with the heading `## 🤖 CI / Continuous Integration` at that position.
+  - The section body must include:
+    - A sentence stating that CI runs on every PR and every push to `main` and `phase-1-scaffold`.
+    - A table (or equivalent list) naming all six checks: Rust Clippy, Rust tests, Rust format check, TypeScript type check, ESLint check, Vitest tests — each paired with its exact command.
+    - A fenced code block containing the six local shell commands a contributor can run to replicate CI.
+    - A note that exit code 0 on all commands means the branch will pass CI.
+  - Verify the five original sections (Prerequisites, Development Setup, Code Style & Guidelines, Verification Checks, Pull Request Process) are all still present and unmodified.
+  - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+- [ ] 5. Final checkpoint — Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+  - Confirm `CONTRIBUTING.md` renders correctly (no broken Markdown syntax).
+  - Confirm the new CI section appears between "Verification Checks" and "Pull Request Process".
+  - Confirm all five original headings remain present in `CONTRIBUTING.md`.
+
+## Notes
+
+- No property-based tests apply to this feature — all acceptance criteria are structural checks on YAML and Markdown files.
+- Each task references specific requirements from `requirements.md` for full traceability.
+- The two checkpoint tasks serve as explicit review gates before and after the documentation change.