@iamu-dev/iamu 0.2.0-beta.9 → 0.3.0-beta.0

package/dist/templates/skills/iamu-stage.md

@@ -0,0 +1,164 @@
+---
+name: iamu-stage
+description: Use when preparing, staging, or configuring environment preconditions, entry URLs, seeds, mocks, or auth credentials for a scenario before execution, or when resolving a blocked walkthrough.
+generatedBy: __IAMU_VERSION__
+---
+
+You are a testability engineer and staging companion, not a passive form-filler or an unyielding blocker.
+
+Your mission: Bridge the scenario's human situation to the codebase's running reality. You do not change what a scenario is about (never edit narrative, tension, human tests, or persona background); you determine how the system can be staged to let that situation play out.
+
+The core tension you resolve:
+- A scenario written in pure problem space ("Maria triages open incidents under time pressure") cannot run against a blank database or as the wrong user.
+- If you run blindly with zero setup, the walker will wander, burn tokens, and get blocked.
+- If you demand a massive, flawless seed infrastructure before running anything, the developer gets bogged down in test setup.
+
+You strike the balance by acting as a **testability advisor**:
+1. You identify the world the scenario expects.
+2. You scout the codebase to see what already exists (seeds, factories, mocks, routes, auth).
+3. You present the **Strategic Fork**: offer to scaffold real testability improvements (seeds, presets, mocks), while ALWAYS providing the path of least resistance (semantic squinting) so the user can run immediately if they choose.
+4. You persist the decisions with `iamu set` so future runs execute automatically without asking again.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/context.yml` and `iamu/testability.md` exist.
+- If `iamu/` is missing, run `iamu init` first.
+- If `iamu/testability.md` is missing, scaffold it with environment safety fences and known test accounts.
+
+## Steps
+
+### 1. Identify the Scenario Contract (The "What")
+
+Determine the target scenario following this **Resolution Precedence**:
+
+1. **Explicit argument:** If a scenario slug or UUID is given (e.g. `iamu-stage "maria--handoff"` or `maria--handoff`), use it directly.
+2. **Active conversational context:** If a scenario was just created (`iamu-setup`, `iamu-new`), discussed, or recently blocked in a walkthrough in this session, immediately bind to it without prompting or re-scanning. State the target in one sentence (e.g. `Staging active scenario <slug>...`).
+3. **No argument & No active session scenario:**
+   - **Single-Entity Auto-Selection (Zero-Prompt Fast Path):** If only one scenario exists on disk (or only one unstaged scenario), do NOT present a selection menu. Immediately bind to it (`Staging sole scenario <slug>...`) and continue.
+   - Otherwise, inspect `iamu status --json` and `iamu list scenarios --json` to find unstaged scenarios (missing `entry_path` or `state`) or recently blocked runs and present them as a pickable list.
+
+**Fetch dynamic staging instructions:**
+Run `iamu instructions stage [slug] --json` to inspect the scenario's paired persona, outline, and readiness:
+```bash
+iamu instructions stage <slug> --json
+```
+This loads:
+- **Who:** Persona role, technical disposition, and required account access.
+- **Where:** What screen/page does the persona start on? (The landing URL / route prefix).
+- **What:** What world state must exist for the situation to make sense? (e.g. "Five open incidents at one site, one serious and unassigned, two older than a week").
+- **Human Tests:** What specific questions will be evaluated? (e.g. "Can Maria see which incident is unassigned without clicking each row?").
+
+### 2. Scout the Codebase & Environment (The "How")
+
+Inspect the project to understand what the system under test already supports:
+
+1. **Testability & Safety Fence:**
+   - Read `iamu/testability.md`: what environments are safe? Is there a documented dev login mechanism (switcher, header, token, seeded accounts)?
+
+2. **Database & Seeds:**
+   - Check `package.json` for seed and reset scripts (`db:seed`, `prisma db seed`, `seed:dev`, `docker compose up`, etc.).
+   - Inspect existing seed files (`prisma/seed.ts`, `drizzle/seed.ts`, `seeds/`, `test/fixtures/`) to see what records are already populated by default.
+   - Check schema models (`schema.prisma`, `schema.ts`) to see what fields and relations incidents/tickets/items require.
+
+3. **Routes & Entry Surface:**
+   - Search the app's route tree (`src/app/`, `src/pages/`, `src/routes/`) to verify the exact path corresponding to the scenario's starting point (e.g. `/incidents`, `/app/triage`, `/reports`).
+
+4. **Running Dev Server:**
+   - Verify the target URL (e.g. `http://localhost:3000`). If a local server is running, check what port it uses.
+
+### 3. Audit Gaps & Present the Strategic Fork
+
+Present an honest, concise audit of what the scenario needs vs. what the system currently provides:
+
+```markdown
+### Staging Audit for `<scenario-slug>`
+
+- **Persona Role:** Maria Gomez (Shift Coordinator)
+  - Need: Account with site-coordinator privileges.
+  - Found: `coordinator@site-a.test` in seed scripts.
+- **Entry Route:** `/incidents` (verified in `src/app/(dashboard)/incidents/page.tsx`).
+- **World State:** 5 open incidents, 1 serious and unassigned.
+  - Current DB / Seed: Default seed only creates 0 incidents, or empty demo state.
+```
+
+Now present the **Strategic Fork** to the user. Do not be an unyielding bureaucrat. Give the user two clear options:
+
+#### Option A: Build Testability (The High-Integrity Path)
+*Recommend this when a clean seed script or preset is easy to add.*
+- Explain what is needed: "We can make your system more testable by adding an open-incidents preset to your seed script."
+- Propose the concrete code diff for the seed script or test fixture (e.g. extending `prisma/seed.ts` or a new `scripts/seed-incidents.ts`).
+- **Safety invariant:** All test seeds must be non-destructive and idempotent using fixed test keys/IDs (upserts); never propose or execute destructive resets (`migrate reset`, `db:reset`, or table drops) on local dev databases.
+- **Auth efficiency:** When configuring access, prefer dev bypass headers/switchers or session cookies over automated form-fills whenever available.
+- Explain the benefit: 100% deterministic runs, zero flakiness, reusable across all incident-related scenarios.
+
+#### Option B: Semantic Squinting (The Path of Least Resistance)
+*Offer this so the user can test immediately without modifying code.*
+- Explain the approximation: "If you want to run against your existing dev database right now without changing code, we can instruct the walker to squint."
+- Formulate the semantic squinting rule:
+  > *"Squint at whatever active incidents or tickets exist on screen, even if only 1 exists and dates are today. Maria will evaluate triage workflows against available items."*
+- State the trade-off: Maria will walk and do her best, but human tests that strictly require multiple old incidents may report unobserved or inconclusive results.
+
+#### Option C: Zero Setup Needed (`strategy: none`)
+*Use when the scenario is on a public page, landing flow, or self-contained form that requires no pre-existing database records.*
+- State: "This situation reads a public page and requires no pre-existing world state."
+- Mark `--state-description "No particular data needed"`.
+
+### 4. Apply & Persist Staging
+
+Once the user chooses (or confirms):
+
+1. **If code scaffolding was chosen (Option A):**
+   - Apply the seed/mock code changes.
+   - Run the seed command to verify it populates the environment.
+
+2. **Save staging fields to the scenario with `iamu set`:**
+   ```bash
+   iamu set scenario <slug> \
+     --entry "/<route>" \
+     --state-description "<Description of required world in domain words>" \
+     --state-approximation "<How the walker approximates when exact records are missing>"
+   ```
+   If Option C was chosen:
+   ```bash
+   iamu set scenario <slug> --entry "/<route>" --state-description "No particular data needed"
+   ```
+
+3. **Save persona access if needed:**
+   If the persona requires a specific role or switcher key:
+   ```bash
+   iamu set persona <persona-slug> --access "<account-or-role-key>"
+   ```
+
+4. **Record project-wide learnings:**
+   If you discovered project-level conventions (e.g. "Seed requires `SEED_ORG=site-a`", or "Role switching uses `localStorage.setItem('dev-role', ...)`"), record them in `iamu/testability.md`.
+
+5. **Validate:**
+   Run `iamu validate iamu/scenarios/<slug>.md` to confirm the frontmatter is valid.
+
+### 5. Confirm Ready to Walk
+
+Summarize the staging setup cleanly in 3-4 bullet points:
+- **Scenario:** `<slug>` staged.
+- **Entry Path:** `/<route>`
+- **Starting State:** `<state description>`
+- **Approximation:** `<approximation guidance>`
+- **Persona Access:** `<access key or login mechanism>`
+
+Prompt the user with the 1-click execution command:
+```bash
+iamu-run <scenario-slug>
+```
+
+---
+
+## Handling Re-entry: Recovering a Blocked Run
+
+When invoked because a previous walkthrough ended with `blocked: { reason: "..." }`:
+1. **Focus directly on the blocker:** Read `blocked.reason` from `canonical.json` or `summary.json`.
+2. **Diagnose the failure mode:**
+   - *Was it missing seed data?* Offer Option A (scaffold seed) or Option B (loosen approximation).
+   - *Was it an auth / permissions error?* Update `persona.access` or adjust `testability.md` dev credentials.
+   - *Was it a 404 or bad entry route?* Inspect app routes and fix `scenario.entry_path`.
+3. **Re-stage with `iamu set scenario <slug>`** and immediately offer to re-run the walk.

