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

package/dist/cjs/internal/Walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Walk.d.ts","sourceRoot":"","sources":["../../../src/internal/Walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAK/C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAwC,CAAA;AAa3F;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,IAAI,CAAC,IAAI,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,KAAG,MAG9E,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACxB,YAAY,UAAU,CAAC,UAAU,EACjC,YAAY,aAAa,CAAC,MAAM,CAAC,KAChC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAKpC,CAAA;AAEH;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,GAChB,YAAY,UAAU,CAAC,UAAU,EACjC,MAAM,IAAI,CAAC,IAAI,EACf,MAAM,MAAM,EACZ,QAAQ,OAAO,EACf,kBAAgB,EAChB,WAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAoB,KACrE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAmEtC,CAAA"}

package/dist/cjs/internal/Walk.js

@@ -0,0 +1,108 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Walk_exports = {};
+__export(Walk_exports, {
+  files: () => files,
+  relativeForPattern: () => relativeForPattern,
+  skippedDirectories: () => skippedDirectories,
+  symbolicLinks: () => symbolicLinks
+});
+module.exports = __toCommonJS(Walk_exports);
+var import_effect = require("effect");
+var Ignore = __toESM(require("./Ignore.js"), 1);
+var Prune = __toESM(require("./Prune.js"), 1);
+var import_SearchContract = require("./SearchContract.js");
+const skippedDirectories = new Set(Prune.repositoryDirectories);
+const concurrency = 16;
+const relativeForPattern = (path, from, to) => {
+  const relative = path.relative(from, to);
+  return path.sep === "\\" ? relative.replaceAll("\\", "/") : relative;
+};
+const symbolicLinks = (fileSystem, candidates) => import_effect.Effect.forEach(
+  candidates,
+  (candidate) => fileSystem.readLink(candidate).pipe(import_effect.Effect.as(true), import_effect.Effect.orElseSucceed(() => false)),
+  { concurrency }
+);
+const files = (fileSystem, path, root, hidden, noIgnore = false, included = () => true) => import_effect.Effect.gen(function* () {
+  const info = yield* fileSystem.stat(root).pipe(import_effect.Effect.mapError((error) => (0, import_SearchContract.rootFailure)(root, error)));
+  if (info.type === "File") return { explicitFile: true, files: [path.normalize(root)], ignored: false };
+  const files2 = [];
+  let excluded = false;
+  const directories = [{
+    directory: root,
+    scopes: []
+  }];
+  while (directories.length > 0) {
+    const next = directories.pop();
+    const { directory } = next;
+    let scopes = next.scopes;
+    const children = yield* fileSystem.readDirectory(directory).pipe(
+      import_effect.Effect.catch(
+        (error) => directory === root ? import_effect.Effect.fail((0, import_SearchContract.rootFailure)(directory, error)) : import_effect.Effect.succeed([])
+      )
+    );
+    if (!noIgnore && children.includes(".gitignore")) {
+      const content = yield* fileSystem.readFileString(path.join(directory, ".gitignore")).pipe(
+        import_effect.Effect.orElseSucceed(() => "")
+      );
+      const scope = Ignore.parse(directory, content);
+      if (scope.rules.length > 0) scopes = [...scopes, scope];
+    }
+    const candidates = children.filter((child) => !skippedDirectories.has(child) && (hidden || !child.startsWith("."))).map((child) => path.join(directory, child));
+    const entries = yield* import_effect.Effect.forEach(candidates, (candidate) => fileSystem.stat(candidate).pipe(
+      import_effect.Effect.map((candidateInfo) => ({
+        candidate,
+        type: candidateInfo.type
+      })),
+      import_effect.Effect.orElseSucceed(() => ({ candidate, type: void 0 }))
+    ), { concurrency });
+    const nested = [];
+    for (const entry of entries) {
+      if (entry.type !== void 0 && Ignore.ignored(
+        scopes,
+        entry.candidate,
+        path.basename(entry.candidate),
+        entry.type === "Directory",
+        (from, to) => relativeForPattern(path, from, to)
+      )) {
+        if (entry.type === "Directory" || included(relativeForPattern(path, root, entry.candidate), path.basename(entry.candidate))) excluded = true;
+        continue;
+      }
+      if (entry.type === "Directory") nested.push(entry.candidate);
+      else if (entry.type === "File") files2.push(path.normalize(entry.candidate));
+    }
+    const links = yield* symbolicLinks(fileSystem, nested);
+    for (let index = 0; index < nested.length; index++) {
+      const candidate = nested[index];
+      if (links[index] !== true) directories.push({ directory: candidate, scopes });
+    }
+  }
+  return { explicitFile: false, files: files2.sort(), ignored: excluded };
+});
+//# sourceMappingURL=Walk.js.map

