create-mono-agent 0.5.1

package/README.md

@@ -0,0 +1,79 @@
+# create-mono-agent
+
+The unscoped npm-init installer for the mono-agent CLI. It ships two bins —
+`create-mono-agent` and `mono-agent` — each of which delegates every command to
+the CLI that lives in [`@mono-agent/agent-app`](https://www.npmjs.com/package/@mono-agent/agent-app).
+
+Three equivalent entry points, one behaviour:
+
+- `npm create mono-agent@latest` — npm's `create-*` convention resolves this package (no install).
+- `npx create-mono-agent` — the same, spelled explicitly.
+- `npm i -g create-mono-agent` — a global install that puts the natural `mono-agent` command on your `PATH`.
+
+The bare `mono-agent` npm name is unavailable — npm rejects it as too similar to
+an unrelated `monoagent` package — so this installer follows the `create-*`
+convention while still exposing the ergonomic `mono-agent` bin.
+
+## Category
+
+Category: `app`
+
+This is the catalog's sole `tier: "alias"` package: an unscoped publishable
+installer, not a core package with its own responsibility. It is excluded from the
+core/plugin package counts and carries no library API.
+
+## Responsibility
+
+Provide the discoverable, unscoped `create-mono-agent` name on npm so
+`npm create mono-agent`/`npx create-mono-agent` and a global `mono-agent` command
+work, and forward every invocation, unchanged, to `@mono-agent/agent-app`'s
+`mono-agent` CLI. It owns no CLI behaviour of its own.
+
+## Install / Usage
+
+```bash
+# One-off, no install (npm-init convention resolves create-mono-agent):
+npm create mono-agent@latest init
+npx create-mono-agent init
+
+# Or install globally for the persistent `mono-agent` command:
+npm i -g create-mono-agent
+mono-agent init
+mono-agent validate
+mono-agent --version
+```
+
+Every command, flag, and exit code is exactly what `@mono-agent/agent-app`
+provides — including interactive shutdown: Ctrl-C on `mono-agent start --foreground`
+runs the same graceful teardown and yields the same exit status as calling
+agent-app's bin directly (the bin forwards signals without double-signalling the
+child; see `delegateSignals`). This package adds nothing but the names. Prefer
+pinning the scoped host directly (`npm i -g @mono-agent/agent-app`) if you don't
+need the installer.
+
+## Public API
+
+None. This package exports no library surface; it ships `create-mono-agent` and
+`mono-agent` bins that both delegate to `@mono-agent/agent-app`.
+
+## Dependency Boundary
+
+Depends only on `@mono-agent/agent-app` (category `app`) at the same lockstep
+version, resolved at runtime through its published `bin`. It must not depend on
+runtime, communication, memory, observability, or operator-surface packages, and
+it must not reimplement any CLI logic.
+
+## What This Package Does Not Own
+
+It does not parse args, load config, run models, scaffold files, or define any
+command — all of that lives in `@mono-agent/agent-app`. It is metadata plus a
+delegating bin, nothing more. If the installer ever needs behaviour, that
+behaviour belongs in `@mono-agent/agent-app`, not here.
+
+## Verification
+
+```bash
+pnpm --filter create-mono-agent run build
+pnpm --filter create-mono-agent run typecheck
+pnpm --filter create-mono-agent run test
+```

package/dist/bin/mono-agent.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=mono-agent.d.ts.map

package/dist/bin/mono-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mono-agent.d.ts","sourceRoot":"","sources":["../../src/bin/mono-agent.ts"],"names":[],"mappings":""}

package/dist/bin/mono-agent.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { delegateSignals } from "../delegate.js";
+import { resolveAgentAppCliEntry } from "../resolve-agent-app-cli.js";
+/**
+ * Delegating bin for the `create-mono-agent` installer. Both of its bin names
+ * (`create-mono-agent` and `mono-agent`) point here. It owns no CLI logic of its
+ * own: it locates `@mono-agent/agent-app`'s `mono-agent` CLI entry and runs it in a
+ * child process with the same args and inherited stdio, so behaviour — output,
+ * interactive shutdown, and exit status — is byte-identical to calling
+ * `@mono-agent/agent-app`'s own bin directly.
+ *
+ * Why a child process instead of importing `runCli` in-process: agent-app's
+ * `dist/cli.js` auto-runs the CLI when it detects it is the entry module (by
+ * `argv[1]` basename), which is exactly what a bin symlink named `mono-agent`
+ * looks like under an npm/npx global install. Importing it here would risk a
+ * double-run (the auto-run guard AND an explicit call) on some install layouts,
+ * and avoiding that would require agent-app to grow a side-effect-free entry —
+ * widening its surface. Spawning agent-app's real bin keeps this package pure
+ * delegation with zero agent-app changes and one deterministic execution path.
+ *
+ * Signal/exit fidelity is delegated to `delegateSignals` (see there): the child
+ * shares this process group, so Ctrl-C already reaches it; the shim must NOT
+ * re-forward group-delivered signals (that would hard-kill a child mid-shutdown),
+ * only relay a targeted SIGTERM, and mirror the child's exit code/signal exactly.
+ */
+const cliEntry = resolveAgentAppCliEntry();
+const child = spawn(process.execPath, [cliEntry, ...process.argv.slice(2)], { stdio: "inherit" });
+delegateSignals(child, process);
+//# sourceMappingURL=mono-agent.js.map

