@iamu-dev/iamu 0.2.0-beta.1 → 0.2.0-beta.2

package/dist/commands/evaluate.d.ts

@@ -1,30 +0,0 @@
-import { type CanonicalWalkthrough } from "@iamu-dev/protocol";
-/** What `verdicts.json` holds, as far as the report needs it. */
-export interface RecordedVerdicts {
-    verdicts: Array<{
-        human_test_id: string;
-        verdict: string;
-        reasoning: string;
-        grounding_step_ids: string[];
-        grounding_finding_ids: string[];
-    }>;
-    overall?: {
-        answer: string;
-        reasoning: string;
-    };
-}
-/**
- * A copy of `canonical` with the judge's verdicts filled in. canonical.json
- * itself never carries them (its writer is `complete`); the report does.
- */
-export declare function applyVerdicts(canonical: CanonicalWalkthrough, recorded: RecordedVerdicts): CanonicalWalkthrough;
-export declare function evaluate(runId: string, opts?: {
-    json?: boolean;
-}): Promise<void>;
-export declare function evaluateRecord(runId: string, opts: {
-    file: string;
-    json?: boolean;
-    yes?: boolean;
-    prompt?: boolean;
-    view?: boolean;
-}): Promise<void>;

package/dist/commands/findings.d.ts

@@ -1,7 +0,0 @@
-export declare function findings(opts?: {
-    open?: boolean;
-    resolved?: boolean;
-    dismissed?: boolean;
-    scenario?: string;
-    json?: boolean | string;
-}): Promise<void>;

package/dist/commands/init.d.ts

@@ -1,9 +0,0 @@
-export interface InitOptions {
-    name?: string;
-    yes?: boolean;
-    json?: boolean;
-}
-/**
- * Scaffold `iamu/` and install skills for the detected hosts.
- */
-export declare function init(opts?: InitOptions | string): Promise<void>;

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

@@ -1,59 +0,0 @@
-import { type GuidanceRule, type RevisitPlace } from "@iamu-dev/local-store";
-import { type RunViewport } 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;
-}
-/**
- * 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/list.d.ts

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

package/dist/commands/match.d.ts

@@ -1,12 +0,0 @@
-/**
- * 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;
-}): Promise<void>;
-/** Record the matcher's answer and re-derive the run's delta and report. */
-export declare function matchRecord(runId: string, opts: {
-    file: string;
-    json?: boolean;
-}): Promise<void>;

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

@@ -1,10 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-export interface NewEntityOptions {
-    name: string;
-    slug?: string;
-    description?: string;
-    role?: string;
-    disposition?: string;
-    outline?: string;
-    persona?: string;
-    url?: string;
-    authority?: string;
-    /** Scenario start path, e.g. /en/episodes/1. */
-    entry?: string;
-    json?: boolean;
-}
-export declare function newEntity(type: string, opts: NewEntityOptions): Promise<void>;

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

@@ -1,19 +0,0 @@
-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;
-    json?: boolean;
-}
-export declare function newFinding(opts: NewFindingOptions): Promise<void>;

package/dist/commands/open.d.ts

@@ -1,8 +0,0 @@
-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

@@ -1,17 +0,0 @@
-/**
- * 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/prune.d.ts

@@ -1,11 +0,0 @@
-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

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

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

@@ -1,5 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

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

package/dist/commands/serve.d.ts

@@ -1,11 +0,0 @@
-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/skills.d.ts

@@ -1,34 +0,0 @@
-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

@@ -1,49 +0,0 @@
-import { type BuildMetadata, type RunViewport, type ScenarioFrontmatter } from "@iamu-dev/protocol";
-/**
- * The URL a run starts at: `--target` (or the scenario's `target_url`)
- * 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">): {
-    url: string;
-} | {
-    error: string;
-};
-/**
- * Fast preflight probe to check if the target URL answers HTTP requests.
- * Times out quickly (default: 1000ms) to avoid stalling walkthrough initialization.
- */
-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;
-}
-export declare function startRun(scenarioSlug: string, opts: StartRunOptions): Promise<void>;

package/dist/commands/status.d.ts

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

package/dist/commands/step-numbering.d.ts

