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

package/src/Ls.ts

@@ -0,0 +1,228 @@
+/**
+ * Directory listing 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.ts"
+import * as FsFailure from "./internal/FsFailure.ts"
+import { DEFAULT_READ_LIMIT, MAX_ENTRIES, notice } from "./internal/Text.ts"
+import * as StdError from "./StdError.ts"
+
+/**
+ * The registry name of the `ls` flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "ls"
+
+/**
+ * The one-line description the model sees for the `ls` flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export 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."
+
+/**
+ * What the `ls` flow accepts.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export 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"
+  })
+})
+
+/**
+ * Decoded input accepted by the `ls` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+
+/**
+ * What the `ls` flow returns.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export 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" }))
+})
+
+/**
+ * Decoded output returned by the `ls` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+
+/**
+ * The declared effect envelope of the `ls` flow, before any input is known.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "hermetic", reads: ["/**"], writes: [] })
+
+/**
+ * Narrows {@link effects} to what this particular input actually touches.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (input: typeof Input.Type) =>
+  envelope({ tier: "sealed", mode: "hermetic", reads: [input.path], writes: [] })
+
+/**
+ * The authority the `ls` flow requires.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**")]
+
+/**
+ * The `ls` 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 } as const
+
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const activity = "reads" as const
+
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const presentation = {
+  verb: { pending: "listing", success: "listed", failure: "failed to list" },
+  subject: "path",
+  result: "entries"
+} as const
+
+// localeCompare changes with host locale and ICU data. Code-unit comparisons
+// keep journalled directory listings identical on every host.
+const byText = (left: string, right: string): number => (left < right ? -1 : Number(left > right))
+
+/**
+ * Lists a directory deterministically. A file supplied as `path` is reported
+ * as `not_a_directory`.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("Ls.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, FileSystem.FileSystem | Path.Path> {
+  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
+  // An empty directory is not an out-of-range listing: the caller asked for
+  // the first page and there is nothing on it. This matches `read`, which
+  // answers an empty page for an empty file and refuses only a real overshoot.
+  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 ?? DEFAULT_READ_LIMIT, MAX_ENTRIES)
+  // Every entry is described before the page is cut, because the order the
+  // description promises is directories first and a kind is a stat away.
+  // Statting only the page and ordering inside it made the order local to the
+  // page: a directory `zdir/` beside a file `a.txt` came back as
+  // `[zdir/, a.txt]` unpaged and as `[a.txt]` then `[zdir/]` at `limit: 1`, so
+  // `offset` addressed a different listing at every page size and an agent
+  // paging a large directory could see one entry twice and another never.
+  //
+  // A per-entry stat can fail on a name the directory legitimately
+  // contains — a dangling symlink, or a file the guarded filesystem refuses
+  // to describe. The name is still real (readDirectory returned it), so the
+  // listing reports it as a plain entry instead of dying: one broken link in
+  // a repository root used to fail the whole `ls` and cost the agent a frame
+  // per attempt.
+  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" as const : "file" as const
+        })),
+        Effect.catch(() => Effect.succeed({ name: entry, kind: "file" as const }))
+      ),
+    { 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: notice("entries", selected.length, ordered.length) } : {})
+  }
+})

package/src/Lsp.ts

@@ -0,0 +1,184 @@
+/**
+ * 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 { capability, envelope } from "./internal/Declaration.ts"
+import * as FsFailure from "./internal/FsFailure.ts"
+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 const name = "lsp"
+/**
+ * The one-line description the model sees for the `lsp` flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description = "Inspect code intelligence through the configured language server."
+/**
+ * What the `lsp` flow accepts.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export 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"
+  })
+})
+/**
+ * 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 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"
+  })
+})
+/**
+ * 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 const effects = envelope({
+  tier: "sealed",
+  mode: "hermetic",
+  reads: ["/**"],
+  writes: []
+})
+/**
+ * Returns the workspace-wide envelope every language-server query needs.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input: typeof Input.Type) => effects
+/**
+ * The authority the `lsp` flow requires.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**")]
+/**
+ * The `lsp` 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
+} as const
+const isAbsolutePath = (path: string): boolean => path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path)
+/**
+ * Runs the `lsp` flow: queries the configured language server.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("Lsp.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, LanguageServer.LanguageServer | FileSystem.FileSystem> {
+  const server = yield* LanguageServer.LanguageServer
+  const path = input.path
+  const position = path === undefined || input.line === undefined || input.character === undefined
+    ? undefined
+    : { path, line: input.line - 1, character: input.character - 1 }
+  if ((input.operation === "workspaceSymbols")) return { result: yield* server.workspaceSymbols(input.query ?? "") }
+  if (path === undefined || !isAbsolutePath(path)) {
+    return yield* Effect.fail(
+      new StdError.StdError({ code: "invalid_input", message: "A normalized absolute path is required" })
+    )
+  }
+  // The server reads the file itself, outside the guarded filesystem, so the
+  // path is authorized here: a read the caller could not make through `read`
+  // is not made through the language server either.
+  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 === undefined) {
+    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) }
+  }
+})

package/src/Manifest.ts

@@ -0,0 +1,162 @@
+/**
+ * Built-in flow declarations and their separately supplied handlers.
+ *
+ * @since 1.0.0
+ */
+
+import * as ApplyPatch from "./ApplyPatch.ts"
+import * as Bash from "./Bash.ts"
+import * as Edit from "./Edit.ts"
+import * as Explore from "./Explore.ts"
+import * as Fetch from "./Fetch.ts"
+import * as Glob from "./Glob.ts"
+import * as Grep from "./Grep.ts"
+import * as HttpPost from "./HttpPost.ts"
+import * as Ls from "./Ls.ts"
+import * as Lsp from "./Lsp.ts"
+import * as Read from "./Read.ts"
+import * as ShellCommand from "./ShellCommand.ts"
+import * as TestRun from "./TestRun.ts"
+import * as UpdatePlan from "./UpdatePlan.ts"
+import * as WebFetch from "./WebFetch.ts"
+import * as WebSearch from "./WebSearch.ts"
+import * as Write from "./Write.ts"
+
+/**
+ * Frozen name-to-declaration registry for every standard flow.
+ *
+ * @category registries
+ * @since 1.0.0
+ */
+export const flows = Object.freeze({
+  [Read.name]: Read.flow,
+  [Write.name]: Write.flow,
+  [Edit.name]: Edit.flow,
+  [Ls.name]: Ls.flow,
+  [Glob.name]: Glob.flow,
+  [Grep.name]: Grep.flow,
+  [Bash.name]: Bash.flow,
+  [TestRun.name]: TestRun.flow,
+  [ShellCommand.name]: ShellCommand.flow,
+  [ApplyPatch.name]: ApplyPatch.flow,
+  [UpdatePlan.name]: UpdatePlan.flow,
+  [Fetch.name]: Fetch.flow,
+  [HttpPost.name]: HttpPost.flow,
+  [Explore.name]: Explore.flow,
+  [WebFetch.name]: WebFetch.flow,
+  [WebSearch.name]: WebSearch.flow,
+  [Lsp.name]: Lsp.flow
+})
+
+/**
+ * Frozen name-to-handler registry for executable standard flows.
+ *
+ * Explore is dynamic and therefore has no handler entry.
+ *
+ * @category registries
+ * @since 1.0.0
+ */
+export const handlers = Object.freeze({
+  [Read.name]: Read.run,
+  [Write.name]: Write.run,
+  [Edit.name]: Edit.run,
+  [Ls.name]: Ls.run,
+  [Glob.name]: Glob.run,
+  [Grep.name]: Grep.run,
+  [Bash.name]: Bash.run,
+  [TestRun.name]: TestRun.run,
+  [ShellCommand.name]: ShellCommand.run,
+  [ApplyPatch.name]: ApplyPatch.run,
+  [UpdatePlan.name]: UpdatePlan.run,
+  [Fetch.name]: Fetch.run,
+  [HttpPost.name]: HttpPost.run,
+  [WebFetch.name]: WebFetch.run,
+  [WebSearch.name]: WebSearch.run,
+  [Lsp.name]: Lsp.run
+})
+
+/**
+ * Frozen name-to-narrowing registry: the entry point for `effectsFor`.
+ *
+ * Every flow declares a registry-time worst case in `flow.effects`, and every
+ * module also narrows that declaration for one decoded input. Without this map
+ * a host holding a flow name and a decoded input has no generic way to reach
+ * the narrowing, so it would have to serialize conflicts against the worst case
+ * for every call. Explore is included even though it has no handler entry: it
+ * is a declaration a seat can be offered, and its envelope narrows the same way.
+ *
+ * @category registries
+ * @since 1.0.0
+ */
+export const effectsFor = Object.freeze({
+  [Read.name]: Read.effectsFor,
+  [Write.name]: Write.effectsFor,
+  [Edit.name]: Edit.effectsFor,
+  [Ls.name]: Ls.effectsFor,
+  [Glob.name]: Glob.effectsFor,
+  [Grep.name]: Grep.effectsFor,
+  [Bash.name]: Bash.effectsFor,
+  [TestRun.name]: TestRun.effectsFor,
+  [ShellCommand.name]: ShellCommand.effectsFor,
+  [ApplyPatch.name]: ApplyPatch.effectsFor,
+  [UpdatePlan.name]: UpdatePlan.effectsFor,
+  [Fetch.name]: Fetch.effectsFor,
+  [HttpPost.name]: HttpPost.effectsFor,
+  [Explore.name]: Explore.effectsFor,
+  [WebFetch.name]: WebFetch.effectsFor,
+  [WebSearch.name]: WebSearch.effectsFor,
+  [Lsp.name]: Lsp.effectsFor
+})
+
+/**
+ * Frozen standard flow names in registry order.
+ *
+ * @category metadata
+ * @since 1.0.0
+ */
+export const names = Object.freeze(
+  [
+    Read.name,
+    Write.name,
+    Edit.name,
+    Ls.name,
+    Glob.name,
+    Grep.name,
+    Bash.name,
+    TestRun.name,
+    ShellCommand.name,
+    ApplyPatch.name,
+    UpdatePlan.name,
+    Fetch.name,
+    HttpPost.name,
+    Explore.name,
+    WebFetch.name,
+    WebSearch.name,
+    Lsp.name
+  ] as const
+)
+
+/**
+ * Frozen names visible to a seat restricted to read-only flows.
+ *
+ * Seat policies consume this list instead of duplicating name checks.
+ *
+ * `websearch` is deliberately absent: its provider contract requires
+ * `net:post` authority, which is mutating under the kernel capability
+ * taxonomy, so it cannot ride in a read-only seat.
+ *
+ * @category visibility
+ * @since 1.0.0
+ */
+export const readOnly = Object.freeze(
+  [
+    Read.name,
+    Ls.name,
+    Glob.name,
+    Grep.name,
+    Fetch.name,
+    Explore.name,
+    WebFetch.name,
+    Lsp.name
+  ] as const
+)