feat: programmatic entry point for generate, check and build

[PhilDL]

Closes #153.

import { generate, check, build } from "balade" runs the three commands from a script or a CI job without a terminal.

What changed

• src/library.ts — a second root beside cli.ts: generate, check, build as promises, with Effect variants (generateWalkthrough, checkWalkthrough, buildWalkthrough) and one exported liveLayer (Node services, process executor, Pi author adapter, context resolver — no terminal, browser or presence). The layer is provided per call, so a finished call leaves no handle open and a script exits on its own.
• No prompts. resolveAgentModel (agent/model.ts) matches an explicit { providerId, modelId } or the saved preference and fails typed — AgentModelUnresolved listing the available models, or NoProviderAuthenticated — never logging in or rewriting the preference. An existing same-head walkthrough fails ExistingWalkthroughUndecided naming the files; force: true replaces it, keeping the .superseded copy. PullTargetInvalid and PresetUnknown cover the other two pre-flight refusals. Local checks fail before the pull-request head is fetched.
• headInstructions defaults to "omit-changed"; "trust-changed" is the explicit opt-in (threat model updated).
• onProgress receives the pipeline's GenerationProgress events unfiltered; the test replays them through the CLI's terminal renderer.
• Rejections are the tagged errors themselves (_tag, fields, instanceof) with the CLI's sentence attached as message at the library boundary. The result is the CLI's GenerationResult plus the pull-request notices the command prints as warnings.
• Packaging — package.json gains an exports map; the build emits declarations. One explicit return type in pi/inspection.ts keeps Pi's typebox parameter types out of the .d.ts.
• Tests — test/library.test.ts runs the library through Pi's faux author on a real fixture clone (default policy → refused replacement → forced replacement, model resolution, promise rejection, check and build). The Pi harness moves to test/support/pi.ts, shared with generate.test.ts. The architecture test learns the second root and asserts nothing imports either entry. The npm smoke test type-checks and runs a consumer against the packed tarball, including that the process exits.
• CLI generate/check/build are untouched apart from reading the default output directory from a shared constant; existing CLI tests pass without edits.

Why the CLI is not a literal wrapper over generate()

Its replace prompt and model picker sit between the pre-flight and the paid turn, and the library refuses prompts. Both compose the same functions (parsePrTarget, resolvePullHead, inspectExistingWalkthroughs, planSupersession, runGeneration); the CLI's interactive glue stays in commands/generate/index.ts. Recorded in DECISIONS.md, along with the pkg.pr.new --previewVersion trigger this creates (workflow left alone).

Verified at the real seam

Against this repository with the built dist/library.js: a wrong model id rejects AgentModelUnresolved in ~1s listing the authenticated models, check returns the report for an existing walkthrough, and the process exits without process.exit.

Not exercised here: a paid generate() end to end — the faux author covers the pipeline; the model call itself is the same code path the CLI runs.

https://claude.ai/code/session_01QiAQotDRMwQigFYV9NXv5i

[pkg-pr-new]

npx https://pkg.pr.new/basaltbytes/balade@154

commit: d9e13b9