@@ -1,87 +0,0 @@
-/**
- * A step number claimed on disk. The file at `stepPath` exists (empty)
- * until the caller overwrites it with the step, or calls `release()`.
- *
- * @public
- */
-export interface StepReservation {
-    /** The reserved 1-based step number. */
-    stepNumber: number;
-    /** Absolute path of the reserved `NNN.json`. */
-    stepPath: string;
-    /** Give the number back — removes the placeholder file. Never throws. */
-    release(): Promise<void>;
-}
-/**
- * The file name for a step number: `7` → `"007.json"`.
- *
- * @param stepNumber - 1-based step number.
- * @returns The zero-padded file name.
- *
- * @example
- * ```ts
- * stepFileName(7); // "007.json"
- * ```
- *
- * @public
- */
-export declare function stepFileName(stepNumber: number): string;
-/**
- * The step-limit error message shared by `iamu step` and
- * `iamu browse step`.
- *
- * @param maxSteps - The limit that was hit.
- * @param runId - The run being recorded into.
- * @returns A message naming the limit and both ways out.
- *
- * @example
- * ```ts
- * throw new Error(stepLimitMessage(50, runId));
- * ```
- *
- * @public
- */
-export declare function stepLimitMessage(maxSteps: number, runId: string): string;
-/**
- * The number the next step would get (highest recorded + 1), without
- * claiming it. Use for an early "would this exceed the limit?" check;
- * only {@link reserveStepFile} makes the number yours.
- *
- * @param stepsDir - Absolute path of `<runDir>/steps`.
- * @returns The next free step number (1 when the directory is empty or missing).
- *
- * @example
- * ```ts
- * if ((await peekNextStepNumber(stepsDir)) > maxSteps) fail("limit");
- * ```
- *
- * @public
- */
-export declare function peekNextStepNumber(stepsDir: string): Promise<number>;
-/**
- * Claim the next step number by exclusively creating its `NNN.json`.
- * On `EEXIST` (another writer won that number) it moves to the next
- * one, so N concurrent callers end up with N distinct files.
- *
- * @param stepsDir - Absolute path of `<runDir>/steps` (must exist).
- * @param limit - `maxSteps` cap and the `runId` named in the error.
- * @returns The reservation; overwrite `stepPath` with the step or `release()` it.
- * @throws Error with {@link stepLimitMessage} when the next number exceeds `maxSteps`.
- *
- * @example
- * ```ts
- * const r = await reserveStepFile(stepsDir, { maxSteps: 50, runId });
- * try {
- *   await writeStep(runDir, { ...step, step_number: r.stepNumber });
- * } catch (err) {
- *   await r.release();
- *   throw err;
- * }
- * ```
- *
- * @public
- */
-export declare function reserveStepFile(stepsDir: string, limit: {
-    maxSteps: number;
-    runId: string;
-}): Promise<StepReservation>;

package/dist/commands/step.d.ts

@@ -1,95 +0,0 @@
-import { type RunStep } from "@iamu-dev/protocol";
-/** Steps a run may record before the circuit breaker trips. */
-export declare const DEFAULT_MAX_STEPS = 50;
-/**
- * The step limit to enforce: `val` (from `--max-steps`) when it is a
- * positive integer, else `IAMU_MAX_STEPS`, else {@link DEFAULT_MAX_STEPS}.
- *
- * @param val - The raw `--max-steps` value, if any.
- * @returns A positive step limit.
- *
- * @example
- * ```ts
- * parseMaxSteps("20"); // 20
- * parseMaxSteps(undefined); // 50, unless IAMU_MAX_STEPS is set
- * ```
- *
- * @public
- */
-export declare function parseMaxSteps(val?: string | number): number;
-/** What {@link recordStep} records. */
-export interface RecordStepInput {
-    projectRoot: string;
-    runId: string;
-    action: string;
-    note?: string | null;
-    /** Path of an existing screenshot to copy in; a missing file is an error. */
-    shot?: string | null;
-    url?: string | null;
-    surface?: string | null;
-    grounding?: string | null;
-    timestamp?: string;
-    maxSteps?: string | number;
-    extra?: Record<string, unknown>;
-}
-/** What {@link recordStep} wrote. */
-export interface RecordStepResult {
-    step: RunStep;
-    stepPath: string;
-    screenshotPath: string | null;
-}
-/**
- * Record a single step into `<runDir>/steps/NNN.json`.
- *
- * The step number is reserved with an exclusive create (see
- * {@link reserveStepFile}), so concurrent calls get distinct numbers
- * instead of overwriting each other; the content is then written
- * atomically (temp file + rename). A `shot` is copied into
- * `<runDir>/screenshots/step-N.png`; a `shot` that is not an existing
- * file is an error — a step never points at a screenshot that is not there.
- *
- * @param input - The run, the action, and optional evidence.
- * @returns The validated step, its file, and the copied screenshot path.
- * @throws Error when the run is missing, `shot` is not a file, or the step limit is reached.
- *
- * @example
- * ```ts
- * const { step } = await recordStep({
- *   projectRoot,
- *   runId,
- *   action: "Clicked checkout",
- *   shot: "./shot.png",
- * });
- * console.log(step.step_number);
- * ```
- *
- * @public
- */
-export declare function recordStep(input: RecordStepInput): Promise<RecordStepResult>;
-/** Options for `iamu step`. */
-export interface StepOptions {
-    run?: string;
-    action: string;
-    note?: string;
-    shot?: string;
-    url?: string;
-    surface?: string;
-    grounding?: string;
-    maxSteps?: string | number;
-    json?: boolean;
-}
-/**
- * `iamu step [run-id]` — record one step via {@link recordStep} and
- * print it (one JSON document with `--json`). Errors set exit code 1.
- *
- * @param runArg - Positional run ID; falls back to `opts.run`.
- * @param opts - Parsed CLI options.
- *
- * @example
- * ```ts
- * await stepCommand("run-123", { action: "Clicked checkout", json: true });
- * ```
- *
- * @public
- */
-export declare function stepCommand(runArg: string | undefined, opts: StepOptions): Promise<void>;

