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

package/dist/commands/browse-actions.d.ts

@@ -1,56 +0,0 @@
-/**
- * The page actions `iamu browse` can perform — one table shared by the
- * direct commands (`iamu browse click …`) and by `iamu browse step
- * click …`, so the two can never drift apart.
- */
-import type { Page } from "playwright-core";
-/** Options an action reads. */
-export interface ActionOptions {
-    /** Pick the nth (0-based) match instead of the first. */
-    nth?: string;
-    /** Press Enter after fill/select. */
-    submit?: boolean;
-}
-/**
- * One page action: how it is called, what it targets (for the "nothing
- * matches" error), and what it does.
- *
- * @public
- */
-export interface PageAction {
-    /** Call shape after `iamu browse`, e.g. `click <role> "<name>" [--nth N]`. */
-    usage: string;
-    /** Positional arguments required after the action name. */
-    minArgs: number;
-    /** What the action looks for, named the way the error message says it. */
-    target?: (args: string[]) => string;
-    run(page: Page, args: string[], opts: ActionOptions): Promise<void>;
-}
-/**
- * Every page action, by name. `shot` does nothing to the page; the
- * screenshot is taken after any action when one is asked for.
- *
- * @example
- * ```ts
- * const action = PAGE_ACTIONS.click;
- * if (args.length >= action.minArgs) await action.run(page, args, {});
- * ```
- *
- * @public
- */
-export declare const PAGE_ACTIONS: Readonly<Record<string, PageAction>>;
-/**
- * Look up a page action by name, own properties only (so `toString`
- * and friends are not actions).
- *
- * @param name - The action name as typed.
- * @returns The action, or undefined.
- *
- * @example
- * ```ts
- * findPageAction("click")?.usage; // 'click <role> "<name>" [--nth N]'
- * ```
- *
- * @public
- */
-export declare function findPageAction(name: string): PageAction | undefined;

package/dist/commands/browse-driver.d.ts

@@ -1,117 +0,0 @@
-import type { Page } from "playwright-core";
-/** A page size in CSS pixels. */
-export interface Size {
-    width: number;
-    height: number;
-}
-/**
- * The page a command acts on, plus how to let go of it. Detaching
- * disconnects from the browser; it never closes the page.
- *
- * @public
- */
-export interface AttachedPage {
-    page: Page;
-    detach(): Promise<void>;
-}
-/**
- * What `iamu browse` needs from the machine and the browser — the real
- * one spawns Chrome and speaks CDP; tests pass a fake.
- *
- * @public
- */
-export interface BrowserDriver {
-    /** Is a browser answering CDP on this port? Must not hang. */
-    isRunning(port: number): Promise<boolean>;
-    /** Launch Chrome detached with these arguments; returns its PID. */
-    launch(chrome: string, args: string[]): number | undefined;
-    /**
-     * Fit the running window's content area to the viewport
-     * (`Browser.setWindowBounds`), so a person watching sees the
-     * persona's screen. Best effort: a window cannot be phone-narrow, and
-     * every command emulates the stored viewport on its page anyway.
-     */
-    resize(port: number, viewport: Size | null): Promise<void>;
-    /** Attach over CDP to the page the persona is on. Throws when nothing answers. */
-    attach(port: number): Promise<AttachedPage>;
-    /** Ask the browser on this port to close (`Browser.close`). Best effort. */
-    closeBrowser(port: number): Promise<void>;
-    /** The full command line of `pid`, or null when it is gone or cannot be read. */
-    commandLine(pid: number): Promise<string | null>;
-    /** Send SIGTERM to `pid`. Never throws. */
-    kill(pid: number): void;
-}
-/** How long a CDP liveness probe may take before the port counts as dead. */
-export declare const CDP_PROBE_TIMEOUT_MS = 1000;
-/**
- * Is a browser answering CDP on `port`? A process that accepts the
- * connection but never answers (a hung Chrome, something else on the
- * port) counts as not running once `timeoutMs` passes.
- *
- * @param port - CDP port on 127.0.0.1.
- * @param timeoutMs - Give up after this long.
- * @returns True when `/json/version` answers 2xx in time.
- *
- * @example
- * ```ts
- * if (!(await probeCdp(9333))) console.log("no browser");
- * ```
- *
- * @public
- */
-export declare function probeCdp(port: number, timeoutMs?: number): Promise<boolean>;
-/**
- * The command line of a running process, read without a shell:
- * `/proc/<pid>/cmdline` on Linux, else `ps -ww -o args= -p <pid>`.
- * Windows has no equivalent we trust, so it answers null there — and
- * callers then leave the process alone.
- *
- * @param pid - Process ID to inspect.
- * @param platform - Defaults to `process.platform`.
- * @returns The arguments joined by spaces, or null.
- *
- * @example
- * ```ts
- * const cmd = await readProcessCommandLine(12345);
- * ```
- *
- * @public
- */
-export declare function readProcessCommandLine(pid: number, platform?: NodeJS.Platform): Promise<string | null>;
-/**
- * Was this command line launched with exactly this `--user-data-dir`?
- * The profile directory is ours alone, so a match means the PID is the
- * Chrome `iamu browse start` launched, not a process that reused its PID.
- *
- * @param commandLine - From {@link readProcessCommandLine}.
- * @param profileDir - The `--user-data-dir` we launched with.
- * @returns True only on an exact flag match.
- *
- * @example
- * ```ts
- * isOurBrowser("chrome --user-data-dir=/h/.iamu/browse/profile", "/h/.iamu/browse/profile"); // true
- * ```
- *
- * @public
- */
-export declare function isOurBrowser(commandLine: string | null, profileDir: string): boolean;
-/**
- * SIGTERM `pid` only if it is verifiably our Chrome (see
- * {@link isOurBrowser}). PIDs get reused; anything else is left alone
- * and Chrome's own profile lock guards a second launch.
- *
- * @param pid - PID recorded in the browse state.
- * @param profileDir - The `--user-data-dir` it was launched with.
- * @param driver - Supplies `commandLine` and `kill`.
- * @returns True when the process was signalled.
- *
- * @example
- * ```ts
- * await reapBrowser(state.pid, profileDir, cdpDriver);
- * ```
- *
- * @public
- */
-export declare function reapBrowser(pid: number, profileDir: string, driver: Pick<BrowserDriver, "commandLine" | "kill">): Promise<boolean>;
-/** The real driver: spawns Chrome and speaks CDP through playwright-core. */
-export declare const cdpDriver: BrowserDriver;

