agent-readable-ts 0.1.3 → 0.1.5

package/README.md

@@ -1,291 +1,23 @@
 # agent-readable-ts
 
-Coding agents hallucinate a library's API — inventing methods, using stale signatures, or misusing real methods because the correct usage rules (lifecycle order, preconditions, anti-patterns) are not visible from the API surface alone.
+[![CI](https://github.com/zydo/agent-readable-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/zydo/agent-readable-ts/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/agent-readable-ts.svg)](https://www.npmjs.com/package/agent-readable-ts)
 
-`agent-readable-ts` lets a library author attach those rules next to a class, object, or function. A package-level function `agentHelp(target)` returns curated, agent-oriented Markdown: the real public runtime surface that can be discovered safely, plus any author-supplied behavioral rules. An agent that calls `agentHelp(target)` before writing code against the target sees the real callable surface and the right usage rules.
+`agent-readable-ts` helps coding agents inspect the live public surface of a
+TypeScript or JavaScript API before they write code against it.
 
-> **For coding agents:** Install the agent skill to have this run automatically before coding against unfamiliar packages:
-> ```sh
-> npx skills add zydo/skills --skill agent-readable
-> ```
+Library authors can add agent-oriented usage rules next to a class, object, or
+function. Consumers call `agentHelp(target)` or the `agent-readable-ts` CLI to get
+compact Markdown with the real callable surface plus any author-supplied
+behavioral notes.
 
-**Token efficiency.** When an agent hallucinates an API, the resulting code fails — and each failed attempt triggers a retry cycle that burns tokens without making progress. `agent-readable-ts` generates compact, precise, accurate descriptions of publicly exposed interfaces (verified by runtime introspection on live packages). Calling `npx agent-readable-ts <package>` on unfamiliar packages and classes *before* writing code surfaces the real API upfront, preventing that waste.
-
-## Other languages
-
-- **Python:** [agent-readable](https://github.com/zydo/agent-readable) — same idea for Python packages and classes.
-
-## Install
+To let your coding agent automatically call `agentHelp()` before using an
+unfamiliar API, install the companion skill:
 
 ```sh
-npm install agent-readable-ts
+npx skills add zydo/skills --skill agent-readable
 ```
 
-## CLI
-
-The package includes a CLI for generating documentation from the command line. It works with local files **and installed npm packages**.
-
-```sh
-npx agent-readable-ts commander           # list all exports
-npx agent-readable-ts commander:Command   # document a specific export
-npx agent-readable-ts ./src/widget.ts:Widget   # a local TypeScript file
-```
-
-### Usage
-
-```sh
-agent-readable-ts <package-name>[:<export-name>]
-agent-readable-ts <module-path>[:<export-name>]
-```
-
-- **`package-name`** — any installed npm package (e.g. `commander`, `pino`, `@scope/package`)
-- **`module-path`** — a file path (`.js`, `.mjs`, or `.ts`) relative to the current directory
-- **`export-name`** — the named export to document (use dots for nested access, e.g. `Things.Helper`)
-
-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 require `tsx` to be installed. It is included as a devDependency, and `npx` resolves it automatically.
-
-### Examples
-
-List all exports from an installed package:
-
-```sh
-npm install commander
-npx agent-readable-ts commander
-```
-
-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 with full type signatures:
-
-```sh
-npx agent-readable-ts commander:Command
-```
-
-Output:
-
-```markdown
-# Command
-
-## Public API
-
-- `action(fn: (this: this, ...args: any[]) => void | Promise<void>): this` method
-- `addArgument(arg: Argument): this` method
-- `addCommand(cmd: Command, opts: CommandOptions): this` method
-- `addOption(option: Option): this` method
-- `alias(): string` method
-- `argument(name: string, description: string, defaultValue: unknown): this` method
-- `command(nameAndArgs: string, description: string, opts: ExecutableCommandOptions): this` method
-- `description(): string` method
-- `error(message: string, errorOptions: ErrorOptions): never` method
-- `hook(event: HookEvent, listener: (...args: any[]) => void | Promise<void>): this` method
-- `option(flags: string, description: string, defaultValue: unknown): this` method
-- `parse(argv: readonly string[], parseOptions: ParseOptions): this` method
-- `parseAsync(argv: readonly string[], parseOptions: ParseOptions): Promise<this>` method
-- `requiredOption(flags: string, description: string, defaultValue: unknown): this` method
-- `version(str: string, flags: string, description: string): this` method
-- ... (80+ methods total)
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-```
-
-Document a local file:
-
-```sh
-npx agent-readable-ts ./src/widget.ts:Widget    # a class export
-npx agent-readable-ts ./src/util.ts:connect     # a function export
-npx agent-readable-ts ./dist/api.js:fetch       # a .js file with adjacent api.d.ts
-```
-
-## Two protocols
-
-| Protocol       | Role              | Output behavior                                  |
-| -------------- | ----------------- | ------------------------------------------------ |
-| `agentHelp()`  | Full replacement  | Returned Markdown is used verbatim               |
-| `agentNotes()` | Additive guidance | Notes are appended after auto-generated API docs |
-
-### `agentHelp()` — Full replacement
-
-If a target implements `agentHelp()`, the returned string **is** the output verbatim. No auto-generated sections are added.
-
-```ts
-import { AgentHelper, agentHelp } 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.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-`;
-  }
-}
-
-console.log(agentHelp(new RateLimiter()));
-```
-
-Output:
-
-```markdown
-# RateLimiter
-
-## Usage
-
-- Create with `new RateLimiter(maxRequests)`.
-- Call `acquire()` before making a request.
-- Call `release()` after the request completes.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-```
-
-If the target also defines `agentNotes()`, a warning is written to stderr and the notes are dropped.
-
-### `agentNotes()` — Additive guidance
-
-Define `agentNotes()` on any class to append usage rules to the auto-generated documentation. Notes accumulate across the inheritance chain in parent-to-child order.
-
-```ts
-import { AgentNoter, 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.
-`;
-  }
-}
-
-console.log(agentHelp(new Sensor()));
-```
-
-### `agentHelp(target)` entry point
-
-The single entry point accepts:
-
-- Class constructors
-- Class instances
-- Plain objects
-- Plain functions
-- Arrow functions
-- Bound method values
-- Callable objects
-
-```ts
-import { agentHelp } from "agent-readable-ts";
-
-agentHelp(MyClass);          // class constructor
-agentHelp(new MyClass());    // class instance
-agentHelp({ a: 1 });        // plain object
-agentHelp(myFunction);       // function
-agentHelp(obj.method.bind(obj)); // bound method
-```
-
-## Examples
-
-### Example 1: 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()));
-```
-
-Output:
-
-```markdown
-# DocumentedClient
-
-## Public API
-
-- `connect(url)` method
-- `query(sql)` method
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-
-## Notes from DocumentedClient
-
-## Do
-
-- Call `connect()` before `query()`.
-
-## Do not
-
-- Do not pass untrusted SQL directly to `query()`.
-```
-
-### Example 2: Inheritance with accumulated notes
-
 ```ts
 import { agentHelp } from "agent-readable-ts";
 
@@ -296,255 +28,41 @@ class Sensor {
   }
 
   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()));
