@habemus-papadum/aiui 0.2.0 → 0.3.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,48 @@ 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 (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 +72,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,15 @@
+export interface DebugOptions {
+    /** Target a channel by its registry tag instead of the interactive selector. */
+    mcp?: string;
+    /** UI port for the viewer's dev server (default {@link DEFAULT_UI_PORT}). */
+    port?: string;
+    /** Open the browser at the viewer (default true; `--no-open` skips). */
+    open?: boolean;
+}
+/**
+ * This package's root — the Vite server root, found by walking up from this
+ * module to the `@habemus-papadum/aiui` package.json (two levels in the
+ * source tree, but the walk keeps it honest against dist layouts too).
+ */
+export declare function packageRoot(): string | undefined;
+export declare function runDebug(opts?: DebugOptions): Promise<void>;

package/dist/commands/demo.d.ts

@@ -17,7 +17,7 @@ export declare function classifyDemoTarget(target: string): DemoTargetState;
  * doesn't exist on the registry).
  */
 export declare function demoDependencyRange(version: string): string;
-/** Copy the template, restore `.gitignore`, and pin dependency ranges. */
+/** Copy the template, restore dot-paths npm strips, and pin dependency ranges. */
 export declare function scaffoldDemo(template: string, target: string): void;
 /**
  * The template directory shipped with this install. Probed upward from this

package/dist/commands/paint.d.ts

@@ -0,0 +1,3 @@
+export declare function runPaintUrl(opts?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/vite.d.ts

@@ -35,5 +35,43 @@ export declare function resolveChannelTarget(servers: RunningServer[], targetTag
  * 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 as the workbench's parseServeReadyLine, 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;

package/dist/index.d.ts

@@ -1,8 +1,16 @@
 /**
  * ai ui frontends
  *
+ * The `aiui` CLI's library surface. Launch *policy* the CLI applies lives here
+ * too, so sibling supervisors can reuse it instead of re-deriving it — the
+ * first case is {@link resolveSidecars}, the `aiui claude` logic deciding
+ * which session sidecars (e.g. the paint stream) a channel server should host for a
+ * project root. The workbench imports it to give its debug channel the same
+ * sidecar set a real session would get.
+ *
  * @packageDocumentation
  */
+export { type ResolveSidecarsDeps, resolveSidecars, type SidecarDescriptor, } from "./util/sidecars";
 /** The published package name — handy for smoke tests. */
 export declare const name = "@habemus-papadum/aiui";
 /** Greet someone. Replace with your library's real API. */

package/dist/index.js

@@ -1,9 +1,11 @@
-const a = "@habemus-papadum/aiui";
-function n(e) {
+import { r as n } from "./sidecars-BKlhUA0V.js";
+const r = "@habemus-papadum/aiui";
+function a(e) {
   return `Hello, ${e}!`;
 }
 export {
-  n as greet,
-  a as name
+  a as greet,
+  r as name,
+  n as resolveSidecars
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["/**\n * ai ui frontends\n *\n * @packageDocumentation\n */\n\n/** The published package name — handy for smoke tests. */\nexport const name = \"@habemus-papadum/aiui\";\n\n/** Greet someone. Replace with your library's real API. */\nexport function greet(who: string): string {\n  return `Hello, ${who}!`;\n}\n"],"names":["name","greet","who"],"mappings":"AAOO,MAAMA,IAAO;AAGb,SAASC,EAAMC,GAAqB;AACzC,SAAO,UAAUA,CAAG;AACtB;"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["/**\n * ai ui frontends\n *\n * The `aiui` CLI's library surface. Launch *policy* the CLI applies lives here\n * too, so sibling supervisors can reuse it instead of re-deriving it — the\n * first case is {@link resolveSidecars}, the `aiui claude` logic deciding\n * which session sidecars (e.g. the paint stream) a channel server should host for a\n * project root. The workbench imports it to give its debug channel the same\n * sidecar set a real session would get.\n *\n * @packageDocumentation\n */\n\nexport {\n  type ResolveSidecarsDeps,\n  resolveSidecars,\n  type SidecarDescriptor,\n} from \"./util/sidecars\";\n\n/** The published package name — handy for smoke tests. */\nexport const name = \"@habemus-papadum/aiui\";\n\n/** Greet someone. Replace with your library's real API. */\nexport function greet(who: string): string {\n  return `Hello, ${who}!`;\n}\n"],"names":["name","greet","who"],"mappings":";AAoBO,MAAMA,IAAO;AAGb,SAASC,EAAMC,GAAqB;AACzC,SAAO,UAAUA,CAAG;AACtB;"}

package/dist/sidecars-BKlhUA0V.js

@@ -0,0 +1,48 @@
+import { createRequire as c } from "node:module";
+const l = c(import.meta.url), n = [
+  {
+    // The iPad paint stream. Always on: it rides the channel's own port (no
+    // process, no extra listener), so hosting it costs nothing. Whether an
+    // iPad can actually REACH it is the channel bind's decision (`channel.bind`
+    // / `--aiui-bind`, asked at first run) — the security posture lives there,
+    // not here. `--aiui-no-sidecar paint` / `sidecars.paint: false` turn it off.
+    name: "paint",
+    autoEnable: () => !0,
+    descriptor: (a, o) => ({
+      name: "paint",
+      module: o("@habemus-papadum/aiui-paint/sidecar"),
+      export: "paintSidecar",
+      options: { root: a }
+    })
+  }
+];
+function u(a, o, i = {}) {
+  const d = i.resolveModule ?? ((e) => l.resolve(e)), s = i.log ?? ((e) => process.stderr.write(`[aiui] warning: ${e}
+`)), t = /* @__PURE__ */ new Set();
+  for (const e of n)
+    try {
+      e.autoEnable(a) && t.add(e.name);
+    } catch (r) {
+      s(
+        `sidecar "${e.name}" auto-detect failed: ${r instanceof Error ? r.message : String(r)}`
+      );
+    }
+  for (const e of o.enable)
+    n.some((r) => r.name === e) && t.add(e);
+  for (const e of o.disable)
+    t.delete(e);
+  return n.filter((e) => t.has(e.name)).map((e) => {
+    try {
+      return e.descriptor(a, d);
+    } catch (r) {
+      s(
+        `sidecar "${e.name}" disabled — its module failed to resolve: ${r instanceof Error ? r.message : String(r)}`
+      );
+      return;
+    }
+  }).filter((e) => e !== void 0);
+}
+export {
+  u as r
+};
+//# sourceMappingURL=sidecars-BKlhUA0V.js.map

package/dist/sidecars-BKlhUA0V.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecars-BKlhUA0V.js","sources":["../src/util/sidecars.ts"],"sourcesContent":["/**\n * Deciding which **session sidecars** the channel should host for a launch.\n *\n * A sidecar is an extra backend the channel mounts alongside the intent\n * pipeline — the concrete one today is the iPad paint stream. The channel takes\n * no dependency on any sidecar: `aiui claude` hands it a JSON array of\n * {@link SidecarDescriptor}s on `--sidecars`, and the channel dynamic-imports\n * each `module`, calls `mod[export ?? \"default\"](options)`, and mounts the\n * result (a bad descriptor is logged + skipped there).\n *\n * This module is the CLI's half: a small registry of the sidecars the launcher\n * knows how to construct, plus a pure resolver that decides which are on for a\n * given project root and set of `--aiui-sidecar` / `--aiui-no-sidecar` flags.\n */\n\nimport { createRequire } from \"node:module\";\n\nconst nodeRequire = createRequire(import.meta.url);\n\n/**\n * The contract the channel's `--sidecars` argument expects, mirrored here so\n * the CLI can emit it. The channel imports `module`, calls its `export` (or\n * `default`) with `options`, and mounts the returned sidecar.\n */\nexport interface SidecarDescriptor {\n  /** Stable identifier, used for `--aiui-sidecar`/`--aiui-no-sidecar` and logs. */\n  name: string;\n  /** Importable specifier the channel `import()`s (e.g. a package subpath). */\n  module: string;\n  /** Named export to call as the factory. Defaults to `\"default\"`. */\n  export?: string;\n  /** Passed opaquely to the factory (e.g. `{ root: \"/proj\" }`). */\n  options?: unknown;\n}\n\n/** Resolves a package specifier to an absolute path the channel can `import()`. */\ntype ResolveModule = (specifier: string) => string;\n\n/** Injectable seams, so the resolver is unit-testable without on-disk state. */\nexport interface ResolveSidecarsDeps {\n  /**\n   * Resolves a sidecar's package specifier to an ABSOLUTE path. Defaults to\n   * `createRequire(import.meta.url).resolve`. This matters: the channel\n   * dynamic-imports the descriptor's `module`, but it does NOT depend on any\n   * sidecar package — so a bare specifier resolves from the channel's own\n   * node_modules and fails (pnpm's isolated layout). Resolving here (from the\n   * `aiui` CLI, which DOES depend on the sidecar package) to an absolute path\n   * makes the import work in both the source-first workspace and an install.\n   */\n  resolveModule?: ResolveModule;\n  /** Warning sink for a sidecar that had to be dropped (defaults to stderr). */\n  log?: (message: string) => void;\n}\n\n/** A sidecar the CLI knows how to enable and construct, keyed by name. */\ninterface KnownSidecar {\n  name: string;\n  /** Whether this sidecar auto-enables for the given project root. */\n  autoEnable: (root: string) => boolean;\n  /** Build the descriptor the channel will mount for this root. */\n  descriptor: (root: string, resolveModule: ResolveModule) => SidecarDescriptor;\n}\n\n/**\n * The registry of sidecars the launcher can enable. Emit order follows this\n * list, so the resolver's output is stable regardless of flag order. The paint\n * stream is always on — see its entry.\n */\nconst KNOWN_SIDECARS: KnownSidecar[] = [\n  {\n    // The iPad paint stream. Always on: it rides the channel's own port (no\n    // process, no extra listener), so hosting it costs nothing. Whether an\n    // iPad can actually REACH it is the channel bind's decision (`channel.bind`\n    // / `--aiui-bind`, asked at first run) — the security posture lives there,\n    // not here. `--aiui-no-sidecar paint` / `sidecars.paint: false` turn it off.\n    name: \"paint\",\n    autoEnable: () => true,\n    descriptor: (root, resolveModule) => ({\n      name: \"paint\",\n      module: resolveModule(\"@habemus-papadum/aiui-paint/sidecar\"),\n      export: \"paintSidecar\",\n      options: { root },\n    }),\n  },\n];\n\n/**\n * Decide which session sidecars to host for `root`.\n *\n * Starts from the auto-detected set (each known sidecar whose `autoEnable`\n * predicate is truthy for this root), then applies the flags: `opts.enable`\n * force-adds a known sidecar by name even when it wouldn't auto-detect, and\n * `opts.disable` removes one. Disable wins over enable. Enable names the CLI\n * doesn't know how to construct are ignored (the launcher can only build the\n * sidecars in {@link KNOWN_SIDECARS}). Descriptors come back in the registry's\n * stable order.\n */\nexport function resolveSidecars(\n  root: string,\n  opts: { enable: string[]; disable: string[] },\n  deps: ResolveSidecarsDeps = {},\n): SidecarDescriptor[] {\n  const resolveModule =\n    deps.resolveModule ?? ((specifier: string) => nodeRequire.resolve(specifier));\n  const log =\n    deps.log ?? ((message: string) => process.stderr.write(`[aiui] warning: ${message}\\n`));\n  const enabled = new Set<string>();\n\n  // Auto-detected sidecars. A throwing detector must not kill the launch —\n  // warn and treat as not detected.\n  for (const known of KNOWN_SIDECARS) {\n    try {\n      if (known.autoEnable(root)) {\n        enabled.add(known.name);\n      }\n    } catch (err) {\n      log(\n        `sidecar \"${known.name}\" auto-detect failed: ${\n          err instanceof Error ? err.message : String(err)\n        }`,\n      );\n    }\n  }\n  // Force-enable, but only sidecars the CLI knows how to construct.\n  for (const name of opts.enable) {\n    if (KNOWN_SIDECARS.some((k) => k.name === name)) {\n      enabled.add(name);\n    }\n  }\n  // Disable wins over enable.\n  for (const name of opts.disable) {\n    enabled.delete(name);\n  }\n\n  return KNOWN_SIDECARS.filter((k) => enabled.has(k.name))\n    .map((k) => {\n      try {\n        return k.descriptor(root, resolveModule);\n      } catch (err) {\n        // The sidecar's package isn't resolvable (e.g. not installed) — skip it\n        // rather than failing the whole launch, but say so: silently dropping it\n        // would surface as \"the sidecar is mysteriously absent\".\n        log(\n          `sidecar \"${k.name}\" disabled — its module failed to resolve: ${\n            err instanceof Error ? err.message : String(err)\n          }`,\n        );\n        return undefined;\n      }\n    })\n    .filter((d): d is SidecarDescriptor => d !== undefined);\n}\n"],"names":["nodeRequire","createRequire","KNOWN_SIDECARS","root","resolveModule","resolveSidecars","opts","deps","specifier","log","message","enabled","known","err","name","k","d"],"mappings":";AAiBA,MAAMA,IAAcC,EAAc,YAAY,GAAG,GAmD3CC,IAAiC;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAME,MAAM;AAAA,IACN,YAAY,MAAM;AAAA,IAClB,YAAY,CAACC,GAAMC,OAAmB;AAAA,MACpC,MAAM;AAAA,MACN,QAAQA,EAAc,qCAAqC;AAAA,MAC3D,QAAQ;AAAA,MACR,SAAS,EAAE,MAAAD,EAAA;AAAA,IAAK;AAAA,EAClB;AAEJ;AAaO,SAASE,EACdF,GACAG,GACAC,IAA4B,CAAA,GACP;AACrB,QAAMH,IACJG,EAAK,kBAAkB,CAACC,MAAsBR,EAAY,QAAQQ,CAAS,IACvEC,IACJF,EAAK,QAAQ,CAACG,MAAoB,QAAQ,OAAO,MAAM,mBAAmBA,CAAO;AAAA,CAAI,IACjFC,wBAAc,IAAA;AAIpB,aAAWC,KAASV;AAClB,QAAI;AACF,MAAIU,EAAM,WAAWT,CAAI,KACvBQ,EAAQ,IAAIC,EAAM,IAAI;AAAA,IAE1B,SAASC,GAAK;AACZ,MAAAJ;AAAA,QACE,YAAYG,EAAM,IAAI,yBACpBC,aAAe,QAAQA,EAAI,UAAU,OAAOA,CAAG,CACjD;AAAA,MAAA;AAAA,IAEJ;AAGF,aAAWC,KAAQR,EAAK;AACtB,IAAIJ,EAAe,KAAK,CAACa,MAAMA,EAAE,SAASD,CAAI,KAC5CH,EAAQ,IAAIG,CAAI;AAIpB,aAAWA,KAAQR,EAAK;AACtB,IAAAK,EAAQ,OAAOG,CAAI;AAGrB,SAAOZ,EAAe,OAAO,CAACa,MAAMJ,EAAQ,IAAII,EAAE,IAAI,CAAC,EACpD,IAAI,CAACA,MAAM;AACV,QAAI;AACF,aAAOA,EAAE,WAAWZ,GAAMC,CAAa;AAAA,IACzC,SAASS,GAAK;AAIZ,MAAAJ;AAAA,QACE,YAAYM,EAAE,IAAI,8CAChBF,aAAe,QAAQA,EAAI,UAAU,OAAOA,CAAG,CACjD;AAAA,MAAA;AAEF;AAAA,IACF;AAAA,EACF,CAAC,EACA,OAAO,CAACG,MAA8BA,MAAM,MAAS;AAC1D;"}

