diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 865f15b..d3eacbf 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -12,10 +12,13 @@ }, "ghcr.io/devcontainers/features/docker-in-docker": { "moby": false + }, + "ghcr.io/devcontainers/features/dotnet": { + "version": "latest" } }, - "postStartCommand": "copilot plugin marketplace add microsoft/github-copilot-for-azure && copilot plugin install azure@github-copilot-for-azure", + "postStartCommand": "copilot plugin install microsoft/github-copilot-for-azure:plugin", "postCreateCommand": "bash .devcontainer/post-create.sh" } diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh index 63e8cee..8481386 100755 --- a/.devcontainer/post-create.sh +++ b/.devcontainer/post-create.sh @@ -14,10 +14,12 @@ npx playwright install curl -sSL https://aspire.dev/install.sh | bash # Trust HTTPS dev certificates -dotnet dev-certs https --trust +# dotnet dev-certs https --trust # Install TypeScript language server for Copilot CLI LSP support npm install -g typescript-language-server # Install Python docs tooling pip install mkdocs mkdocs-material + +source /home/node/.bashrc diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index da4ab99..6631fb8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -26,7 +26,8 @@ is driven by automated tests generated from those specifications. - **Never implement features not in the specs** (specs/frd-*.md) - **Never modify tests** without human approval — tests are the contract - **Always check Gherkin scenarios** before implementing a feature -- **Always run tests** after making changes +- **Never skip tests** — no `test.skip()`, no `xit()`, no `@pending`, no commenting out. Tests are proof that specs are met. +- **Always run tests** after making changes — the FULL suite, not just "relevant" tests - If a spec seems wrong, flag it — do not silently deviate ## File Organization @@ -142,6 +143,21 @@ specs/ - Commit format: `[bugfix] {frd-id}: {description}` - Tracked as micro-increments in state.json + +## Test Discipline Gospel +Tests are the **proof** that specifications have been implemented correctly. They are not optional, not skippable, and not negotiable. + +Key rules: +- **Tests = proof of spec completion.** A feature without passing tests is not done. +- **Phase order is sacred.** Tests → Contracts → Implementation → Verify. Never skip or reorder. +- **All tests must pass before advancing.** No deployment, no commit to main while any test fails. +- **Regression is mandatory.** After every change, run ALL tests — not just new ones. + +### When the User Spots a Problem +At any point during the flow, if the user identifies something wrong: +1. **Pause** current work +2. **Offer** to generate a test that captures the problem + ## Shell-Specific Extensions diff --git a/.github/skills/bug-fix/SKILL.md b/.github/skills/bug-fix/SKILL.md index 78a6b9a..5b1d9cb 100644 --- a/.github/skills/bug-fix/SKILL.md +++ b/.github/skills/bug-fix/SKILL.md @@ -67,7 +67,24 @@ The test must: 3. Assert the EXPECTED behavior (not the buggy behavior). 4. Reference the FRD: `// Validates: frd-user-auth.md, AC-3` -### Step 3 — Verify the Test Fails +### Step 3 — Human Approval of the Test + +**MANDATORY GATE.** Present the test to the user for review before proceeding: + +1. Show the test code and explain what it verifies. +2. Explain which FRD acceptance criterion it maps to. +3. Ask the user to approve or reject the test. + +| User Response | Action | +|--------------|--------| +| **Approve** | Proceed to Step 4 (verify the test fails). | +| **Reject with feedback** | Revise the test based on feedback. Re-present. | +| **Defer** | Log the bug as a known issue in state.json. Resume previous work. | + +Do NOT proceed to fix the code until the user approves the test. The test +defines what "fixed" means — the user must agree on that definition. + +### Step 4 — Verify the Test Fails Run the test and confirm it fails with the expected error: @@ -82,7 +99,7 @@ npx playwright test --grep "duplicate email" If the test passes → the bug is not reproduced. Re-examine the reproduction steps and the test. Do NOT proceed until the test fails. -### Step 4 — Fix the Code +### Step 5 — Fix the Code Apply the minimal change to make the failing test pass: @@ -95,7 +112,7 @@ Apply the minimal change to make the failing test pass: The fix should be obvious from the diff. If the fix is complex, it may warrant a full increment rather than a bug-fix micro-increment. -### Step 5 — Run Full Regression +### Step 6 — Run Full Regression After the fix, run the complete test suite: @@ -113,7 +130,7 @@ npm run build Every test must pass — the bug-fix test AND all pre-existing tests. If any pre-existing test breaks, the fix is too broad or has side effects. Revise. -### Step 6 — Update State +### Step 7 — Update State Update `.spec2cloud/state.json` with the micro-increment: @@ -133,7 +150,7 @@ Update `.spec2cloud/state.json` with the micro-increment: } ``` -### Step 7 — Commit +### Step 8 — Commit Commit with the standard bug-fix format: @@ -160,10 +177,11 @@ Every bug fix creates a complete traceability chain: Bug Report → FRD (frd-{feature}.md, acceptance criterion N) → Failing Test (proves the bug exists) - → Fix (minimal code change) - → Passing Test (proves the bug is fixed) - → Commit (links all artifacts) - → State (tracked as micro-increment) + → Human Approval (user agrees the test captures the problem) + → Fix (minimal code change) + → Passing Test (proves the bug is fixed) + → Commit (links all artifacts) + → State (tracked as micro-increment) ``` This chain ensures: @@ -178,6 +196,7 @@ Append to `.spec2cloud/audit.log`: ``` [ISO-timestamp] step=bugfix action=test-created bug=bugfix-{nnn} frd={frd-id} test={test-file} result=failing +[ISO-timestamp] step=bugfix action=test-approved bug=bugfix-{nnn} approver=human result=approved [ISO-timestamp] step=bugfix action=fix-applied bug=bugfix-{nnn} files={fixed-files} result=done [ISO-timestamp] step=bugfix action=regression-passed bug=bugfix-{nnn} result=all-green [ISO-timestamp] step=bugfix action=committed bug=bugfix-{nnn} commit={sha} result=done diff --git a/AGENTS.md b/AGENTS.md index 80b3fb3..95f4fd8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -171,11 +171,13 @@ Resolve every technology, library, service. Research via MCP tools. Search skill main green + deployed ``` +> **⚠ MANDATORY:** Every step must execute in order. No step may be skipped, reordered, or compressed. Tests from Step 1 are the proof that specs are met — they are the contract. + #### Step 1: Test Scaffolding - **1a** `e2e-generation` — Playwright specs + POMs from flow walkthrough -- **1b** `gherkin-generation` — Feature files from FRDs (**human gate** after this) -- **1c** `test-generation` — Cucumber steps + Vitest from Gherkin -- **1d** Red baseline: new tests fail, existing tests still pass +- **1b** `gherkin-generation` — Feature files from FRDs (**human gate** after this — user approves scenarios) +- **1c** `test-generation` — Cucumber steps + Vitest from Gherkin (**human gate** — user approves test code) +- **1d** Red baseline: new tests fail, existing tests still pass. Zero `test.skip()` allowed. **Commit:** `[increment] {id}/tests — test scaffolding complete` #### Step 2: Contracts → `contract-generation` skill diff --git a/apphost.cs b/apphost.cs index 3da9055..48912b5 100644 --- a/apphost.cs +++ b/apphost.cs @@ -1,12 +1,13 @@ -#:sdk Aspire.AppHost.Sdk@13.1.0 -#:package Aspire.Hosting.JavaScript@13.1.0 -#:package Aspire.Hosting.Python@13.1.0 +#:sdk Aspire.AppHost.Sdk@13.2.0 +#:package Aspire.Hosting.JavaScript@13.2.0 +#:package Aspire.Hosting.Python@13.2.0 var builder = DistributedApplication.CreateBuilder(args); // API — Express.js / TypeScript backend var api = builder.AddJavaScriptApp("api", "./src/api") .WithEnvironment("JWT_SECRET", "aspire-local-dev-jwt-secret") + .WithHttpEndpoint(port: 5001, env: "PORT") .WithHttpHealthCheck("/health"); // Web — Next.js frontend diff --git a/aspire.config.json b/aspire.config.json new file mode 100644 index 0000000..a777aa5 --- /dev/null +++ b/aspire.config.json @@ -0,0 +1,5 @@ +{ + "appHost": { + "path": "apphost.cs" + } +} diff --git a/docs/quickstart.md b/docs/quickstart.md index 82b9623..171d167 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,51 +1,143 @@ # Quick Start -Get spec2cloud running in your project in under 5 minutes. +Get the spec2cloud TypeScript shell running in under 5 minutes. ## Prerequisites -- GitHub Copilot (Chat enabled) or Claude Code -- VS Code with Copilot extension -- Azure CLI + Azure Developer CLI (azd) -- Node.js 20+ or .NET 8+ +### Option A: Use Codespaces / DevContainer (Recommended) -## Option 1: npx (Recommended) +All spec2cloud shells include a fully configured **DevContainer** / **GitHub Codespaces** setup. Everything is pre- the only thing you need locally is:installed + +- **Docker Desktop** (or any Docker-compatible [docker.com](https://www.docker.com/products/docker-desktop/)runtime) +- **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + +Then simply open the repo in VS Code and click "Reopen in Container", or launch a GitHub Codespace from the repo page. All prerequisites below are handled automatically. + +### Option B: Local Setup + +If you prefer running locally without containers, install the following: + +#### Core Tools (all shells need these) + +| Tool | Purpose | Install | +|------|---------|---------| +| **GitHub Copilot** | AI orchestrator | [github.com/features/copilot](https://github.com/features/copilot) | +| **VS Code** | Editor with Copilot extension | [code.visualstudio.com](https://code.visualstudio.com/) | +| **Azure CLI** | Azure resource management | [aka.ms/installcli](https://aka.ms/installcli) | +| **Azure Developer CLI (azd)** | Deploy to Azure | [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) | +| **.NET SDK (latest)** | Required for Aspire orchestration | [dot.net](https://dot.net/download) | +| **.NET Aspire** | Local service orchestration | `curl -sSL https://aspire.dev/install.sh \| bash` | +| **Docker** | Container builds & deployment | [docker.com](https://www.docker.com/products/docker-desktop/) | +| **Git** | Source control | [git-scm.com](https://git-scm.com/) | + +#### Language-Specific (TypeScript) + +- **Node.js 20+** and ** [nodejs.org](https://nodejs.org/)npm** + +#### Optional (Recommended) + +- ** `npx playwright install` (for E2E tests)Playwright** +- ** `pip install mkdocs mkdocs-material` (for documentation site)MkDocs** + +### Install Scripts + +
+macOS (Homebrew) ```bash -npx spec2cloud init +# Core tools +brew install azure-cli +brew install azd +brew install --cask docker +brew install dotnet +curl -sSL https://aspire.dev/install.sh | bash + +# Language-specific +brew install node@20 + +# Optional +npx playwright install-deps && npx playwright install +pip install mkdocs mkdocs-material ``` -## Option 2: One-Line Install +
+ +
+Linux (Ubuntu/Debian) ```bash -curl -fsSL https://raw.githubusercontent.com/EmeaAppGbb/spec2cloud/vNext/scripts/quick-install.sh | bash +# Core tools +curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash +curl -fsSL https://aka.ms/install-azd.sh | bash +wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh && chmod +x dotnet-install.sh && ./dotnet-install.sh +curl -sSL https://aspire.dev/install.sh | bash + +# Language-specific +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs + +# Optional +npx playwright install-deps && npx playwright install +pip install mkdocs mkdocs-material ``` -## Option 3: Shell Template (Recommended for New Projects) +
-Use a pre-configured shell: +
+Windows (winget / PowerShell) -- **Next.js + TypeScript**: `shell-typescript` -- **.NET**: `shell-dotnet` -- **Agentic .NET**: `agentic-shell-dotnet` -- **Agentic Python**: `agentic-shell-python` +```powershell +# Core tools +winget install Microsoft.AzureCLI +winget install Microsoft.Azd +winget install Microsoft.DotNet.SDK.Preview +winget install Docker.DockerDesktop +dotnet workload install aspire -## Option 4: Add to Existing Project +# Language-specific +winget install OpenJS.NodeJS.LTS + +# Optional +npx playwright install +pip install mkdocs mkdocs-material +``` + +
+ +### Verify Installation ```bash -npx spec2cloud init --minimal +# Core +az --version && azd version && dotnet --version && aspire --version && docker --version + +# Language +node --version # v20+ +npm --version ``` -## Your First Workflow +--- + +## Getting Started + +### 1. Clone and Run + +```bash +git clone https://github.com/EmeaAppGbb/spec2cloud-shell-nextjs-typescript.git +cd spec2cloud-shell-nextjs-typescript +dotnet run --project apphost.cs # Aspire starts all services +``` + +### 2. Open in VS Code with Copilot + +The orchestrator (AGENTS.md) activates automatically when you start a Copilot conversation. + +### 3. Start Building -1. Open your project in VS Code with GitHub Copilot -2. Start a conversation with Copilot — the orchestrator (AGENTS.md) activates automatically -3. Describe your app idea or ask Copilot to analyze your existing codebase -4. At each human gate, review and approve -5. Watch as tests, contracts, implementation, and deployment happen automatically + deploy +- **Brownfield:** Ask Copilot to analyze the existing it extracts specs, then you choose pathscodebase ## What Happens Next -**Greenfield:** Phase 1 Discovery (spec → UI → plan → tech stack) → Phase 2 Delivery (tests → contracts → code → deploy) × N increments + deploy) N increments -**Brownfield:** Phase B1 Extract → Phase B2 Spec-Enable → Testability Gate (can you test it?) → Track A (green baseline tests) or Track B (behavioral docs) → Choose paths → Assess → Plan → Phase 2 Delivery + Phase 2 Delivery