@juzser/blacksmith 0.1.0

package/factory/scaffold/base/tsconfig.test.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "declaration": false
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/factory/scaffold/base/vitest.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      // `json-summary` is not decoration: the text reporter suppresses rows for
+      // files at 100% on every metric, so the file an acceptance criterion
+      // names vanishes from the transcript exactly when it is doing best. The
+      // gate reads coverage/coverage-summary.json instead (D-40/P9-25).
+      reporter: ['text', 'text-summary', 'json-summary'],
+      include: ['src/**/*.ts'],
+      // `src/main.ts` is the Vite mount entrypoint the `--ui` variant writes:
+      // three lines that call `createApp(App).mount('#app')`, with nothing a
+      // node-environment test could assert that a browser wouldn't. Counted, it
+      // drags a freshly scaffolded UI project to 50% lines and the floor below
+      // fails the project on its very first run — measured, not predicted.
+      // Ambient declarations have no statements to cover at all.
+      exclude: ['src/main.ts', 'src/**/*.d.ts'],
+      thresholds: {
+        lines: 80,
+        statements: 80,
+        functions: 80,
+        branches: 80,
+      },
+    },
+  },
+});

package/factory/scaffold/mcp/mcp.manifest.json

@@ -0,0 +1,22 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "protocolRevision": "2025-11-25",
+  "transport": {
+    "kind": "stdio"
+  },
+  "tools": [
+    {
+      "name": "project_health",
+      "title": "Project health",
+      "description": "Report this project's MCP surface: server name, version, pinned protocol revision, and — with verbose — the declared tool surface. Reads no project state and no credentials.",
+      "mutation": "read-only",
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    }
+  ]
+}

package/factory/scaffold/mcp/package.fragment.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "mcp:serve": "node dist/mcp/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "4.4.3"
+  }
+}

package/factory/scaffold/mcp/src/mcp/README.md

@@ -0,0 +1,63 @@
+# The MCP surface
+
+This is `__PROJECT_NAME__`'s agent-callable face: the whole of what an MCP
+client can see, and the whole of what an agent can call.
+
+## What is here
+
+| File | Job |
+| --- | --- |
+| `../../mcp.manifest.json` | The declaration. Every tool, its mutation class, its annotations, and — for anything that is not read-only — the operator sign-off. |
+| `guard.ts` | The runtime half of the policy. Refuses to register an undeclared, reclassified, or unsigned tool, and refuses to boot on a transport this surface has not implemented. |
+| `redact.ts` | Output scrubbing. Two independent nets: by key name and by credential shape. |
+| `server.ts` | Wiring. Loads the manifest, builds the server, connects stdio. |
+| `tools/health.ts` | The one shipped tool, and the worked example every other tool copies. |
+
+Tests live in `test/mcp/`. `surface.test.ts` connects a real client to a real
+server over an in-memory transport, so the assertions are about what an agent
+would actually see, not about what the manifest says.
+
+## Adding a tool
+
+1. **Declare it in `mcp.manifest.json` first.** Name it `snake_case`, give it a
+   `mutation` class (`read-only` | `write` | `destructive` | `outbound`), and
+   set the four annotations to match that class. A read-only tool with
+   `destructiveHint: true` is a contradiction and the check will say so.
+2. **If it is not read-only, get it signed off.** Add
+   `"approval": { "operator": "...", "date": "YYYY-MM-DD", "milestone": "..." }`.
+   This is a person deciding, at the MCP milestone, that an agent may do this
+   thing unattended. It is not a formality and it is not yours to add for
+   yourself.
+3. **Write the tool in `tools/`.** Start with `requireDeclaredTool(manifest,
+   NAME, <what this code actually does>)`. Pass the class the *implementation*
+   is, not the class you wish it were — that argument is what stops a tool that
+   quietly started writing from shipping under a read-only declaration.
+4. **Give it a typed input schema.** Unvalidated arguments must never reach tool
+   code.
+5. **Redact on the way out.** `redact()` the payload even when nothing in it is
+   secret today; that is what keeps it holding when the payload grows.
+6. **Register it in `server.ts`** and add a case to `test/mcp/surface.test.ts`.
+
+`pnpm test test/mcp` is the verdict. `surface.test.ts` advertises exactly what
+the manifest declares and fails on anything else, so a tool registered without
+a declaration is caught there rather than by a client.
+
+## Why stdio
+
+No port is opened, no listener is exposed, and there is no authorization surface
+to get wrong. The MCP security guidance is explicit that servers meant to run
+locally should use stdio to limit access to just the MCP client.
+
+Serving over HTTP is a deliberate opt-in, not a config flag. It requires
+Cloudflare Access in front, a canonical resource URI over `https`, RFC 8707
+resource indicators, and — non-negotiably — no token passthrough: this server
+must never accept a token that was not issued for it. Until that work is real,
+`requireSupportedTransport` refuses to boot on anything but stdio.
+
+## Two rules that are easy to break by accident
+
+- **stdout belongs to the protocol.** A stray `console.log` corrupts the stream.
+  Diagnostics go to stderr, through `redactError` first.
+- **Nothing is registered that the manifest does not declare.** The manifest is
+  the one place an operator reads to know what this server can do. If the code
+  can do more than the manifest admits, that document is a lie.

