@smthrs/std 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/Container.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The host's route into a named container, as an injected transport.
+ *
+ * A task whose interpreter, dependencies, and test runner live in a container
+ * makes every command a nested quoting problem: the agent writes
+ * `docker exec c bash -lc 'cd /testbed && python - <<EOF … EOF'`, and one layer
+ * of that stack eats a quote. The measured cost across the 45-instance program
+ * was twelve failed probes, one instance's single most expensive frame
+ * (astropy-8707, which produced a probe that never ran), and a class of failure
+ * that turns from a broken probe into a broken *edit* the moment the same
+ * quoting reaches a writing command.
+ *
+ * So the transport is the harness's, not the agent's. A caller names the
+ * container and passes its program and payload as data; this service turns that
+ * into the argv the host actually spawns. `docker` and `podman` share the CLI
+ * {@link makeCommand} builds, and a host with a different route supplies its own
+ * {@link make} rather than teaching the agent a new incantation.
+ *
+ * A host that has no container route provides {@link makeNoop}, whose refusal
+ * says so plainly. Nothing here shells out on its own: it only decides an argv,
+ * and `bash` spawns it through the same permission-aware spawner as everything
+ * else.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, Layer } from "effect";
+import * as StdError from "./StdError.ts";
+/**
+ * One command to run inside a container.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Request {
+    readonly container: string;
+    readonly file: string;
+    readonly args: ReadonlyArray<string>;
+    readonly cwd?: string | undefined;
+    readonly env?: Record<string, string> | undefined;
+    /** Whether the payload arrives on the program's standard input. */
+    readonly stdin: boolean;
+}
+/**
+ * The argv the host spawns to satisfy a {@link Request}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Plan {
+    readonly file: string;
+    readonly args: ReadonlyArray<string>;
+    /** Environment overrides for the transport process, never rendered as argv. */
+    readonly env?: Record<string, string> | undefined;
+}
+/**
+ * The one container transport contract.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export interface Container {
+    readonly exec: (request: Request) => Effect.Effect<Plan, StdError.StdError>;
+}
+/**
+ * The {@link Container} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export declare const Container: Context.Service<Container, Container>;
+/**
+ * Builds a container transport from its one operation.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (service: Container) => Container;
+/**
+ * The refusal a host with no container route answers with.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const unavailable: (container: string) => StdError.StdError;
+/**
+ * Builds the transport for a host with no container route.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeNoop: () => Container;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerNoop: Layer.Layer<Container>;
+/**
+ * Builds a transport over a `docker exec`-compatible CLI.
+ *
+ * `-i` is attached only when the payload arrives on standard input, because a
+ * container CLI that holds stdin open for a command that never reads it makes
+ * that command hang.
+ *
+ * Requested environment variables never reach the transport process under
+ * their own names. The request's `env` is the caller's, and the transport is a
+ * host program: `PATH`, `LD_PRELOAD`, `DOCKER_HOST` or `XDG_CONFIG_HOME` set on
+ * it would choose what runs on the host. Each value therefore travels in
+ * {@link Plan.env} under `SMITHERS_CONTAINER_ENV_`, is forwarded by that name
+ * (`-e SMITHERS_CONTAINER_ENV_KEY`), and a `sh` inside the container renames it
+ * to `KEY` before `exec`ing the program. Values stay out of the argv. A name
+ * must be a POSIX shell name. A request with `env` therefore requires `sh` in
+ * the container; one without `env` runs the program directly, so an image
+ * without a shell works only for requests that carry no `env`.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeCommand: (options?: {
+    readonly program?: string | undefined;
+}) => Container;
+/**
+ * Provides {@link makeCommand}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerCommand: (options?: {
+    readonly program?: string | undefined;
+}) => Layer.Layer<Container>;
+//# sourceMappingURL=Container.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Container.d.ts","sourceRoot":"","sources":["../../src/Container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACjD,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;CAClD;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;CAC5E;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAA4C,CAAA;AAExG;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,SAAS,KAAG,SAAkC,CAAA;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,KAAG,QAAQ,CAAC,QAKrD,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAO,SAAqF,CAAA;AAEjH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAwC,CAAA;AAerF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,KAAG,SAuDjF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,KAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CACxD,CAAA"}

package/dist/esm/Container.js

@@ -0,0 +1,151 @@
+/**
+ * The host's route into a named container, as an injected transport.
+ *
+ * A task whose interpreter, dependencies, and test runner live in a container
+ * makes every command a nested quoting problem: the agent writes
+ * `docker exec c bash -lc 'cd /testbed && python - <<EOF … EOF'`, and one layer
+ * of that stack eats a quote. The measured cost across the 45-instance program
+ * was twelve failed probes, one instance's single most expensive frame
+ * (astropy-8707, which produced a probe that never ran), and a class of failure
+ * that turns from a broken probe into a broken *edit* the moment the same
+ * quoting reaches a writing command.
+ *
+ * So the transport is the harness's, not the agent's. A caller names the
+ * container and passes its program and payload as data; this service turns that
+ * into the argv the host actually spawns. `docker` and `podman` share the CLI
+ * {@link makeCommand} builds, and a host with a different route supplies its own
+ * {@link make} rather than teaching the agent a new incantation.
+ *
+ * A host that has no container route provides {@link makeNoop}, whose refusal
+ * says so plainly. Nothing here shells out on its own: it only decides an argv,
+ * and `bash` spawns it through the same permission-aware spawner as everything
+ * else.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, Layer } from "effect";
+import * as StdError from "./StdError.js";
+/**
+ * The {@link Container} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export const Container = Context.Service("@smthrs/std/Container");
+/**
+ * Builds a container transport from its one operation.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (service) => Container.of(service);
+/**
+ * The refusal a host with no container route answers with.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export const unavailable = (container) => new StdError.StdError({
+    code: "provider_unavailable",
+    message: `This host has no container transport, so it cannot run anything in "${container}". Drop the container field and run the command here, or ask the host to bind one.`
+});
+/**
+ * Builds the transport for a host with no container route.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeNoop = () => make({ exec: (request) => Effect.fail(unavailable(request.container)) });
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerNoop = Layer.succeed(Container, makeNoop());
+/** The names a forwarded environment variable may take: a POSIX shell name. */
+const environmentName = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The prefix a forwarded variable carries on the host transport process. */
+const forwardedPrefix = "SMITHERS_CONTAINER_ENV_";
+/** The in-container script that renames each forwarded variable, then runs the program. */
+const rename = (names) => [
+    ...names.map((key) => `${key}="$${forwardedPrefix}${key}"; export ${key}; unset ${forwardedPrefix}${key}`),
+    `exec "$@"`
+].join("; ");
+/**
+ * Builds a transport over a `docker exec`-compatible CLI.
+ *
+ * `-i` is attached only when the payload arrives on standard input, because a
+ * container CLI that holds stdin open for a command that never reads it makes
+ * that command hang.
+ *
+ * Requested environment variables never reach the transport process under
+ * their own names. The request's `env` is the caller's, and the transport is a
+ * host program: `PATH`, `LD_PRELOAD`, `DOCKER_HOST` or `XDG_CONFIG_HOME` set on
+ * it would choose what runs on the host. Each value therefore travels in
+ * {@link Plan.env} under `SMITHERS_CONTAINER_ENV_`, is forwarded by that name
+ * (`-e SMITHERS_CONTAINER_ENV_KEY`), and a `sh` inside the container renames it
+ * to `KEY` before `exec`ing the program. Values stay out of the argv. A name
+ * must be a POSIX shell name. A request with `env` therefore requires `sh` in
+ * the container; one without `env` runs the program directly, so an image
+ * without a shell works only for requests that carry no `env`.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeCommand = (options) => {
+    const program = options?.program ?? "docker";
+    return make({
+        exec: (request) => {
+            const env = request.env;
+            const entries = Object.entries(env ?? {});
+            const names = entries.map(([key]) => key);
+            const invalid = names.find((key) => !environmentName.test(key));
+            if (invalid !== undefined) {
+                return Effect.fail(new StdError.StdError({
+                    code: "invalid_input",
+                    message: `Environment variable names must match ${environmentName.source}: ${invalid}`
+                }));
+            }
+            if (request.container === "" || request.container.startsWith("-")) {
+                return Effect.fail(new StdError.StdError({
+                    code: "invalid_input",
+                    message: `Container name must be non-empty and cannot start with '-': ${request.container}`,
+                    path: request.container
+                }));
+            }
+            const args = Array.from(request.args);
+            if (args.some((arg) => typeof arg !== "string")) {
+                return Effect.fail(new StdError.StdError({
+                    code: "invalid_input",
+                    message: "Container arguments must be a dense array of strings."
+                }));
+            }
+            return Effect.succeed({
+                file: program,
+                args: [
+                    "exec",
+                    ...(request.stdin ? ["-i"] : []),
+                    ...(request.cwd === undefined ? [] : ["-w", request.cwd]),
+                    ...names.flatMap((key) => ["-e", `${forwardedPrefix}${key}`]),
+                    "--",
+                    request.container,
+                    ...(names.length === 0 ? [] : ["sh", "-c", rename(names), "sh"]),
+                    request.file,
+                    ...args
+                ],
+                ...(env === undefined ? {} : {
+                    env: Object.fromEntries(entries.map(([key, value]) => [`${forwardedPrefix}${key}`, value]))
+                })
+            });
+        }
+    });
+};
+/**
+ * Provides {@link makeCommand}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerCommand = (options) => Layer.succeed(Container, makeCommand(options));
+//# sourceMappingURL=Container.js.map

package/dist/esm/Container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Container.js","sourceRoot":"","sources":["../../src/Container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAyCzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAA0C,OAAO,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAA;AAExG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAkB,EAAa,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAiB,EAAqB,EAAE,CAClE,IAAI,QAAQ,CAAC,QAAQ,CAAC;IACpB,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EACL,uEAAuE,SAAS,oFAAoF;CACvK,CAAC,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAc,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAA;AAEjH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAA2B,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAA;AAErF,+EAA+E;AAC/E,MAAM,eAAe,GAAG,0BAA0B,CAAA;AAElD,6EAA6E;AAC7E,MAAM,eAAe,GAAG,yBAAyB,CAAA;AAEjD,2FAA2F;AAC3F,MAAM,MAAM,GAAG,CAAC,KAA4B,EAAU,EAAE,CACtD;IACE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,eAAe,GAAG,GAAG,aAAa,GAAG,WAAW,eAAe,GAAG,GAAG,EAAE,CAAC;IAC1G,WAAW;CACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEd;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAmD,EAAa,EAAE;IAC5F,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,QAAQ,CAAA;IAC5C,OAAO,IAAI,CAAC;QACV,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE;YAChB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAA;YACvB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,CAAA;YACzC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAA;YACzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;YAC/D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,MAAM,CAAC,IAAI,CAChB,IAAI,QAAQ,CAAC,QAAQ,CAAC;oBACpB,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,yCAAyC,eAAe,CAAC,MAAM,KAAK,OAAO,EAAE;iBACvF,CAAC,CACH,CAAA;YACH,CAAC;YACD,IAAI,OAAO,CAAC,SAAS,KAAK,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClE,OAAO,MAAM,CAAC,IAAI,CAChB,IAAI,QAAQ,CAAC,QAAQ,CAAC;oBACpB,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,+DAA+D,OAAO,CAAC,SAAS,EAAE;oBAC3F,IAAI,EAAE,OAAO,CAAC,SAAS;iBACxB,CAAC,CACH,CAAA;YACH,CAAC;YACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACrC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAChD,OAAO,MAAM,CAAC,IAAI,CAChB,IAAI,QAAQ,CAAC,QAAQ,CAAC;oBACpB,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,uDAAuD;iBACjE,CAAC,CACH,CAAA;YACH,CAAC;YACD,OAAO,MAAM,CAAC,OAAO,CAAC;gBACpB,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE;oBACJ,MAAM;oBACN,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChC,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;oBACzD,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,eAAe,GAAG,GAAG,EAAE,CAAC,CAAC;oBAC7D,IAAI;oBACJ,OAAO,CAAC,SAAS;oBACjB,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;oBAChE,OAAO,CAAC,IAAI;oBACZ,GAAG,IAAI;iBACR;gBACD,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBAC3B,GAAG,EAAE,MAAM,CAAC,WAAW,CACrB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,eAAe,GAAG,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC,CACnE;iBACF,CAAC;aACH,CAAC,CAAA;QACJ,CAAC;KACF,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAmD,EAA0B,EAAE,CAC1G,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The host's route into a named container, as an injected transport.\n *\n * A task whose interpreter, dependencies, and test runner live in a container\n * makes every command a nested quoting problem: the agent writes\n * `docker exec c bash -lc 'cd /testbed && python - <<EOF … EOF'`, and one layer\n * of that stack eats a quote. The measured cost across the 45-instance program\n * was twelve failed probes, one instance's single most expensive frame\n * (astropy-8707, which produced a probe that never ran), and a class of failure\n * that turns from a broken probe into a broken *edit* the moment the same\n * quoting reaches a writing command.\n *\n * So the transport is the harness's, not the agent's. A caller names the\n * container and passes its program and payload as data; this service turns that\n * into the argv the host actually spawns. `docker` and `podman` share the CLI\n * {@link makeCommand} builds, and a host with a different route supplies its own\n * {@link make} rather than teaching the agent a new incantation.\n *\n * A host that has no container route provides {@link makeNoop}, whose refusal\n * says so plainly. Nothing here shells out on its own: it only decides an argv,\n * and `bash` spawns it through the same permission-aware spawner as everything\n * else.\n *\n * @since 1.0.0\n */\n\nimport { Context, Effect, Layer } from \"effect\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * One command to run inside a container.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Request {\n  readonly container: string\n  readonly file: string\n  readonly args: ReadonlyArray<string>\n  readonly cwd?: string | undefined\n  readonly env?: Record<string, string> | undefined\n  /** Whether the payload arrives on the program's standard input. */\n  readonly stdin: boolean\n}\n\n/**\n * The argv the host spawns to satisfy a {@link Request}.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Plan {\n  readonly file: string\n  readonly args: ReadonlyArray<string>\n  /** Environment overrides for the transport process, never rendered as argv. */\n  readonly env?: Record<string, string> | undefined\n}\n\n/**\n * The one container transport contract.\n *\n * @category services\n * @since 1.0.0\n */\nexport interface Container {\n  readonly exec: (request: Request) => Effect.Effect<Plan, StdError.StdError>\n}\n\n/**\n * The {@link Container} service tag.\n *\n * @category services\n * @since 1.0.0\n */\nexport const Container: Context.Service<Container, Container> = Context.Service(\"@smthrs/std/Container\")\n\n/**\n * Builds a container transport from its one operation.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (service: Container): Container => Container.of(service)\n\n/**\n * The refusal a host with no container route answers with.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const unavailable = (container: string): StdError.StdError =>\n  new StdError.StdError({\n    code: \"provider_unavailable\",\n    message:\n      `This host has no container transport, so it cannot run anything in \"${container}\". Drop the container field and run the command here, or ask the host to bind one.`\n  })\n\n/**\n * Builds the transport for a host with no container route.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeNoop = (): Container => make({ exec: (request) => Effect.fail(unavailable(request.container)) })\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerNoop: Layer.Layer<Container> = Layer.succeed(Container, makeNoop())\n\n/** The names a forwarded environment variable may take: a POSIX shell name. */\nconst environmentName = /^[A-Za-z_][A-Za-z0-9_]*$/\n\n/** The prefix a forwarded variable carries on the host transport process. */\nconst forwardedPrefix = \"SMITHERS_CONTAINER_ENV_\"\n\n/** The in-container script that renames each forwarded variable, then runs the program. */\nconst rename = (names: ReadonlyArray<string>): string =>\n  [\n    ...names.map((key) => `${key}=\"$${forwardedPrefix}${key}\"; export ${key}; unset ${forwardedPrefix}${key}`),\n    `exec \"$@\"`\n  ].join(\"; \")\n\n/**\n * Builds a transport over a `docker exec`-compatible CLI.\n *\n * `-i` is attached only when the payload arrives on standard input, because a\n * container CLI that holds stdin open for a command that never reads it makes\n * that command hang.\n *\n * Requested environment variables never reach the transport process under\n * their own names. The request's `env` is the caller's, and the transport is a\n * host program: `PATH`, `LD_PRELOAD`, `DOCKER_HOST` or `XDG_CONFIG_HOME` set on\n * it would choose what runs on the host. Each value therefore travels in\n * {@link Plan.env} under `SMITHERS_CONTAINER_ENV_`, is forwarded by that name\n * (`-e SMITHERS_CONTAINER_ENV_KEY`), and a `sh` inside the container renames it\n * to `KEY` before `exec`ing the program. Values stay out of the argv. A name\n * must be a POSIX shell name. A request with `env` therefore requires `sh` in\n * the container; one without `env` runs the program directly, so an image\n * without a shell works only for requests that carry no `env`.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeCommand = (options?: { readonly program?: string | undefined }): Container => {\n  const program = options?.program ?? \"docker\"\n  return make({\n    exec: (request) => {\n      const env = request.env\n      const entries = Object.entries(env ?? {})\n      const names = entries.map(([key]) => key)\n      const invalid = names.find((key) => !environmentName.test(key))\n      if (invalid !== undefined) {\n        return Effect.fail(\n          new StdError.StdError({\n            code: \"invalid_input\",\n            message: `Environment variable names must match ${environmentName.source}: ${invalid}`\n          })\n        )\n      }\n      if (request.container === \"\" || request.container.startsWith(\"-\")) {\n        return Effect.fail(\n          new StdError.StdError({\n            code: \"invalid_input\",\n            message: `Container name must be non-empty and cannot start with '-': ${request.container}`,\n            path: request.container\n          })\n        )\n      }\n      const args = Array.from(request.args)\n      if (args.some((arg) => typeof arg !== \"string\")) {\n        return Effect.fail(\n          new StdError.StdError({\n            code: \"invalid_input\",\n            message: \"Container arguments must be a dense array of strings.\"\n          })\n        )\n      }\n      return Effect.succeed({\n        file: program,\n        args: [\n          \"exec\",\n          ...(request.stdin ? [\"-i\"] : []),\n          ...(request.cwd === undefined ? [] : [\"-w\", request.cwd]),\n          ...names.flatMap((key) => [\"-e\", `${forwardedPrefix}${key}`]),\n          \"--\",\n          request.container,\n          ...(names.length === 0 ? [] : [\"sh\", \"-c\", rename(names), \"sh\"]),\n          request.file,\n          ...args\n        ],\n        ...(env === undefined ? {} : {\n          env: Object.fromEntries(\n            entries.map(([key, value]) => [`${forwardedPrefix}${key}`, value])\n          )\n        })\n      })\n    }\n  })\n}\n\n/**\n * Provides {@link makeCommand}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerCommand = (options?: { readonly program?: string | undefined }): Layer.Layer<Container> =>\n  Layer.succeed(Container, makeCommand(options))\n"]}

