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

package/dist/commands/step.d.ts

@@ -1,95 +0,0 @@
-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

@@ -1,6 +0,0 @@
-export declare function sync(opts?: {
-    status?: boolean;
-    json?: boolean;
-    keepMine?: boolean;
-    confirmDeletes?: boolean;
-}): Promise<void>;

package/dist/commands/triage.d.ts

@@ -1,21 +0,0 @@
-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

@@ -1,4 +0,0 @@
-export interface UpdateOptions {
-    host?: string;
-}
-export declare function update(opts?: UpdateOptions): Promise<void>;

package/dist/commands/validate.d.ts

@@ -1,8 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

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

package/dist/sync-mcp/fatal.d.ts

@@ -1,42 +0,0 @@
-/**
- * Fatal-error reporting for the sync MCP server entry point.
- *
- * stdout is the MCP stdio transport, so a diagnostic printed there would
- * corrupt the protocol stream. Everything here writes to stderr only.
- */
-/** Side effects a fatal report needs, injectable so it can be tested. */
-export interface FatalDeps {
-    /** Write a diagnostic line — stderr, never stdout. */
-    writeErr: (text: string) => void;
-    /** Terminate the process with the given exit code. */
-    exit: (code: number) => void;
-}
-/**
- * Describe a fatal error, with its stack when there is one.
- *
- * @example
- * ```ts
- * formatFatal("uncaughtException", new Error("boom"));
- * // "iamu sync-server: fatal uncaughtException: boom\n…stack…\n"
- * ```
- */
-export declare function formatFatal(kind: string, err: unknown): string;
-/**
- * Report a fatal error on stderr and exit non-zero.
- *
- * @example
- * ```ts
- * handleFatal("uncaughtException", err, deps);
- * ```
- */
-export declare function handleFatal(kind: string, err: unknown, deps?: FatalDeps): void;
-/**
- * Install `uncaughtException` / `unhandledRejection` handlers that log
- * to stderr before exiting, instead of dying silently with code 1.
- *
- * @example
- * ```ts
- * installFatalHandlers();
- * ```
- */
-export declare function installFatalHandlers(deps?: FatalDeps): void;

package/dist/sync-mcp/server.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync-mcp/tools.d.ts

@@ -1,12 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
- * Build the `iamu-sync` MCP server: push, pull, auth status, and
- * background change polling over the local `iamu/` project tree.
- *
- * @example
- * ```ts
- * const server = createSyncServer();
- * await server.connect(new StdioServerTransport());
- * ```
- */
-export declare function createSyncServer(): McpServer;

package/dist/templates.d.ts

@@ -1,10 +0,0 @@
-/**
- * Resolves the root directory containing `templates/`.
- * In development (source/vitest): import.meta.url is in `src/` or `src/commands/`,
- * so templates are located at `src/templates`.
- * In production bundle (tsup): import.meta.url is in `dist/`,
- * and copy-assets.mjs copies templates to `dist/templates`.
- */
-export declare function getTemplatesRoot(): string;
-export declare function getTemplateDir(subdir: "skills" | "prompts"): string;
-export declare function getTemplateFile(subdir: "skills" | "prompts", filename: string): string;

package/dist/ui/journey-diff.d.ts

@@ -1,3 +0,0 @@
-import type { JourneyDiff } from "@iamu-dev/local-store";
-export declare function formatJourneyDiffTerminal(diff: JourneyDiff): string;
-export declare function printJourneyDiff(diff: JourneyDiff): void;

package/dist/ui/json.d.ts

@@ -1,6 +0,0 @@
-/**
- * Pick specified keys from an array of records or a single record.
- * Supports comma-separated field list: e.g. "slug,name,role".
- * If fields is boolean true or undefined/empty, returns target as-is.
- */
-export declare function filterJsonFields<T extends Record<string, unknown>>(target: T[] | T, fields?: string | boolean): unknown;

package/dist/ui/logger.d.ts

@@ -1,5 +0,0 @@
-/**
- * Standard verbosity and quiet mode helpers driven by IAMU_QUIET and IAMU_VERBOSE environment variables.
- */
-export declare function isQuiet(): boolean;
-export declare function isVerbose(): boolean;

package/dist/ui/panic.d.ts