package/factory/scaffold/mcp/src/mcp/guard.ts

@@ -0,0 +1,110 @@
+/**
+ * The startup guard for this project's MCP surface.
+ *
+ * The manifest is checked statically too, before any of this runs. This is
+ * the runtime half: no tool reaches a client unless the manifest declares it
+ * with the mutation class the code claims. The two halves are deliberately
+ * separate — a static check the server can ignore is a suggestion, and a
+ * runtime check nothing audits is unreviewable — and the shared contract
+ * between them is mcp.manifest.json itself.
+ *
+ * Fail closed: every failure here throws before `connect()`, so a
+ * misconfigured surface never starts rather than starting with a hole.
+ */
+
+export type MutationClass = 'read-only' | 'write' | 'destructive' | 'outbound';
+
+export interface ToolAnnotations {
+  readOnlyHint: boolean;
+  destructiveHint: boolean;
+  idempotentHint: boolean;
+  openWorldHint: boolean;
+}
+
+export interface ToolApproval {
+  operator: string;
+  date: string;
+  milestone: string;
+}
+
+export interface DeclaredTool {
+  name: string;
+  title: string;
+  description: string;
+  mutation: MutationClass;
+  annotations: ToolAnnotations;
+  approval?: ToolApproval;
+}
+
+export interface McpManifest {
+  name: string;
+  version: string;
+  protocolRevision: string;
+  transport: { kind: string };
+  tools: DeclaredTool[];
+}
+
+export class SurfaceError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'SurfaceError';
+    this.code = code;
+  }
+}
+
+/**
+ * Look a tool up in the manifest and refuse anything undeclared, reclassified,
+ * or unsigned.
+ *
+ * `mutation` is what the implementation says it does. Passing it in is the
+ * whole point: when a tool that used to only read starts writing, the author
+ * changes this argument, the manifest no longer agrees, and the surface
+ * refuses to boot until an operator signs the new class off. Trusting the
+ * manifest alone would make that change silent.
+ */
+export function requireDeclaredTool(
+  manifest: McpManifest,
+  name: string,
+  mutation: MutationClass,
+): DeclaredTool {
+  const declared = manifest.tools.find((tool) => tool.name === name);
+  if (!declared) {
+    throw new SurfaceError(
+      'mcp.undeclared-tool',
+      `Tool "${name}" is not declared in mcp.manifest.json. Declare it (docs/standards/mcp.md MCP-T5) before registering it.`,
+    );
+  }
+  if (declared.mutation !== mutation) {
+    throw new SurfaceError(
+      'mcp.mutation-mismatch',
+      `Tool "${name}" is implemented as ${mutation} but declared as ${declared.mutation}. Update the manifest and get the new class signed off (MCP-T4).`,
+    );
+  }
+  if (mutation !== 'read-only' && !declared.approval) {
+    throw new SurfaceError(
+      'mcp.unapproved-tool',
+      `Tool "${name}" is ${mutation} and has no operator sign-off in the manifest (MCP-T4).`,
+    );
+  }
+  return declared;
+}
+
+/**
+ * Refuse to start on a transport this template does not implement. Shipping
+ * `stdio` opens no port and presents no auth surface (MCP spec, "Local MCP
+ * Server Compromise": servers meant to run locally SHOULD use stdio to limit
+ * access to just the MCP client). Serving over HTTP is a deliberate opt-in that
+ * has to satisfy MCP-X2..X6 first — Cloudflare Access in front, a canonical
+ * resource URI, resource indicators, no token passthrough — so this refuses
+ * rather than quietly falling back to a listener nobody reviewed.
+ */
+export function requireSupportedTransport(manifest: McpManifest): void {
+  if (manifest.transport.kind !== 'stdio') {
+    throw new SurfaceError(
+      'mcp.unsupported-transport',
+      `This surface is stdio-only; the manifest declares "${manifest.transport.kind}". Implement the HTTP opt-in against docs/standards/mcp.md MCP-X2..X6 before declaring it.`,
+    );
+  }
+}

