@code-first-agents/tool 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Gipponi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @code-first-agents/tool
+
+![CI](https://github.com/beogip/code-first-agents-tool/actions/workflows/ci.yml/badge.svg)
+[![npm](https://img.shields.io/npm/v/@code-first-agents/tool)](https://www.npmjs.com/package/@code-first-agents/tool)
+
+Code-first agent tool definitions with Zod schemas.
+
+## Installation
+
+```bash
+bun add @code-first-agents/tool
+# or
+npm install @code-first-agents/tool
+```
+
+## Usage
+
+```ts
+import { Tool, l1Output } from "@code-first-agents/tool";
+import { z } from "zod";
+
+const greet = new Tool({
+  name: "greet",
+  description: "Say hello",
+  input: z.object({ name: z.string() }),
+  handler: async ({ input }) => l1Output("pass", `Hello, ${input.name}!`),
+});
+```
+
+## Development
+
+**Prerequisites:** [Bun](https://bun.sh) >= 1.0
+
+```bash
+git clone https://github.com/beogip/code-first-agents-tool.git
+cd code-first-agents-tool
+bun install
+```
+
+| Command          | Description                     |
+| ---------------- | ------------------------------- |
+| `bun run dev`    | Run with file watcher           |
+| `bun run build`  | Compile to `dist/` (bun + tsc)  |
+| `bun test`       | Run tests                       |
+| `bun run check`  | Lint + format (Biome, auto-fix) |
+| `bun run lint`   | Lint only                       |
+| `bun run format` | Format only                     |
+
+## Project Structure
+
+```
+src/          # Source code
+tests/        # Test files (*.test.ts)
+dist/         # Build output (git-ignored)
+```
+
+## Git Hooks
+
+[Lefthook](https://github.com/evilmartians/lefthook) runs automatically after `bun install` (via the `prepare` script):
+
+- **pre-commit** — Biome checks and auto-fixes staged files
+- **commit-msg** — Validates [Conventional Commits](https://www.conventionalcommits.org/) format
+
+## Releases
+
+Releases are automated via [semantic-release](https://semantic-release.gitbook.io/) on every push to `main`:
+
+- `feat:` → minor release
+- `fix:` → patch release
+- `feat!:` or `BREAKING CHANGE:` → major release
+
+The CI workflow handles changelog generation, npm publishing, GitHub releases, and version bumping automatically.
+
+## License
+
+[MIT](LICENSE)

package/dist/args.d.ts

@@ -0,0 +1,55 @@
+/**
+ * args.ts — CLI argv parsing and input validation for the Tool base class.
+ *
+ * Contains only the pre-dispatch concerns: turning `process.argv.slice(2)`
+ * into a structured `{subcommand, ParsedArgs}` pair and validating the
+ * parsed args against a subcommand's Zod input schema.
+ *
+ * @module code-first-agents-tool/args
+ */
+import type { z } from "zod";
+import type { ParsedArgs } from "./types.ts";
+/**
+ * Subcommand names reserved by the base class (`schema`, `help`).
+ * Module-private: not re-exported from `./index.ts`.
+ */
+export declare const RESERVED_SUBCOMMANDS: ReadonlySet<string>;
+/**
+ * Parse a raw argv slice into subcommand + typed flags + positional args.
+ *
+ * Rules:
+ * - `argv[0]` is the subcommand. A leading `--` prefix is stripped so that
+ *   `--help` and `help` both resolve to `"help"`. The bare `--` sentinel
+ *   yields an empty subcommand.
+ * - When `argv[0]` is NOT already a reserved builtin, a `--help` or
+ *   `--schema` flag in the remaining tokens (up to the `--` sentinel)
+ *   promotes to the subcommand (global-flag override).
+ * - Tokens starting with `--` are flag keys; the next token (if not also a
+ *   flag) is the value. A bare `--flag` at end-of-argv or followed by
+ *   another `--flag` resolves to `true`.
+ * - Repeated `--flag v1 --flag v2` → last-one-wins (`v2`).
+ * - The bare `--` token is the end-of-options sentinel (POSIX convention):
+ *   all subsequent tokens become positional, even if they start with `--`.
+ * - Non-flag tokens become positional args in order.
+ *
+ * Pure function — no I/O, no side effects.
+ *
+ * @param argv - Array of CLI tokens, typically `process.argv.slice(2)`.
+ * @returns Parsed subcommand + {@link ParsedArgs}.
+ */
+export declare function parseArgs(argv: string[]): {
+    subcommand: string;
+    parsed: ParsedArgs;
+};
+/**
+ * Validate raw {@link ParsedArgs} against a subcommand's input Zod schema.
+ * Flags are merged as-is; positional args are attached under a reserved `_`
+ * key only when present (so strict schemas without `_` stay happy when no
+ * positional args are passed).
+ *
+ * @param parsed - Raw parsed args from {@link parseArgs}.
+ * @param inputSchema - The subcommand's input Zod schema.
+ * @returns The Zod `safeParse` result carrying either validated data or a structured error.
+ */
+export declare function validateInput<I extends z.ZodTypeAny>(parsed: ParsedArgs, inputSchema: I): z.ZodSafeParseResult<z.core.output<I>>;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAA+B,CAAC;AAkBrF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CA6CpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,0CAMvF"}

package/dist/envelopes.d.ts

@@ -0,0 +1,141 @@
+/**
+ * envelopes.ts — Typed error-envelope factories for the Tool base class.
+ *
+ * The four error codes (`unknown_subcommand`, `input_validation_error`,
+ * `schema_violation`, `unexpected_error`) are modeled as a discriminated
+ * union so extras (`subcommands`, `input_schema`, `detail`) stay type-safe
+ * per-code. Each builder owns the exact message template for its code,
+ * which previously lived inline in `Tool#run`.
+ *
+ * @module code-first-agents-tool/envelopes
+ */
+import type { z } from "zod";
+import { type HelpPayload } from "./introspection.ts";
+import type { SubcommandSpec } from "./types.ts";
+/**
+ * Discriminated union of every error envelope the base class can emit.
+ * Each variant is assignable to `ToolOutput` from `./utils.ts` via its
+ * index signature, so `jsonOutput` consumes them without casts.
+ *
+ * The final variant (`error: string`) covers handler-emitted business
+ * errors thrown via {@link ToolError} — the `error` code is whatever the
+ * handler chose.
+ */
+export type ErrorEnvelope = {
+    ok: false;
+    error: "unknown_subcommand";
+    message: string;
+    subcommands: HelpPayload;
+} | {
+    ok: false;
+    error: "input_validation_error";
+    message: string;
+    detail: string;
+    input_schema: unknown;
+} | {
+    ok: false;
+    error: "schema_violation";
+    message: string;
+    detail: string;
+} | {
+    ok: false;
+    error: "non_object_return";
+    message: string;
+} | {
+    ok: false;
+    error: "unexpected_error";
+    message: string;
+    detail?: string | Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+    message: string;
+    detail?: string | Record<string, unknown>;
+};
+/**
+ * Error class a handler can throw to emit a structured error envelope with
+ * a business-specific `error` code (e.g. `"path_not_found"`, `"rate_limited"`).
+ * The base class catches instances of this class and produces the envelope
+ * via {@link toolErrorEnvelope}; anything else thrown becomes an
+ * `unexpected_error` envelope.
+ *
+ * @example
+ * handler: ({ path }) => {
+ *   if (!existsSync(path)) {
+ *     throw new ToolError("path_not_found", `Path does not exist: ${path}`);
+ *   }
+ *   return { message: "ok", ... };
+ * }
+ */
+export declare class ToolError extends Error {
+    /** Machine-readable error code emitted in the envelope's `error` field. */
+    readonly code: string;
+    /** Optional extra context included in the envelope's `detail` field. */
+    readonly detail?: string | Record<string, unknown>;
+    /**
+     * @param code - Machine-readable error code (emitted verbatim). Conventionally snake_case.
+     * @param message - Human-readable message.
+     * @param detail - Optional extra context (string or structured object).
+     */
+    constructor(code: string, message: string, detail?: string | Record<string, unknown>);
+}
+/**
+ * Build the `unknown_subcommand` envelope. When `name === ""` (empty argv),
+ * the message notes the absence; otherwise it names the unrecognized input.
+ * Always includes the full `subcommands` listing so an LLM caller can
+ * self-correct on retry.
+ *
+ * @param name - The unrecognized subcommand (or empty string for empty argv).
+ * @param subs - The Tool's registered-subcommands map.
+ * @returns A typed `unknown_subcommand` envelope.
+ */
+export declare function unknownSubcommandEnvelope(name: string, subs: ReadonlyMap<string, SubcommandSpec<z.ZodTypeAny, z.ZodTypeAny>>): ErrorEnvelope;
+/**
+ * Build the `input_validation_error` envelope. Attaches the input JSON
+ * Schema (or `$error` fallback) so the LLM can correct the flags and retry.
+ *
+ * @param name - The subcommand whose input failed validation.
+ * @param zerr - The Zod error produced by `safeParse`.
+ * @param inputSchema - The subcommand's declared input Zod schema.
+ * @returns A typed `input_validation_error` envelope.
+ */
+export declare function inputValidationErrorEnvelope(name: string, zerr: z.ZodError, inputSchema: z.ZodTypeAny): ErrorEnvelope;
+/**
+ * Build the `schema_violation` envelope. Fires when a handler returns a
+ * value that fails the subcommand's output Zod schema.
+ *
+ * @param name - The subcommand whose handler return failed validation.
+ * @param zerr - The Zod error produced by output `safeParse`.
+ * @returns A typed `schema_violation` envelope.
+ */
+export declare function schemaViolationEnvelope(name: string, zerr: z.ZodError): ErrorEnvelope;
+/**
+ * Build the `unexpected_error` envelope. Catches anything the handler (or
+ * the base class plumbing itself) throws that is NOT a {@link ToolError}.
+ * The error's stack is included in `detail` when available.
+ *
+ * @param err - The thrown value (or rejected Promise reason).
+ * @returns A typed `unexpected_error` envelope.
+ */
+export declare function unexpectedErrorEnvelope(err: unknown): ErrorEnvelope;
+/**
+ * Build a handler-emitted error envelope from a {@link ToolError}. Preserves
+ * the custom `code`, `message`, and optional `detail` the handler declared,
+ * so consumers see a business-specific error envelope instead of a generic
+ * `unexpected_error`.
+ *
+ * @param err - The {@link ToolError} the handler threw.
+ * @returns An envelope carrying the handler's custom `error` code.
+ */
+export declare function toolErrorEnvelope(err: ToolError): ErrorEnvelope;
+/**
+ * Build the `non_object_return` envelope. Fires when a handler returns a
+ * non-plain-object value (null, string, array, etc.) that cannot be spread
+ * into the output envelope.
+ *
+ * @param name - The subcommand whose handler returned a non-object.
+ * @param value - The actual value the handler returned (used to describe the type).
+ * @returns A typed `non_object_return` envelope.
+ */
+export declare function nonObjectReturnEnvelope(name: string, value: unknown): ErrorEnvelope;
+//# sourceMappingURL=envelopes.d.ts.map

package/dist/envelopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,oBAAoB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;CAC1B,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,wBAAwB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;CACvB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,kBAAkB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,kBAAkB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C,CAAC;AAEN;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,SAAgB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1D;;;;OAIG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,GACpE,aAAa,CAWf;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,CAAC,QAAQ,EAChB,WAAW,EAAE,CAAC,CAAC,UAAU,GACxB,aAAa,CAUf;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,GAAG,aAAa,CAOrF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAMnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,aAAa,CAI/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,aAAa,CAOnF"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * index.ts — Barrel for the code-first-agents Tool base class.
+ *
+ * Implementation lives in `src/*.ts`. This file re-exports the public API
+ * so consumers import from the package root:
+ *
+ *   import { Tool, l1Output, parseArgs, validateInput } from "@code-first-agents/tool";
+ *
+ * @module @code-first-agents/tool
+ */
+export { parseArgs, validateInput } from "./args.ts";
+export type { ErrorEnvelope } from "./envelopes.ts";
+export { ToolError } from "./envelopes.ts";
+export type { HelpPayload, HelpPayloadEntry, SchemaOutputEntry, } from "./introspection.ts";
+export { buildHelpPayload, buildSchemaOutput } from "./introspection.ts";
+export type { JSONSchemaResult } from "./json-schema.ts";
+export { l1Output, l2Output, l3Output } from "./output-helpers.ts";
+export { Tool } from "./tool-class.ts";
+export type { HandlerReturn, ParsedArgs, SubcommandSpec, ToolMeta, } from "./types.ts";
+export type { ToolOutput } from "./utils.ts";
+export { jsonOutput, stringifyError } from "./utils.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACrD,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACzE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,316 @@
+// src/args.ts
+var RESERVED_SUBCOMMANDS = new Set(["schema", "help"]);
+function normalizeSubcommand(raw) {
+  if (raw === undefined || raw === "--")
+    return "";
+  return raw.startsWith("--") ? raw.slice(2) : raw;
+}
+function parseArgs(argv) {
+  let subcommand = normalizeSubcommand(argv[0]);
+  const flags = {};
+  const positional = [];
+  let i = 1;
+  while (i < argv.length) {
+    const tok = argv[i];
+    if (tok === "--") {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!tok.startsWith("--")) {
+      positional.push(tok);
+      i += 1;
+      continue;
+    }
+    const key = tok.slice(2);
+    if (RESERVED_SUBCOMMANDS.has(key) && !RESERVED_SUBCOMMANDS.has(subcommand)) {
+      subcommand = key;
+      i += 1;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+      flags[key] = true;
+      i += 1;
+      continue;
+    }
+    flags[key] = next;
+    i += 2;
+  }
+  return { subcommand, parsed: { flags, positional } };
+}
+function validateInput(parsed, inputSchema) {
+  const toValidate = { ...parsed.flags };
+  if (parsed.positional.length > 0) {
+    toValidate._ = parsed.positional;
+  }
+  return inputSchema.safeParse(toValidate);
+}
+// src/json-schema.ts
+import { z } from "zod";
+function safeToJSONSchema(schema) {
+  try {
+    return { ok: true, schema: z.toJSONSchema(schema, { target: "draft-2020-12" }) };
+  } catch (err) {
+    return { ok: false, $error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+// src/introspection.ts
+function buildSchemaOutput(subs) {
+  const result = {};
+  for (const [name, spec] of subs) {
+    const inputResult = safeToJSONSchema(spec.input);
+    const outputResult = safeToJSONSchema(spec.output);
+    if (!inputResult.ok) {
+      result[name] = { $error: inputResult.$error };
+    } else if (!outputResult.ok) {
+      result[name] = { $error: outputResult.$error };
+    } else {
+      result[name] = { input: inputResult.schema, output: outputResult.schema };
+    }
+  }
+  return result;
+}
+function buildHelpPayload(subs) {
+  const result = [];
+  for (const [name, spec] of subs) {
+    const conv = safeToJSONSchema(spec.input);
+    const input_schema = conv.ok ? conv.schema : { $error: conv.$error };
+    result.push({ name, description: spec.description, input_schema });
+  }
+  return result;
+}
+
+// src/utils.ts
+function jsonOutput(data) {
+  console.log(JSON.stringify(data));
+  process.exit(0);
+}
+function stringifyError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/envelopes.ts
+class ToolError extends Error {
+  code;
+  detail;
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "ToolError";
+    this.code = code;
+    if (detail !== undefined) {
+      this.detail = detail;
+    }
+  }
+}
+function unknownSubcommandEnvelope(name, subs) {
+  const message = name === "" ? "No subcommand provided — see 'subcommands' for available options" : `Unknown subcommand '${name}' — see 'subcommands' for available options`;
+  return {
+    ok: false,
+    error: "unknown_subcommand",
+    message,
+    subcommands: buildHelpPayload(subs)
+  };
+}
+function inputValidationErrorEnvelope(name, zerr, inputSchema) {
+  const conv = safeToJSONSchema(inputSchema);
+  const input_schema = conv.ok ? conv.schema : { $error: conv.$error };
+  return {
+    ok: false,
+    error: "input_validation_error",
+    message: `Input validation failed for subcommand '${name}'`,
+    detail: zerr.message,
+    input_schema
+  };
+}
+function schemaViolationEnvelope(name, zerr) {
+  return {
+    ok: false,
+    error: "schema_violation",
+    message: `Handler output failed schema validation for subcommand '${name}'`,
+    detail: zerr.message
+  };
+}
+function unexpectedErrorEnvelope(err) {
+  const message = stringifyError(err);
+  const stack = err instanceof Error ? err.stack : undefined;
+  return stack !== undefined ? { ok: false, error: "unexpected_error", message, detail: stack } : { ok: false, error: "unexpected_error", message };
+}
+function toolErrorEnvelope(err) {
+  return err.detail !== undefined ? { ok: false, error: err.code, message: err.message, detail: err.detail } : { ok: false, error: err.code, message: err.message };
+}
+function nonObjectReturnEnvelope(name, value) {
+  const type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  return {
+    ok: false,
+    error: "non_object_return",
+    message: `Handler for '${name}' must return a plain object, got ${type}`
+  };
+}
+// src/output-helpers.ts
+import { z as z2 } from "zod";
+function l1Output(fields) {
+  return z2.object({
+    ok: z2.literal(true),
+    message: z2.string(),
+    ...fields
+  });
+}
+function l2Output(classification, fields) {
+  return z2.object({
+    ok: z2.literal(true),
+    message: z2.string(),
+    classification,
+    ...fields ?? {}
+  });
+}
+function l3Output(fields) {
+  return z2.object({
+    ok: z2.literal(true),
+    message: z2.string(),
+    instructions: z2.string(),
+    ...fields ?? {}
+  });
+}
+// src/tool-class.ts
+import { z as z3 } from "zod";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+class Tool {
+  meta;
+  subs = new Map;
+  constructor(meta) {
+    this.meta = meta;
+  }
+  subcommand(spec) {
+    this.validateRegistration(spec);
+    this.subs.set(spec.name, spec);
+    return this;
+  }
+  async run(argv) {
+    try {
+      const { subcommand, parsed } = parseArgs(argv);
+      const builtin = this.dispatchBuiltin(subcommand);
+      if (builtin)
+        return jsonOutput(builtin);
+      const miss = this.rejectUnknown(subcommand);
+      if (miss)
+        return jsonOutput(miss);
+      return jsonOutput(await this.runSubcommand(subcommand, parsed));
+    } catch (err) {
+      if (err instanceof ToolError)
+        return jsonOutput(toolErrorEnvelope(err));
+      return jsonOutput(unexpectedErrorEnvelope(err));
+    }
+  }
+  validateRegistration(spec) {
+    if (RESERVED_SUBCOMMANDS.has(spec.name)) {
+      throw new RangeError(`Subcommand name "${spec.name}" is reserved — the base class auto-registers 'schema' and 'help'`);
+    }
+    if (this.subs.has(spec.name)) {
+      throw new RangeError(`Subcommand "${spec.name}" is already registered`);
+    }
+    if (spec.input === undefined || spec.input === null) {
+      throw new TypeError(`Subcommand "${spec.name}" is missing required 'input' Zod schema (use z.object({}).strict() for argless subs)`);
+    }
+    if (spec.output === undefined || spec.output === null) {
+      throw new TypeError(`Subcommand "${spec.name}" is missing required 'output' Zod schema (use l1Output({}) for minimal output)`);
+    }
+  }
+  dispatchBuiltin(name) {
+    if (name === "schema") {
+      return {
+        ok: true,
+        message: this.subs.size === 0 ? `Tool "${this.meta.name}" has no subcommands registered` : `JSON Schemas for ${this.subs.size} subcommand(s)`,
+        schemas: buildSchemaOutput(this.subs)
+      };
+    }
+    if (name === "help") {
+      return {
+        ok: true,
+        message: this.meta.description || `Help for ${this.meta.name}`,
+        tool: { name: this.meta.name },
+        subcommands: buildHelpPayload(this.subs)
+      };
+    }
+    return null;
+  }
+  rejectUnknown(name) {
+    if (name === "" || !this.subs.has(name)) {
+      return unknownSubcommandEnvelope(name, this.subs);
+    }
+    return null;
+  }
+  async runSubcommand(name, parsed) {
+    const spec = this.subs.get(name);
+    if (!spec) {
+      return unexpectedErrorEnvelope(new Error(`Subcommand '${name}' vanished between rejectUnknown and runSubcommand`));
+    }
+    const inputResult = validateInput(parsed, spec.input);
+    if (!inputResult.success) {
+      return inputValidationErrorEnvelope(name, inputResult.error, spec.input);
+    }
+    const handlerResult = await spec.handler(inputResult.data);
+    return this.validateOutput(name, handlerResult, spec);
+  }
+  async invoke(subcommand, args = {}) {
+    try {
+      const builtin = this.dispatchBuiltin(subcommand);
+      if (builtin)
+        return builtin;
+      const miss = this.rejectUnknown(subcommand);
+      if (miss)
+        return miss;
+      const spec = this.subs.get(subcommand);
+      if (!spec) {
+        return unexpectedErrorEnvelope(new Error(`Subcommand '${subcommand}' vanished between rejectUnknown and invoke`));
+      }
+      const inputResult = spec.input.safeParse(args);
+      if (!inputResult.success) {
+        return inputValidationErrorEnvelope(subcommand, inputResult.error, spec.input);
+      }
+      const handlerResult = await spec.handler(inputResult.data);
+      return this.validateOutput(subcommand, handlerResult, spec);
+    } catch (err) {
+      if (err instanceof ToolError)
+        return toolErrorEnvelope(err);
+      return unexpectedErrorEnvelope(err);
+    }
+  }
+  validateOutput(name, handlerResult, spec) {
+    if (!isPlainObject(handlerResult)) {
+      return nonObjectReturnEnvelope(name, handlerResult);
+    }
+    const fullResult = { ...handlerResult, ok: true };
+    const outputResult = spec.output.safeParse(fullResult);
+    if (!outputResult.success) {
+      return schemaViolationEnvelope(name, outputResult.error);
+    }
+    const data = outputResult.data;
+    if (!("ok" in data)) {
+      return schemaViolationEnvelope(name, new z3.ZodError([
+        {
+          code: "custom",
+          path: ["ok"],
+          message: "Output schema is missing 'ok' field — add ok: z.literal(true) or use l1Output/l2Output/l3Output helpers"
+        }
+      ]));
+    }
+    return data;
+  }
+}
+export {
+  validateInput,
+  stringifyError,
+  parseArgs,
+  l3Output,
+  l2Output,
+  l1Output,
+  jsonOutput,
+  buildSchemaOutput,
+  buildHelpPayload,
+  ToolError,
+  Tool
+};

package/dist/introspection.d.ts

@@ -0,0 +1,51 @@
+/**
+ * introspection.ts — Builders for the auto-registered `schema` and `help`
+ * subcommand payloads, plus the help listing carried inside the
+ * `unknown_subcommand` error envelope.
+ *
+ * Both builders delegate to `safeToJSONSchema` so exotic Zod constructs
+ * fail soft (one subcommand emits `{$error}` instead of crashing the whole
+ * response).
+ *
+ * @module code-first-agents-tool/introspection
+ */
+import type { z } from "zod";
+import type { SubcommandSpec } from "./types.ts";
+/** One entry in the `subcommands` help listing. */
+export interface HelpPayloadEntry {
+    /** Subcommand name as registered. */
+    name: string;
+    /** One-line description from the spec. */
+    description: string;
+    /** Input JSON Schema (draft-2020-12) or `{$error}` fallback. */
+    input_schema: unknown;
+}
+/** The shape returned by {@link buildHelpPayload} — an array of entries. */
+export type HelpPayload = HelpPayloadEntry[];
+/** One entry in the `schemas` map emitted by the `schema` subcommand. */
+export type SchemaOutputEntry = {
+    input: unknown;
+    output: unknown;
+} | {
+    $error: string;
+};
+/**
+ * Convert a registered subcommand map into a `{name: {input, output}}`
+ * record of JSON Schemas (draft-2020-12). Per-subcommand conversion is
+ * fail-soft via {@link safeToJSONSchema}: a failing sub gets a `$error`
+ * entry instead of crashing the whole `schema` response.
+ *
+ * @param subs - Map from subcommand name to its spec.
+ * @returns Record keyed by subcommand name, each value either `{input, output}` or `{$error}`.
+ */
+export declare function buildSchemaOutput(subs: ReadonlyMap<string, SubcommandSpec<z.ZodTypeAny, z.ZodTypeAny>>): Record<string, SchemaOutputEntry>;
+/**
+ * Build the `subcommands` array used by `help` output and the
+ * `unknown_subcommand` error envelope. Each entry carries the input JSON
+ * Schema so an LLM caller can discover which flags a subcommand expects.
+ *
+ * @param subs - Map from subcommand name to its spec.
+ * @returns Array of `{name, description, input_schema}` entries.
+ */
+export declare function buildHelpPayload(subs: ReadonlyMap<string, SubcommandSpec<z.ZodTypeAny, z.ZodTypeAny>>): HelpPayload;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../src/introspection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,gBAAgB,EAAE,CAAC;AAE7C,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,GACpE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAcnC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,GACpE,WAAW,CAQb"}

package/dist/json-schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * json-schema.ts — Safe wrapper around `z.toJSONSchema`.
+ *
+ * `z.toJSONSchema` throws on exotic Zod constructs (e.g. `.transform()`).
+ * This helper centralizes the try/catch and the target version
+ * (`draft-2020-12`) so the three call sites — `buildSchemaOutput`,
+ * `buildHelpPayload`, and the `input_validation_error` envelope builder —
+ * share a single fail-soft path.
+ *
+ * **Known limitation:** Zod v4's `toJSONSchema` emits `required` for fields
+ * that have `.default(...)`. The emitted JSON Schema says the field is
+ * mandatory even though Zod's runtime validation accepts its absence and
+ * fills the default. This can mislead LLM callers reading `input_schema`
+ * for self-correction (they may conclude a defaulted flag is required).
+ * No workaround applied — consumers should test with the actual tool, not
+ * rely on the schema's `required` array for defaulted fields.
+ *
+ * @module code-first-agents-tool/json-schema
+ */
+import { z } from "zod";
+/** Result of converting a Zod schema to JSON Schema — success carries the schema; failure carries a message. */
+export type JSONSchemaResult = {
+    ok: true;
+    schema: unknown;
+} | {
+    ok: false;
+    $error: string;
+};
+/**
+ * Convert a Zod schema to JSON Schema (draft-2020-12) without throwing.
+ * On success returns `{ ok: true, schema }`; on failure returns
+ * `{ ok: false, $error }` carrying the thrown message.
+ *
+ * @param schema - Any Zod schema.
+ * @returns A discriminated result — never throws.
+ */
+export declare function safeToJSONSchema(schema: z.ZodTypeAny): JSONSchemaResult;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gHAAgH;AAChH,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,gBAAgB,CAMvE"}

package/dist/output-helpers.d.ts

@@ -0,0 +1,77 @@
+/**
+ * output-helpers.ts — Level-specific output-schema composers for the
+ * code-first-agents Tool contract.
+ *
+ * Every tool output includes the `ok: z.literal(true)` + `message: z.string()`
+ * envelope. These helpers bake that in and add the fields the spec requires
+ * for each level (none for L1; required `classification` enum for L2;
+ * required `instructions` string for L3), so the caller can't forget them
+ * and VS Code shows a fully-resolved handler return type.
+ *
+ * Opt-in: tools with shapes that don't fit a level may pass a raw
+ * `z.object({...})` to `output`. The base class doesn't require a helper.
+ *
+ * @module code-first-agents-tool/output-helpers
+ */
+import { z } from "zod";
+/**
+ * Compose an **L1 (data)** output schema: envelope + arbitrary raw fields.
+ * Use when the tool returns facts for the LLM to interpret.
+ *
+ * @example
+ * const schema = l1Output({ checkboxes: z.number(), file_paths: z.number() });
+ *
+ * @param fields - Raw data fields to include alongside the envelope.
+ * @returns A `z.object` carrying `ok`, `message`, and the caller's fields.
+ */
+export declare function l1Output<T extends z.ZodRawShape>(fields: T): z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    message: z.ZodString;
+} & T extends infer T_1 ? { -readonly [P in keyof T_1]: T_1[P]; } : never, z.core.$strip>;
+/**
+ * Compose an **L2 (classification)** output schema: envelope + a required
+ * `classification` enum + optional extras. Use when the tool returns a
+ * discrete category the skill can branch on.
+ *
+ * @example
+ * const schema = l2Output(
+ *   z.enum(["lean", "standard", "full"]),
+ *   { score: z.number(), signals: z.object({ checkboxes: z.number() }) },
+ * );
+ *
+ * @param classification - Zod enum describing the discrete classification result.
+ * @param fields - Optional extras (e.g. score, raw signals) merged into the output.
+ * @returns A `z.object` carrying `ok`, `message`, `classification`, and extras.
+ */
+export declare function l2Output<C extends z.ZodTypeAny, T extends z.ZodRawShape>(classification: C, fields: T): z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    message: z.ZodString;
+    classification: C;
+} & T>;
+export declare function l2Output<C extends z.ZodTypeAny>(classification: C): z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    message: z.ZodString;
+    classification: C;
+}>;
+/**
+ * Compose an **L3 (instructions)** output schema: envelope + a required
+ * `instructions` string + optional extras. Use when the tool builds a
+ * verbatim procedure for the LLM to execute.
+ *
+ * @example
+ * const schema = l3Output({ plan_level: z.enum(["lean", "standard", "full"]) });
+ *
+ * @param fields - Optional extras (e.g. classification alongside instructions) merged into the output.
+ * @returns A `z.object` carrying `ok`, `message`, `instructions`, and extras.
+ */
+export declare function l3Output<T extends z.ZodRawShape>(fields: T): z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    message: z.ZodString;
+    instructions: z.ZodString;
+} & T>;
+export declare function l3Output(): z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    message: z.ZodString;
+    instructions: z.ZodString;
+}>;
+//# sourceMappingURL=output-helpers.d.ts.map

package/dist/output-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-helpers.d.ts","sourceRoot":"","sources":["../src/output-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;;;0FAM1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,WAAW,EACtE,cAAc,EAAE,CAAC,EACjB,MAAM,EAAE,CAAC,GACR,CAAC,CAAC,SAAS,CAAC;IAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC;IAAC,cAAc,EAAE,CAAC,CAAA;CAAE,GAAG,CAAC,CAAC,CAAC;AAExF,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAC7C,cAAc,EAAE,CAAC,GAChB,CAAC,CAAC,SAAS,CAAC;IAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC;IAAC,cAAc,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAUpF;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAC9C,MAAM,EAAE,CAAC,GACR,CAAC,CAAC,SAAS,CAAC;IAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC;IAAC,YAAY,EAAE,CAAC,CAAC,SAAS,CAAA;CAAE,GAAG,CAAC,CAAC,CAAC;AAEhG,wBAAgB,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC;IACtC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC,SAAS,CAAC;CAC3B,CAAC,CAAC"}

package/dist/tool-class.d.ts

@@ -0,0 +1,162 @@
+/**
+ * tool-class.ts — The `Tool` orchestrator for code-first-agents deterministic tools.
+ *
+ * Implements the tool contract defined in the code-first agents pattern:
+ * - Subcommand dispatch with typed input/output Zod schemas
+ * - Validated JSON output (the shape IS the validator)
+ * - Self-describing `schema` subcommand (auto-registered)
+ * - `help` subcommand + unknown-subcommand fallback that exposes input schemas
+ *   so LLM callers can self-correct
+ * - Always exits with code 0; errors communicated via `ok: false` envelope
+ *
+ * Spec: https://beogip.github.io/code-first-agents/patterns/deterministic-tools.html
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { z } from "zod";
+ * import { Tool, l2Output } from "@code-first-agents/tool";
+ *
+ * new Tool({ name: "level-classifier", description: "..." })
+ *   .subcommand({
+ *     name: "classify",
+ *     description: "Classify a SKILL.md by code-first level",
+ *     input: z.object({ path: z.string() }).strict(),
+ *     output: l2Output(z.enum(["L1", "L2", "L3"])),
+ *     // Handler returns message + data. `ok: true` is framework-added.
+ *     handler: ({ path }) => ({
+ *       message: `classified ${path}`,
+ *       classification: "L2",
+ *     }),
+ *   })
+ *   .run(process.argv.slice(2));
+ * ```
+ *
+ * ## Output envelope contract
+ *
+ * Handlers return the output shape **without `ok`** — the base class stamps
+ * `ok: true` onto the handler's result before validating against the output
+ * schema. This keeps handlers focused on `message` + business data and avoids
+ * TypeScript widening `ok: true` to `boolean` in object-literal returns.
+ *
+ * Use the level helpers (`l1Output`, `l2Output`, `l3Output` from
+ * `./output-helpers.ts`) to get the envelope + level-specific required
+ * fields baked in; fall back to raw `z.object({...})` when the tool's shape
+ * doesn't fit a level (remember to include `ok: z.literal(true)` and
+ * `message: z.string()` in the raw schema so validation covers the whole
+ * envelope).
+ *
+ * Error envelopes (`schema_violation`, `input_validation_error`,
+ * `unknown_subcommand`, `unexpected_error`) are class-authored — see
+ * `./envelopes.ts`.
+ *
+ * @module code-first-agents-tool/tool-class
+ */
+import { z } from "zod";
+import type { SubcommandSpec, ToolMeta } from "./types.ts";
+import { type ToolOutput } from "./utils.ts";
+/**
+ * Orchestrator for a code-first deterministic tool. Register subcommands via
+ * {@link Tool.subcommand}, then call {@link Tool.run} with `process.argv.slice(2)`.
+ *
+ * The class always terminates the process with exit code 0 via `jsonOutput`;
+ * errors are communicated through the JSON envelope's `ok: false` + `error`
+ * fields.
+ *
+ * Reserved subcommand names `schema` and `help` are auto-registered by the
+ * class — attempting to register them manually throws `RangeError`.
+ */
+export declare class Tool {
+    private readonly meta;
+    private readonly subs;
+    /**
+     * @param meta - Tool metadata (name + description).
+     */
+    constructor(meta: ToolMeta);
+    /**
+     * Register a subcommand. Chainable (returns `this`).
+     *
+     * Throws synchronously on:
+     * - reserved name collision (`schema`, `help`) → `RangeError`
+     * - duplicate name → `RangeError`
+     * - missing `input` schema → `TypeError`
+     * - missing `output` schema → `TypeError`
+     *
+     * @param spec - {@link SubcommandSpec} carrying name, description, input/output Zod schemas, and handler.
+     * @returns This tool instance, for chaining.
+     */
+    subcommand<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(spec: SubcommandSpec<I, O>): this;
+    /**
+     * Dispatch a subcommand from parsed `argv`. Always terminates the process
+     * via `jsonOutput` with exit code 0.
+     *
+     * Pure dispatch — each branch delegates to a single-responsibility helper:
+     * 1. {@link Tool.dispatchBuiltin} handles `schema` / `help`.
+     * 2. {@link Tool.rejectUnknown} handles empty or unregistered subcommands.
+     * 3. {@link Tool.runSubcommand} runs the validate → handler → validate pipeline.
+     * 4. Outer try/catch: {@link ToolError} → handler-emitted envelope with the
+     *    custom code; anything else → `unexpected_error`.
+     *
+     * @param argv - CLI tokens, typically `process.argv.slice(2)`.
+     * @returns Never — the process exits via `jsonOutput`.
+     */
+    run(argv: string[]): Promise<never>;
+    /**
+     * Pre-flight checks for a subcommand registration. Called by
+     * {@link Tool.subcommand}; throws synchronously on any violation.
+     *
+     * @param spec - The {@link SubcommandSpec} to validate.
+     * @throws `RangeError` for reserved-name collision or duplicate registration.
+     * @throws `TypeError` when `input` is missing.
+     */
+    private validateRegistration;
+    /**
+     * Handle the auto-registered `schema` and `help` subcommands. Returns the
+     * success envelope for those names, or `null` to signal the caller should
+     * fall through to user-registered dispatch.
+     *
+     * @param name - The parsed subcommand name.
+     * @returns A success envelope for `schema`/`help`, or `null` otherwise.
+     */
+    private dispatchBuiltin;
+    /**
+     * Handle empty argv and unregistered-subcommand cases. Returns the
+     * `unknown_subcommand` envelope (carrying the help listing for LLM
+     * self-correction) when applicable, or `null` when the subcommand is
+     * registered and should proceed.
+     *
+     * @param name - The parsed subcommand name.
+     * @returns An `unknown_subcommand` envelope, or `null` if the name is registered.
+     */
+    private rejectUnknown;
+    /**
+     * Execute a registered subcommand: validate input → `await` handler →
+     * stamp `ok: true` → validate output. Returns whichever envelope the
+     * pipeline produced (success or one of the validation errors).
+     *
+     * Preconditions: `name` must be a registered subcommand name. Callers
+     * should run {@link Tool.rejectUnknown} first.
+     *
+     * @param name - The subcommand to execute.
+     * @param parsed - Raw parsed args from {@link parseArgs}.
+     * @returns A success envelope or a typed error envelope.
+     */
+    private runSubcommand;
+    /**
+     * Programmatic entry point — runs a subcommand in-process without CLI
+     * arg parsing or `process.exit`. Identical validation pipeline to
+     * {@link Tool.run}, but accepts a plain object instead of argv tokens.
+     *
+     * @param subcommand - The subcommand name to dispatch.
+     * @param args - Input data as a plain object (bypasses CLI parsing).
+     * @returns The output envelope (success or error).
+     *
+     * Unlike `run()`, this method does NOT promote global flags (e.g. `--path`)
+     * into subcommand args. Callers must pass the full args object directly.
+     * Also, stderr output from handlers is not capturable — spawn the tool
+     * as a subprocess in tests that need to assert on stderr content.
+     */
+    invoke(subcommand: string, args?: Record<string, unknown>): Promise<ToolOutput>;
+    private validateOutput;
+}
+//# sourceMappingURL=tool-class.d.ts.map

package/dist/tool-class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-class.d.ts","sourceRoot":"","sources":["../src/tool-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,OAAO,KAAK,EAAc,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AASzD;;;;;;;;;;GAUG;AACH,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IAExD;;OAEG;gBACS,IAAI,EAAE,QAAQ;IAI1B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAM5F;;;;;;;;;;;;;OAaG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;IAczC;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;;;;;;;OAWG;YACW,aAAa;IAkB3B;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA2BzF,OAAO,CAAC,cAAc;CA4BvB"}

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * types.ts — Public interfaces for the code-first-agents Tool base class.
+ *
+ * Kept pure: no imports beyond `zod`, no runtime logic. Consumers of the
+ * `Tool` class type their code against these.
+ *
+ * @module code-first-agents-tool/types
+ */
+import type { z } from "zod";
+/** Metadata describing the tool itself. Used in help output. */
+export interface ToolMeta {
+    /** Tool identifier (usually matches the filename stem). */
+    name: string;
+    /** One-line human description shown in help output. */
+    description: string;
+}
+/**
+ * Raw CLI args after parsing. Flags are `--key value` pairs; bare `--flag`
+ * (with no following value) resolves to `true`. Positional args are any
+ * tokens that don't start with `--`.
+ */
+export interface ParsedArgs {
+    /** Flag key → value mapping. Last-one-wins on repeated keys. */
+    flags: Record<string, string | true>;
+    /** Positional (non-flag) tokens in order. */
+    positional: string[];
+}
+/**
+ * What a handler is expected to return: the output shape **without** `ok`.
+ * The base class stamps `ok: true` onto the result before output validation,
+ * so handlers stay focused on `message` + business data. This also avoids
+ * TypeScript widening `ok: true` to `boolean` in object-literal returns.
+ */
+export type HandlerReturn<O extends z.ZodTypeAny> = Omit<z.infer<O>, "ok">;
+/**
+ * A registered subcommand spec. Both `input` and `output` Zod schemas are
+ * required — they validate CLI args before the handler runs and the
+ * handler's return value before emit.
+ *
+ * @typeParam I - Input Zod schema type
+ * @typeParam O - Output Zod schema type
+ */
+export interface SubcommandSpec<I extends z.ZodTypeAny, O extends z.ZodTypeAny> {
+    /** Subcommand name as it appears on the CLI (e.g. "classify"). */
+    name: string;
+    /** One-line description shown in help output. */
+    description: string;
+    /**
+     * Zod schema for the validated flags + positional args. Positional args
+     * are exposed under a reserved `_` key when present. Use `.strict()` to
+     * reject unknown flags loudly.
+     *
+     * **Sync only:** the base class uses `safeParse` (not `safeParseAsync`).
+     * Schemas with `.refine(async ...)` or `.transform(async ...)` will cause
+     * a hard runtime throw at dispatch time (caught by the outer `unexpected_error`
+     * envelope, but with a cryptic message). Use synchronous validators only.
+     */
+    input: I;
+    /**
+     * Zod schema for the full output envelope (including `ok: z.literal(true)`
+     * and `message: z.string()`). Use the level helpers `l1Output` / `l2Output`
+     * / `l3Output` to get the envelope baked in, or pass a raw `z.object`.
+     * The handler returns everything **except** `ok`; the base class adds it.
+     *
+     * **Sync only:** same constraint as `input` — no async transforms or refinements.
+     */
+    output: O;
+    /**
+     * Business logic. Receives the validated, typed input. Returns the output
+     * shape **without** `ok` — the base class adds `ok: true` before validating
+     * against the output schema. May return a plain value or a Promise.
+     */
+    handler: (args: z.infer<I>) => HandlerReturn<O> | Promise<HandlerReturn<O>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACrC,6CAA6C;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAE3E;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU;IAC5E,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;OASG;IACH,KAAK,EAAE,CAAC,CAAC;IACT;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC,CAAC;IACV;;;;OAIG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7E"}

package/dist/utils.d.ts

@@ -0,0 +1,20 @@
+/** Standard JSON envelope for all tool stdout output. */
+export type ToolOutput = {
+    ok: boolean;
+    message: string;
+    [key: string]: unknown;
+};
+/**
+ * Print a {@link ToolOutput} as JSON to stdout and terminate with exit code 0.
+ * @param data - The tool output envelope to serialize.
+ * @returns Never — the process exits.
+ */
+export declare function jsonOutput(data: ToolOutput): never;
+/**
+ * Extract a human-readable message from an unknown thrown value. Preserves
+ * the `Error.message` when available; otherwise coerces via `String(...)`.
+ * @param err - The caught value (Error instance, string, null, etc.).
+ * @returns A non-undefined string suitable for envelope `message` / log output.
+ */
+export declare function stringifyError(err: unknown): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,KAAK,CAIlD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEnD"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@code-first-agents/tool",
+  "version": "0.1.0",
+  "description": "Code-first agent tool definitions with Zod schemas",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beogip/code-first-agents-tool.git"
+  },
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --format esm --target node --packages external && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check --write .",
+    "prepare": "test -d .git && lefthook install || true",
+    "prepublishOnly": "bun run build"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "^4.0.0",
+    "@biomejs/biome": "latest",
+    "bun-types": "latest",
+    "lefthook": "latest",
+    "semantic-release": "latest",
+    "@semantic-release/changelog": "latest",
+    "@semantic-release/git": "latest",
+    "@semantic-release/github": "latest",
+    "@semantic-release/npm": "latest",
+    "typescript": "latest"
+  }
+}