aw-spec-cli 0.1.3 → 0.1.4

package/README.md

@@ -0,0 +1,291 @@
+# aw-spec-cli
+
+**AppWeaver Spec-Driven Development CLI** — Scaffold projects with vertical slices, DDD, CQRS, and AI agent skills.
+
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+---
+
+## Overview
+
+`aw-spec-cli` initializes new projects with the **AppWeaver Spec-Driven Development** structure:
+
+- **Vertical Slice Architecture** — Feature-oriented, decoupled modules
+- **Domain-Driven Design (DDD)** — Rich domain models, bounded contexts
+- **CQRS** — Command/Query separation for scalable reads/writes
+- **AI Agent Skills** — Ready-to-use skills for Claude Code, Antigravity, and KiloCode
+
+The CLI copies a battle-tested project skeleton (from the [AppWeaver.Spec](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) reference implementation) into your target directory.
+
+---
+
+## Installation
+
+### Global Install (via Azure Artifacts / npm)
+```bash
+# From Azure Artifacts (after publishing)
+npm install -g aw-spec-cli
+
+# Or use via npx
+npx aw-spec-cli@latest init
+```
+
+### Local Development Install
+```bash
+# From the cloned repository
+git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/appweaver
+cd platform/Appweaver.Spec.Cli
+npm install
+npm run build
+# Then run via node
+dist/index.js init
+```
+
+Requires **Node.js ≥ 18**.
+
+---
+
+## Quick Start
+
+```bash
+# Create a new project in the current directory
+aw-spec init
+
+# Or specify a target directory
+aw-spec init my-project
+
+# Non-interactive (uses Claude skills by default)
+aw-spec init -y
+
+# Choose agent explicitly
+aw-spec init --agent antigravity
+aw-spec init --agent kilocode
+
+# Preview what would be copied (no changes)
+aw-spec init --dry-run
+```
+
+After initialization:
+
+```bash
+# Verify the installation
+aw-spec doctor
+
+# Start spec-driven development
+aw-spec specify "Your feature description"
+```
+
+---
+
+## Commands
+
+### `aw-spec init [directory]`
+
+Initialize a new AppWeaver Spec project.
+
+| Option | Description |
+|--------|-------------|
+| `directory` | Target directory (default: current directory) |
+| `-a, --agent <agent>` | Agent skills to include: `claude`, `antigravity`, `kilocode` (default: prompt) |
+| `-y, --yes` | Skip prompts, use defaults (Claude) |
+| `--dry-run` | Show what would be copied without making changes |
+
+**Copied structure:**
+```
+target-dir/
+├── .aw-spec/              # Core spec configuration
+│   ├── extensions.yml     # Extension registry
+│   ├── feature.json       # Feature tracking
+│   ├── workflows/         # Workflow definitions
+│   ├── templates/         # Spec/plan/task templates
+│   └── scripts/           # Bash/PowerShell helpers
+├── docs/                  # Documentation scaffold
+│   ├── architecture/
+│   ├── domain/
+│   ├── governance/
+│   ├── security/
+│   ├── domainspecs/
+│   ├── glossary/
+│   ├── VerticalSlice/     # Vertical slice packaging
+│   └── ...
+└── .claude/skills/        # Or .agents/skills/, .kilocode/
+    ├── aw-spec-specify/
+    ├── aw-spec-plan/
+    ├── aw-spec-implement/
+    └── ... (13 skills total)
+```
+
+### `aw-spec doctor`
+
+Verify the project structure is complete and valid.
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Show detailed output (lists all skills, missing items) |
+
+**Checks performed:**
+- Required folders: `.aw-spec/`, `docs/`
+- Required config files: `extensions.yml`, `feature.json`, `init-options.json`, `integration.json`, `workflow-registry.json`
+- Agent skills folder (`.claude/skills` or `.agents/skills`) with all 13 skills
+- Documentation structure (`architecture/`, `domain/`, `governance/`, `security/`, `domainspecs/`, `glossary/`, `VerticalSlice/`)
+- Vertical Slice packaging scripts (`pack-foundation.sh`, `unpack-foundation.sh`, `PACKAGING.md`)
+- `.aw-spec` subdirectories (`extensions/`, `templates/`, `scripts/`, `workflows/`, `integrations/`, `memory/`)
+
+---
+
+## Agent Support
+
+| Agent | Folder | Skills |
+|-------|--------|--------|
+| **Claude Code** | `.claude/skills/` | 13 skills (specify, plan, implement, tasks, clarify, analyze, checklist, foundation, constitution, select-domain, agent-context-update, addcomponent, taskstoissues) |
+| **Antigravity** | `.agents/skills/` | Same 13 skills, Antigravity-compatible format |
+| **KiloCode** | `.kilocode/` | Workflow definitions (`.md` files) |
+
+Choose based on your AI assistant. Skills provide guided workflows for spec-driven development:
+- `aw-spec-specify` — Write feature specifications
+- `aw-spec-plan` — Create implementation plans
+- `aw-spec-implement` — Generate code from plans
+- `aw-spec-tasks` — Break down into executable tasks
+- ... and more
+
+---
+
+## Project Structure (After Init)
+
+```
+my-project/
+├── .aw-spec/
+│   ├── extensions.yml
+│   ├── feature.json
+│   ├── init-options.json
+│   ├── integration.json
+│   ├── workflows/
+│   │   └── workflow-registry.json
+│   ├── extensions/
+│   │   └── agent-context/
+│   │       ├── scripts/
+│   │       └── commands/
+│   ├── templates/
+│   │   ├── spec-template.md
+│   │   ├── plan-template.md
+│   │   └── tasks-template.md
+│   ├── scripts/
+│   │   └── bash/
+│   │       └── common.sh
+│   ├── integrations/
+│   └── memory/
+├── docs/
+│   ├── architecture/
+│   ├── domain/
+│   ├── governance/
+│   ├── security/
+│   ├── domainspecs/
+│   ├── glossary/
+│   ├── interop/
+│   ├── ModularMonolith/
+│   ├── VerticalSlice/
+│   │   ├── VerticalSlice.pack.txt
+│   │   ├── PACKAGING.md
+│   │   ├── pack-foundation.sh
+│   │   └── unpack-foundation.sh
+│   ├── command.txt
+│   ├── components/
+│   ├── pharma-constitution.my-ref.md
+│   ├── requirement-spec.txt
+│   ├── technology-constitution.md
+│   └── README.md
+└── .claude/skills/          # Or .agents/skills/, .kilocode/
+    ├── aw-spec-addcomponent/
+    ├── aw-spec-agent-context-update/
+    ├── aw-spec-analyze/
+    ├── aw-spec-checklist/
+    ├── aw-spec-clarify/
+    ├── aw-spec-constitution/
+    ├── aw-spec-foundation/
+    ├── aw-spec-implement/
+    ├── aw-spec-plan/
+    ├── aw-spec-select-domain/
+    ├── aw-spec-specify/
+    ├── aw-spec-tasks/
+    └── aw-spec-taskstoissues/
+```
+
+---
+
+## Development
+
+### Prerequisites
+- Node.js ≥ 18
+- The [AppWeaver.Spec](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) repository cloned as a sibling directory (for bundling assets)
+
+### Scripts
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm run bundle:content` | Copy assets from `../AppWeaver.Spec` → `assets/` |
+| `npm run prepack` | Build + bundle (runs automatically on `npm publish`) |
+| `npm test` | Run unit tests (Vitest) |
+| `npm run test:watch` | Watch mode |
+| `npm run lint` | ESLint on `src/` |
+| `npm run doctor` | Run CLI doctor on current directory |
+
+### Setup (Local Development)
+```bash
+# Clone the main repository
+git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/appweaver
+cd platform/Appweaver.Spec.Cli
+npm install
+
+# Ensure AppWeaver.Spec is available for bundling
+# Either clone it as a sibling directory:
+#   git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec ../AppWeaver.Spec
+# Or the bundling script will fall back to published assets in dist/assets/
+```
+
+### Setup (After Publishing to Azure Artifacts)
+Once published to Azure Artifacts, consumers can install via:
+```bash
+# From Azure Artifacts / npm registry (after publishing)
+npm install -g aw-spec-cli
+
+# Or use directly via npx
+npx aw-spec-cli@latest init
+```
+
+---
+
+## How It Works
+
+1. **Asset Bundling** (`scripts/bundle-content.ts`) — On publish, copies the AppWeaver.Spec reference implementation into `assets/` (excludes build artifacts, secrets, VCS folders).
+
+2. **Asset Resolution** (`src/utils/paths.ts`) — At runtime, finds assets in priority order:
+   - `dist/assets/` (published package)
+   - `../AppWeaver.Spec` (local development)
+   - `packageRoot/assets` (fallback)
+
+3. **Project Initialization** (`src/commands/init.ts`) — Copies `.aw-spec/`, `docs/`, and the selected agent's skills to the target directory with overwrite protection.
+
+4. **Validation** (`src/commands/doctor.ts`) — Comprehensive structure verification with colored output.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make changes with tests
+4. Run `npm run build && npm test && npm run lint`
+5. Submit a PR
+
+---
+
+## License
+
+MIT © [AppWeaver Team](https://dev.azure.com/bytestrone-labs/AppWeaver)
+
+---
+
+## Related
+
+- [AppWeaver.Spec](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) — Reference implementation & source of bundled assets
+- [Spec-Driven Development](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec?path=/docs/spec-driven-development.md) — Methodology overview

package/assets/docs/UI.Visualization/PACKAGING.md

@@ -0,0 +1,191 @@
+# UI.Visualization — Foundation Packaging Rules
+
+> **Why this exists.** This packaging model replaces reconstruction with a
+> **byte-for-byte bundle of the real, verified Next.js template**.
+>
+> You author the UI foundation **once** (a Next.js app that actually builds and runs),
+> pack it into a single text file, and the scaffolder **unpacks + renames** it.
+> No regeneration, no drift — the same guarantee that `VerticalSlice` provides for the backend.
+
+---
+
+## The single artifact
+
+```
+docs/UI.Visualization/
+├── UI.Visualization.pack.txt      ← THE BUNDLE: every source file in one text file
+├── PACKAGING.md                             ← this file
+├── pack-foundation.ps1                      ← produces the pack from the template folder (Windows)
+├── pack-foundation.sh                       ← produces the pack from the template folder (macOS/Linux)
+├── pack-reference-foundation.ps1            ← produces a reference/sample pack
+├── pack-reference-foundation.sh
+├── unpack-foundation.ps1                    ← extracts + renames into a target app (used by skill)
+├── unpack-foundation.sh
+├── unpack-reference-foundation.ps1
+└── unpack-reference-foundation.sh
+```
+
+The source template lives at:
+
+```
+templates/UI.Visualization/
+```
+
+---
+
+## The sentinel convention
+
+The template is authored under the sentinel app name:
+
+```
+UI.Visualization
+```
+
+The scaffolder rewrites the sentinel in **four case forms** (ordinal, case-sensitive, longest-first),
+applied to **file contents and to file/folder paths**:
+
+| Form         | Sentinel                       | Example target (`PharmaViz`)    | Where it appears                          |
+|--------------|--------------------------------|---------------------------------|-------------------------------------------|
+| dotted       | `UI.Visualization`   | `PharmaViz`                     | `package.json` name (dotted form), README |
+| underscored  | `UI_Visualization`   | `PharmaViz`                     | any underscored identifiers               |
+| lower-hyphen | `ui-visualization`   | `pharmaviz`                     | npm package name, Docker image tag        |
+| lower-dot    | `ui.visualization`   | `pharmaviz`                     | any lowercased identifiers                |
+
+### What does NOT get renamed
+
+- `AppWeaver.*` framework package references in `package.json` (there are none in this UI template — all deps are third-party).
+- The generic sample pages (`/heatmap`, `/bubble`, etc.) — these are example content the caller replaces with their own pages.
+
+---
+
+## How to author the template (do this once per change)
+
+1. Work in `templates/UI.Visualization/`.
+
+2. Use `UI.Visualization` as the sentinel wherever the app name belongs:
+   - `package.json` → `"name": "ui-visualization"` (lower-hyphen form)
+   - `README.md` → title
+   - `src/app/layout.tsx` → `<title>UI.Visualization</title>` and metadata
+   - Any other branding strings
+
+3. Verify the template builds and runs clean:
+   ```bash
+   cd templates/UI.Visualization
+   npm install
+   npm run build    # must exit 0, no TypeScript errors
+   npm run dev      # browse to http://localhost:3000, all 10 chart pages render
+   ```
+
+4. Fix every error here, in the real template, where the compiler tells you exactly what's wrong.
+
+---
+
+## How to build the bundle
+
+From `docs/UI.Visualization/`:
+
+**macOS / Linux:**
+```bash
+./pack-foundation.sh \
+    --source-dir ../../../../templates/UI.Visualization \
+    --out-file   ./UI.Visualization.pack.txt
+```
+
+**Windows (PowerShell):**
+```powershell
+./pack-foundation.ps1 `
+    -SourceDir ../../../../templates/UI.Visualization `
+    -OutFile   ./UI.Visualization.pack.txt
+```
+
+The packer:
+- Walks the template, **excluding** build/IDE and JS output artifacts:
+  - dirs: `node_modules .next .turbo dist out coverage .cache bin obj .vs .git logs`
+  - files: `*.tsbuildinfo  next-env.d.ts  *.log  .env.*  *.pem  *.key  secrets.json`
+- **Fails closed on detected secrets** — scans file contents for credential markers and refuses to pack unless `--allow-secrets` / `-AllowSecrets` is passed.
+- Stores text files **verbatim** and binary files (e.g. `.xlsx`) **base64-encoded**.
+- Writes a header containing `foundation`, `sentinel`, file count, format version, and the replacement contract.
+- **Warns** if the sentinel token appears in zero files.
+
+Re-run it whenever the template changes; commit the regenerated `UI.Visualization.pack.txt`.
+
+---
+
+## How to build the reference pack
+
+The reference pack is used by `/aw-spec-addcomponent` and `/aw-spec-implement` unpack workflows
+when a feature reference example exists under `templates/features/`.
+
+```bash
+./pack-reference-foundation.sh \
+    --source-dir ../../../../templates/features/UIVisualization.SimpleSample \
+    --out-file   ./UI.Visualization.Reference.pack.txt
+```
+
+*(Create the `SimpleSample` folder when you have a working feature example to bundle.)*
+
+---
+
+## Pack file format (`aw-spec-pack/v1`)
+
+Same format as `VerticalSlice.pack.txt`:
+
+```
+# AW-SPEC FOUNDATION PACK
+# foundation: UI.Visualization
+# sentinel: UI.Visualization
+# generated: 2026-06-26T10:00:00.0000000Z
+# files: 32
+# format: aw-spec-pack/v1
+# --- replacement contract ... ---
+# ============================================================
+
+<<<FILE path="package.json">>>
+...verbatim file content...
+<<<ENDFILE>>>
+<<<FILE path="src/app/layout.tsx">>>
+...
+<<<ENDFILE>>>
+<<<FILE path="public/sample-data.xlsx" encoding="base64">>>
+AAABAAE...
+<<<ENDFILE>>>
+```
+
+---
+
+## How scaffolding consumes the bundle
+
+`/aw-spec-foundation UI.Visualization <AppName> [OutputDir]`
+runs `unpack-foundation.sh` (or `.ps1`), which reads the sentinel from the pack header,
+derives the four target case forms, and writes the renamed files to the output directory.
+
+```bash
+# macOS / Linux
+./unpack-foundation.sh \
+    --pack-file   ./UI.Visualization.pack.txt \
+    --target-app-name PharmaViz \
+    --out-dir     ~/projects/
+
+# Windows
+./unpack-foundation.ps1 `
+    -PackFile        ./UI.Visualization.pack.txt `
+    -TargetAppName   PharmaViz `
+    -OutDir          ~/projects/
+```
+
+After unpacking:
+```bash
+cd ~/projects/PharmaViz     # or wherever OutDir puts it
+npm install
+npm run dev                  # → http://localhost:3000
+```
+
+---
+
+## Maintenance checklist
+
+- [ ] Template builds clean (`npm run build`, no TypeScript errors).
+- [ ] Sentinel `UI.Visualization` appears in `package.json`, `README.md`, `layout.tsx`.
+- [ ] No `node_modules/`, `.next/`, or generated files committed into the pack.
+- [ ] `pack-foundation.sh` reported a non-zero sentinel hit count.
+- [ ] `UI.Visualization.pack.txt` regenerated and committed after any change.