agent-readable-ts 0.1.4 → 0.1.6

package/docs/authoring.md

@@ -0,0 +1,112 @@
+# Authoring Notes
+
+Start with clear public method names and JSDoc. Add `agentNotes()` only when a
+class or object has cross-method rules that are easy to miss.
+
+Use `agentHelp()` rarely, when the auto-generated output is not the right shape
+and you want to provide the full Markdown response yourself.
+
+## `agentNotes()`
+
+Define `agentNotes()` to append usage guidance after the generated public API
+docs.
+
+```ts
+import { AgentNoter } from "agent-readable-ts";
+
+interface Connection {}
+
+class DatabasePool implements AgentNoter {
+  acquire(): Promise<Connection> {
+    throw new Error("not implemented");
+  }
+
+  release(conn: Connection): void {}
+
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  agentNotes(): string {
+    return `
+## Do
+
+- Always call \`release(conn)\` after every \`acquire()\`, even on error.
+- Call \`shutdown()\` during graceful application teardown.
+
+## Do not
+
+- Do not call \`acquire()\` after \`shutdown()\`.
+- Do not share a \`Connection\` object across async tasks.
+`;
+  }
+}
+```
+
+`agentNotes()` is a good fit for:
+
+- lifecycle and call ordering rules;
+- preconditions and cleanup requirements;
+- sync vs async constraints;
+- streaming vs non-streaming behavior;
+- important do and do-not guidance.
+
+Avoid duplicating obvious method-level information that belongs in names,
+signatures, or JSDoc.
+
+## Inheritance
+
+Notes accumulate across the inheritance chain in parent-to-child order.
+
+Unlike Python, TypeScript does not automatically merge notes from separate
+prototype methods. Implement `agentNotes()` on each class that has its own
+cross-method rules.
+
+## `agentHelp()`
+
+Implement `agentHelp()` for full control over the returned Markdown:
+
+```ts
+import { AgentHelper } from "agent-readable-ts";
+
+class RateLimiter implements AgentHelper {
+  agentHelp(): string {
+    return `# RateLimiter
+
+## Usage
+
+- Create with \`new RateLimiter(maxRequests)\`.
+- Call \`acquire()\` before making a request.
+- Call \`release()\` after the request completes.
+`;
+  }
+}
+```
+
+If both `agentHelp()` and `agentNotes()` are defined on the same target,
+`agentHelp()` wins and `agentNotes()` is ignored. The library emits a warning,
+but authors should treat this as an API design error.
+
+## Warning Output
+
+By default, advisory warnings are written to `process.stderr`. You can redirect
+or silence them:
+
+```ts
+import { getWarnOutput, setWarnOutput } from "agent-readable-ts";
+
+setWarnOutput((chunk: string) => {
+  console.log("[WARN]", chunk.trim());
+});
+
+setWarnOutput({
+  write(chunk: string) {
+    console.log(chunk);
+  },
+});
+
+setWarnOutput(null);
+setWarnOutput(process.stderr);
+```
+
+`getWarnOutput()` returns the current warning sink.

package/docs/examples.md

@@ -0,0 +1,166 @@
+# Examples
+
+## Installed Package
+
+List all exports from an installed package:
+
+```sh
+npm install commander
+npx agent-readable-ts commander
+```
+
+Example output:
+
+```markdown
+# commander
+
+## Exports
+
+- `CommanderError` class
+- `InvalidArgumentError` class
+- `Argument` class
+- `Option` class
+- `Help` class
+- `Command` class
+- `createCommand(name: string): Command` function
+- `createOption(flags: string, description: string): Option` function
+- `createArgument(name: string, description: string): Argument` function
+- `program` object
+```
+
+Document a specific export:
+
+```sh
+npx agent-readable-ts commander:Command
+```
+
+## Local File
+
+```sh
+npx agent-readable-ts ./src/widget.ts:Widget
+npx agent-readable-ts ./src/util.ts:connect
+npx agent-readable-ts ./dist/api.js:fetch
+```
+
+For `.js`, `.mjs`, and `.cjs` files, the CLI can read adjacent `.d.ts`,
+`.d.mts`, and `.d.cts` declaration files when they exist.
+
+## Wrapping a Class You Do Not Own
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+class Client {
+  connect(url: string): void {}
+  query(sql: string): unknown {
+    return undefined;
+  }
+}
+
+class DocumentedClient extends Client {
+  agentNotes(): string {
+    return `
+## Do
+
+- Call \`connect()\` before \`query()\`.
+
+## Do not
+
+- Do not pass untrusted SQL directly to \`query()\`.
+`;
+  }
+}
+
+console.log(agentHelp(new DocumentedClient()));
+```
+
+## Inheritance With Accumulated Notes
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+class Sensor {
+  calibrate(offset: number): void {}
+  read(): number {
+    return 0;
+  }
+
+  agentNotes(): string {
+    return `
+## Do
+
+- Call \`calibrate()\` once during setup, before \`read()\`.
+
+## Do not
+
+- Do not call \`read()\` before \`calibrate()\` on first use.
+`;
+  }
+}
+
+class CalibratedSensor extends Sensor {
+  reset(): void {}
+
+  override agentNotes(): string {
+    return `
+## Do
+
+- Use \`reset()\` only when recalibration is required.
+
+## Do not
+
+- Do not call \`reset()\` in the hot read path.
+`;
+  }
+}
+
+console.log(agentHelp(new CalibratedSensor()));
+```
+
+Notes are emitted in parent-to-child order. If rules conflict, the child class
+guidance should be treated as more specific.
+
+## Full Control With `agentHelp()`
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+class RateLimiter {
+  agentHelp(): string {
+    return `# RateLimiter
+
+## Usage
+
+- Create with \`new RateLimiter(maxRequests)\`.
+- Call \`acquire()\` before making a request.
+- Call \`release()\` after the request completes.
+`;
+  }
+}
+
+console.log(agentHelp(new RateLimiter()));
+```
+
+When `agentHelp()` exists, its returned Markdown is used verbatim.
+
+## Functions and Bound Methods
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+function connect(host: string, port: number): void {}
+
+class Runner {
+  execute(command: string): number {
+    return 0;
+  }
+}
+
+const runner = new Runner();
+
+console.log(agentHelp(connect));
+console.log(agentHelp(runner.execute.bind(runner)));
+```
+
+Bound methods may lose original parameter names at runtime and fall back to
+`arg0`, `arg1`, and so on.

