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

package/dist/esm/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/esm/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/esm/WebSearch.js

@@ -0,0 +1,134 @@
+/**
+ * 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 { capability, envelope } from "./internal/Declaration.js";
+import * as StdError from "./StdError.js";
+/**
+ * The registry name of the `websearch` flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "websearch";
+/**
+ * The one-line description the model sees for the `websearch` flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export 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 const Input = Schema.Struct({
+    query: Schema.NonEmptyString.annotate({ description: "Search query" }),
+    numResults: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 20 }))).annotate({
+        description: "Maximum number of results, from 1 through 20; defaults to 8"
+    }),
+    freshness: Schema.optional(Schema.Literals(["day", "week", "month", "year"])).annotate({
+        description: "Optional age limit for published results"
+    })
+});
+/**
+ * One search hit, normalized across providers.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Result = Schema.Struct({
+    title: Schema.String.annotate({ description: "Result title" }),
+    url: Schema.String.annotate({ description: "Absolute result URL" }),
+    snippet: Schema.String.annotate({ description: "Provider-normalized result excerpt" }),
+    publishedAt: Schema.optional(Schema.String).annotate({
+        description: "Provider publication timestamp when available"
+    })
+});
+/**
+ * What the `websearch` flow returns.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Schema.Struct({ results: Schema.Array(Result) });
+/**
+ * The declared effect envelope of the `websearch` flow, before any input is known.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "expected", reads: [], writes: [] });
+/**
+ * Narrows {@link effects} to what this particular input actually touches.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input) => effects;
+/**
+ * The authority the `websearch` flow requires.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("net:post", "*")];
+/**
+ * The `websearch` flow declaration: schemas, capabilities, and effects, with the
+ * implementation attached separately.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects };
+/**
+ * The {@link WebSearch} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export const WebSearch = Context.Service("@smthrs/std/WebSearch");
+/**
+ * Builds a {@link WebSearch} from an implementation of its one method.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (service) => WebSearch.of(service);
+/**
+ * A {@link WebSearch} that fails every search with `provider_unavailable`,
+ * for an environment with no provider configured.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeNoop = () => make({
+    search: () => Effect.fail(new StdError.StdError({ code: "provider_unavailable", message: "No web search provider is configured" }))
+});
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerNoop = Layer.succeed(WebSearch, makeNoop());
+/**
+ * Runs the `websearch` flow: searches the web through the configured provider.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("WebSearch.run")(function* (input) {
+    const provider = yield* WebSearch;
+    return yield* provider.search(input);
+});
+//# sourceMappingURL=WebSearch.js.map

package/dist/esm/WebSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearch.js","sourceRoot":"","sources":["../../src/WebSearch.ts"],"names":[],"mappings":"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","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"]}

package/dist/esm/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/esm/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/esm/Write.js

@@ -0,0 +1,144 @@
+/**
+ * Write flow declaration and portable handler.
+ *
+ * @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 { 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 write flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "write";
+/**
+ * Model-facing description of the write flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export 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 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" })
+});
+/**
+ * Output schema for the write flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export 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" })
+});
+/**
+ * Static conservative effect envelope for the write flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "compensable", mode: "hermetic", reads: ["/**"], writes: ["/**"] });
+/**
+ * Narrows the write effect envelope to one input path.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (input) => envelope({ tier: "compensable", mode: "hermetic", reads: [input.path], writes: [input.path] });
+/**
+ * Capabilities required by the write flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**"), capability("fs:write", "/**")];
+/**
+ * Declaration-only write 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: "writing", success: "wrote", failure: "failed to write" },
+    subject: "path",
+    result: "write"
+};
+const writeError = (path, message) => new StdError.StdError({ code: "command_failed", message, path });
+/**
+ * Replaces a file's contents through the permission-aware kernel filesystem.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export 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/esm/Write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Write.js","sourceRoot":"","sources":["../../src/Write.ts"],"names":[],"mappings":"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","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"]}