@habemus-papadum/aiui 0.2.0 → 0.5.0

package/dist/commands/browser.d.ts

@@ -1,3 +1,8 @@
+import { type SessionBrowser } from "@habemus-papadum/aiui-util";
+import type { AiuiArgs } from "../util/aiui-args";
+import { type ChromeSettings } from "../util/chrome";
+import { type AiuiConfig } from "../util/config";
+type ChromeConfig = NonNullable<AiuiConfig["chrome"]>;
 /** The default *remote* port — the one worth keeping fixed (see module doc). */
 export declare const DEFAULT_REMOTE_PORT = 9222;
 export interface BrowserOptions {
@@ -12,6 +17,50 @@ export interface BrowserOptions {
     remotePort?: string;
 }
 export declare function runBrowser(opts: BrowserOptions): Promise<void>;
+/** Options for {@link startSessionBrowser}. */
+export interface StartSessionBrowserOptions {
+    /** CLI identity flags (profile / data dir), reconciled against config. */
+    flags?: Pick<AiuiArgs, "chromeProfile" | "chromeDataDir">;
+    /** The `chrome` section of the loaded config. */
+    config?: ChromeConfig;
+    /**
+     * Whether prompting is allowed. Interactive launches may offer to
+     * install/update Chrome for Testing and print the extension autoload hint;
+     * non-interactive ones (CI, or a sidecar whose terminal belongs to another
+     * process — `aiui vite`'s browser open) degrade to whatever browser is
+     * already installed, silently.
+     */
+    interactive: boolean;
+    /** Override the resolved DevTools debug port (`aiui browser --port`). */
+    debugPort?: number;
+    /** Launch headless regardless of config (`aiui browser --headless`). */
+    headless?: boolean;
+    /** Open this URL as the first tab instead of about:blank. */
+    startUrl?: string;
+}
+/**
+ * Launch the session browser the way `aiui browser` does — the shared
+ * "everything before the window exists" sequence, extracted so other commands
+ * (`aiui vite`'s browser sidecar) launch identically instead of re-deriving
+ * it:
+ *
+ *  1. Resolve settings from flags + config.
+ *  2. Prefer the managed Chrome for Testing unless config names a browser
+ *     explicitly (the sync may prompt to install/update — only when
+ *     `interactive`; otherwise it just reports what's installed).
+ *  3. Rebuild and load the aiui devtools extension, and pick up the
+ *     intent-tool extension's dist/ if its dev loop has produced one
+ *     (dev checkouts only).
+ *  4. Launch on the profile's user data dir and wait for the debug endpoint.
+ *
+ * Throws with a remediation-bearing message when no browser can be found or
+ * the launch fails; callers decide whether that's fatal (`aiui browser`) or
+ * merely a warning (`aiui vite`, where the dev server must keep running).
+ */
+export declare function startSessionBrowser(opts: StartSessionBrowserOptions): Promise<{
+    session: SessionBrowser;
+    settings: ChromeSettings;
+}>;
 /**
  * `~/.cache/aiui/browser-profiles/<key>` for a tunneled session browser.
  * Path-only (no mkdir) — the browser launch creates it on first use.
@@ -25,3 +74,4 @@ export declare function sshTunnelArgs(target: string, remotePort: number, localP
 export declare function remoteAttachCommand(remotePort: number): string;
 /** `aiui open <url>` — open a page in the running session browser. */
 export declare function runOpen(url: string, opts: Pick<BrowserOptions, "profile" | "dataDir">): Promise<void>;
+export {};

package/dist/commands/clean.d.ts

@@ -0,0 +1,49 @@
+export interface CleanOptions {
+    /** Limit the reset to this repo's `.aiui-cache/`. */
+    projectOnly?: boolean;
+    /** Limit the reset to the user cache (`~/.cache/aiui`). */
+    userOnly?: boolean;
+    /** Keep the managed Chrome for Testing install (skip the ~160 MB re-download). */
+    keepBrowser?: boolean;
+    /** Print what would be deleted, then stop. */
+    dryRun?: boolean;
+    /** Delete without the confirmation prompt. */
+    yes?: boolean;
+}
+/** The three cache roots `clean` reasons about (resolved, never created). */
+export interface CleanRoots {
+    /** `<base>/.aiui-cache`. */
+    project: string;
+    /** `~/.cache/aiui` (respects `$AIUI_CACHE` / `$XDG_CACHE_HOME`). */
+    user: string;
+    /** The managed Chrome for Testing dir — a child of {@link CleanRoots.user}. */
+    browser: string;
+}
+/** One thing `clean` will delete: a root path, optionally sparing some children. */
+export interface CleanTarget {
+    /** Short human label for the plan output. */
+    label: string;
+    /** The directory to remove. */
+    path: string;
+    /**
+     * Absolute child paths to preserve instead of deleting `path` wholesale. Used
+     * by `--keep-browser` to clear the user cache while keeping `chrome/`.
+     */
+    keep?: string[];
+}
+/** Resolve the cache roots for a given base dir (defaults to cwd). */
+export declare function cleanRoots(base?: string): CleanRoots;
+/**
+ * Decide which roots to remove from the flags. Pure over `roots`: the fs is only
+ * touched later, when the targets are resolved to concrete deletions.
+ */
+export declare function planCleanTargets(opts: CleanOptions, roots: CleanRoots): CleanTarget[];
+/**
+ * The concrete absolute paths a target will delete. `[path]` for a plain target,
+ * or its children minus the kept ones for a `--keep-browser` target; `[]` when
+ * nothing there exists (so an already-clean root drops out of the plan).
+ */
+export declare function resolveDeletions(target: CleanTarget): string[];
+export declare function runClean(opts?: CleanOptions): Promise<void>;
+/** Human-readable byte count (binary units), e.g. `346.0 MB`. */
+export declare function formatBytes(n: number): string;

package/dist/commands/config-tui.d.ts

@@ -0,0 +1 @@
+export declare function runConfigTui(base?: string): Promise<void>;

package/dist/commands/config.d.ts

@@ -0,0 +1,43 @@
+import { type AiuiConfig } from "../util/config";
+import { type ConfigValue, type ResolvedField } from "../util/config-schema";
+/** Which config file a write targets. */
+export type ConfigLevel = "user" | "project";
+/** Both config files, read once — the raw material for every subcommand. */
+export interface ConfigLevels {
+    paths: {
+        user: string;
+        project: string;
+    };
+    user: AiuiConfig;
+    project: AiuiConfig;
+}
+/** One field with its per-level values and resolved provenance. */
+export interface FieldState extends ResolvedField {
+    userValue?: ConfigValue;
+    projectValue?: ConfigValue;
+    /** The value the launcher would see (project beats user); undefined = unset. */
+    effective?: ConfigValue;
+    /** Where {@link effective} comes from; "default"/"unset" mean no file sets it. */
+    source: ConfigLevel | "default" | "unset";
+}
+/** Read both config levels (missing files read as empty configs). */
+export declare function readLevels(base?: string): ConfigLevels;
+/** Resolve every schema field against the two levels. */
+export declare function fieldStates(levels: ConfigLevels): FieldState[];
+export interface ShowOptions {
+    json?: boolean;
+}
+export declare function runConfigShow(options?: ShowOptions, base?: string): void;
+/** The value column of one `show`/TUI row: set value + source, or the default. */
+export declare function valueCell(state: FieldState): string;
+export declare function runConfigGet(key: string, base?: string): void;
+export interface WriteOptions {
+    /** Target the project file (.aiui-cache/config.json) instead of the user file. */
+    project?: boolean;
+}
+export declare function runConfigSet(key: string, raw: string, options?: WriteOptions, base?: string): void;
+/** The shared write path for `set` and the TUI. */
+export declare function writeValue(levels: ConfigLevels, state: ResolvedField, value: ConfigValue, level: ConfigLevel): void;
+export declare function runConfigUnset(key: string, options?: WriteOptions, base?: string): void;
+/** The shared unset path for `unset` and the TUI. */
+export declare function removeValue(levels: ConfigLevels, state: ResolvedField, level: ConfigLevel): void;

package/dist/commands/debug.d.ts

@@ -0,0 +1,7 @@
+export interface DebugOptions {
+    /** Target a channel by its registry tag instead of the interactive selector. */
+    mcp?: string;
+    /** Open the browser at the console (default true; `--no-open` skips). */
+    open?: boolean;
+}
+export declare function runDebug(opts?: DebugOptions): Promise<void>;

package/dist/commands/env.d.ts

@@ -0,0 +1,36 @@
+/** The env files read from the workspace root, in load order (later wins). */
+export declare const ENV_FILES: readonly [".env", ".env.local", ".env.dev", ".env.dev.local"];
+/**
+ * Find the workspace root: the nearest ancestor of `start` carrying a
+ * `pnpm-workspace.yaml` or a `.git`. Falls back to `start` itself (a bare
+ * consumer project without either still gets its own ./node_modules/.bin).
+ */
+export declare function findWorkspaceRoot(start: string): string;
+/**
+ * Parse one dotenv file's text into ordered KEY → value entries. Deliberately
+ * minimal (the files here hold API keys, not programs): `KEY=VALUE` lines, an
+ * optional `export ` prefix, `#` comment lines and blanks skipped, one pair of
+ * matching single or double outer quotes stripped. No escape processing, no
+ * multiline values, no inline comments after unquoted values.
+ */
+export declare function parseDotenv(text: string): Map<string, string>;
+/** Single-quote `value` for POSIX shells (embedded `'` becomes `'\''`). */
+export declare function shQuote(value: string): string;
+/**
+ * Render the activation script. Pure — the command resolves dirs and reads
+ * files, this just writes shell. Every line ends in `;` (see the module
+ * header: unquoted `eval` survival), and each PATH prepend is wrapped in a
+ * containment check so activation is idempotent.
+ */
+export declare function buildEnvScript(input: {
+    /** Directories to prepend to PATH, highest priority first. */
+    pathDirs: string[];
+    /** Env entries to export (already merged across files, later-file wins). */
+    vars: Map<string, string>;
+}): string;
+/**
+ * The command: resolve the workspace root from the cwd, collect the PATH dirs
+ * that exist, merge the env files, and print the script (stdout) + a summary
+ * of what it does (stderr, names only — never a value).
+ */
+export declare function runEnv(): void;

package/dist/commands/extension.d.ts

@@ -0,0 +1,46 @@
+/** The NM host name (lowercase alphanumerics, dots, underscores only). */
+export declare const NATIVE_HOST_NAME = "com.habemus_papadum.aiui";
+/**
+ * The intent client's stable unpacked-extension id (see
+ * `packages/aiui-intent-client/src/ext/manifest.ts`, which owns the key this
+ * is derived from). Duplicated rather than imported: `aiui` does not depend on
+ * the intent client, and this is a 32-char constant that changes only if the
+ * key does.
+ */
+export declare const INTENT_CLIENT_EXTENSION_ID = "cdpbfpcelmifhagikjlfpgfipggcmdeg";
+export interface ExtensionOptions {
+    extensionId?: string;
+}
+/**
+ * Browser NM manifest directories, user-level, per platform.
+ *
+ * Deliberately NO Chrome for Testing entry: CfT does not read a fixed
+ * user-level directory — it looks in `<user-data-dir>/NativeMessagingHosts`
+ * (measured on macOS; an earlier `Google/ChromeForTesting` guess here was
+ * never read by anything). aiui-launched browsers get the manifest written
+ * into their profile at launch instead ({@link installProfileNativeHost}).
+ */
+export declare function nativeHostManifestDirs(platform: NodeJS.Platform, home: string): string[];
+/** The wrapper script body. Exported for tests. */
+export declare function wrapperScript(cwd: string, command: string, args: string[]): string;
+export declare function runExtension(action: string, options?: ExtensionOptions): Promise<void>;
+/**
+ * Install the NM manifest into a session-browser profile
+ * (`<user-data-dir>/NativeMessagingHosts/`) — the directory Chrome for
+ * Testing actually consults (measured; see the module doc). Called by the
+ * launchers whenever they load the intent client's extension: the profile
+ * lives in aiui's own project-local cache, so unlike the global install this
+ * needs no user decision — it is the same class of write as creating the
+ * profile. Quiet and idempotent; no browser restart needed (NM manifests are
+ * read per `connectNative`/`sendNativeMessage` call).
+ */
+export declare function installProfileNativeHost(userDataDir: string, options?: ExtensionOptions): void;
+/**
+ * {@link installProfileNativeHost} as the launchers call it: only when the
+ * intent client's extension is actually loadable (no point granting a host to
+ * an extension that won't be there), and never fatal — a failed write
+ * degrades to the panel's type-a-port fallback, with a note saying so. Called
+ * on both the launch and the attach-to-running paths, so a profile whose
+ * browser outlives many sessions still converges on a current manifest.
+ */
+export declare function ensureProfileNativeHost(userDataDir: string, intentReady: boolean, warn: (title: string, detail: string) => void): void;

package/dist/commands/mcp.d.ts

@@ -7,6 +7,16 @@
  * user-facing channel commands under `aiui` without moving them out of the
  * package that owns the MCP server Claude Code spawns.
  *
+ * **One thing is not verbatim.** The subcommands that *are* a channel process —
+ * `serve` (standalone debug channel) and `mcp` (the stdio MCP server) — get the
+ * same config-derived `--bind` that `aiui claude` computes when it tells Claude
+ * Code how to spawn the channel (see util/channel-launch), so both ways of
+ * starting a channel honor `channel.bind` identically. (Sidecars need no such
+ * plumbing: the channel imports and mounts its own standard set — paint, intent,
+ * bar, pencil — so every channel hosts all four.) Flags you pass explicitly
+ * always win. Every other subcommand (`quick`, `config`) talks to a channel
+ * someone *else* is running and forwards untouched.
+ *
  * Like `aiui vite`, the channel CLI is a declared dependency, so we resolve it
  * from node_modules (tsx-from-source in a dev checkout, the built `dist` when
  * installed; see {@link resolvePackageCli}) rather than looking on the PATH.

package/dist/commands/native-host.d.ts

@@ -0,0 +1,16 @@
+/** Encode one native-messaging frame (native-endian u32 length + JSON). Pure. */
+export declare function encodeNativeFrame(message: unknown): Buffer;
+/**
+ * Split complete frames off an accumulating buffer. Returns the parsed
+ * messages and the unconsumed remainder (a partial frame stays buffered).
+ * Unparseable JSON inside a complete frame yields `undefined` in its slot —
+ * the caller answers with an error rather than dying. Pure.
+ */
+export declare function decodeNativeFrames(buffer: Buffer): {
+    messages: unknown[];
+    rest: Buffer;
+};
+/** Answer one request. Exported for tests. */
+export declare function handleNativeRequest(message: unknown): Record<string, unknown>;
+/** The stdio loop. Never resolves until stdin ends (Chrome closes it). */
+export declare function runNativeHost(): Promise<void>;

package/dist/commands/pencil-url.d.ts

@@ -0,0 +1,18 @@
+/** A network interface the channel's bind makes reachable, as offered in the picker. */
+interface HostInterface {
+    /** The OS interface name (`en0`, `lo0`) or a synthetic label (`loopback`). */
+    name: string;
+    address: string;
+}
+/**
+ * The interfaces the channel is actually reachable on, given its bind:
+ *  - loopback (`127.0.0.1`) → only the loopback address; an iPad can't reach it
+ *    without a tunnel, but we still offer it (the user may have one).
+ *  - host (`0.0.0.0`) → every non-internal IPv4 the machine holds, named by its
+ *    OS interface, plus loopback last for on-machine testing.
+ */
+export declare function boundInterfaces(bindHost: string | undefined): HostInterface[];
+export declare function runPencilUrl(opts?: {
+    json?: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/vite.d.ts

@@ -1,39 +1,65 @@
-import type { RunningServer } from "@habemus-papadum/aiui-claude-channel";
-/** The channel server `runVite` should point Vite at, or why it couldn't. */
-export interface ChannelTarget {
-    /** The server resolved without prompting (by tag). */
-    server?: RunningServer;
-    /** Servers to offer in the interactive selector (no tag given, ≥1 running). */
-    select?: RunningServer[];
-    /** A human-readable reason a requested server couldn't be resolved. */
-    error?: string;
-}
-/**
- * Decide which running channel server Vite should connect to.
- *
- * Pure so it can be unit-tested without spawning anything:
- *  - With a `targetTag`, return the server whose `tag` matches exactly; if none
- *    matches, return an `error` naming the tag and the tags that *are* running.
- *  - Without a `targetTag`, don't guess: return `{}` when nothing is running, or
- *    `{ select }` so the caller runs the same selector as `quick` (which
- *    auto-picks a lone server and prompts when there are several).
- */
-export declare function resolveChannelTarget(servers: RunningServer[], targetTag: string | undefined): ChannelTarget;
+import { type AiuiArgs } from "../util/aiui-args";
 /**
  * Launch Vite, forwarding any extra args (e.g. `aiui vite dev`,
  * `aiui vite --port 3000`, `aiui vite --version`).
  *
- * Before launching, resolve which running aiui channel server the dev server
- * should talk to — either the one named by `--aiui-mcp <tag>` (or `--aiui-tag`),
- * or, with no tag, the one you pick from the same selector `quick` uses (which
- * auto-selects when only one is running) — and inject its port as
- * {@link VITE_PORT_ENV} so the app can reach it. When a specific tag was asked
- * for but isn't running, we fail loudly instead of connecting to the wrong one.
- *
  * Unlike `claude` — an external tool we look up on the PATH — Vite is a declared
  * dependency of this package, so we resolve it straight out of node_modules and
  * run it via the current Node with an absolute path. Resolving it also doubles
  * as the "is Vite available?" check: if it isn't installed, we fail loudly
  * rather than shelling out to nothing. See {@link resolvePackageCli}.
+ *
+ * Once the dev server is up, a *sidecar* opens it in the session browser (the
+ * shared window `aiui claude` attaches the agent to). We never know up front
+ * which port Vite will bind — the user runs many dev servers and Vite walks up
+ * from 5173 — so instead of guessing, Vite's stdout is teed through us and
+ * scanned for its own ready banner (see {@link parseViteLocalUrl}). stdin and
+ * stderr stay inherited: Vite still owns the terminal, its interactive
+ * shortcuts and Ctrl-C behave exactly as before. The sidecar is fire-and-forget
+ * ({@link openAppInBrowser}): whatever the browser does, the dev server runs on.
  */
 export declare function runVite(rawArgs?: string[]): Promise<void>;
+/**
+ * Parse one line of Vite's stdout for the local dev-server URL.
+ *
+ * Vite's ready banner looks like (colored in a real terminal):
+ *
+ *     ➜  Local:   http://localhost:5174/
+ *     ➜  Network: use --host to expose
+ *
+ * Only the `Local:` line counts, and only with a loopback host (`localhost`,
+ * `127.0.0.1`, `[::1]`) — that's the URL meaningful to open in a browser on
+ * this machine, or to port-forward in the headless hint. ANSI codes are
+ * stripped *first*: Vite colors the host and the port separately, so escape
+ * sequences sit in the middle of the URL text and no pattern would survive
+ * matching against the raw bytes. Returns undefined for anything that isn't
+ * the ready line — the same shape the retired workbench lab used, the
+ * house pattern for these one-line protocols.
+ */
+export declare function parseViteLocalUrl(line: string): string | undefined;
+/**
+ * Tee a child's stdout to ours verbatim while watching for the dev-server URL.
+ *
+ * Chunks are forwarded untouched (colors, spinners, screen clears all pass
+ * through); scanning happens on a parallel line-buffered copy so a URL split
+ * across chunk boundaries is still seen. Once found, `onUrl` fires exactly
+ * once and the scanner disengages — from then on this is a plain passthrough.
+ * Exported for tests, which drive it with in-memory streams (no child
+ * process).
+ */
+export declare function teeAndDetectLocalUrl(source: NodeJS.ReadableStream, sink: NodeJS.WritableStream, onUrl: (url: string) => void): void;
+/**
+ * The browser sidecar: once the dev server's URL is known, put it in front of
+ * the user — in the *session browser* (the shared window `aiui claude`
+ * attaches the agent to; see aiui-util's browser module and `aiui open`),
+ * never their default browser. A running session browser gets a new tab; none running
+ * means launching one exactly the way `aiui browser` does
+ * ({@link startSessionBrowser}), with the app as its first tab.
+ *
+ * Runs concurrently with Vite and must never interfere with it: everything is
+ * caught, failures print a warning, and the dev server keeps the terminal and
+ * keeps running either way. It is also deliberately non-interactive — Vite
+ * owns stdin — so the Chrome for Testing sync never prompts here; it just
+ * uses whatever browser is already available.
+ */
+export declare function openAppInBrowser(url: string, aiuiArgs: AiuiArgs): Promise<void>;