@coryrylan/cradle 0.0.0 → 1.2.0

package/dist/nono/profiles.d.ts

@@ -45,7 +45,7 @@ export interface ProfileSpec {
  * `extends default`, pulls the `node_runtime` group, and grants mise/pi/say
  * paths) merged with this run's grants — the target cwd, the agent folder, the
  * state dir, the linked git dir when cwd is a worktree/submodule checkout, and
- * the agent's own `sandbox/nono.json` entries. Regenerated every run into the
+ * the agent's own path and direct-child Unix socket grants from `sandbox/nono.json`. Regenerated every run into the
  * state dir, so there is no shared global profile: each agent's permissions
  * are fully described by its own directory.
  *

package/dist/sbx/compose.d.ts

@@ -0,0 +1,115 @@
+import type { AgentNetwork, AgentSandboxGrants } from '../agent/folder.js';
+/**
+ * Guest `localhost` resolves to the microVM itself, not the host — host
+ * loopback is reachable at this gateway, which sbx routes through the policy
+ * proxy. Used both to rewrite `allowDomain` localhost entries (see
+ * `composeSbxPolicyArgvs`) and caller-supplied base URLs (see
+ * `rewriteLocalhostBaseUrl`).
+ */
+export declare const SBX_HOST_GATEWAY = "host.docker.internal";
+/** A single sbx mount: a host path (preserved verbatim in the guest) and its access mode. */
+export interface SbxMount {
+    readonly path: string;
+    readonly readonly: boolean;
+}
+/**
+ * Everything `composeSbxCreateArgv`, `composeSbxPolicyArgvs`,
+ * `composeSbxProvisionArgv`, and `composeSbxExecArgv` need — the sbx analog of
+ * nono's `ProfileSpec`.
+ */
+export interface SbxSpec {
+    /** Resolved path, or bare `sbx` for dry-run previews. */
+    readonly sbxBin: string;
+    /** Sandbox name from `sbxSandboxName()`. */
+    readonly name: string;
+    /** The target project — always the first (rw) workspace mount. */
+    readonly cwd: string;
+    /** Host home dir — for the exec `HOME` override and the `~/.pi/agent` mount. */
+    readonly home: string;
+    /** From `composeSbxMounts()`; cwd first. Fixed at sandbox creation time. */
+    readonly mounts: readonly SbxMount[];
+    /** Precedence-resolved network posture — the same shape nono consumes. */
+    readonly network?: AgentNetwork;
+    /** Host pi version to pin in-guest; `null` = install only if missing. */
+    readonly piVersion: string | null;
+    /** Pass `-t` on exec — set when a TTY is present. */
+    readonly tty: boolean;
+}
+/** Inputs to `composeSbxMounts` — everything that can contribute a guest mount. */
+export interface SbxMountContext {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly stateDir: string;
+    readonly home: string;
+    readonly grants: AgentSandboxGrants;
+    /**
+     * The real git dir when `cwd` is a linked worktree or submodule checkout
+     * (see `agent/linked-git-dir.ts`) — mirrors nono's `ProfileSpec.linkedGitDir`.
+     * Absent for regular repos, where `.git` already sits inside the cwd mount.
+     */
+    readonly linkedGitDir?: string;
+}
+/**
+ * Build this run's guest mount list: cwd (rw), the agent folder (ro), the
+ * state dir (rw), `~/.pi/agent` (rw — pi's auth/settings store; the exec
+ * `HOME` override in `composeSbxExecArgv` makes pi find it there), the linked
+ * git dir when present (rw), then the agent's own `sandbox/nono.json` grants
+ * (`read` ro, `write`/`allow` rw), each expanded against `home`. Duplicate
+ * paths collapse to one entry — rw wins over ro, first-occurrence order
+ * otherwise — since sbx takes a flat mount list, not layered grants.
+ */
+export declare function composeSbxMounts(ctx: SbxMountContext): SbxMount[];
+/**
+ * `cradle-<stateDirBasename>-<hash8>` — hash8 is the first 8 hex chars of a
+ * sha256 over the order-insensitive sorted `path:ro|rw` strings, mirroring
+ * `agentId` (`agent/state.ts`). Mounts are fixed at sbx creation time, so this
+ * name keys the mount set: a changed mount set yields a new sandbox name
+ * instead of silently attaching to (and running with) a stale mount list.
+ */
+export declare function sbxSandboxName(stateDirBasename: string, mounts: readonly SbxMount[]): string;
+/** `sbx create shell <path>[:ro]... --name <name> -q`. `spec.mounts` already carries cwd first. */
+export declare function composeSbxCreateArgv(spec: SbxSpec): string[];
+/**
+ * Per-sandbox network policy argvs (idempotent re-adds — safe to run every
+ * launch). `[]` when `spec.network` is absent. A `block: true` posture emits a
+ * single deny-all — `allowDomain` is ignored under block, matching nono's
+ * block-wins precedence, since a same-scope deny always beats an allow.
+ * Otherwise, a non-empty `allowDomain` emits a single allow argv with every
+ * expanded resource comma-joined (see `composeAllowResources`); an empty or
+ * absent `allowDomain` under a non-blocking posture emits nothing.
+ * `openPort`/`listenPort`/`networkProfile` have no sbx policy equivalent —
+ * see `sbxNetworkWarnings` for their disclosures.
+ */
+export declare function composeSbxPolicyArgvs(spec: SbxSpec): string[][];
+/**
+ * Warn-and-drop disclosures for `AgentNetwork` fields sbx cannot enforce the
+ * way nono does. Returns `[]` when nothing applies (including when `network`
+ * is absent) — this module never throws, it only reports what it dropped.
+ */
+export declare function sbxNetworkWarnings(network: AgentNetwork | undefined): string[];
+/** Warn-and-drop disclosure for the one `AgentSandboxGrants` field sbx cannot honor: Unix sockets cannot cross the VM boundary. */
+export declare function sbxGrantWarnings(grants: AgentSandboxGrants): string[];
+/**
+ * `sbx exec <name> bash -lc <script>` running an idempotent pi install: with
+ * `spec.piVersion` pinned, reinstalls only on a version mismatch (`pi
+ * --version` compared against the pin); with `null`, installs only if `pi` is
+ * missing from PATH entirely, otherwise leaving whatever version is already
+ * there.
+ */
+export declare function composeSbxProvisionArgv(spec: SbxSpec): string[];
+/**
+ * `sbx exec -i [-t] -e HOME=<home> -w <cwd> <name> <piArgv...>` — docker-exec
+ * semantics. `-t` rides only when `spec.tty` is set (a TTY is present);
+ * forcing it without one breaks non-interactive callers.
+ */
+export declare function composeSbxExecArgv(spec: SbxSpec, piArgv: readonly string[]): string[];
+/** True when `stderr` reports the sandbox name is already taken — callers treat that as attach, not failure. */
+export declare function isSbxAlreadyExistsError(stderr: string): boolean;
+/**
+ * Rewrite a `localhost`/`127.0.0.1` base URL to `SBX_HOST_GATEWAY`, preserving
+ * scheme, port, and path — a host service bound to loopback is unreachable
+ * from inside the sbx guest microVM under its own name, but the gateway
+ * routes through the policy proxy back to the host. Any other host, and a
+ * parse failure, pass through unchanged.
+ */
+export declare function rewriteLocalhostBaseUrl(baseUrl: string): string;