package/dist/commands/sync.d.ts

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

package/dist/commands/triage.d.ts

@@ -1,21 +0,0 @@
-export interface TriageOptions {
-    status: string;
-    /** Why — the triager's words. Required when dismissing. */
-    note?: string;
-    /** Dismiss reason: not_relevant | walker_error | duplicate. */
-    reason?: string;
-    /** Guidance rule text; defaults to "Don't report: <title>". */
-    rule?: string;
-    /** Where the guidance rule applies. Default: project. */
-    scope?: string;
-    /** `false` (`--no-guidance`): dismiss without writing a guidance rule. */
-    guidance?: boolean;
-    json?: boolean;
-}
-/**
- * Set the triage status of one or more findings. Dismissing as
- * `not_relevant` or `walker_error` also writes a tester guidance rule
- * (`iamu/guidance/<slug>.md`) so later walks stop reporting the same
- * thing; several findings dismissed together share one rule.
- */
-export declare function triage(refs: string[], opts: TriageOptions): Promise<void>;

package/dist/commands/update.d.ts

@@ -1,4 +0,0 @@
-export interface UpdateOptions {
-    host?: string;
-}
-export declare function update(opts?: UpdateOptions): Promise<void>;

package/dist/commands/validate.d.ts

@@ -1,8 +0,0 @@
-export declare function validate(filePath: string | undefined, opts: {
-    run?: string;
-    all?: boolean;
-    type?: string;
-    json?: boolean;
-    fix?: boolean;
-    dryRun?: boolean;
-}): Promise<void>;

package/dist/commands/view-results.d.ts

@@ -1,9 +0,0 @@
-export declare function openBrowserResults(projectRoot: string, runId?: string): Promise<void>;
-export interface PromptViewResultsOptions {
-    prompt?: boolean;
-    yes?: boolean;
-    view?: boolean;
-    json?: boolean;
-    runId?: string;
-}
-export declare function promptViewResults(projectRoot: string, opts?: PromptViewResultsOptions): Promise<void>;

package/dist/index.d.ts

@@ -1,9 +0,0 @@
-/**
- * \@iamu-dev/iamu
- *
- * Scenario-driven development — test your product as realistic personas.
- *
- * @packageDocumentation
- */
-export { registerAllCommands } from "./commands/register.js";
-export { setupProcessHandlers, registerSigintCleanup } from "./ui/panic.js";

package/dist/sync-mcp/fatal.d.ts

@@ -1,42 +0,0 @@
-/**
- * Fatal-error reporting for the sync MCP server entry point.
- *
- * stdout is the MCP stdio transport, so a diagnostic printed there would
- * corrupt the protocol stream. Everything here writes to stderr only.
- */
-/** Side effects a fatal report needs, injectable so it can be tested. */
-export interface FatalDeps {
-    /** Write a diagnostic line — stderr, never stdout. */
-    writeErr: (text: string) => void;
-    /** Terminate the process with the given exit code. */
-    exit: (code: number) => void;
-}
-/**
- * Describe a fatal error, with its stack when there is one.
- *
- * @example
- * ```ts
- * formatFatal("uncaughtException", new Error("boom"));
- * // "iamu sync-server: fatal uncaughtException: boom\n…stack…\n"
- * ```
- */
-export declare function formatFatal(kind: string, err: unknown): string;
-/**
- * Report a fatal error on stderr and exit non-zero.
- *
- * @example
- * ```ts
- * handleFatal("uncaughtException", err, deps);
- * ```
- */
-export declare function handleFatal(kind: string, err: unknown, deps?: FatalDeps): void;
-/**
- * Install `uncaughtException` / `unhandledRejection` handlers that log
- * to stderr before exiting, instead of dying silently with code 1.
- *
- * @example
- * ```ts
- * installFatalHandlers();
- * ```
- */
-export declare function installFatalHandlers(deps?: FatalDeps): void;