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

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

@@ -0,0 +1,27 @@
+/** 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

@@ -0,0 +1,132 @@
+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;
+    push?: 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(runIdArg?: 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

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

package/dist/commands/context.d.ts

@@ -0,0 +1,81 @@
+import { readEntity } from "@iamu-dev/local-store";
+import { type EntityType, type ProjectConfig } from "@iamu-dev/protocol";
+export interface ProjectContext {
+    projectRoot: string;
+    config: ProjectConfig;
+}
+export interface CloudContext extends ProjectContext {
+    apiKey: string;
+    apiUrl: string;
+}
+export interface CommandDiagnosticOptions {
+    json?: boolean | string;
+    code?: string;
+    fix?: string | boolean | null;
+    details?: Record<string, unknown>;
+}
+export declare function commandError(message: string, opts?: CommandDiagnosticOptions): 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;
+/**
+ * Resolves the active scenario slug following the OpenSpec single-entity resolution pattern:
+ * 1. Explicit slug argument if provided
+ * 2. Active scenario in session state (`iamu/.cache/session-state.json`)
+ * 3. Single-entity auto-selection: if exactly 1 scenario exists on disk, auto-select it.
+ */
+export declare function resolveScenarioSlug(projectRoot: string, explicitSlug?: string): string | null;
+/**
+ * Resolves the active finding slug following the OpenSpec single-entity resolution pattern:
+ * 1. Explicit slug argument if provided
+ * 2. Active finding in session state (`iamu/.cache/session-state.json`)
+ * 3. Single-entity auto-selection: if exactly 1 finding exists on disk, auto-select it.
+ */
+export declare function resolveFindingSlug(projectRoot: string, explicitSlug?: string): string | null;
+/**
+ * Resolves the active run ID from an explicit argument or falls back to
+ * session state (`iamu/.cache/session-state.json`).
+ */
+export declare function resolveRunId(projectRoot: string, explicitRunId?: string): 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>;

package/dist/commands/credentials.d.ts

@@ -0,0 +1,144 @@
+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://app.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

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

@@ -0,0 +1,33 @@
+export interface DoctorCheck {
+    category: "runtime" | "browser" | "project" | "agent" | "cloud" | "target";
+    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 checkTargetHealth(targetUrl: string): Promise<DoctorCheck[]>;
+export declare function checkProjectHarnesses(projectRoot: string): Promise<DoctorCheck[]>;
+export declare function checkProjectTestabilityContract(projectRoot: string): Promise<{
+    checks: DoctorCheck[];
+    targetUrl?: string;
+}>;
+export declare function runDoctorChecks(projectRoot?: string, opts?: {
+    target?: string;
+}): Promise<DoctorResult>;
+export declare function doctor(opts?: {
+    json?: boolean;
+    target?: string;
+}): Promise<void>;

package/dist/commands/edit-entity.d.ts

@@ -0,0 +1,8 @@
+export interface EditEntityOptions {
+    json?: boolean;
+}
+/**
+ * Open an entity in the user's $EDITOR or $VISUAL, and validate its frontmatter
+ * against the entity schema on exit.
+ */
+export declare function editEntity(type: string, slug: string, opts?: EditEntityOptions): Promise<void>;

package/dist/commands/evaluate.d.ts

@@ -0,0 +1,34 @@
+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;
+    promptFile?: string;
+}): Promise<void>;
+export interface EvaluateRecordOptions {
+    file?: string;
+    data?: string;
+    json?: boolean;
+    yes?: boolean;
+    prompt?: boolean;
+    view?: boolean;
+    push?: boolean;
+}
+export declare function evaluateRecord(runId: string, opts: EvaluateRecordOptions): Promise<void>;

