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

package/src/WebSearch.ts

@@ -0,0 +1,165 @@
+/**
+ * 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.ts"
+import * as StdError from "./StdError.ts"
+
+/**
+ * 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"
+  })
+})
+/**
+ * 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 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) })
+/**
+ * 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 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: typeof Input.Type) => 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 } as const
+
+/**
+ * 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 const WebSearch: Context.Service<WebSearch, 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): WebSearch => 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 = (): WebSearch =>
+  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.Layer<WebSearch> = 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: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, WebSearch> {
+  const provider = yield* WebSearch
+  return yield* provider.search(input)
+})

package/src/Write.ts

@@ -0,0 +1,195 @@
+/**
+ * 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.ts"
+import * as Diagnostics from "./internal/Diagnostics.ts"
+import * as FileMutation from "./internal/FileMutation.ts"
+import * as FsFailure from "./internal/FsFailure.ts"
+import * as Preserve from "./internal/Preserve.ts"
+import * as StdError from "./StdError.ts"
+
+/**
+ * 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" })
+})
+
+/**
+ * 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 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" })
+})
+
+/**
+ * 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 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: typeof Input.Type) =>
+  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 } 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 = "writes" 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: "writing", success: "wrote", failure: "failed to write" },
+  subject: "path",
+  result: "write"
+} as const
+
+const writeError = (path: string, message: string): StdError.StdError =>
+  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: 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
+  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
+    }
+  }))
+})

package/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * `@smthrs/std`: the standard coding tools expressed as flows, the host
+ * services they bind, and the one error they share.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Read from "./Read.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Write from "./Write.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Edit from "./Edit.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Ls from "./Ls.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Glob from "./Glob.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Grep from "./Grep.ts"
+
+/** @category services @since 1.0.0 */
+export * as Search from "./Search.ts"
+
+/** @category services @since 1.0.0 */
+export * as SearchContract from "./SearchContract.ts"
+
+/** @category conformance @since 1.0.0 */
+export * as SearchConformance from "./SearchConformance.ts"
+
+/** @category layers @since 1.0.0 */
+export * as PortableSearch from "./PortableSearch.ts"
+
+/** @category layers @since 1.0.0 */
+export * as NativeSearch from "./NativeSearch.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Bash from "./Bash.ts"
+
+/** @category services @since 1.0.0 */
+export * as Container from "./Container.ts"
+
+/**
+ * @category measurement
+ * @since 1.0.0
+ */
+export * as TreeFingerprint from "./TreeFingerprint.ts"
+
+/** @category services @since 1.0.0 */
+export * as Checkpoints from "./Checkpoints.ts"
+
+/** @category conversions @since 1.0.0 */
+export * as Relocate from "./Relocate.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as TestRun from "./TestRun.ts"
+
+/** @category services @since 1.0.0 */
+export * as TestRunner from "./TestRunner.ts"
+
+/**
+ * @category classification
+ * @since 1.0.0
+ */
+export * as Probe from "./Probe.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as ApplyPatch from "./ApplyPatch.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as ShellCommand from "./ShellCommand.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as UpdatePlan from "./UpdatePlan.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Fetch from "./Fetch.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as HttpPost from "./HttpPost.ts"
+
+/**
+ * @category flows
+ * @since 1.0.0
+ */
+export * as Explore from "./Explore.ts"
+
+/** @category flows @since 1.0.0 */
+export * as WebFetch from "./WebFetch.ts"
+/** @category flows @since 1.0.0 */
+export * as WebSearch from "./WebSearch.ts"
+/** @category services @since 1.0.0 */
+export * as ExaWebSearch from "./ExaWebSearch.ts"
+/** @category services @since 1.0.0 */
+export * as LanguageServer from "./LanguageServer.ts"
+/** @category layers @since 1.0.0 */
+export * as NodeLanguageServer from "./NodeLanguageServer.ts"
+/** @category flows @since 1.0.0 */
+export * as Lsp from "./Lsp.ts"
+
+/**
+ * @category registries
+ * @since 1.0.0
+ */
+export * as Manifest from "./Manifest.ts"
+
+/**
+ * @category errors
+ * @since 1.0.0
+ */
+export * as StdError from "./StdError.ts"