@coryrylan/cradle 0.0.0 → 1.3.0

package/dist/commands/{start.d.ts → run.d.ts}

@@ -1,8 +1,10 @@
+import { type SandboxBackend } from '../agent/folder.js';
 import { type LaunchSpec } from '../agent/launch.js';
 import { type NpmPackageSpec } from '../agent/packages.js';
+import { type SbxSpec } from '../sbx/compose.js';
 import { type TreeFile } from '../setup/install.js';
 import { type WhichFn } from '../util/which.js';
-export interface StartFlags {
+export interface RunFlags {
     readonly dir: string;
     /** `--offline` → full network block. Overrides the folder network posture and forces the sandbox on (unless --no-sandbox). */
     readonly offline?: boolean;
@@ -10,15 +12,19 @@ export interface StartFlags {
     readonly allowHost?: readonly string[];
     /** Explicit CLI choice: `--no-sandbox` → true, `--sandbox` → false. Absent = defer to the folder. */
     readonly noSandbox?: boolean;
+    /** `--sandbox-backend` → explicit backend choice; implies the sandbox is on (still beaten by `--no-sandbox`). */
+    readonly sandboxBackend?: SandboxBackend;
     readonly dryRun?: boolean;
     readonly passthrough?: readonly string[];
     /** `--verbose` → show nono's full sandbox capabilities banner instead of the one-line status. */
     readonly verbose?: boolean;
 }
-interface StartDeps {
+interface RunDeps {
     readonly cwd?: string;
     readonly home?: string;
     readonly which?: WhichFn;
+    /** Whether stdout is a TTY (`cli.ts` passes `process.stdout.isTTY`) — rides the sbx exec argv as `-t`; default false. */
+    readonly tty?: boolean;
 }
 /**
  * The agent's settings.json `packages` resolved into a per-agent npm install
@@ -41,27 +47,46 @@ export interface PackagesPlan {
      */
     readonly installCommand: readonly string[];
 }
-export interface StartPlan {
+/**
+ * The sbx backend's materialization plan: the setup argvs `materializeRun`
+ * runs before the final `sbx exec` (composed there, wrapping the pi argv).
+ * `spec.piVersion` is null at plan time — the provision argv is recomposed at
+ * materialize with the host pi version (see `MaterializeDeps.readPiVersion`)
+ * so the guest install pins to it; the plan-time argv is the unpinned preview
+ * dry-run prints, the same precedent as package `-e` entries, which also
+ * resolve at materialize.
+ */
+export interface SbxRunPlan {
+    readonly spec: SbxSpec;
+    /** Resolved host pi path — the version-pin source for guest provisioning; never spawned in-guest. */
+    readonly hostPiBin: string;
+    readonly createArgv: readonly string[];
+    readonly policyArgvs: ReadonlyArray<readonly string[]>;
+    readonly provisionArgv: readonly string[];
+}
+export interface RunPlan {
     /** Generated extensions, relative to `extensionsDir`. */
     readonly files: readonly TreeFile[];
     /**
      * Authoritative — the single derivation site for where generated extensions
-     * and sessions live. `materializeStart` re-asserts these onto `launch`
+     * and sessions live. `materializeRun` re-asserts these onto `launch`
      * before composing the final argv, so overriding either here (as tests do)
      * changes the composed argv accordingly instead of silently disagreeing
-     * with whatever `launch` had baked in at `planStart` time.
+     * with whatever `launch` had baked in at `planRun` time.
      */
     readonly extensionsDir: string;
     readonly sessionsDir: string;
     readonly warnings: readonly string[];
-    /** The generated per-agent nono profile to write before spawning; `null` on unsandboxed runs (no profile needed). */
+    /** The generated per-agent nono profile to write before spawning; `null` unless the resolved backend is `'nono'`. */
     readonly profile: {
         readonly path: string;
         readonly content: string;
     } | null;
+    /** The sbx setup plan (see `SbxRunPlan`); `null` unless the resolved backend is `'sbx'`. */
+    readonly sbx: SbxRunPlan | null;
     /** Settings.json `packages` resolved into an install plan; `null` when the folder declares none. */
     readonly packages: PackagesPlan | null;
-    /** The single argv source: `composeArgv(plan.launch)` — package-entry-free until `materializeStart` recomposes it with resolved package entries. */
+    /** The single argv source: `composeArgv(plan.launch)` — package-entry-free until `materializeRun` recomposes it with resolved package entries. */
     readonly launch: LaunchSpec;
     readonly dryRun: boolean;
 }
@@ -71,23 +96,32 @@ export interface StartPlan {
  * decides whether to print it (`--dry-run`) or materialize + spawn it.
  *
  * `--dry-run` only previews, so it deliberately skips the bin checks — you can
- * compose a command before nono/pi are installed.
+ * compose a command before nono/sbx/pi are installed.
  */
-export declare function planStart(flags: StartFlags, deps?: StartDeps): Promise<StartPlan>;
+export declare function planRun(flags: RunFlags, deps?: RunDeps): Promise<RunPlan>;
+export interface SbxRunResult {
+    readonly exitCode: number;
+    readonly stderr: string;
+}
 export interface MaterializeDeps {
     /** Runs a package install (e.g. `npm install`) in `cwd`; `cli.ts` always passes `runInstall` from `util/proc.js`. */
     readonly install?: (command: readonly string[], cwd: string) => Promise<void>;
+    /** Runs one sbx setup command (create/policy/provision), capturing stderr; `cli.ts` passes `runCapture` from `util/proc.js`. */
+    readonly run?: (argv: readonly string[]) => Promise<SbxRunResult>;
+    /** Reads the host pi version (`cli.ts` passes its `--version` reader) to pin the guest install; absent → unpinned provisioning. */
+    readonly readPiVersion?: (piBin: string) => Promise<string | null>;
 }
 /**
  * Write the generated extensions (replacing stale ones), ensure the sessions
- * dir, and — on sandboxed runs — (re)write the generated per-agent nono profile
- * that `nono run --profile` points at. When the folder declares `packages`,
- * also (re)install the per-agent npm project and resolve each package's pi
- * extension entries, returning the final argv with those entries appended as
- * `-e` flags plus any resolution warnings; otherwise the plan's argv is
- * already final.
+ * dir, and — per backend — (re)write the generated per-agent nono profile
+ * that `nono run --profile` points at, or run the sbx setup sequence
+ * (create/policy/provision) and wrap the final argv in `sbx exec`. When the
+ * folder declares `packages`, also (re)install the per-agent npm project and
+ * resolve each package's pi extension entries, returning the final argv with
+ * those entries appended as `-e` flags plus any resolution warnings;
+ * otherwise the plan's argv is already final.
  */
-export declare function materializeStart(plan: StartPlan, deps?: MaterializeDeps): Promise<{
+export declare function materializeRun(plan: RunPlan, deps?: MaterializeDeps): Promise<{
     argv: string[];
     warnings: string[];
 }>;