package/dist/commands/explore-crawl.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The read-only crawl behind `iamu explore`.
+ *
+ * Breadth-first from the start URL: on every surface, try every visible
+ * link and button once, and see where it leads. A surface is a page
+ * (keyed by its templated URL, see `explorePlaceKey`) or a view a click
+ * switched to on the same URL (keyed by its headings). Every surface is
+ * reached by replaying its path from the start, so the crawl does not
+ * depend on what the previous click left behind, and two crawls of one
+ * build should produce the same map.
+ *
+ * Read-only is enforced twice:
+ * - Controls whose name or link reads like a write (delete, pay, send,
+ *   save, log out …), form submits, downloads and other origins are
+ *   never clicked. Nothing is typed into a field.
+ * - Every request that is not GET/HEAD/OPTIONS is aborted before it
+ *   leaves the browser, and recorded on the action that caused it.
+ *
+ * Dialogs are dismissed (`confirm()` answers no) and popups closed.
+ * WebSocket messages are not guarded; a page controlled by a service
+ * worker (whose requests the guard cannot see) is refused.
+ */
+import { type ExploreBudget, type ExploreStats, type ExploreSurface } from "@iamu-dev/local-store";
+import type { Page } from "playwright-core";
+/**
+ * Options for {@link crawl}.
+ *
+ * @public
+ */
+export interface CrawlOptions {
+    startUrl: string;
+    budget: ExploreBudget;
+    /** Extra patterns: a control whose name or link matches is never tried. */
+    deny?: RegExp[];
+    /** Longest wait for the page to settle after an action. */
+    settleMs?: number;
+    /** One line per new surface, for progress output. */
+    log?: (line: string) => void;
+}
+/**
+ * What {@link crawl} found.
+ *
+ * @public
+ */
+export interface CrawlResult {
+    surfaces: ExploreSurface[];
+    stats: ExploreStats;
+}
+/**
+ * Crawl the product read-only from `opts.startUrl`.
+ *
+ * @param page - A page of its own; the crawl navigates it freely and
+ *   installs a request guard on it.
+ * @param opts - Start URL, budget, extra deny patterns.
+ * @returns The surfaces found and counts.
+ *
+ * @example
+ * ```ts
+ * const { surfaces, stats } = await crawl(page, {
+ *   startUrl: "http://localhost:3000/",
+ *   budget: { max_surfaces: 40, max_actions: 300, max_depth: 6 },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function crawl(page: Page, opts: CrawlOptions): Promise<CrawlResult>;

package/dist/commands/explore.d.ts

@@ -0,0 +1,53 @@
+/** Parsed options for `iamu explore [url]`. */
+export interface ExploreOptions {
+    maxSurfaces?: string;
+    maxActions?: string;
+    maxDepth?: string;
+    deny?: string[];
+    viewport?: string;
+    attach?: boolean;
+    json?: boolean;
+}
+/**
+ * `iamu explore [url]`: crawl the product read-only and write a map.
+ *
+ * @example
+ * ```ts
+ * await exploreRun("http://localhost:3000/", { maxSurfaces: "20" });
+ * ```
+ */
+export declare function exploreRun(url: string | undefined, opts: ExploreOptions): Promise<void>;
+/**
+ * `iamu explore list`.
+ *
+ * @example
+ * ```ts
+ * await exploreList({ json: true });
+ * ```
+ */
+export declare function exploreList(opts: {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * `iamu explore coverage [map]`.
+ *
+ * @example
+ * ```ts
+ * await exploreCoverageCommand(undefined, {});
+ * ```
+ */
+export declare function exploreCoverageCommand(mapId: string | undefined, opts: {
+    json?: boolean;
+    all?: boolean;
+}): Promise<void>;
+/**
+ * `iamu explore diff [a] [b]` — default: the two latest maps.
+ *
+ * @example
+ * ```ts
+ * await exploreDiffCommand(undefined, undefined, { json: true });
+ * ```
+ */
+export declare function exploreDiffCommand(a: string | undefined, b: string | undefined, opts: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/findings.d.ts

@@ -0,0 +1,7 @@
+export declare function findings(opts?: {
+    open?: boolean;
+    resolved?: boolean;
+    dismissed?: boolean;
+    scenario?: string;
+    json?: boolean | string;
+}): Promise<void>;

package/dist/commands/init.d.ts

@@ -0,0 +1,27 @@
+import type { HostAdapter } from "../adapters/types.js";
+/**
+ * The setup skill as the user will see it. With the Iamu plugin enabled,
+ * Claude Code has `/iamu:init` and no `iamu-setup`.
+ */
+export declare function setupCommand(projectRoot: string, hosts: HostAdapter[]): string;
+/**
+ * Detect the target port for local dev execution.
+ * Checks, in order:
+ * 1. process.env.PORT
+ * 2. .env files (.env.local, .env.development, .env) for PORT, VITE_PORT, APP_URL, NEXT_PUBLIC_APP_URL
+ * 3. package.json scripts for `-p <port>` or `--port <port>` flags
+ * 4. package.json dependencies and framework config files (vite -> 5173, astro -> 4321)
+ */
+export declare function detectTargetPort(projectRoot: string): number | undefined;
+export declare function detectTargetUrl(projectRoot: string): string;
+export declare function createDraftTestabilityContent(targetUrl?: string): string;
+export interface InitOptions {
+    name?: string;
+    yes?: boolean;
+    json?: boolean;
+    cloud?: boolean;
+}
+/**
+ * Scaffold `iamu/` and install skills for the detected hosts.
+ */
+export declare function init(opts?: InitOptions | string): Promise<void>;