package/dist/cjs/internal/Walk.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/Walk.ts"],
+  "sourcesContent": ["/**\n * The directory names a repository walk never descends into.\n *\n * `grep` and `glob` walk with the kernel filesystem, and every entry costs a\n * guarded stat. A walk rooted at \".\" that descends into `.git` visits tens of\n * thousands of object files no search wants: one such `grep` held a benchmark\n * frame for its entire fifteen-minute ceiling. The skip set is the same\n * convention ripgrep ships \u2014 version control, dependency trees, and caches \u2014\n * and an explicit root inside a skipped directory still walks, because\n * skipping applies to descent, never to what the caller named.\n *\n * @since 1.0.0\n */\n\nimport type * as Path from \"@smthrs/kernel/Path\"\nimport { Effect } from \"effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport type * as StdError from \"../StdError.ts\"\nimport * as Ignore from \"./Ignore.ts\"\nimport * as Prune from \"./Prune.ts\"\nimport { rootFailure } from \"./SearchContract.ts\"\n\n/**\n * Directory basenames excluded from recursive descent.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const skippedDirectories: ReadonlySet<string> = new Set(Prune.repositoryDirectories)\n\n/**\n * How many filesystem questions one directory level asks at a time.\n *\n * A metadata call through the layer costs far more in fiber scheduling than in\n * kernel time, so asking one entry at a time is what makes a walk slow: the\n * same probe measured 28.8 \u00B5s sequentially and 6.0 \u00B5s at this width on the\n * SWE-bench pytest tree. The bound keeps the file-descriptor and thread-pool\n * pressure of a wide directory predictable.\n */\nconst concurrency = 16\n\n/**\n * Separates pattern path segments with slashes while preserving POSIX filenames.\n *\n * @private\n * @since 1.0.0\n */\nexport const relativeForPattern = (path: Path.Path, from: string, to: string): string => {\n  const relative = path.relative(from, to)\n  return path.sep === \"\\\\\" ? relative.replaceAll(\"\\\\\", \"/\") : relative\n}\n\n/**\n * Answers whether each path is a symbolic link, which neither peer follows.\n *\n * `FileSystem.stat` resolves links, so the only probe available is `readLink`,\n * and every probe is one more call in a loop that already makes one per entry.\n * The walk therefore probes directories, where following a link would duplicate\n * a subtree or loop forever, and the callers probe the far smaller set of files\n * they are about to report \u2014 batched, never one at a time.\n *\n * @private\n * @since 1.0.0\n */\nexport const symbolicLinks = (\n  fileSystem: FileSystem.FileSystem,\n  candidates: ReadonlyArray<string>\n): Effect.Effect<ReadonlyArray<boolean>> =>\n  Effect.forEach(\n    candidates,\n    (candidate) => fileSystem.readLink(candidate).pipe(Effect.as(true), Effect.orElseSucceed(() => false)),\n    { concurrency }\n  )\n\n/**\n * One walk: admitted files, explicit-root status, and ignore exclusions.\n *\n * @private\n * @since 1.0.0\n */\nexport interface Walked {\n  readonly ignored: boolean\n  readonly explicitFile: boolean\n  readonly files: ReadonlyArray<string>\n}\n\n/**\n * Lists the files a search under `root` reaches.\n *\n * Only the root the caller named is allowed to fail the walk. Every entry\n * below it that the process cannot inspect \u2014 a dangling symlink, a symlink\n * loop, a directory it may not list \u2014 is skipped and the walk continues, which\n * is what `rg --no-messages` does with the same tree. Turning one of those into\n * a typed failure would make a whole repository unsearchable because of one\n * link, and would answer differently from the native peer. Only .gitignore\n * files within this root are read; ignored directories are never descended.\n * `included` narrows the empty-result diagnostic without changing descent.\n *\n * @private\n * @since 1.0.0\n */\nexport const files = (\n  fileSystem: FileSystem.FileSystem,\n  path: Path.Path,\n  root: string,\n  hidden: boolean,\n  noIgnore = false,\n  included: (relative: string, basename: string) => boolean = () => true\n): Effect.Effect<Walked, StdError.StdError> =>\n  Effect.gen(function*() {\n    const info = yield* fileSystem.stat(root).pipe(Effect.mapError((error) => rootFailure(root, error)))\n    if (info.type === \"File\") return { explicitFile: true, files: [path.normalize(root)], ignored: false }\n    const files: Array<string> = []\n    let excluded = false\n    const directories: Array<{ directory: string; scopes: ReadonlyArray<Ignore.Scope> }> = [{\n      directory: root,\n      scopes: []\n    }]\n    while (directories.length > 0) {\n      const next = directories.pop()!\n      const { directory } = next\n      let scopes = next.scopes\n      const children: ReadonlyArray<string> = yield* fileSystem.readDirectory(directory).pipe(\n        Effect.catch((error) =>\n          directory === root\n            ? Effect.fail(rootFailure(directory, error))\n            : Effect.succeed<ReadonlyArray<string>>([])\n        )\n      )\n      if (!noIgnore && children.includes(\".gitignore\")) {\n        const content = yield* fileSystem.readFileString(path.join(directory, \".gitignore\")).pipe(\n          Effect.orElseSucceed(() => \"\")\n        )\n        const scope = Ignore.parse(directory, content)\n        if (scope.rules.length > 0) scopes = [...scopes, scope]\n      }\n      const candidates = children\n        .filter((child) => !skippedDirectories.has(child) && (hidden || !child.startsWith(\".\")))\n        .map((child) => path.join(directory, child))\n      const entries = yield* Effect.forEach(candidates, (candidate) =>\n        fileSystem.stat(candidate).pipe(\n          Effect.map((candidateInfo): { readonly candidate: string; readonly type: string | undefined } => ({\n            candidate,\n            type: candidateInfo.type\n          })),\n          Effect.orElseSucceed(() => ({ candidate, type: undefined }))\n        ), { concurrency })\n      const nested: Array<string> = []\n      for (const entry of entries) {\n        if (\n          entry.type !== undefined &&\n          Ignore.ignored(\n            scopes,\n            entry.candidate,\n            path.basename(entry.candidate),\n            entry.type === \"Directory\",\n            (from, to) => relativeForPattern(path, from, to)\n          )\n        ) {\n          if (\n            entry.type === \"Directory\" ||\n            included(relativeForPattern(path, root, entry.candidate), path.basename(entry.candidate))\n          ) excluded = true\n          continue\n        }\n        if (entry.type === \"Directory\") nested.push(entry.candidate)\n        else if (entry.type === \"File\") files.push(path.normalize(entry.candidate))\n      }\n      const links = yield* symbolicLinks(fileSystem, nested)\n      for (let index = 0; index < nested.length; index++) {\n        const candidate = nested[index]!\n        if (links[index] !== true) directories.push({ directory: candidate, scopes })\n      }\n    }\n    return { explicitFile: false, files: files.sort(), ignored: excluded }\n  })\n"],
+  "mappings": "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",
+  "names": ["files"]
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/ApplyPatch.d.ts

