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

package/dist/commands/credentials.d.ts

@@ -1,144 +0,0 @@
-import { IamuConfigError } from "@iamu-dev/protocol";
-/**
- * Production API URL, used when neither a flag, `IAMU_API_URL`, nor the
- * project config names one.
- *
- * @example
- * ```ts
- * const url = config.cloud_api_url ?? DEFAULT_API_URL;
- * ```
- */
-export declare const DEFAULT_API_URL = "https://api.iamu.dev";
-/**
- * Stored credentials, keyed by API URL. Values are left `unknown` on
- * purpose: the file is user-editable, so every reader narrows.
- */
-export type CredentialsStore = Record<string, unknown>;
-/**
- * Absolute path of the credentials file (`~/.iamu/credentials.json`).
- *
- * @returns The path; the file may not exist yet.
- *
- * @example
- * ```ts
- * console.log(`Tokens live in ${getCredentialsPath()}`);
- * ```
- */
-export declare function getCredentialsPath(): string;
-/**
- * The API URL a command talks to: the configured one (project config
- * or flag), else `IAMU_API_URL`, else {@link DEFAULT_API_URL}. Empty
- * strings count as unset.
- *
- * @param configured - URL from project config or a flag, if any.
- * @returns The effective API URL.
- *
- * @example
- * ```ts
- * const apiUrl = resolveApiUrl(config.cloud_api_url);
- * ```
- */
-export declare function resolveApiUrl(configured?: string | null): string;
-/**
- * The credentials file exists but is not a JSON object. Reported instead
- * of being treated as empty: the next login would otherwise overwrite
- * every stored token without a word.
- *
- * @example
- * ```ts
- * try {
- *   await readCredentialsStore();
- * } catch (err) {
- *   if (err instanceof CredentialsFileError) console.error(err.message);
- * }
- * ```
- */
-export declare class CredentialsFileError extends IamuConfigError {
-    /**
-     * @param path - The unreadable credentials file.
-     * @param reason - What is wrong with it.
-     * @param cause - Underlying parse error, if any.
-     */
-    constructor(path: string, reason: string, cause?: unknown);
-}
-/**
- * Read the whole credentials store. A missing file is an empty store; a
- * corrupt one throws {@link CredentialsFileError} so no caller writes
- * over tokens it could not read.
- *
- * @returns The parsed store.
- * @throws {@link CredentialsFileError} when the file is not a JSON object.
- *
- * @example
- * ```ts
- * const store = await readCredentialsStore();
- * delete store["https://api.iamu.dev"];
- * await writeCredentialsStore(store);
- * ```
- */
-export declare function readCredentialsStore(): Promise<CredentialsStore>;
-/**
- * Replace the credentials store. Written to a temp file with mode 0600
- * and renamed into place, so a crash mid-write leaves the previous file
- * intact and the tokens are never world-readable, even briefly. The
- * parent directory is created with mode 0700.
- *
- * @param store - The full store to persist.
- *
- * @example
- * ```ts
- * const store = await readCredentialsStore();
- * store[apiUrl] = { token, createdAt: new Date().toISOString() };
- * await writeCredentialsStore(store);
- * ```
- */
-export declare function writeCredentialsStore(store: CredentialsStore): Promise<void>;
-/** @internal Reset warned flag for unit testing. */
-export declare function _resetWarnedUnreadableStoreForTesting(): void;
-/**
- * Token for `apiUrl`: `IAMU_TOKEN`, then `IAMU_API_KEY`, then the entry
- * for that URL in the credentials file. A corrupt credentials file is
- * reported once on stderr (with the recovery step) and treated as no
- * token.
- *
- * Synchronous because it sits on hot paths (MCP tool handlers, status).
- *
- * @param apiUrl - API URL the token must belong to; defaults via
- *   {@link resolveApiUrl}.
- * @returns The token, or `null` when none is available.
- *
- * @example
- * ```ts
- * const token = resolveApiKey(config.cloud_api_url);
- * if (!token) console.error("Run iamu auth login");
- * ```
- */
-export declare function resolveApiKey(apiUrl?: string | null): string | null;
-/**
- * True for hostnames that never leave the machine.
- *
- * @param hostname - `URL.hostname` (IPv6 arrives bracketed).
- * @returns Whether the host is loopback.
- *
- * @example
- * ```ts
- * isLoopbackHost(new URL("http://[::1]:3000").hostname); // true
- * ```
- */
-export declare function isLoopbackHost(hostname: string): boolean;
-/**
- * Refuse an API URL that would send the bearer token in cleartext:
- * anything but `https://`, except plain `http://` to a loopback host
- * (the local cloud stack).
- *
- * @param url - Candidate API URL.
- * @param source - Where it came from, for the error (`--url`,
- *   `IAMU_API_URL`, ...).
- * @throws {@link IamuValidationError} when the URL is malformed or insecure.
- *
- * @example
- * ```ts
- * assertSecureApiUrl(process.env.IAMU_API_URL ?? DEFAULT_API_URL, "IAMU_API_URL");
- * ```
- */
-export declare function assertSecureApiUrl(url: string, source: string): void;

package/dist/commands/diff-filter.d.ts

@@ -1,11 +0,0 @@
-import type { OutlineFrontmatter, ScenarioFrontmatter } from "@iamu-dev/protocol";
-export interface ChangedFilesResult {
-    baseRef: string;
-    files: string[];
-}
-/** Resolve changed files against a git base ref (e.g. origin/main, HEAD~1). */
-export declare function getChangedFiles(projectRoot: string, explicitRef?: string | boolean): ChangedFilesResult | null;
-/** Extract matching tokens from a scenario and its outline. */
-export declare function extractScenarioKeywords(scenario: ScenarioFrontmatter, outline?: OutlineFrontmatter): string[];
-/** Checks whether any changed file matches the scenario's keywords or path. */
-export declare function matchesChangedFiles(changedFiles: string[], scenario: ScenarioFrontmatter, outline?: OutlineFrontmatter): boolean;

package/dist/commands/doctor.d.ts

@@ -1,24 +0,0 @@
-export interface DoctorCheck {
-    category: "runtime" | "browser" | "project" | "agent" | "cloud";
-    name: string;
-    status: "ok" | "warn" | "error";
-    message: string;
-    remedy?: string;
-}
-export interface DoctorResult {
-    ok: boolean;
-    checks: DoctorCheck[];
-    summary: {
-        ok: number;
-        warn: number;
-        error: number;
-    };
-}
-/** Check if a TCP port is available or bound */
-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 doctor(opts?: {
-    json?: boolean;
-}): Promise<void>;

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