raptor-aios 0.1.0

package/scripts/prepare-npm.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * prepare-npm.mjs — Assemble a single, self-contained publishable npm package
+ * (`raptor-aios`) from the pnpm monorepo into `build/npm/`.
+ *
+ * The CLI uses oclif file-based command discovery (dist/commands/*.js) and the
+ * core reads its templates relative to its own dist, so we DON'T flatten into a
+ * single bundle. Instead we VENDOR @raptor/core into `dist/_core/` and rewrite
+ * every `@raptor/core` import specifier to a relative path. Templates,
+ * extensions and shell scripts are copied to the package root because
+ * `init` resolves them by walking up to a dir containing `scripts/bash`.
+ */
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const CLI = join(ROOT, "packages", "cli");
+const CORE = join(ROOT, "packages", "core");
+const OUT = join(ROOT, "build", "npm");
+
+const VERSION = "0.1.0";
+
+function log(msg) {
+  process.stdout.write(`  ${msg}\n`);
+}
+
+// --- 0. sanity: builds must exist ---
+for (const [name, d] of [
+  ["cli/dist", join(CLI, "dist")],
+  ["core/dist", join(CORE, "dist")],
+]) {
+  if (!existsSync(d)) {
+    console.error(`✗ Missing ${name} — run \`pnpm build\` first.`);
+    process.exit(1);
+  }
+}
+
+// --- 1. clean staging ---
+rmSync(OUT, { recursive: true, force: true });
+mkdirSync(OUT, { recursive: true });
+log("clean staging build/npm/");
+
+// --- 2. copy CLI bin + dist ---
+cpSync(join(CLI, "bin"), join(OUT, "bin"), { recursive: true });
+cpSync(join(CLI, "dist"), join(OUT, "dist"), { recursive: true });
+log("copied cli bin + dist");
+
+// --- 3. vendor @raptor/core into dist/_core ---
+const VENDOR = join(OUT, "dist", "_core");
+mkdirSync(VENDOR, { recursive: true });
+cpSync(join(CORE, "dist"), join(VENDOR, "dist"), { recursive: true });
+cpSync(join(CORE, "templates"), join(VENDOR, "templates"), { recursive: true });
+writeFileSync(
+  join(VENDOR, "package.json"),
+  JSON.stringify(
+    { name: "@raptor/core", version: VERSION, type: "module", main: "dist/index.js" },
+    null,
+    2,
+  ) + "\n",
+);
+log("vendored @raptor/core → dist/_core");
+
+// --- 4. rewrite @raptor/core specifiers in cli dist to relative paths ---
+const coreEntry = join(OUT, "dist", "_core", "dist", "index.js");
+let rewritten = 0;
+function walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      if (p === VENDOR) continue; // don't touch vendored core
+      walk(p);
+    } else if (name.endsWith(".js")) {
+      const src = readFileSync(p, "utf8");
+      if (!src.includes("@raptor/core")) continue;
+      let rel = relative(dirname(p), coreEntry).split("\\").join("/");
+      if (!rel.startsWith(".")) rel = "./" + rel;
+      const next = src
+        .split('"@raptor/core"')
+        .join(`"${rel}"`)
+        .split("'@raptor/core'")
+        .join(`'${rel}'`);
+      writeFileSync(p, next);
+      rewritten++;
+    }
+  }
+}
+walk(join(OUT, "dist"));
+log(`rewrote @raptor/core → relative in ${rewritten} file(s)`);
+
+// --- 5. copy root-level resources init resolves (templates/extensions/scripts) ---
+for (const d of ["templates", "extensions", "scripts"]) {
+  cpSync(join(ROOT, d), join(OUT, d), { recursive: true });
+}
+log("copied templates/, extensions/, scripts/");
+
+// --- 6. docs ---
+for (const f of ["README.md", "LICENSE", "CHANGELOG.md"]) {
+  if (existsSync(join(ROOT, f))) cpSync(join(ROOT, f), join(OUT, f));
+}
+log("copied README/LICENSE/CHANGELOG");
+
+// --- 7. publishable package.json ---
+const pkg = {
+  name: "raptor-aios",
+  version: VERSION,
+  description:
+    "Raptor — Spec-Driven Development (SDD) CLI for modern mobile apps. Constitutional gates, audit trail, real verification (a11y/perf/stores/OS matrix), and AI-agent slash commands.",
+  type: "module",
+  bin: { raptor: "./bin/raptor.js" },
+  files: ["bin", "dist", "templates", "extensions", "scripts", "README.md", "LICENSE", "CHANGELOG.md"],
+  engines: { node: ">=20" },
+  oclif: {
+    bin: "raptor",
+    dirname: "raptor",
+    commands: "./dist/commands",
+    topicSeparator: " ",
+  },
+  keywords: [
+    "sdd",
+    "spec-driven-development",
+    "cli",
+    "mobile",
+    "react-native",
+    "spec-kit",
+    "ai",
+    "claude",
+    "governance",
+    "audit",
+  ],
+  author: "lucaspedronet",
+  license: "MIT",
+  repository: { type: "git", url: "git+https://github.com/lucaspedronet/raptor-aios.git" },
+  homepage: "https://github.com/lucaspedronet/raptor-aios#readme",
+  bugs: { url: "https://github.com/lucaspedronet/raptor-aios/issues" },
+  publishConfig: { access: "public" },
+  dependencies: {
+    "@oclif/core": "^4",
+    ajv: "^8.18.0",
+    yaml: "^2.5.0",
+  },
+};
+writeFileSync(join(OUT, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+log("wrote publishable package.json (raptor-aios)");
+
+log(`\n✓ Staged raptor-aios@${VERSION} at build/npm/`);

package/templates/checklist-template.md

@@ -0,0 +1,103 @@
+# Quality Checklist — {{featureName}}
+
+> Generated by `/rpt.checklist`. Source: spec.md + plan.md (+ tasks.md if present).
+> Spec Kit ref: E09 — quality gate before `/rpt.implement` proceeds.
+
+---
+
+## Metadata
+
+- **Feature**: `{{featureDirectory}}`
+- **Generated**: `{{generatedAt}}`
+- **Spec status**: {{specStatus}}
+- **Plan status**: {{planStatus}}
+
+---
+
+## Code Quality
+
+- [ ] All files follow project coding standards (lint clean)
+- [ ] No `TODO` / `FIXME` markers remain in production code
+- [ ] Error handling covers both expected and unexpected failures
+- [ ] Logging follows project conventions (no console.log in prod paths)
+- [ ] Public APIs have type signatures
+- [ ] No dead code or unused imports
+
+## Testing
+
+- [ ] Unit tests cover business logic (target ≥ 80% coverage)
+- [ ] Integration tests for external dependencies
+- [ ] Edge cases documented and tested
+- [ ] Test fixtures are realistic (no `foo`/`bar` placeholders)
+- [ ] Tests are deterministic (no flaky timing/ordering)
+- [ ] Tests run independently (no shared mutable state)
+
+## Security
+
+- [ ] Input validation on all endpoints / boundaries
+- [ ] Authentication and authorization verified
+- [ ] No secrets in code, fixtures, or configuration files
+- [ ] OWASP Top 10 reviewed (injection, XSS, auth, etc.)
+- [ ] Sensitive data handling (PII, tokens) audited
+- [ ] Dependency vulnerabilities checked
+
+## Performance
+
+- [ ] No N+1 query patterns
+- [ ] Pagination on list endpoints
+- [ ] Caching strategy documented (where applicable)
+- [ ] Load characteristics measured for critical paths
+- [ ] Memory / connection pools sized appropriately
+
+## Documentation
+
+- [ ] API documentation reflects new contracts
+- [ ] README updated when surface changes
+- [ ] Architecture decisions recorded (in `plan.md` Decisions section)
+- [ ] Operational runbook (if applicable)
+- [ ] Migration / rollback procedure documented
+
+## Accessibility (UI features)
+
+- [ ] Screen-reader compatible
+- [ ] Keyboard navigation supported (no mouse-only flows)
+- [ ] Color contrast meets WCAG AA
+- [ ] Touch targets ≥ 44px on mobile
+- [ ] Localizable strings (no hardcoded user-facing text)
+
+## Mobile (when applicable)
+
+- [ ] Tested on iOS minimum supported version
+- [ ] Tested on Android minimum supported version
+- [ ] Offline-friendly (graceful degradation)
+- [ ] Battery / data usage acceptable
+- [ ] Push / notification permissions handled correctly
+
+## Constitution
+
+- [ ] No principle violated without explicit, documented mitigation
+- [ ] Test-First respected (where mandated)
+- [ ] Library-First respected (no in-house reimplementation of common libs)
+
+## Observability
+
+- [ ] Critical paths emit logs at appropriate level
+- [ ] Key metrics exported (latency, errors, throughput)
+- [ ] Distributed tracing in place (where applicable)
+- [ ] Alerts wired for SLO violations
+
+---
+
+## Sign-Off
+
+- [ ] All boxes above checked OR justified inline with `<!-- justification: ... -->`
+- [ ] Reviewer: `{{reviewerEmail}}`
+- [ ] Date: `{{signOffDate}}`
+
+---
+
+## Rules
+
+1. **No partial sign-off**: every box must be ticked OR justified.
+2. **Justifications are auditable**: inline justifications must reference a decision in `plan.md` or an issue number.
+3. **Re-runnable**: `/rpt.checklist` regenerates this file when artifacts change; user-justifications are preserved between runs.

package/templates/commands/analyze.md

@@ -0,0 +1,103 @@
+---
+description: Analyze consistency between spec, plan, tasks, and implementation
+handoffs:
+  - label: Fix issues in spec
+    agent: rpt.specify
+    prompt: "Update the spec to resolve inconsistencies"
+    send: false
+  - label: Generate checklist
+    agent: rpt.checklist
+    prompt: "Generate a quality checklist"
+    send: false
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.analyze
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_analyze`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root. Parse JSON for `FEATURE_DIR`, `AVAILABLE_DOCS`.
+2. **Load artifacts**: Read all available documents.
+3. **Cross-reference analysis**: Check consistency between artifacts.
+4. **Report findings**: Generate structured consistency report.
+
+## Analysis Dimensions
+
+### 1. Spec ↔ Plan Alignment
+
+- Every user story in spec has a corresponding architecture decision in plan
+- Plan does not introduce requirements not in spec
+- Non-functional requirements are addressed in plan
+
+### 2. Plan ↔ Tasks Coverage
+
+- Every architecture decision maps to at least one task
+- No orphan tasks (task without plan backing)
+- Phase ordering reflects dependency analysis
+
+### 3. Spec ↔ Tasks Traceability
+
+- Every user story has `[US<N>]` tagged tasks
+- Acceptance criteria map to verifiable tasks
+- Priority ordering (P1/P2/P3) is preserved
+
+### 4. Constitution Compliance
+
+- Read `.raptor/memory/constitution.md`
+- Verify all principles are honored in current artifacts
+- Flag violations with severity
+
+### 5. Completeness
+
+- No `[NEEDS CLARIFICATION]` items remaining
+- All `TODO` markers resolved
+- Contracts match data model
+
+## Output Format
+
+```markdown
+# Consistency Analysis — <feature-name>
+
+## Summary
+- ✅ N checks passed
+- ⚠️ N warnings
+- ❌ N errors
+
+## Findings
+
+### [ERROR/WARNING] <Finding Title>
+- **Affected artifacts**: spec.md, plan.md
+- **Description**: ...
+- **Recommendation**: ...
+
+## Traceability Matrix
+
+| User Story | Plan Section | Tasks | Status |
+|------------|-------------|-------|--------|
+| US1        | §2.1        | T005, T006 | ✅ |
+```
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_analyze`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/commands/checklist.md

@@ -0,0 +1,87 @@
+---
+description: Generate quality checklist for the feature
+handoffs:
+  - label: Implement the feature
+    agent: rpt.implement
+    prompt: "Execute tasks and write code"
+    send: false
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.checklist
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_checklist`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root. Parse JSON for `FEATURE_DIR`, `AVAILABLE_DOCS`.
+2. **Load artifacts**: Read spec.md, plan.md, tasks.md (if available).
+3. **Generate checklist**: Create comprehensive quality checklist.
+4. **Write**: Save to `<FEATURE_DIR>/checklists/requirements.md`.
+
+## Checklist Categories
+
+### Code Quality
+
+- [ ] All files follow project coding standards
+- [ ] No TODO/FIXME markers remain in production code
+- [ ] Error handling is comprehensive
+- [ ] Logging follows project conventions
+
+### Testing
+
+- [ ] Unit tests cover business logic (≥80% coverage)
+- [ ] Integration tests for external dependencies
+- [ ] Edge cases documented and tested
+- [ ] Test fixtures are realistic
+
+### Security
+
+- [ ] Input validation on all endpoints
+- [ ] Authentication/authorization verified
+- [ ] No secrets in code or configuration
+- [ ] OWASP top 10 addressed
+
+### Performance
+
+- [ ] No N+1 query patterns
+- [ ] Pagination for list endpoints
+- [ ] Caching strategy documented
+- [ ] Load testing performed
+
+### Documentation
+
+- [ ] API documentation updated
+- [ ] README updated if needed
+- [ ] Architecture decisions recorded
+- [ ] Runbook for operations
+
+### Accessibility (if UI)
+
+- [ ] Screen reader compatible
+- [ ] Keyboard navigation works
+- [ ] Color contrast meets WCAG AA
+- [ ] Touch targets ≥ 44px
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_checklist`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/commands/clarify.md

@@ -0,0 +1,85 @@
+---
+description: Ask clarifying questions to resolve NEEDS CLARIFICATION items in the spec
+handoffs:
+  - label: Plan the implementation
+    agent: rpt.plan
+    prompt: "Create an implementation plan based on the clarified spec"
+    send: false
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.clarify
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_clarify`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root. Parse JSON for `FEATURE_DIR`.
+2. **Load spec**: Read `<FEATURE_DIR>/spec.md`.
+3. **Find clarification needs**: Extract all `[NEEDS CLARIFICATION: <question>]` markers.
+4. **Generate questions**: For each marker, formulate a clear, answerable question.
+5. **Present Q&A table**: Show questions to the user in a numbered table.
+6. **Process answers**: Update `spec.md` with resolved clarifications.
+
+## Phases
+
+### Phase 0 — Load Context
+
+Run `{SCRIPT}` and parse JSON. Read `<FEATURE_DIR>/spec.md`.
+
+### Phase 1 — Extract Clarifications
+
+Scan `spec.md` for all `[NEEDS CLARIFICATION: ...]` markers. For each:
+
+- Extract the embedded question.
+- Categorize: `scope`, `technical`, `ux`, `business`.
+
+### Phase 2 — Q&A Session
+
+Present a numbered table:
+
+| # | Category | Question | Current Assumption |
+|---|----------|----------|-------------------|
+| 1 | scope    | ...      | ...               |
+
+If `$ARGUMENTS` contains answers (e.g., "1: yes, 2: use PostgreSQL"), process them directly.
+Otherwise, wait for user input.
+
+### Phase 3 — Resolution
+
+For each answered question:
+
+1. Remove the `[NEEDS CLARIFICATION: ...]` marker.
+2. Replace with the resolved text.
+3. If the answer reveals new requirements, add them to the appropriate section.
+
+### Phase 4 — Re-validate
+
+After all clarifications are resolved:
+
+1. Re-read the spec.
+2. Check for any remaining `[NEEDS CLARIFICATION]` items.
+3. If none remain, mark the spec as `clarified`.
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_clarify`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/commands/constitution.md

@@ -0,0 +1,126 @@
+---
+description: Create or update the project constitution with interactive ratification
+handoffs:
+  - label: Review constitution
+    agent: rpt.plan
+    prompt: "Plan the next feature with the updated constitution"
+    send: false
+  - label: Specify a new feature
+    agent: rpt.specify
+    prompt: "Specify a new feature"
+    send: false
+scripts:
+  sh: scripts/bash/common.sh
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.constitution
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_constitution`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+   - If `enabled: false` → skip silently.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Check existing constitution**: Read `.raptor/memory/constitution.md` if it exists.
+2. **Mode selection**:
+   - If constitution exists → UPDATE mode (present current principles, ask what to change).
+   - If constitution does not exist → CREATE mode (start from template).
+3. **Interactive ratification**:
+   - Present each principle for review.
+   - User can approve, modify, or reject each principle.
+   - Track changes for the ratification history.
+4. **Version bump**: Increment the version number (patch for edits, minor for new sections, major for structural changes).
+5. **Write**: Save the constitution to `.raptor/memory/constitution.md`.
+6. **Update ratification history**: Append a new row to the history table.
+
+## Phases
+
+### Phase 0 — Load Existing Constitution
+
+Read `.raptor/memory/constitution.md` if it exists. Parse the current principles, sections, and ratification history.
+
+If creating from scratch, copy from the constitution template (`templates/constitution-template.md` via priority stack resolution).
+
+### Phase 1 — Principle Review
+
+For each principle section in the constitution:
+
+1. Present the principle name and description.
+2. Ask the user: **Approve / Modify / Remove?**
+3. If **Modify**: ask for the new description. Replace in-place.
+4. If **Remove**: mark for deletion. Confirm with user.
+
+### Phase 2 — New Principles
+
+Ask: "Do you want to add new principles?"
+
+For each new principle:
+
+1. Ask for principle name.
+2. Ask for principle description.
+3. Place in the appropriate section.
+
+### Phase 3 — Section Management
+
+Ask: "Do you want to add, rename, or remove sections?"
+
+Handle section-level operations.
+
+### Phase 4 — Ratification
+
+1. Show a summary diff of all changes.
+2. Ask for final approval.
+3. If approved:
+   - Bump version.
+   - Update `Last Updated` timestamp.
+   - Append to ratification history.
+   - Write file.
+4. If rejected: discard changes.
+
+## Output Format
+
+The constitution is a Markdown file with the following structure:
+
+```markdown
+# Constitution — <Project Name>
+
+> **Version**: x.y.z
+> **Last Updated**: <ISO 8601>
+
+## Core Principles
+
+### <Principle Name>
+<Principle Description>
+
+## <Section Name>
+
+### <Section Principle Name>
+<Section Principle Description>
+
+## Ratification History
+
+| Version | Date | Author | Change |
+|---------|------|--------|--------|
+| x.y.z   | date | author | description |
+```
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_constitution`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.