@intentic/agent-cli 1.310.0 → 1.311.0

package/README.md

@@ -1,37 +1,37 @@
-# @intentic/agent-cli
+# agent-cli
 
-The promise an agent-facing CLI makes — capsule first, content to a budget, errors you cannot mistake for silence — held in one place for the three tools that make it.
+The process contract, budgeted output and in-process test runner that the agent-facing CLIs `iq`, `fileq` and `webq` share, so a failure never reads as an empty answer.
 
-`iq` (code), `fileq` (workspace files) and `webq` (the web) are three answers to one question: *the thing I need
-is in a format I cannot read, give me the part that fits.* They were written months apart, each one's entry file
-copied from the last, and the copies had already drifted in the way copies do — three spellings of "read my own
-version", two hand-rolled parsers beside the one their shared dependency ships, one inline token estimate beside
-the shared one it was supposed to use.
+```mermaid
+flowchart LR
+    agent["Agent shell<br/>pipes into head, drops stderr"] --> bin["iq · fileq · webq"]
+    bin --> run(["agent-cli<br/>runAgentCli"])
+    run --> app["The tool's stricli app<br/>loaded lazily"]
+    app --> out["stdout<br/>capsule, clipped body, errors"]
+    out --> agent
+```
 
-What lives here is only the part all three must answer the same way:
+- The reader is an agent: it pipes into `head`, sends stderr to `/dev/null` and cannot tell a crash from an empty
+  answer. So `runAgentCli` treats EPIPE as a clean stop, writes errors to stdout, reports a module graph that will
+  not load as a broken install, and clamps the exit code to 0 content, 1 none, 2 anything else.
+- The app is passed as a `load` thunk, never a static import, so an engine or native module that fails to load
+  fails inside the contract's catch and gets reported.
+- `capsule` prints the line an agent reads first plus one `note:` per caveat; `clip` cuts markdown to a token budget
+  on a line boundary and always names the file that holds the whole answer.
+- `toolHome` gives each tool its own directory: `<NAME>_HOME`, else `$XDG_CACHE_HOME/<name>`, else `~/.cache/<name>`.
+- Each tool's end-to-end suites use `captureCli` from `./testing`, which runs the app in process and returns what
+  a shell would see.
 
-- **The process contract** ([src/run.ts](src/run.ts)). EPIPE is a clean stop, not a crash — an agent pipes into
-  `head`. Errors go to **stdout**, because `<tool> … 2>/dev/null` is a reflex and a failure routed to stderr
-  reads as an empty answer. The app loads through a thunk so a broken module graph dies as a sentence naming the
-  install, not as a stack the same reflex swallows. Exit codes are 0 content / 1 none / 2 anything else.
-- **The output shape** ([src/output.ts](src/output.ts)). One capsule line, one `note:` per caveat, then content
-  cut on a line boundary with a trailer naming the budget it hit and the file holding the rest. A body that
-  stops mid-thought with no trailer is the failure mode this exists to prevent.
-- **The rest of the floor**: one XDG home per tool ([src/env.ts](src/env.ts)), one version resolver that finds
-  the manifest by walking to it ([src/version.ts](src/version.ts)), one non-negative parser for counts and
-  budgets ([src/flags.ts](src/flags.ts)), one in-process test seam ([src/testing.ts](src/testing.ts)).
+## Key files
 
-What does **not** live here is everything that makes the three tools different: iq's grep-dialect absorption and
-fusion budgets, fileq's sidecars and derivers, webq's cache, pruning and crawls. The shell takes a `name` and a
-`noun` and nothing else about what the tool does.
+- [src/run.ts](src/run.ts) — `runAgentCli`: the process contract every rule above lives in.
+- [src/output.ts](src/output.ts) — `capsule` and `clip`, the capsule-then-content shape these CLIs print.
+- [src/env.ts](src/env.ts) — `toolHome` and `toolOutDir`, where a tool's own files go.
+- [src/testing.ts](src/testing.ts) — `captureCli`, the in-process runner the tools' suites drive.
+- [src/flags.ts](src/flags.ts) — `countParser`, which refuses negative, infinite and NaN budgets.
 
-## Key files
+## Commands
 
-- [src/run.ts](src/run.ts) — the process contract; the one file a `cli.ts` is allowed to import statically, and
-  `run.test.ts` fails if it ever grows a runtime import of its own.
-- [src/output.ts](src/output.ts) — the capsule line and the budget cut, including the trailer that keeps a
-  clipped answer from reading as a whole one.
-- [src/env.ts](src/env.ts) — `<NAME>_HOME` → `XDG_CACHE_HOME` → `~/.cache/<name>`, and the shared `out` leaf.
-- [src/flags.ts](src/flags.ts) — the count parser, and why stricli's own is not it.
-- [src/testing.ts](src/testing.ts) — runs an app through the same `run` seam `cli.ts` uses, capturing stdout: no
-  build artifact, no child process.
+```sh
+pnpm --filter @intentic/agent-cli test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/agent-cli",
-  "version": "1.310.0",
+  "version": "1.311.0",
   "description": "The process contract, budgeted output and test seam every agent-facing CLI in this repo keeps",
   "license": "MIT",
   "type": "module",
@@ -85,8 +85,8 @@
     }
   },
   "dependencies": {
-    "@intentic/base": "1.310.0",
-    "@intentic/constants": "1.310.0",
+    "@intentic/base": "1.311.0",
+    "@intentic/constants": "1.311.0",
     "@stricli/core": "1.3.0",
     "tslib": "2.8.1"
   },