@nimbus-sh/core 0.5.0 → 0.7.0

package/src/workspace/supervisor-op.ts

@@ -0,0 +1,117 @@
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+import { CRED_SESSION_USER, type VfsCred } from '../runtime/os-contracts.js';
+import { SqliteRuntimeFsBridge } from '../runtime/sqlite-runtime-fs-bridge.js';
+import { getSymlinkRegistry } from '../vfs/symlink-registry.js';
+import type { SessionProcessSupervisor } from '../runtime/session-process-supervisor.js';
+
+/** Identity comes from the supervisor binding, never from facet arguments. */
+export interface SupervisorOpEnvelope {
+  readonly op: string;
+  readonly args?: readonly unknown[];
+  readonly pid?: number;
+  readonly writerId?: string;
+  readonly mutationOwner?: string;
+  readonly stream?: ReadableStream<Uint8Array>;
+}
+
+export type SupervisorOpHandler = (envelope: SupervisorOpEnvelope) => unknown;
+
+export interface SupervisorOpDeps {
+  readonly vfs: SqliteVFS;
+  /** Absent a process table, operations use the unprivileged session user. */
+  readonly processes?: SessionProcessSupervisor;
+  readonly output?: (stream: 'stdout' | 'stderr', pid: number, data: string) => void;
+  /** Host handlers override defaults, for example to account for stream drains. */
+  readonly extend?: Readonly<Record<string, SupervisorOpHandler>>;
+}
+
+function stringArg(envelope: SupervisorOpEnvelope, index: number): string {
+  const value = envelope.args?.[index];
+  if (typeof value !== 'string') {
+    throw new Error(`supervisor op ${envelope.op}: argument ${index} must be a string`);
+  }
+  return value;
+}
+
+function numberArg(envelope: SupervisorOpEnvelope, index: number): number {
+  const value = envelope.args?.[index];
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`supervisor op ${envelope.op}: argument ${index} must be a number`);
+  }
+  return value;
+}
+
+function contentArg(envelope: SupervisorOpEnvelope, index: number): string | Uint8Array {
+  const value = envelope.args?.[index];
+  if (typeof value === 'string' || value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  throw new Error(`supervisor op ${envelope.op}: argument ${index} must be bytes or text`);
+}
+
+function credFor(deps: SupervisorOpDeps, pid: number | undefined): VfsCred {
+  if (pid === undefined) return CRED_SESSION_USER;
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error('supervisor op: filesystem operation requires a valid process pid');
+  }
+  return deps.processes ? deps.processes.cred(pid) : CRED_SESSION_USER;
+}
+
+/** One dispatch method lets any host serve its workspace to process facets. */
+export function createSupervisorOpHandler(
+  deps: SupervisorOpDeps,
+): (envelope: SupervisorOpEnvelope) => Promise<unknown> {
+  const bridges = new Map<number, SqliteRuntimeFsBridge>();
+  const bridgeFor = (pid: number | undefined): SqliteRuntimeFsBridge => {
+    const key = pid ?? 0;
+    const credentialed = deps.vfs.as(credFor(deps, pid));
+    const held = bridges.get(key);
+    if (held) {
+      held.updateCredential(credentialed);
+      return held;
+    }
+    const built = new SqliteRuntimeFsBridge(credentialed, deps.vfs);
+    bridges.set(key, built);
+    return built;
+  };
+  const ops: Readonly<Record<string, SupervisorOpHandler>> = {
+    readFile: async (e) => {
+      const bytes = await bridgeFor(e.pid).readFile(stringArg(e, 0));
+      return bytes === null ? null : new TextDecoder().decode(bytes);
+    },
+    readFileBytes: (e) => bridgeFor(e.pid).readFile(stringArg(e, 0)),
+    stat: (e) => bridgeFor(e.pid).stat(stringArg(e, 0)),
+    lstat: (e) => bridgeFor(e.pid).stat(stringArg(e, 0), { followSymlinks: false }),
+    exists: async (e) => (await bridgeFor(e.pid).stat(stringArg(e, 0))) !== null,
+    readdir: (e) => bridgeFor(e.pid).readdir(stringArg(e, 0)),
+    readlink: (e) => bridgeFor(e.pid).readlink(stringArg(e, 0)),
+    fsReadRange: (e) => bridgeFor(e.pid).readRange(stringArg(e, 0), numberArg(e, 1), numberArg(e, 2)),
+    fsReadRangeUncached: (e) => bridgeFor(e.pid).readRange(stringArg(e, 0), numberArg(e, 1), numberArg(e, 2), { cached: false }),
+    fsRevision: (e) => bridgeFor(e.pid).revision(e.args?.[0] === undefined ? undefined : stringArg(e, 0)),
+    hasLegacySymlinkUnder: (e) => getSymlinkRegistry(deps.vfs).hasAtOrBelow(stringArg(e, 0)),
+    writeFile: (e) => bridgeFor(e.pid).writeFile(stringArg(e, 0), contentArg(e, 1)),
+    mkdir: (e) => bridgeFor(e.pid).mkdir(stringArg(e, 0), { recursive: true }),
+    rmdir: (e) => bridgeFor(e.pid).rmdir(stringArg(e, 0)),
+    unlink: (e) => bridgeFor(e.pid).unlink(stringArg(e, 0)),
+    rename: (e) => bridgeFor(e.pid).rename(stringArg(e, 0), stringArg(e, 1)),
+    symlink: (e) => bridgeFor(e.pid).symlink(stringArg(e, 0), stringArg(e, 1)),
+    chmod: (e) => bridgeFor(e.pid).chmod(stringArg(e, 0), numberArg(e, 1)),
+    utimes: (e) => bridgeFor(e.pid).utimes(stringArg(e, 0), numberArg(e, 1), numberArg(e, 2)),
+    fsTruncate: (e) => bridgeFor(e.pid).truncate(stringArg(e, 0), numberArg(e, 1)),
+    writeBatchStream: (e) => {
+      if (!e.stream) throw new Error('supervisor op writeBatchStream: no stream');
+      return deps.vfs.as(credFor(deps, e.pid)).writeStream(e.stream, { mutationOwner: e.mutationOwner });
+    },
+    stdout: (e) => { deps.output?.('stdout', e.pid ?? 0, stringArg(e, 0)); },
+    stderr: (e) => { deps.output?.('stderr', e.pid ?? 0, stringArg(e, 0)); },
+  };
+  const extend = deps.extend ?? {};
+  return async (envelope) => {
+    if (!envelope || typeof envelope.op !== 'string') {
+      throw new Error('supervisor op: envelope names no operation');
+    }
+    const handler = Object.hasOwn(extend, envelope.op) ? extend[envelope.op]
+      : Object.hasOwn(ops, envelope.op) ? ops[envelope.op] : undefined;
+    if (!handler) throw new Error(`supervisor op: '${envelope.op}' is not served by this host`);
+    return handler(envelope);
+  };
+}

