@yaag/cli 0.1.0

package/src/runtime-alias.ts

@@ -0,0 +1,64 @@
+import { fileURLToPath } from "node:url";
+
+const runtimeEntry = fileURLToPath(
+  new URL("../../../packages/runtime/src/index.ts", import.meta.url),
+);
+const typeboxEntry = fileURLToPath(
+  new URL("../node_modules/typebox/build/index.mjs", import.meta.url),
+);
+const runtimeValues = [
+  "CASSETTE_VERSION",
+  "loadCassette",
+  "defineAgent",
+  "isAgentDefinition",
+  "agentDefinitionConfig",
+  "defineRun",
+  "isOrchestrationProgram",
+  "programDefinition",
+  "isYaagError",
+  "YaagError",
+  "prompt",
+  "reap",
+  "recordingTransport",
+  "replayTransport",
+  "resumeTransport",
+  "executeRun",
+  "applyEvent",
+  "initialSummary",
+  "worktreeTransport",
+].join(", ");
+let registered = false;
+
+/**
+ * Pins bare program imports to runtime dependencies shipped with this CLI.
+ *
+ * Exact `@yaag/runtime` and `typebox` imports resolve through virtual modules.
+ * Their subpaths (`@yaag/runtime/*` and `typebox/*`) deliberately remain under
+ * Bun's normal resolver. Registration is idempotent because in-process CLI
+ * tests may call `main()` repeatedly.
+ */
+export function registerRuntimeAlias(): void {
+  if (registered) return;
+  Bun.plugin({
+    name: "yaag-runtime-entry-alias",
+    setup(build) {
+      // Bun 1.3 can skip onResolve for scoped @yaag/runtime imports, while a
+      // nearby .yaag/tsconfig.json paths entry can preempt onResolve for bare
+      // typebox. Exact virtual modules take precedence in both cases.
+      build.module("@yaag/runtime", () => ({
+        contents: `export { ${runtimeValues} } from ${JSON.stringify(runtimeEntry)};`,
+        loader: "ts",
+      }));
+      build.module("typebox", () => ({
+        contents: [
+          `export * from ${JSON.stringify(typeboxEntry)};`,
+          `export { default } from ${JSON.stringify(typeboxEntry)};`,
+        ].join("\n"),
+        loader: "ts",
+      }));
+      build.onResolve({ filter: /^@yaag\/runtime$/ }, () => ({ path: runtimeEntry }));
+      build.onResolve({ filter: /^typebox$/ }, () => ({ path: typeboxEntry }));
+    },
+  });
+  registered = true;
+}

package/src/setup-workspace.ts