package/dist/bin/mono-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mono-agent.js","sourceRoot":"","sources":["../../src/bin/mono-agent.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,QAAQ,GAAG,uBAAuB,EAAE,CAAC;AAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAClG,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC"}

package/dist/delegate.d.ts

@@ -0,0 +1,31 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * The subset of `NodeJS.Process` the delegator touches, named so the wiring is
+ * unit-testable with a fake process.
+ */
+export interface DelegatorProcess {
+    readonly pid: number;
+    exitCode?: string | number | null | undefined;
+    on(event: NodeJS.Signals, listener: () => void): unknown;
+    removeAllListeners(event: NodeJS.Signals): unknown;
+    kill(pid: number, signal: NodeJS.Signals): unknown;
+    exit(code?: number): never;
+    readonly stderr: {
+        write(chunk: string): unknown;
+    };
+}
+/**
+ * Wires a spawned agent-app CLI child to the shim process so exit status and
+ * shutdown are byte-identical to invoking agent-app's bin directly:
+ *
+ * - SIGINT/SIGHUP: inert keep-alive handlers (the group already delivered them to
+ *   the child); we wait for the child's graceful exit rather than re-signalling.
+ * - SIGTERM: forwarded once — a targeted `kill <shim-pid>` reaches only the shim,
+ *   so the child needs it relayed to shut down gracefully.
+ * - child exit by code: mirror the code.
+ * - child exit by signal: mirror it by re-raising on ourselves, first removing our
+ *   own handler for that signal so the re-raise actually terminates us (otherwise
+ *   our keep-alive handler catches it and we'd exit 0 instead of 128+signum).
+ */
+export declare function delegateSignals(child: Pick<ChildProcess, "on" | "kill">, proc: DelegatorProcess): void;
+//# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACzD,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IACnD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IACnD,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CACpD;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,MAAM,CAAC,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAuBtG"}

package/dist/delegate.js

@@ -0,0 +1,46 @@
+/**
+ * Signals the terminal delivers to the ENTIRE foreground process group. Because
+ * the delegated child is spawned into this same group (inherited stdio, not
+ * detached), it already receives these directly — so the shim must NOT forward a
+ * second copy, which would land on a child that has already removed its own
+ * handler and started an async shutdown, hard-killing it mid-teardown (no channel
+ * teardown, no trace flush, no memory-DB close). The shim installs inert handlers
+ * only, to stay alive until the child's own graceful shutdown drives our exit.
+ */
+const GROUP_DELIVERED_SIGNALS = ["SIGINT", "SIGHUP"];
+/**
+ * Wires a spawned agent-app CLI child to the shim process so exit status and
+ * shutdown are byte-identical to invoking agent-app's bin directly:
+ *
+ * - SIGINT/SIGHUP: inert keep-alive handlers (the group already delivered them to
+ *   the child); we wait for the child's graceful exit rather than re-signalling.
+ * - SIGTERM: forwarded once — a targeted `kill <shim-pid>` reaches only the shim,
+ *   so the child needs it relayed to shut down gracefully.
+ * - child exit by code: mirror the code.
+ * - child exit by signal: mirror it by re-raising on ourselves, first removing our
+ *   own handler for that signal so the re-raise actually terminates us (otherwise
+ *   our keep-alive handler catches it and we'd exit 0 instead of 128+signum).
+ */
+export function delegateSignals(child, proc) {
+    for (const signal of GROUP_DELIVERED_SIGNALS) {
+        proc.on(signal, () => {
+            // Intentionally inert: the child owns the shutdown; we await its exit.
+        });
+    }
+    proc.on("SIGTERM", () => {
+        child.kill("SIGTERM");
+    });
+    child.on("error", (error) => {
+        proc.stderr.write(`mono-agent: failed to launch the @mono-agent/agent-app CLI: ${error.message}\n`);
+        proc.exitCode = 1;
+    });
+    child.on("exit", (code, signal) => {
+        if (signal !== null) {
+            proc.removeAllListeners(signal);
+            proc.kill(proc.pid, signal);
+            return;
+        }
+        proc.exit(code ?? 0);
+    });
+}
+//# sourceMappingURL=delegate.js.map