package/dist/commands/browse.d.ts

@@ -1,156 +0,0 @@
-import type { Page } from "playwright-core";
-import { type BrowserDriver, type Size } from "./browse-driver.js";
-export type { BrowserDriver } from "./browse-driver.js";
-/** Parsed options for `iamu browse <command>`. */
-export interface BrowseOptions {
-    shot?: string;
-    nth?: string;
-    submit?: boolean;
-    full?: boolean;
-    viewport?: string;
-    width?: string;
-    height?: string;
-    headless?: boolean;
-    port?: string | number;
-    /** `start`: size the browser for this run's persona. */
-    run?: string;
-    action?: string;
-    note?: string;
-    surface?: string;
-    maxSteps?: string | number;
-    json?: boolean;
-}
-interface BrowseState {
-    port: number;
-    viewport: Size | null;
-    pid?: number;
-    headless?: boolean;
-}
-/**
- * The state `iamu browse start` left in `~/.iamu/browse/state.json`, or
- * null when no browser was started (or the file is unreadable).
- *
- * @example
- * ```ts
- * const state = readBrowseState();
- * if (state) console.log(`CDP on :${state.port}`);
- * ```
- *
- * @public
- */
-export declare function readBrowseState(): BrowseState | null;
-/**
- * Parse `"390x844"` into a size.
- *
- * @param value - `WxH`, 2–5 digits each.
- * @returns The size, or null when absent or malformed.
- *
- * @example
- * ```ts
- * parseViewport("390x844"); // { width: 390, height: 844 }
- * ```
- *
- * @public
- */
-export declare function parseViewport(value: string | undefined): Size | null;
-/**
- * The installed Chrome/Chromium to drive: `IAMU_BROWSER`, else the
- * usual install location for this platform.
- *
- * @example
- * ```ts
- * const chrome = findChrome();
- * if (!chrome) console.error("Install Chrome or set IAMU_BROWSER");
- * ```
- *
- * @public
- */
-export declare function findChrome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (p: string) => boolean): string | null;
-/**
- * Should `start` launch without a window? `--headless` wins, then
- * `IAMU_HEADLESS`, then CI or a Linux box with no `DISPLAY`.
- *
- * @example
- * ```ts
- * isHeadlessEnvironment({ headless: true }); // true
- * ```
- *
- * @public
- */
-export declare function isHeadlessEnvironment(opts?: BrowseOptions): boolean;
-/**
- * Should Chrome run with `--no-sandbox`? Only when it cannot start
- * otherwise — as root (Chrome refuses to sandbox as root, typical in
- * containers) — or when explicitly asked via `IAMU_BROWSE_NO_SANDBOX=1`.
- * Being headless or in CI is not a reason: the sandbox is what keeps a
- * page the persona visits away from the machine.
- *
- * @param env - Defaults to `process.env`.
- * @param uid - Effective user ID; defaults to `process.getuid()` (undefined on Windows).
- * @returns True when `--no-sandbox` should be passed.
- *
- * @example
- * ```ts
- * shouldDisableSandbox({ IAMU_BROWSE_NO_SANDBOX: "1" }, 1000); // true
- * shouldDisableSandbox({ CI: "true" }, 1000); // false
- * ```
- *
- * @public
- */
-export declare function shouldDisableSandbox(env?: NodeJS.ProcessEnv, uid?: number | undefined): boolean;
-/**
- * Start the browser, or converge the one already running: a running
- * browser is reused, and resized when the requested viewport differs
- * from the one it was started with — never silently left at another
- * persona's size.
- *
- * A PID left by an earlier `start` whose CDP no longer answers is
- * terminated only when its command line shows our `--user-data-dir`;
- * a PID the OS has since handed to another process is left alone.
- *
- * @param opts - `viewport`, `run`, `port`, `width`, `height`, `headless`, `json`.
- * @param driver - Machine/browser seam; tests pass a fake.
- *
- * @example
- * ```ts
- * await start({ viewport: "390x844" });
- * ```
- *
- * @public
- */
-export declare function start(opts: BrowseOptions, driver?: BrowserDriver): Promise<void>;
-/** Where the page ended up after an action. */
-export interface PageResult {
-    url: string;
-    title: string;
-    /** Absolute path of the screenshot written, or null when none was asked for. */
-    screenshot: string | null;
-}
-/**
- * Attach to the running browser, run `fn` on the page the persona is
- * on, optionally screenshot it, and return where the page is. Prints
- * nothing on success — the caller decides the output shape. Detaching
- * never closes the page.
- *
- * @public
- */
-export declare function withPage(opts: BrowseOptions, driver: BrowserDriver, fn: (page: Page) => Promise<void>, 
-/** What the action looks for, named for the error message. */
-target?: string): Promise<PageResult | null>;
-/**
- * `iamu browse <command> [args…]` — dispatch one browse subcommand.
- * Failures print to stderr and set exit code 1.
- *
- * @param command - `start`, `stop`, `step`, `snapshot`, `shot`, or a page action.
- * @param args - Positional arguments after the command.
- * @param opts - Parsed CLI options.
- * @param driver - Machine/browser seam; tests pass a fake.
- *
- * @example
- * ```ts
- * await browse("click", ["button", "Sign in"], { json: true });
- * ```
- *
- * @public
- */
-export declare function browse(command: string, args: string[], opts: BrowseOptions, driver?: BrowserDriver): Promise<void>;

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