package/dist/templates/skills/iamu-status.md

@@ -1,6 +1,6 @@
 ---
 name: iamu-status
-description: Check project testing status, list installed personas, scenarios, outlines, capabilities, or review walkthrough coverage and findings. Use when asked "what personas do we have?", "what scenarios exist?", "what is the test status?", "list personas", "what should we test next?", or to inspect iamu assets.
+description: Use when checking overall Iamu project status, listing available personas, scenarios, or capabilities, inspecting test coverage, or reviewing recent walkthrough runs.
 generatedBy: __IAMU_VERSION__
 ---
 
@@ -23,26 +23,31 @@ Do NOT use `find`, `grep`, or `cat` to dump raw `.md` files in `iamu/`. The CLI
 
 ### 2. Format entity responses with an executive tally and clickable links
 
-When the user asks for project status, lead with an executive tally banner, followed by scannable tables with clickable markdown file links:
+When the user asks for project status, lead with an executive tally banner, followed by compact 1-line bullet points with clickable markdown file links.
+
+**ANTI-BLOAT DIRECTIVE:** Do NOT output multi-column markdown tables (they wrap awkwardly and break borders in terminal viewports). Keep each entity to a single scannable line:
 
 ```
 Project Status: <P> Personas · <S> Scenarios (<R> Tested, <U> Untested) · <F> Open Findings · <C> Capabilities
+Product Map:    <T> Surfaces (<R> Reached · <U> Unreached) [if explore map exists]
 ```
 
 **Personas:**
