@iamu-dev/iamu 0.0.0-stage → 0.2.0-beta.10

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

@@ -0,0 +1,28 @@
+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;
+    /** Structural tension driving the situation (outline only). */
+    tension?: string;
+    /** Human-test question to evaluate at walkthrough completion (outline only). */
+    humanTest?: string | 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,19 @@
+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

@@ -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/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/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,54 @@
+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;
+};
+/**
+ * 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;
+    walker?: string;
+    judge?: string;
+    matcher?: string;
+}
+export declare function startRun(scenarioSlug: string, opts: StartRunOptions): Promise<void>;

package/dist/commands/status.d.ts

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

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

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

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

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

package/dist/commands/triage.d.ts

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

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

package/dist/commands/validate.d.ts

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

@@ -0,0 +1,9 @@
+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/eval/gemini-eval-cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI Entrypoint: Autonomous Gemini Walker Benchmark Suite
+ *
+ * Runs Gemini 2.5 Flash through the live iamu CLI walking prompt and tools,
+ * grading autonomous decisions against ground-truth contracts.
+ *
+ * Usage:
+ *   GEMINI_API_KEY=... pnpm eval:gemini
+ */
+export {};