package/dist/util/proc.d.ts

@@ -16,6 +16,17 @@ export declare function killOn(proc: Killable, signal: ForwardableSignal): () =>
  * sandboxed-run `MISE_CACHE_DIR`, see `agent/launch.ts`'s `composeEnv`).
  */
 export declare function runForeground(argv: readonly string[], env?: Record<string, string>): Promise<number>;
+/**
+ * Run a setup command silently, capturing stderr for the caller's error
+ * message — the sbx create/policy/provision sequence, see
+ * `commands/run.ts`'s `MaterializeDeps.run`. Never throws on a non-zero
+ * exit: the caller decides which failures matter (an sbx create name
+ * collision means attach, not failure).
+ */
+export declare function runCapture(argv: readonly string[]): Promise<{
+    exitCode: number;
+    stderr: string;
+}>;
 /** Run a package install (e.g. `npm install`) in `cwd`, inheriting output; throws on non-zero exit. */
 export declare function runInstall(command: readonly string[], cwd: string): Promise<void>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coryrylan/cradle",
-  "version": "0.0.0",
+  "version": "1.2.0",
   "description": "A runtime for portable agents defined as folders — launches the pi coding agent configured from an agent folder, sandboxed with nono",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -220,14 +220,17 @@
     }
   },
   "dependencies": {
-    "yargs": "18.0.0"
+    "yargs": "^18.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "catalog:",
-    "@types/bun": "catalog:",
+    "@coryrylan/tools": "1.1.0",
+    "@eslint/js": "10.0.1",
+    "@eslint/json": "1.2.0",
+    "@types/bun": "1.3.14",
     "@types/yargs": "17.0.35",
-    "eslint": "catalog:",
-    "typescript": "catalog:",
-    "typescript-eslint": "catalog:"
+    "eslint": "10.6.0",
+    "eslint-plugin-jsdoc": "63.2.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.62.1"
   }
 }