@unigent/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gintas Zenevskis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,470 @@
+<p align="center">
+  <img src="https://github.com/gintasz/unigent/raw/refs/heads/main/assets/icon.svg" alt="Unigent" width="96" height="96" />
+</p>
+
+<h1 align="center">Unigent</h1>
+
+<p align="center"><strong>The cross-harness agent SDK for TypeScript.</strong></p>
+
+<p align="center">
+  Build stateful agent workflows with typed outputs, reusable tools, session forks, and ordinary TypeScript.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@unigent/sdk"><img alt="npm version" src="https://img.shields.io/npm/v/@unigent/sdk?logo=npm&logoColor=white" /></a>
+  <a href="https://github.com/gintasz/unigent/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-0A7EA4" /></a>
+  <a href="https://github.com/gintasz/unigent/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/gintasz/unigent?style=flat" /></a>
+  <img alt="Works with" src="https://img.shields.io/badge/works_with-555555" />
+  <a href="https://github.com/earendil-works/pi"><img alt="Pi SDK" src="https://img.shields.io/badge/Pi_SDK-7AA2F7" /></a>
+  <a href="https://docs.anthropic.com/en/docs/claude-code"><img alt="Claude CLI" src="https://img.shields.io/badge/Claude_Code-E5582B" /></a>
+  <a href="https://developers.openai.com/codex/cli/"><img alt="Codex CLI" src="https://img.shields.io/badge/Codex_CLI-10A37F" /></a>
+</p>
+
+<p align="center"><a href="https://github.com/gintasz/unigent/tree/main/examples">Examples</a></p>
+
+## Install
+
+Unigent requires Node.js 24 or newer.
+The live trace inspector (`unigent tui`) additionally requires [Bun](https://bun.sh/).
+Published packages are ESM-only.
+
+```bash
+npm install @unigent/sdk zod
+npm install -g @unigent/cli
+```
+
+The examples below use [Zod](https://zod.dev/), but Unigent accepts any
+[Standard Schema](https://standardschema.dev/) validator.
+
+### Drop-in Bun scripts
+
+For small automations, a single Bun script is often more comfortable than adding a `package.json`,
+lockfile, and local dependencies to a project. Start the file with `#!/usr/bin/env bun`; Unigent's
+CLI will use Bun in both normal and TUI mode, with missing-package fallback enabled. Imports are
+downloaded into Bun's global cache instead of creating project boilerplate.
+
+Copy [examples/standalone.ts](https://github.com/gintasz/unigent/blob/main/examples/standalone.ts)
+into a project and launch it through Unigent:
+
+```bash
+unigent standalone.ts "Write a launch announcement"
+unigent tui standalone.ts "Write a launch announcement"
+```
+
+The same file is directly executable when you do not need Unigent's trace transport or TUI:
+
+```bash
+chmod +x standalone.ts
+./standalone.ts "Write a launch announcement"
+```
+
+Pi reads models and authentication from your local Pi configuration. The Claude and Codex
+adapters use the authenticated official CLIs installed on your machine.
+
+👉 Your agent can invoke such workflow scripts with a bash command, isn't that cool?
+
+## Your first agent
+
+```typescript
+import { agent, piAgent } from "@unigent/sdk";
+
+const writer = agent({
+  name: "writer",
+  backend: piAgent(),
+  model: "openrouter/deepseek/deepseek-v4-flash",
+});
+
+const result = await writer.run("Write one sentence about durable software.");
+console.log(result.output);
+```
+
+`result` also contains token usage, any cost reported by the harness, and the full trace. The run
+starts immediately, can be aborted, and exposes its events as an async iterable while you await the
+final result.
+
+See [`examples/hello.ts`](https://github.com/gintasz/unigent/blob/main/examples/hello.ts) for the
+smallest complete script and
+[`examples/pitch.ts`](https://github.com/gintasz/unigent/blob/main/examples/pitch.ts) for a workflow
+using most of the API.
+
+## Choose what comes back
+
+Every run starts with `.run(prompt)`. The optional second argument controls what comes back: pass a
+schema for a typed value or `done` for side-effect-only work.
+
+```typescript
+import { done } from "@unigent/sdk";
+import { z } from "zod";
+
+const prose = await writer.run("Explain the tradeoff.");
+
+const structured = await writer.run(
+  "Choose the strongest title.",
+  z.object({ title: z.string(), score: z.number().min(0).max(100) }),
+);
+
+await writer.run("Update CHANGELOG.md.", done);
+```
+
+- Omit the second argument to return prose.
+- Pass a Standard Schema to return its inferred type.
+- Pass `done` when the work ends with side effects and no prose result is useful.
+
+`done` is a built-in completion sentinel schema. Passing it as the
+second argument makes Unigent expose the reserved `unigent_return` tool with an empty object input
+schema. The agent is instructed to call that tool after completing the requested side effects. An
+accepted call returns `void` and terminates the run before the agent writes a final prose response,
+saving tokens that the caller would otherwise discard.
+
+Structured output uses the same completion-tool protocol. Instead of the empty sentinel schema,
+`unigent_return` accepts a `value` matching the schema passed to `run()`.
+
+Structured values therefore never need to be scraped from prose: Markdown, preambles, and trailing
+commentary cannot corrupt the value. If the agent omits the completion call or returns an invalid
+value, Unigent repairs the turn a bounded number of times and then throws
+`AgentRepairExhaustedError`.
+
+## Give agents tools
+
+Pass ordinary named functions. Unigent reads their TypeScript signatures and JSDoc from the module
+named by `source`, then builds the tool definitions for the harness.
+
+```typescript
+/** Return the number of words in some copy.
+ *
+ * @promptSnippet Use this before accepting copy with a word limit.
+ * @promptGuideline Do not call wordCount repeatedly with unchanged text.
+ */
+function wordCount(text: string): number {
+  return text.trim().split(/\s+/u).length;
+}
+
+const editor = agent({
+  name: "editor",
+  source: import.meta.url,
+  backend: piAgent(),
+  model: "openrouter/deepseek/deepseek-v4-flash",
+  tools: [wordCount],
+});
+```
+
+The opening JSDoc prose is the tool description; there is no `@description` tag. Both prompt tags
+are optional. `@promptSnippet` adds a named entry to the system prompt's available-tools section.
+Each `@promptGuideline` becomes a standalone bullet in its guidelines section, without an automatic
+tool-name prefix, so every guideline must name its tool explicitly. This distinction follows Pi's
+native semantics. Claude Code and Codex do not expose equivalent tool fields, so Unigent renders
+both sections itself for every harness instead of appending either tag to the tool description.
+Omit the tags when that extra guidance is not worth its token cost. When TypeScript source is
+unavailable, the portable `tool({...})` helper accepts an explicit Standard Schema input.
+
+For compiled deployments, bake source-derived schemas after compiling the entry:
+
+```bash
+tsc && unigent bake src/worker.ts
+```
+
+This writes `worker.unigent-tools.json` beside the compiled `worker.js`. Production loads that
+manifest without installing or loading TypeScript; development can continue reflecting directly
+from a `.ts` entry when the optional `typescript` peer is installed.
+
+Only values listed in `tools` are callable. Deliberate agent failure is also opt-in:
+
+```typescript
+import { fail } from "@unigent/sdk";
+
+const reviewer = agent({ ...options, tools: [fail] });
+```
+
+Unigent does not rename ordinary function tools: `wordCount` is advertised as `wordCount`. To the
+agent, `unigent_fail` is another callable tool. It is special only at the TypeScript boundary:
+ordinary tool errors are recoverable feedback for the agent, while `unigent_fail` terminates the
+run and throws `AgentRaisedError` to the caller. Adding the `fail` sentinel opts the agent into that
+control tool; agents cannot deliberately abort a run unless the developer enables it. User-defined
+names beginning with `unigent_` are rejected because that namespace belongs to protocol tools such
+as `unigent_return` and `unigent_fail`.
+
+## Compose agents with functions
+
+An agent becomes a nested agent when you call it from a tool function.
+
+```typescript
+const researcher = agent({
+  name: "researcher",
+  backend: piAgent(),
+  model: "openrouter/deepseek/deepseek-v4-pro",
+});
+
+/** Research one question and return a concise finding. */
+async function research(question: string): Promise<string> {
+  const result = await researcher.run(question);
+  return result.output;
+}
+
+const author = agent({
+  name: "author",
+  source: import.meta.url,
+  backend: piAgent(),
+  model: "openrouter/deepseek/deepseek-v4-flash",
+  tools: [research],
+});
+```
+
+When the author calls `research`, the function opens another Unigent run. The nested run keeps its
+trace parentage, and its usage rolls up into the parent. The surrounding program still decides how
+many agents run, which work happens in parallel, and where results go next.
+
+## Keep a conversation and branch it
+
+Stateless runs are the default. A session keeps the harness conversation for later turns.
+
+```typescript
+const review = reviewer.session();
+
+await review.run(`
+Read the repository and learn its architecture, conventions, and current behavior.
+Trace the main execution paths and note the patterns that new code should follow.
+Do not review or modify anything yet; reply when you have enough context.
+`);
+
+const correctnessReview = review.fork();
+const maintainabilityReview = review.fork();
+
+const [correctness, maintainability] = await Promise.all([
+  correctnessReview.run("Review the codebase only for correctness and edge-case failures."),
+  maintainabilityReview.run("Review the codebase only for maintainability and API clarity."),
+]);
+```
+
+Both branches reuse the repository context gathered by the first turn instead of paying to rebuild
+it independently. All three official harnesses support forks. A session can be forked after its
+first completed turn, but not while a turn is active.
+
+## Group a workflow with scopes
+
+A scope groups related runs and owns their cumulative usage, traces, annotations, logs,
+cancellation, and deadline.
+
+```typescript
+const release = writer.scope("release", {
+  duration: "10m",
+  retainTraces: 50,
+  limits: { budgetUsd: 1 },
+});
+
+release.annotate({ pullRequest: 42 });
+release.log("drafting release notes");
+
+const draft = await release.scope("draft").run("Draft the notes.");
+await release.scope("publish").run(`Publish these notes: ${draft.output}`, done);
+
+console.log(release.usage);
+console.log(release.traces);
+```
+
+`.with(overrides)` returns an immutable agent variation with different configuration, such as a
+model, backend, system prompt, or per-turn limits. It does not create a new lifecycle or telemetry
+group; runs still belong to the current scope.
+
+`.scope(name, options)` creates a named workflow boundary. It can apply the same configuration
+overrides, but it also owns aggregate usage and traces, annotations and logs, cancellation, and an
+overall `duration` deadline. Nested scopes roll their usage and traces into their parent. Inherited
+limits can only tighten: `limits.turnDuration` caps each agent turn, while the scope's `duration`
+caps the whole grouped workflow. Explicit scopes retain the latest 50 completed root traces by
+default; set `retainTraces` to another bound or `0` to disable retention. Each run still returns its
+complete trace as `result.trace`.
+
+## Run and inspect scripts
+
+The CLI runs an ordinary TypeScript file as a child process. The file needs no TUI-specific code.
+Everything after the script path is forwarded to the script. A conventional `--` separator is
+also accepted for compatibility with command generators that insert one, but Unigent does not
+need it: its own option parsing stops at the script path.
+
+```bash
+unigent examples/pitch.ts "Kebab shop app"
+unigent tui examples/pitch.ts "Kebab shop app"
+```
+
+Trace events travel over an isolated channel, leaving the script's stdout and stderr alone. The
+TUI shows the live run tree, transcript, system prompt, tool calls, usage, errors, and process
+output.
+
+<p align="center">
+  <img src="https://github.com/gintasz/unigent/raw/refs/heads/main/assets/tui.png" alt="Unigent live trace inspector" width="1100" />
+</p>
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` | Select a trace row |
+| `Enter` | Expand or hide the selected agent's tool calls |
+| `s` | Show or hide the system prompt |
+| `o` | Switch between activity and process output |
+| `[` / `]` | Page through older or newer trace history |
+| `r` / `Ctrl-R` | Rerun or stop |
+| `q` | Quit |
+
+The trace retains its complete history in 250-row pages, and the activity pane keeps only its latest
+250 entries mounted. Both panes use viewport culling so off-screen content is not painted.
+
+## Parse script arguments
+
+`args()` parses `process.argv` through any Standard Schema. A scalar schema joins positional
+arguments into one natural value:
+
+```typescript
+import { args } from "@unigent/sdk";
+import { z } from "zod";
+
+const idea = await args(z.string().min(1));
+```
+
+The second argument is optional. Add it only when the script needs more useful `--help` output:
+
+```typescript
+const idea = await args(z.string().min(1), {
+  description: "Turn a product idea into an elevator pitch.",
+  usage: '"Product idea"',
+});
+```
+
+Ask the script to print the generated help without starting an agent run:
+
+```console
+$ unigent examples/pitch.ts --help
+Turn a product idea into a scored elevator pitch.
+
+Usage: pitch.ts "Product idea"
+```
+
+`args()` prints this standardized usage for `-h` or `--help`. Invalid input prints the schema's
+validation message and the same usage before exiting. Zod's default messages work without any
+authored message; customize them only when the default is not clear enough for your script.
+
+Object schemas accept named flags, defaults, repeated arrays, dotted paths, booleans, and `--no-*`
+negation:
+
+```typescript
+const input = await args(
+  z.object({
+    keyword: z.string(),
+    count: z.number().int().positive().default(1),
+    cache: z.boolean().default(true),
+  }),
+);
+```
+
+```bash
+unigent task.ts --keyword kebab --count 3 --no-cache
+```
+
+`--no-cache` sets the `cache` field to `false`; `--cache` sets it to `true`. The `no-` prefix is a
+conventional CLI negation for boolean flags, not part of the schema field name.
+
+## Resume finished work with checkpoints
+
+Checkpoints reuse successful stateless runs across reruns and deduplicate identical concurrent
+calls. Their fingerprint covers the prompt, return schema, harness adapter, model, system
+prompt, tools, and explicit checkpoint keys.
+
+```typescript
+import { agent, createFileCheckpointStore } from "@unigent/sdk";
+
+const defaults = {
+  backend: piAgent(),
+  checkpoint: createFileCheckpointStore(".unigent/checkpoints.jsonl"),
+  limits: { turnDuration: "5m" as const },
+};
+
+const writer = agent({ ...defaults, name: "writer", model: "model-a" });
+const reviewer = agent({ ...defaults, name: "reviewer", model: "model-b" });
+```
+
+Set `checkpointKey` when closed-over or ambient behavior changes the run's identity. Use
+`.with({ checkpoint: false })` for a fresh branch. Stateful session turns always run fresh because
+their result depends on the conversation transcript. A checkpoint replay restores the recorded
+usage, including `costUsd`; scope telemetry and budgets therefore describe the logical workflow,
+not only newly billed backend calls.
+
+Budget enforcement is exact for sequential work. Parallel siblings can each begin below the same
+remaining budget because their costs are unknown until they settle; a sibling that takes the scope
+over budget rejects after settlement, but the provider spend has already occurred.
+
+## Test without a model
+
+The SDK includes a deterministic harness adapter under its `test` subpath, so tests need no second
+Unigent package.
+
+```typescript
+import { agent } from "@unigent/sdk";
+import { createScriptedBackend } from "@unigent/sdk/test";
+import { z } from "zod";
+
+const backend = createScriptedBackend([
+  {
+    toolCalls: [
+      { name: "unigent_return", input: { value: { title: "Unigent" } } },
+    ],
+  },
+]);
+
+const subject = agent({ name: "subject", backend, model: "test" });
+const result = await subject.run("Name the project.", z.object({ title: z.string() }));
+
+expect(result.output).toEqual({ title: "Unigent" });
+expect(backend.requests).toHaveLength(1);
+```
+
+`createTestBackend` accepts a programmable turn handler. `createScriptedBackend` consumes
+declarative turns. Adapter authors can use `exerciseBackendContract` to run the shared prose,
+session, and fork contract against a new harness adapter.
+
+## Harnesses
+
+Unigent talks to each harness through a small adapter that opens sessions, runs turns, executes
+Unigent tools, streams events, reports usage, and forks conversations where supported.
+
+```typescript
+import { claudeCli, codexCli, piAgent } from "@unigent/sdk";
+
+const pi = piAgent();
+const claude = claudeCli();
+const codex = codexCli();
+```
+
+All three adapters default to `base: "clean"`, which starts without the machine's prompt,
+plugins, skills, hooks, or MCP configuration. Authentication, model configuration, and each
+harness's native tools remain available unless you restrict them. Set `base: "machine"` to inherit
+ambient harness configuration.
+
+| Capability | Pi agent SDK | Claude CLI | Codex CLI |
+| --- | --- | --- | --- |
+| Prose, structured output, `done`, `fail`, tools | Yes | Yes, through ephemeral local MCP | Yes, through ephemeral local MCP |
+| Cost reporting and budget enforcement | Yes | Yes | No; budget configuration fails fast |
+| Session continuation and forks | Yes | Yes, through CLI resume/fork flags | Yes; forks copy Codex's persisted session transcript under a new session ID |
+| Native tools | Exact allowlist; `[]` disables | `--tools` allowlist; may retain `ToolSearch` for MCP | `[]` disables shell and web search; no exact allowlist |
+| Plugins | Exact allowlist or disable | Exact installed-plugin allowlist or disable | No Unigent control |
+| Skills | Exact allowlist or disable | Inherit all with machine base or disable all; no named allowlist | Exact allowlist or disable |
+| Machine MCP servers and hooks | Pi has no built-in MCP; MCP extensions and hooks follow plugin selection | Inherit all with machine base or disable all; no named allowlist | Clean base ignores user config and rules; machine base inherits |
+| Permissions | Harness execution is unrestricted | Bypassed by default; `permissions: "cli"` defers to Claude | Bypassed by default; `permissions: "cli"` defers to Codex |
+
+Explicit adapter options override the inherited category where the harness can enforce them.
+Unsupported controls fail during setup instead of becoming silent no-ops.
+
+## Development
+
+```bash
+corepack pnpm install --frozen-lockfile
+corepack pnpm run typecheck
+corepack pnpm test
+corepack pnpm run test:tui
+corepack pnpm run test:e2e
+corepack pnpm run check:full
+```
+
+The deterministic suite uses no model. `test:tui` drives a real terminal without a model.
+`test:e2e` spends real Pi, Claude CLI, and Codex CLI turns and requires all three local harnesses
+to be authenticated.
+
+## License
+
+[MIT](https://github.com/gintasz/unigent/blob/main/LICENSE) © 2026 Gintas Zenevskis

package/dist/cli.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants as operatingSystemConstants } from "node:os";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { bakeSourceTools } from "@unigent/core";
+import packageManifest from "../package.json" with { type: "json" };
+import { parseCommand } from "./command.js";
+import { childProcessEnvironment } from "./environment.js";
+import { assertSupportedNodeVersion } from "./node_version.js";
+import { TRACE_TRANSPORT_ENVIRONMENT_VARIABLE } from "./protocol.js";
+import { detectScriptRuntime, runtimeInvocation } from "./script_runtime.js";
+const HELP = `unigent — run and inspect a Unigent script
+
+Usage:
+  unigent <file> [args...]      run a TypeScript or JavaScript file
+  unigent run <file> [args...]  same, explicitly
+  unigent tui <file> [args...]  open the live trace inspector
+  unigent bake <entry>          bake source-tool schemas for production
+  unigent --version             print the installed version
+
+Arguments after <file> are forwarded to the script. A conventional -- separator from command
+generators is accepted but not required because Unigent stops parsing at <file>. Bun shebangs are
+honored. TUI mode requires Bun.
+`;
+const DEVELOPMENT_LOADER_PREFIX = "--developmentLoader=";
+const SIGNAL_EXIT_CODE_BASE = 128;
+const INTERRUPTED_EXIT_CODE = 130;
+function parseInternalArguments(arguments_) {
+    const [first, ...remaining] = arguments_;
+    return first?.startsWith(DEVELOPMENT_LOADER_PREFIX) === true
+        ? {
+            developmentLoader: first.slice(DEVELOPMENT_LOADER_PREFIX.length),
+            commandArguments: remaining,
+        }
+        : { developmentLoader: undefined, commandArguments: arguments_ };
+}
+function packageEntry(name) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const extension of ["js", "ts", "tsx"]) {
+        const candidate = resolve(here, `${name}.${extension}`);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`unigent: ${name} entry not found`);
+}
+function signalExitCode(signal) {
+    return SIGNAL_EXIT_CODE_BASE + operatingSystemConstants.signals[signal];
+}
+function requireBun() {
+    const probe = spawnSync("bun", ["--version"], { stdio: "ignore" });
+    if (probe.error !== undefined) {
+        throw new Error("TUI mode requires Bun. Install it from https://bun.sh, then rerun `unigent tui`.");
+    }
+}
+async function spawnExitCode(executable, arguments_) {
+    return await new Promise((resolveCode, reject) => {
+        const environment = childProcessEnvironment({
+            [TRACE_TRANSPORT_ENVIRONMENT_VARIABLE]: undefined,
+        });
+        const child = spawn(executable, arguments_, { env: environment, stdio: "inherit" });
+        let interrupted = false;
+        const forwardInterrupt = () => {
+            interrupted = true;
+            child.kill("SIGINT");
+        };
+        process.on("SIGINT", forwardInterrupt);
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            process.removeListener("SIGINT", forwardInterrupt);
+            resolveCode(interrupted
+                ? INTERRUPTED_EXIT_CODE
+                : (code ?? (signal === null ? 1 : signalExitCode(signal))));
+        });
+    });
+}
+async function execute(command, developmentLoader) {
+    const runtime = runtimeInvocation(await detectScriptRuntime(command.sourceFile), process.execPath);
+    const developmentPreload = developmentLoader !== undefined && runtime.kind === "node"
+        ? ["--import", developmentLoader]
+        : [];
+    if (command.mode === "run") {
+        return await spawnExitCode(runtime.executable, [
+            ...runtime.arguments,
+            ...developmentPreload,
+            "--import",
+            packageEntry("register"),
+            command.sourceFile,
+            ...command.scriptArguments,
+        ]);
+    }
+    requireBun();
+    return await spawnExitCode("bun", [
+        packageEntry("tui"),
+        "--node",
+        process.execPath,
+        "--register",
+        packageEntry("register"),
+        ...(developmentLoader === undefined ? [] : [`--developmentLoader=${developmentLoader}`]),
+        command.sourceFile,
+        "--",
+        ...command.scriptArguments,
+    ]);
+}
+async function main() {
+    assertSupportedNodeVersion(process.versions.node);
+    const internal = parseInternalArguments(process.argv.slice(2));
+    const parsed = parseCommand(internal.commandArguments, process.cwd());
+    if (parsed.kind === "help") {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (parsed.kind === "version") {
+        process.stdout.write(`${packageManifest.version}\n`);
+        return 0;
+    }
+    if (parsed.kind === "bake") {
+        process.stdout.write(`${bakeSourceTools(parsed.command.sourceFile)}\n`);
+        return 0;
+    }
+    return await execute(parsed.command, internal.developmentLoader);
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`unigent: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,SAAS,IAAI,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,eAAe,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACpE,OAAO,EAAE,YAAY,EAAmB,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,oCAAoC,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7E,MAAM,IAAI,GAAG;;;;;;;;;;;;CAYZ,CAAC;AACF,MAAM,yBAAyB,GAAG,sBAAsB,CAAC;AACzD,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAOlC,SAAS,sBAAsB,CAAC,UAA6B;IAC3D,MAAM,CAAC,KAAK,EAAE,GAAG,SAAS,CAAC,GAAG,UAAU,CAAC;IACzC,OAAO,KAAK,EAAE,UAAU,CAAC,yBAAyB,CAAC,KAAK,IAAI;QAC1D,CAAC,CAAC;YACE,iBAAiB,EAAE,KAAK,CAAC,KAAK,CAAC,yBAAyB,CAAC,MAAM,CAAC;YAChE,gBAAgB,EAAE,SAAS;SAC5B;QACH,CAAC,CAAC,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC;AACrE,CAAC;AAED,SAAS,YAAY,CAAC,IAAwB;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,KAAK,MAAM,SAAS,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAU,EAAE,CAAC;QACrD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,SAAS,EAAE,CAAC,CAAC;QACxD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,kBAAkB,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,cAAc,CAAC,MAAsB;IAC5C,OAAO,qBAAqB,GAAG,wBAAwB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,UAAU;IACjB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnE,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,kFAAkF,CACnF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,UAAkB,EAAE,UAA6B;IAC5E,OAAO,MAAM,IAAI,OAAO,CAAS,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE;QACvD,MAAM,WAAW,GAAG,uBAAuB,CAAC;YAC1C,CAAC,oCAAoC,CAAC,EAAE,SAAS;SAClD,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACpF,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,MAAM,gBAAgB,GAAG,GAAS,EAAE;YAClC,WAAW,GAAG,IAAI,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC,CAAC;QACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAClC,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;YACnD,WAAW,CACT,WAAW;gBACT,CAAC,CAAC,qBAAqB;gBACvB,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAC7D,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,OAAO,CACpB,OAAmB,EACnB,iBAAqC;IAErC,MAAM,OAAO,GAAG,iBAAiB,CAC/B,MAAM,mBAAmB,CAAC,OAAO,CAAC,UAAU,CAAC,EAC7C,OAAO,CAAC,QAAQ,CACjB,CAAC;IACF,MAAM,kBAAkB,GACtB,iBAAiB,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;QACxD,CAAC,CAAC,CAAC,UAAU,EAAE,iBAAiB,CAAC;QACjC,CAAC,CAAC,EAAE,CAAC;IACT,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAC3B,OAAO,MAAM,aAAa,CAAC,OAAO,CAAC,UAAU,EAAE;YAC7C,GAAG,OAAO,CAAC,SAAS;YACpB,GAAG,kBAAkB;YACrB,UAAU;YACV,YAAY,CAAC,UAAU,CAAC;YACxB,OAAO,CAAC,UAAU;YAClB,GAAG,OAAO,CAAC,eAAe;SAC3B,CAAC,CAAC;IACL,CAAC;IACD,UAAU,EAAE,CAAC;IACb,OAAO,MAAM,aAAa,CAAC,KAAK,EAAE;QAChC,YAAY,CAAC,KAAK,CAAC;QACnB,QAAQ;QACR,OAAO,CAAC,QAAQ;QAChB,YAAY;QACZ,YAAY,CAAC,UAAU,CAAC;QACxB,GAAG,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,uBAAuB,iBAAiB,EAAE,CAAC,CAAC;QACxF,OAAO,CAAC,UAAU;QAClB,IAAI;QACJ,GAAG,OAAO,CAAC,eAAe;KAC3B,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,0BAA0B,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACtE,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,OAAO,IAAI,CAAC,CAAC;QACrD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACxE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AACnE,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;IACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport { spawn, spawnSync } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { constants as operatingSystemConstants } from \"node:os\";\nimport { dirname, resolve } from \"node:path\";\nimport process from \"node:process\";\nimport { fileURLToPath } from \"node:url\";\nimport { bakeSourceTools } from \"@unigent/core\";\nimport packageManifest from \"../package.json\" with { type: \"json\" };\nimport { parseCommand, type RunCommand } from \"./command.js\";\nimport { childProcessEnvironment } from \"./environment.js\";\nimport { assertSupportedNodeVersion } from \"./node_version.js\";\nimport { TRACE_TRANSPORT_ENVIRONMENT_VARIABLE } from \"./protocol.js\";\nimport { detectScriptRuntime, runtimeInvocation } from \"./script_runtime.js\";\n\nconst HELP = `unigent — run and inspect a Unigent script\n\nUsage:\n  unigent <file> [args...]      run a TypeScript or JavaScript file\n  unigent run <file> [args...]  same, explicitly\n  unigent tui <file> [args...]  open the live trace inspector\n  unigent bake <entry>          bake source-tool schemas for production\n  unigent --version             print the installed version\n\nArguments after <file> are forwarded to the script. A conventional -- separator from command\ngenerators is accepted but not required because Unigent stops parsing at <file>. Bun shebangs are\nhonored. TUI mode requires Bun.\n`;\nconst DEVELOPMENT_LOADER_PREFIX = \"--developmentLoader=\";\nconst SIGNAL_EXIT_CODE_BASE = 128;\nconst INTERRUPTED_EXIT_CODE = 130;\n\ninterface InternalArguments {\n  readonly developmentLoader: string | undefined;\n  readonly commandArguments: readonly string[];\n}\n\nfunction parseInternalArguments(arguments_: readonly string[]): InternalArguments {\n  const [first, ...remaining] = arguments_;\n  return first?.startsWith(DEVELOPMENT_LOADER_PREFIX) === true\n    ? {\n        developmentLoader: first.slice(DEVELOPMENT_LOADER_PREFIX.length),\n        commandArguments: remaining,\n      }\n    : { developmentLoader: undefined, commandArguments: arguments_ };\n}\n\nfunction packageEntry(name: \"register\" | \"tui\"): string {\n  const here = dirname(fileURLToPath(import.meta.url));\n  for (const extension of [\"js\", \"ts\", \"tsx\"] as const) {\n    const candidate = resolve(here, `${name}.${extension}`);\n    if (existsSync(candidate)) {\n      return candidate;\n    }\n  }\n  throw new Error(`unigent: ${name} entry not found`);\n}\n\nfunction signalExitCode(signal: NodeJS.Signals): number {\n  return SIGNAL_EXIT_CODE_BASE + operatingSystemConstants.signals[signal];\n}\n\nfunction requireBun(): void {\n  const probe = spawnSync(\"bun\", [\"--version\"], { stdio: \"ignore\" });\n  if (probe.error !== undefined) {\n    throw new Error(\n      \"TUI mode requires Bun. Install it from https://bun.sh, then rerun `unigent tui`.\",\n    );\n  }\n}\n\nasync function spawnExitCode(executable: string, arguments_: readonly string[]): Promise<number> {\n  return await new Promise<number>((resolveCode, reject) => {\n    const environment = childProcessEnvironment({\n      [TRACE_TRANSPORT_ENVIRONMENT_VARIABLE]: undefined,\n    });\n    const child = spawn(executable, arguments_, { env: environment, stdio: \"inherit\" });\n    let interrupted = false;\n    const forwardInterrupt = (): void => {\n      interrupted = true;\n      child.kill(\"SIGINT\");\n    };\n    process.on(\"SIGINT\", forwardInterrupt);\n    child.once(\"error\", reject);\n    child.once(\"exit\", (code, signal) => {\n      process.removeListener(\"SIGINT\", forwardInterrupt);\n      resolveCode(\n        interrupted\n          ? INTERRUPTED_EXIT_CODE\n          : (code ?? (signal === null ? 1 : signalExitCode(signal))),\n      );\n    });\n  });\n}\n\nasync function execute(\n  command: RunCommand,\n  developmentLoader: string | undefined,\n): Promise<number> {\n  const runtime = runtimeInvocation(\n    await detectScriptRuntime(command.sourceFile),\n    process.execPath,\n  );\n  const developmentPreload =\n    developmentLoader !== undefined && runtime.kind === \"node\"\n      ? [\"--import\", developmentLoader]\n      : [];\n  if (command.mode === \"run\") {\n    return await spawnExitCode(runtime.executable, [\n      ...runtime.arguments,\n      ...developmentPreload,\n      \"--import\",\n      packageEntry(\"register\"),\n      command.sourceFile,\n      ...command.scriptArguments,\n    ]);\n  }\n  requireBun();\n  return await spawnExitCode(\"bun\", [\n    packageEntry(\"tui\"),\n    \"--node\",\n    process.execPath,\n    \"--register\",\n    packageEntry(\"register\"),\n    ...(developmentLoader === undefined ? [] : [`--developmentLoader=${developmentLoader}`]),\n    command.sourceFile,\n    \"--\",\n    ...command.scriptArguments,\n  ]);\n}\n\nasync function main(): Promise<number> {\n  assertSupportedNodeVersion(process.versions.node);\n  const internal = parseInternalArguments(process.argv.slice(2));\n  const parsed = parseCommand(internal.commandArguments, process.cwd());\n  if (parsed.kind === \"help\") {\n    process.stdout.write(HELP);\n    return 0;\n  }\n  if (parsed.kind === \"version\") {\n    process.stdout.write(`${packageManifest.version}\\n`);\n    return 0;\n  }\n  if (parsed.kind === \"bake\") {\n    process.stdout.write(`${bakeSourceTools(parsed.command.sourceFile)}\\n`);\n    return 0;\n  }\n  return await execute(parsed.command, internal.developmentLoader);\n}\n\nmain().then(\n  (code) => {\n    process.exitCode = code;\n  },\n  (error: unknown) => {\n    process.stderr.write(`unigent: ${error instanceof Error ? error.message : String(error)}\\n`);\n    process.exitCode = 1;\n  },\n);\n"]}