@@ -1,11 +0,0 @@
-type SigintCleanup = () => Promise<void> | void;
-/**
- * Registers an asynchronous cleanup handler to execute on SIGINT (e.g. closing an HTTP server).
- * Returns an unregister function.
- */
-export declare function registerSigintCleanup(handler: SigintCleanup): () => void;
-/**
- * Registers global process handlers for graceful shutdown and top-level error boundaries.
- */
-export declare function setupProcessHandlers(): void;
-export {};

package/dist/ui/symbols.d.ts

@@ -1,11 +0,0 @@
-export declare const symbols: {
-    success: string;
-    error: string;
-    pending: string;
-    warning: string;
-    modified: string;
-    add: string;
-    info: string;
-    dot: string;
-    question: string;
-};

package/dist/ui/table.d.ts

@@ -1,20 +0,0 @@
-export declare function stripAnsi(str: string): string;
-export declare function visualLength(str: string): number;
-export declare function padRight(str: string, targetWidth: number): string;
-export declare function truncate(str: string, maxWidth: number): string;
-export interface TableColumn<T> {
-    header: string;
-    value: (item: T) => string;
-    minWidth?: number;
-    maxWidth?: number;
-}
-export interface FormatTableOptions {
-    tty?: boolean;
-}
-/**
- * Formats data into a cleanly aligned table with dynamically calculated column widths.
- * Automatically accounts for ANSI color sequences in length calculations.
- * When output is piped (!process.stdout.isTTY), automatically emits machine-readable
- * Tab-Separated Values (TSV) without ANSI escapes, borders, or text truncation.
- */
-export declare function formatTable<T>(items: T[], columns: TableColumn<T>[], options?: FormatTableOptions): string[];

package/dist/ui/update-check.d.ts

@@ -1,6 +0,0 @@
-export declare function isSemverGreater(latest: string, current: string): boolean;
-/**
- * Non-blocking, cached check against npm registry for CLI updates.
- */
-export declare function checkForUpdate(currentVersion: string): Promise<string | null>;
-export declare function printUpdateNotice(currentVersion: string, latestVersion: string): void;

package/dist/worktree-state.d.ts

@@ -1,49 +0,0 @@
-/** The build block's view of the working tree. */
-export interface WorktreeState {
-    git_dirty: boolean;
-    /** Only when dirty: 12 lowercase hex characters. */
-    worktree_hash?: string;
-}
-/** Answers the working-tree question for a project root. */
-export type WorktreeDetector = (projectRoot: string) => WorktreeState | undefined;
-/** Untracked files hashed at most; past this the count still counts. */
-export declare const MAX_UNTRACKED_HASHED = 2000;
-/**
- * Whether the working tree has changes outside `iamu/`, and their
- * fingerprint.
- *
- * Hash recipe (sha256, first 12 hex characters):
- * 1. the bytes of `git diff HEAD --binary -- . ':(exclude)<iamu>'`, run
- *    from the repository root with diff settings pinned;
- * 2. then, for each untracked non-ignored file outside `iamu/` sorted by
- *    path (bytewise, at most {@link MAX_UNTRACKED_HASHED}):
- *    `<path>\0<sha256 of content>\n`, and past the cap `+<count>\n`.
- *
- * @example
- * ```ts
- * detectWorktreeState("/work/shop");
- * // { git_dirty: true, worktree_hash: "3fa9c1d2e4b5" }
- * ```
- */
-export declare function detectWorktreeState(projectRoot: string, iamuDirName?: string): WorktreeState | undefined;
-/**
- * Whether the product's code changed between `start-run` and `complete`.
- * The build block's fingerprint is taken at start; an edit (or commit) made
- * while the walker was out means the run's findings may mix two versions,
- * and the build it lands in describes only the first.
- *
- * @param start - The run's recorded build block (`walkthrough.json`).
- * @param now - The working tree as it is now.
- * @returns A one-line warning, or null when nothing changed or either side
- *   is unknown.
- *
- * @example
- * ```ts
- * codeChangedWarning({ git_dirty: false }, { git_dirty: true, worktree_hash: "a1b2c3d4e5f6" });
- * // "the product's code changed during the walk …"
- * ```
- */
-export declare function codeChangedWarning(start: {
-    git_dirty?: boolean;
-    worktree_hash?: string;
-} | undefined, now: WorktreeState | undefined): string | null;