@zerotal/arch 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog — @zerotal/arch
+
+All notable changes to this package are documented here. The format is
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**Maturity: beta.** The API is close to final and breaking changes are rare, called out
+here with migration steps — but a minor release may still contain one.
+
+## [1.7.0] — 2026-08-16
+
+### Added
+
+- **The agent surface.** An MCP server exposing what the framework already knows about an
+  app: `app_info`, `api_surface`, `search_docs`, `routes`, `schema`, `logs`, `last_error`,
+  `baselines` and `doctor`. Every tool is read-only and publishes an `outputSchema`.
+- **`zt arch:install` / `zt arch:update`.** Writes `.mcp.json`, `AGENTS.md` and a
+  `CLAUDE.md` shim, detecting Cursor and VS Code configs alongside. Every generated region
+  is marker-fenced, so re-running preserves anything written around it. `--dry` shows what
+  would change.
+- **`zt arch:probe <topic>`.** Prints one JSON report — `doctor`, `routes`, `schema` or
+  `app-info` — for the tools that need a booted app.
+- **Dual-era MCP.** Serves the stateless `2026-07-28` revision, including the mandatory
+  `server/discover`, and the `initialize` handshake of `2025-11-25` and earlier. The era is
+  selected per request.
+- **A vendored documentation corpus.** The framework's hand-written pages ship inside this
+  package, so `search_docs` is version-matched by construction — no embeddings, no hosted
+  API, and no way to answer from documentation for a version the app is not running.
+- **A doctor check** reporting whether the MCP server is actually registered anywhere. A
+  project that installed the package and never ran `arch:install` has an agent surface
+  connected to nothing, which looks exactly like it working.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+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,67 @@
+# @zerotal/arch
+
+**Maturity: beta.** The API is close to final and breaking changes are rare, called out
+in release notes with migration steps — but a minor release may still contain one. See
+the [support policy](https://zerotal.dev/docs/support-policy#maturity-levels).
+
+The Zerotal agent surface: an MCP server that hands a coding agent the framework's
+machine-readable truth about your app.
+
+Not a documentation search over prose about an API — the API itself. Zerotal commits an
+`api-surface.md` per package holding every export's exact TypeScript signature,
+regenerated and diffed by CI on every change. `zt doctor` already returns structured
+findings with a fix attached to each. The router knows its routes and the ORM knows its
+columns. This package exposes all of it over the protocol agents speak.
+
+## Install
+
+```bash
+bun add -d @zerotal/arch
+```
+
+```typescript
+// bootstrap/providers.ts
+import { ArchProvider } from "@zerotal/arch";
+
+export default [DatabaseProvider, ArchProvider];
+```
+
+```bash
+bun zt arch:install     # writes .mcp.json, AGENTS.md and a CLAUDE.md shim
+```
+
+Re-running is safe: generated regions are fenced with markers and only those regions are
+ever rewritten.
+
+## Tools
+
+| Tool                  | Answers                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `app_info`            | Bun version, boot mode, providers, and the version and maturity of every installed `@zerotal` package. |
+| `api_surface`         | Every export of a package with its full signature.                                                     |
+| `search_docs`         | The framework docs for the version installed here.                                                     |
+| `routes`              | The routes actually registered, with their names.                                                      |
+| `schema`              | Tables, columns, indexes — what the models declare.                                                    |
+| `logs` / `last_error` | The app's own structured trail.                                                                        |
+| `baselines`           | The quality ratchets and the commands that check them.                                                 |
+| `doctor`              | Every health check, with the fix beside each finding.                                                  |
+
+All read-only. All publish an `outputSchema`.
+
+## How it runs
+
+The server is a bin that **never boots your application**. MCP's stdio transport forbids
+writing anything to stdout that is not a protocol message, and a booted app prints. The
+tools that need an app spawn one per call instead — which also means every answer
+describes the code as it is now, not as it was when a long-lived server started.
+
+It speaks both eras of MCP: the stateless `2026-07-28` revision, including the mandatory
+`server/discover`, and the `initialize` handshake that shipping clients still open with.
+
+## Documentation
+
+<https://zerotal.dev/docs/arch>
+
+## License
+
+MIT

package/api-surface.md

@@ -0,0 +1,283 @@
+# @zerotal/arch — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class ArchError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): ArchError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ArchProvider = {
+  new (app: Application): ArchProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly []
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class NoProjectRootError = {
+  new (dir: string): NoProjectRootError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+const BLOCK_END = '<!-- zerotal:arch:end -->'
+
+const BLOCK_START = '<!-- zerotal:arch:start -->'
+
+const PROBE_TOPICS = readonly ['doctor', 'routes', 'schema', 'app-info']
+
+const SERVER_ENTRY_PATH = 'node_modules/@zerotal/arch/src/bin/mcp.ts'
+
+function agentsPreamble = () => string
+
+function applyBlock = (existing: string | undefined, content: string, preamble?: string) => BlockOutcome
+
+function applyMcpConfig = (existing: string | undefined, name: string, target: McpTarget) => ConfigOutcome
+
+function ArchConfig = (options?: Partial<ArchConfigShape>) => ArchConfigShape
+
+function archTools = (ctx: ToolContext) => ArchTool[]
+
+function buildGuidelines = (options: GuidelineOptions) => string
+
+function claudeShim = () => string
+
+function detectAgents = (root: string) => Promise<Detected>
+
+function fence = (content: string) => string
+
+function findApp = (start: string) => Promise<{    root: string;    entry: string;} | undefined>
+
+function isProbeTopic = (value: string) => value is ProbeTopic
+
+function probe = (topic: ProbeTopic, app: Application) => Promise<unknown>
+
+function serverEntry = () => Record<string, unknown>
+
+function spawnProbe = (options?: SpawnProbeOptions) => ProbeRunner
+
+function vendoredDocsDir = () => string
+
+interface AppInfo = {
+  appEnv: string
+  bun: string
+  environment: string
+  packages: InstalledPackage[]
+  providers: string[]
+  url?: string
+  webSocketPaths: string[]
+}
+
+interface ArchConfigShape = {
+  agentsFile: boolean
+  claudeFile: boolean
+  mcpConfig: boolean
+  mcpConfigPath: string
+  serverName: string
+}
+
+interface Detected = {
+  agents: string[]
+  targets: McpTarget[]
+}
+
+interface DoctorFinding = {
+  fix?: string
+  id: string
+  label: string
+  message: string
+  status: 'ok' | 'warn' | 'fail'
+}
+
+interface DoctorReport = {
+  counts: {    ok: number;    warn: number;    fail: number;    total: number;}
+  findings: DoctorFinding[]
+  healthy: boolean
+}
+
+interface GuidelineOptions = {
+  packages: string[]
+  serverName: string
+}
+
+interface InstalledPackage = {
+  maturity?: string
+  name: string
+  version: string
+}
+
+interface McpTarget = {
+  client: string
+  key: 'mcpServers' | 'servers'
+  path: string
+}
+
+interface ProbeRunner = {
+  run: (topic: ProbeTopic, signal: AbortSignal) => Promise<ProbeResult>
+}
+
+interface RouteEntry = {
+  action: string
+  controller: string
+  domain?: string
+  method: string
+  middleware: string[]
+  name?: string
+  path: string
+}
+
+interface RouteReport = {
+  routes: RouteEntry[]
+  total: number
+}
+
+interface SchemaColumn = {
+  indexed: boolean
+  name: string
+  nullable: boolean
+  primary: boolean
+  type: string
+  unique: boolean
+}
+
+interface SchemaModel = {
+  columns: SchemaColumn[]
+  primaryKey: string
+  softDeletes: boolean
+  table: string
+  timestamps: boolean
+}
+
+interface SchemaReport = {
+  models: SchemaModel[]
+  note?: string
+  total: number
+}
+
+interface SpawnProbeOptions = {
+  cwd?: string
+  timeoutMs?: number
+}
+
+interface ToolContext = {
+  docsDir: string
+  probe: ProbeRunner
+  root: string
+}
+
+type BlockOutcome = {    status: 'created';    text: string;} | {    status: 'updated';    text: string;} | {    status: 'unchanged';    text: string;} | {    status: 'conflict';    reason: string;}
+
+type ConfigOutcome = {    status: 'created' | 'updated' | 'unchanged';    text: string;} | {    status: 'conflict';    reason: string;}
+
+type ProbeResult = {    ok: true;    data: unknown;} | {    ok: false;    message: string;}
+
+type ProbeTopic = 'doctor' | 'routes' | 'schema' | 'app-info'
+
+## ./mcp  `(./src/mcp/index.ts)`
+
+class McpServer = {
+  new (options: McpServerOptions): McpServer
+  handle: (request: JsonRpcRequest) => Promise<JsonRpcResponse | undefined>
+}
+
+const LEGACY_VERSIONS = readonly ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']
+
+const Meta = {    readonly PROTOCOL_VERSION: 'io.modelcontextprotocol/protocolVersion';    readonly CLIENT_INFO: 'io.modelcontextprotocol/clientInfo';    readonly CLIENT_CAPABILITIES: 'io.modelcontextprotocol/clientCapabilities';    readonly SERVER_INFO: 'io.modelcontextprotocol/serverInfo';}
+
+const MODERN_VERSION = '2026-07-28'
+
+const RpcError = {    readonly PARSE: -32700;    readonly INVALID_REQUEST: -32600;    readonly METHOD_NOT_FOUND: -32601;    readonly INVALID_PARAMS: -32602;    readonly INTERNAL: -32603;    readonly UNSUPPORTED_PROTOCOL_VERSION: -32022;}
+
+const SUPPORTED_VERSIONS = readonly ['2026-07-28', '2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']
+
+function decodeFrame = (line: string) => DecodedFrame | undefined
+
+function encodeFrame = (message: JsonRpcResponse) => string
+
+function failure = (id: JsonRpcId | null, code: number, message: string, data?: unknown) => JsonRpcFailure
+
+function serveStdio = (options: StdioOptions) => Promise<void>
+
+function success = (id: JsonRpcId, result: Record<string, unknown>) => JsonRpcResponse
+
+interface ArchTool = {
+  description: string
+  inputSchema: JsonSchema
+  name: string
+  outputSchema: JsonSchema
+  run: (args: Record<string, unknown>, signal: AbortSignal) => Promise<ToolOutcome>
+  title: string
+}
+
+interface JsonRpcFailure = {
+  error: {    code: number;    message: string;    data?: unknown;}
+  id: JsonRpcId | null
+  jsonrpc: '2.0'
+}
+
+interface JsonRpcRequest = {
+  id?: JsonRpcId
+  jsonrpc: '2.0'
+  method: string
+  params?: Record<string, unknown>
+}
+
+interface JsonRpcSuccess = {
+  id: JsonRpcId
+  jsonrpc: '2.0'
+  result: Record<string, unknown>
+}
+
+interface McpServerOptions = {
+  identity: ServerIdentity
+  tools: readonly ArchTool[]
+}
+
+interface ServerIdentity = {
+  name: string
+  title: string
+  version: string
+}
+
+interface StdioOptions = {
+  input?: ReadableStream<Uint8Array<ArrayBufferLike>>
+  log?: (message: string) => void
+  server: McpServer
+  write?: (frame: string) => void
+}
+
+interface ToolOutcome = {
+  data?: unknown
+  failed?: boolean
+  text: string
+}
+
+type DecodedFrame = {    ok: true;    request: JsonRpcRequest;} | {    ok: false;    failure: JsonRpcFailure;}
+
+type Era = 'modern' | 'legacy'
+
+type JsonRpcId = string | number
+
+type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure
+
+type JsonSchema = {    [x: string]: unknown;}