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

package/dist/cjs/Ls.js

@@ -0,0 +1,136 @@
+"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 Ls_exports = {};
+__export(Ls_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(Ls_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 FsFailure = __toESM(require("./internal/FsFailure.js"), 1);
+var import_Text = require("./internal/Text.js");
+var StdError = __toESM(require("./StdError.js"), 1);
+const name = "ls";
+const description = "List a directory with directories first, trailing /, and locale-independent UTF-16 code-unit ordering; use 1-based offset and limit to page large listings.";
+const Input = Schema.Struct({
+  path: Schema.String.annotate({ description: "Directory path to list" }),
+  offset: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "1-based entry offset"
+  }),
+  limit: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "Maximum entries to return"
+  })
+});
+const Output = Schema.Struct({
+  entries: Schema.Array(Schema.Struct({
+    name: Schema.String.annotate({ description: "Entry name; directories end in /" }),
+    kind: Schema.Literals(["file", "directory"]).annotate({ description: "Entry kind" })
+  })),
+  total: Schema.Number.annotate({ description: "Total entries before paging" }),
+  truncated: Schema.Boolean.annotate({ description: "Whether more entries remain" }),
+  notice: Schema.optional(Schema.String.annotate({ description: "Truncation disclosure" }))
+});
+const effects = (0, import_Declaration.envelope)({ tier: "sealed", mode: "hermetic", reads: ["/**"], writes: [] });
+const effectsFor = (input) => (0, import_Declaration.envelope)({ tier: "sealed", mode: "hermetic", reads: [input.path], writes: [] });
+const capabilities = [(0, import_Declaration.capability)("fs:read", "/**")];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const activity = "reads";
+const presentation = {
+  verb: { pending: "listing", success: "listed", failure: "failed to list" },
+  subject: "path",
+  result: "entries"
+};
+const byText = (left, right) => left < right ? -1 : Number(left > right);
+const run = Effect.fn("Ls.run")(function* (input) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const info = yield* fileSystem.stat(input.path).pipe(
+    Effect.mapError(FsFailure.reading(input.path, `Directory not found: ${input.path}`))
+  );
+  if (info.type !== "Directory") {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "not_a_directory",
+        message: `Cannot list a file: ${input.path}`,
+        path: input.path
+      })
+    );
+  }
+  const names = yield* fileSystem.readDirectory(input.path).pipe(
+    Effect.mapError(FsFailure.reading(input.path, `Directory not found: ${input.path}`))
+  );
+  const sortedNames = [...names].sort(byText);
+  const offset = input.offset ?? 1;
+  if (offset > Math.max(sortedNames.length, 1)) {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "offset_out_of_range",
+        message: `Entry offset ${offset} is outside ${input.path}, which has ${sortedNames.length} entries`,
+        path: input.path
+      })
+    );
+  }
+  const limit = Math.min(input.limit ?? import_Text.DEFAULT_READ_LIMIT, import_Text.MAX_ENTRIES);
+  const described = yield* Effect.forEach(
+    sortedNames,
+    (entry) => fileSystem.stat(path.join(input.path, entry)).pipe(
+      Effect.map((entryInfo) => ({
+        name: entryInfo.type === "Directory" ? `${entry}/` : entry,
+        kind: entryInfo.type === "Directory" ? "directory" : "file"
+      })),
+      Effect.catch(() => Effect.succeed({ name: entry, kind: "file" }))
+    ),
+    { concurrency: 16 }
+  );
+  const ordered = [...described].sort(
+    (left, right) => left.kind === right.kind ? byText(left.name, right.name) : left.kind === "directory" ? -1 : 1
+  );
+  const selected = ordered.slice(offset - 1, offset - 1 + limit);
+  const truncated = offset - 1 + selected.length < ordered.length;
+  return {
+    entries: selected,
+    total: ordered.length,
+    truncated,
+    ...truncated ? { notice: (0, import_Text.notice)("entries", selected.length, ordered.length) } : {}
+  };
+});
+//# sourceMappingURL=Ls.js.map