package/dist/_shared/install-phase.d.ts

@@ -1,47 +0,0 @@
-/**
- * _shared/install-phase.ts — single source of truth for the npm-install
- * state-machine phase enum.
- *
- * History: CLN-1 (2026-05-11) — consolidated from two diverged copies.
- *   - `npm/installer.ts:93-95` was the progress-event variant. Included
- *     'lock-check' (a real progress event emitted while parsing
- *     package-lock.json) but lacked 'idle'.
- *   - `observability/diag-counters.ts:33-35` was the counter-state variant.
- *     Included 'idle' (the resting state when no install is in flight)
- *     but lacked 'lock-check'. The diag-counter's `setInstallPhase()`
- *     was actually called with 'idle' (installer.ts:184,201) — passing
- *     a value not declared in installer.ts's local type. The type check
- *     fell through to diag-counters' type because installer.ts imports
- *     setInstallPhase from there; the local `InstallPhase` definition
- *     in installer.ts was only used by `InstallProgress.phase`.
- *
- * Going forward both consumers import from this module; any new phase
- * value added here is automatically available everywhere.
- *
- * Phase semantics (chronological order for a single install run):
- *
- *   idle         resting state, no install in flight
- *     ↓
- *   lock-check   parsing existing package-lock.json (if present)
- *     ↓
- *   resolve      walking the dep tree, fetching packuments
- *     ↓
- *   hoist        hoisting peer-deps + flattening node_modules
- *     ↓
- *   diff         comparing target tree against current install state
- *     ↓
- *   fetch        downloading missing tarballs
- *     ↓
- *   write        extracting tarballs into the VFS
- *     ↓
- *   link-bins    creating bin/ symlinks
- *     ↓
- *   bundle       (post-install) pre-bundling for esbuild fast path
- *     ↓
- *   done         install complete; about to return to 'idle'
- *
- * The phase strings are surfaced via /api/_diag/install-pipeline and
- * displayed in the install-progress UI; treat them as a public API.
- */
-export type InstallPhase = 'idle' | 'lock-check' | 'resolve' | 'hoist' | 'diff' | 'fetch' | 'write' | 'link-bins' | 'bundle' | 'done';
-//# sourceMappingURL=install-phase.d.ts.map

package/dist/_shared/install-phase.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"install-phase.d.ts","sourceRoot":"","sources":["../../src/_shared/install-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,MAAM,CAAC"}

package/dist/_shared/install-phase.js

@@ -1 +0,0 @@
-export {};

package/dist/_shared/rpc-dispose.d.ts

@@ -1,4 +0,0 @@
-export declare function disposeRpcResource(value: unknown): boolean;
-export declare function disposeRpcResources(values: Iterable<unknown>): void;
-export declare function useRpcResource<T, R>(promise: Promise<T>, use: (value: T) => R | Promise<R>): Promise<R>;
-//# sourceMappingURL=rpc-dispose.d.ts.map