@@ -0,0 +1,91 @@
+import { cp, lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TYPES_ASSET_DIRECTORY = fileURLToPath(new URL("../assets/types/", import.meta.url));
+const TYPES_IGNORE_ENTRY = ".yaag/types/";
+
+const TSCONFIG = `${JSON.stringify(
+  {
+    compilerOptions: {
+      target: "ESNext",
+      module: "Preserve",
+      moduleResolution: "bundler",
+      lib: ["ESNext"],
+      strict: true,
+      skipLibCheck: true,
+      noEmit: true,
+      verbatimModuleSyntax: true,
+      moduleDetection: "force",
+      allowImportingTsExtensions: true,
+      types: [],
+      paths: {
+        "@yaag/runtime": ["./types/runtime/index.d.ts"],
+        typebox: ["./types/typebox/build/index.d.mts"],
+        "typebox/*": ["./types/typebox/build/*/index.d.mts"],
+      },
+    },
+    include: ["./**/*.ts"],
+  },
+  null,
+  2,
+)}\n`;
+
+/**
+ * Materializes editor declarations and configuration inside a workspace's `.yaag` directory.
+ *
+ * Replaces only the owned declarations tree, preserves an existing configuration, and rejects
+ * filesystem failures from the requested workspace.
+ */
+export async function setupWorkspace(directory: string): Promise<readonly string[]> {
+  const ownedDirectory = join(directory, ".yaag");
+  const typesDirectory = join(ownedDirectory, "types");
+  const configPath = join(ownedDirectory, "tsconfig.json");
+  const ignorePath = join(directory, ".gitignore");
+
+  await mkdir(ownedDirectory, { recursive: true });
+  const typesReport = await replaceTypes(typesDirectory);
+  const configReport = await writeConfigIfAbsent(configPath);
+  const ignoreReport = await updateGitignoreIfPresent(ignorePath);
+  return [typesReport, configReport, ignoreReport];
+}
+
+async function replaceTypes(destination: string): Promise<string> {
+  const existed = await exists(destination);
+  await rm(destination, { recursive: true, force: true });
+  await cp(TYPES_ASSET_DIRECTORY, destination, { recursive: true });
+  return existed ? ".yaag/types/: written (refreshed)" : ".yaag/types/: written";
+}
+
+async function writeConfigIfAbsent(path: string): Promise<string> {
+  if (await exists(path)) return ".yaag/tsconfig.json: skipped (already exists)";
+  await writeFile(path, TSCONFIG);
+  return ".yaag/tsconfig.json: written";
+}
+
+async function updateGitignoreIfPresent(path: string): Promise<string> {
+  if (!(await exists(path))) return ".gitignore: skipped (file does not exist)";
+  const contents = await readFile(path, "utf8");
+  if (contents.split(/\r?\n/).includes(TYPES_IGNORE_ENTRY)) {
+    return ".gitignore: skipped (already present)";
+  }
+  await writeFile(
+    path,
+    `${contents}${contents.endsWith("\n") || contents === "" ? "" : "\n"}${TYPES_IGNORE_ENTRY}\n`,
+  );
+  return ".gitignore: written";
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}

package/src/tree-app.ts

@@ -0,0 +1,178 @@
+/**
+ * The standalone CLI's interactive Run view: the same `@yaag/tui` tree the Host
+ * Session opens, hosted in an alt-screen pi-tui app (spec §4).
+ *
+ * Every collaborator arrives as a parameter, so the app is driven in tests over
+ * a recording terminal; `alt-screen.ts` owns the real `ProcessTerminal`.
+ */
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { LifecycleEvent } from "@yaag/runtime";
+import { createRunTreeView, type RunViewResult, TreeState } from "@yaag/tui";
+import { createCliTreeHost } from "./cli-tree-host.ts";
+
+/** Shown in place of the tree when its own render throws. */
+const FATAL_LINE = "[yaag] the Run view failed to render; leaving the alt-screen";
+
+/** Everything the app needs; none of it is read from the process. */
+export interface TreeAppDeps {
+  readonly tui: TUI;
+  /** Runs the reap ladder for this Run (ADR-0008). */
+  stop(): void;
+  writeStdout(text: string): void;
+  writeStderr(text: string): void;
+  /** The Run id, e.g. `r1`; heads the tree. */
+  readonly label?: string;
+  now?(): number;
+}
+
+/** How the app ended. A fatal exit still restored the terminal. */
+export type TreeAppExit =
+  | { readonly kind: "dismissed" }
+  | { readonly kind: "detached" }
+  | { readonly kind: "fatal"; readonly error: unknown };
+
+/** What `finish` writes after the alt-screen closes (architecture §9). */
+export interface FinalOutput {
+  /** The pipeable Run result for stdout, or null when the Run returned none. */
+  readonly result: string | null;
+  /** The final summary frame for stderr. */
+  readonly frame: readonly string[];
+}
+
+/** The running app: one Run, one alt-screen, one teardown. */
+export interface TreeApp {
+  /** The projection the view reads; the caller renders the final frame from it. */
+  readonly state: TreeState;
+  /** Resolves when the reader dismisses or detaches, or a render throws. */
+  readonly exit: Promise<TreeAppExit>;
+  /** Folds one Lifecycle Event into the projection and redraws. */
+  present(event: LifecycleEvent): void;
+  /** The Run settled: freeze the tree and show the Result region. */
+  settle(result: RunViewResult): void;
+  /** SIGINT: opens the stop prompt, and a second one confirms the stop. */
+  interrupt(): void;
+  /**
+   * Drains input and leaves the alt-screen, writing no channel. Once.
+   *
+   * A detach closes the alt-screen while the Run is still live, so this step is
+   * separate from the final channel emission.
+   */
+  close(): Promise<void>;
+  /** Writes the Run result to stdout and the final frame to stderr. Once. */
+  emit(final: FinalOutput): void;
+  /** `close` then `emit`, for the paths where the Run already settled. */
+  finish(final: FinalOutput): Promise<void>;
+}
+
+/**
+ * Starts the alt-screen app over a fresh `TreeState`.
+ *
+ * A render error never escapes: it resolves `exit` as fatal and the caller's
+ * `finish` still restores the terminal. `finish` is idempotent, so the stop
+ * path and the throw path can both call it.
+ */
+export function startTreeApp(deps: TreeAppDeps): TreeApp {
+  const state = new TreeState();
+  const tui = deps.tui;
+  let settleExit: ((exit: TreeAppExit) => void) | undefined;
+  const exit = new Promise<TreeAppExit>((resolve) => {
+    settleExit = resolve;
+  });
+  const resolveExit = (value: TreeAppExit): void => {
+    settleExit?.(value);
+    settleExit = undefined;
+  };
+  let notice: string | undefined;
+
+  const host = createCliTreeHost({
+    terminal: tui.terminal,
+    state,
+    notify: (message) => {
+      notice = message;
+      tui.requestRender();
+    },
+    requestRender: () => tui.requestRender(),
+  });
+  const view = createRunTreeView({
+    state,
+    host: {
+      ...host,
+      stop: deps.stop,
+      // A CLI has no background surface, so a detach closes the alt-screen and
+      // the caller keeps awaiting the Run on the plain line presenter.
+      detach: () => resolveExit({ kind: "detached" }),
+      done: (kind) => resolveExit({ kind: kind === "detached" ? "detached" : "dismissed" }),
+    },
+    ...(deps.label === undefined ? {} : { label: deps.label }),
+    surface: "foreground",
+    ...(deps.now === undefined ? {} : { now: deps.now }),
+  });
+
+  const root: Component = {
+    render: (width) => {
+      try {
+        const lines = view.render(width);
+        return notice === undefined ? lines : [...lines, notice.slice(0, width)];
+      } catch (error) {
+        resolveExit({ kind: "fatal", error });
+        return [FATAL_LINE];
+      }
+    },
+    handleInput: (data) => {
+      view.handleInput(data);
+    },
+    invalidate: () => view.invalidate(),
+  };
+
+  tui.addChild(root);
+  tui.setFocus(root);
+  // `TuiBase.start` installs raw mode and the resize → requestRender callback
+  // itself (pi-tui `tui.js` start), so nothing here re-wires either.
+  tui.start();
+
+  let closed: Promise<void> | undefined;
+  let emitted = false;
+  const close = (): Promise<void> => {
+    closed ??= teardown(deps, view.dispose);
+    return closed;
+  };
+  const emit = (final: FinalOutput): void => {
+    if (emitted) return;
+    emitted = true;
+    if (final.result !== null) deps.writeStdout(`${final.result}\n`);
+    if (final.frame.length > 0) deps.writeStderr(`${final.frame.join("\n")}\n`);
+  };
+  return {
+    state,
+    exit,
+    present(event: LifecycleEvent): void {
+      state.apply(event);
+      view.touch();
+    },
+    settle(result: RunViewResult): void {
+      view.settle(result);
+    },
+    interrupt(): void {
+      view.interrupt();
+    },
+    close,
+    emit,
+    async finish(final: FinalOutput): Promise<void> {
+      await close();
+      emit(final);
+    },
+  };
+}
+
+/**
+ * Drains trailing key-release bytes and leaves the alt-screen.
+ *
+ * `preserveScreen` is load-bearing: the default `stop()` replays the last
+ * document through the terminal, which writes to stdout, and that would put
+ * tree glyphs in front of the pipeable Run result (architecture §9).
+ */
+async function teardown(deps: TreeAppDeps, dispose: () => void): Promise<void> {
+  dispose();
+  await deps.tui.terminal.drainInput();
+  deps.tui.stop({ preserveScreen: true });
+}

package/src/tui-test-support.ts

@@ -0,0 +1,96 @@
+/**
+ * A recording `Terminal` the tests drive a real `TuiAltScreen` over.
+ *
+ * Bun has no PTY primitive, so this double is how the teardown order, the
+ * preserved main screen, and a fatal render error are asserted without a
+ * terminal (ADR-0011). It lives beside the source rather than in a test file,
+ * because both `tree-app.test.ts` and future CLI tests drive it.
+ */
+import type { Terminal } from "@earendil-works/pi-tui";
+
+/** One recorded terminal call, in the order the TUI made it. */
+export type TerminalCall =
+  | { readonly kind: "write"; readonly data: string }
+  | { readonly kind: "drainInput" }
+  | { readonly kind: "start" }
+  | { readonly kind: "stop" }
+  | { readonly kind: "hideCursor" }
+  | { readonly kind: "showCursor" };
+
+/** Fixed terminal geometry; the double never resizes itself. */
+export interface RecordingTerminalOptions {
+  readonly columns?: number;
+  readonly rows?: number;
+}
+
+/** A `Terminal` that records every call and lets a test push input. */
+export class RecordingTerminal implements Terminal {
+  readonly calls: TerminalCall[] = [];
+  readonly columns: number;
+  readonly rows: number;
+  #onInput: ((data: string) => void) | undefined;
+  #onResize: (() => void) | undefined;
+
+  constructor(options: RecordingTerminalOptions = {}) {
+    this.columns = options.columns ?? 100;
+    this.rows = options.rows ?? 24;
+  }
+
+  /** Everything written to the terminal, concatenated in order. */
+  get output(): string {
+    return this.calls.map((call) => (call.kind === "write" ? call.data : "")).join("");
+  }
+
+  /** The names of the recorded calls, for an ordering assertion. */
+  get order(): readonly TerminalCall["kind"][] {
+    return this.calls.map((call) => call.kind);
+  }
+
+  /** Delivers one input byte string, as `StdinBuffer` would. */
+  emitInput(data: string): void {
+    this.#onInput?.(data);
+  }
+
+  /** Fires the resize callback the TUI installed. */
+  emitResize(): void {
+    this.#onResize?.();
+  }
+
+  start(onInput: (data: string) => void, onResize: () => void): void {
+    this.#onInput = onInput;
+    this.#onResize = onResize;
+    this.calls.push({ kind: "start" });
+  }
+
+  stop(): void {
+    this.calls.push({ kind: "stop" });
+  }
+
+  async drainInput(): Promise<void> {
+    this.calls.push({ kind: "drainInput" });
+  }
+
+  write(data: string): void {
+    this.calls.push({ kind: "write", data });
+  }
+
+  get kittyProtocolActive(): boolean {
+    return false;
+  }
+
+  moveBy(): void {}
+
+  hideCursor(): void {
+    this.calls.push({ kind: "hideCursor" });
+  }
+
+  showCursor(): void {
+    this.calls.push({ kind: "showCursor" });
+  }
+
+  clearLine(): void {}
+  clearFromCursor(): void {}
+  clearScreen(): void {}
+  setTitle(): void {}
+  setProgress(): void {}
+}