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

package/dist/cjs/WebFetch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/WebFetch.ts"],
+  "sourcesContent": ["/**\n * The `webfetch` flow: an HTTP GET rendered as text, Markdown, or HTML.\n *\n * The handler fetches through the permission-checked `HttpClient`, follows at\n * most ten redirects, refuses a body over 5 MiB, and returns the final URL,\n * status, and content type beside the rendered body. The rendered body keeps\n * its first 60,000 bytes and reports any cut with `truncated` and `notice`.\n *\n * @since 1.0.0\n */\n\nimport type { GrantStore } from \"@smthrs/kernel/GrantStore\"\nimport * as HttpClient from \"@smthrs/kernel/HttpClient\"\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as HttpClientRequest from \"effect/unstable/http/HttpClientRequest\"\nimport { capability, envelope } from \"./internal/Declaration.ts\"\nimport { toMarkdown, toText } from \"./internal/Html.ts\"\nimport { capOutput, header, MAX_RESPONSE_BYTES, readBounded, Timeout, withDeadline } from \"./internal/Http.ts\"\nimport { guarded, refusal } from \"./internal/HttpNetwork.ts\"\nimport { parseHttpUrl } from \"./internal/Url.ts\"\nimport * as StdError from \"./StdError.ts\"\n\nconst maxRedirects = 10\n/**\n * The registry name of the `webfetch` flow.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"webfetch\"\n/**\n * The one-line description the model sees for the `webfetch` flow.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description = \"Fetch an HTTP URL and render its content as text, Markdown, or HTML.\"\n/**\n * What the `webfetch` flow accepts.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  url: Schema.String.annotate({ description: \"Absolute http or https URL to retrieve without user information\" }),\n  format: Schema.optional(Schema.Literals([\"text\", \"markdown\", \"html\"])).annotate({\n    description: \"Response rendering format; defaults to markdown\"\n  }),\n  timeout: Schema.optional(Timeout).annotate({\n    description: \"Total timeout across requests, redirects, and response body in seconds, capped at 120\"\n  })\n})\n/**\n * Decoded input accepted by the `webfetch` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n/**\n * What the `webfetch` flow returns.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  url: Schema.String.annotate({ description: \"Final URL after redirects\" }),\n  status: Schema.Int.annotate({ description: \"HTTP status code, including error statuses\" }),\n  contentType: Schema.String.annotate({ description: \"Response Content-Type header, or an empty string when absent\" }),\n  content: Schema.String.annotate({ description: \"Response body rendered in the requested format\" }),\n  truncated: Schema.Boolean.annotate({ description: \"Whether the rendered body exceeded the display budget\" }),\n  notice: Schema.optional(Schema.String.annotate({ description: \"Truncation disclosure\" }))\n})\n/**\n * Decoded output returned by the `webfetch` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n/**\n * The declared effect envelope of the `webfetch` flow, before any input is known.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({ tier: \"sealed\", mode: \"expected\", reads: [], writes: [] })\n/**\n * Narrows {@link effects} to what this particular input actually touches.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (_input: typeof Input.Type) => effects\n/**\n * The authority the `webfetch` flow requires.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"net:get\", \"*\")]\n/**\n * The `webfetch` flow declaration: schemas, capabilities, and effects, with the\n * implementation attached separately.\n *\n * @category flows\n * @since 1.0.0\n */\nexport const flow = { name, description, input: Input, output: Output, capabilities, effects } as const\n\nconst error = (code: StdError.Code, message: string, path?: string): StdError.StdError =>\n  new StdError.StdError({ code, message, ...(path === undefined ? {} : { path }) })\n/**\n * Runs the `webfetch` flow: fetches one HTTP URL and renders it as text.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"WebFetch.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<typeof Output.Type, StdError.StdError, HttpClient.HttpClient | GrantStore> {\n  let url = parseHttpUrl(input.url)\n  if (url === undefined) {\n    return yield* Effect.fail(\n      error(\"invalid_input\", \"URL must use http or https without user information\", input.url)\n    )\n  }\n  const client = guarded(yield* HttpClient.HttpClient, false)\n  let headers: Readonly<Record<string, string>> = {\n    accept: input.format === \"html\" ? \"text/html, text/plain;q=0.8\" : \"text/markdown, text/plain, text/html;q=0.8\"\n  }\n  for (let redirect = 0; redirect <= maxRedirects; redirect++) {\n    const response = yield* client.execute(\n      HttpClientRequest.setHeaders(HttpClientRequest.get(url.toString()), headers)\n    ).pipe(\n      Effect.mapError((cause) => refusal(cause) ?? error(\"request_failed\", `Web fetch request failed: ${url}`))\n    )\n    const location = header(response.headers, \"location\")\n    if (response.status >= 300 && response.status < 400 && location !== undefined) {\n      const next = parseHttpUrl(location, url)\n      if (next === undefined) {\n        return yield* Effect.fail(\n          error(\"invalid_input\", \"Redirect target must use http or https without user information\", location)\n        )\n      }\n      if (next.origin !== url.origin) {\n        headers = Object.fromEntries(\n          Object.entries(headers).filter(([key]) =>\n            key.toLowerCase() !== \"authorization\" && key.toLowerCase() !== \"cookie\"\n          )\n        )\n      }\n      url = next\n      continue\n    }\n    const contentType = header(response.headers, \"content-type\") ?? \"\"\n    const normalizedContentType = contentType.toLowerCase()\n    if (\n      !normalizedContentType.startsWith(\"text/\")\n      && !normalizedContentType.includes(\"json\")\n      && !normalizedContentType.includes(\"xml\")\n    ) {\n      return yield* Effect.fail(\n        error(\"unsupported_content_type\", `Unsupported content type: ${contentType || \"unknown\"}`)\n      )\n    }\n    const length = Number(header(response.headers, \"content-length\"))\n    if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {\n      return yield* Effect.fail(error(\"response_too_large\", \"Response exceeds the 5 MiB limit\"))\n    }\n    const body = yield* readBounded(response.stream, url.toString()).pipe(\n      Effect.mapError((cause) =>\n        cause instanceof StdError.StdError\n          ? cause\n          : error(\"request_failed\", \"Web fetch response could not be read\")\n      )\n    )\n    const raw = new TextDecoder().decode(body)\n    const format = input.format ?? \"markdown\"\n    const { text: content, ...disclosure } = capOutput(\n      format === \"html\" || !normalizedContentType.includes(\"html\")\n        ? raw\n        : format === \"text\"\n        ? toText(raw)\n        : toMarkdown(raw)\n    )\n    return { url: url.toString(), status: response.status, contentType, content, ...disclosure }\n  }\n  return yield* Effect.fail(error(\"request_failed\", \"Web fetch exceeded the redirect limit\"))\n}, (effect, input) =>\n  // Keep the shared deadline outside the redirect loop and error mapping.\n  withDeadline(effect, input.url, input.timeout, (seconds) =>\n    error(\"timeout\", `Web fetch timed out after ${seconds} seconds`)))\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/WebSearch.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The `websearch` flow and the provider seam it runs through.
+ *
+ * The flow is provider-neutral: it hands the query to the bound
+ * {@link WebSearch} service and returns normalized results. A host binds a
+ * provider such as `ExaWebSearch.layer`; {@link layerNoop} fails every search
+ * with `provider_unavailable`.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, Layer, Schema } from "effect";
+import * as StdError from "./StdError.ts";
+/**
+ * The registry name of the `websearch` flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "websearch";
+/**
+ * The one-line description the model sees for the `websearch` flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "Search the web through a configured provider and return normalized results.";
+/**
+ * What the `websearch` flow accepts.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly query: Schema.NonEmptyString;
+    readonly numResults: Schema.optional<Schema.Int>;
+    readonly freshness: Schema.optional<Schema.Literals<readonly ["day", "week", "month", "year"]>>;
+}>;
+/**
+ * Decoded input accepted by the `websearch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * One search hit, normalized across providers.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Result: Schema.Struct<{
+    readonly title: Schema.String;
+    readonly url: Schema.String;
+    readonly snippet: Schema.String;
+    readonly publishedAt: Schema.optional<Schema.String>;
+}>;
+/**
+ * What the `websearch` flow returns.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly results: Schema.$Array<Schema.Struct<{
+        readonly title: Schema.String;
+        readonly url: Schema.String;
+        readonly snippet: Schema.String;
+        readonly publishedAt: Schema.optional<Schema.String>;
+    }>>;
+}>;
+/**
+ * Decoded output returned by the `websearch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * The declared effect envelope of the `websearch` flow, before any input is known.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows {@link effects} to what this particular input actually touches.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * The authority the `websearch` flow requires.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * The `websearch` flow declaration: schemas, capabilities, and effects, with the
+ * implementation attached separately.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "websearch";
+    readonly description: "Search the web through a configured provider and return normalized results.";
+    readonly input: Schema.Struct<{
+        readonly query: Schema.NonEmptyString;
+        readonly numResults: Schema.optional<Schema.Int>;
+        readonly freshness: Schema.optional<Schema.Literals<readonly ["day", "week", "month", "year"]>>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly results: Schema.$Array<Schema.Struct<{
+            readonly title: Schema.String;
+            readonly url: Schema.String;
+            readonly snippet: Schema.String;
+            readonly publishedAt: Schema.optional<Schema.String>;
+        }>>;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * The provider seam a web search is served through.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export interface WebSearch {
+    readonly search: (input: typeof Input.Type) => Effect.Effect<typeof Output.Type, StdError.StdError>;
+}
+/**
+ * The {@link WebSearch} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export declare const WebSearch: Context.Service<WebSearch, WebSearch>;
+/**
+ * Builds a {@link WebSearch} from an implementation of its one method.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (service: WebSearch) => WebSearch;
+/**
+ * A {@link WebSearch} that fails every search with `provider_unavailable`,
+ * for an environment with no provider configured.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeNoop: () => WebSearch;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerNoop: Layer.Layer<WebSearch>;
+/**
+ * Runs the `websearch` flow: searches the web through the configured provider.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly query: string;
+    readonly numResults?: number | undefined;
+    readonly freshness?: "day" | "week" | "month" | "year" | undefined;
+}) => Effect.Effect<{
+    readonly results: readonly {
+        readonly title: string;
+        readonly url: string;
+        readonly snippet: string;
+        readonly publishedAt?: string | undefined;
+    }[];
+}, StdError.StdError, WebSearch>;
+//# sourceMappingURL=WebSearch.d.ts.map

package/dist/cjs/WebSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearch.d.ts","sourceRoot":"","sources":["../../src/WebSearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEvD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,cAAc,CAAA;AAC/B;;;;;GAKG;AACH,eAAO,MAAM,WAAW,gFAAgF,CAAA;AACxG;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;EAQhB,CAAA;AACF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AACrC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;EAOjB,CAAA;AACF;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;;;EAAmD,CAAA;AACtE;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AACvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAAwE,CAAA;AAC5F;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAChE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAAgC,CAAA;AACzD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;CAAsF,CAAA;AAEvG;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;CACpG;AACD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAA4C,CAAA;AACxG;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,SAAS,KAAG,SAAkC,CAAA;AAC5E;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,QAAO,SAMxB,CAAA;AACJ;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAwC,CAAA;AACrF;;;;;GAKG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;gCAKd,CAAA"}

package/dist/cjs/WebSearch.js

@@ -0,0 +1,86 @@
+"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 name2 in all)
+    __defProp(target, name2, { get: all[name2], 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 WebSearch_exports = {};
+__export(WebSearch_exports, {
+  Input: () => Input,
+  Output: () => Output,
+  Result: () => Result,
+  WebSearch: () => WebSearch,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  layerNoop: () => layerNoop,
+  make: () => make,
+  makeNoop: () => makeNoop,
+  name: () => name,
+  run: () => run
+});
+module.exports = __toCommonJS(WebSearch_exports);
+var import_effect = require("effect");
+var import_Declaration = require("./internal/Declaration.js");
+var StdError = __toESM(require("./StdError.js"), 1);
+const name = "websearch";
+const description = "Search the web through a configured provider and return normalized results.";
+const Input = import_effect.Schema.Struct({
+  query: import_effect.Schema.NonEmptyString.annotate({ description: "Search query" }),
+  numResults: import_effect.Schema.optional(import_effect.Schema.Int.check(import_effect.Schema.isBetween({ minimum: 1, maximum: 20 }))).annotate({
+    description: "Maximum number of results, from 1 through 20; defaults to 8"
+  }),
+  freshness: import_effect.Schema.optional(import_effect.Schema.Literals(["day", "week", "month", "year"])).annotate({
+    description: "Optional age limit for published results"
+  })
+});
+const Result = import_effect.Schema.Struct({
+  title: import_effect.Schema.String.annotate({ description: "Result title" }),
+  url: import_effect.Schema.String.annotate({ description: "Absolute result URL" }),
+  snippet: import_effect.Schema.String.annotate({ description: "Provider-normalized result excerpt" }),
+  publishedAt: import_effect.Schema.optional(import_effect.Schema.String).annotate({
+    description: "Provider publication timestamp when available"
+  })
+});
+const Output = import_effect.Schema.Struct({ results: import_effect.Schema.Array(Result) });
+const effects = (0, import_Declaration.envelope)({ tier: "sealed", mode: "expected", reads: [], writes: [] });
+const effectsFor = (_input) => effects;
+const capabilities = [(0, import_Declaration.capability)("net:post", "*")];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const WebSearch = import_effect.Context.Service("@smthrs/std/WebSearch");
+const make = (service) => WebSearch.of(service);
+const makeNoop = () => make({
+  search: () => import_effect.Effect.fail(
+    new StdError.StdError({ code: "provider_unavailable", message: "No web search provider is configured" })
+  )
+});
+const layerNoop = import_effect.Layer.succeed(WebSearch, makeNoop());
+const run = import_effect.Effect.fn("WebSearch.run")(function* (input) {
+  const provider = yield* WebSearch;
+  return yield* provider.search(input);
+});
+//# sourceMappingURL=WebSearch.js.map

package/dist/cjs/WebSearch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/WebSearch.ts"],
+  "sourcesContent": ["/**\n * The `websearch` flow and the provider seam it runs through.\n *\n * The flow is provider-neutral: it hands the query to the bound\n * {@link WebSearch} service and returns normalized results. A host binds a\n * provider such as `ExaWebSearch.layer`; {@link layerNoop} fails every search\n * with `provider_unavailable`.\n *\n * @since 1.0.0\n */\n\nimport { Context, Effect, Layer, Schema } from \"effect\"\nimport { capability, envelope } from \"./internal/Declaration.ts\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * The registry name of the `websearch` flow.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"websearch\"\n/**\n * The one-line description the model sees for the `websearch` flow.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description = \"Search the web through a configured provider and return normalized results.\"\n/**\n * What the `websearch` flow accepts.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  query: Schema.NonEmptyString.annotate({ description: \"Search query\" }),\n  numResults: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 20 }))).annotate({\n    description: \"Maximum number of results, from 1 through 20; defaults to 8\"\n  }),\n  freshness: Schema.optional(Schema.Literals([\"day\", \"week\", \"month\", \"year\"])).annotate({\n    description: \"Optional age limit for published results\"\n  })\n})\n/**\n * Decoded input accepted by the `websearch` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n/**\n * One search hit, normalized across providers.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Result = Schema.Struct({\n  title: Schema.String.annotate({ description: \"Result title\" }),\n  url: Schema.String.annotate({ description: \"Absolute result URL\" }),\n  snippet: Schema.String.annotate({ description: \"Provider-normalized result excerpt\" }),\n  publishedAt: Schema.optional(Schema.String).annotate({\n    description: \"Provider publication timestamp when available\"\n  })\n})\n/**\n * What the `websearch` flow returns.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({ results: Schema.Array(Result) })\n/**\n * Decoded output returned by the `websearch` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n/**\n * The declared effect envelope of the `websearch` flow, before any input is known.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({ tier: \"sealed\", mode: \"expected\", reads: [], writes: [] })\n/**\n * Narrows {@link effects} to what this particular input actually touches.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (_input: typeof Input.Type) => effects\n/**\n * The authority the `websearch` flow requires.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"net:post\", \"*\")]\n/**\n * The `websearch` flow declaration: schemas, capabilities, and effects, with the\n * implementation attached separately.\n *\n * @category flows\n * @since 1.0.0\n */\nexport const flow = { name, description, input: Input, output: Output, capabilities, effects } as const\n\n/**\n * The provider seam a web search is served through.\n *\n * @category services\n * @since 1.0.0\n */\nexport interface WebSearch {\n  readonly search: (input: typeof Input.Type) => Effect.Effect<typeof Output.Type, StdError.StdError>\n}\n/**\n * The {@link WebSearch} service tag.\n *\n * @category services\n * @since 1.0.0\n */\nexport const WebSearch: Context.Service<WebSearch, WebSearch> = Context.Service(\"@smthrs/std/WebSearch\")\n/**\n * Builds a {@link WebSearch} from an implementation of its one method.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (service: WebSearch): WebSearch => WebSearch.of(service)\n/**\n * A {@link WebSearch} that fails every search with `provider_unavailable`,\n * for an environment with no provider configured.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeNoop = (): WebSearch =>\n  make({\n    search: () =>\n      Effect.fail(\n        new StdError.StdError({ code: \"provider_unavailable\", message: \"No web search provider is configured\" })\n      )\n  })\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerNoop: Layer.Layer<WebSearch> = Layer.succeed(WebSearch, makeNoop())\n/**\n * Runs the `websearch` flow: searches the web through the configured provider.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"WebSearch.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<typeof Output.Type, StdError.StdError, WebSearch> {\n  const provider = yield* WebSearch\n  return yield* provider.search(input)\n})\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,oBAA+C;AAC/C,yBAAqC;AACrC,eAA0B;AAQnB,MAAM,OAAO;AAOb,MAAM,cAAc;AAOpB,MAAM,QAAQ,qBAAO,OAAO;AAAA,EACjC,OAAO,qBAAO,eAAe,SAAS,EAAE,aAAa,eAAe,CAAC;AAAA,EACrE,YAAY,qBAAO,SAAS,qBAAO,IAAI,MAAM,qBAAO,UAAU,EAAE,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS;AAAA,IACpG,aAAa;AAAA,EACf,CAAC;AAAA,EACD,WAAW,qBAAO,SAAS,qBAAO,SAAS,CAAC,OAAO,QAAQ,SAAS,MAAM,CAAC,CAAC,EAAE,SAAS;AAAA,IACrF,aAAa;AAAA,EACf,CAAC;AACH,CAAC;AAcM,MAAM,SAAS,qBAAO,OAAO;AAAA,EAClC,OAAO,qBAAO,OAAO,SAAS,EAAE,aAAa,eAAe,CAAC;AAAA,EAC7D,KAAK,qBAAO,OAAO,SAAS,EAAE,aAAa,sBAAsB,CAAC;AAAA,EAClE,SAAS,qBAAO,OAAO,SAAS,EAAE,aAAa,qCAAqC,CAAC;AAAA,EACrF,aAAa,qBAAO,SAAS,qBAAO,MAAM,EAAE,SAAS;AAAA,IACnD,aAAa;AAAA,EACf,CAAC;AACH,CAAC;AAOM,MAAM,SAAS,qBAAO,OAAO,EAAE,SAAS,qBAAO,MAAM,MAAM,EAAE,CAAC;AAc9D,MAAM,cAAU,6BAAS,EAAE,MAAM,UAAU,MAAM,YAAY,OAAO,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC;AAOpF,MAAM,aAAa,CAAC,WAA8B;AAOlD,MAAM,eAAe,KAAC,+BAAW,YAAY,GAAG,CAAC;AAQjD,MAAM,OAAO,EAAE,MAAM,aAAa,OAAO,OAAO,QAAQ,QAAQ,cAAc,QAAQ;AAiBtF,MAAM,YAAmD,sBAAQ,QAAQ,uBAAuB;AAOhG,MAAM,OAAO,CAAC,YAAkC,UAAU,GAAG,OAAO;AAQpE,MAAM,WAAW,MACtB,KAAK;AAAA,EACH,QAAQ,MACN,qBAAO;AAAA,IACL,IAAI,SAAS,SAAS,EAAE,MAAM,wBAAwB,SAAS,uCAAuC,CAAC;AAAA,EACzG;AACJ,CAAC;AAOI,MAAM,YAAoC,oBAAM,QAAQ,WAAW,SAAS,CAAC;AAO7E,MAAM,MAAM,qBAAO,GAAG,eAAe,EAAE,WAC5C,OACoE;AACpE,QAAM,WAAW,OAAO;AACxB,SAAO,OAAO,SAAS,OAAO,KAAK;AACrC,CAAC;",
+  "names": []
+}

package/dist/cjs/Write.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Write flow declaration and portable handler.
+ *
+ * @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 write flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "write";
+/**
+ * Model-facing description of the write flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "Write UTF-8 text to a path, replacing any existing file; parent directories are created. Prefer edit for targeted changes.";
+/**
+ * Input schema for the write flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly content: Schema.String;
+}>;
+/**
+ * Decoded input accepted by the `write` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output schema for the write flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly bytesWritten: Schema.Number;
+    readonly created: Schema.Boolean;
+}>;
+/**
+ * Decoded output returned by the `write` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static conservative effect envelope for the write flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the write 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 write flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * Declaration-only write flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "write";
+    readonly description: "Write UTF-8 text to a path, replacing any existing file; parent directories are created. Prefer edit for targeted changes.";
+    readonly input: Schema.Struct<{
+        readonly path: Schema.String;
+        readonly content: Schema.String;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly path: Schema.String;
+        readonly bytesWritten: Schema.Number;
+        readonly created: Schema.Boolean;
+    }>;
+    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: "writing";
+        readonly success: "wrote";
+        readonly failure: "failed to write";
+    };
+    readonly subject: "path";
+    readonly result: "write";
+};
+/**
+ * Replaces a file's contents through the permission-aware kernel filesystem.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly path: string;
+    readonly content: string;
+}) => Effect.Effect<{
+    readonly path: string;
+    readonly bytesWritten: number;
+    readonly created: boolean;
+}, StdError.StdError, import("effect/Path").Path | FileSystem.FileSystem>;
+//# sourceMappingURL=Write.d.ts.map

package/dist/cjs/Write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Write.d.ts","sourceRoot":"","sources":["../../src/Write.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAMvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,UAAU,CAAA;AAE3B;;;;;GAKG;AACH,eAAO,MAAM,WAAW,+HACsG,CAAA;AAE9H;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;EAGhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;EAIjB,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;AAKV;;;;;GAKG;AACH,eAAO,MAAM,GAAG;;;;;;;yEAiDd,CAAA"}

package/dist/cjs/Write.js

@@ -0,0 +1,122 @@
+"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 name2 in all)
+    __defProp(target, name2, { get: all[name2], 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 Write_exports = {};
+__export(Write_exports, {
+  Input: () => Input,
+  Output: () => Output,
+  activity: () => activity,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  name: () => name,
+  presentation: () => presentation,
+  run: () => run
+});
+module.exports = __toCommonJS(Write_exports);
+var Path = __toESM(require("@smthrs/kernel/Path"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var FileSystem = __toESM(require("effect/FileSystem"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_Declaration = require("./internal/Declaration.js");
+var Diagnostics = __toESM(require("./internal/Diagnostics.js"), 1);
+var FileMutation = __toESM(require("./internal/FileMutation.js"), 1);
+var FsFailure = __toESM(require("./internal/FsFailure.js"), 1);
+var Preserve = __toESM(require("./internal/Preserve.js"), 1);
+var StdError = __toESM(require("./StdError.js"), 1);
+const name = "write";
+const description = "Write UTF-8 text to a path, replacing any existing file; parent directories are created. Prefer edit for targeted changes.";
+const Input = Schema.Struct({
+  path: Schema.String.annotate({ description: "Path of the file to write" }),
+  content: Schema.String.annotate({ description: "Complete UTF-8 file contents" })
+});
+const Output = Schema.Struct({
+  path: Schema.String.annotate({ description: "Path that was written" }),
+  bytesWritten: Schema.Number.annotate({ description: "Number of UTF-8 bytes written" }),
+  created: Schema.Boolean.annotate({ description: "Whether the file did not previously exist" })
+});
+const effects = (0, import_Declaration.envelope)({ tier: "compensable", mode: "hermetic", reads: ["/**"], writes: ["/**"] });
+const effectsFor = (input) => (0, import_Declaration.envelope)({ tier: "compensable", mode: "hermetic", reads: [input.path], writes: [input.path] });
+const capabilities = [(0, import_Declaration.capability)("fs:read", "/**"), (0, import_Declaration.capability)("fs:write", "/**")];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const activity = "writes";
+const presentation = {
+  verb: { pending: "writing", success: "wrote", failure: "failed to write" },
+  subject: "path",
+  result: "write"
+};
+const writeError = (path, message) => new StdError.StdError({ code: "command_failed", message, path });
+const run = Effect.fn("Write.run")(function* (input) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  yield* FileMutation.validate(fileSystem, [input.path]);
+  if (!FileMutation.isVersioned(fileSystem)) {
+    yield* fileSystem.makeDirectory(path.dirname(input.path), { recursive: true }).pipe(
+      Effect.mapError(
+        FsFailure.denied(
+          input.path,
+          () => writeError(input.path, `Could not create the parent directory of ${input.path}`)
+        )
+      )
+    );
+  }
+  return yield* Effect.scoped(Effect.gen(function* () {
+    const mutation = yield* FileMutation.acquire(fileSystem, [input.path], path);
+    const existed = yield* fileSystem.exists(input.path).pipe(Effect.orElseSucceed(() => false));
+    if (existed) {
+      const info = yield* fileSystem.stat(input.path).pipe(
+        Effect.mapError(
+          FsFailure.denied(input.path, () => writeError(input.path, `Could not inspect ${input.path} before writing`))
+        )
+      );
+      if (info.type === "Directory") {
+        return yield* Effect.fail(writeError(input.path, `Cannot write a file over directory ${input.path}`));
+      }
+    }
+    yield* mutation.commit(
+      [{
+        path: input.path,
+        content: new TextEncoder().encode(input.content)
+      }],
+      Preserve.writeFileString(fileSystem, input.path, input.content).pipe(
+        Effect.mapError(
+          (error) => error.reason.method === "chmod" ? writeError(input.path, `Could not preserve the mode of ${input.path} before replacement by chmod`) : FsFailure.denied(input.path, () => writeError(input.path, `Could not write ${input.path}`))(error)
+        )
+      )
+    );
+    yield* Diagnostics.sync(path.resolve(input.path), input.content);
+    return {
+      path: input.path,
+      bytesWritten: new TextEncoder().encode(input.content).byteLength,
+      created: !existed
+    };
+  }));
+});
+//# sourceMappingURL=Write.js.map

package/dist/cjs/Write.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Write.ts"],
+  "sourcesContent": ["/**\n * Write flow declaration and portable handler.\n *\n * @since 1.0.0\n */\n\nimport * as Path from \"@smthrs/kernel/Path\"\nimport * as Effect from \"effect/Effect\"\nimport * as FileSystem from \"effect/FileSystem\"\nimport * as Schema from \"effect/Schema\"\nimport { capability, envelope } from \"./internal/Declaration.ts\"\nimport * as Diagnostics from \"./internal/Diagnostics.ts\"\nimport * as FileMutation from \"./internal/FileMutation.ts\"\nimport * as FsFailure from \"./internal/FsFailure.ts\"\nimport * as Preserve from \"./internal/Preserve.ts\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * Registry name for the write flow.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"write\"\n\n/**\n * Model-facing description of the write flow.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description =\n  \"Write UTF-8 text to a path, replacing any existing file; parent directories are created. Prefer edit for targeted changes.\"\n\n/**\n * Input schema for the write flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  path: Schema.String.annotate({ description: \"Path of the file to write\" }),\n  content: Schema.String.annotate({ description: \"Complete UTF-8 file contents\" })\n})\n\n/**\n * Decoded input accepted by the `write` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * Output schema for the write flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  path: Schema.String.annotate({ description: \"Path that was written\" }),\n  bytesWritten: Schema.Number.annotate({ description: \"Number of UTF-8 bytes written\" }),\n  created: Schema.Boolean.annotate({ description: \"Whether the file did not previously exist\" })\n})\n\n/**\n * Decoded output returned by the `write` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n\n/**\n * Static conservative effect envelope for the write flow.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({ tier: \"compensable\", mode: \"hermetic\", reads: [\"/**\"], writes: [\"/**\"] })\n\n/**\n * Narrows the write effect envelope to one input path.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (input: typeof Input.Type) =>\n  envelope({ tier: \"compensable\", mode: \"hermetic\", reads: [input.path], writes: [input.path] })\n\n/**\n * Capabilities required by the write flow.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"fs:read\", \"/**\"), capability(\"fs:write\", \"/**\")]\n\n/**\n * Declaration-only write flow.\n *\n * @category flows\n * @since 1.0.0\n */\nexport const flow = { name, description, input: Input, output: Output, capabilities, effects } as const\n\n/**\n * What a call to this flow does, for a reader of a run.\n *\n * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the\n * governing vocabulary and `StandardFlows` binds this value onto the flow's\n * descriptor, where the binding site checks it. `declarationDigest` excludes\n * it, so declaring it cannot invalidate a call identity or a cached prompt.\n *\n * @category presentation\n * @since 1.0.0-rc.0\n */\nexport const activity = \"writes\" as const\n\n/**\n * How one recorded call to this flow reads: the verb for each settlement, the\n * input field that is its subject, and the measured output fields a one-line\n * summary may count.\n *\n * Display metadata only, governed by `@smthrs/registry`\n * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.\n *\n * @category presentation\n * @since 1.0.0-rc.0\n */\nexport const presentation = {\n  verb: { pending: \"writing\", success: \"wrote\", failure: \"failed to write\" },\n  subject: \"path\",\n  result: \"write\"\n} as const\n\nconst writeError = (path: string, message: string): StdError.StdError =>\n  new StdError.StdError({ code: \"command_failed\", message, path })\n\n/**\n * Replaces a file's contents through the permission-aware kernel filesystem.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"Write.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<typeof Output.Type, StdError.StdError, FileSystem.FileSystem | Path.Path> {\n  const fileSystem = yield* FileSystem.FileSystem\n  const path = yield* Path.Path\n  yield* FileMutation.validate(fileSystem, [input.path])\n  if (!FileMutation.isVersioned(fileSystem)) {\n    yield* fileSystem.makeDirectory(path.dirname(input.path), { recursive: true }).pipe(\n      Effect.mapError(\n        FsFailure.denied(\n          input.path,\n          () => writeError(input.path, `Could not create the parent directory of ${input.path}`)\n        )\n      )\n    )\n  }\n  return yield* Effect.scoped(Effect.gen(function*() {\n    const mutation = yield* FileMutation.acquire(fileSystem, [input.path], path)\n    const existed = yield* fileSystem.exists(input.path).pipe(Effect.orElseSucceed(() => false))\n    if (existed) {\n      const info = yield* fileSystem.stat(input.path).pipe(\n        Effect.mapError(\n          FsFailure.denied(input.path, () => writeError(input.path, `Could not inspect ${input.path} before writing`))\n        )\n      )\n      if (info.type === \"Directory\") {\n        return yield* Effect.fail(writeError(input.path, `Cannot write a file over directory ${input.path}`))\n      }\n    }\n    yield* mutation.commit(\n      [{\n        path: input.path,\n        content: new TextEncoder().encode(input.content)\n      }],\n      Preserve.writeFileString(fileSystem, input.path, input.content).pipe(\n        Effect.mapError((error) =>\n          error.reason.method === \"chmod\"\n            ? writeError(input.path, `Could not preserve the mode of ${input.path} before replacement by chmod`)\n            : FsFailure.denied(input.path, () => writeError(input.path, `Could not write ${input.path}`))(error)\n        )\n      )\n    )\n    yield* Diagnostics.sync(path.resolve(input.path), input.content)\n    return {\n      path: input.path,\n      bytesWritten: new TextEncoder().encode(input.content).byteLength,\n      created: !existed\n    }\n  }))\n})\n"],
+  "mappings": "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",
+  "names": []
+}