@smthrs/kernel 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/ChildProcessSpawner.js

@@ -0,0 +1,342 @@
+/**
+ * Permission-aware process spawning.
+ *
+ * Smithers has no shell service of its own — process execution is Effect's
+ * `effect/unstable/process`. The only thing the kernel adds is the
+ * `proc:spawn` capability check and the host confinement wrapper, applied to
+ * the one primitive every other helper is derived from.
+ *
+ * There is no kernel spawner interface and no kernel spawner tag. Effect owns
+ * both, and its tag fixes the error channel to `PlatformError`, so this module
+ * is only the middleware: a `Layer` over Effect's own tag. A denied command is
+ * projected into `PlatformError` by `Permission.toPlatformError`, which keeps
+ * the structured kernel failure on the error's `cause`. Because the channel
+ * stays `PlatformError`, the full six-method surface is derived from the one
+ * guarded `spawn` through Effect's own `ChildProcessSpawner.make` without a
+ * cast.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Permission Kernel.md` and
+ * `docs/specs/Concepts/Host Adapters.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { toPlatformError } from "@smthrs/capability/Permission";
+import { Effect, FileSystem, Layer, Option, Path } from "effect";
+import { systemError } from "effect/PlatformError";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import { ChildProcessSpawner, make as makeSpawner } from "effect/unstable/process/ChildProcessSpawner";
+import * as CommandLine from "./CommandLine.js";
+import { GrantStore } from "./GrantStore.js";
+import * as Containment from "./internal/Containment.js";
+import { makeCapability } from "./internal/makeCapability.js";
+import * as ProcessConfinement from "./ProcessConfinement.js";
+import * as Rooted from "./Rooted.js";
+import { Workspace } from "./Workspace.js";
+const data = (value, name) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, name);
+    if (descriptor === undefined || !("value" in descriptor)) {
+        throw new TypeError(`command ${String(name)} must be a data property`);
+    }
+    return descriptor.value;
+};
+const optionalData = (value, name) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, name);
+    if (descriptor === undefined)
+        return undefined;
+    if (!("value" in descriptor))
+        throw new TypeError(`command ${String(name)} must be a data property`);
+    return descriptor.value;
+};
+const snapshotRecord = (value) => {
+    if (value === undefined)
+        return undefined;
+    const snapshot = Object.create(null);
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+        if (!descriptor.enumerable)
+            continue;
+        if (!("value" in descriptor) || (descriptor.value !== undefined && typeof descriptor.value !== "string")) {
+            throw new TypeError("command environment must contain string data properties");
+        }
+        snapshot[name] = descriptor.value;
+    }
+    return Object.freeze(snapshot);
+};
+const snapshotStreamConfig = (value) => {
+    if (typeof value !== "object" || value === null)
+        return value;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (descriptors.stream === undefined)
+        return value;
+    if (!("value" in descriptors.stream))
+        throw new TypeError("command stream must be a data property");
+    const snapshot = { stream: descriptors.stream.value };
+    for (const name of ["endOnDone", "encoding"]) {
+        const descriptor = descriptors[name];
+        if (descriptor !== undefined) {
+            if (!("value" in descriptor))
+                throw new TypeError(`command ${name} must be a data property`);
+            snapshot[name] = descriptor.value;
+        }
+    }
+    return Object.freeze(snapshot);
+};
+const snapshotAdditionalFds = (value) => {
+    if (value === undefined)
+        return undefined;
+    const snapshot = {};
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+        if (!descriptor.enumerable)
+            continue;
+        if (!("value" in descriptor) || typeof descriptor.value !== "object" || descriptor.value === null) {
+            throw new TypeError("additional file descriptors must be data records");
+        }
+        const config = descriptor.value;
+        const type = data(config, "type");
+        if (type === "input") {
+            const stream = Object.getOwnPropertyDescriptor(config, "stream");
+            snapshot[name] = Object.freeze({
+                type,
+                ...(stream === undefined ? {} : "value" in stream ? { stream: stream.value } : (() => {
+                    throw new TypeError("additional fd stream must be a data property");
+                })())
+            });
+        }
+        else if (type === "output") {
+            const sink = Object.getOwnPropertyDescriptor(config, "sink");
+            snapshot[name] = Object.freeze({
+                type,
+                ...(sink === undefined ? {} : "value" in sink ? { sink: sink.value } : (() => {
+                    throw new TypeError("additional fd sink must be a data property");
+                })())
+            });
+        }
+        else {
+            throw new TypeError("additional file descriptor type is invalid");
+        }
+    }
+    return Object.freeze(snapshot);
+};
+const snapshotOptions = (options) => Object.freeze({
+    killSignal: options.killSignal,
+    forceKillAfter: options.forceKillAfter,
+    cwd: options.cwd,
+    env: snapshotRecord(options.env),
+    extendEnv: options.extendEnv,
+    shell: options.shell,
+    detached: options.detached,
+    windowsHide: options.windowsHide,
+    stdin: snapshotStreamConfig(options.stdin),
+    stdout: snapshotStreamConfig(options.stdout),
+    stderr: snapshotStreamConfig(options.stderr),
+    additionalFds: snapshotAdditionalFds(options.additionalFds)
+});
+const snapshotCommand = (command) => {
+    const tag = data(command, "_tag");
+    if (tag === "StandardCommand") {
+        const executable = data(command, "command");
+        const args = data(command, "args");
+        const options = data(command, "options");
+        if (typeof executable !== "string" || !Array.isArray(args) || !args.every((arg) => typeof arg === "string")) {
+            throw new TypeError("standard command executable and arguments are invalid");
+        }
+        if (typeof options !== "object" || options === null)
+            throw new TypeError("command options are invalid");
+        return ChildProcess.make(executable, Object.freeze([...args]), snapshotOptions(options));
+    }
+    if (tag === "PipedCommand") {
+        const left = data(command, "left");
+        const right = data(command, "right");
+        const options = data(command, "options");
+        if (typeof left !== "object" || left === null || typeof right !== "object" || right === null) {
+            throw new TypeError("pipeline commands are invalid");
+        }
+        if (typeof options !== "object" || options === null)
+            throw new TypeError("pipeline options are invalid");
+        const from = optionalData(options, "from");
+        const to = optionalData(options, "to");
+        return ChildProcess.pipeTo(snapshotCommand(right), Object.freeze({
+            ...(from === undefined ? {} : { from: from }),
+            ...(to === undefined ? {} : { to: to })
+        }))(snapshotCommand(left));
+    }
+    throw new TypeError("unsupported command shape");
+};
+const maximumEnvironmentNames = 64;
+/**
+ * The environment this process holds, which a child built with
+ * `ChildProcessEnvironment.make` inherits its bootstrap names from. Empty on a
+ * host with no process environment, so every declared bootstrap name counts
+ * as an override there.
+ */
+const ambientEnvironment = () => globalThis.process?.env ?? {};
+const environmentNames = (command) => {
+    const environment = command.options.env;
+    if (environment === undefined)
+        return undefined;
+    const names = Object.entries(environment)
+        .filter(([, value]) => value !== undefined)
+        .map(([name]) => name)
+        .sort();
+    if (names.length === 0)
+        return undefined;
+    return names.length <= maximumEnvironmentNames
+        ? names
+        : [...names.slice(0, maximumEnvironmentNames), `+${names.length - maximumEnvironmentNames} more`];
+};
+/**
+ * Effect's own process spawner tag, unchanged. Re-exported so the kernel
+ * namespace stays one-stop; it is the *same* tag, never a second one.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
+/**
+ * Derives the full six-method surface from one `spawn`, so `exitCode`,
+ * `string`, `lines`, and both `stream*` helpers can never bypass whatever
+ * `spawn` was given.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export { make } from "effect/unstable/process/ChildProcessSpawner";
+/**
+ * Constructs an unavailable spawner stub.
+ *
+ * Every derived helper reports the missing host as a `NotFound`
+ * `PlatformError` naming the command line, so an unconfigured capability
+ * answers rather than vanishing.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const makeNoop = (overrides = {}) => ({
+    ...makeSpawner((command) => Effect.fail(systemError({
+        _tag: "NotFound",
+        module: "ChildProcessSpawner",
+        method: "spawn",
+        description: `no process host for \`${CommandLine.render(command)}\``
+    }))),
+    ...overrides
+});
+/**
+ * Provides an unavailable spawner stub.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerNoop = (overrides = {}) => Layer.succeed(ChildProcessSpawner)(makeNoop(overrides));
+/**
+ * Decorates the process spawner in place with a `proc:spawn` capability check.
+ *
+ * The check is suspended into the spawn itself, so building a `Command` or a
+ * stream neither requests permission nor starts a process; only running one
+ * does. Every pipeline stage is checked as its own capability, left to right,
+ * and no stage starts until all pass. A stage's resource is
+ * `CommandLine.resource`: the command line `CommandLine.render` produces, with
+ * a `shell: true` line that holds shell control syntax marked as
+ * `sh -c '<line>'`, any environment variable the child would not inherit from
+ * this process named in an `env <NAME>… -- ` prefix, and a working directory
+ * outside `Workspace.root` named in a `cwd <path> -- ` prefix. Custom shell
+ * paths are included explicitly in the resource; browser and remote adapters
+ * reject them rather than silently substituting a different shell.
+ *
+ * Every approved stage requires `ProcessConfinement` in the host context.
+ * A missing service refuses spawning; its `layerNoop` is the explicit choice
+ * for an unconfined host.
+ *
+ * Pipeline `from`/`to` routing remains outside the grant. The working
+ * directory and overridden environment names also reach attended surfaces as
+ * display metadata; environment values never leave the command.
+ *
+ * The layer provides the tag it also requires: compose it over a host spawner
+ * layer with `Layer.provide` and a `ChildProcess.Command` run as a plain
+ * `Effect` is checked too.
+ *
+ * A command with no `cwd`, or a relative one, runs in `Workspace.root`, never
+ * the process's own directory; the check sees that resolved directory. When
+ * the host filesystem is in the layer's context, the working directory and
+ * `Workspace.root` are compared by real path, so a symlink inside the
+ * workspace that leads out of it is named, as its target, in the `cwd` prefix.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = Layer.effect(ChildProcessSpawner, Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner;
+    const grants = yield* GrantStore;
+    const confinement = yield* Effect.serviceOption(ProcessConfinement.ProcessConfinement);
+    const path = yield* Path.Path;
+    const rooted = Rooted.path(path, path.resolve((yield* Workspace).root));
+    const root = rooted.resolve(".");
+    // The raw host filesystem this layer is composed over, when there is one.
+    // A symlink inside the workspace can lead out of it, so containment is
+    // judged on real paths; a directory that cannot be resolved (it does not
+    // exist, or the host has no filesystem) is judged lexically.
+    const fileSystem = yield* Effect.serviceOption(FileSystem.FileSystem);
+    const real = (directory) => Option.match(fileSystem, {
+        onNone: () => Effect.succeed(directory),
+        onSome: (fs) => fs.realPath(directory).pipe(Effect.orElseSucceed(() => directory))
+    });
+    const within = (base) => (directory) => {
+        const relative = path.relative(base, directory);
+        return relative.split(path.sep)[0] !== ".." && !path.isAbsolute(relative);
+    };
+    const checkStage = (stage) => Effect.gen(function* () {
+        // Rooted.command gives every stage an absolute cwd.
+        const cwd = stage.options.cwd;
+        const realRoot = yield* real(root);
+        const resolvedCwd = yield* real(cwd);
+        const contains = resolvedCwd === cwd
+            ? (directory) => within(root)(directory) || within(realRoot)(directory)
+            : within(realRoot);
+        return yield* checkResolved(stage, CommandLine.resource(stage, {
+            ambient: ambientEnvironment(),
+            contains,
+            resolvedCwd
+        }));
+    });
+    const checkResolved = (stage, rendered) => {
+        const environment = environmentNames(stage);
+        return makeCapability("proc:spawn", rendered).pipe(Effect.flatMap((capability) => grants.check(capability, {
+            cwd: stage.options.cwd,
+            ...(environment === undefined ? {} : { env: environment })
+        })), Effect.mapError((error) => toPlatformError({
+            module: "ChildProcessSpawner",
+            method: "spawn",
+            pathOrDescriptor: rendered,
+            error
+        })));
+    };
+    const check = (command) => Effect.forEach(CommandLine.stages(command), checkStage, { discard: true });
+    const confine = (command) => Option.match(confinement, {
+        onNone: () => Effect.fail(systemError({
+            _tag: "NotFound",
+            module: "ProcessConfinement",
+            method: "confine",
+            description: "process confinement is required; use ProcessConfinement.layerNoop to explicitly run unconfined"
+        })),
+        onSome: (service) => Effect.gen(function* () {
+            const profile = yield* ProcessConfinement.profile(grants, root, path).pipe(Effect.mapError((error) => toPlatformError({ module: "ChildProcessSpawner", method: "spawn", error })));
+            const wrap = (command) => command._tag === "StandardCommand"
+                ? service.confine(command, profile)
+                : Effect.gen(function* () {
+                    const left = yield* wrap(command.left);
+                    const right = yield* wrap(command.right);
+                    return ChildProcess.pipeTo(right, command.options)(left);
+                });
+            return yield* wrap(command);
+        })
+    });
+    return Containment.inherit(spawner, makeSpawner(Effect.fn("ChildProcessSpawner.spawn")((command) => Effect.try({
+        try: () => snapshotCommand(command),
+        catch: () => systemError({
+            _tag: "InvalidData",
+            module: "ChildProcessSpawner",
+            method: "spawn",
+            description: "command must be an immutable supported process description"
+        })
+    }).pipe(Effect.map((snapshot) => Rooted.command(snapshot, rooted)), Effect.flatMap((rooted) => check(rooted).pipe(Effect.andThen(confine(rooted)), Effect.flatMap(spawner.spawn)))))));
+}));
+//# sourceMappingURL=ChildProcessSpawner.js.map

package/dist/esm/ChildProcessSpawner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChildProcessSpawner.js","sourceRoot":"","sources":["../../src/ChildProcessSpawner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Permission-aware process spawning.\n *\n * Smithers has no shell service of its own — process execution is Effect's\n * `effect/unstable/process`. The only thing the kernel adds is the\n * `proc:spawn` capability check and the host confinement wrapper, applied to\n * the one primitive every other helper is derived from.\n *\n * There is no kernel spawner interface and no kernel spawner tag. Effect owns\n * both, and its tag fixes the error channel to `PlatformError`, so this module\n * is only the middleware: a `Layer` over Effect's own tag. A denied command is\n * projected into `PlatformError` by `Permission.toPlatformError`, which keeps\n * the structured kernel failure on the error's `cause`. Because the channel\n * stays `PlatformError`, the full six-method surface is derived from the one\n * guarded `spawn` through Effect's own `ChildProcessSpawner.make` without a\n * cast.\n *\n * Governing design:\n * `docs/specs/Concepts/Permission Kernel.md` and\n * `docs/specs/Concepts/Host Adapters.md`.\n *\n * @since 1.0.0-rc.0\n */\n\nimport { toPlatformError } from \"@smthrs/capability/Permission\"\nimport { Effect, FileSystem, Layer, Option, Path, type Scope } from \"effect\"\nimport { type PlatformError, systemError } from \"effect/PlatformError\"\nimport * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport { ChildProcessSpawner, make as makeSpawner } from \"effect/unstable/process/ChildProcessSpawner\"\nimport * as CommandLine from \"./CommandLine.ts\"\nimport { GrantStore } from \"./GrantStore.ts\"\nimport * as Containment from \"./internal/Containment.ts\"\nimport { makeCapability } from \"./internal/makeCapability.ts\"\nimport * as ProcessConfinement from \"./ProcessConfinement.ts\"\nimport * as Rooted from \"./Rooted.ts\"\nimport { Workspace } from \"./Workspace.ts\"\n\nconst data = (value: object, name: PropertyKey): unknown => {\n  const descriptor = Object.getOwnPropertyDescriptor(value, name)\n  if (descriptor === undefined || !(\"value\" in descriptor)) {\n    throw new TypeError(`command ${String(name)} must be a data property`)\n  }\n  return descriptor.value\n}\n\nconst optionalData = (value: object, name: PropertyKey): unknown => {\n  const descriptor = Object.getOwnPropertyDescriptor(value, name)\n  if (descriptor === undefined) return undefined\n  if (!(\"value\" in descriptor)) throw new TypeError(`command ${String(name)} must be a data property`)\n  return descriptor.value\n}\n\nconst snapshotRecord = (\n  value: Readonly<Record<string, string | undefined>> | undefined\n): Record<string, string | undefined> | undefined => {\n  if (value === undefined) return undefined\n  const snapshot: Record<string, string | undefined> = Object.create(null)\n  for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {\n    if (!descriptor.enumerable) continue\n    if (!(\"value\" in descriptor) || (descriptor.value !== undefined && typeof descriptor.value !== \"string\")) {\n      throw new TypeError(\"command environment must contain string data properties\")\n    }\n    snapshot[name] = descriptor.value\n  }\n  return Object.freeze(snapshot)\n}\n\nconst snapshotStreamConfig = <A>(value: A): A => {\n  if (typeof value !== \"object\" || value === null) return value\n  const descriptors = Object.getOwnPropertyDescriptors(value)\n  if (descriptors.stream === undefined) return value\n  if (!(\"value\" in descriptors.stream)) throw new TypeError(\"command stream must be a data property\")\n  const snapshot: Record<string, unknown> = { stream: descriptors.stream.value }\n  for (const name of [\"endOnDone\", \"encoding\"] as const) {\n    const descriptor = descriptors[name]\n    if (descriptor !== undefined) {\n      if (!(\"value\" in descriptor)) throw new TypeError(`command ${name} must be a data property`)\n      snapshot[name] = descriptor.value\n    }\n  }\n  return Object.freeze(snapshot) as A\n}\n\nconst snapshotAdditionalFds = (\n  value: ChildProcess.CommandOptions[\"additionalFds\"]\n): ChildProcess.CommandOptions[\"additionalFds\"] => {\n  if (value === undefined) return undefined\n  const snapshot: Record<`fd${number}`, ChildProcess.AdditionalFdConfig> = {}\n  for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {\n    if (!descriptor.enumerable) continue\n    if (!(\"value\" in descriptor) || typeof descriptor.value !== \"object\" || descriptor.value === null) {\n      throw new TypeError(\"additional file descriptors must be data records\")\n    }\n    const config = descriptor.value as ChildProcess.AdditionalFdConfig\n    const type = data(config, \"type\")\n    if (type === \"input\") {\n      const stream = Object.getOwnPropertyDescriptor(config, \"stream\")\n      snapshot[name as `fd${number}`] = Object.freeze({\n        type,\n        ...(stream === undefined ? {} : \"value\" in stream ? { stream: stream.value } : (() => {\n          throw new TypeError(\"additional fd stream must be a data property\")\n        })())\n      })\n    } else if (type === \"output\") {\n      const sink = Object.getOwnPropertyDescriptor(config, \"sink\")\n      snapshot[name as `fd${number}`] = Object.freeze({\n        type,\n        ...(sink === undefined ? {} : \"value\" in sink ? { sink: sink.value } : (() => {\n          throw new TypeError(\"additional fd sink must be a data property\")\n        })())\n      })\n    } else {\n      throw new TypeError(\"additional file descriptor type is invalid\")\n    }\n  }\n  return Object.freeze(snapshot)\n}\n\nconst snapshotOptions = (options: ChildProcess.CommandOptions): ChildProcess.CommandOptions =>\n  Object.freeze({\n    killSignal: options.killSignal,\n    forceKillAfter: options.forceKillAfter,\n    cwd: options.cwd,\n    env: snapshotRecord(options.env),\n    extendEnv: options.extendEnv,\n    shell: options.shell,\n    detached: options.detached,\n    windowsHide: options.windowsHide,\n    stdin: snapshotStreamConfig(options.stdin),\n    stdout: snapshotStreamConfig(options.stdout),\n    stderr: snapshotStreamConfig(options.stderr),\n    additionalFds: snapshotAdditionalFds(options.additionalFds)\n  })\n\nconst snapshotCommand = (command: ChildProcess.Command): ChildProcess.Command => {\n  const tag = data(command, \"_tag\")\n  if (tag === \"StandardCommand\") {\n    const executable = data(command, \"command\")\n    const args = data(command, \"args\")\n    const options = data(command, \"options\")\n    if (typeof executable !== \"string\" || !Array.isArray(args) || !args.every((arg) => typeof arg === \"string\")) {\n      throw new TypeError(\"standard command executable and arguments are invalid\")\n    }\n    if (typeof options !== \"object\" || options === null) throw new TypeError(\"command options are invalid\")\n    return ChildProcess.make(\n      executable,\n      Object.freeze([...args]),\n      snapshotOptions(options)\n    )\n  }\n  if (tag === \"PipedCommand\") {\n    const left = data(command, \"left\")\n    const right = data(command, \"right\")\n    const options = data(command, \"options\")\n    if (typeof left !== \"object\" || left === null || typeof right !== \"object\" || right === null) {\n      throw new TypeError(\"pipeline commands are invalid\")\n    }\n    if (typeof options !== \"object\" || options === null) throw new TypeError(\"pipeline options are invalid\")\n    const from = optionalData(options, \"from\")\n    const to = optionalData(options, \"to\")\n    return ChildProcess.pipeTo(\n      snapshotCommand(right as ChildProcess.Command),\n      Object.freeze({\n        ...(from === undefined ? {} : { from: from as ChildProcess.PipeFromOption }),\n        ...(to === undefined ? {} : { to: to as ChildProcess.PipeToOption })\n      })\n    )(snapshotCommand(left as ChildProcess.Command))\n  }\n  throw new TypeError(\"unsupported command shape\")\n}\n\nconst maximumEnvironmentNames = 64\n\n/**\n * The environment this process holds, which a child built with\n * `ChildProcessEnvironment.make` inherits its bootstrap names from. Empty on a\n * host with no process environment, so every declared bootstrap name counts\n * as an override there.\n */\nconst ambientEnvironment = (): Readonly<Record<string, string | undefined>> =>\n  (globalThis as { readonly process?: { readonly env?: Record<string, string | undefined> } }).process?.env ?? {}\n\nconst environmentNames = (command: ChildProcess.StandardCommand): ReadonlyArray<string> | undefined => {\n  const environment = command.options.env\n  if (environment === undefined) return undefined\n  const names = Object.entries(environment)\n    .filter(([, value]) => value !== undefined)\n    .map(([name]) => name)\n    .sort()\n  if (names.length === 0) return undefined\n  return names.length <= maximumEnvironmentNames\n    ? names\n    : [...names.slice(0, maximumEnvironmentNames), `+${names.length - maximumEnvironmentNames} more`]\n}\n\n/**\n * Effect's own process spawner tag, unchanged. Re-exported so the kernel\n * namespace stays one-stop; it is the *same* tag, never a second one.\n *\n * @category services\n * @since 1.0.0-rc.0\n */\nexport { ChildProcessSpawner } from \"effect/unstable/process/ChildProcessSpawner\"\n\n/**\n * Derives the full six-method surface from one `spawn`, so `exitCode`,\n * `string`, `lines`, and both `stream*` helpers can never bypass whatever\n * `spawn` was given.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport { make } from \"effect/unstable/process/ChildProcessSpawner\"\n\n/**\n * Constructs an unavailable spawner stub.\n *\n * Every derived helper reports the missing host as a `NotFound`\n * `PlatformError` naming the command line, so an unconfigured capability\n * answers rather than vanishing.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const makeNoop = (\n  overrides: Partial<ChildProcessSpawner[\"Service\"]> = {}\n): ChildProcessSpawner[\"Service\"] => ({\n  ...makeSpawner((command) =>\n    Effect.fail(\n      systemError({\n        _tag: \"NotFound\",\n        module: \"ChildProcessSpawner\",\n        method: \"spawn\",\n        description: `no process host for \\`${CommandLine.render(command)}\\``\n      })\n    )\n  ),\n  ...overrides\n})\n\n/**\n * Provides an unavailable spawner stub.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerNoop = (\n  overrides: Partial<ChildProcessSpawner[\"Service\"]> = {}\n): Layer.Layer<ChildProcessSpawner> => Layer.succeed(ChildProcessSpawner)(makeNoop(overrides))\n\n/**\n * Decorates the process spawner in place with a `proc:spawn` capability check.\n *\n * The check is suspended into the spawn itself, so building a `Command` or a\n * stream neither requests permission nor starts a process; only running one\n * does. Every pipeline stage is checked as its own capability, left to right,\n * and no stage starts until all pass. A stage's resource is\n * `CommandLine.resource`: the command line `CommandLine.render` produces, with\n * a `shell: true` line that holds shell control syntax marked as\n * `sh -c '<line>'`, any environment variable the child would not inherit from\n * this process named in an `env <NAME>… -- ` prefix, and a working directory\n * outside `Workspace.root` named in a `cwd <path> -- ` prefix. Custom shell\n * paths are included explicitly in the resource; browser and remote adapters\n * reject them rather than silently substituting a different shell.\n *\n * Every approved stage requires `ProcessConfinement` in the host context.\n * A missing service refuses spawning; its `layerNoop` is the explicit choice\n * for an unconfined host.\n *\n * Pipeline `from`/`to` routing remains outside the grant. The working\n * directory and overridden environment names also reach attended surfaces as\n * display metadata; environment values never leave the command.\n *\n * The layer provides the tag it also requires: compose it over a host spawner\n * layer with `Layer.provide` and a `ChildProcess.Command` run as a plain\n * `Effect` is checked too.\n *\n * A command with no `cwd`, or a relative one, runs in `Workspace.root`, never\n * the process's own directory; the check sees that resolved directory. When\n * the host filesystem is in the layer's context, the working directory and\n * `Workspace.root` are compared by real path, so a symlink inside the\n * workspace that leads out of it is named, as its target, in the `cwd` prefix.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layer: Layer.Layer<\n  ChildProcessSpawner,\n  never,\n  ChildProcessSpawner | GrantStore | Path.Path | Workspace\n> = Layer.effect(\n  ChildProcessSpawner,\n  Effect.gen(function*() {\n    const spawner = yield* ChildProcessSpawner\n    const grants = yield* GrantStore\n    const confinement = yield* Effect.serviceOption(ProcessConfinement.ProcessConfinement)\n    const path = yield* Path.Path\n    const rooted = Rooted.path(path, path.resolve((yield* Workspace).root))\n    const root = rooted.resolve(\".\")\n    // The raw host filesystem this layer is composed over, when there is one.\n    // A symlink inside the workspace can lead out of it, so containment is\n    // judged on real paths; a directory that cannot be resolved (it does not\n    // exist, or the host has no filesystem) is judged lexically.\n    const fileSystem = yield* Effect.serviceOption(FileSystem.FileSystem)\n    const real = (directory: string) =>\n      Option.match(fileSystem, {\n        onNone: () => Effect.succeed(directory),\n        onSome: (fs) => fs.realPath(directory).pipe(Effect.orElseSucceed(() => directory))\n      })\n    const within = (base: string) => (directory: string) => {\n      const relative = path.relative(base, directory)\n      return relative.split(path.sep)[0] !== \"..\" && !path.isAbsolute(relative)\n    }\n    const checkStage = (stage: ChildProcess.StandardCommand) =>\n      Effect.gen(function*() {\n        // Rooted.command gives every stage an absolute cwd.\n        const cwd = stage.options.cwd!\n        const realRoot = yield* real(root)\n        const resolvedCwd = yield* real(cwd)\n        const contains = resolvedCwd === cwd\n          ? (directory: string) => within(root)(directory) || within(realRoot)(directory)\n          : within(realRoot)\n        return yield* checkResolved(\n          stage,\n          CommandLine.resource(stage, {\n            ambient: ambientEnvironment(),\n            contains,\n            resolvedCwd\n          })\n        )\n      })\n    const checkResolved = (stage: ChildProcess.StandardCommand, rendered: string) => {\n      const environment = environmentNames(stage)\n      return makeCapability(\"proc:spawn\", rendered).pipe(\n        Effect.flatMap((capability) =>\n          grants.check(capability, {\n            cwd: stage.options.cwd,\n            ...(environment === undefined ? {} : { env: environment })\n          })\n        ),\n        Effect.mapError((error) =>\n          toPlatformError({\n            module: \"ChildProcessSpawner\",\n            method: \"spawn\",\n            pathOrDescriptor: rendered,\n            error\n          })\n        )\n      )\n    }\n    const check = (command: ChildProcess.Command) =>\n      Effect.forEach(CommandLine.stages(command), checkStage, { discard: true })\n    const confine = (\n      command: ChildProcess.Command\n    ): Effect.Effect<\n      ChildProcess.Command,\n      PlatformError,\n      Scope.Scope\n    > =>\n      Option.match(confinement, {\n        onNone: () =>\n          Effect.fail(systemError({\n            _tag: \"NotFound\",\n            module: \"ProcessConfinement\",\n            method: \"confine\",\n            description:\n              \"process confinement is required; use ProcessConfinement.layerNoop to explicitly run unconfined\"\n          })),\n        onSome: (service) =>\n          Effect.gen(function*() {\n            const profile = yield* ProcessConfinement.profile(grants, root, path).pipe(\n              Effect.mapError((error) => toPlatformError({ module: \"ChildProcessSpawner\", method: \"spawn\", error }))\n            )\n            const wrap = (\n              command: ChildProcess.Command\n            ): Effect.Effect<\n              ChildProcess.Command,\n              PlatformError,\n              Scope.Scope\n            > =>\n              command._tag === \"StandardCommand\"\n                ? service.confine(command, profile)\n                : Effect.gen(function*() {\n                  const left = yield* wrap(command.left)\n                  const right = yield* wrap(command.right)\n                  return ChildProcess.pipeTo(right, command.options)(left)\n                })\n            return yield* wrap(command)\n          })\n      })\n    return Containment.inherit(\n      spawner,\n      makeSpawner(\n        Effect.fn(\"ChildProcessSpawner.spawn\")((command: ChildProcess.Command) =>\n          Effect.try({\n            try: () => snapshotCommand(command),\n            catch: () =>\n              systemError({\n                _tag: \"InvalidData\",\n                module: \"ChildProcessSpawner\",\n                method: \"spawn\",\n                description: \"command must be an immutable supported process description\"\n              })\n          }).pipe(\n            Effect.map((snapshot) => Rooted.command(snapshot, rooted)),\n            Effect.flatMap((rooted) =>\n              check(rooted).pipe(Effect.andThen(confine(rooted)), Effect.flatMap(spawner.spawn))\n            )\n          )\n        )\n      )\n    )\n  })\n)\n"]}