package/factory/scaffold/mcp/src/mcp/redact.ts

@@ -0,0 +1,69 @@
+/**
+ * Output redaction for the MCP surface — docs/standards/mcp.md MCP-S1, and
+ * guardrails.md's "No secrets in outputs". Everything leaving a tool passes
+ * through here: results, error text, stderr diagnostics. The cheapest way to
+ * leak a token is to put a config object into an error message, so redaction
+ * lives on the way OUT rather than at each call site that might forget.
+ *
+ * Two independent nets, because either alone has a blind spot:
+ *   - by key   — anything under a secret-looking key is dropped regardless of
+ *                its value, which catches short or unusual credentials.
+ *   - by shape — recognisable token formats are scrubbed wherever they appear,
+ *                including inside free text where no key exists.
+ */
+
+export const REDACTED = '[redacted]';
+
+/** Object keys whose value is never safe to emit, whatever it looks like. */
+const SECRET_KEY =
+  /(?:pass(?:word|phrase)?|secret|token|api[-_]?key|apikey|authorization|auth|cookie|credential|private[-_]?key|session[-_]?id)/i;
+
+/** Credential shapes recognisable without a key to hang them on. */
+const SECRET_SHAPED: RegExp[] = [
+  /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}/g,
+  /\bgh[pousr]_[A-Za-z0-9]{16,}/g,
+  /\bxox[abposr]-[A-Za-z0-9-]{10,}/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/g,
+  /\bAKIA[0-9A-Z]{16}/g,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+];
+
+/** Deep structures are truncated rather than walked forever. */
+const MAX_DEPTH = 8;
+
+export function redactText(text: string): string {
+  let out = text;
+  for (const pattern of SECRET_SHAPED) {
+    out = out.replace(pattern, REDACTED);
+  }
+  return out;
+}
+
+/**
+ * Recursively redact a value. Cycles are broken by a seen-set rather than by
+ * throwing: a tool that accidentally returns a cyclic object should degrade to
+ * a marker, not crash the surface mid-response.
+ */
+export function redact(value: unknown, depth = 0, seen = new WeakSet<object>()): unknown {
+  if (typeof value === 'string') return redactText(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (depth >= MAX_DEPTH) return '[truncated]';
+  if (seen.has(value)) return '[circular]';
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => redact(entry, depth + 1, seen));
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    out[key] = SECRET_KEY.test(key) ? REDACTED : redact(entry, depth + 1, seen);
+  }
+  return out;
+}
+
+/** Error text safe to hand back to a client or write to stderr. */
+export function redactError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return redactText(message);
+}