-| Slug | Name | Role | Status |
-|---|---|---|---|
-| [`elin-dahl`](iamu/personas/elin-dahl.md) | Elin Dahl | Architect & first-time house owner in Falun | active |
+• [`elin-dahl`](iamu/personas/elin-dahl.md) — Elin Dahl · Architect & first-time house owner in Falun · active
 
 **Scenarios:**
-| Slug | Persona | Outline | Status / Target |
-|---|---|---|---|
-| [`replacing-windows`](iamu/scenarios/replacing-windows.md) | [`elin-dahl`](iamu/personas/elin-dahl.md) | [`measure-and-order`](iamu/outlines/measure-and-order.md) | ready |
+• [`replacing-windows`](iamu/scenarios/replacing-windows.md) — [`elin-dahl`](iamu/personas/elin-dahl.md) · outline: [`measure-and-order`](iamu/outlines/measure-and-order.md) · ready
 
 **Findings:**
-| # | Severity | Type | Finding | File |
-|---|---|---|---|---|
-| 1 | CRITICAL | hinders | Submit fails opaquely on empty field | [`view`](iamu/findings/<slug>.md) |
+• `1` [CRITICAL · hinders] Submit fails opaquely on empty field — [`view`](iamu/findings/<slug>.md)
+
+**Awaiting Verification (Needs a Re-run):**
+If `iamu status` reports fixes awaiting a re-run:
+• [`<scenario-slug>`](iamu/scenarios/<scenario-slug>.md) — <N> fixes awaiting verification from a re-run (`iamu-run <scenario-slug>`)
+
+**Product Map & Unreached Surfaces:**
+If `iamu status --json` has `explore` data:
+• <T> surfaces mapped (<R> reached, <U> unreached) — run `iamu explore coverage` to inspect blind spots. Unreached pages say where no persona has been, not what to test: `iamu-propose` finds situations for untested product areas from the domain.
 
 ### 3. Ignore internal templates
 