package/dist/util/aiui-args.d.ts

@@ -6,6 +6,7 @@
  * begin with `--aiui-` so they're unambiguously distinguishable from flags meant
  * for the wrapped command (e.g. claude's `--resume`).
  */
+import { type ChannelBind } from "./config-schema";
 export interface AiuiArgs {
     /** The `--aiui-tag <tag>` value, if provided (the channel/MCP session tag). */
     tag?: string;
@@ -25,6 +26,18 @@ export interface AiuiArgs {
      * Code's built-in browser integration and forwards via passthrough.)
      */
     noChrome: boolean;
+    /**
+     * `--aiui-browser` was passed: open the wrapped tool's page in the session
+     * browser even where it would default off (CI / headless environments —
+     * e.g. `aiui vite` on a machine whose port *is* getting forwarded to one
+     * with a display).
+     */
+    browser: boolean;
+    /**
+     * `--aiui-no-browser` was passed: skip all session-browser activity (no
+     * tab opened, no browser launched) for this run.
+     */
+    noBrowser: boolean;
     /**
      * The `--aiui-chrome-profile <name>` value, if provided — which named Chrome
      * profile (user data dir under `.aiui-cache/chrome/`) to launch with.
@@ -42,6 +55,24 @@ export interface AiuiArgs {
      * `chrome.browserUrl` in config for this launch.
      */
     browserUrl?: string;
+    /**
+     * Names collected from repeatable `--aiui-sidecar <name>` flags — session
+     * sidecars to force-enable even when they wouldn't auto-detect for this
+     * project (e.g. `--aiui-sidecar paint`).
+     */
+    sidecar: string[];
+    /**
+     * Names collected from repeatable `--aiui-no-sidecar <name>` flags — session
+     * sidecars to disable for this run. Disable wins over enable.
+     */
+    noSidecar: string[];
+    /**
+     * The `--aiui-bind <loopback|host>` value, if provided — where the channel's
+     * web backend binds for this launch, overriding `channel.bind` in config.
+     * `host` is the trusted-LAN posture: the whole (unauthenticated) channel
+     * surface, iPad paint page included, becomes reachable from the network.
+     */
+    bind?: ChannelBind;
     /** Everything else, to forward verbatim to the wrapped tool. */
     passthrough: string[];
 }
@@ -65,12 +96,21 @@ export declare function infoFlag(passthrough: string[]): "help" | "version" | un
  *    MCP server to target (e.g. which session `aiui vite` should connect to).
  *  - `--aiui-chrome` / `--aiui-no-chrome` — force the Chrome DevTools MCP on
  *    (even under CI) / leave it off. Passing both is an error.
+ *  - `--aiui-browser` / `--aiui-no-browser` — force opening the page in the
+ *    session browser (even in CI/headless environments) / never open one.
+ *    Passing both is an error.
  *  - `--aiui-chrome-profile <name>` — launch Chrome with the named profile
  *    (created on first use under `.aiui-cache/chrome/<name>`).
  *  - `--aiui-chrome-data-dir <path>` — launch Chrome with an explicit user data
  *    dir instead of a named profile. Mutually exclusive with the above.
  *  - `--aiui-browser-url <url>` — attach the Chrome DevTools MCP to this
  *    endpoint (e.g. a tunneled remote browser) instead of managing one.
+ *  - `--aiui-sidecar <name>` / `--aiui-no-sidecar <name>` — force-enable /
+ *    disable a session sidecar by name. Both are repeatable and accumulate;
+ *    disable wins over enable when the same name appears in both.
+ *  - `--aiui-bind <loopback|host>` — where the channel's web backend binds for
+ *    this launch (see `channel.bind` in the config guide). Any other value is
+ *    an error.
  *
  * Any other `--aiui-*` flag throws, so a typo surfaces loudly instead of being
  * silently dropped or leaking into the child command.

package/dist/util/chrome.d.ts

@@ -19,10 +19,14 @@ type ChromeFlags = Pick<AiuiArgs, "chrome" | "noChrome" | "chromeProfile" | "chr
  * npx download + Chrome launch), with `--aiui-no-chrome`, or with
  * `chrome.enabled: false` in config. `--aiui-chrome` forces it on even under
  * CI; `chrome.enabled: true` merely restates the default and does not.
+ *
+ * Deliberately gated on CI alone, not the wider `isHeadless` check from
+ * aiui-util: on a headless-but-interactive box (SSH into a dev machine)
+ * the MCP still works — it just launches/attaches a headless-capable Chrome —
+ * whereas *opening a page for the user* would be pointless. Only commands that
+ * put a window in front of someone consult the broader signals.
  */
 export declare function chromeDevtoolsEnabled(args: Pick<ChromeFlags, "chrome" | "noChrome">, config?: ChromeConfig, env?: NodeJS.ProcessEnv): boolean;
-/** Truthy `CI` env var, with the conventional "false"/"0" escape hatches. */
-export declare function isCi(env?: NodeJS.ProcessEnv): boolean;
 /** The launch-relevant Chrome settings after flags and config are reconciled. */
 export interface ChromeSettings {
     /** Absolute user data dir for this launch. */

package/dist/util/config-schema.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The declarative schema for aiui's `config.json` — one table that drives
+ * everything config-shaped:
+ *
+ *   - validation (util/config.ts walks these sections instead of hand-rolled
+ *     per-key checks),
+ *   - the `aiui config` commands (show/get/set/unset use it to resolve keys,
+ *     parse CLI values, and report defaults),
+ *   - the `aiui config tui` browser (docs, defaults, and enum choices all
+ *     render from here).
+ *
+ * Because docs, defaults, and validation come from the same rows, they cannot
+ * drift apart. `docs/guide/config.md` remains the long-form narrative; the
+ * `doc` strings here are the terminal-sized versions.
+ *
+ * **How a component participates.** `CONFIG_SECTIONS` is the registry: a
+ * section is plain data, so a future component that grows file-backed settings
+ * (say, an `intent` section for the pipeline) joins by contributing one
+ * `ConfigSectionSchema` object here and a matching optional section on
+ * `AiuiConfig`. Nothing else — validation, show/get/set, and the TUI pick it
+ * up from the table. (The intent pipeline's current config is deliberately
+ * *not* here: it is per-app, passed as `aiuiDevOverlay({ intent: { … } })` in
+ * the app's Vite config — see docs/guide/intent-overlay.md.)
+ */
+export { CHROME_CHANNELS, type ChromeChannel } from "@habemus-papadum/aiui-util";
+export declare const FOR_TESTING_MODES: readonly ["prompt", "auto", "off"];
+export type ForTestingMode = (typeof FOR_TESTING_MODES)[number];
+export declare const CHROME_MODES: readonly ["attach", "launch"];
+export type ChromeMode = (typeof CHROME_MODES)[number];
+export declare const CHANNEL_BINDS: readonly ["loopback", "host"];
+export type ChannelBind = (typeof CHANNEL_BINDS)[number];
+/** Every config leaf is a JSON scalar; sections never nest further. */
+export type ConfigValue = boolean | number | string;
+export interface ConfigFieldSchema {
+    /** Leaf key within its section, e.g. `"skipPermissions"`. */
+    key: string;
+    /** `"enum"` is a string constrained to {@link values}. */
+    type: "boolean" | "number" | "string" | "enum";
+    /** The allowed values when {@link type} is `"enum"`. */
+    values?: readonly string[];
+    /** The built-in default, when the fallback is a plain value. */
+    default?: ConfigValue;
+    /**
+     * Human phrasing of the default when a bare value would mislead (dynamic
+     * fallbacks, first-run prompts). Shown instead of {@link default}.
+     */
+    defaultText?: string;
+    /** One-line summary — the TUI's list row. */
+    summary: string;
+    /** The rest of the documentation (terminal-sized; optional). */
+    doc?: string;
+    /**
+     * Constraint beyond type/enum. Returns the "expected …" tail of the error
+     * message, or undefined when the value is fine.
+     */
+    validate?: (value: ConfigValue) => string | undefined;
+}
+export interface ConfigSectionSchema {
+    /** Top-level key in config.json, e.g. `"chrome"`. */
+    name: string;
+    /** One-line summary of what the section configures. */
+    summary: string;
+    fields: ConfigFieldSchema[];
+}
+export declare const CONFIG_SECTIONS: ConfigSectionSchema[];
+/** A field paired with its section — what key-resolution hands back. */
+export interface ResolvedField {
+    section: ConfigSectionSchema;
+    field: ConfigFieldSchema;
+    /** The dotted path, e.g. `"chrome.mode"`. */
+    path: string;
+}
+/** Every field in schema order, with dotted paths. */
+export declare function allConfigFields(): ResolvedField[];
+/** Resolve a dotted path like `"chrome.mode"`; undefined when unknown. */
+export declare function findConfigField(path: string): ResolvedField | undefined;
+/** The `typeof` a field's values (enums are strings). */
+export declare function fieldRuntimeType(field: ConfigFieldSchema): "boolean" | "number" | "string";
+/**
+ * Constraint check beyond the runtime type: enum membership, then the field's
+ * own `validate`. Returns the "expected …" tail for the error, or undefined.
+ */
+export declare function invalidReason(field: ConfigFieldSchema, value: ConfigValue): string | undefined;
+/**
+ * Parse a CLI-provided string into the field's type and validate it — how
+ * `aiui config set` and the TUI turn text into a config value.
+ */
+export declare function parseFieldValue(field: ConfigFieldSchema, raw: string): {
+    value: ConfigValue;
+} | {
+    error: string;
+};
+/** Render a value the way config.json would hold it (strings quoted). */
+export declare function formatConfigValue(value: ConfigValue): string;
+/** The default, phrased for humans: `defaultText` wins, then the value, then "unset". */
+export declare function describeDefault(field: ConfigFieldSchema): string;