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

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,49 @@
+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

@@ -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/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * \@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";