feat(cli): add BeforeCode CLI MVP

.github/workflows/cli-test.yml

@@ -0,0 +1,28 @@
+name: CLI test
+
+on:
+  pull_request:
+    paths:
+      - "bin/**"
+      - "src/**"
+      - "tests/**"
+      - "package.json"
+      - ".github/workflows/cli-test.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  cli:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "20"
+      - run: npm test
+      - run: node ./bin/beforecode.js help
+      - run: node ./bin/beforecode.js list
+      - run: node ./bin/beforecode.js init --type saas --docs tmp-docs
+      - run: node ./bin/beforecode.js check --type saas --docs tmp-docs

bin/beforecode.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(`BeforeCode error: ${error.message}`);
+  process.exit(1);
+});

docs/cli-prd.md

@@ -0,0 +1,60 @@
+# BeforeCode CLI PRD
+
+## Overview
+
+BeforeCode CLI turns the Markdown toolkit into a project-integrated generator.
+
+Users can run one command inside any software project and generate the right documentation set for the project type.
+
+## Goal
+
+Make BeforeCode usable without manual copying from GitHub.
+
+## Target Users
+
+- Developers starting a new project
+- Existing project maintainers adding documentation
+- AI coding users preparing source-of-truth docs
+- Students creating structured project documentation
+
+## MVP Commands
+
+| Command | Purpose |
+|---|---|
+| `beforecode init --type saas` | Generate a documentation set for a project type |
+| `beforecode add prd` | Add one template to the project |
+| `beforecode check --type saas` | Check required docs for a project type |
+| `beforecode score --type saas` | Show readiness score |
+| `beforecode handoff` | Generate AI handoff files |
+| `beforecode list` | Show supported project types and templates |
+
+## Supported Project Types
+
+- small
+- portfolio
+- saas
+- crm
+- ecommerce
+- mobile
+- ai-agent
+- opensource
+
+## Success Criteria
+
+- CLI can run with Node 18 or later
+- CLI can generate docs into a local `docs/` folder
+- CLI does not overwrite files unless `--force` is used
+- CLI supports `--dry-run`
+- CLI creates `.beforecoderc.json`
+- CLI can check missing docs
+- CLI can generate a basic AI handoff package
+- CLI can run tests with Node built-in test runner
+- CLI works with `npx beforecode` after package publishing
+
+## Non-goals for MVP
+
+- No web UI
+- No remote API
+- No AI generation inside CLI
+- No npm publishing automation yet
+- No TypeScript build step yet

docs/cli-roadmap.md

@@ -0,0 +1,29 @@
+# CLI Roadmap
+
+## v0.1
+
+- Generate docs by project type
+- Add one template
+- Check missing docs
+- Show readiness score
+- Generate basic AI handoff files
+- Add Node test workflow
+
+## v0.2
+
+- Interactive prompts
+- Template variable injection
+- More project-specific template packs
+- Better config editing
+
+## v0.3
+
+- Section-level readiness checks
+- Traceability report
+- AI handoff profiles for common coding tools
+
+## v1.0
+
+- Stable npm package
+- Versioned template packs
+- Strong docs site integration

docs/cli-trd.md

@@ -0,0 +1,62 @@
+# BeforeCode CLI TRD
+
+## Overview
+
+The CLI is a zero-dependency Node.js tool that copies BeforeCode templates into a project and checks documentation readiness.
+
+## Runtime
+
+- Node.js 18+
+- ECMAScript modules
+- Built-in filesystem APIs
+- Node built-in test runner
+
+## Entry Point
+
+```text
+bin/beforecode.js
+```
+
+## Source Layout
+
+```text
+src/cli.js
+src/commands/
+src/core/
+src/data/
+src/args.js
+src/fs-utils.js
+src/paths.js
+```
+
+## Commands
+
+- `init` generates a docs set
+- `add` copies one template
+- `check` checks required docs
+- `score` shows readiness score
+- `handoff` creates AI handoff files
+- `list` shows supported options
+
+## Safety Rules
+
+- Do not overwrite files by default
+- Use `--force` to replace existing files
+- Use `--dry-run` to preview changes
+- Generate `.beforecoderc.json` for future checks
+
+## Test Strategy
+
+Use Node's built-in test runner.
+
+```bash
+npm test
+```
+
+## Future Scope
+
+- Interactive prompts
+- Template variables beyond basic fields
+- Section-level scoring
+- Traceability scoring
+- npm publishing workflow

docs/cli-usage.md

@@ -0,0 +1,91 @@
+# CLI Usage
+
+BeforeCode CLI generates project documentation inside an existing or new software project.
+
+## Local usage from the repository
+
+```bash
+npm install
+node ./bin/beforecode.js help
+node ./bin/beforecode.js list
+```
+
+## Generate a docs set
+
+```bash
+beforecode init --type saas
+```
+
+Use a custom docs folder:
+
+```bash
+beforecode init --type ai-agent --docs project-docs
+```
+
+Preview without writing files:
+
+```bash
+beforecode init --type saas --dry-run
+```
+
+Replace existing generated files intentionally:
+
+```bash
+beforecode init --type saas --force
+```
+
+## Add one template
+
+```bash
+beforecode add prd
+beforecode add api-documentation
+beforecode add qa-test-plan
+```
+
+## Check readiness
+
+```bash
+beforecode check --type saas
+```
+
+If `.beforecoderc.json` exists, the CLI can read the project type and docs path automatically:
+
+```bash
+beforecode check
+```
+
+## Score readiness
+
+```bash
+beforecode score --type saas
+```
+
+The MVP score is based on whether required files exist. Later versions can inspect sections and traceability.
+
+## Generate AI handoff files
+
+```bash
+beforecode handoff
+```
+
+This creates:
+
+```text
+AGENTS.md
+docs/ai-handoff.md
+```
+
+## Supported project types
+
+- small
+- portfolio
+- saas
+- crm
+- ecommerce
+- mobile
+- ai-agent
+- opensource
+
+## Safe behavior
+
+The CLI does not overwrite files by default. Use `--force` only when replacing existing generated files is intentional.

package.json

@@ -0,0 +1,38 @@
+{
+  "name": "beforecode",
+  "version": "0.1.0",
+  "description": "Spec-first project planning toolkit for humans and AI coding agents.",
+  "type": "module",
+  "bin": {
+    "beforecode": "./bin/beforecode.js"
+  },
+  "scripts": {
+    "cli": "node ./bin/beforecode.js",
+    "test": "node --test",
+    "test:cli": "node ./bin/beforecode.js help && node ./bin/beforecode.js list"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "checklists",
+    "prompts",
+    "docs/cli-usage.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "prd",
+    "documentation",
+    "project-planning",
+    "software-architecture",
+    "ai-coding",
+    "qa",
+    "cli"
+  ],
+  "author": "Mohit Kumar",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

src/args.js

@@ -0,0 +1,30 @@
+export function parseArgs(args) {
+  const result = { _: [] };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (!arg.startsWith("--")) {
+      result._.push(arg);
+      continue;
+    }
+
+    const raw = arg.slice(2);
+    const equalsIndex = raw.indexOf("=");
+
+    if (equalsIndex !== -1) {
+      result[raw.slice(0, equalsIndex)] = raw.slice(equalsIndex + 1);
+      continue;
+    }
+
+    const next = args[i + 1];
+    if (!next || next.startsWith("--")) {
+      result[raw] = true;
+    } else {
+      result[raw] = next;
+      i += 1;
+    }
+  }
+
+  return result;
+}