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

package/src/HttpPost.ts

@@ -0,0 +1,120 @@
+/**
+ * HTTP POST flow declaration and portable handler.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import { capability, envelope } from "./internal/Declaration.ts"
+import { execute, Response, Timeout } from "./internal/Http.ts"
+
+/**
+ * Registry name for the http-post flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "http-post"
+
+/**
+ * Model-facing description of the http-post flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description =
+  "Post a text body to an absolute URL and return the response; this is irreversible because the remote side may already have acted."
+
+/**
+ * Input schema for the http-post flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  url: Schema.String.annotate({ description: "Absolute http or https URL to post to" }),
+  body: Schema.String.annotate({ description: "Request body sent verbatim" }),
+  contentType: Schema.optional(Schema.String).annotate({
+    description: "Request content type; defaults to application/json"
+  }),
+  headers: Schema.optional(Schema.Record(Schema.String, Schema.String)).annotate({
+    description: "Additional request headers"
+  }),
+  timeout: Schema.optional(Timeout).annotate({
+    description: "Total request and response body timeout in seconds; defaults to 30, capped at 120"
+  })
+})
+
+/**
+ * Decoded input accepted by the `http-post` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+
+/**
+ * Output schema for the http-post flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Response
+
+/**
+ * Decoded output returned by the `http-post` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+
+/**
+ * Static effect envelope for the http-post flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "irreversible", mode: "expected", reads: [], writes: [] })
+
+/**
+ * Narrows the http-post effect envelope for one decoded input.
+ *
+ * Network reach is expressed as a capability rather than a path envelope, so
+ * a post has nothing left to narrow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input: typeof Input.Type) => effects
+
+/**
+ * Capabilities required by the http-post flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("net:post", "*")]
+
+/**
+ * Declaration-only http-post flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * Posts a body through the permission-aware kernel HTTP client.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("HttpPost.run")((input: Input) =>
+  execute(input, (url) =>
+    HttpClientRequest.post(url).pipe(
+      HttpClientRequest.bodyText(input.body, input.contentType ?? "application/json")
+    ))
+)

package/src/LanguageServer.ts

@@ -0,0 +1,110 @@
+/**
+ * The code-intelligence seam behind the `lsp` flow.
+ *
+ * A host binds {@link LanguageServer} to a client such as
+ * `NodeLanguageServer.layer`. Every method answers one language-server request
+ * with the server's own result; {@link layerNoop} answers every request with
+ * `unsupported`, for a host that runs no server.
+ *
+ * @since 1.0.0
+ */
+
+import { Context, Effect, Layer } from "effect"
+import * as StdError from "./StdError.ts"
+
+/**
+ * A point in a file, addressed the way a language server addresses it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Position {
+  readonly path: string
+  readonly line: number
+  readonly character: number
+}
+/**
+ * The code-intelligence seam. Every method answers one language-server
+ * request and reports an unavailable server as a typed failure.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface LanguageServer {
+  readonly hover: (position: Position) => Effect.Effect<unknown, StdError.StdError>
+  readonly definition: (position: Position) => Effect.Effect<unknown, StdError.StdError>
+  readonly references: (position: Position) => Effect.Effect<unknown, StdError.StdError>
+  readonly implementation: (position: Position) => Effect.Effect<unknown, StdError.StdError>
+  readonly documentSymbols: (path: string) => Effect.Effect<unknown, StdError.StdError>
+  readonly workspaceSymbols: (query: string) => Effect.Effect<unknown, StdError.StdError>
+  readonly prepareCallHierarchy: (position: Position) => Effect.Effect<unknown, StdError.StdError>
+  readonly callHierarchyIncoming: (position: Position) => Effect.Effect<unknown, StdError.StdError>
+  readonly callHierarchyOutgoing: (position: Position) => Effect.Effect<unknown, StdError.StdError>
+  /**
+   * The file's diagnostics as a document report, `{ kind: "full", items }`.
+   * A server without pull diagnostics answers with what it last published for
+   * the latest synced text.
+   */
+  readonly diagnostics: (path: string) => Effect.Effect<unknown, StdError.StdError>
+  /**
+   * Tells the server a file now holds `text`: opens it on first sync and sends
+   * the full new text on every later one.
+   */
+  readonly sync: (path: string, text: string) => Effect.Effect<void, StdError.StdError>
+  /** Tells the server a synced file is gone; a file never synced is a no-op. */
+  readonly close: (path: string) => Effect.Effect<void, StdError.StdError>
+  /**
+   * Re-reads every synced file from disk: sends the text of each that changed
+   * and closes each that is gone, so a file something else changed is not
+   * left stale on the server.
+   */
+  readonly refresh: Effect.Effect<void, StdError.StdError>
+}
+/**
+ * The {@link LanguageServer} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export const LanguageServer: Context.Service<LanguageServer, LanguageServer> = Context.Service(
+  "@smthrs/std/LanguageServer"
+)
+/**
+ * Builds a {@link LanguageServer} from an implementation of its methods.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (service: LanguageServer): LanguageServer => LanguageServer.of(service)
+const unsupported = (): Effect.Effect<never, StdError.StdError> =>
+  Effect.fail(new StdError.StdError({ code: "unsupported", message: "Language server support is unavailable" }))
+/**
+ * A {@link LanguageServer} that reports `unsupported` for every request,
+ * for an environment with no server configured.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeNoop = (): LanguageServer =>
+  make({
+    hover: unsupported,
+    definition: unsupported,
+    references: unsupported,
+    implementation: unsupported,
+    documentSymbols: unsupported,
+    workspaceSymbols: unsupported,
+    prepareCallHierarchy: unsupported,
+    callHierarchyIncoming: unsupported,
+    callHierarchyOutgoing: unsupported,
+    diagnostics: unsupported,
+    sync: unsupported,
+    close: unsupported,
+    refresh: unsupported()
+  })
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerNoop: Layer.Layer<LanguageServer> = Layer.succeed(LanguageServer, makeNoop())

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) }
+  }
+})