callspec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marc H. Weiner
+
+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,170 @@
+<div align="center">
+  <picture>
+    <source srcset="assets/callspec-lockup-light.svg" media="(prefers-color-scheme: light)" />
+    <source srcset="assets/callspec-lockup-dark.svg" media="(prefers-color-scheme: dark)" />
+    <img src="assets/callspec-lockup-dark.svg" alt="callspec" />
+  </picture>
+
+  <p><strong>One registry. HTTP RPC, interactive docs, OpenAPI, MCP, and a typed client.</strong></p>
+</div>
+
+One `defineRegistry` powers HTTP RPC, OpenAPI, callsheet docs, MCP tools, and a typed client. Add a route once; it shows up everywhere.
+
+<p align="center">
+  <a href="assets/callsheet-chirp-demo.png">
+    <img src="assets/callsheet-chirp-demo.png" alt="callsheet home — Chirp demo API with Connect MCP panel showing Cursor config" width="920" />
+  </a>
+</p>
+
+<p align="center"><sub><strong>callsheet</strong> — built-in docs UI with a <strong>Connect MCP</strong> panel. Copy the endpoint and a ready-made config for Cursor, Claude, VS Code, Windsurf, or Pi.</sub></p>
+
+```typescript
+import {defineRegistry, defineRoute, mountRegistry, mountMcp, client} from 'callspec';
+import {predicates as p} from 'runtyp';
+
+export const api = defineRegistry({
+    getPipelines: defineRoute({
+        input: getPipelinesInput,
+        meta: {
+            summary: 'List pipelines',
+            description: 'Returns pipelines for a team.',
+            tags: ['pipelines'],
+        },
+        mcp: true,           // → MCP tools/list
+        handler: getPipelines,
+    }),
+});
+
+mountRegistry(app, api, {
+    contextResolver: getUserContext,
+    docs: {
+        openApi: {title: 'My API', version: '1.0.0'},
+        exposeUi: true,      // → /docs (callsheet + Connect MCP)
+        exposeOpenApi: true, // → /openapi.json
+    },
+});
+
+mountMcp(app, api, {path: '/mcp', contextResolver: getUserContext});
+```
+
+Try the demo locally: `npm run build && npm run dev:docs` → [http://127.0.0.1:3456/v1/docs](http://127.0.0.1:3456/v1/docs) (Chirp API sample; use `Bearer demo` for private tools).
+
+## Built-in MCP server
+
+No separate MCP process. No hand-maintained tool manifest. No stdio bridge.
+
+1. **Opt in per route** — `mcp: true` on any `defineRoute`. Input/output schemas come from the same runtyp preds as HTTP.
+2. **Mount once** — `mountMcp(app, api, { path: '/mcp' })` on the same Express app. Streamable HTTP at `/mcp`.
+3. **Connect from callsheet** — at `/docs`, the **Connect MCP** panel shows your endpoint and copy-paste configs for Cursor (`.cursor/mcp.json`), Claude Desktop, Claude Code CLI, VS Code, Windsurf, and Pi — including `Authorization` headers when you have private tools.
+
+```typescript
+searchRecent: defineRoute({
+    input: p.object({query: p.string()}),
+    meta: {summary: 'Search recent', description: '…', tags: ['tweets']},
+    access: 'private',
+    mcp: true,   // this route is now an MCP tool — same handler as POST /v1/searchRecent
+    handler: searchRecent,
+}),
+```
+
+Agents call the **same handlers** as your HTTP RPC. Auth uses the same `contextResolver` (e.g. `Authorization: Bearer …`). Public tools work without a token; private tools return 401 without one.
+
+## Why callspec
+
+| Surface | How you get it |
+|---------|----------------|
+| **HTTP RPC** | `POST /v1/<methodName>` |
+| **Interactive docs** | Built-in **callsheet** UI at `/docs` |
+| **OpenAPI 3.1** | `GET /openapi.json` from the same registry |
+| **MCP tools** | `mcp: true` on a route → `tools/list` + `tools/call` at `/mcp` |
+| **Typed client** | `client<API['searchLogs']>('searchLogs', input)` |
+
+No second schema. No duplicate handler layer. No separate MCP subprocess.
+
+## Batteries included
+
+### callsheet — interactive docs
+
+Minimal, fast docs UI baked into callspec. Browse routes, try RPCs, read OpenAPI, and **connect MCP clients** from the home page. Env-gated in production; flip on with:
+
+```typescript
+docs: {
+    openApi: {title: 'Logfox API', version: '1.0.0'},
+    exposeOpenApi: true,   // machine-readable spec
+    exposeUi: true,        // human-readable /docs + Connect MCP
+    openApiPath: '/openapi.json',
+    uiPath: '/docs',
+    callsheet: {
+        mcp: {
+            authHint: 'Use Authorization: Bearer <token> for private tools.',
+        },
+    },
+}
+```
+
+Toggle each surface independently — spec only, UI only, both, or neither (`docs: false`).
+
+### Auth
+
+- **`access: 'public'`** — no credentials required
+- **`access: 'private'`** (default) — 401 without `contextResolver` result
+- Team/role rules stay in your resolver `assert*` helpers
+
+Private gate runs **before** validation so unauthenticated callers never see field-level errors.
+
+### runtyp + OpenAPI
+
+Field `{ description }` on runtyp preds flows to JSON Schema → OpenAPI → callsheet → MCP `inputSchema`. Route-level `meta` (summary, tags) is callspec-only.
+
+## Client
+
+Fetch-only — works in the browser and in Node 18+ (global `fetch`). The `callspec/client` entry has no `http`, `https`, or Express imports, so it is safe in frontend bundles.
+
+**Browser or frontend bundler** — import the client subpath so you do not pull server code:
+
+```typescript
+import type {API} from '@logfoxai/my-service';   // InferRegistry<typeof api> from the service package
+import {client} from 'callspec/client';
+
+const logs = await client<API['searchLogs']>('searchLogs', {teamId}, {
+    endpoint: 'https://api.example.com/v1',
+    fetchOptions: {headers: {Authorization: `Bearer ${token}`}},
+});
+```
+
+**Service package** — export the API type once from your registry:
+
+```typescript
+import type {InferRegistry} from 'callspec';
+
+export const api = defineRegistry({ /* ... */ });
+export type API = InferRegistry<typeof api>;
+```
+
+Responses deserialize ISO date strings back to `Date` on read (`deserializeResponse`).
+
+## Development
+
+```bash
+npm run validate   # build server + callsheet UI, lint, test (incl. integration)
+npm run dev:docs   # Chirp demo API + callsheet at :3456/v1/docs
+```
+
+Integration tests spin up Express in-process and verify OpenAPI, `/docs`, auth, MCP schemas, and RPC end-to-end.
+
+## Package layout
+
+```
+src/
+  defineRoute.ts      # route definition + arity guard
+  defineRegistry.ts   # named route map
+  executeRoute.ts     # shared HTTP + MCP pipeline
+  mountRegistry.ts    # POST routes + openapi + callsheet
+  mountMcp.ts         # MCP on Express
+  mcpTools.ts         # tools/list schemas from runtyp
+  openapi.ts          # OpenAPI 3.1 emitter
+  client.ts           # typed fetch client
+  callsheet/          # built-in docs UI (bundled to dist/callsheet/ui)
+```
+
+Powered by [runtyp](https://github.com/logfoxai/runtyp) for validation.

package/assets/callspec-lockup-dark.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="248" height="66" viewBox="0 0 248 66" role="img" aria-label="callspec">
+  <rect x="4" y="9" width="44" height="44" rx="9" fill="#1a1a1a" stroke="#333" stroke-width="1"/>
+  <circle cx="26" cy="36" r="4" fill="#fafafa"/>
+  <path d="M26 32V24" stroke="#fafafa" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="26" cy="22.5" r="2.25" fill="#fafafa"/>
+  <path d="M22.5 38L16.1 41.2" stroke="#fafafa" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="15.2" cy="41.8" r="2.25" fill="#fafafa"/>
+  <path d="M29.5 38L35.9 41.2" stroke="#fafafa" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="36.8" cy="41.8" r="2.25" fill="#fafafa"/>
+  <text x="62" y="33" dominant-baseline="middle" font-family="ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="32" font-weight="600" letter-spacing="-0.02em" fill="#fafafa">callspec</text>
+</svg>

package/assets/callspec-lockup-light.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="248" height="66" viewBox="0 0 248 66" role="img" aria-label="callspec">
+  <rect x="4" y="9" width="44" height="44" rx="9" fill="none" stroke="#171717" stroke-width="2"/>
+  <circle cx="26" cy="36" r="4" fill="#171717"/>
+  <path d="M26 32V24" stroke="#171717" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="26" cy="22.5" r="2.25" fill="#171717"/>
+  <path d="M22.5 38L16.1 41.2" stroke="#171717" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="15.2" cy="41.8" r="2.25" fill="#171717"/>
+  <path d="M29.5 38L35.9 41.2" stroke="#171717" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="36.8" cy="41.8" r="2.25" fill="#171717"/>
+  <text x="62" y="33" dominant-baseline="middle" font-family="ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="32" font-weight="600" letter-spacing="-0.02em" fill="#171717">callspec</text>
+</svg>

package/assets/callspec-mark-dark.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48" role="img" aria-label="callspec">
+  <rect x="2" y="2" width="44" height="44" rx="9" fill="#1a1a1a" stroke="#333" stroke-width="1"/>
+  <circle cx="24" cy="27" r="4" fill="#fafafa"/>
+  <path d="M24 23V15" stroke="#fafafa" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="24" cy="13.5" r="2.25" fill="#fafafa"/>
+  <path d="M20.5 29L14.1 32.2" stroke="#fafafa" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="13.2" cy="32.8" r="2.25" fill="#fafafa"/>
+  <path d="M27.5 29L33.9 32.2" stroke="#fafafa" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="34.8" cy="32.8" r="2.25" fill="#fafafa"/>
+</svg>

package/assets/callspec-mark-light.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48" role="img" aria-label="callspec">
+  <rect x="2" y="2" width="44" height="44" rx="9" fill="none" stroke="#171717" stroke-width="2"/>
+  <circle cx="24" cy="27" r="4" fill="#171717"/>
+  <path d="M24 23V15" stroke="#171717" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="24" cy="13.5" r="2.25" fill="#171717"/>
+  <path d="M20.5 29L14.1 32.2" stroke="#171717" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="13.2" cy="32.8" r="2.25" fill="#171717"/>
+  <path d="M27.5 29L33.9 32.2" stroke="#171717" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="34.8" cy="32.8" r="2.25" fill="#171717"/>
+</svg>

package/assets/chirp/mark-dark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" role="img" aria-label="Chirp">
+  <rect width="64" height="64" rx="14" fill="#134e4a"/>
+  <circle cx="33" cy="31" r="12" fill="#fafafa"/>
+  <path fill="#fafafa" d="M19 21l-5 6 8 2 4-5z"/>
+  <circle cx="36.5" cy="26.5" r="2" fill="#171717"/>
+  <path fill="#fb923c" d="M45 28.5 51.5 31.5 45 34.5z"/>
+</svg>

package/assets/chirp/mark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" role="img" aria-label="Chirp">
+  <rect width="64" height="64" fill="#0f766e"/>
+  <circle cx="33" cy="31" r="12" fill="#f5f2eb"/>
+  <path fill="#f5f2eb" d="M19 21l-5 6 8 2 4-5z"/>
+  <circle cx="36.5" cy="26.5" r="2" fill="#171717"/>
+  <path fill="#f97316" d="M45 28.5 51.5 31.5 45 34.5z"/>
+</svg>

package/dist/callsheet/branding.d.ts

@@ -0,0 +1,33 @@
+export type CallsheetBranding = {
+    /** Display name; defaults to OpenAPI info.title */
+    name?: string;
+    /** Short welcome paragraph on the home page */
+    intro?: string;
+    /** Company or product website */
+    websiteUrl?: string;
+    /** Link label; defaults to hostname or "Learn more" */
+    websiteLabel?: string;
+    /** Logo URL (relative to docs mount or absolute) */
+    logoUrl?: string;
+    /** Dark-mode logo; falls back to logoUrl */
+    logoUrlDark?: string;
+    /** Optional srcset, e.g. "./brand/mark.png 1x, ./brand/mark@2x.png 2x" */
+    logoSrcSet?: string;
+    /** Display size in px. Default 80 */
+    logoSize?: number;
+};
+export type CallsheetMcp = {
+    /** MCP endpoint (absolute or relative). Default: sibling of docs at mcpPath */
+    url?: string;
+    /** Auth note shown when private MCP tools exist */
+    authHint?: string;
+};
+export type CallsheetConfig = {
+    specUrl: string;
+    rpcBase: string;
+    title?: string;
+    branding?: CallsheetBranding;
+    /** Relative path from docs to MCP endpoint. Default `../mcp` */
+    mcpPath?: string;
+    mcp?: CallsheetMcp;
+};

package/dist/callsheet/branding.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/callsheet/index.d.ts

@@ -0,0 +1,4 @@
+export { parseCallspecOpenApi } from './parseOpenApi';
+export type { CallsheetAccess, CallsheetRoute, CallsheetSpec } from './parseOpenApi';
+export { mountCallsheet, renderCallsheetPage } from './mountCallsheet';
+export type { MountCallsheetOptions, CallsheetConfig, CallsheetBranding, CallsheetMcp } from './mountCallsheet';

package/dist/callsheet/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCallsheetPage = exports.mountCallsheet = exports.parseCallspecOpenApi = void 0;
+var parseOpenApi_1 = require("./parseOpenApi");
+Object.defineProperty(exports, "parseCallspecOpenApi", { enumerable: true, get: function () { return parseOpenApi_1.parseCallspecOpenApi; } });
+var mountCallsheet_1 = require("./mountCallsheet");
+Object.defineProperty(exports, "mountCallsheet", { enumerable: true, get: function () { return mountCallsheet_1.mountCallsheet; } });
+Object.defineProperty(exports, "renderCallsheetPage", { enumerable: true, get: function () { return mountCallsheet_1.renderCallsheetPage; } });

package/dist/callsheet/mountCallsheet.d.ts

@@ -0,0 +1,22 @@
+import type { Router } from 'express';
+import type { CallsheetBranding, CallsheetConfig, CallsheetMcp } from './branding';
+export type { CallsheetBranding, CallsheetConfig, CallsheetMcp } from './branding';
+export type MountCallsheetOptions = {
+    /** Mount path for the UI. Default `/docs`. */
+    path?: string;
+    /** OpenAPI JSON URL for the UI to fetch. Default `../openapi.json`. */
+    specPath?: string;
+    /** RPC base for try-it requests. Default `..` (sibling of the docs path). */
+    rpcBase?: string;
+    /** Page title override. */
+    title?: string;
+    /** Whitelabel home page content */
+    branding?: CallsheetBranding;
+    /** Relative path from docs to MCP endpoint. Default `../mcp` */
+    mcpPath?: string;
+    mcp?: CallsheetMcp;
+    /** Directory of tenant logos/static files served at `{path}/brand/` */
+    brandAssetsDir?: string;
+};
+export declare function renderCallsheetPage(config: CallsheetConfig): string;
+export declare function mountCallsheet(router: Router, options?: MountCallsheetOptions): void;

package/dist/callsheet/mountCallsheet.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCallsheetPage = renderCallsheetPage;
+exports.mountCallsheet = mountCallsheet;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const express_1 = __importDefault(require("express"));
+const CONFIG_PLACEHOLDER = '<!--CALLSHEET_CONFIG-->';
+function uiDir() {
+    const candidates = [
+        path_1.default.join(__dirname, 'ui'),
+        path_1.default.resolve(__dirname, '../../dist/callsheet/ui'),
+        path_1.default.resolve(process.cwd(), 'dist/callsheet/ui'),
+    ];
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(path_1.default.join(candidate, 'index.html'))) {
+            return candidate;
+        }
+    }
+    throw new Error('callsheet UI assets missing — run `npm run build` in callspec');
+}
+function readIndexHtml() {
+    const file = path_1.default.join(uiDir(), 'index.html');
+    return fs_1.default.readFileSync(file, 'utf8');
+}
+function renderCallsheetPage(config) {
+    const html = readIndexHtml();
+    const script = `<script>window.__CALLSHEET__=${JSON.stringify(config)};</script>`;
+    if (html.includes(CONFIG_PLACEHOLDER)) {
+        return html.replace(CONFIG_PLACEHOLDER, script);
+    }
+    return html.replace('</head>', `${script}</head>`);
+}
+function mountCallsheet(router, options = {}) {
+    const mountPath = options.path ?? '/docs';
+    const mountPathWithSlash = mountPath.endsWith('/') ? mountPath : `${mountPath}/`;
+    const specUrl = options.specPath ?? '../openapi.json';
+    const rpcBase = options.rpcBase ?? '..';
+    const assetsDir = uiDir();
+    const servePage = (req, res) => {
+        if (!req.path.endsWith('/')) {
+            res.redirect(301, `${req.baseUrl}${mountPathWithSlash}`);
+            return;
+        }
+        res.type('html').send(renderCallsheetPage({
+            specUrl,
+            rpcBase,
+            title: options.title,
+            branding: options.branding,
+            mcpPath: options.mcpPath ?? '../mcp',
+            mcp: options.mcp,
+        }));
+    };
+    router.get(mountPath, servePage);
+    router.use(mountPathWithSlash, express_1.default.static(assetsDir, { index: false }));
+    if (options.brandAssetsDir && fs_1.default.existsSync(options.brandAssetsDir)) {
+        router.use(`${mountPathWithSlash}brand`, express_1.default.static(options.brandAssetsDir, { index: false }));
+    }
+}