@@ -0,0 +1,174 @@
+/**
+ * apply_patch flow declaration and portable handler.
+ *
+ * A Codex CLI clone: the V4A patch grammar (`*** Begin Patch` /
+ * `*** Add File:` / `*** Update File:` / `*** Delete File:` /
+ * `*** End Patch`), the fuzzy context-matching applier, and Codex's error
+ * and summary text, expressed as a flow over the kernel filesystem.
+ *
+ * @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 apply_patch flow. Matches the Codex CLI tool name.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "apply_patch";
+/**
+ * Model-facing description of the apply_patch flow. Matches the Codex CLI
+ * freeform tool description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.";
+/**
+ * Input schema for the apply_patch flow.
+ *
+ * Codex delivers the patch as freeform text; the JSON function fallback uses
+ * a single `input` field, which is the shape cloned here.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly input: Schema.String;
+}>;
+/**
+ * Decoded input accepted by the `apply_patch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output schema for the apply_patch flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly output: Schema.String;
+    readonly added: Schema.$Array<Schema.String>;
+    readonly modified: Schema.$Array<Schema.String>;
+    readonly deleted: Schema.$Array<Schema.String>;
+}>;
+/**
+ * Decoded output returned by the `apply_patch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static conservative effect envelope for the apply_patch flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the effect envelope for a decoded invocation.
+ *
+ * A patch names its files inside its own text rather than in a decoded field,
+ * and the parse that finds them is the same parse that can fail, so there is
+ * nothing here to narrow before the handler runs: the static envelope is the
+ * honest answer.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the apply_patch flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * Declaration-only apply_patch flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "apply_patch";
+    readonly description: "The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.";
+    readonly input: Schema.Struct<{
+        readonly input: Schema.String;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly output: Schema.String;
+        readonly added: Schema.$Array<Schema.String>;
+        readonly modified: Schema.$Array<Schema.String>;
+        readonly deleted: Schema.$Array<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: "patching";
+        readonly success: "patched";
+        readonly failure: "failed to patch";
+    };
+    readonly subject: "patch";
+    readonly result: "patch";
+};
+/**
+ * Every path a patch writes, in the order it names them, including a move's
+ * destination. The patch is read by the parser {@link run} uses, so a header
+ * `run` accepts is never missed.
+ *
+ * Returns `undefined` when `run` would refuse the patch. A caller asking
+ * permission for the call then asks for everything the flow declares.
+ *
+ * @category parsing
+ * @since 1.0.0-rc.1
+ */
+export declare const paths: (patch: string) => ReadonlyArray<string> | undefined;
+/**
+ * Parses and applies a V4A patch through the permission-aware kernel
+ * filesystem, preserving Codex error text.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly input: string;
+}) => Effect.Effect<{
+    readonly output: string;
+    readonly added: readonly string[];
+    readonly modified: readonly string[];
+    readonly deleted: readonly string[];
+}, StdError.StdError, import("effect/Path").Path | FileSystem.FileSystem>;
+//# sourceMappingURL=ApplyPatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ApplyPatch.d.ts","sourceRoot":"","sources":["../../src/ApplyPatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAE/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAOvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,gBAAgB,CAAA;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,iHACwF,CAAA;AAEhH;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK;;EAEhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;EAOjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAAuF,CAAA;AAE3G;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAEhE;;;;;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;AAEV;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,aAAa,CAAC,MAAM,CAAC,GAAG,SAc7D,CAAA;AAsBD;;;;;;GAMG;AACH,eAAO,MAAM,GAAG;;;;;;;yEA0Pd,CAAA"}

package/dist/esm/ApplyPatch.js

@@ -0,0 +1,346 @@
+/**
+ * apply_patch flow declaration and portable handler.
+ *
+ * A Codex CLI clone: the V4A patch grammar (`*** Begin Patch` /
+ * `*** Add File:` / `*** Update File:` / `*** Delete File:` /
+ * `*** End Patch`), the fuzzy context-matching applier, and Codex's error
+ * and summary text, expressed as a flow over the kernel filesystem.
+ *
+ * @since 1.0.0
+ */
+import * as Path from "@smthrs/kernel/Path";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import * as ApplyPatchText from "./internal/ApplyPatch.js";
+import { capability, envelope } from "./internal/Declaration.js";
+import * as Diagnostics from "./internal/Diagnostics.js";
+import * as FileMutation from "./internal/FileMutation.js";
+import * as FsFailure from "./internal/FsFailure.js";
+import * as Preserve from "./internal/Preserve.js";
+import * as StdError from "./StdError.js";
+/**
+ * Registry name for the apply_patch flow. Matches the Codex CLI tool name.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "apply_patch";
+/**
+ * Model-facing description of the apply_patch flow. Matches the Codex CLI
+ * freeform tool description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description = "The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.";
+/**
+ * Input schema for the apply_patch flow.
+ *
+ * Codex delivers the patch as freeform text; the JSON function fallback uses
+ * a single `input` field, which is the shape cloned here.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+    input: Schema.String.annotate({ description: "The entire contents of the apply_patch command" })
+});
+/**
+ * Output schema for the apply_patch flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Schema.Struct({
+    output: Schema.String.annotate({
+        description: "Codex-style summary: 'Success. Updated the following files:' with A/M/D lines"
+    }),
+    added: Schema.Array(Schema.String).annotate({ description: "Paths of files created by the patch" }),
+    modified: Schema.Array(Schema.String).annotate({ description: "Paths of files updated by the patch" }),
+    deleted: Schema.Array(Schema.String).annotate({ description: "Paths of files deleted by the patch" })
+});
+/**
+ * Static conservative effect envelope for the apply_patch flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "compensable", mode: "hermetic", reads: ["/**"], writes: ["/**"] });
+/**
+ * Narrows the effect envelope for a decoded invocation.
+ *
+ * A patch names its files inside its own text rather than in a decoded field,
+ * and the parse that finds them is the same parse that can fail, so there is
+ * nothing here to narrow before the handler runs: the static envelope is the
+ * honest answer.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input) => effects;
+/**
+ * Capabilities required by the apply_patch flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**"), capability("fs:write", "/**")];
+/**
+ * Declaration-only apply_patch flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects };
+/**
+ * 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";
+/**
+ * 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: "patching", success: "patched", failure: "failed to patch" },
+    subject: "patch",
+    result: "patch"
+};
+/**
+ * Every path a patch writes, in the order it names them, including a move's
+ * destination. The patch is read by the parser {@link run} uses, so a header
+ * `run` accepts is never missed.
+ *
+ * Returns `undefined` when `run` would refuse the patch. A caller asking
+ * permission for the call then asks for everything the flow declares.
+ *
+ * @category parsing
+ * @since 1.0.0-rc.1
+ */
+export const paths = (patch) => {
+    let parsed;
+    try {
+        parsed = ApplyPatchText.parsePatch(patch);
+    }
+    catch {
+        return undefined;
+    }
+    return [
+        ...new Set(parsed.hunks.flatMap((hunk) => hunk.kind === "update" && hunk.movePath !== undefined ? [hunk.path, hunk.movePath] : [hunk.path]))
+    ];
+};
+/**
+ * The one sentence a model sees for a failure this handler did not design.
+ * The raw failure goes to the log, never into the tool result.
+ */
+const unknownFailureSentence = "Something went wrong on our side. Not your fault.";
+const unknownFailure = (error, path) => Effect.logError("apply_patch failed unexpectedly", error).pipe(Effect.andThen(Effect.fail(new StdError.StdError(path === undefined
+    ? { code: "command_failed", message: unknownFailureSentence }
+    : { code: "command_failed", message: unknownFailureSentence, path }))));
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Parses and applies a V4A patch through the permission-aware kernel
+ * filesystem, preserving Codex error text.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("ApplyPatch.run")(function* (input) {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    let parsed;
+    try {
+        parsed = ApplyPatchText.parsePatch(input.input);
+    }
+    catch (error) {
+        if (error instanceof ApplyPatchText.ParseError) {
+            return yield* Effect.fail(new StdError.StdError({ code: "invalid_input", message: error.message }));
+        }
+        return yield* unknownFailure(error);
+    }
+    // Every update hunk is derived from the file as it is on disk, so two
+    // sections naming one path both start from the same original and the second
+    // write erases the first — while the summary reports two modifications.
+    // The preflight cannot honestly validate the second section against a file
+    // the first has not written yet, so the patch is refused whole rather than
+    // applied by halves. A file needing several edits carries several `@@`
+    // chunks inside one section, which is the shape the parser already accepts.
+    // Resolve against the injected workspace, then follow existing filesystem
+    // aliases. For a new file, resolve its parent (which may be a symlink).
+    const identity = (value) => {
+        const resolved = path.resolve(value);
+        return fileSystem.realPath(resolved).pipe(Effect.catch((error) => error.reason._tag === "NotFound"
+            ? fileSystem.realPath(path.dirname(resolved)).pipe(Effect.map((parent) => path.resolve(parent, path.basename(resolved))), Effect.catch((parentError) => parentError.reason._tag === "NotFound"
+                ? Effect.succeed(resolved)
+                : Effect.fail(parentError)))
+            : Effect.fail(error)), Effect.mapError(FsFailure.denied(value, () => new StdError.StdError({
+            code: "command_failed",
+            message: `Failed to resolve patch path ${value}`,
+            path: value
+        }))));
+    };
+    const touched = new Set();
+    for (const hunk of parsed.hunks) {
+        const source = yield* identity(hunk.path);
+        const destination = hunk.kind === "update" && hunk.movePath !== undefined
+            ? yield* identity(hunk.movePath)
+            : undefined;
+        const claims = [[hunk.path, source]];
+        if (hunk.kind === "update" && hunk.movePath !== undefined && destination !== source) {
+            claims.push([hunk.movePath, destination]);
+        }
+        for (const [claimed, key] of claims) {
+            if (touched.has(key)) {
+                return yield* Effect.fail(new StdError.StdError({
+                    code: "invalid_input",
+                    message: `The patch names ${claimed} in more than one section; give one section per path`,
+                    path: claimed
+                }));
+            }
+            touched.add(key);
+        }
+    }
+    yield* FileMutation.validate(fileSystem, parsed.hunks.flatMap((hunk) => hunk.kind === "update" && hunk.movePath !== undefined ? [hunk.path, hunk.movePath] : [hunk.path]));
+    // Create only parents the patch already intends to create, before taking
+    // stable sibling locks for new destinations as well as existing sources.
+    for (const hunk of parsed.hunks) {
+        const destination = hunk.kind === "add" ? hunk.path : hunk.kind === "update" ? hunk.movePath : undefined;
+        if (destination !== undefined && !FileMutation.isVersioned(fileSystem)) {
+            yield* fileSystem.makeDirectory(path.dirname(destination), { recursive: true }).pipe(Effect.mapError(FsFailure.denied(destination, () => new StdError.StdError({
+                code: "command_failed",
+                message: `Failed to create parent directories for ${destination}`,
+                path: destination
+            }))));
+        }
+    }
+    return yield* Effect.scoped(Effect.gen(function* () {
+        const mutation = yield* FileMutation.acquire(fileSystem, parsed.hunks.flatMap((hunk) => hunk.kind === "update" && hunk.movePath !== undefined ? [hunk.path, hunk.movePath] : [hunk.path]), path);
+        const added = [];
+        const modified = [];
+        const deleted = [];
+        const prepared = new Map();
+        for (const hunk of parsed.hunks) {
+            if (hunk.kind !== "update")
+                continue;
+            const bytes = yield* mutation.read(hunk.path, fileSystem.readFile(hunk.path).pipe(Effect.mapError(FsFailure.reading(hunk.path, `Failed to read file to update ${hunk.path}`))));
+            if (bytes.includes(0)) {
+                return yield* Effect.fail(new StdError.StdError({
+                    code: "binary_file",
+                    message: `Cannot read binary file: ${hunk.path}`,
+                    path: hunk.path
+                }));
+            }
+            const original = yield* Effect.try({
+                try: () => decoder.decode(bytes),
+                catch: () => new StdError.StdError({
+                    code: "binary_file",
+                    message: `File is not valid UTF-8: ${hunk.path}`,
+                    path: hunk.path
+                })
+            });
+            let contents;
+            try {
+                contents = ApplyPatchText.deriveNewContents(original, hunk.path, hunk.chunks);
+            }
+            catch (error) {
+                if (error instanceof ApplyPatchText.ComputeReplacementsError) {
+                    return yield* Effect.fail(new StdError.StdError({ code: "no_match", message: error.message, path: hunk.path }));
+                }
+                return yield* unknownFailure(error, hunk.path);
+            }
+            prepared.set(hunk, contents);
+        }
+        // Prepare one complete provider request before touching any file. A move
+        // carries both its destination write and source removal in the same commit.
+        const changes = [];
+        const moves = new Set();
+        for (const hunk of parsed.hunks) {
+            if (hunk.kind === "delete") {
+                changes.push({ path: hunk.path, content: null });
+            }
+            else if (hunk.kind === "add") {
+                changes.push({ path: hunk.path, content: encoder.encode(hunk.contents) });
+            }
+            else {
+                changes.push({
+                    path: hunk.movePath ?? hunk.path,
+                    content: encoder.encode(prepared.get(hunk))
+                });
+                if (hunk.movePath !== undefined && (yield* identity(hunk.movePath)) !== (yield* identity(hunk.path))) {
+                    moves.add(hunk);
+                    changes.push({ path: hunk.path, content: null });
+                }
+            }
+        }
+        // A denial names itself, so the model does not retry a write the host refuses.
+        const mutationFailure = (code, message, offendingPath) => (error) => error.reason._tag === "PermissionDenied"
+            ? mutationError("permission_denied", `Permission denied: ${offendingPath}`, offendingPath)
+            : mutationError(code, message, offendingPath);
+        const mutationError = (code, message, offendingPath) => new StdError.StdError({
+            code,
+            message: `${message}; applied before failure: added=${JSON.stringify(added)}, modified=${JSON.stringify(modified)}, deleted=${JSON.stringify(deleted)}`,
+            path: offendingPath
+        });
+        yield* mutation.commit(changes, Effect.gen(function* () {
+            for (const hunk of parsed.hunks) {
+                switch (hunk.kind) {
+                    case "add": {
+                        yield* fileSystem.writeFile(hunk.path, encoder.encode(hunk.contents)).pipe(Effect.mapError(mutationFailure("command_failed", `Failed to write file ${hunk.path}`, hunk.path)));
+                        added.push(hunk.path);
+                        break;
+                    }
+                    case "delete": {
+                        yield* fileSystem.remove(hunk.path).pipe(Effect.mapError(mutationFailure("not_found", `Failed to delete file ${hunk.path}`, hunk.path)));
+                        deleted.push(hunk.path);
+                        break;
+                    }
+                    case "update": {
+                        const contents = prepared.get(hunk);
+                        const destination = hunk.movePath ?? hunk.path;
+                        yield* Preserve.writeFile(fileSystem, destination, encoder.encode(contents)).pipe(Effect.mapError((error) => error.reason.method === "chmod"
+                            ? mutationError("command_failed", `Could not preserve the mode of ${destination} before replacement by chmod`, destination)
+                            : mutationFailure("command_failed", `Failed to write file ${destination}`, destination)(error)));
+                        modified.push(destination);
+                        if (moves.has(hunk)) {
+                            yield* fileSystem.remove(hunk.path).pipe(Effect.mapError(mutationFailure("command_failed", `Failed to remove original ${hunk.path}`, hunk.path)));
+                        }
+                        break;
+                    }
+                }
+            }
+        }));
+        // Publish diagnostics only after the whole provider operation succeeds.
+        for (const change of changes) {
+            if (change.content === null)
+                yield* Diagnostics.close(path.resolve(change.path));
+            else
+                yield* Diagnostics.sync(path.resolve(change.path), decoder.decode(change.content));
+        }
+        const summary = {
+            added: parsed.hunks.filter((hunk) => hunk.kind === "add").map((hunk) => hunk.path),
+            deleted: parsed.hunks.filter((hunk) => hunk.kind === "delete").map((hunk) => hunk.path),
+            modified: parsed.hunks.filter((hunk) => hunk.kind === "update").map((hunk) => hunk.movePath ?? hunk.path)
+        };
+        return {
+            output: ApplyPatchText.printSummary(summary),
+            ...summary
+        };
+    }));
+});
+//# sourceMappingURL=ApplyPatch.js.map