-```
-
-Output:
-
-```markdown
-# CalibratedSensor
-
-## Public API
-
-- `calibrate(offset)` method
-- `read()` method
-- `reset()` method
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-
-## Notes from Sensor
-
-## Do
-
-- Call `calibrate()` once during setup, before `read()`.
-
-## Do not
-
-- Do not call `read()` before `calibrate()` on first use.
-
-## Notes from CalibratedSensor (extends Sensor; if notes conflict, these take precedence)
-
-## Do
-
-- Use `reset()` only when recalibration is required.
-
-## Do not
-
-- Do not call `reset()` in the hot read path.
-```
-
-### Example 3: Full control via `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.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-`;
-  }
-  agentNotes(): string {
-    return "This is ignored because agentHelp() owns the full output.";
-  }
-}
-
-console.log(agentHelp(new RateLimiter()));
-```
-
-Output:
-
-```markdown
-# RateLimiter
-
-## Usage
-
-- Create with `new RateLimiter(maxRequests)`.
-- Call `acquire()` before making a request.
-- Call `release()` after the request completes.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-```
-
-A warning is written to stderr noting that `agentNotes()` is ignored.
-
-### Example 4: Any class, no setup
-
-```ts
-import { agentHelp } from "agent-readable-ts";
-
-class Cache {
-  get(key: string): unknown {
-    return undefined;
-  }
-  set(key: string, value: unknown): void {}
-  clear(): void {}
-}
-
-console.log(agentHelp(new Cache()));
-```
-
-Output:
-
-```markdown
-# Cache
-
-## Public API
-
-- `clear()` method
-- `get(key)` method
-- `set(key, value)` method
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-```
-
-### Example 5: 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;
+    return "- Call `calibrate()` once during setup, before `read()`.";
   }
 }
 
