@yaag/cli 0.1.4 → 0.2.1

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { writeSync } from "node:fs";
 import { resolve } from "node:path";
 import {
+  assertReplayable,
   executeRun,
   isOrchestrationProgram,
   isYaagError,
@@ -13,6 +13,7 @@ import {
 import { interactiveAvailable } from "./alt-screen.ts";
 import { parseArgv } from "./argv.ts";
 import { runInteractive } from "./interactive-run.ts";
+import { writeChannel, writeChannelFd } from "./output-channel.ts";
 import { createPlainPresenter } from "./presenter.ts";
 import { executeOptions, formatResult, type RunFlags } from "./run-invocation.ts";
 import { registerRuntimeAlias } from "./runtime-alias.ts";
@@ -24,18 +25,22 @@ registerRuntimeAlias();
 export async function main(argv: readonly string[]): Promise<number> {
   const parsed = parseArgv(argv);
   if (!parsed.ok) {
-    process.stderr.write(`${parsed.error}\n`);
+    writeChannel(process.stderr, `${parsed.error}\n`);
     return 2;
   }
 
   try {
     if (parsed.command === "setup-workspace") {
-      process.stdout.write(`${(await setupWorkspace(resolve(parsed.dir))).join("\n")}\n`);
+      writeChannel(process.stdout, `${(await setupWorkspace(resolve(parsed.dir))).join("\n")}\n`);
       return 0;
     }
-    // A bad artifact must fail before importing an arbitrary program module.
-    if (parsed.command === "run" && (parsed.replay !== undefined || parsed.resume !== undefined)) {
-      await loadCassette(parsed.replay ?? parsed.resume ?? "");
+    // A bad artifact must fail before importing an arbitrary program module,
+    // and an interrupted artifact is a bad artifact for strict replay (ADR-0031).
+    if (parsed.command === "run" && parsed.replay !== undefined) {
+      assertReplayable(await loadCassette(parsed.replay), parsed.replay);
+    }
+    if (parsed.command === "run" && parsed.resume !== undefined) {
+      await loadCassette(parsed.resume);
     }
     const programFile = resolve(parsed.file);
     const program = await loadProgram(programFile);
@@ -50,14 +55,18 @@ export async function main(argv: readonly string[]): Promise<number> {
       quiet: parsed.quiet,
     });
   } catch (error) {
-    process.stderr.write(`[yaag] ${error instanceof Error ? error.message : String(error)}\n`);
+    writeChannel(
+      process.stderr,
+      `[yaag] ${error instanceof Error ? error.message : String(error)}\n`,
+    );
     return parsed.command === "run" && isYaagError(error) && error.code === "ARGS_INVALID" ? 2 : 1;
   }
 }
 
 function describe(program: OrchestrationProgram): number {
   const definition = programDefinition(program);
-  process.stdout.write(
+  writeChannel(
+    process.stdout,
     `${JSON.stringify({
       name: definition.name ?? null,
       description: definition.description ?? null,
@@ -110,7 +119,7 @@ async function runPlain(program: OrchestrationProgram, flags: RunFlags): Promise
       executeOptions(flags, eventSink(flags.eventsFd, presenter.present), stop.signal),
     );
     const output = formatResult(result);
-    if (output !== null) process.stdout.write(`${output}\n`);
+    if (output !== null) writeChannel(process.stdout, `${output}\n`);
     return 0;
   } finally {
     process.off("SIGINT", onSignal);
@@ -128,7 +137,7 @@ async function runPlain(program: OrchestrationProgram, flags: RunFlags): Promise
  */
 function eventSink(fd: number | undefined, present: StampedEventSink): StampedEventSink {
   return (event) => {
-    if (fd !== undefined) writeSync(fd, `${JSON.stringify({ v: 1, ...event })}\n`);
+    if (fd !== undefined) writeChannelFd(fd, `${JSON.stringify({ v: 1, ...event })}\n`);
     present(event);
   };
 }

package/src/interactive-run.ts

@@ -1,8 +1,8 @@
 /**
- * The `yaag run` path that opens the alt-screen Run tree (spec §4).
+ * The `yaag run` path that opens the alt-screen Run tree (architecture §9).
  *
  * `orchestrateInteractiveRun` is process-free: every collaborator arrives as a
- * parameter, so each exit path — settle, detach, fatal render, signal — is
+ * parameter, so each exit path — settle, close, fatal render, signal — is
  * driven in tests without a TTY. `runInteractive` is the thin production edge
  * that binds it to the real terminal, the real signals, and the real streams.
  *
@@ -15,6 +15,7 @@ import type { RunViewResult, TreeState } from "@yaag/tui";
 import { createAltScreen } from "./alt-screen.ts";
 import { createFatalSignal, type FatalExit, type FatalSignal } from "./fatal-signal.ts";
 import { finalFrame } from "./final-frame.ts";
+import { writeChannel } from "./output-channel.ts";
 import { createPlainPresenter } from "./presenter.ts";
 import { errorText, executeOptions, formatResult, type RunFlags } from "./run-invocation.ts";
 import { type FinalOutput, startTreeApp, type TreeApp } from "./tree-app.ts";
@@ -62,9 +63,10 @@ export interface InteractiveRunDeps {
  * exit code of the Run.
  *
  * The terminal is restored before this resolves or rejects, on every path: the
- * settle-then-`q` path, a confirmed stop, a detach, and a render throw. A
- * detach closes the alt-screen and keeps awaiting the Run on the plain lines,
- * so the process never exits with a Run still running. A fatal render error is
+ * settle-then-`esc` path, a confirmed stop, an `esc` over a live Run, and a
+ * render throw. Closing the view over a live Run closes the alt-screen and
+ * keeps awaiting the Run on the plain lines, so the process never exits with a
+ * Run still running. A fatal render error is
  * reported only after the terminal is restored and the Run is aborted and
  * reaped, so no Run is abandoned pending. A fatal accepted at any point while
  * the handlers are installed is rethrown, never converted into a normal return.
@@ -117,7 +119,7 @@ export async function orchestrateInteractiveRun(deps: InteractiveRunDeps): Promi
     }
     const settled = await running;
     app.settle(viewResult(settled));
-    // The settled view stays interactive until the reader presses `q` (spec §1).
+    // The settled view stays interactive until the reader presses `esc`.
     const exit = await Promise.race([app.exit, signal.wait]);
     let fatal = exit.kind === "fatal" ? exit : signal.taken();
     const closing = app.close();
@@ -146,8 +148,8 @@ export async function runInteractive(options: InteractiveRunOptions): Promise<nu
         startTreeApp({
           tui: createAltScreen(),
           stop,
-          writeStdout: (text) => process.stdout.write(text),
-          writeStderr: (text) => process.stderr.write(text),
+          writeStdout: (text) => writeChannel(process.stdout, text),
+          writeStderr: (text) => writeChannel(process.stderr, text),
         }),
       startRun: (events, signal) =>
         executeRun(options.program, executeOptions(options.flags, options.events(events), signal)),

package/src/output-channel.ts

@@ -0,0 +1,35 @@
+/**
+ * Best-effort writes to the Run's output channels (architecture §9, ADR-0031).
+ *
+ * The Orchestrator is detached from its Host Session. When that session dies,
+ * stdout, stderr, and the events descriptor become broken pipes. A write to a
+ * broken pipe must not end the Run: it becomes a no-op, the Run keeps going as
+ * an Orphaned Run, and `yaag_stop` remains the way to end one.
+ */
+import { writeSync } from "node:fs";
+
+const silenced = new WeakSet<NodeJS.WriteStream>();
+
+/** Writes one chunk to a stream; a broken or failed pipe is ignored. */
+export function writeChannel(stream: NodeJS.WriteStream, text: string): void {
+  // A stream reports a broken pipe asynchronously, and an unheard `error`
+  // event ends the process. One no-op listener per stream absorbs it.
+  if (!silenced.has(stream)) {
+    silenced.add(stream);
+    stream.on("error", () => {});
+  }
+  try {
+    stream.write(text);
+  } catch {
+    // The Host Session closed the pipe; the Run continues without an observer.
+  }
+}
+
+/** Writes one whole line to a descriptor; a broken or failed pipe is ignored. */
+export function writeChannelFd(fd: number, text: string): void {
+  try {
+    writeSync(fd, text);
+  } catch {
+    // The Host Session closed the descriptor; the Run continues without an observer.
+  }
+}

package/src/presenter.ts

@@ -5,6 +5,7 @@
  * gets the interactive alt-screen tree instead (`tree-app.ts`).
  */
 import type { StampedEventSink } from "@yaag/runtime";
+import { writeChannel } from "./output-channel.ts";
 import { type PlainRenderMode, renderEvent } from "./render.ts";
 
 /**
@@ -24,7 +25,7 @@ export function createPlainPresenter(quiet: boolean): EventPresenter {
   return {
     present: (event) => {
       const rendered = renderEvent(event, mode);
-      if (rendered !== null) process.stderr.write(`${rendered}\n`);
+      if (rendered !== null) writeChannel(process.stderr, `${rendered}\n`);
     },
     dispose: () => {},
   };

package/src/runtime-alias.ts

@@ -1,11 +1,3 @@
-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",
@@ -39,6 +31,12 @@ let registered = false;
  */
 export function registerRuntimeAlias(): void {
   if (registered) return;
+  // Resolved from this CLI package (ADR-0018), so each entry is the same copy
+  // the CLI itself imports in the monorepo layout and in the published npm
+  // layout, where typebox is hoisted and no packages/ sibling exists. A
+  // failure here means a corrupt CLI install, so Bun's ResolveMessage stands.
+  const runtimeEntry = Bun.resolveSync("@yaag/runtime", import.meta.dir);
+  const typeboxEntry = Bun.resolveSync("typebox", import.meta.dir);
   Bun.plugin({
     name: "yaag-runtime-entry-alias",
     setup(build) {

package/src/tree-app.ts

@@ -1,6 +1,6 @@
 /**
  * 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).
+ * Session opens, hosted in an alt-screen pi-tui app (architecture §9).
  *
  * Every collaborator arrives as a parameter, so the app is driven in tests over
  * a recording terminal; `alt-screen.ts` owns the real `ProcessTerminal`.
@@ -28,7 +28,6 @@ export interface TreeAppDeps {
 /** 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). */
@@ -43,7 +42,7 @@ export interface FinalOutput {
 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. */
+  /** Resolves when the reader closes the view, or a render throws. */
   readonly exit: Promise<TreeAppExit>;
   /** Folds one Lifecycle Event into the projection and redraws. */
   present(event: LifecycleEvent): void;
@@ -54,7 +53,7 @@ export interface TreeApp {
   /**
    * 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
+   * `esc` closes the alt-screen while the Run is still live, so this step is
    * separate from the final channel emission.
    */
   close(): Promise<void>;
@@ -98,13 +97,11 @@ export function startTreeApp(deps: TreeAppDeps): TreeApp {
     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" }),
+      // A CLI has no background surface, so closing the view closes the
+      // alt-screen and the caller keeps awaiting the Run on the plain lines.
+      done: () => resolveExit({ kind: "dismissed" }),
     },
     ...(deps.label === undefined ? {} : { label: deps.label }),
-    surface: "foreground",
     ...(deps.now === undefined ? {} : { now: deps.now }),
   });