@@ -1,27 +0,0 @@
-/** What happened to a run's cloud copy, as `--json` and the terminal show it. */
-export interface CloudRunInfo {
-    mirrored: boolean;
-    status: string;
-    skipped_reason?: string;
-    /** Dashboard URL — set only when the cloud holds this run. */
-    url?: string;
-}
-/**
- * Push one run to the cloud when the project is cloud-linked. Returns
- * `undefined` for a local-only project, so callers print nothing.
- *
- * Called by every command that changes what the run's cloud copy shows
- * (`complete`, `evaluate-record`): offering "Open in Iamu Cloud" after a
- * local-only write would open a stale report.
- */
-export declare function pushRunToCloud(projectRoot: string, runId: string): Promise<CloudRunInfo | undefined>;
-/** Project dashboard URL, or `null` for a local-only project. */
-export declare function projectDashboardUrl(projectRoot: string): Promise<string | null>;
-/**
- * Dashboard URL of a run this machine already pushed, or `null` when the
- * project is local-only or the run never reached the cloud. Reads local
- * sync tracking only — no network.
- */
-export declare function pushedRunUrl(projectRoot: string, runId: string): Promise<string | null>;
-/** Terminal lines for a run's cloud state; prints nothing when local-only. */
-export declare function printCloudRunInfo(info: CloudRunInfo | undefined): void;