-const runner = new Runner();
-
-console.log(agentHelp(connect));
-console.log(agentHelp(runner.execute.bind(runner)));
+console.log(agentHelp(new Sensor()));
 ```
 
-Output for `connect`:
-
-````markdown
-# connect
-
-## Signature
+## Install
 
-```ts
-connect(host, port)
+```sh
+npm install agent-readable-ts
 ```
 
-## Agent usage rules
-
-- Call this function according to the signature above.
-- Do not invent unsupported parameters, return values, side effects, or lifecycle behavior.
-- Do not use private, underscored, or internal implementation details.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-````
-
-Output for the bound method:
+For one-off CLI use:
 
-````markdown
-# execute
-
-## Signature
-
-```ts
-execute(arg0)
+```sh
+npx agent-readable-ts commander
+npm exec -- agent-readable-ts commander:Command
+pnpm dlx agent-readable-ts ./src/widget.ts:Widget
 ```
 
-## Agent usage rules
-
-- Call this function according to the signature above.
-- Do not invent unsupported parameters, return values, side effects, or lifecycle behavior.
-- Do not use private, underscored, or internal implementation details.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-````
-
-## Warning output
+See [Getting Started](docs/getting-started.md) for full install and CLI usage.
 
-By default, advisory warnings are written to `process.stderr`. You can redirect or silence them:
-
-```ts
-import { setWarnOutput, getWarnOutput } from "agent-readable-ts";
-
-// Redirect to a custom sink
-setWarnOutput((chunk: string) => {
-  console.log("[WARN]", chunk.trim());
-});
-
-// Or use an object with a write method
-setWarnOutput({ write(chunk: string) { /* handle */ } });
-
-// Silence warnings
-setWarnOutput(null);
-
-// Restore default
-setWarnOutput(process.stderr);
-```
+## Documentation
 
-## Limitations in TypeScript
+- [Getting Started](docs/getting-started.md)
+- [Why agent-readable-ts?](docs/why.md)
+- [Examples](docs/examples.md)
+- [Authoring Notes](docs/authoring.md)
+- [FAQ](docs/faq.md)
 
-Runtime JavaScript reflection cannot read TypeScript type annotations, interfaces, overloads, generic parameters, return types, or doc comments. The auto-generated documentation is intentionally conservative:
+## Other Languages
 
-- **Parameter names** are recovered from `Function.prototype.toString()` when possible. For native or bound functions, names fall back to `arg0`, `arg1`, etc. using `Function.length`. Destructured parameters also fall back to `argN`.
-- **Type information** is available in two ways:
-  - **CLI with `.ts` source**: full types are extracted by parsing the source file with the TypeScript compiler API.
-  - **CLI with `.js`/`.mjs`/`.cjs` files**: types are extracted from adjacent `.d.ts`/`.d.mts`/`.d.cts` declaration files if present (covers published packages).
-  - **Library API (`agentHelp()`)**: no type information — only runtime parameter names and arity.
-- **No per-method descriptions.** Authors convey prose through `agentNotes()` or by implementing `agentHelp()`.
-- **Constructors are not invoked** during introspection. Construction guidance belongs in notes.
-- **Instance fields** can only be discovered from an actual instance or plain object, not from a class constructor.
-- **Getters are not invoked** during introspection.
-- **TypeScript `private` and `protected`** are compile-time constructs. The library excludes names starting with `_` but cannot perfectly detect visibility at runtime.
-- **JavaScript `#private` fields and methods** are not reflectable and never appear in output.
-- **Module-level documentation** is not supported.
-- **Dynamic package import or CLI-based introspection** is intentionally omitted.
+- **Python:** [agent-readable](https://github.com/zydo/agent-readable) provides
+  the same idea for Python packages and classes.
 
 ## License
 

package/dist/src/cli.js

@@ -6,8 +6,12 @@ import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 function usage() {
-    process.stderr.write("Usage: agent-readable-ts <module-path>[:<export-name>]\n" +
-        "       agent-readable-ts <package-name>[:<export-name>]\n");
+    process.stderr.write("Usage: agent-readable-ts [--install] <module-path>[:<export-name>]\n" +
+        "       agent-readable-ts [--install] <package-name>[:<export-name>]\n" +
+        "\n" +
+        "Options:\n" +
+        "  --install  Allow fetching a package on demand (with npm install) when it\n" +
+        "             is not already installed locally or in the cache.\n");
     process.exit(1);
 }
 function fail(message) {
@@ -38,9 +42,9 @@ async function handleFile(modulePath, exportName) {
     process.stdout.write(agentHelp(target, typeSigs));
 }
 // ── package-based handling ─────────────────────────────────────────────────────
-async function handlePackage(spec, exportName) {
+async function handlePackage(spec, exportName, allowInstall) {
     const { name } = splitPackageSpec(spec);
-    const { mod, typesDir } = await loadPackage(spec);
+    const { mod, typesDir } = await loadPackage(spec, undefined, allowInstall);
     const dtsPath = resolvePackageTypesPath(name, typesDir);
     // No export name: list all exports
     if (!exportName) {
@@ -58,13 +62,21 @@ async function handlePackage(spec, exportName) {
     process.stdout.write(agentHelp(target, typeSigs));
 }
 // ── main ───────────────────────────────────────────────────────────────────────
-const specifier = process.argv[2];
+const args = process.argv.slice(2);
+const allowInstall = args.includes("--install");
+const positional = args.filter((arg) => arg !== "--install");
+const unknownFlag = positional.find((arg) => arg.startsWith("--"));
+if (unknownFlag) {
+    process.stderr.write(`Error: Unknown option "${unknownFlag}"\n`);
+    usage();
+}
+const specifier = positional[0];
 if (!specifier)
     usage();
 try {
     const { modulePath, exportName } = parseSpecifier(specifier);
     if (isBarePackageName(modulePath)) {
-        await handlePackage(modulePath, exportName);
+        await handlePackage(modulePath, exportName, allowInstall);
     }
     else {
         await handleFile(modulePath, exportName);

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/packages.d.ts

@@ -24,7 +24,7 @@ export declare function formatExportList(packageName: string, exports: ExportDes
 export declare function listRuntimeExports(mod: Record<string, unknown>): ExportDescriptor[];
 export declare function isModuleNotFound(err: unknown): boolean;
 export declare function isInstalledIn(name: string, dir: string): boolean;
-export declare function ensureCacheInstall(name: string, install: string, dir?: string): string;
+export declare function ensureCacheInstall(name: string, install: string, dir?: string, allowInstall?: boolean): string;
 export declare function resolvePackageRootFromDir(name: string, dir: string): string | null;
 export declare function resolveLocalPackageRoot(name: string): string | null;
 export declare function importFromDir(name: string, dir: string): Promise<Record<string, unknown>>;
@@ -32,5 +32,5 @@ export interface LoadedPackage {
     mod: Record<string, unknown>;
     typesDir: string;
 }
-export declare function loadPackage(spec: string, cacheDir?: string): Promise<LoadedPackage>;
+export declare function loadPackage(spec: string, cacheDir?: string, allowInstall?: boolean): Promise<LoadedPackage>;
 //# sourceMappingURL=packages.d.ts.map

package/dist/src/packages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/packages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,eAAO,MAAM,SAAS,QAC8D,CAAC;AAIrF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAQnG;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKhF;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAc3E;AAoBD,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,gBAAgB,GAAG,SAAS,CAc1G;AAID,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAiBtH;AAaD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,EAAE,CAInF;AAID,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGtD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAchE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,MAAM,CAqBjG;AAoBD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAclF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBnE;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAkB/F;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAiBpG"}
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/packages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,eAAO,MAAM,SAAS,QAC8D,CAAC;AAIrF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAQnG;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKhF;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAc3E;AAoBD,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,gBAAgB,GAAG,SAAS,CAc1G;AAID,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAiBtH;AAaD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,EAAE,CAInF;AAID,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGtD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAchE;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAkB,EACvB,YAAY,UAAQ,GACnB,MAAM,CAsCR;AAoBD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAclF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBnE;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAkB/F;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAkB,EAC5B,YAAY,UAAQ,GACnB,OAAO,CAAC,aAAa,CAAC,CAiBxB"}

package/dist/src/packages.js

@@ -149,18 +149,33 @@ export function isInstalledIn(name, dir) {
         return false;
     }
 }
-export function ensureCacheInstall(name, install, dir = CACHE_DIR) {
+export function ensureCacheInstall(name, install, dir = CACHE_DIR, allowInstall = false) {
     mkdirSync(dir, { recursive: true });
     const pkgJson = join(dir, "package.json");
     if (!existsSync(pkgJson)) {
         writeFileSync(pkgJson, JSON.stringify({ name: "agent-readable-cache", private: true }) + "\n");
     }
     if (!isInstalledIn(name, dir)) {
+        if (!allowInstall) {
+            throw new Error(`Package "${name}" is not installed. ` +
+                `Run "npm install ${install}" in your project, or re-run with --install to fetch it on demand.`);
+        }
         process.stderr.write(`Installing ${install} on demand into ${dir} ...\n`);
         try {
             // Save into the cache's own package.json so previously fetched packages are
             // not pruned as "extraneous" when a different package is installed later.
-            execFileSync("npm", ["install", install, "--prefix", dir, "--save", "--no-audit", "--no-fund", "--loglevel=error"], { stdio: ["ignore", "ignore", "inherit"] });
+            // --ignore-scripts prevents arbitrary lifecycle scripts from running.
+            execFileSync("npm", [
+                "install",
+                install,
+                "--prefix",
+                dir,
+                "--save",
+                "--ignore-scripts",
+                "--no-audit",
+                "--no-fund",
+                "--loglevel=error",
+            ], { stdio: ["ignore", "ignore", "inherit"] });
         }
         catch (err) {
             throw new Error(`Failed to install "${install}": ${err instanceof Error ? err.message : String(err)}`);
@@ -251,7 +266,7 @@ export async function importFromDir(name, dir) {
         rmSync(loaderPath, { force: true });
     }
 }
-export async function loadPackage(spec, cacheDir = CACHE_DIR) {
+export async function loadPackage(spec, cacheDir = CACHE_DIR, allowInstall = false) {
     const { name, install } = splitPackageSpec(spec);
     // Prefer a copy already resolvable from the current project.
     try {
@@ -264,7 +279,7 @@ export async function loadPackage(spec, cacheDir = CACHE_DIR) {
         }
     }
     // Not installed locally: fetch on demand into the cache, then load from there.
-    const dir = ensureCacheInstall(name, install, cacheDir);
+    const dir = ensureCacheInstall(name, install, cacheDir, allowInstall);
     const mod = await importFromDir(name, dir);
     return { mod, typesDir: resolvePackageRootFromDir(name, dir) ?? dir };
 }

package/dist/src/packages.js.map

@@ -1 +1 @@
-{"version":3,"file":"packages.js","sourceRoot":"","sources":["../../src/packages.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"packages.js","sourceRoot":"","sources":["../../src/packages.ts"],"names":[],"mappings":"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"}

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,59 @@
+# FAQ
+
+## Which Node versions are supported?
+
+Node 20 or newer.
+
+## 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.
+
+## 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).
+
+## 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,94 @@
+# 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 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, local JavaScript files, and local
+TypeScript files.
+
+```sh
+npx agent-readable-ts commander
+npx agent-readable-ts commander:Command
+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>]
+```
+
+- `package-name`: an installed npm package, such as `commander`, `pino`, or
+  `@scope/package`.
+- `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 require `tsx`. It is included as a dev dependency in this repo, and
+`npx` resolves it automatically when running from this package.
+
+## One-Off Execution
+
+Use one of these when you do not want to add a dependency to the current project:
+
+```sh
+npx agent-readable-ts commander
+npm exec -- agent-readable-ts commander:Command
+pnpm dlx agent-readable-ts ./src/widget.ts:Widget
+```
+
+## On-Demand Package Fetching
+
+Packages already installed in the current project load directly. For anything
+else, 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. 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,6 +1,6 @@
 {
   "name": "agent-readable-ts",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Attach agent-oriented documentation to any class, object, or function",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -17,6 +17,7 @@
     "agent-readable-ts": "dist/src/cli.js"
   },
   "files": [
+    "docs",
     "dist/src"
   ],
   "scripts": {