package/dist/cjs/Ls.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Ls.ts"],
+  "sourcesContent": ["/**\n * Directory listing 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 FsFailure from \"./internal/FsFailure.ts\"\nimport { DEFAULT_READ_LIMIT, MAX_ENTRIES, notice } from \"./internal/Text.ts\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * The registry name of the `ls` flow.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"ls\"\n\n/**\n * The one-line description the model sees for the `ls` flow.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description =\n  \"List a directory with directories first, trailing /, and locale-independent UTF-16 code-unit ordering; use 1-based offset and limit to page large listings.\"\n\n/**\n * What the `ls` flow accepts.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  path: Schema.String.annotate({ description: \"Directory path to list\" }),\n  offset: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({\n    description: \"1-based entry offset\"\n  }),\n  limit: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({\n    description: \"Maximum entries to return\"\n  })\n})\n\n/**\n * Decoded input accepted by the `ls` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * What the `ls` flow returns.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  entries: Schema.Array(Schema.Struct({\n    name: Schema.String.annotate({ description: \"Entry name; directories end in /\" }),\n    kind: Schema.Literals([\"file\", \"directory\"]).annotate({ description: \"Entry kind\" })\n  })),\n  total: Schema.Number.annotate({ description: \"Total entries before paging\" }),\n  truncated: Schema.Boolean.annotate({ description: \"Whether more entries remain\" }),\n  notice: Schema.optional(Schema.String.annotate({ description: \"Truncation disclosure\" }))\n})\n\n/**\n * Decoded output returned by the `ls` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n\n/**\n * The declared effect envelope of the `ls` flow, before any input is known.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({ tier: \"sealed\", mode: \"hermetic\", reads: [\"/**\"], writes: [] })\n\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) =>\n  envelope({ tier: \"sealed\", mode: \"hermetic\", reads: [input.path], writes: [] })\n\n/**\n * The authority the `ls` flow requires.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"fs:read\", \"/**\")]\n\n/**\n * The `ls` 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 * 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 = \"reads\" 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: \"listing\", success: \"listed\", failure: \"failed to list\" },\n  subject: \"path\",\n  result: \"entries\"\n} as const\n\n// localeCompare changes with host locale and ICU data. Code-unit comparisons\n// keep journalled directory listings identical on every host.\nconst byText = (left: string, right: string): number => (left < right ? -1 : Number(left > right))\n\n/**\n * Lists a directory deterministically. A file supplied as `path` is reported\n * as `not_a_directory`.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"Ls.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  const info = yield* fileSystem.stat(input.path).pipe(\n    Effect.mapError(FsFailure.reading(input.path, `Directory not found: ${input.path}`))\n  )\n  if (info.type !== \"Directory\") {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"not_a_directory\",\n        message: `Cannot list a file: ${input.path}`,\n        path: input.path\n      })\n    )\n  }\n  const names = yield* fileSystem.readDirectory(input.path).pipe(\n    Effect.mapError(FsFailure.reading(input.path, `Directory not found: ${input.path}`))\n  )\n  const sortedNames = [...names].sort(byText)\n  const offset = input.offset ?? 1\n  // An empty directory is not an out-of-range listing: the caller asked for\n  // the first page and there is nothing on it. This matches `read`, which\n  // answers an empty page for an empty file and refuses only a real overshoot.\n  if (offset > Math.max(sortedNames.length, 1)) {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"offset_out_of_range\",\n        message: `Entry offset ${offset} is outside ${input.path}, which has ${sortedNames.length} entries`,\n        path: input.path\n      })\n    )\n  }\n  const limit = Math.min(input.limit ?? DEFAULT_READ_LIMIT, MAX_ENTRIES)\n  // Every entry is described before the page is cut, because the order the\n  // description promises is directories first and a kind is a stat away.\n  // Statting only the page and ordering inside it made the order local to the\n  // page: a directory `zdir/` beside a file `a.txt` came back as\n  // `[zdir/, a.txt]` unpaged and as `[a.txt]` then `[zdir/]` at `limit: 1`, so\n  // `offset` addressed a different listing at every page size and an agent\n  // paging a large directory could see one entry twice and another never.\n  //\n  // A per-entry stat can fail on a name the directory legitimately\n  // contains \u2014 a dangling symlink, or a file the guarded filesystem refuses\n  // to describe. The name is still real (readDirectory returned it), so the\n  // listing reports it as a plain entry instead of dying: one broken link in\n  // a repository root used to fail the whole `ls` and cost the agent a frame\n  // per attempt.\n  const described = yield* Effect.forEach(\n    sortedNames,\n    (entry) =>\n      fileSystem.stat(path.join(input.path, entry)).pipe(\n        Effect.map((entryInfo) => ({\n          name: entryInfo.type === \"Directory\" ? `${entry}/` : entry,\n          kind: entryInfo.type === \"Directory\" ? \"directory\" as const : \"file\" as const\n        })),\n        Effect.catch(() => Effect.succeed({ name: entry, kind: \"file\" as const }))\n      ),\n    { concurrency: 16 }\n  )\n  const ordered = [...described].sort((left, right) =>\n    left.kind === right.kind ? byText(left.name, right.name) : left.kind === \"directory\" ? -1 : 1\n  )\n  const selected = ordered.slice(offset - 1, offset - 1 + limit)\n  const truncated = offset - 1 + selected.length < ordered.length\n  return {\n    entries: selected,\n    total: ordered.length,\n    truncated,\n    ...(truncated ? { notice: notice(\"entries\", selected.length, ordered.length) } : {})\n  }\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Lsp.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The `lsp` flow: one code-intelligence query per call.
+ *
+ * The handler checks the path and 1-based position each operation needs,
+ * authorizes the path as a read through the guarded `FileSystem` (the server
+ * process reads the file on its own), forwards the query to the bound
+ * `LanguageServer`, and returns the server's answer unchanged in `result`.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import * as LanguageServer from "./LanguageServer.ts";
+import * as StdError from "./StdError.ts";
+/**
+ * The registry name of the `lsp` flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "lsp";
+/**
+ * The one-line description the model sees for the `lsp` flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "Inspect code intelligence through the configured language server.";
+/**
+ * What the `lsp` flow accepts.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly operation: Schema.Literals<readonly ["hover", "definition", "references", "implementation", "documentSymbols", "workspaceSymbols", "prepareCallHierarchy", "callHierarchyIncoming", "callHierarchyOutgoing", "diagnostics"]>;
+    readonly path: Schema.optional<Schema.String>;
+    readonly line: Schema.optional<Schema.Int>;
+    readonly character: Schema.optional<Schema.Int>;
+    readonly query: Schema.optional<Schema.String>;
+}>;
+/**
+ * Decoded input accepted by the `lsp` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * What the `lsp` flow returns.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly result: Schema.Unknown;
+}>;
+/**
+ * Decoded output returned by the `lsp` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * The declared effect envelope of the `lsp` flow, before any input is known.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Returns the workspace-wide envelope every language-server query needs.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * The authority the `lsp` flow requires.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * The `lsp` flow declaration: schemas, capabilities, and effects, with the
+ * implementation attached separately.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "lsp";
+    readonly description: "Inspect code intelligence through the configured language server.";
+    readonly input: Schema.Struct<{
+        readonly operation: Schema.Literals<readonly ["hover", "definition", "references", "implementation", "documentSymbols", "workspaceSymbols", "prepareCallHierarchy", "callHierarchyIncoming", "callHierarchyOutgoing", "diagnostics"]>;
+        readonly path: Schema.optional<Schema.String>;
+        readonly line: Schema.optional<Schema.Int>;
+        readonly character: Schema.optional<Schema.Int>;
+        readonly query: Schema.optional<Schema.String>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly result: Schema.Unknown;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * Runs the `lsp` flow: queries the configured language server.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly operation: "hover" | "definition" | "references" | "implementation" | "documentSymbols" | "workspaceSymbols" | "prepareCallHierarchy" | "callHierarchyIncoming" | "callHierarchyOutgoing" | "diagnostics";
+    readonly path?: string | undefined;
+    readonly line?: number | undefined;
+    readonly character?: number | undefined;
+    readonly query?: string | undefined;
+}) => Effect.Effect<{
+    readonly result: unknown;
+}, StdError.StdError, FileSystem.FileSystem | LanguageServer.LanguageServer>;
+//# sourceMappingURL=Lsp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Lsp.d.ts","sourceRoot":"","sources":["../../src/Lsp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,QAAQ,CAAA;AACzB;;;;;GAKG;AACH,eAAO,MAAM,WAAW,sEAAsE,CAAA;AAC9F;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;EA4BhB,CAAA;AACF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AACrC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;EAIjB,CAAA;AACF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AACvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAKlB,CAAA;AACF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAChE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAAiC,CAAA;AAC1D;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;CAOP,CAAA;AAEV;;;;;GAKG;AACH,eAAO,MAAM,GAAG;;;;;;;;4EA0Cd,CAAA"}

package/dist/cjs/Lsp.js

@@ -0,0 +1,137 @@
+"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 Lsp_exports = {};
+__export(Lsp_exports, {
+  Input: () => Input,
+  Output: () => Output,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  name: () => name,
+  run: () => run
+});
+module.exports = __toCommonJS(Lsp_exports);
+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 FsFailure = __toESM(require("./internal/FsFailure.js"), 1);
+var LanguageServer = __toESM(require("./LanguageServer.js"), 1);
+var StdError = __toESM(require("./StdError.js"), 1);
+const name = "lsp";
+const description = "Inspect code intelligence through the configured language server.";
+const Input = Schema.Struct({
+  operation: Schema.Literals([
+    "hover",
+    "definition",
+    "references",
+    "implementation",
+    "documentSymbols",
+    "workspaceSymbols",
+    "prepareCallHierarchy",
+    "callHierarchyIncoming",
+    "callHierarchyOutgoing",
+    "diagnostics"
+  ]).annotate({
+    description: "The query to run; workspaceSymbols takes query, documentSymbols and diagnostics take path, the rest take path with line and character"
+  }),
+  path: Schema.optional(Schema.String).annotate({
+    description: "Absolute path of the file to query; required by every operation except workspaceSymbols"
+  }),
+  line: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "1-based line of the position to query, as read and grep report it"
+  }),
+  character: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "1-based character offset within the line"
+  }),
+  query: Schema.optional(Schema.String).annotate({
+    description: "Symbol text to search the workspace for; workspaceSymbols only"
+  })
+});
+const Output = Schema.Struct({
+  result: Schema.Unknown.annotate({
+    description: "The language server's answer for this operation, passed through in the server's own shape"
+  })
+});
+const effects = (0, import_Declaration.envelope)({
+  tier: "sealed",
+  mode: "hermetic",
+  reads: ["/**"],
+  writes: []
+});
+const effectsFor = (_input) => effects;
+const capabilities = [(0, import_Declaration.capability)("fs:read", "/**")];
+const flow = {
+  name,
+  description,
+  input: Input,
+  output: Output,
+  capabilities,
+  effects
+};
+const isAbsolutePath = (path) => path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path);
+const run = Effect.fn("Lsp.run")(function* (input) {
+  const server = yield* LanguageServer.LanguageServer;
+  const path = input.path;
+  const position = path === void 0 || input.line === void 0 || input.character === void 0 ? void 0 : { path, line: input.line - 1, character: input.character - 1 };
+  if (input.operation === "workspaceSymbols") return { result: yield* server.workspaceSymbols(input.query ?? "") };
+  if (path === void 0 || !isAbsolutePath(path)) {
+    return yield* Effect.fail(
+      new StdError.StdError({ code: "invalid_input", message: "A normalized absolute path is required" })
+    );
+  }
+  const fileSystem = yield* FileSystem.FileSystem;
+  yield* fileSystem.stat(path).pipe(Effect.mapError(FsFailure.reading(path, `File not found: ${path}`)));
+  if (input.operation === "documentSymbols") return { result: yield* server.documentSymbols(path) };
+  if (input.operation === "diagnostics") return { result: yield* server.diagnostics(path) };
+  if (position === void 0) {
+    return yield* Effect.fail(
+      new StdError.StdError({ code: "invalid_input", message: "1-based line and character are required" })
+    );
+  }
+  switch (input.operation) {
+    case "hover":
+      return { result: yield* server.hover(position) };
+    case "definition":
+      return { result: yield* server.definition(position) };
+    case "references":
+      return { result: yield* server.references(position) };
+    case "implementation":
+      return { result: yield* server.implementation(position) };
+    case "prepareCallHierarchy":
+      return { result: yield* server.prepareCallHierarchy(position) };
+    case "callHierarchyIncoming":
+      return { result: yield* server.callHierarchyIncoming(position) };
+    case "callHierarchyOutgoing":
+      return { result: yield* server.callHierarchyOutgoing(position) };
+  }
+});
+//# sourceMappingURL=Lsp.js.map

package/dist/cjs/Lsp.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Lsp.ts"],
+  "sourcesContent": ["/**\n * The `lsp` flow: one code-intelligence query per call.\n *\n * The handler checks the path and 1-based position each operation needs,\n * authorizes the path as a read through the guarded `FileSystem` (the server\n * process reads the file on its own), forwards the query to the bound\n * `LanguageServer`, and returns the server's answer unchanged in `result`.\n *\n * @since 1.0.0\n */\n\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 FsFailure from \"./internal/FsFailure.ts\"\nimport * as LanguageServer from \"./LanguageServer.ts\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * The registry name of the `lsp` flow.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"lsp\"\n/**\n * The one-line description the model sees for the `lsp` flow.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description = \"Inspect code intelligence through the configured language server.\"\n/**\n * What the `lsp` flow accepts.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  operation: Schema.Literals([\n    \"hover\",\n    \"definition\",\n    \"references\",\n    \"implementation\",\n    \"documentSymbols\",\n    \"workspaceSymbols\",\n    \"prepareCallHierarchy\",\n    \"callHierarchyIncoming\",\n    \"callHierarchyOutgoing\",\n    \"diagnostics\"\n  ]).annotate({\n    description:\n      \"The query to run; workspaceSymbols takes query, documentSymbols and diagnostics take path, the rest take path with line and character\"\n  }),\n  path: Schema.optional(Schema.String).annotate({\n    description: \"Absolute path of the file to query; required by every operation except workspaceSymbols\"\n  }),\n  line: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({\n    description: \"1-based line of the position to query, as read and grep report it\"\n  }),\n  character: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({\n    description: \"1-based character offset within the line\"\n  }),\n  query: Schema.optional(Schema.String).annotate({\n    description: \"Symbol text to search the workspace for; workspaceSymbols only\"\n  })\n})\n/**\n * Decoded input accepted by the `lsp` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n/**\n * What the `lsp` flow returns.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  result: Schema.Unknown.annotate({\n    description: \"The language server's answer for this operation, passed through in the server's own shape\"\n  })\n})\n/**\n * Decoded output returned by the `lsp` 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 `lsp` flow, before any input is known.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({\n  tier: \"sealed\",\n  mode: \"hermetic\",\n  reads: [\"/**\"],\n  writes: []\n})\n/**\n * Returns the workspace-wide envelope every language-server query needs.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (_input: typeof Input.Type) => effects\n/**\n * The authority the `lsp` flow requires.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"fs:read\", \"/**\")]\n/**\n * The `lsp` 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 = {\n  name,\n  description,\n  input: Input,\n  output: Output,\n  capabilities,\n  effects\n} as const\nconst isAbsolutePath = (path: string): boolean => path.startsWith(\"/\") || /^[A-Za-z]:[\\\\/]/.test(path)\n/**\n * Runs the `lsp` flow: queries the configured language server.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"Lsp.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<typeof Output.Type, StdError.StdError, LanguageServer.LanguageServer | FileSystem.FileSystem> {\n  const server = yield* LanguageServer.LanguageServer\n  const path = input.path\n  const position = path === undefined || input.line === undefined || input.character === undefined\n    ? undefined\n    : { path, line: input.line - 1, character: input.character - 1 }\n  if ((input.operation === \"workspaceSymbols\")) return { result: yield* server.workspaceSymbols(input.query ?? \"\") }\n  if (path === undefined || !isAbsolutePath(path)) {\n    return yield* Effect.fail(\n      new StdError.StdError({ code: \"invalid_input\", message: \"A normalized absolute path is required\" })\n    )\n  }\n  // The server reads the file itself, outside the guarded filesystem, so the\n  // path is authorized here: a read the caller could not make through `read`\n  // is not made through the language server either.\n  const fileSystem = yield* FileSystem.FileSystem\n  yield* fileSystem.stat(path).pipe(Effect.mapError(FsFailure.reading(path, `File not found: ${path}`)))\n  if (input.operation === \"documentSymbols\") return { result: yield* server.documentSymbols(path) }\n  if (input.operation === \"diagnostics\") return { result: yield* server.diagnostics(path) }\n  if (position === undefined) {\n    return yield* Effect.fail(\n      new StdError.StdError({ code: \"invalid_input\", message: \"1-based line and character are required\" })\n    )\n  }\n  switch (input.operation) {\n    case \"hover\":\n      return { result: yield* server.hover(position) }\n    case \"definition\":\n      return { result: yield* server.definition(position) }\n    case \"references\":\n      return { result: yield* server.references(position) }\n    case \"implementation\":\n      return { result: yield* server.implementation(position) }\n    case \"prepareCallHierarchy\":\n      return { result: yield* server.prepareCallHierarchy(position) }\n    case \"callHierarchyIncoming\":\n      return { result: yield* server.callHierarchyIncoming(position) }\n    case \"callHierarchyOutgoing\":\n      return { result: yield* server.callHierarchyOutgoing(position) }\n  }\n})\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,aAAwB;AACxB,iBAA4B;AAC5B,aAAwB;AACxB,yBAAqC;AACrC,gBAA2B;AAC3B,qBAAgC;AAChC,eAA0B;AAQnB,MAAM,OAAO;AAOb,MAAM,cAAc;AAOpB,MAAM,QAAQ,OAAO,OAAO;AAAA,EACjC,WAAW,OAAO,SAAS;AAAA,IACzB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC,EAAE,SAAS;AAAA,IACV,aACE;AAAA,EACJ,CAAC;AAAA,EACD,MAAM,OAAO,SAAS,OAAO,MAAM,EAAE,SAAS;AAAA,IAC5C,aAAa;AAAA,EACf,CAAC;AAAA,EACD,MAAM,OAAO,SAAS,OAAO,IAAI,MAAM,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,SAAS;AAAA,IACjF,aAAa;AAAA,EACf,CAAC;AAAA,EACD,WAAW,OAAO,SAAS,OAAO,IAAI,MAAM,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,SAAS;AAAA,IACtF,aAAa;AAAA,EACf,CAAC;AAAA,EACD,OAAO,OAAO,SAAS,OAAO,MAAM,EAAE,SAAS;AAAA,IAC7C,aAAa;AAAA,EACf,CAAC;AACH,CAAC;AAcM,MAAM,SAAS,OAAO,OAAO;AAAA,EAClC,QAAQ,OAAO,QAAQ,SAAS;AAAA,IAC9B,aAAa;AAAA,EACf,CAAC;AACH,CAAC;AAcM,MAAM,cAAU,6BAAS;AAAA,EAC9B,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO,CAAC,KAAK;AAAA,EACb,QAAQ,CAAC;AACX,CAAC;AAOM,MAAM,aAAa,CAAC,WAA8B;AAOlD,MAAM,eAAe,KAAC,+BAAW,WAAW,KAAK,CAAC;AAQlD,MAAM,OAAO;AAAA,EAClB;AAAA,EACA;AAAA,EACA,OAAO;AAAA,EACP,QAAQ;AAAA,EACR;AAAA,EACA;AACF;AACA,MAAM,iBAAiB,CAAC,SAA0B,KAAK,WAAW,GAAG,KAAK,kBAAkB,KAAK,IAAI;AAO9F,MAAM,MAAM,OAAO,GAAG,SAAS,EAAE,WACtC,OACgH;AAChH,QAAM,SAAS,OAAO,eAAe;AACrC,QAAM,OAAO,MAAM;AACnB,QAAM,WAAW,SAAS,UAAa,MAAM,SAAS,UAAa,MAAM,cAAc,SACnF,SACA,EAAE,MAAM,MAAM,MAAM,OAAO,GAAG,WAAW,MAAM,YAAY,EAAE;AACjE,MAAK,MAAM,cAAc,mBAAqB,QAAO,EAAE,QAAQ,OAAO,OAAO,iBAAiB,MAAM,SAAS,EAAE,EAAE;AACjH,MAAI,SAAS,UAAa,CAAC,eAAe,IAAI,GAAG;AAC/C,WAAO,OAAO,OAAO;AAAA,MACnB,IAAI,SAAS,SAAS,EAAE,MAAM,iBAAiB,SAAS,yCAAyC,CAAC;AAAA,IACpG;AAAA,EACF;AAIA,QAAM,aAAa,OAAO,WAAW;AACrC,SAAO,WAAW,KAAK,IAAI,EAAE,KAAK,OAAO,SAAS,UAAU,QAAQ,MAAM,mBAAmB,IAAI,EAAE,CAAC,CAAC;AACrG,MAAI,MAAM,cAAc,kBAAmB,QAAO,EAAE,QAAQ,OAAO,OAAO,gBAAgB,IAAI,EAAE;AAChG,MAAI,MAAM,cAAc,cAAe,QAAO,EAAE,QAAQ,OAAO,OAAO,YAAY,IAAI,EAAE;AACxF,MAAI,aAAa,QAAW;AAC1B,WAAO,OAAO,OAAO;AAAA,MACnB,IAAI,SAAS,SAAS,EAAE,MAAM,iBAAiB,SAAS,0CAA0C,CAAC;AAAA,IACrG;AAAA,EACF;AACA,UAAQ,MAAM,WAAW;AAAA,IACvB,KAAK;AACH,aAAO,EAAE,QAAQ,OAAO,OAAO,MAAM,QAAQ,EAAE;AAAA,IACjD,KAAK;AACH,aAAO,EAAE,QAAQ,OAAO,OAAO,WAAW,QAAQ,EAAE;AAAA,IACtD,KAAK;AACH,aAAO,EAAE,QAAQ,OAAO,OAAO,WAAW,QAAQ,EAAE;AAAA,IACtD,KAAK;AACH,aAAO,EAAE,QAAQ,OAAO,OAAO,eAAe,QAAQ,EAAE;AAAA,IAC1D,KAAK;AACH,aAAO,EAAE,QAAQ,OAAO,OAAO,qBAAqB,QAAQ,EAAE;AAAA,IAChE,KAAK;AACH,aAAO,EAAE,QAAQ,OAAO,OAAO,sBAAsB,QAAQ,EAAE;AAAA,IACjE,KAAK;AACH,aAAO,EAAE,QAAQ,OAAO,OAAO,sBAAsB,QAAQ,EAAE;AAAA,EACnE;AACF,CAAC;",
+  "names": []
+}