refactor(surface,cli,serve): Zod-Core-Out vertical slice for surface (#114)

[stackbilt-admin]

Summary

• Mirrors the blast Core-Out refactor (refactor(blast,cli,serve): Zod-Core-Out vertical slice (#109) #110) on @stackbilt/surface: SurfaceInputSchema + SurfaceOutputSchema are now the authoritative contract, analyze(input) composes extractSurface, and charter_surface joins charter_blast as an MCP tool in charter serve.
• Direct unblocker for feat(adf): auto-populate context modules from blast/surface/classify — reduce LM-agent cold-boot token cost #113 (repo-brief RFC). The brief's Surface section consumes analyze() output — without Zod-validated schemas the brief shape would reshape on every surface primitive refactor.
• OSS additive-only: existing extractSurface / extractRoutes / extractSchema / formatSurfaceMarkdown exports preserved. Route / SchemaTable / SchemaColumn become z.infer<> aliases of their schemas — structurally identical to the prior interfaces, no consumer breakage.

Changes

@stackbilt/surface (additive)

• Add zod ^3.24.1 runtime dependency
• Export RouteSchema, SchemaTableSchema, SchemaColumnSchema, SurfaceInputSchema, SurfaceOutputSchema
• Export DEFAULT_SURFACE_EXTENSIONS and DEFAULT_SURFACE_IGNORE_DIRS — shared between schema defaults and extractSurface fallback, same DEFAULT_MAX_DEPTH pattern as blast
• Add analyze(input: SurfaceInput): SurfaceOutput — the Core-Out entry point for CLI + MCP adapters
• README: "zero runtime dependencies" claim removed; programmatic example updated to lead with analyze()

@stackbilt/cli (additive)

• commands/surface.ts — argv routed through SurfaceInputSchema.parse, ZodError mapped to CLIError (same shape as blast's CLI adapter)
• commands/serve.ts — charter_surface MCP tool registered following the charter_blast pattern. Supports format: "json" | "markdown" input so agents can ask for a pre-digested summary instead of the full structured payload.

Decisions locked per #114

1. Zod → JSON-schema path: pass the raw shape directly to server.registerTool, no new library
2. Schema location: @stackbilt/surface (Zod becomes a runtime dep — programmatic consumers need the authoritative schema from the package boundary)
3. Tests: structural assertions via SurfaceOutputSchema.parse on fixtures, no byte-identical snapshots
4. Defaults as shared constants referenced by both schema .default() and primitive fallback

Acceptance criteria (#114)

• @stackbilt/surface exports SurfaceInputSchema, SurfaceOutputSchema, SurfaceInput, SurfaceOutput, analyze
• Existing extractSurface, extractRoutes, extractSchema, formatSurfaceMarkdown exports preserved
• charter surface <root> CLI output structurally equivalent to current behavior
• charter serve registers charter_surface; tools/list surfaces the JSON schema with per-field .describe() strings
• SurfaceOutputSchema.parse(analyze(...)) succeeds on a representative fixture with both routes and D1 tables
• packages/surface/package.json lists zod as a dependency, not devDependency
• Unit tests cover schema validation + analyze via synthetic fixtures
• No removal or rename of existing public API

Test plan

• pnpm build — clean (no TS errors)
• pnpm test — 37 files / 431 tests passing
• CI: typecheck + test on the PR branch
• Manual: node packages/cli/dist/bin.js surface on the Charter repo itself — confirm text output unchanged
• Manual: node packages/cli/dist/bin.js serve + MCP tools/list — confirm charter_surface appears with schema + descriptions

Related

• Closes refactor(surface,cli): Zod-Core-Out vertical slice for surface #114
• Unblocks feat(adf): auto-populate context modules from blast/surface/classify — reduce LM-agent cold-boot token cost #113 (repo-brief RFC — this was the last prerequisite)
• Follows refactor(blast,cli,serve): Zod-Core-Out vertical slice (#109) #110 (blast Core-Out) as the second vertical slice of the refactor(blast,cli,serve): Zod-Core-Out architecture — vertical slice for blast #109 Zod-Core-Out migration

🤖 Generated with Claude Code