package/dist/esm/Edit.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Edit flow declaration and portable handler.
+ *
+ * Three rules, each of them paid for by a measured failure:
+ *
+ * 1. **Exact or loud.** The anchor matches the file's bytes or the call fails
+ *    with the file's actual bytes at the nearest region. No fuzzy apply reports
+ *    success (sympy-15380 corrupted a file that way), and no failure returns a
+ *    bare `null` (sphinx-7590 abandoned a correct edit twice against one).
+ * 2. **Anchors by reference.** A prior `grep` or `read` already located the
+ *    region; `startLine`/`endLine` re-use that hit instead of retyping the text,
+ *    and `expect` turns the retyped copy into a checked assertion rather than a
+ *    search key.
+ * 3. **The hunk comes back.** The result carries the applied region as raw text
+ *    with its line range, so a mis-indented edit costs one glance instead of an
+ *    investigation (sphinx-7233 lost its verdict to a hunk nobody could see).
+ *    With a `LanguageServer` bound, the file's errors after the edit come back
+ *    too.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import * as StdError from "./StdError.ts";
+/**
+ * Registry name for the edit flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "edit";
+/**
+ * Model-facing description of the edit flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "Edit a file by exact text (oldString, unique unless replaceAll) or by an earlier hit's line range (startLine/endLine, optional expect). A miss returns the file's real text; a hit returns the hunk.";
+/**
+ * Input schema for the edit flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly oldString: Schema.optional<Schema.String>;
+    readonly startLine: Schema.optional<Schema.Int>;
+    readonly endLine: Schema.optional<Schema.Int>;
+    readonly expect: Schema.optional<Schema.String>;
+    readonly newString: Schema.String;
+    readonly replaceAll: Schema.optional<Schema.Boolean>;
+}>;
+/**
+ * Decoded input accepted by the `edit` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output schema for the edit flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly replacements: Schema.Number;
+    readonly startLine: Schema.Number;
+    readonly endLine: Schema.Number;
+    readonly hunk: Schema.String;
+    readonly errors: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly line: Schema.Number;
+        readonly character: Schema.Number;
+        readonly message: Schema.String;
+    }>>>;
+}>;
+/**
+ * Decoded output returned by the `edit` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static conservative effect envelope for the edit flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the edit effect envelope to one input path.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the edit flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * Declaration-only edit flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "edit";
+    readonly description: "Edit a file by exact text (oldString, unique unless replaceAll) or by an earlier hit's line range (startLine/endLine, optional expect). A miss returns the file's real text; a hit returns the hunk.";
+    readonly input: Schema.Struct<{
+        readonly path: Schema.String;
+        readonly oldString: Schema.optional<Schema.String>;
+        readonly startLine: Schema.optional<Schema.Int>;
+        readonly endLine: Schema.optional<Schema.Int>;
+        readonly expect: Schema.optional<Schema.String>;
+        readonly newString: Schema.String;
+        readonly replaceAll: Schema.optional<Schema.Boolean>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly path: Schema.String;
+        readonly replacements: Schema.Number;
+        readonly startLine: Schema.Number;
+        readonly endLine: Schema.Number;
+        readonly hunk: Schema.String;
+        readonly errors: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly line: Schema.Number;
+            readonly character: Schema.Number;
+            readonly message: Schema.String;
+        }>>>;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const activity: "writes";
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const presentation: {
+    readonly verb: {
+        readonly pending: "editing";
+        readonly success: "edited";
+        readonly failure: "failed to edit";
+    };
+    readonly subject: "path";
+    readonly result: "edit";
+};
+/**
+ * Applies one exact-anchored edit through the permission-aware kernel filesystem.
+ *
+ * Every refusal names what the file actually holds. A non-unique match is a
+ * refusal rather than a silent first-match edit, and it reports the lines every
+ * occurrence sits on so the caller can widen the anchor without re-reading.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly path: string;
+    readonly newString: string;
+    readonly replaceAll?: boolean | undefined;
+    readonly endLine?: number | undefined;
+    readonly oldString?: string | undefined;
+    readonly startLine?: number | undefined;
+    readonly expect?: string | undefined;
+}) => Effect.Effect<{
+    readonly hunk: string;
+    readonly path: string;
+    readonly endLine: number;
+    readonly startLine: number;
+    readonly replacements: number;
+    readonly errors?: readonly {
+        readonly line: number;
+        readonly character: number;
+        readonly message: string;
+    }[] | undefined;
+}, StdError.StdError, FileSystem.FileSystem>;
+//# sourceMappingURL=Edit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Edit.d.ts","sourceRoot":"","sources":["../../src/Edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAQvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,SAAS,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,WAAW,yMACgL,CAAA;AAExM;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;;;EAgBhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;EAWjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAAuF,CAAA;AAE3G;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAK,CAAC,IAAI,+CAC6C,CAAA;AAEhG;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAAgE,CAAA;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;CAAsF,CAAA;AAEvG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAG,QAAiB,CAAA;AAEzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;;;;;;;;CAIf,CAAA;AAgDV;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;4CAwId,CAAA"}