package/dist/esm/CommandLine.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @since 1.0.0-rc.0
+ *
+ * Rendering an `effect/unstable/process` `Command` back to a shell command
+ * line.
+ *
+ * Two callers need the same string and must agree on it exactly:
+ *
+ *  1. `@smthrs/kernel/ChildProcessSpawner` uses it as the `proc:spawn`
+ *     capability resource, so a grant reads the way an operator wrote it; and
+ *  2. `@smthrs/platform-browser/BrowserChildProcessSpawner` uses it as the line
+ *     it hands to the in-browser bash interpreter, which has no `argv` to spawn
+ *     with.
+ *
+ * A single renderer keeps a granted capability and the command a browser
+ * actually runs from drifting apart.
+ *
+ * The module is pure string handling — no host access — so it stays on the
+ * browser-safe side of the package.
+ */
+import type * as ChildProcess from "effect/unstable/process/ChildProcess";
+/**
+ * Quotes one token for a POSIX shell, leaving obviously safe tokens alone.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export declare const quote: (token: string) => string;
+/**
+ * Renders a `Command` as a single shell command line.
+ *
+ * A standard command with `shell: true` renders its tokens verbatim, matching
+ * the line Node and the browser interpreter hand to the default shell. A
+ * custom shell renders as an explicit `<shell> -c <line>` invocation so the
+ * selected executable is part of the permission resource. Without `shell`,
+ * every token is POSIX-quoted to preserve literal argv semantics. These
+ * distinctions are security-sensitive: the rendered value is also the
+ * `proc:spawn` capability resource, so it must describe what will execute.
+ * The rendering is POSIX-only by contract: on Windows, Node invokes the shell
+ * with `/d /s /c` rather than `-c`, so the rendered line describes the POSIX
+ * invocation, not a cmd.exe one.
+ *
+ * The `proc:spawn` capability resource is {@link resource}, which starts from
+ * this line and adds what the line alone cannot show.
+ *
+ * A `PipedCommand` renders with `|` between its sides. That is a faithful
+ * rendering of what the pipeline does, and it is the only form an interpreter
+ * that takes a command line rather than an `argv` can be given. `from`/`to`
+ * pipe options are *not* expressible this way; rendering ignores them, so a
+ * pipeline that redirects `stderr` renders like one that pipes `stdout`.
+ * Capability checks therefore see the commands, never the plumbing.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export declare const render: (command: ChildProcess.Command) => string;
+/**
+ * What {@link resource} compares a stage against, supplied by the spawner that
+ * checks it.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export interface ResourceContext {
+    /**
+     * The environment the spawning process itself holds. A bootstrap name
+     * (`PATH`, `HOME`, ...) whose declared value equals the ambient value is the
+     * inherited default and stays out of the resource; one set to anything else
+     * is named. Omitted, every declared bootstrap name is named.
+     */
+    readonly ambient?: Readonly<Record<string, string | undefined>> | undefined;
+    /**
+     * Whether a stage's working directory is inside the directory the flow
+     * already governs. A `cwd` it rejects is named in the resource. Omitted,
+     * every `cwd` a stage sets is named.
+     */
+    readonly contains?: ((directory: string) => boolean) | undefined;
+    /**
+     * The stage `cwd` with every symlink resolved, when the host could resolve
+     * it. It replaces the lexical `cwd` both for `contains` and in the
+     * `cwd <path> -- ` prefix, so a symlink inside the governed directory that
+     * leads out of it is judged, and shown, by where the command really runs.
+     */
+    readonly resolvedCwd?: string | undefined;
+}
+/**
+ * The stages of a command in execution order: the command itself, or every
+ * `StandardCommand` of a pipeline from left to right. The spawner checks each
+ * stage as its own `proc:spawn` capability.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.1
+ */
+export declare const stages: (command: ChildProcess.Command) => ReadonlyArray<ChildProcess.StandardCommand>;
+/**
+ * The `proc:spawn` capability resource for one stage: {@link render}, with
+ * three additions that keep a prefix grant from authorizing code the stage
+ * never named.
+ *
+ *  - A `shell: true` stage whose line holds shell control syntax (`;`, `&`,
+ *    `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`, or a line break) is marked as the
+ *    explicit `sh -c '<line>'` it is. A grant such as `git status *` then
+ *    cannot match `git status; curl x | sh`, while a simple shell line such as
+ *    `git status --short` keeps its verbatim resource. An fd duplication such
+ *    as `2>&1` and a discard to `/dev/null` do not count as control syntax.
+ *  - A stage that sets an environment variable the child would not otherwise
+ *    inherit is prefixed with `env <NAME>… -- `, sorted names only. That is
+ *    every name outside the bootstrap set `ChildProcessEnvironment` inherits
+ *    (`PATH`, `HOME`, `USER`, `LANG`, `TERM`, `TMPDIR`, `SHELL`, `LC_*`), and a
+ *    bootstrap name whose value differs from `context.ambient`. A grant for
+ *    `git status` covers neither `env GIT_SSH_COMMAND -- git status` nor
+ *    `env PATH -- git status`. Values never enter the resource because they
+ *    often carry credentials.
+ *  - A stage whose `cwd` `context.contains` rejects is prefixed with
+ *    `cwd <path> -- `, so a grant does not follow the command into a
+ *    directory whose configuration the flow does not govern. When
+ *    `context.resolvedCwd` is given, that real path is judged and named
+ *    instead of the lexical `cwd`.
+ *
+ * A pipeline has no single resource: the spawner checks every one of its
+ * {@link stages}, so `git status | sh` needs a grant for `sh` too.
+ *
+ * The `env` and `cwd` prefixes share their spelling with a literal command:
+ * `make("env", ["PATH", "--", "git", "status"])` renders as
+ * `env PATH -- git status`, the resource of `git status` with `PATH`
+ * overridden. The alias grants nothing extra. The literal command runs a
+ * program named `PATH` (or `cwd`) from the ambient `PATH`, not `git`. A grant
+ * with `*` inside the prefix, such as `env * -- git status`, also matches
+ * `env -C /x -- git status`, but it already admits any variable name,
+ * including `GIT_SSH_COMMAND` and `LD_PRELOAD`, which run arbitrary code.
+ * Grant a prefixed resource exactly as the request shows it.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.1
+ */
+export declare const resource: (command: ChildProcess.StandardCommand, context?: ResourceContext) => string;
+/**
+ * The executable a command runs, without its arguments.
+ *
+ * A durable record of a spawned process names its program with this rather
+ * than with {@link render}: arguments carry credentials (`curl -u user:pass`,
+ * `mysql -phunter2`), and a journal that keeps them keeps them permanently.
+ * Nothing that reads such a record needs more than the program name; a reaper
+ * matches processes by pid and process group.
+ *
+ * Without `shell`, `command` is the executable itself, spaces and all. With a
+ * shell, the line is what runs, so the program is its first token: both
+ * `make("mysql -phunter2", [], { shell: true })` and
+ * `make("mysql", ["-phunter2"])` yield `mysql`. A pipeline names one
+ * executable per stage, joined the way {@link render} joins the stages.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export declare const executable: (command: ChildProcess.Command) => string;
+/**
+ * The working directory a command runs in, taking the leftmost stage of a
+ * pipeline, which is the stage `setCwd` and the spawners agree to treat as the
+ * pipeline's own directory.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export declare const cwd: (command: ChildProcess.Command) => string | undefined;
+/**
+ * The environment overrides a command runs with, taking the leftmost stage of
+ * a pipeline for the same reason {@link cwd} does.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export declare const env: (command: ChildProcess.Command) => Record<string, string | undefined> | undefined;
+//# sourceMappingURL=CommandLine.d.ts.map

package/dist/esm/CommandLine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLine.d.ts","sourceRoot":"","sources":["../../src/CommandLine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,YAAY,MAAM,sCAAsC,CAAA;AAMzE;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,MAC4C,CAAA;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,MAAM,GAAI,SAAS,YAAY,CAAC,OAAO,KAAG,MAOG,CAAA;AAiB1D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IAC3E;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAA;IAChE;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAgBD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,SAAS,YAAY,CAAC,OAAO,KAAG,aAAa,CAAC,YAAY,CAAC,eAAe,CACK,CAAA;AAEtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,YAAY,CAAC,eAAe,EAAE,UAAS,eAAoB,KAAG,MAW/F,CAAA;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,YAAY,CAAC,OAAO,KAAG,MAKO,CAAA;AAElE;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,GAAI,SAAS,YAAY,CAAC,OAAO,KAAG,MAAM,GAAG,SACiB,CAAA;AAE9E;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,GACd,SAAS,YAAY,CAAC,OAAO,KAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SACsC,CAAA"}