package/factory/scaffold/mcp/src/mcp/server.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * __PROJECT_NAME__'s MCP surface — the agent-callable face of this project.
+ *
+ * stdio only, by default and on purpose: no port is opened, no listener is
+ * exposed, and there is no authorization surface to get wrong. Serving this
+ * over HTTP is an opt-in that has to satisfy docs/standards/mcp.md MCP-X2..X6
+ * first; `requireSupportedTransport` refuses to boot until that work is real.
+ *
+ * Two invariants this file exists to hold:
+ *   - stdout belongs to the protocol. Every diagnostic goes to stderr, and
+ *     goes through redaction first (MCP-S1) — a stray console.log corrupts the
+ *     stream, and an un-redacted one leaks.
+ *   - nothing is registered that the manifest does not declare. Registration
+ *     runs through guard.ts, and a mismatch throws before connect().
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { type McpManifest, requireSupportedTransport } from './guard.js';
+import { redactError } from './redact.js';
+import { registerHealthTool } from './tools/health.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** Resolves to the project root from both `src/mcp/` and the built `dist/mcp/`. */
+const MANIFEST_PATH = path.resolve(HERE, '..', '..', 'mcp.manifest.json');
+
+export function loadManifest(manifestPath: string = MANIFEST_PATH): McpManifest {
+  return JSON.parse(readFileSync(manifestPath, 'utf8')) as McpManifest;
+}
+
+export function buildServer(manifest: McpManifest): McpServer {
+  requireSupportedTransport(manifest);
+  const server = new McpServer({ name: manifest.name, version: manifest.version });
+  registerHealthTool(server, manifest);
+  return server;
+}
+
+export async function main(): Promise<void> {
+  const manifest = loadManifest();
+  const server = buildServer(manifest);
+  await server.connect(new StdioServerTransport());
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (invokedDirectly) {
+  main().catch((error: unknown) => {
+    process.stderr.write(`${redactError(error)}\n`);
+    process.exit(1);
+  });
+}

package/factory/scaffold/mcp/src/mcp/tools/health.ts

@@ -0,0 +1,60 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { type McpManifest, requireDeclaredTool } from '../guard.js';
+import { redact } from '../redact.js';
+
+/**
+ * The one tool the scaffold ships: enough to prove the surface is wired end to
+ * end, and a worked example of the shape every other tool copies —
+ *
+ *   1. a typed input schema (MCP-P4), so unknown arguments never reach code;
+ *   2. `requireDeclaredTool` with the class this implementation actually is,
+ *      so a later change to what it does cannot outrun the manifest;
+ *   3. title/description/annotations taken FROM the manifest rather than
+ *      restated here, so there is one place an operator has to read to know
+ *      what this server can do.
+ */
+const TOOL_NAME = 'project_health';
+
+const inputSchema = {
+  verbose: z
+    .boolean()
+    .optional()
+    .describe('Also list the declared tool surface, not just the server identity.'),
+};
+
+export function registerHealthTool(server: McpServer, manifest: McpManifest): void {
+  const declared = requireDeclaredTool(manifest, TOOL_NAME, 'read-only');
+
+  server.registerTool(
+    declared.name,
+    {
+      title: declared.title,
+      description: declared.description,
+      inputSchema,
+      annotations: declared.annotations,
+    },
+    async ({ verbose }) => {
+      const payload = {
+        name: manifest.name,
+        version: manifest.version,
+        protocolRevision: manifest.protocolRevision,
+        transport: manifest.transport.kind,
+        ...(verbose
+          ? {
+              tools: manifest.tools.map((tool) => ({
+                name: tool.name,
+                mutation: tool.mutation,
+              })),
+            }
+          : {}),
+      };
+
+      // Redacted even though nothing here is secret today: the redaction runs
+      // on the way out so it keeps holding when this payload grows.
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(redact(payload), null, 2) }],
+      };
+    },
+  );
+}

