@iamu-dev/iamu 0.2.0-beta.9 → 0.3.0-beta.0

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,96 @@
+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;
+    cancelled?: boolean;
+}
+/**
+ * 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/summary.d.ts

@@ -0,0 +1,20 @@
+export interface SummaryOptions {
+    run?: string;
+    worked?: string | string[];
+    question?: string | string[];
+    model?: string;
+    /** The walk could not start as set up: what was missing, or `false` to clear. */
+    blocked?: string | false;
+    file?: string;
+    json?: boolean;
+}
+export interface SummaryData {
+    what_worked: string[];
+    open_questions: string[];
+    model?: string;
+    /** Set when the walk could not start as set up (`--blocked`). */
+    blocked?: {
+        reason: string;
+    };
+}
+export declare function summaryCommand(runIdArg: string | undefined, opts: SummaryOptions): 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,11 @@
+import { type EntityType } from "@iamu-dev/protocol";
+import type { ZodSchema } from "zod";
+export declare const schemaByType: Record<EntityType, ZodSchema>;
+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";