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

package/src/Container.ts

@@ -0,0 +1,212 @@
+/**
+ * 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 const Container: Context.Service<Container, 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): Container => Container.of(service)
+
+/**
+ * The refusal a host with no container route answers with.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export const unavailable = (container: string): StdError.StdError =>
+  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 = (): Container => make({ exec: (request) => Effect.fail(unavailable(request.container)) })
+
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerNoop: Layer.Layer<Container> = 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: ReadonlyArray<string>): string =>
+  [
+    ...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?: { readonly program?: string | undefined }): Container => {
+  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?: { readonly program?: string | undefined }): Layer.Layer<Container> =>
+  Layer.succeed(Container, makeCommand(options))

package/src/Edit.ts

@@ -0,0 +1,366 @@
+/**
+ * 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 { capability, envelope } from "./internal/Declaration.ts"
+import * as Diagnostics from "./internal/Diagnostics.ts"
+import * as FileMutation from "./internal/FileMutation.ts"
+import * as FsFailure from "./internal/FsFailure.ts"
+import * as Match from "./internal/Match.ts"
+import * as Preserve from "./internal/Preserve.ts"
+import { sourceLines } from "./internal/Text.ts"
+import * as StdError from "./StdError.ts"
+
+/**
+ * Registry name for the edit flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "edit"
+
+/**
+ * Model-facing description of the edit flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export 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 const Input = Schema.Struct({
+  path: Schema.String.annotate({ description: "Path of the file to edit" }),
+  oldString: Schema.optional(Schema.String).annotate({
+    description: "Exact text to replace, byte for byte, including surrounding context"
+  }),
+  startLine: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "First 1-based line to replace, from a prior read or grep hit; pair with endLine"
+  }),
+  endLine: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "Last 1-based line to replace, inclusive"
+  }),
+  expect: Schema.optional(Schema.String).annotate({
+    description: "What those lines currently hold; the edit fails loudly if they hold anything else"
+  }),
+  newString: Schema.String.annotate({ description: "Replacement text" }),
+  replaceAll: Schema.optional(Schema.Boolean).annotate({ description: "Replace every occurrence instead of one" })
+})
+
+/**
+ * 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 const Output = Schema.Struct({
+  path: Schema.String.annotate({ description: "Path that was edited" }),
+  replacements: Schema.Number.annotate({ description: "Number of occurrences replaced" }),
+  startLine: Schema.Number.annotate({ description: "First 1-based line of the returned hunk" }),
+  endLine: Schema.Number.annotate({ description: "Last 1-based line of the returned hunk" }),
+  hunk: Schema.String.annotate({
+    description: "The edited region as it now stands, raw and with its exact indentation, plus two lines of context"
+  }),
+  errors: Schema.optional(Schema.Array(Diagnostics.Problem)).annotate({
+    description: "Errors the language server reports in the file after the edit; absent when no server answered"
+  })
+})
+
+/**
+ * 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 const effects = envelope({ tier: "compensable", mode: "hermetic", reads: ["/**"], writes: ["/**"] })
+
+/**
+ * Narrows the edit effect envelope to one input path.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (input: typeof Input.Type) =>
+  envelope({ tier: "compensable", mode: "hermetic", reads: [input.path], writes: [input.path] })
+
+/**
+ * Capabilities required by the edit flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**"), capability("fs:write", "/**")]
+
+/**
+ * Declaration-only edit flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * 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 const activity = "writes" as const
+
+/**
+ * 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 const presentation = {
+  verb: { pending: "editing", success: "edited", failure: "failed to edit" },
+  subject: "path",
+  result: "edit"
+} as const
+
+const invalid = (path: string, message: string): StdError.StdError =>
+  new StdError.StdError({ code: "invalid_input", message, path })
+
+/** The failure text for an anchor that is not in the file, with the file's own bytes. */
+const miss = (path: string, content: string, needle: string, subject: string): StdError.StdError => {
+  const region = Match.nearest(content, needle)
+  return new StdError.StdError({
+    code: "no_match",
+    message: region === undefined
+      ? `${subject} does not occur in ${path}, and no line of it occurs there either — this is the wrong file, or the region is not what you remember. Read it and anchor on what it actually holds.`
+      : `${subject} does not occur in ${path}. Lines ${region.startLine}-${region.endLine} actually hold this, raw:\n${region.text}\n\nCopy the lines you meant from that text, or anchor by startLine/endLine instead.`,
+    path
+  })
+}
+
+/** The byte span of an inclusive 1-based line range, or the failure explaining why not. */
+const lineSpan = (
+  path: string,
+  content: string,
+  startLine: number,
+  endLine: number
+): { readonly start: number; readonly end: number } | StdError.StdError => {
+  const lines = sourceLines(content)
+  if (endLine < startLine) return invalid(path, `endLine ${endLine} is before startLine ${startLine}`)
+  if (startLine > lines.length) {
+    return new StdError.StdError({
+      code: "offset_out_of_range",
+      message: `${path} has ${lines.length} lines, so line ${startLine} is outside it`,
+      path
+    })
+  }
+  if (endLine > lines.length) {
+    return new StdError.StdError({
+      code: "offset_out_of_range",
+      message: `Requested endLine ${endLine}, but ${path} has ${lines.length} lines`,
+      path
+    })
+  }
+  const last = endLine
+  let start = 0
+  for (let index = 0; index < startLine - 1; index++) start += lines[index]!.length + 1
+  let end = start
+  for (let index = startLine - 1; index < last; index++) end += lines[index]!.length + (index === last - 1 ? 0 : 1)
+  return { start, end }
+}
+
+/**
+ * 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 const run = Effect.fn("Edit.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, FileSystem.FileSystem> {
+  const fileSystem = yield* FileSystem.FileSystem
+  const byLines = input.startLine !== undefined || input.endLine !== undefined
+  if (input.oldString !== undefined && byLines) {
+    return yield* Effect.fail(
+      invalid(input.path, "Anchor by oldString or by startLine/endLine, not by both")
+    )
+  }
+  if (input.oldString === undefined && !byLines) {
+    return yield* Effect.fail(
+      invalid(input.path, "Give either oldString or a startLine/endLine range; use the write flow to create a file")
+    )
+  }
+  if (byLines && (input.startLine === undefined || input.endLine === undefined)) {
+    return yield* Effect.fail(invalid(input.path, "A line anchor needs both startLine and endLine"))
+  }
+  if (input.oldString === "") {
+    return yield* Effect.fail(
+      invalid(input.path, "oldString must not be empty; use the write flow to create a file")
+    )
+  }
+  if (input.oldString !== undefined && input.expect !== undefined) {
+    return yield* Effect.fail(invalid(input.path, "expect cannot be used with oldString"))
+  }
+  if (byLines && input.replaceAll !== undefined) {
+    return yield* Effect.fail(invalid(input.path, "replaceAll cannot be used with startLine/endLine"))
+  }
+  const edited = yield* Effect.scoped(Effect.gen(function*() {
+    const mutation = yield* FileMutation.acquire(fileSystem, [input.path])
+    const bytes = yield* mutation.read(
+      input.path,
+      fileSystem.readFile(input.path).pipe(
+        Effect.mapError(FsFailure.reading(input.path, `File not found: ${input.path}`))
+      )
+    )
+    if (bytes.includes(0)) {
+      return yield* Effect.fail(
+        new StdError.StdError({
+          code: "binary_file",
+          message: `Cannot read binary file: ${input.path}`,
+          path: input.path
+        })
+      )
+    }
+    const content = yield* Effect.try({
+      try: () => new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+      catch: () =>
+        new StdError.StdError({
+          code: "binary_file",
+          message: `File is not valid UTF-8: ${input.path}`,
+          path: input.path
+        })
+    })
+
+    const targets: Array<{ readonly start: number; readonly end: number }> = []
+    if (input.oldString !== undefined) {
+      const located = Match.locate(content, input.oldString)
+      if (located.length === 0) return yield* Effect.fail(miss(input.path, content, input.oldString, "oldString"))
+      if (located.length > 1 && input.replaceAll !== true) {
+        const at = located.map((span) => span.startLine).join(", ")
+        return yield* Effect.fail(
+          invalid(
+            input.path,
+            `oldString occurs ${located.length} times in ${input.path}, on lines ${at}; add surrounding context to pick one, anchor by startLine/endLine, or set replaceAll`
+          )
+        )
+      }
+      targets.push(...(input.replaceAll === true ? located : [located[0]!]))
+    } else {
+      const span = lineSpan(input.path, content, input.startLine!, input.endLine!)
+      if (span instanceof StdError.StdError) return yield* Effect.fail(span)
+      if (input.expect !== undefined && content.slice(span.start, span.end) !== input.expect) {
+        return yield* Effect.fail(
+          new StdError.StdError({
+            code: "no_match",
+            message:
+              `Lines ${input.startLine}-${input.endLine} of ${input.path} do not hold expect. They hold this, raw:\n${
+                content.slice(span.start, span.end)
+              }\n\nRe-read the file: it moved under the line numbers you anchored on.`,
+            path: input.path
+          })
+        )
+      }
+      targets.push(span)
+    }
+
+    let replaced = ""
+    let cursor = 0
+    for (const span of targets) {
+      replaced += content.slice(cursor, span.start) + input.newString
+      cursor = span.end
+    }
+    replaced += content.slice(cursor)
+    yield* mutation.commit(
+      [{
+        path: input.path,
+        content: new TextEncoder().encode(replaced)
+      }],
+      Preserve.writeFileString(fileSystem, input.path, replaced).pipe(
+        Effect.mapError((error) =>
+          error.reason.method === "chmod"
+            ? new StdError.StdError({
+              code: "command_failed",
+              message: `Could not preserve the mode of ${input.path} before replacement by chmod`,
+              path: input.path
+            })
+            : FsFailure.denied(input.path, () =>
+              new StdError.StdError({
+                code: "command_failed",
+                message: `Could not write ${input.path}`,
+                path: input.path
+              }))(
+                error
+              )
+        )
+      )
+    )
+    // Synced under the file lock, so a later edit's text never reaches the
+    // server before this one's.
+    const server = yield* Diagnostics.sync(input.path, replaced)
+    const first = targets[0]!
+    const applied = Match.hunk(replaced, first.start, first.start + input.newString.length)
+    const output: typeof Output.Type = {
+      path: input.path,
+      replacements: targets.length,
+      startLine: applied.startLine,
+      endLine: applied.endLine,
+      hunk: applied.text
+    }
+    return { output, server }
+  }))
+  // Without a synced text the server can only describe the file as it was.
+  const errors = edited.server === undefined ? undefined : yield* Diagnostics.errorsOf(edited.server, input.path)
+  return errors === undefined ? edited.output : { ...edited.output, errors }
+})