package/factory/scaffold/mcp/test/mcp/guard.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type McpManifest,
+  requireDeclaredTool,
+  requireSupportedTransport,
+  SurfaceError,
+} from '../../src/mcp/guard.js';
+
+function manifest(overrides: Partial<McpManifest> = {}): McpManifest {
+  return {
+    name: 'demo',
+    version: '0.0.0',
+    protocolRevision: '2025-11-25',
+    transport: { kind: 'stdio' },
+    tools: [
+      {
+        name: 'project_health',
+        title: 'Project health',
+        description: 'Reports the surface.',
+        mutation: 'read-only',
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false,
+        },
+      },
+    ],
+    ...overrides,
+  };
+}
+
+describe('requireDeclaredTool', () => {
+  it('returns the declaration for a tool the manifest declares', () => {
+    expect(requireDeclaredTool(manifest(), 'project_health', 'read-only').title).toBe(
+      'Project health',
+    );
+  });
+
+  it('refuses a tool the manifest does not declare', () => {
+    expect(() => requireDeclaredTool(manifest(), 'delete_everything', 'destructive')).toThrow(
+      SurfaceError,
+    );
+  });
+
+  it('refuses when the implementation mutates more than the manifest admits', () => {
+    // The tool used to only read; someone made it write. The manifest still
+    // says read-only, so the surface must not start.
+    expect(() => requireDeclaredTool(manifest(), 'project_health', 'write')).toThrow(
+      /declared as read-only/,
+    );
+  });
+
+  it('refuses a mutating tool with no operator sign-off', () => {
+    const unsigned = manifest({
+      tools: [
+        {
+          name: 'purge_cache',
+          title: 'Purge cache',
+          description: 'Drops every cached entry.',
+          mutation: 'destructive',
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+          },
+        },
+      ],
+    });
+    expect(() => requireDeclaredTool(unsigned, 'purge_cache', 'destructive')).toThrow(
+      /no operator sign-off/,
+    );
+  });
+
+  it('accepts a mutating tool once it is signed off', () => {
+    const signed = manifest({
+      tools: [
+        {
+          name: 'purge_cache',
+          title: 'Purge cache',
+          description: 'Drops every cached entry.',
+          mutation: 'destructive',
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+          },
+          approval: { operator: 'ops', date: '2026-08-07', milestone: 'demo-mcp-surface' },
+        },
+      ],
+    });
+    expect(requireDeclaredTool(signed, 'purge_cache', 'destructive').name).toBe('purge_cache');
+  });
+});
+
+describe('requireSupportedTransport', () => {
+  it('accepts stdio', () => {
+    expect(() => requireSupportedTransport(manifest())).not.toThrow();
+  });
+
+  it('refuses to boot on a transport this surface has not implemented', () => {
+    expect(() => requireSupportedTransport(manifest({ transport: { kind: 'http' } }))).toThrow(
+      /stdio-only/,
+    );
+  });
+});

package/factory/scaffold/mcp/test/mcp/redact.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { REDACTED, redact, redactError, redactText } from '../../src/mcp/redact.js';
+
+describe('redactText', () => {
+  it('scrubs credential shapes out of free text', () => {
+    const text = 'failed with Bearer abcdefghijklmnop and ghp_0123456789abcdefghij';
+    expect(redactText(text)).not.toContain('ghp_0123456789abcdefghij');
+    expect(redactText(text)).not.toContain('abcdefghijklmnop');
+    expect(redactText(text)).toContain(REDACTED);
+  });
+
+  it('leaves ordinary text alone', () => {
+    expect(redactText('no credentials here')).toBe('no credentials here');
+  });
+});
+
+describe('redact', () => {
+  it('drops values under secret-looking keys whatever they contain', () => {
+    const out = redact({ apiKey: 'x', password: 'y', session_id: 'z', name: 'keep' });
+    expect(out).toEqual({
+      apiKey: REDACTED,
+      password: REDACTED,
+      session_id: REDACTED,
+      name: 'keep',
+    });
+  });
+
+  it('recurses through arrays and nested objects', () => {
+    const out = redact({ items: [{ token: 'secret', label: 'ok' }] });
+    expect(out).toEqual({ items: [{ token: REDACTED, label: 'ok' }] });
+  });
+
+  it('survives a cyclic value instead of throwing', () => {
+    const cyclic: Record<string, unknown> = { name: 'self' };
+    cyclic.self = cyclic;
+    expect(() => redact(cyclic)).not.toThrow();
+  });
+
+  it('passes primitives through untouched', () => {
+    expect(redact(42)).toBe(42);
+    expect(redact(null)).toBe(null);
+    expect(redact(true)).toBe(true);
+  });
+
+  it('truncates rather than walking an arbitrarily deep structure', () => {
+    let deep: Record<string, unknown> = { end: true };
+    for (let i = 0; i < 20; i += 1) deep = { next: deep };
+    expect(JSON.stringify(redact(deep))).toContain('[truncated]');
+  });
+});
+
+describe('redactError', () => {
+  it('redacts the message of a thrown Error', () => {
+    const error = new Error('token ghp_0123456789abcdefghij rejected');
+    expect(redactError(error)).toBe(`token ${REDACTED} rejected`);
+  });
+
+  it('handles a non-Error throw', () => {
+    expect(redactError('plain string')).toBe('plain string');
+  });
+});