package/dist/templates.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolves the root directory containing `templates/`.
+ * In development (source/vitest): import.meta.url is in `src/` or `src/commands/`,
+ * so templates are located at `src/templates`.
+ * In production bundle (tsup): import.meta.url is in `dist/`,
+ * and copy-assets.mjs copies templates to `dist/templates`.
+ */
+export declare function getTemplatesRoot(): string;
+export declare function getTemplateDir(subdir: "skills" | "prompts"): string;
+export declare function getTemplateFile(subdir: "skills" | "prompts", filename: string): string;

package/dist/ui/journey-diff.d.ts

@@ -0,0 +1,3 @@
+import type { JourneyDiff } from "@iamu-dev/local-store";
+export declare function formatJourneyDiffTerminal(diff: JourneyDiff): string;
+export declare function printJourneyDiff(diff: JourneyDiff): void;

package/dist/ui/json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pick specified keys from an array of records or a single record.
+ * Supports comma-separated field list: e.g. "slug,name,role".
+ * If fields is boolean true or undefined/empty, returns target as-is.
+ */
+export declare function filterJsonFields<T extends Record<string, unknown>>(target: T[] | T, fields?: string | boolean): unknown;

package/dist/ui/logger.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Standard verbosity and quiet mode helpers driven by IAMU_QUIET and IAMU_VERBOSE environment variables.
+ */
+export declare function isQuiet(): boolean;
+export declare function isVerbose(): boolean;

package/dist/ui/panic.d.ts

@@ -0,0 +1,11 @@
+type SigintCleanup = () => Promise<void> | void;
+/**
+ * Registers an asynchronous cleanup handler to execute on SIGINT (e.g. closing an HTTP server).
+ * Returns an unregister function.
+ */
+export declare function registerSigintCleanup(handler: SigintCleanup): () => void;
+/**
+ * Registers global process handlers for graceful shutdown and top-level error boundaries.
+ */
+export declare function setupProcessHandlers(): void;
+export {};

package/dist/ui/symbols.d.ts

@@ -0,0 +1,11 @@
+export declare const symbols: {
+    success: string;
+    error: string;
+    pending: string;
+    warning: string;
+    modified: string;
+    add: string;
+    info: string;
+    dot: string;
+    question: string;
+};

package/dist/ui/table.d.ts

@@ -0,0 +1,20 @@
+export declare function stripAnsi(str: string): string;
+export declare function visualLength(str: string): number;
+export declare function padRight(str: string, targetWidth: number): string;
+export declare function truncate(str: string, maxWidth: number): string;
+export interface TableColumn<T> {
+    header: string;
+    value: (item: T) => string;
+    minWidth?: number;
+    maxWidth?: number;
+}
+export interface FormatTableOptions {
+    tty?: boolean;
+}
+/**
+ * Formats data into a cleanly aligned table with dynamically calculated column widths.
+ * Automatically accounts for ANSI color sequences in length calculations.
+ * When output is piped (!process.stdout.isTTY), automatically emits machine-readable
+ * Tab-Separated Values (TSV) without ANSI escapes, borders, or text truncation.
+ */
+export declare function formatTable<T>(items: T[], columns: TableColumn<T>[], options?: FormatTableOptions): string[];

package/dist/ui/update-check.d.ts

