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

package/dist/esm/internal/Walk.js

@@ -0,0 +1,126 @@
+/**
+ * The directory names a repository walk never descends into.
+ *
+ * `grep` and `glob` walk with the kernel filesystem, and every entry costs a
+ * guarded stat. A walk rooted at "." that descends into `.git` visits tens of
+ * thousands of object files no search wants: one such `grep` held a benchmark
+ * frame for its entire fifteen-minute ceiling. The skip set is the same
+ * convention ripgrep ships — version control, dependency trees, and caches —
+ * and an explicit root inside a skipped directory still walks, because
+ * skipping applies to descent, never to what the caller named.
+ *
+ * @since 1.0.0
+ */
+import { Effect } from "effect";
+import * as Ignore from "./Ignore.js";
+import * as Prune from "./Prune.js";
+import { rootFailure } from "./SearchContract.js";
+/**
+ * Directory basenames excluded from recursive descent.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const skippedDirectories = new Set(Prune.repositoryDirectories);
+/**
+ * How many filesystem questions one directory level asks at a time.
+ *
+ * A metadata call through the layer costs far more in fiber scheduling than in
+ * kernel time, so asking one entry at a time is what makes a walk slow: the
+ * same probe measured 28.8 µs sequentially and 6.0 µs at this width on the
+ * SWE-bench pytest tree. The bound keeps the file-descriptor and thread-pool
+ * pressure of a wide directory predictable.
+ */
+const concurrency = 16;
+/**
+ * Separates pattern path segments with slashes while preserving POSIX filenames.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const relativeForPattern = (path, from, to) => {
+    const relative = path.relative(from, to);
+    return path.sep === "\\" ? relative.replaceAll("\\", "/") : relative;
+};
+/**
+ * Answers whether each path is a symbolic link, which neither peer follows.
+ *
+ * `FileSystem.stat` resolves links, so the only probe available is `readLink`,
+ * and every probe is one more call in a loop that already makes one per entry.
+ * The walk therefore probes directories, where following a link would duplicate
+ * a subtree or loop forever, and the callers probe the far smaller set of files
+ * they are about to report — batched, never one at a time.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const symbolicLinks = (fileSystem, candidates) => Effect.forEach(candidates, (candidate) => fileSystem.readLink(candidate).pipe(Effect.as(true), Effect.orElseSucceed(() => false)), { concurrency });
+/**
+ * Lists the files a search under `root` reaches.
+ *
+ * Only the root the caller named is allowed to fail the walk. Every entry
+ * below it that the process cannot inspect — a dangling symlink, a symlink
+ * loop, a directory it may not list — is skipped and the walk continues, which
+ * is what `rg --no-messages` does with the same tree. Turning one of those into
+ * a typed failure would make a whole repository unsearchable because of one
+ * link, and would answer differently from the native peer. Only .gitignore
+ * files within this root are read; ignored directories are never descended.
+ * `included` narrows the empty-result diagnostic without changing descent.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const files = (fileSystem, path, root, hidden, noIgnore = false, included = () => true) => Effect.gen(function* () {
+    const info = yield* fileSystem.stat(root).pipe(Effect.mapError((error) => rootFailure(root, error)));
+    if (info.type === "File")
+        return { explicitFile: true, files: [path.normalize(root)], ignored: false };
+    const files = [];
+    let excluded = false;
+    const directories = [{
+            directory: root,
+            scopes: []
+        }];
+    while (directories.length > 0) {
+        const next = directories.pop();
+        const { directory } = next;
+        let scopes = next.scopes;
+        const children = yield* fileSystem.readDirectory(directory).pipe(Effect.catch((error) => directory === root
+            ? Effect.fail(rootFailure(directory, error))
+            : Effect.succeed([])));
+        if (!noIgnore && children.includes(".gitignore")) {
+            const content = yield* fileSystem.readFileString(path.join(directory, ".gitignore")).pipe(Effect.orElseSucceed(() => ""));
+            const scope = Ignore.parse(directory, content);
+            if (scope.rules.length > 0)
+                scopes = [...scopes, scope];
+        }
+        const candidates = children
+            .filter((child) => !skippedDirectories.has(child) && (hidden || !child.startsWith(".")))
+            .map((child) => path.join(directory, child));
+        const entries = yield* Effect.forEach(candidates, (candidate) => fileSystem.stat(candidate).pipe(Effect.map((candidateInfo) => ({
+            candidate,
+            type: candidateInfo.type
+        })), Effect.orElseSucceed(() => ({ candidate, type: undefined }))), { concurrency });
+        const nested = [];
+        for (const entry of entries) {
+            if (entry.type !== undefined &&
+                Ignore.ignored(scopes, entry.candidate, path.basename(entry.candidate), entry.type === "Directory", (from, to) => relativeForPattern(path, from, to))) {
+                if (entry.type === "Directory" ||
+                    included(relativeForPattern(path, root, entry.candidate), path.basename(entry.candidate)))
+                    excluded = true;
+                continue;
+            }
+            if (entry.type === "Directory")
+                nested.push(entry.candidate);
+            else if (entry.type === "File")
+                files.push(path.normalize(entry.candidate));
+        }
+        const links = yield* symbolicLinks(fileSystem, nested);
+        for (let index = 0; index < nested.length; index++) {
+            const candidate = nested[index];
+            if (links[index] !== true)
+                directories.push({ directory: candidate, scopes });
+        }
+    }
+    return { explicitFile: false, files: files.sort(), ignored: excluded };
+});
+//# sourceMappingURL=Walk.js.map

package/dist/esm/internal/Walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Walk.js","sourceRoot":"","sources":["../../../src/internal/Walk.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The directory names a repository walk never descends into.\n *\n * `grep` and `glob` walk with the kernel filesystem, and every entry costs a\n * guarded stat. A walk rooted at \".\" that descends into `.git` visits tens of\n * thousands of object files no search wants: one such `grep` held a benchmark\n * frame for its entire fifteen-minute ceiling. The skip set is the same\n * convention ripgrep ships — version control, dependency trees, and caches —\n * and an explicit root inside a skipped directory still walks, because\n * skipping applies to descent, never to what the caller named.\n *\n * @since 1.0.0\n */\n\nimport type * as Path from \"@smthrs/kernel/Path\"\nimport { Effect } from \"effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport type * as StdError from \"../StdError.ts\"\nimport * as Ignore from \"./Ignore.ts\"\nimport * as Prune from \"./Prune.ts\"\nimport { rootFailure } from \"./SearchContract.ts\"\n\n/**\n * Directory basenames excluded from recursive descent.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const skippedDirectories: ReadonlySet<string> = new Set(Prune.repositoryDirectories)\n\n/**\n * How many filesystem questions one directory level asks at a time.\n *\n * A metadata call through the layer costs far more in fiber scheduling than in\n * kernel time, so asking one entry at a time is what makes a walk slow: the\n * same probe measured 28.8 µs sequentially and 6.0 µs at this width on the\n * SWE-bench pytest tree. The bound keeps the file-descriptor and thread-pool\n * pressure of a wide directory predictable.\n */\nconst concurrency = 16\n\n/**\n * Separates pattern path segments with slashes while preserving POSIX filenames.\n *\n * @private\n * @since 1.0.0\n */\nexport const relativeForPattern = (path: Path.Path, from: string, to: string): string => {\n  const relative = path.relative(from, to)\n  return path.sep === \"\\\\\" ? relative.replaceAll(\"\\\\\", \"/\") : relative\n}\n\n/**\n * Answers whether each path is a symbolic link, which neither peer follows.\n *\n * `FileSystem.stat` resolves links, so the only probe available is `readLink`,\n * and every probe is one more call in a loop that already makes one per entry.\n * The walk therefore probes directories, where following a link would duplicate\n * a subtree or loop forever, and the callers probe the far smaller set of files\n * they are about to report — batched, never one at a time.\n *\n * @private\n * @since 1.0.0\n */\nexport const symbolicLinks = (\n  fileSystem: FileSystem.FileSystem,\n  candidates: ReadonlyArray<string>\n): Effect.Effect<ReadonlyArray<boolean>> =>\n  Effect.forEach(\n    candidates,\n    (candidate) => fileSystem.readLink(candidate).pipe(Effect.as(true), Effect.orElseSucceed(() => false)),\n    { concurrency }\n  )\n\n/**\n * One walk: admitted files, explicit-root status, and ignore exclusions.\n *\n * @private\n * @since 1.0.0\n */\nexport interface Walked {\n  readonly ignored: boolean\n  readonly explicitFile: boolean\n  readonly files: ReadonlyArray<string>\n}\n\n/**\n * Lists the files a search under `root` reaches.\n *\n * Only the root the caller named is allowed to fail the walk. Every entry\n * below it that the process cannot inspect — a dangling symlink, a symlink\n * loop, a directory it may not list — is skipped and the walk continues, which\n * is what `rg --no-messages` does with the same tree. Turning one of those into\n * a typed failure would make a whole repository unsearchable because of one\n * link, and would answer differently from the native peer. Only .gitignore\n * files within this root are read; ignored directories are never descended.\n * `included` narrows the empty-result diagnostic without changing descent.\n *\n * @private\n * @since 1.0.0\n */\nexport const files = (\n  fileSystem: FileSystem.FileSystem,\n  path: Path.Path,\n  root: string,\n  hidden: boolean,\n  noIgnore = false,\n  included: (relative: string, basename: string) => boolean = () => true\n): Effect.Effect<Walked, StdError.StdError> =>\n  Effect.gen(function*() {\n    const info = yield* fileSystem.stat(root).pipe(Effect.mapError((error) => rootFailure(root, error)))\n    if (info.type === \"File\") return { explicitFile: true, files: [path.normalize(root)], ignored: false }\n    const files: Array<string> = []\n    let excluded = false\n    const directories: Array<{ directory: string; scopes: ReadonlyArray<Ignore.Scope> }> = [{\n      directory: root,\n      scopes: []\n    }]\n    while (directories.length > 0) {\n      const next = directories.pop()!\n      const { directory } = next\n      let scopes = next.scopes\n      const children: ReadonlyArray<string> = yield* fileSystem.readDirectory(directory).pipe(\n        Effect.catch((error) =>\n          directory === root\n            ? Effect.fail(rootFailure(directory, error))\n            : Effect.succeed<ReadonlyArray<string>>([])\n        )\n      )\n      if (!noIgnore && children.includes(\".gitignore\")) {\n        const content = yield* fileSystem.readFileString(path.join(directory, \".gitignore\")).pipe(\n          Effect.orElseSucceed(() => \"\")\n        )\n        const scope = Ignore.parse(directory, content)\n        if (scope.rules.length > 0) scopes = [...scopes, scope]\n      }\n      const candidates = children\n        .filter((child) => !skippedDirectories.has(child) && (hidden || !child.startsWith(\".\")))\n        .map((child) => path.join(directory, child))\n      const entries = yield* Effect.forEach(candidates, (candidate) =>\n        fileSystem.stat(candidate).pipe(\n          Effect.map((candidateInfo): { readonly candidate: string; readonly type: string | undefined } => ({\n            candidate,\n            type: candidateInfo.type\n          })),\n          Effect.orElseSucceed(() => ({ candidate, type: undefined }))\n        ), { concurrency })\n      const nested: Array<string> = []\n      for (const entry of entries) {\n        if (\n          entry.type !== undefined &&\n          Ignore.ignored(\n            scopes,\n            entry.candidate,\n            path.basename(entry.candidate),\n            entry.type === \"Directory\",\n            (from, to) => relativeForPattern(path, from, to)\n          )\n        ) {\n          if (\n            entry.type === \"Directory\" ||\n            included(relativeForPattern(path, root, entry.candidate), path.basename(entry.candidate))\n          ) excluded = true\n          continue\n        }\n        if (entry.type === \"Directory\") nested.push(entry.candidate)\n        else if (entry.type === \"File\") files.push(path.normalize(entry.candidate))\n      }\n      const links = yield* symbolicLinks(fileSystem, nested)\n      for (let index = 0; index < nested.length; index++) {\n        const candidate = nested[index]!\n        if (links[index] !== true) directories.push({ directory: candidate, scopes })\n      }\n    }\n    return { explicitFile: false, files: files.sort(), ignored: excluded }\n  })\n"]}