package/dist/_shared/rpc-dispose.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rpc-dispose.d.ts","sourceRoot":"","sources":["../../src/_shared/rpc-dispose.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAY1D;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAEnE;AAED,wBAAsB,cAAc,CAAC,CAAC,EAAE,CAAC,EACvC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/_shared/rpc-dispose.js

@@ -1,30 +0,0 @@
-export function disposeRpcResource(value) {
-    if ((typeof value !== 'object' && typeof value !== 'function') || value === null)
-        return false;
-    const disposerKey = Symbol.dispose;
-    if (!disposerKey)
-        return false;
-    const disposer = Reflect.get(value, disposerKey);
-    if (typeof disposer !== 'function')
-        return false;
-    try {
-        Reflect.apply(disposer, value, []);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function disposeRpcResources(values) {
-    for (const value of values)
-        disposeRpcResource(value);
-}
-export async function useRpcResource(promise, use) {
-    const value = await promise;
-    try {
-        return await use(value);
-    }
-    finally {
-        disposeRpcResource(value);
-    }
-}

package/dist/_shared/w7-frame.d.ts

@@ -1,79 +0,0 @@
-/**
- * W7 v3 — incremental typed records for streamed bulk filesystem writes.
- * The format is internal: every producer and consumer deploys together.
- */
-import type { BatchInodeEntry, BatchWritePayload } from '../vfs/sqlite-vfs.js';
-export declare const W7_MAGIC: Uint8Array<ArrayBuffer>;
-export declare const W7_MAX_PATHS_PER_BATCH = 128;
-export declare const W7_MAX_OWNED_PATH_BYTES: number;
-export declare const W7_MAX_RECORD_BYTES: number;
-declare const MODE: "path-atomic-committed-prefix";
-export interface W7BatchSummary {
-    recordCount: number;
-    pathCount: number;
-    deleteCount: number;
-    directoryCount: number;
-    fileCount: number;
-    chunkCount: number;
-    byteCount: number;
-    check: number;
-}
-export interface W7ChunkRetention {
-    readonly bytes: number;
-    release(): void;
-}
-export interface W7DecodeOptions {
-    signal?: AbortSignal;
-    retainChunk?: (byteLength: number, signal?: AbortSignal) => Promise<W7ChunkRetention>;
-}
-type W7DirectoryInode = BatchInodeEntry & {
-    kind: 'directory';
-    isDir: true;
-};
-type W7ContentInode = BatchInodeEntry & {
-    kind: 'file' | 'symlink';
-    isDir: false;
-};
-export type W7DecodedRecord = {
-    type: 'delete';
-    path: string;
-} | {
-    type: 'directory';
-    inode: W7DirectoryInode;
-} | {
-    type: 'file-begin';
-    streamContentId: string;
-    inode: W7ContentInode;
-} | {
-    type: 'file-chunk';
-    streamContentId: string;
-    path: string;
-    chunkId: number;
-    data: Uint8Array;
-    retention: W7ChunkRetention;
-} | {
-    type: 'file-end';
-    streamContentId: string;
-    path: string;
-    size: number;
-    chunkCount: number;
-    check: number;
-} | {
-    type: 'batch-end';
-    summary: W7BatchSummary;
-};
-export interface W7DecodedStream {
-    readonly batchId: string;
-    readonly mode: typeof MODE;
-    readonly records: AsyncIterable<W7DecodedRecord>;
-}
-/** Encode one bounded record per pull; no batch-sized metadata header exists. */
-export declare function encodeWriteBatchStream(payload: BatchWritePayload): ReadableStream<Uint8Array>;
-/**
- * Parse the v3 preamble eagerly, then expose validated operation records
- * incrementally. Chunk credit is acquired after its bounded header validates
- * and before its payload bytes are read or copied.
- */
-export declare function decodeWriteBatchStream(stream: ReadableStream<Uint8Array>, options?: W7DecodeOptions): Promise<W7DecodedStream>;
-export {};
-//# sourceMappingURL=w7-frame.d.ts.map

package/dist/_shared/w7-frame.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"w7-frame.d.ts","sourceRoot":"","sources":["../../src/_shared/w7-frame.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAEV,eAAe,EACf,iBAAiB,EAElB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,QAAQ,yBAA2C,CAAC;AAOjE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,uBAAuB,QAAY,CAAC;AACjD,eAAO,MAAM,mBAAmB,QAAgD,CAAC;AAYjF,QAAA,MAAM,IAAI,EAAG,8BAAuC,CAAC;AAoCrD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACvF;AAED,KAAK,gBAAgB,GAAG,eAAe,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,CAAC;AAC7E,KAAK,cAAc,GAAG,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEnF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC9C;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,cAAc,CAAC;CACvB,GACD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,gBAAgB,CAAC;CAC7B,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CAClD;AAaD,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAAC,UAAU,CAAC,CAoC7F;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA4C1B"}