package/dist/commands/complete.d.ts

@@ -1,131 +0,0 @@
-import { type JourneyDiff, type RevisitPlaceCoverage, type VerificationSummary, type WalkthroughManifest } from "@iamu-dev/local-store";
-import { type CanonicalWalkthrough, type RunViewport } from "@iamu-dev/protocol";
-import { type CloudRunInfo } from "./cloud-push.js";
-export interface CompleteOptions {
-    cwd?: string;
-    json?: boolean;
-    force?: boolean;
-    yes?: boolean;
-    prompt?: boolean;
-    view?: boolean;
-    strictProvenance?: boolean;
-}
-/** Non-fatal observations made while completing, reported after assembly. */
-export interface CompletionExtras {
-    revisit: RevisitReport | null;
-    viewportWarning: string | null;
-    codeWarning: string | null;
-    cloudInfo: CloudRunInfo | undefined;
-}
-/**
- * `iamu complete <run-id>`: assemble canonical.json + report.md, mark the
- * run completed, push it when cloud-linked and report the outcome.
- */
-export declare function complete(runId: string, opts?: CompleteOptions): Promise<void>;
-/**
- * The run's completion time. `--force` reassembles the report of a finished
- * run; the run still finished when it first completed. Re-stamping would
- * move every re-assembled run to "now", which breaks run ordering and
- * durations downstream.
- */
-export declare function pickCompletedAt(manifest: Pick<WalkthroughManifest, "completed_at">, now?: () => Date): string;
-/** The manifest with its status flipped to completed. */
-export declare function completedManifest(manifest: WalkthroughManifest, completedAt: string): WalkthroughManifest;
-/** Persist the completed manifest to disk atomically. */
-export declare function persistManifest(manifestPath: string, manifest: WalkthroughManifest, completedAt: string): Promise<WalkthroughManifest>;
-/** `complete --json` output: the canonical plus whichever extras exist. */
-export declare function completeJsonPayload(canonical: CanonicalWalkthrough, extras: CompletionExtras): Record<string, unknown>;
-/** Non-fatal provenance warnings; prints nothing for a clean audit. */
-export declare function printProvenanceWarnings(audit: ProvenanceAudit): void;
-/** Width and height from a PNG's IHDR chunk; null if it is not a PNG. */
-export declare function pngSize(head: Buffer): {
-    width: number;
-    height: number;
-} | null;
-/**
- * Is a screenshot `width` px wide consistent with a viewport `expected`
- * CSS px wide? At 1× within 20%; at a 2× or 3× device pixel ratio the
- * width is an exact multiple, so within 5% — wide enough for a scrollbar,
- * narrow enough that a 1280 px desktop shot never passes as a 3× phone.
- */
-export declare function screenshotFitsViewport(width: number, expected: number): boolean;
-/**
- * A warning when the run's first screenshot is not the width of the
- * device its persona uses — the browser was left at another persona's
- * size. Null when the run recorded no viewport, has no screenshots, or
- * the sizes agree. Never fatal.
- */
-export declare function screenshotSizeWarning(runDirPath: string, viewport: RunViewport | null): Promise<string | null>;
-export interface ProvenanceAudit {
-    verified: boolean;
-    warnings: string[];
-    step_count: number;
-    duration_seconds: number | null;
-    avg_step_interval_seconds: number | null;
-    uniform_intervals: boolean;
-}
-/**
- * Audit steps for suspicious timing anomalies that indicate programmatic batch
- * generation (scripts, mocks) rather than interactive human/LLM persona execution.
- */
-export declare function auditStepProvenance(steps: Array<{
-    timestamp?: string;
-    action?: string;
-    step_number?: number;
-}>): ProvenanceAudit;
-/** Strictly validate runtime canonical structure against the protocol schema. */
-export declare function validateCanonicalWalkthrough(canonical: unknown): CanonicalWalkthrough;
-/**
- * Read recorded judge verdicts (if present) and overlay them onto the canonical
- * walkthrough for report markdown rendering.
- */
-export declare function applyRecordedVerdicts(canonical: CanonicalWalkthrough, runDirPath: string): Promise<CanonicalWalkthrough>;
-/** Persist canonical.json to disk atomically. */
-export declare function persistCanonical(runDirPath: string, canonical: CanonicalWalkthrough): Promise<string>;
-/** Persist report.md to disk atomically. */
-export declare function persistReport(runDirPath: string, canonical: CanonicalWalkthrough): Promise<string>;
-/**
- * Build canonical.json (with the verification delta) and report.md for a
- * run. The report keeps any verdicts already recorded by
- * `evaluate-record`, so re-assembling after the judge (`--force`,
- * `match-record`) does not drop them.
- */
-export declare function assembleRun(projectRoot: string, runId: string, manifest: WalkthroughManifest, completedAt: string): Promise<{
-    canonical: CanonicalWalkthrough;
-    verification: VerificationSummary | null;
-    journeyDiff: JourneyDiff | null;
-    canonicalWithVerification: CanonicalWalkthrough & {
-        provenance_audit?: ProvenanceAudit;
-    };
-    canonicalPath: string;
-    reportPath: string;
-}>;
-/** One requested place, whether the run reached it, and what awaits there. */
-export type RevisitReportPlace = RevisitPlaceCoverage & {
-    findings: Array<{
-        id: string;
-        title: string;
-    }>;
-};
-/** Coverage of the run's places to pass through, with finding titles. */
-export interface RevisitReport {
-    requested: number;
-    reached: number;
-    places: RevisitReportPlace[];
-}
-/**
- * Did the run reach the places `start-run` asked it to pass through
- * (manifest `revisit`)? Null when it asked for none. Local only: the
- * cloud manifest has no field for it. Titles are for the person reading
- * this output — the walker never saw them.
- */
-export declare function revisitReport(projectRoot: string, runId: string, manifest: WalkthroughManifest): Promise<RevisitReport | null>;
-/** Print "Re-check places: reached N of M — not reached: …". */
-export declare function printRevisit(r: RevisitReport): void;
-/**
- * Print the delta against this scenario's previous completed run. Its
- * counts are relative to that one run — "new" here means "not in that
- * run", which is not the matcher's "first seen" (never recorded before)
- * — so the heading says what it compares with.
- */
-export declare function printVerification(verification: VerificationSummary): void;