package/docs/README.md

@@ -0,0 +1,119 @@
+---
+title: "@smthrs/std"
+description: "The standard tool library for coding agents: read, edit, grep, bash, test, and twelve more, each a portable declaration paired with a handler your host runs."
+---
+
+`@smthrs/std` is the tool library a coding agent works with: seventeen tools,
+among them `read`, `write`, `edit`, `grep`, `glob`, `bash`, `test`, and `lsp`.
+Every tool ships as two halves. The **declaration**, called a **flow** here and
+exported as `flow` from every module, is plain data, carrying a name, the one
+line a model sees, input and output schemas, the capabilities the tool needs,
+and the effects it would have. It reaches no filesystem, no process, and no
+network, so it is safe to hand to a model or keep in a registry. The **handler**
+is an ordinary [Effect](https://effect.website) whose requirements name the host
+services it needs, so you decide what `read` reads from and where `bash` runs.
+
+Reach for this package directly when you are building your own host, your own
+tool registry, or a tool surface for a model you drive yourself. If you want the
+agent loop that already offers all seventeen, use
+[`@smthrs/agent`](/api/agent), the parent package, instead.
+
+## Why reach for this
+
+Any host can write `read` and `grep` in an afternoon. The cost arrives later, in
+the details that decide whether a model gets its next step right:
+
+- **Limits are disclosed, never silent.** Every capped result says it was
+  capped, in `truncated` and `notice`. A model shown 200 lines of a 1,000-line
+  file is told so, instead of concluding the file ends there.
+- **`read` returns raw file text.** Line numbers come back as the sibling fields
+  `startLine`, `endLine`, and `totalLines`, never as a gutter inside the text,
+  so any line of a read is an anchor that `edit` accepts as it stands.
+- **A `grep` hit carries the definition it sits in.** When a file's shape says
+  plainly which definition a match falls inside, the hit carries that
+  definition's `kind`, `name`, `startLine`, and `endLine`, so the follow-up read
+  is a fact rather than a guess.
+- **Search has one meaning and two implementations.** `PortableSearch` walks the
+  filesystem in process and needs no external binary; `NativeSearch` drives the
+  `rg` executable. A differential kit holds both to the same answers.
+- **Every tool states its authority before it runs**, as `action:resource`
+  capability strings and an effect envelope, so a permission layer or a
+  scheduler can decide about a call before making it.
+
+## Install
+
+```bash
+npm install @smthrs/std@next effect
+```
+
+The handlers
+ask the host for services such as `FileSystem`, `Path`, and
+`ChildProcessSpawner`. `@effect/platform-node` supplies them on Node.js 26.4.0 or later. For the browser-safe subset and the service each handler requires, see
+[Installation](./installation.md).
+
+## Read a file, bounded and disclosed
+
+```ts
+import { NodeServices } from "@effect/platform-node"
+import * as Read from "@smthrs/std/Read"
+import * as Effect from "effect/Effect"
+
+const page = await Effect.runPromise(
+  Effect.provide(Read.run({ path: "./README.md", limit: 20 }), NodeServices.layer)
+)
+
+console.log(page.content) // raw file text, no line-number prefixes
+console.log(`lines ${page.startLine} to ${page.endLine} of ${page.totalLines}`)
+if (page.truncated) console.log(page.notice)
+```
+
+When the file holds more than 20 lines, `page.truncated` is `true` and
+`page.notice` names both counts, in the form
+`Showing 20 of 213 lines; output was truncated.` Nothing was cut quietly, and
+every line of `page.content` can be pasted back into `edit` as an anchor.
+
+## What the library covers
+
+| Area              | Flows                                         |
+| ----------------- | --------------------------------------------- |
+| Files             | `read`, `write`, `edit`, `apply_patch`, `ls`  |
+| Search            | `grep`, `glob`, `explore`                     |
+| Processes         | `bash`, `shell_command`, `test`               |
+| Network           | `fetch`, `http-post`, `webfetch`, `websearch` |
+| Code intelligence | `lsp`                                         |
+| Planning          | `update_plan`                                 |
+
+Sixteen of the seventeen carry a handler. `explore` is a dynamic flow composed
+from the others, so it declares an interface without implementing one.
+`Manifest` is the whole set keyed by name, and `Manifest.readOnly` is the
+projection of it that changes nothing, for offering to a model you want to read
+and not write. Every field of every flow is in the
+[Flow reference](./reference/flows.md).
+
+## How this fits with the Smithers agent
+
+`@smthrs/std` is the tool half of a coding agent, and it knows nothing about
+models, prompts, or loops: it declares tools and it runs them. The loop lives in
+[`@smthrs/agent`](/api/agent), the parent package. Its `StandardFlows` module
+pairs each declaration here with its handler here, so the JavaScript a model
+emits on each turn reaches a file through `ctx.call("read", input)` rather than
+through a bespoke tool surface.
+
+See [Give a run capabilities](/pkg/agent/guides/capabilities) for how a run
+binds these flows and gates the calls a cell makes into them. Both packages sit
+under the `smithers` command line tool,
+[`@smthrs/cli`](/api/cli), which composes the agent, the durable engine, and a
+control plane into something you run in a terminal.
+
+## Where to go next
+
+- [Quickstart](./quickstart.md) searches a real directory and reads the
+  definition a hit sits in, with no external binary and no API key.
+- [Flows and handlers](./concepts/flows-and-handlers.md) explains the two halves
+  and the registries that reach both.
+- [Bind the standard flows into a host](./guides/bind-the-standard-flows.md)
+  composes the layers and offers all seventeen tools at once.
+- [Flow reference](./reference/flows.md) lists every input field, output field,
+  and failure code.
+- [Troubleshooting](./troubleshooting.md) maps each failure code to what to
+  change.