package/docs/faq.md

@@ -0,0 +1,73 @@
+# FAQ
+
+## Which Node versions are supported?
+
+Node 20.6 or newer. The CLI's package resolution uses the synchronous
+`import.meta.resolve()`, which is available from Node 20.6.
+
+## Should I use the library API or the CLI?
+
+Use `agentHelp(target)` when the target is already loaded in your program.
+
+Use the CLI when you want better TypeScript signatures from source files or
+declaration files:
+
+```sh
+npx agent-readable-ts ./src/widget.ts:Widget
+npx agent-readable-ts commander:Command
+```
+
+## Can runtime reflection recover TypeScript types?
+
+No. TypeScript types, interfaces, overloads, generic parameters, return types,
+and doc comments are erased from compiled JavaScript.
+
+The CLI can recover more type information by parsing `.ts` files or adjacent
+declaration files.
+
+## Why do some parameters show up as `arg0`?
+
+Parameter names come from `Function.prototype.toString()` when possible. Native
+functions, bound functions, destructured parameters, and some compiled output do
+not preserve useful names, so the library falls back to `arg0`, `arg1`, and so
+on.
+
+## Are constructors or getters invoked?
+
+No. Constructors are not called during introspection, and getters are not
+invoked.
+
+## Are private members shown?
+
+JavaScript `#private` fields and methods are not reflectable and never appear.
+
+TypeScript `private` and `protected` are compile-time constructs. The library
+excludes names starting with `_`, but runtime JavaScript cannot perfectly detect
+TypeScript visibility.
+
+## Why is `typescript` a dependency?
+
+The CLI uses the TypeScript compiler API to recover type signatures from `.ts`
+sources and declaration files. Bundling it keeps one-off runs such as
+`npx agent-readable-ts commander:Command` fully typed out of the box, at the
+cost of a larger install. The runtime reflection in `agentHelp()` itself does
+not need the compiler — if the compiler cannot be loaded, the library degrades
+to runtime-only signatures instead of failing.
+
+## Does the CLI fetch packages automatically?
+
+No. Missing packages are only fetched when you pass `--install`.
+
+Fetched packages go into an isolated cache and are installed with
+`--ignore-scripts`. See [Getting Started](getting-started.md#on-demand-package-fetching).
+
+`--ignore-scripts` blocks package install scripts, but inspecting a package
+still executes its top-level code when it is imported — see
+[Security](getting-started.md#security).
+
+## Is this the same as the Python package?
+
+It is the TypeScript and JavaScript sibling of
+[agent-readable](https://github.com/zydo/agent-readable). The shared idea is the
+same: inspect the current API surface and author-provided usage rules before
+coding against an unfamiliar target.

package/docs/getting-started.md

@@ -0,0 +1,132 @@
+# Getting Started
+
+`agent-readable-ts` can be used as a library from TypeScript or JavaScript, and
+as a CLI for inspecting local files or npm packages.
+
+## Install
+
+```sh
+npm install agent-readable-ts
+```
+
+Node 20.6 or newer is required.
+
+## Library Usage
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+console.log(agentHelp(SomeClass));        // class constructor
+console.log(agentHelp(new SomeClass()));  // class instance
+console.log(agentHelp(someFunction));     // function or arrow function
+console.log(agentHelp({ a: 1 }));         // plain object
+```
+
+The programmatic API uses runtime JavaScript reflection. It can show public
+members, parameter names when available, and `agentNotes()`/`agentHelp()` output,
+but it cannot recover TypeScript-only types from compiled JavaScript.
+
+## CLI Usage
+
+The CLI can inspect installed npm packages, Node builtins, local JavaScript
+files, and local TypeScript files.
+
+```sh
+npx agent-readable-ts commander
+npx agent-readable-ts commander:Command
+npx agent-readable-ts node:fs:ReadStream
+npx agent-readable-ts ./src/widget.ts:Widget
+```
+
+`commander` is only an example target. Use any trusted installed package, local
+module, or local TypeScript file.
+
+Usage:
+
+```sh
+agent-readable-ts [--install] <package-name>[:<export-name>]
+agent-readable-ts <module-path>[:<export-name>]
+agent-readable-ts node:<builtin>[:<export-name>]
+```
+
+- `package-name`: an installed npm package, such as `commander`, `pino`, or
+  `@scope/package`.
+- `builtin`: a Node builtin module, such as `node:fs` or `node:util`. Type
+  signatures come from `@types/node` when it is installed.
+- `module-path`: a `.js`, `.mjs`, `.cjs`, or `.ts` file path relative to the
+  current directory.
+- `export-name`: the named export to document. Use dots for nested access, such
+  as `Things.Helper`.
+- `--install`: allow the CLI to fetch a package on demand when it is not
+  installed locally.
+
+If no export name is given for a package, all exports are listed. If no export
+name is given for a file, the module namespace object is documented.
+
+`.ts` files load through Node's built-in type stripping (enabled by default on
+Node 22.18+). On older runtimes, register a TypeScript loader such as tsx first
+(installed in the project — a global tsx is not visible to `--import`), for
+example `NODE_OPTIONS="--import tsx" npx agent-readable-ts ./src/widget.ts:Widget`.
+
+## One-Off CLI Use
+
+Two tool options (`npx` and `pnpm`) — pick whichever matches your package manager. Each one-off command runs the CLI without adding a dependency to the current project, and the downloaded package is cached, so repeat runs start instantly. Replace `commander` with any installed package, Node builtin, or local file target.
+
+### npm
+
+```sh
+# One-off — npx fetches and caches the CLI
+npx agent-readable-ts commander
+
+# Repeated use — install once globally, then run the bare command
+npm install -g agent-readable-ts
+agent-readable-ts commander
+```
+
+### pnpm
+
+```sh
+# One-off — pnpm's equivalent of npx
+pnpm dlx agent-readable-ts commander
+
+# Repeated use — install once globally, then run the bare command
+pnpm add -g agent-readable-ts
+agent-readable-ts commander
+```
+
+`yarn dlx` and `bunx` work the same way.
+
+## Your Own Project
+
+One-off runs resolve packages from the current project's `node_modules` first and load local files by path, so your own code needs no install:
+
+```sh
+npx agent-readable-ts ./src/widget.ts:Widget
+```
+
+`.ts` files load through Node's built-in type stripping (enabled by default on Node 22.18+); on older runtimes register a loader such as tsx first — see [CLI Usage](#cli-usage).
+
+## On-Demand Package Fetching
+
+Packages are resolved in order: from the current project's `node_modules`, then
+from the CLI's own install, then from the cache. This means one-off runs such as
+`npx agent-readable-ts <package>` see the packages your project already has
+installed. For anything not found, the CLI refuses to fetch unless `--install`
+is passed:
+
+```sh
+npx agent-readable-ts --install left-pad
+```
+
+Fetched packages go into `~/.cache/agent-readable-ts`, or the directory named by
+`AGENT_READABLE_CACHE`. They are never installed into the current project.
+
+The install uses `npm install --ignore-scripts`, so package lifecycle scripts are
+not run. Concurrent installs into the shared cache are serialized with a lock.
+Cached packages load offline without requiring `--install` again.
+
+## Security
+
+The CLI imports packages and local modules in order to inspect them. Importing a
+module executes its top-level code. Only inspect packages and files you trust to
+run on your machine.

package/docs/why.md

@@ -0,0 +1,43 @@
+# Why agent-readable-ts?
+
+Coding agents often guess a library API from stale memory: inventing methods,
+using old signatures, or missing lifecycle rules that are not visible from a
+method list alone.
+
+`agent-readable-ts` gives agents a small, live, API-shaped context before they
+write code:
+
+- the public callable surface that can be discovered safely;
+- TypeScript signatures when the CLI can parse source or declaration files;
+- author-supplied usage rules from `agentNotes()`;
+- full custom guidance from `agentHelp()` when a library needs it.
+
+This reduces failed edit-test-retry loops and keeps the agent focused on the API
+that exists in the current project.
+
+## Why Not Just README Docs?
+
+README files are written for people and often cover happy-path examples. Coding
+agents need a compact answer to narrower questions:
+
+- What members exist on this object right now?
+- Which methods are public?
+- What is the current call shape?
+- Are there ordering, cleanup, async, or safety rules?
+
+`agent-readable-ts` puts that information next to the implementation and exposes
+it through one consistent inspection path.
+
+## Runtime and Source Inspection
+
+TypeScript type annotations do not exist at runtime. The library API therefore
+uses conservative JavaScript reflection. The CLI fills more gaps by parsing
+`.ts` source or adjacent `.d.ts` declaration files for packages and JavaScript
+modules.
+
+When type detail matters, prefer the CLI:
+
+```sh
+npx agent-readable-ts ./src/widget.ts:Widget
+npx agent-readable-ts commander:Command
+```

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "agent-readable-ts",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Attach agent-oriented documentation to any class, object, or function",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,6 +24,7 @@
     "agent-readable-ts": "dist/src/cli.js"
   },
   "files": [
+    "docs",
     "dist/src"
   ],
   "scripts": {
@@ -35,7 +43,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.6.0"
   },
   "dependencies": {
     "typescript": "^5.5.0"