package/dist/commands/completion.d.ts

@@ -1,2 +0,0 @@
-import type { Command } from "commander";
-export declare function completion(program: Command, shell?: string): void;

package/dist/commands/context.d.ts

@@ -1,58 +0,0 @@
-import { readEntity } from "@iamu-dev/local-store";
-import type { EntityType, ProjectConfig } from "@iamu-dev/protocol";
-export interface ProjectContext {
-    projectRoot: string;
-    config: ProjectConfig;
-}
-export interface CloudContext extends ProjectContext {
-    apiKey: string;
-    apiUrl: string;
-}
-export declare function commandError(message: string, opts?: {
-    json?: boolean | string;
-}): void;
-/**
- * Resolve a run directory, reporting an unusable run id as a command
- * error (message + exit code 1) instead of letting it reach the
- * filesystem. Returns `null` once the error has been reported.
- */
-export declare function resolveRunDir(projectRoot: string, runId: string, opts?: {
-    json?: boolean;
-}): string | null;
-/**
- * Last-resort handler for a rejection that escaped a command action.
- * Prints one line — JSON-shaped when the invocation carried `--json` —
- * and leaves a non-zero exit code behind. Without it, Commander's
- * `parseAsync()` rejection reaches Node as an unhandled rejection: a
- * stack trace at the user, and historically exit code 0.
- *
- * @param err - The value the command rejected with.
- * @param argv - Invocation argv; only `--json` is read from it.
- *
- * @example
- * ```ts
- * await program.parseAsync().catch(reportFatalError);
- * ```
- */
-export declare function reportFatalError(err: unknown, argv?: readonly string[]): void;
-export declare function resolveProject(opts?: {
-    json?: boolean | string;
-}): Promise<ProjectContext | null>;
-/**
- * Resolves both project context and run directory path.
- * Returns null if either fails (error already reported).
- */
-export declare function resolveProjectAndRunDir(runId: string, opts?: {
-    cwd?: string;
-    json?: boolean;
-}): Promise<{
-    projectRoot: string;
-    config: ProjectConfig;
-    runDirPath: string;
-} | null>;
-export declare function resolveCloudProject(opts?: {
-    json?: boolean | string;
-}): Promise<CloudContext | null>;
-export declare function safeReadEntity<T extends object = Record<string, unknown>>(projectRoot: string, type: EntityType, slug: string, opts?: {
-    json?: boolean | string;
-}): Promise<Awaited<ReturnType<typeof readEntity<T>>> | null>;