package/dist/callsheet/parseOpenApi.d.ts

@@ -0,0 +1,17 @@
+export type CallsheetAccess = 'public' | 'private';
+export type CallsheetRoute = {
+    name: string;
+    summary: string;
+    description: string;
+    tags: string[];
+    access: CallsheetAccess;
+    mcp: boolean;
+    inputSchema: unknown;
+    outputSchema: unknown;
+};
+export type CallsheetSpec = {
+    title: string;
+    version: string;
+    routes: CallsheetRoute[];
+};
+export declare function parseCallspecOpenApi(doc: Record<string, unknown>): CallsheetSpec;

package/dist/callsheet/parseOpenApi.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCallspecOpenApi = parseCallspecOpenApi;
+function readAccess(operation) {
+    const ext = operation['x-callspec-access'];
+    if (ext === 'public' || ext === 'private')
+        return ext;
+    const security = operation.security;
+    if (Array.isArray(security) && security.length > 0)
+        return 'private';
+    return 'public';
+}
+function readMcp(operation) {
+    return operation['x-callspec-mcp'] === true;
+}
+function readJsonSchema(content) {
+    if (!content)
+        return { type: 'object' };
+    const appJson = content['application/json'];
+    if (!appJson || typeof appJson !== 'object')
+        return { type: 'object' };
+    return appJson.schema ?? { type: 'object' };
+}
+function parseCallspecOpenApi(doc) {
+    const info = doc.info;
+    const paths = doc.paths;
+    const routes = [];
+    if (paths) {
+        for (const [pathKey, methods] of Object.entries(paths)) {
+            const post = methods.post;
+            if (!post)
+                continue;
+            const name = post.operationId
+                ?? pathKey.replace(/^\//, '');
+            const requestBody = post.requestBody;
+            const content = requestBody?.content;
+            const responses = post.responses;
+            const ok = responses?.['200'];
+            const okContent = ok?.content;
+            routes.push({
+                name,
+                summary: post.summary ?? name,
+                description: post.description ?? '',
+                tags: Array.isArray(post.tags) ? post.tags.map(String) : [],
+                access: readAccess(post),
+                mcp: readMcp(post),
+                inputSchema: readJsonSchema(content),
+                outputSchema: readJsonSchema(okContent),
+            });
+        }
+    }
+    routes.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        title: info?.title ?? 'API',
+        version: info?.version ?? '0.0.0',
+        routes,
+    };
+}