[#1] feat: extract Tool class + lib/tool/ modules into src/

[beogip]

Summary

Extracts the Tool base class and 7 supporting modules from kael.factory/lib/tool/ into this standalone package's src/, establishing the core of the code-first-agents-tool library.

• Copy 7 modules verbatim: types, args, json-schema, output-helpers, introspection, envelopes, tool-class
• Create lean src/utils.ts with only the 3 symbols needed (ToolOutput, jsonOutput, stringifyError)
• Adjust ../utils.ts imports to ./utils.ts in envelopes.ts and tool-class.ts
• Replace placeholder src/index.ts with barrel re-exports of the full public API
• Add zod@^4.0.0 as production dependency
• Update package.json with correct name, exports, and main fields
• Update tsconfig.json with allowImportingTsExtensions and noEmit
• Add 15 smoke tests covering Tool construction, invoke dispatch, error envelopes, and output helpers
• Fix all stale JSDoc comments referencing kael.factory paths

Closes #3

Plan level: lean (8/13) | Depth: medium

Files changed

Action	Path	Purpose
create	src/types.ts	Tool type definitions
create	src/args.ts	CLI argv parsing + validation
create	src/json-schema.ts	Safe Zod→JSON Schema converter
create	src/output-helpers.ts	L1/L2/L3 output schema composers
create	src/introspection.ts	Schema/help payload builders
create	src/envelopes.ts	Error envelope factories
create	src/tool-class.ts	Tool orchestrator class
create	src/utils.ts	Lean utils (ToolOutput, jsonOutput, stringifyError)
modify	src/index.ts	Barrel re-exports
modify	package.json	Name, exports, zod dependency
modify	tsconfig.json	allowImportingTsExtensions, noEmit
modify	tests/index.test.ts	15 smoke tests for new API
create	docs/specs/issue-3-*.md	Plan artifact

Verification

• bunx tsc --noEmit — zero errors
• bun test — 15/15 pass
• bunx biome check — clean
• grep -r '../lib/' src/ — zero matches (no kael.factory paths)

[greptile-apps]

Greptile Summary

This PR extracts the Tool base class and 7 supporting modules from an upstream monorepo into this standalone @code-first-agents/tool package, establishing the full core library in src/.

• 7 source modules added (types, args, json-schema, output-helpers, introspection, envelopes, tool-class) plus a lean utils.ts; all ../utils import paths are correctly re-pointed to ./utils.
• package.json renamed to @code-first-agents/tool with zod@^4.0.0 as a production dependency; src/index.ts becomes a barrel re-exporting the full public API.
• 15 smoke tests cover Tool construction, subcommand dispatch via invoke, error envelopes, and output helpers; all pass.

Confidence Score: 5/5

Safe to merge — the core dispatch pipeline, error envelopes, and schema validation are all correct; the only findings are defensive hardening suggestions for the output-helper spread order.

The extraction is clean: imports are correctly re-pointed, the Zod v4 API is used correctly, and all 15 smoke tests pass. The spread-order issue in the output helpers only manifests when a caller passes a key that collides with an envelope field, and would surface immediately as a schema_violation at runtime.

src/output-helpers.ts — spread order in l1Output, l2Output, and l3Output should be reviewed.

Important Files Changed

Filename	Overview
src/tool-class.ts	Core Tool orchestrator with invoke/run dispatch pipeline. Handler-execution block is duplicated between invoke and runSubcommand (flagged previously). Logic is otherwise sound.
src/output-helpers.ts	Level-specific output schema composers. Spread order places ...fields last, allowing user-provided keys to silently override the required envelope fields.
src/args.ts	Pure argv parser with global-flag override for reserved subcommands. Logic is correct and well-documented.
src/envelopes.ts	Error envelope factories covering all error codes. Discriminated union is well-typed; ToolError correctly extends Error.
tsconfig.json	Added allowImportingTsExtensions + noEmit. The noEmit:true/types:./dist/index.d.ts conflict is acknowledged via TODO comment but leaves typed consumers broken until a tsconfig.build.json is added.
package.json	Renamed to @code-first-agents/tool, added zod@^4.0.0. The exports map references dist/index.d.ts which won't be produced by the current build setup.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Tool.run(argv)"] --> B["parseArgs(argv)"]
    B --> C{"dispatchBuiltin?"}
    C -- "schema/help" --> D["jsonOutput(builtin)"]
    C -- "null" --> E{"rejectUnknown?"}
    E -- "unknown_subcommand" --> F["jsonOutput(error)"]
    E -- "null" --> G["runSubcommand(name, parsed)"]
    G --> H["validateInput(parsed, spec.input)"]
    H -- "fail" --> I["inputValidationErrorEnvelope"]
    H -- "ok" --> J["await spec.handler(data)"]
    J -- "throws ToolError" --> K["toolErrorEnvelope"]
    J -- "throws Error" --> L["unexpectedErrorEnvelope"]
    J -- "plain object" --> N["stamp ok: true"]
    N --> O["spec.output.safeParse(result)"]
    O -- "fail" --> P["schemaViolationEnvelope"]
    O -- "pass" --> Q["jsonOutput(success)"]

Loading

_{Reviews (3): Last reviewed commit: "fix: update package name in JSDoc + biom..." | Re-trigger Greptile}

[beogip]

@greptile