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

package/dist/commands/instructions-walk.d.ts

@@ -0,0 +1,69 @@
+import { type GuidanceRule, type RevisitPlace } from "@iamu-dev/local-store";
+import { type RunViewport, type ScenarioState } from "@iamu-dev/protocol";
+/** "The browser is sized as a phone screen, 390×844." */
+export declare function viewportLine(v: RunViewport): string;
+interface WalkerPromptParts {
+    targetUrl: string | null;
+    persona: {
+        name: string;
+        role: string;
+        disposition: string | null;
+        background: string | null;
+    };
+    outline: {
+        title: string;
+        tension: unknown;
+        narrative: unknown;
+    };
+    brief: string | null;
+    access: {
+        project: string | null;
+        persona: string | null;
+    };
+    methodology: string;
+    dismissed: string[];
+    /** Active tester guidance in the scenario's scope. */
+    guidance?: GuidanceRule[];
+    /** Where fixes awaiting a re-run were seen — places only, no findings. */
+    revisit?: RevisitPlace[];
+    scenarioSlug: string;
+    runId: string;
+    runDirPath: string;
+    projectRoot: string;
+    surface: string;
+    /** The run's viewport (`start-run`, from persona tags), if any. */
+    viewport?: RunViewport | null;
+    /** Scenario environment state and semantic approximation guidance */
+    state?: ScenarioState | null;
+    /** Product domain and regulatory context from context.yml */
+    context?: string | null;
+    /** Untestable execution boundaries from testability.md */
+    untestableBoundaries?: string[] | null;
+}
+/**
+ * Extracts bullet points from a markdown "## Untestable Boundaries" section.
+ */
+export declare function extractUntestableBoundaries(body: string): string[];
+/**
+ * The places-to-pass-through section: where this scenario's fixes
+ * awaiting a re-run were observed, framed as part of the persona's own
+ * route. It carries URLs and screen names only — never a finding's
+ * title, type, severity or any hint of what was wrong, so the walker
+ * judges each place fresh (the same reason it never sees human tests).
+ * Empty when nothing awaits, so those prompts stay as they were.
+ */
+export declare function revisitSection(places: readonly RevisitPlace[]): string[];
+/**
+ * The walker subagent's whole prompt — persona, situation, brief, access,
+ * driving surface, methodology, and the run-directory contract (steps,
+ * screenshots, findings, summary.json). Composed here so every host
+ * hands its walker the same thing instead of assembling it by hand.
+ */
+export declare function composeWalkerPrompt(p: WalkerPromptParts): string;
+export declare function instructionsWalk(opts: {
+    scenario?: string;
+    run?: string;
+    surface?: string;
+    json?: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/instructions.d.ts

@@ -0,0 +1,30 @@
+export interface InstructionsOptions {
+    phase?: string;
+    scenario?: string;
+    run?: string;
+    surface?: string;
+    json?: boolean;
+}
+/**
+ * Generates dynamic staging instructions for an active or specified scenario.
+ */
+export declare function instructionsStage(slug?: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * Generates dynamic setup instructions for the project.
+ */
+export declare function instructionsSetup(opts?: {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * Generates dynamic triage instructions for reviewing run findings.
+ */
+export declare function instructionsTriage(slug?: string, opts?: {
+    run?: string;
+    json?: boolean;
+}): Promise<void>;
+/**
+ * Top-level dispatcher for `iamu instructions [phase] [slug]`.
+ */
+export declare function instructions(phase?: string, slug?: string, opts?: InstructionsOptions): Promise<void>;

package/dist/commands/list.d.ts

@@ -0,0 +1,5 @@
+export declare function list(type: string | undefined, opts: {
+    capability?: string;
+    diff?: string | boolean;
+    json?: boolean | string;
+}): Promise<void>;

package/dist/commands/live-run-client.d.ts

@@ -0,0 +1,127 @@
+import type { RunStep } from "@iamu-dev/protocol";
+/** Timeout for run registration on start-run (3 seconds). */
+export declare const REGISTER_TIMEOUT_MS = 3000;
+/** Timeout for per-step and phase event dispatches (1.5 seconds). */
+export declare const EVENT_TIMEOUT_MS = 1500;
+/** Cap screenshot base64 at 5 MB raw binary (~6.7 MB base64, under the 8 MB payload cap). */
+export declare const MAX_LIVE_SCREENSHOT_BYTES: number;
+export type LiveRunPhase = "walking" | "completing" | "matching" | "judging" | "publishing";
+export interface LiveRunMeta {
+    walkthrough_id: string;
+    viewer_url: string;
+    project_id: string;
+    api_url: string;
+    last_seq: number;
+}
+export interface RegisterLiveRunParams {
+    projectRoot: string;
+    runId: string;
+    scenarioSlug: string;
+    targetUrl: string;
+    startedAt?: string;
+    lenses?: string[];
+    fetchFn?: typeof fetch;
+}
+export interface RegisterLiveRunResult {
+    walkthroughId: string;
+    viewerUrl: string;
+    status: "created" | "resumed";
+}
+export interface LiveStepEvent {
+    seq: number;
+    type: "step";
+    step: {
+        number: number;
+        title: string;
+        persona_reasoning?: string | null;
+        grounding?: string | null;
+        page_url?: string | null;
+        surface?: string | null;
+        screenshot_base64?: string;
+    };
+}
+export interface LiveActionEvent {
+    seq: number;
+    type: "action";
+    step_number: number;
+    action_type: string;
+    target?: string | null;
+}
+export interface LiveFindingEvent {
+    seq: number;
+    type: "finding";
+    finding: {
+        id: string;
+        title: string;
+        type: "helps" | "hinders" | "missing" | "irrelevant" | "incorrect";
+        severity: "critical" | "major" | "minor" | "observation";
+        ui_fact?: string | null;
+        consequence?: string | null;
+        step_number?: number | null;
+        task_impact?: string | null;
+        confidence?: string | null;
+    };
+}
+export interface LivePhaseEvent {
+    seq: number;
+    type: "phase";
+    phase: LiveRunPhase;
+}
+export interface LiveAbandonEvent {
+    seq: number;
+    type: "abandon";
+    reason?: string;
+}
+export type LiveRunEvent = LiveStepEvent | LiveActionEvent | LiveFindingEvent | LivePhaseEvent | LiveAbandonEvent;
+export interface LiveEventsResponse {
+    accepted_seq?: number;
+    cancelled?: boolean;
+}
+/**
+ * Reads `<runDir>/live.json`. Returns null when absent or malformed.
+ */
+export declare function loadLiveRunMeta(runDirPath: string): Promise<LiveRunMeta | null>;
+/**
+ * Saves `<runDir>/live.json` atomically.
+ */
+export declare function saveLiveRunMeta(runDirPath: string, meta: LiveRunMeta): Promise<void>;
+/**
+ * Register a running walkthrough with Iamu Cloud (POST /api/projects/:id/live-runs).
+ *
+ * Runs only when the project is cloud-linked, IAMU_LIVE != "0", and valid
+ * credentials exist. Never throws: network errors or 4xx/5xx silently return null.
+ */
+export declare function registerLiveRun(params: RegisterLiveRunParams): Promise<RegisterLiveRunResult | null>;
+/**
+ * Dispatch ordered events to POST /api/projects/:id/live-runs/:runId/events.
+ *
+ * Reads `<runDir>/live.json`. If absent or not cloud-linked, makes 0 network
+ * requests. Increments `last_seq` and catches all network errors silently.
+ */
+export declare function sendLiveEvents(projectRoot: string, runId: string, buildEvents: (startSeq: number) => LiveRunEvent[] | LiveRunEvent, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post a step event with optional base64 screenshot.
+ */
+export declare function sendLiveStep(projectRoot: string, runId: string, step: RunStep, screenshotPath?: string | null, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post a phase transition event (completing, matching, judging, publishing).
+ */
+export declare function sendLivePhase(projectRoot: string, runId: string, phase: LiveRunPhase, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post a finding event.
+ */
+export declare function sendLiveFinding(projectRoot: string, runId: string, finding: {
+    id: string;
+    title: string;
+    type: "helps" | "hinders" | "missing" | "irrelevant" | "incorrect";
+    severity: "critical" | "major" | "minor" | "observation";
+    ui_fact?: string | null;
+    consequence?: string | null;
+    step_number?: number | null;
+    task_impact?: string | null;
+    confidence?: string | null;
+}, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post an abandon event if a run was discarded or failed locally.
+ */
+export declare function sendLiveAbandon(projectRoot: string, runId: string, reason?: string, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;

package/dist/commands/match.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Print the matcher's input bundle: this run's findings, the scenario's
+ * earlier canonical findings, this run's steps, and the prompt.
+ */
+export declare function match(runId: string, opts?: {
+    json?: boolean;
+    promptFile?: string;
+}): Promise<void>;
+export interface MatchRecordOptions {
+    file?: string;
+    data?: string;
+    json?: boolean;
+}
+/** Record the matcher's answer and re-derive the run's delta and report. */
+export declare function matchRecord(runId: string, opts: MatchRecordOptions): Promise<void>;

package/dist/commands/mcp-config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Write or update the `iamu-sync` entry in an MCP config file.
+ * Merges with existing content — does not clobber other servers.
+ * Throws if existing file contains invalid JSON (avoids silent data loss).
+ */
+export declare function writeSyncMcpEntry(mcpPath: string): Promise<void>;
+/**
+ * Check if an MCP config file has an `iamu-sync` entry.
+ */
+export declare function hasSyncMcpEntry(parsed: Record<string, unknown>, mcpPath: string): boolean;

package/dist/commands/new-entity.d.ts

@@ -0,0 +1,34 @@
+export interface NewEntityOptions {
+    name: string;
+    slug?: string;
+    description?: string;
+    body?: string;
+    narrative?: string;
+    access?: string;
+    role?: string;
+    disposition?: string;
+    outline?: string;
+    persona?: string;
+    url?: string;
+    authority?: string;
+    /** Primary capability slug (outline only). */
+    capability?: string;
+    /** Secondary capability slugs, comma-separated or array (outline only). */
+    additionalCapabilities?: string | string[];
+    /** Structural tension driving the situation (outline only). */
+    tension?: string;
+    /** Human-test question to evaluate at walkthrough completion (outline only). */
+    humanTest?: string | string[];
+    /** Route patterns owned by this capability, comma-separated or array (capability only). */
+    paths?: string | string[];
+    /** Optional visual grouping category (capability only). */
+    area?: string;
+    /** Scenario start path, e.g. /en/episodes/1. */
+    entry?: string;
+    /** Scenario assumed environment state description. */
+    stateDescription?: string;
+    /** Scenario squint/approximation guidance when exact records are missing. */
+    stateApproximation?: string;
+    json?: boolean;
+}
+export declare function newEntity(type: string, opts: NewEntityOptions): Promise<void>;

package/dist/commands/new-finding.d.ts

@@ -0,0 +1,25 @@
+export interface NewFindingOptions {
+    scenario?: string;
+    run?: string;
+    title: string;
+    type: string;
+    severity: string;
+    uiFact?: string;
+    consequence?: string;
+    lens?: string;
+    uxHeuristic?: string;
+    /** What the finding does to the persona's task (blocks … enables). */
+    taskImpact?: string;
+    /** How sure the walker is that this is real (high | medium | low). */
+    confidence?: string;
+    /** Step number whose screenshot shows the finding. */
+    step?: string;
+    /** Finding narrative description. */
+    description?: string;
+    /** Concrete recommendation for fixing the finding. */
+    recommendation?: string;
+    /** Complete markdown body (overrides description and recommendation). */
+    body?: string;
+    json?: boolean;
+}
+export declare function newFinding(opts: NewFindingOptions): Promise<void>;

package/dist/commands/open.d.ts

@@ -0,0 +1,8 @@
+export interface OpenOptions {
+    printOnly?: boolean;
+}
+/**
+ * Opens the Iamu Cloud dashboard for the project or a specific walkthrough run.
+ * If the project is not cloud-linked, prompts the user to link or view the terminal summary.
+ */
+export declare function openDashboard(runId?: string, opts?: OpenOptions): Promise<void>;

package/dist/commands/port.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Commander coercer for `--port`. Commander calls a coercer as
+ * `(value, previous)`, so a bare `parseInt` took the previous value as
+ * its radix — reinterpreting the digits — and silently truncated
+ * anything non-numeric instead of rejecting it.
+ *
+ * @param value - Raw option text from the command line.
+ * @returns The port as an integer in `0..65535`.
+ * @throws InvalidArgumentError when `value` is not such an integer.
+ *
+ * @example
+ * ```ts
+ * parsePortOption("8080"); // 8080
+ * parsePortOption("abc"); // throws InvalidArgumentError
+ * ```
+ */
+export declare function parsePortOption(value: string, _previous?: unknown): number;

package/dist/commands/preflight.d.ts

@@ -0,0 +1,26 @@
+export interface PreflightOptions {
+    cwd?: string;
+    json?: boolean;
+}
+export interface PreflightCheckResult {
+    ok: boolean;
+    command?: string;
+    output?: string;
+    skipped?: boolean;
+    reason?: string;
+}
+/**
+ * Detect the fast compile/typecheck/lint command for a target project.
+ */
+export declare function detectPreflightCommand(targetDir: string): Promise<{
+    command: string;
+    args: string[];
+} | null>;
+/**
+ * Executes a fast preflight type/lint check.
+ */
+export declare function runPreflightCheck(targetDir: string): Promise<PreflightCheckResult>;
+/**
+ * CLI handler for `iamu preflight`.
+ */
+export declare function preflight(opts?: PreflightOptions): Promise<void>;

package/dist/commands/prune.d.ts

@@ -0,0 +1,11 @@
+import { type PruneResult } from "@iamu-dev/local-store";
+export interface PruneCliOptions {
+    keep?: string | number;
+    days?: string | number;
+    screenshotsOnly?: boolean;
+    dryRun?: boolean;
+    yes?: boolean;
+    json?: boolean;
+}
+export declare function formatBytes(bytes: number): string;
+export declare function prune(opts?: PruneCliOptions): Promise<PruneResult | undefined>;

package/dist/commands/pull.d.ts

@@ -0,0 +1,5 @@
+export declare function pull(opts?: {
+    force?: boolean;
+    preview?: boolean;
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/register-cloud.d.ts

@@ -0,0 +1,5 @@
+import { type Command } from "commander";
+/**
+ * Registers cloud sync, pull, auth, open, and internal sync-server commands.
+ */
+export declare function registerCloudCommands(program: Command): void;

package/dist/commands/register-findings.d.ts

@@ -0,0 +1,5 @@
+import { type Command } from "commander";
+/**
+ * Registers findings, triage, report, and serve commands.
+ */
+export declare function registerFindingsCommands(program: Command): void;

package/dist/commands/register-project.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+/**
+ * Registers project lifecycle commands: init, status, doctor, list, validate, update, new, completion.
+ */
+export declare function registerProjectCommands(program: Command): void;

package/dist/commands/register-walkthrough.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+/**
+ * Registers walkthrough execution commands: start-run, instructions, browse, step, new-finding, complete, match, match-record, evaluate, evaluate-record, prune.
+ */
+export declare function registerWalkthroughCommands(program: Command): void;

package/dist/commands/register.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { registerCloudCommands } from "./register-cloud.js";
+import { registerFindingsCommands } from "./register-findings.js";
+import { registerProjectCommands } from "./register-project.js";
+import { registerWalkthroughCommands } from "./register-walkthrough.js";
+/**
+ * Registers all CLI command groups onto the root Commander program.
+ */
+export declare function registerAllCommands(program: Command): void;
+export { registerProjectCommands, registerWalkthroughCommands, registerFindingsCommands, registerCloudCommands, };

package/dist/commands/report.d.ts

@@ -0,0 +1,3 @@
+export declare function report(scenario?: string, opts?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/serve.d.ts

@@ -0,0 +1,11 @@
+export interface ServeOptions {
+    /**
+     * `false` (from `--no-open`) prints the dashboard URL instead of
+     * launching a browser, like `iamu open --print`.
+     */
+    open?: boolean;
+}
+/**
+ * Deprecated: The local web UI has been retired in favor of Iamu Cloud and terminal reporting.
+ */
+export declare function serve(opts?: ServeOptions): Promise<void>;

package/dist/commands/set-entity.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Options for `iamu set`. Every field is staging: where a walk starts,
+ * what the world holds, which account a persona uses, which routes an
+ * area owns. What a scenario is about (narrative, tension, human tests,
+ * brief, background) is not settable here — that is authoring's.
+ *
+ * Commander maps `--no-<flag>` to `false`, which clears the field.
+ */
+export interface SetEntityOptions {
+    /** Scenario start path, or `false` to clear. */
+    entry?: string | false;
+    /** Scenario default target URL, or `false` to clear. */
+    target?: string | false;
+    /** Scenario `state.description`. */
+    stateDescription?: string;
+    /** Scenario `state.approximation`. */
+    stateApproximation?: string;
+    /** `false` clears scenario `state` (Commander defaults it to `true`). */
+    state?: boolean;
+    /** Persona access key, or `false` to clear. */
+    access?: string | false;
+    /** Capability route prefixes, comma-separated; replaces `paths`, or `false` to clear. */
+    paths?: string | false;
+    /** Capability route prefix to add (repeatable). */
+    addPath?: string[];
+    /** Capability route prefix to remove (repeatable). */
+    removePath?: string[];
+    /** Capability visual grouping, or `false` to clear. */
+    area?: string | false;
+    /** JSON patch file (or - for stdin) containing staging fields. */
+    file?: string;
+    json?: boolean;
+}
+/**
+ * `iamu set <type> <slug>` — change the staging fields of an existing
+ * entity: a scenario's start path, target and starting state, a
+ * persona's access key, a capability's route prefixes and area.
+ *
+ * @example
+ * ```bash
+ * iamu set scenario maria--handoff --entry /incidents \
+ *   --state-description "Five open incidents at one site"
+ * iamu set capability team-access --add-path /team
+ * ```
+ */
+export declare function setEntity(type: string, slug: string, opts: SetEntityOptions): Promise<void>;

package/dist/commands/skills.d.ts

@@ -0,0 +1,34 @@
+import type { HostAdapter, CommandContent } from "../adapters/types.js";
+export declare function getVersion(): string;
+export declare function loadSkillTemplates(version: string): Map<string, string>;
+export declare function commandsFromSkills(templates: Map<string, string>): CommandContent[];
+/**
+ * Hosts in `projectRoot` that already have iamu skills or commands
+ * installed — the ones `iamu update` refreshes.
+ */
+export declare function detectInstalledHosts(projectRoot: string): HostAdapter[];
+/**
+ * Resolves target hosts for install or update.
+ * If hostFilter is supplied, matches by value or name (case-insensitive).
+ * Otherwise combines already-installed hosts and detected editor hosts in the workspace.
+ */
+export declare function resolveTargetHosts(projectRoot: string, hostFilter?: string): {
+    hosts: HostAdapter[];
+    error?: string;
+};
+/**
+ * Installed skill/command files that differ from what `iamu update` would
+ * write for this CLI version. Local reads only — no network.
+ *
+ * @returns Absolute paths of the stale files; empty when up to date or
+ *   when no host has iamu skills installed.
+ */
+export declare function findStaleSkills(projectRoot: string): Promise<string[]>;
+/** The one-line nudge `iamu status` and `iamu sync` print. */
+export declare const STALE_SKILLS_MESSAGE = "Skills are out of date \u2014 run `iamu update`";
+export declare function installSkillsForHosts(hosts: HostAdapter[], projectRoot: string, version: string, opts?: {
+    quiet?: boolean;
+}): Promise<{
+    totalSkills: number;
+    totalCommands: number;
+}>;

package/dist/commands/start-run.d.ts

@@ -0,0 +1,56 @@
+import { type BuildMetadata, type RunViewport, type ScenarioFrontmatter } from "@iamu-dev/protocol";
+/** `target_url` from `iamu/testability.md`, when there is one. */
+export declare function testabilityTarget(projectRoot: string): Promise<string | null>;
+/**
+ * The URL a run starts at: `--target` (or the scenario's `target_url` or `iamu/testability.md`)
+ * as the base, with the scenario's `entry_path` resolved against it.
+ * Returns an error message instead when there is nothing usable.
+ */
+export declare function resolveStartUrl(target: string | undefined, scenario: Pick<ScenarioFrontmatter, "target_url" | "entry_path">, fallbackTarget?: string | null): {
+    url: string;
+} | {
+    error: string;
+};
+export declare const DEV_CRASH_MARKERS: string[];
+/**
+ * Fast preflight probe to check if the target URL answers HTTP requests.
+ * Times out quickly (default: 1500ms) to avoid stalling walkthrough initialization.
+ * Validates against 5xx crash responses and dev server compiler crash overlays.
+ */
+export declare function checkTargetReachable(url: string, timeoutMs?: number): Promise<{
+    reachable: boolean;
+    error?: string;
+}>;
+/**
+ * The build as one line: label, branch, commit and CI provider. A dirty
+ * tree shows next to the commit, so a re-run after an uncommitted fix
+ * visibly walks a different build.
+ *
+ * @example
+ * ```ts
+ * formatBuild({ git_sha: "90e2444…", git_dirty: true, worktree_hash: "3fa9c1d2e4b5" });
+ * // "90e2444 + uncommitted changes (3fa9c1…)"
+ * ```
+ */
+export declare function formatBuild(build: BuildMetadata): string;
+/**
+ * A run viewport as one line.
+ *
+ * @example
+ * ```ts
+ * formatViewport({ device: "desktop", width: 1280, height: 800, source: "persona-tags" });
+ * // "desktop 1280×800 (from persona tags)"
+ * ```
+ */
+export declare function formatViewport(v: RunViewport): string;
+export interface StartRunOptions {
+    target?: string;
+    build?: string;
+    env?: string;
+    json?: boolean;
+    check?: boolean;
+    walker?: string;
+    judge?: string;
+    matcher?: string;
+}
+export declare function startRun(scenarioSlugArg: string | undefined, opts: StartRunOptions): Promise<void>;

package/dist/commands/status.d.ts

@@ -0,0 +1,3 @@
+export declare function status(opts: {
+    json?: boolean;
+}): Promise<void>;