@yaag/cli 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.3.0",
-    "@yaag/tui": "0.3.0",
+    "@yaag/runtime": "0.4.0",
+    "@yaag/tui": "0.4.0",
     "typebox": "1.3.7"
   }
 }

package/src/argv.ts

@@ -7,6 +7,7 @@ import { resolve } from "node:path";
 export const USAGE = `usage:
   yaag run <program.ts> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
   yaag run --eval <source> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
+  yaag run --eval-fd <n> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
   yaag describe <program.ts>
   yaag setup-workspace [dir]
 
@@ -15,8 +16,12 @@ program file or --eval, but do not give both. A program that --eval runs can
 import "@yaag/runtime" and "typebox" only. A program that imports other modules
 must be a file.
 
-A --resume or --replay Run also needs the program: give the program file, or
---eval <source>. A Cassette holds the history of a Run, and never the program
+--eval-fd reads the program source from descriptor <n>, and needs the writer to
+close that descriptor. It keeps the source out of the process argument list,
+where every local user can read it. The yaag extension always uses it.
+
+A --resume or --replay Run also needs the program: give the program file,
+--eval <source>, or --eval-fd <n>. A Cassette holds the history of a Run, and never the program
 to run.
 
 Warning: describe imports the module and executes its top level. Keep program module top level side-effect free.`;
@@ -24,7 +29,8 @@ Warning: describe imports the module and executes its top level. Keep program mo
 /** The program one `run` invocation names: a file, or source text (ADR-0033). */
 export type ProgramSource =
   | { readonly kind: "file"; readonly file: string }
-  | { readonly kind: "inline"; readonly source: string };
+  | { readonly kind: "inline"; readonly source: string }
+  | { readonly kind: "inline-fd"; readonly fd: number };
 
 export type ParsedArgv =
   | {
@@ -60,6 +66,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
 function parseRun(tokens: readonly string[]): ParsedArgv {
   let file: string | undefined;
   let evalSource: string | undefined;
+  let evalFd: number | undefined;
   let args: unknown = {};
   let eventsFd: number | undefined;
   let record: string | undefined;
@@ -74,6 +81,7 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     } else if (
       token === "--args" ||
       token === "--eval" ||
+      token === "--eval-fd" ||
       token === "--events-fd" ||
       token === "--record" ||
       token === "--replay" ||
@@ -88,6 +96,10 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
         args = parsed.value;
       } else if (token === "--eval") {
         evalSource = value;
+      } else if (token === "--eval-fd") {
+        const parsed = parseEvalDescriptor(value);
+        if (!parsed.ok) return parsed;
+        evalFd = parsed.value;
       } else if (token === "--events-fd") {
         const parsed = parseDescriptor(value);
         if (!parsed.ok) return parsed;
@@ -108,9 +120,9 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     }
   }
 
-  const clash = conflict({ file, evalSource, record, replay, resume });
+  const clash = conflict({ file, evalSource, evalFd, eventsFd, record, replay, resume });
   if (clash !== null) return failure(`${clash}\n${USAGE}`);