package/dist/delegate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.js","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AACH,MAAM,uBAAuB,GAA8B,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,KAAwC,EAAE,IAAsB;IAC9F,KAAK,MAAM,MAAM,IAAI,uBAAuB,EAAE,CAAC;QAC7C,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACnB,uEAAuE;QACzE,CAAC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACtB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;QACjC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,+DAA+D,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;QACpG,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAmB,EAAE,MAA6B,EAAE,EAAE;QACtE,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/resolve-agent-app-cli.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves the absolute path of `@mono-agent/agent-app`'s `mono-agent` CLI entry
+ * from the installed dependency's own `package.json` `bin` field.
+ *
+ * Reading the `bin` path from the manifest (rather than hardcoding `dist/cli.js`)
+ * means this survives any install layout — npm/npx global, pnpm-linked — and any
+ * future change to agent-app's bin location. We resolve it through CJS
+ * `require.resolve` of `@mono-agent/agent-app/package.json` (which agent-app
+ * exports), so this works on every Node ≥20 without depending on the newer
+ * synchronous `import.meta.resolve` (Node 20.6+).
+ */
+export declare function resolveAgentAppCliEntry(from?: string | URL): string;
+//# sourceMappingURL=resolve-agent-app-cli.d.ts.map

package/dist/resolve-agent-app-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-agent-app-cli.d.ts","sourceRoot":"","sources":["../src/resolve-agent-app-cli.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,MAAM,GAAG,GAAqB,GAAG,MAAM,CAkBpF"}

package/dist/resolve-agent-app-cli.js

@@ -0,0 +1,32 @@
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+/**
+ * Resolves the absolute path of `@mono-agent/agent-app`'s `mono-agent` CLI entry
+ * from the installed dependency's own `package.json` `bin` field.
+ *
+ * Reading the `bin` path from the manifest (rather than hardcoding `dist/cli.js`)
+ * means this survives any install layout — npm/npx global, pnpm-linked — and any
+ * future change to agent-app's bin location. We resolve it through CJS
+ * `require.resolve` of `@mono-agent/agent-app/package.json` (which agent-app
+ * exports), so this works on every Node ≥20 without depending on the newer
+ * synchronous `import.meta.resolve` (Node 20.6+).
+ */
+export function resolveAgentAppCliEntry(from = import.meta.url) {
+    const require = createRequire(from);
+    let manifestPath;
+    try {
+        manifestPath = require.resolve("@mono-agent/agent-app/package.json");
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`the create-mono-agent installer could not find @mono-agent/agent-app (its CLI host) — reinstall it (\`npm i -g create-mono-agent\`). (${reason})`);
+    }
+    const manifest = require("@mono-agent/agent-app/package.json");
+    const bin = manifest.bin;
+    const relative = typeof bin === "string" ? bin : bin?.["mono-agent"];
+    if (typeof relative !== "string" || relative.length === 0) {
+        throw new Error("@mono-agent/agent-app does not declare a `mono-agent` bin; cannot delegate.");
+    }
+    return resolve(dirname(manifestPath), relative);
+}
+//# sourceMappingURL=resolve-agent-app-cli.js.map

package/dist/resolve-agent-app-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-agent-app-cli.js","sourceRoot":"","sources":["../src/resolve-agent-app-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAM7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAqB,MAAM,CAAC,IAAI,CAAC,GAAG;IAC1E,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,YAAoB,CAAC;IACzB,IAAI,CAAC;QACH,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,oCAAoC,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,yIAAyI,MAAM,GAAG,CACnJ,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,oCAAoC,CAAqB,CAAC;IACnF,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;IACzB,MAAM,QAAQ,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC;IACrE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,CAAC;AAClD,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "create-mono-agent",
+  "version": "0.5.1",
+  "description": "npm-init style installer for the mono-agent CLI: `npm create mono-agent`. Ships both a `create-mono-agent` and a `mono-agent` bin, each delegating to the @mono-agent/agent-app CLI.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "bin": {
+    "create-mono-agent": "./dist/bin/mono-agent.js",
+    "mono-agent": "./dist/bin/mono-agent.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@mono-agent/agent-app": "0.5.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}