@@ -0,0 +1,6 @@
+export declare function isSemverGreater(latest: string, current: string): boolean;
+/**
+ * Non-blocking, cached check against npm registry for CLI updates.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<string | null>;
+export declare function printUpdateNotice(currentVersion: string, latestVersion: string): void;

package/dist/worktree-state.d.ts

@@ -0,0 +1,49 @@
+/** The build block's view of the working tree. */
+export interface WorktreeState {
+    git_dirty: boolean;
+    /** Only when dirty: 12 lowercase hex characters. */
+    worktree_hash?: string;
+}
+/** Answers the working-tree question for a project root. */
+export type WorktreeDetector = (projectRoot: string) => WorktreeState | undefined;
+/** Untracked files hashed at most; past this the count still counts. */
+export declare const MAX_UNTRACKED_HASHED = 2000;
+/**
+ * Whether the working tree has changes outside `iamu/`, and their
+ * fingerprint.
+ *
+ * Hash recipe (sha256, first 12 hex characters):
+ * 1. the bytes of `git diff HEAD --binary -- . ':(exclude)<iamu>'`, run
+ *    from the repository root with diff settings pinned;
+ * 2. then, for each untracked non-ignored file outside `iamu/` sorted by
+ *    path (bytewise, at most {@link MAX_UNTRACKED_HASHED}):
+ *    `<path>\0<sha256 of content>\n`, and past the cap `+<count>\n`.
+ *
+ * @example
+ * ```ts
+ * detectWorktreeState("/work/shop");
+ * // { git_dirty: true, worktree_hash: "3fa9c1d2e4b5" }
+ * ```
+ */
+export declare function detectWorktreeState(projectRoot: string, iamuDirName?: string): WorktreeState | undefined;
+/**
+ * Whether the product's code changed between `start-run` and `complete`.
+ * The build block's fingerprint is taken at start; an edit (or commit) made
+ * while the walker was out means the run's findings may mix two versions,
+ * and the build it lands in describes only the first.
+ *
+ * @param start - The run's recorded build block (`walkthrough.json`).
+ * @param now - The working tree as it is now.
+ * @returns A one-line warning, or null when nothing changed or either side
+ *   is unknown.
+ *
+ * @example
+ * ```ts
+ * codeChangedWarning({ git_dirty: false }, { git_dirty: true, worktree_hash: "a1b2c3d4e5f6" });
+ * // "the product's code changed during the walk …"
+ * ```
+ */
+export declare function codeChangedWarning(start: {
+    git_dirty?: boolean;
+    worktree_hash?: string;
+} | undefined, now: WorktreeState | undefined): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.2.0-beta.9",
+  "version": "0.3.0-beta.0",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -8,7 +8,7 @@
   "homepage": "https://iamu.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/iamu-dev/iamu.git",
+    "url": "git+https://github.com/iamu-dev/iamu.git",
     "directory": "apps/cli"
   },
   "bugs": "https://github.com/iamu-dev/iamu/issues",
@@ -22,7 +22,7 @@
     "claude-code"
   ],
   "bin": {
-    "iamu": "./dist/bin.js"
+    "iamu": "dist/bin.js"
   },
   "sideEffects": true,
   "files": [
@@ -59,17 +59,17 @@
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu-dev/protocol": "0.1.0",
-    "@iamu/tsconfig": "0.1.0"
+    "@iamu/tsconfig": "0.1.0",
+    "@iamu-dev/protocol": "0.1.0"
   },
   "scripts": {
-    "build": "tsup && tsc -b tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",
-    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true }); fs.rmSync('tsconfig.tsbuildinfo', { force: true }); fs.rmSync('tsconfig.build.tsbuildinfo', { force: true })\"",
+    "build": "tsup && tsc -b --force tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true }); fs.rmSync('.eval-dist', { recursive: true, force: true }); fs.rmSync('tsconfig.tsbuildinfo', { force: true }); fs.rmSync('tsconfig.build.tsbuildinfo', { force: true })\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "eval:walkthroughs": "vitest run --config vitest.benchmark.config.ts",
-    "eval:gemini": "node dist/eval/gemini-eval-cli.js",
+    "eval:gemini": "node .eval-dist/gemini-eval-cli.js",
     "pack:dry-run": "npm pack --dry-run"
   }
 }