-  const program = programSource(file, evalSource);
+  const program = programSource(file, evalSource, evalFd);
   if (program === undefined) return missingProgram(resume, replay);
   return {
     ok: true,
@@ -128,6 +140,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
 interface RunFlags {
   readonly file?: string;
   readonly evalSource?: string;
+  readonly evalFd?: number;
+  readonly eventsFd?: number;
   readonly record?: string;
   readonly replay?: string;
   readonly resume?: string;
@@ -135,10 +149,19 @@ interface RunFlags {
 
 /** Names the first pair of options that cannot appear in one invocation. */
 function conflict(flags: RunFlags): string | null {
-  const { file, evalSource, record, replay, resume } = flags;
+  const { file, evalSource, evalFd, eventsFd, record, replay, resume } = flags;
   if (file !== undefined && evalSource !== undefined) {
     return "--eval and a program file cannot be used together";
   }
+  if (evalSource !== undefined && evalFd !== undefined) {
+    return "--eval and --eval-fd cannot be used together";
+  }
+  if (file !== undefined && evalFd !== undefined) {
+    return "--eval-fd and a program file cannot be used together";
+  }
+  if (evalFd !== undefined && eventsFd !== undefined && evalFd === eventsFd) {
+    return "--eval-fd and --events-fd must use different descriptors";
+  }
   if (record !== undefined && replay !== undefined) {
     return "--record and --replay cannot be used together";
   }
@@ -159,7 +182,7 @@ function missingProgram(
   if (resume === undefined && replay === undefined) return failure(USAGE);
   const flag = resume !== undefined ? "--resume" : "--replay";
   return failure(
-    `${flag} needs the program too: give <program.ts> or --eval <source>. ` +
+    `${flag} needs the program too: give <program.ts>, --eval <source>, or --eval-fd <n>. ` +
       `A cassette holds the history of a Run, and never the program to run.\n${USAGE}`,
   );
 }
@@ -167,8 +190,10 @@ function missingProgram(
 function programSource(
   file: string | undefined,
   source: string | undefined,
+  fd: number | undefined,
 ): ProgramSource | undefined {
   if (source !== undefined) return { kind: "inline", source };
+  if (fd !== undefined) return { kind: "inline-fd", fd };
   return file === undefined ? undefined : { kind: "file", file };
 }
 
@@ -202,6 +227,14 @@ function parseDescriptor(value: string): ParsedValue<number> {
     : failure(`--events-fd must be a descriptor number\n${USAGE}`);
 }
 
+/** 0, 1 and 2 are stdin, stdout and stderr, so an Inline Program needs 3 or higher. */
+function parseEvalDescriptor(value: string): ParsedValue<number> {
+  const fd = Number(value);
+  return Number.isInteger(fd) && fd >= 3
+    ? { ok: true, value: fd }
+    : failure(`--eval-fd must be a descriptor number of 3 or higher\n${USAGE}`);
+}
+
 function failure(error: string): { readonly ok: false; readonly error: string } {
   return { ok: false, error };
 }

package/src/cli-tree-host.ts

@@ -6,9 +6,7 @@
  * caller adds `stop` and `done`: nothing in this module can prompt
  * an Agent (ADR — a Peek observes, it never sends).
  */
-import { readFile, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 import type { Terminal } from "@earendil-works/pi-tui";
 import type { AgentInfo } from "@yaag/runtime";
 import { cliKeybindings, type RunTreeViewHost, type TreeState } from "@yaag/tui";
@@ -21,8 +19,6 @@ export interface CliTreeHostOptions {
   /** Shows a transient message; `tree-app.ts` routes it to the TUI. */
   notify(message: string, level: "info" | "warning" | "error"): void;
   requestRender(): void;
-  /** Where `openEditor` puts the body; defaults to the system temp directory. */
-  readonly scratchDir?: string;
 }
 
 /** The read-only capabilities the CLI Run view has. */
@@ -41,17 +37,6 @@ export function createCliTreeHost(options: CliTreeHostOptions): ReadOnlyCliHost
     copyPath: async (text) => {
       terminal.write(`\u001b]52;c;${Buffer.from(text, "utf8").toString("base64")}\u0007`);
     },
-    // Spawning $EDITOR inside a live alt-screen would fight the TUI for the
-    // terminal, so the body lands in a file and the path is reported instead.
-    openEditor: async (title, body) => {
-      const path = join(options.scratchDir ?? tmpdir(), scratchName(title));
-      try {
-        await writeFile(path, body, "utf8");
-        options.notify(`Wrote ${title} to ${path}`, "info");
-      } catch (error) {
-        options.notify(`Could not write ${title}: ${message(error)}`, "error");
-      }
-    },
     notify: (text, level) => options.notify(text, level),
     requestRender: () => options.requestRender(),
     rows: () => Math.max(1, terminal.rows - 1),
@@ -70,12 +55,3 @@ async function readSession(info: AgentInfo | undefined): Promise<string | null>
     return null;
   }
 }
-
-function scratchName(title: string): string {
-  const slug = title.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "");
-  return `yaag-${slug === "" ? "note" : slug}.txt`;
-}
-
-function message(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/eval-fd.ts

@@ -0,0 +1,35 @@
+/**
+ * Reads the source of an Inline Program from a file descriptor (ADR-0033).
+ *
+ * An argv element is readable by every local user through `ps` and
+ * `/proc/<pid>/cmdline`, so the source of an Inline Program travels on a
+ * descriptor instead. Descriptor 3 stays exclusive to Run Lifecycle Events
+ * (ADR-0016), so the extension writes the source to descriptor 4.
+ */
+
+/** The descriptor the extension writes an Inline Program to; fd 3 is events. */
+export const DEFAULT_EVAL_FD = 4;
+
+/**
+ * Reads the whole Inline Program source from `fd`, until end of file.
+ *
+ * The read stops when the writer closes the descriptor, so a caller that
+ * keeps the descriptor open parks the Run before the program loads.
+ *
+ * Throws an `Error` that names the descriptor when the read fails, and when
+ * the descriptor gives no source.
+ */
+export async function readEvalSource(fd: number): Promise<string> {
+  let source: string;
+  try {
+    source = await Bun.file(fd).text();
+  } catch (error) {
+    throw new Error(`--eval-fd ${fd} cannot be read: ${String(error)}`);
+  }
+  if (source === "") {
+    throw new Error(
+      `--eval-fd ${fd} gave no source; write the Orchestration Program to the descriptor and close it`,
+    );
+  }
+  return source;
+}

package/src/inline-imports.ts

@@ -35,7 +35,7 @@ export function assertClosedImports(source: string): void {
     throw new Error(
       `inline program cannot import a computed specifier ` +
         `(import call on line ${computed.line}): ` +
-        `--eval allows ${allowedText()} only, each one as a string literal`,
+        `an Inline Program allows ${allowedText()} only, each one as a string literal`,
     );
   }
   const transpiler = new Bun.Transpiler({ loader: "ts" });
@@ -43,7 +43,7 @@ export function assertClosedImports(source: string): void {
     if (ALLOWED_INLINE_IMPORTS.includes(scanned.path)) continue;
     throw new Error(
       `inline program cannot import ${JSON.stringify(scanned.path)}: ` +
-        `--eval allows ${allowedText()} only`,
+        `an Inline Program allows ${allowedText()} only`,
     );
   }
 }
@@ -61,7 +61,7 @@ export function assertClosedImports(source: string): void {
  * by exactly one.
  */
 export function inlineRequirePrelude(): string {
-  const suffix = JSON.stringify(`: --eval allows ${allowedText()} only`);
+  const suffix = JSON.stringify(`: an Inline Program allows ${allowedText()} only`);
   return [
     "const require = ((real, allowed) => (id) => {",
     " if (allowed.includes(id)) return real(id);",

package/src/run-program.ts

@@ -1,6 +1,7 @@
 /**
- * Composes the two ways `yaag run` gets its Orchestration Program: a file, or
- * the source text of an Inline Program.
+ * Composes the ways `yaag run` gets its Orchestration Program: a file, or the
+ * source of an Inline Program. That source arrives as text, or on a
+ * descriptor (ADR-0033); the loader below does not know which.
  *
  * The composition sits above both loaders, so neither loader knows the other
  * and the imports stay a DAG.
@@ -8,6 +9,7 @@
 import { resolve } from "node:path";
 import type { OrchestrationProgram } from "@yaag/runtime";
 import type { ProgramSource } from "./argv.ts";
+import { readEvalSource } from "./eval-fd.ts";
 import { loadInlineProgram } from "./inline-program.ts";
 import { loadProgram } from "./program-loader.ts";
 
@@ -25,7 +27,9 @@ export interface LoadedProgram {
  * A file path is resolved against the working directory, and its
  * `programFile` is that absolute path. An Inline Program reports no
  * `programFile`, because its temporary module is unlinked after the import; it
- * reports its source text as its identity instead.
+ * reports its source text as its identity instead. A `--eval-fd` program is
+ * read to end of file first, so a writer that never closes the descriptor
+ * parks the Run (see `eval-fd.ts`).
  * Each failure of `loadProgram` or `loadInlineProgram` — a missing file, a
  * specifier outside the closed contract, a module that is not a program —
  * passes through unchanged.
@@ -42,5 +46,13 @@ export async function loadRunProgram(source: ProgramSource): Promise<LoadedProgr
         programFile: undefined,
         programSource: source.source,
       };
+    case "inline-fd": {
+      const text = await readEvalSource(source.fd);
+      return {
+        program: await loadInlineProgram(text),
+        programFile: undefined,
+        programSource: text,
+      };
+    }
   }
 }