feat: implement @code-first-agents/tool package

[beogip]

Summary

Implements the @code-first-agents/tool package — a standalone, installable library that provides the full Code-First Agents tool contract (named params, JSON stdout, L1/L2/L3 output levels, self-describing schema).

Closes #1

What's included

• Package structure — package.json, tsconfig.json, src/, tests/ ([#1] feat: set up package structure #2)
• Tool class extraction — Tool base class + lib/tool/ modules ported from kael.factory into src/ ([#1] feat: extract Tool class + lib/tool/ modules into src/ #3)
• Bundled utils — stringifyError, jsonOutput, ToolOutput type — zero dependency on kael.factory ([#1] feat: bundle required utils (stringifyError, jsonOutput, ToolOutput) #4)
• Public API barrel — exports Tool, ToolError, l1Output, l2Output, l3Output, parseArgs, validateInput + type exports ([#1] feat: export public API via barrel file #5)
• Test suite — Vitest setup with ported Tool.ts tests ([#1] test: set up test suite and port Tool.ts tests #6)
• Build + publish pipeline — Bun build, CI workflow, npm publish config ([#1] chore: configure build + publish pipeline #7)

Files changed

28 files changed (+2653 -246)

Key additions:

• src/tool-class.ts — Core Tool base class with subcommand dispatch, Zod validation, output helpers
• src/args.ts — Argument parsing
• src/envelopes.ts — JSON output envelope helpers
• src/output-helpers.ts — L1/L2/L3 output level functions
• src/introspection.ts — Auto-generated schema/help
• src/types.ts — Type definitions (HandlerReturn, ParsedArgs, SubcommandSpec, ToolMeta)
• tests/ — Full test suite (args, index, utils)

Test plan

• All sub-issue PRs (feat: set up package structure #8–[#1] chore: configure build + publish pipeline #13) reviewed and merged into this branch
• bun test passes all tests
• bun run build produces valid dist output
• Package is publish-ready with correct metadata

[greptile-apps]

Greptile Summary

This PR introduces the @code-first-agents/tool package — a standalone TypeScript library implementing the code-first agents tool contract: subcommand dispatch, Zod-validated input/output, structured JSON stdout envelopes, and auto-generated schema/help introspection.

• src/tool-class.ts — Core Tool orchestrator with run() (CLI) and invoke() (programmatic) entry points, plus a shared validateOutput pipeline used by both paths.
• src/envelopes.ts / src/output-helpers.ts — Typed error envelope factories and l1Output/l2Output/l3Output schema composers that enforce the envelope contract.
• .github/workflows/ci.yml — Splits CI into a ci job (lint, typecheck, test, build) and a release job (semantic-release on main pushes).

Confidence Score: 5/5

The implementation is safe to merge — logic is correct, test coverage is thorough, and both CLI and programmatic entry points share a single validated output pipeline.

The core dispatch, input/output validation, and error envelope logic are well-structured and fully exercised by the test suite. No new correctness issues were found in the changed source files.

.github/workflows/ci.yml — the release job configuration warrants a close look before the first automated publish runs.

Important Files Changed

Filename	Overview
src/tool-class.ts	Core orchestrator; clean separation between run() (CLI+exit) and invoke() (programmatic), shared validateOutput pipeline, correct 'ok' stripping guard and handler-return stamping.
src/envelopes.ts	All six error-envelope factories are well-typed and cover every error path; unexpectedErrorEnvelope correctly includes the stack trace in detail for debuggability.
src/args.ts	Pure arg-parsing logic with documented global-flag promotion, POSIX '--' sentinel, and last-one-wins flag semantics; validateInput correctly defers positional injection.
src/output-helpers.ts	l1/l2/l3Output composers correctly bake in ok: z.literal(true) and message: z.string(); overloads handle the no-extras case cleanly.
src/json-schema.ts	safeToJSONSchema correctly wraps z.toJSONSchema (Zod v4 API) in a try/catch, returning a discriminated result; known limitation about defaulted fields documented inline.
src/types.ts	Pure type file; HandlerReturn correctly uses Omit<z.infer, 'ok'> to match the 'framework adds ok' contract.
src/introspection.ts	buildSchemaOutput and buildHelpPayload both use fail-soft safeToJSONSchema per-subcommand, correctly preventing a single exotic schema from crashing the full introspection response.
.github/workflows/ci.yml	Release job correctly gates on main push and depends on ci; release step is missing NPM_TOKEN so npm publish will fail on every release run (previously flagged).
package.json	Package fields (name, exports, files, publishConfig, peerDependencies) are correct for a scoped npm package; prepare script guards against non-git installs.
tests/index.test.ts	Comprehensive test coverage for Tool construction, subcommand dispatch, error envelopes, ToolError, invoke() paths, and introspection; uses invoke() correctly to avoid process.exit.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Tool.run(argv)"] --> B["parseArgs(argv)"]
    B --> C{"dispatchBuiltin\nschema / help?"}
    C -->|"yes"| D["jsonOutput(builtin)\n→ process.exit(0)"]
    C -->|"null"| E{"rejectUnknown\nempty / unregistered?"}
    E -->|"yes"| F["jsonOutput(unknown_subcommand)\n→ process.exit(0)"]
    E -->|"null"| G["runSubcommand(name, parsed)"]
    G --> H["validateInput(parsed, spec.input)"]
    H -->|"fail"| I["inputValidationErrorEnvelope\n(+ input_schema for self-correction)"]
    H -->|"success"| J["await spec.handler(data)"]
    J --> K["validateOutput(name, result, spec)"]
    K -->|"not plain object"| L["nonObjectReturnEnvelope"]
    K -->|"safeParse fail"| M["schemaViolationEnvelope"]
    K -->|"'ok' stripped"| N["schemaViolationEnvelope\n(guided message)"]
    K -->|"success"| O["jsonOutput(data)\n→ process.exit(0)"]
    I --> O2["jsonOutput(error)\n→ process.exit(0)"]
    L --> O2
    M --> O2
    N --> O2
    A -->|"catch ToolError"| P["toolErrorEnvelope(err)"]
    A -->|"catch unknown"| Q["unexpectedErrorEnvelope(err)"]
    P --> O2
    Q --> O2

Loading

_{Reviews (2): Last reviewed commit: "refactor: extract validateOutput to dedu..." | Re-trigger Greptile}