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

package/dist/commands/browse.d.ts

@@ -18,6 +18,7 @@ export interface BrowseOptions {
     note?: string;
     surface?: string;
     maxSteps?: string | number;
+    stepFile?: string;
     json?: boolean;
 }
 interface BrowseState {
@@ -126,6 +127,19 @@ export interface PageResult {
     /** Absolute path of the screenshot written, or null when none was asked for. */
     screenshot: string | null;
 }
+/**
+ * Wait for the page to visually settle before taking a screenshot.
+ *
+ * SPA actions (state updates, CSS transitions, element mounts) do not trigger
+ * a navigation, so `domcontentloaded` returns immediately. Rather than a blunt
+ * hardcoded sleep, this flushes the rendering pipeline via double
+ * `requestAnimationFrame` and waits for in-flight CSS/web animations to finish,
+ * bounded by `maxWaitMs` (default 300ms) to ensure it never hangs on continuous
+ * animations like spinners.
+ *
+ * @public
+ */
+export declare function waitForVisualStability(page: Page, maxWaitMs?: number): Promise<void>;
 /**
  * Attach to the running browser, run `fn` on the page the persona is
  * on, optionally screenshot it, and return where the page is. Prints

package/dist/commands/complete.d.ts

@@ -9,6 +9,7 @@ export interface CompleteOptions {
     prompt?: boolean;
     view?: boolean;
     strictProvenance?: boolean;
+    push?: boolean;
 }
 /** Non-fatal observations made while completing, reported after assembly. */
 export interface CompletionExtras {

package/dist/commands/credentials.d.ts

@@ -8,7 +8,7 @@ import { IamuConfigError } from "@iamu-dev/protocol";
  * const url = config.cloud_api_url ?? DEFAULT_API_URL;
  * ```
  */
-export declare const DEFAULT_API_URL = "https://api.iamu.dev";
+export declare const DEFAULT_API_URL = "https://app.iamu.dev";
 /**
  * Stored credentials, keyed by API URL. Values are left `unknown` on
  * purpose: the file is user-editable, so every reader narrows.

package/dist/commands/doctor.d.ts

@@ -1,5 +1,5 @@
 export interface DoctorCheck {
-    category: "runtime" | "browser" | "project" | "agent" | "cloud";
+    category: "runtime" | "browser" | "project" | "agent" | "cloud" | "target";
     name: string;
     status: "ok" | "warn" | "error";
     message: string;
@@ -18,7 +18,16 @@ export interface DoctorResult {
 export declare function checkPortAvailable(port: number): Promise<boolean>;
 /** Check CDP responsiveness on a port */
 export declare function checkCdpResponsive(port: number): Promise<boolean>;
-export declare function runDoctorChecks(projectRoot?: string): Promise<DoctorResult>;
+export declare function checkTargetHealth(targetUrl: string): Promise<DoctorCheck[]>;
+export declare function checkProjectHarnesses(projectRoot: string): Promise<DoctorCheck[]>;
+export declare function checkProjectTestabilityContract(projectRoot: string): Promise<{
+    checks: DoctorCheck[];
+    targetUrl?: string;
+}>;
+export declare function runDoctorChecks(projectRoot?: string, opts?: {
+    target?: string;
+}): Promise<DoctorResult>;
 export declare function doctor(opts?: {
     json?: boolean;
+    target?: string;
 }): Promise<void>;

package/dist/commands/evaluate.d.ts

@@ -20,6 +20,7 @@ export interface RecordedVerdicts {
 export declare function applyVerdicts(canonical: CanonicalWalkthrough, recorded: RecordedVerdicts): CanonicalWalkthrough;
 export declare function evaluate(runId: string, opts?: {
     json?: boolean;
+    promptFile?: string;
 }): Promise<void>;
 export declare function evaluateRecord(runId: string, opts: {
     file: string;
@@ -27,4 +28,5 @@ export declare function evaluateRecord(runId: string, opts: {
     yes?: boolean;
     prompt?: boolean;
     view?: boolean;
+    push?: boolean;
 }): Promise<void>;

package/dist/commands/explore-crawl.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The read-only crawl behind `iamu explore`.
+ *
+ * Breadth-first from the start URL: on every surface, try every visible
+ * link and button once, and see where it leads. A surface is a page
+ * (keyed by its templated URL, see `explorePlaceKey`) or a view a click
+ * switched to on the same URL (keyed by its headings). Every surface is
+ * reached by replaying its path from the start, so the crawl does not
+ * depend on what the previous click left behind, and two crawls of one
+ * build should produce the same map.
+ *
+ * Read-only is enforced twice:
+ * - Controls whose name or link reads like a write (delete, pay, send,
+ *   save, log out …), form submits, downloads and other origins are
+ *   never clicked. Nothing is typed into a field.
+ * - Every request that is not GET/HEAD/OPTIONS is aborted before it
+ *   leaves the browser, and recorded on the action that caused it.
+ *
+ * Dialogs are dismissed (`confirm()` answers no) and popups closed.
+ * WebSocket messages are not guarded; a page controlled by a service
+ * worker (whose requests the guard cannot see) is refused.
+ */
+import { type ExploreBudget, type ExploreStats, type ExploreSurface } from "@iamu-dev/local-store";
+import type { Page } from "playwright-core";
+/**
+ * Options for {@link crawl}.
+ *
+ * @public
+ */
+export interface CrawlOptions {
+    startUrl: string;
+    budget: ExploreBudget;
+    /** Extra patterns: a control whose name or link matches is never tried. */
+    deny?: RegExp[];
+    /** Longest wait for the page to settle after an action. */
+    settleMs?: number;
+    /** One line per new surface, for progress output. */
+    log?: (line: string) => void;
+}
+/**
+ * What {@link crawl} found.
+ *
+ * @public
+ */
+export interface CrawlResult {
+    surfaces: ExploreSurface[];
+    stats: ExploreStats;
+}
+/**
+ * Crawl the product read-only from `opts.startUrl`.
+ *
+ * @param page - A page of its own; the crawl navigates it freely and
+ *   installs a request guard on it.
+ * @param opts - Start URL, budget, extra deny patterns.
+ * @returns The surfaces found and counts.
+ *
+ * @example
+ * ```ts
+ * const { surfaces, stats } = await crawl(page, {
+ *   startUrl: "http://localhost:3000/",
+ *   budget: { max_surfaces: 40, max_actions: 300, max_depth: 6 },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function crawl(page: Page, opts: CrawlOptions): Promise<CrawlResult>;

package/dist/commands/explore.d.ts

@@ -0,0 +1,52 @@
+/** Parsed options for `iamu explore [url]`. */
+export interface ExploreOptions {
+    maxSurfaces?: string;
+    maxActions?: string;
+    maxDepth?: string;
+    deny?: string[];
+    viewport?: string;
+    attach?: boolean;
+    json?: boolean;
+}
+/**
+ * `iamu explore [url]`: crawl the product read-only and write a map.
+ *
+ * @example
+ * ```ts
+ * await exploreRun("http://localhost:3000/", { maxSurfaces: "20" });
+ * ```
+ */
+export declare function exploreRun(url: string | undefined, opts: ExploreOptions): Promise<void>;
+/**
+ * `iamu explore list`.
+ *
+ * @example
+ * ```ts
+ * await exploreList({ json: true });
+ * ```
+ */
+export declare function exploreList(opts: {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * `iamu explore coverage [map]`.
+ *
+ * @example
+ * ```ts
+ * await exploreCoverageCommand(undefined, {});
+ * ```
+ */
+export declare function exploreCoverageCommand(mapId: string | undefined, opts: {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * `iamu explore diff [a] [b]` — default: the two latest maps.
+ *
+ * @example
+ * ```ts
+ * await exploreDiffCommand(undefined, undefined, { json: true });
+ * ```
+ */
+export declare function exploreDiffCommand(a: string | undefined, b: string | undefined, opts: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/init.d.ts

@@ -1,7 +1,14 @@
+import type { HostAdapter } from "../adapters/types.js";
+/**
+ * The setup skill as the user will see it. With the Iamu plugin enabled,
+ * Claude Code has `/iamu:init` and no `iamu-setup`.
+ */
+export declare function setupCommand(projectRoot: string, hosts: HostAdapter[]): string;
 export interface InitOptions {
     name?: string;
     yes?: boolean;
     json?: boolean;
+    cloud?: boolean;
 }
 /**
  * Scaffold `iamu/` and install skills for the detected hosts.

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

@@ -1,5 +1,5 @@
 import { type GuidanceRule, type RevisitPlace } from "@iamu-dev/local-store";
-import { type RunViewport } from "@iamu-dev/protocol";
+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 {
@@ -33,7 +33,17 @@ interface WalkerPromptParts {
     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

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

@@ -4,6 +4,7 @@
  */
 export declare function match(runId: string, opts?: {
     json?: boolean;
+    promptFile?: string;
 }): Promise<void>;
 /** Record the matcher's answer and re-derive the run's delta and report. */
 export declare function matchRecord(runId: string, opts: {

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

@@ -2,14 +2,27 @@ 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/start-run.d.ts

@@ -1,10 +1,12 @@
 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`)
+ * 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">): {
+export declare function resolveStartUrl(target: string | undefined, scenario: Pick<ScenarioFrontmatter, "target_url" | "entry_path">, fallbackTarget?: string | null): {
     url: string;
 } | {
     error: string;
@@ -45,5 +47,8 @@ export interface StartRunOptions {
     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/step.d.ts

@@ -37,6 +37,7 @@ export interface RecordStepResult {
     step: RunStep;
     stepPath: string;
     screenshotPath: string | null;
+    cancelled?: boolean;
 }
 /**
  * Record a single step into `<runDir>/steps/NNN.json`.

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 {};