@afora/mcp 0.0.0-stage → 0.0.3

package/dist/index.js

@@ -0,0 +1,1087 @@
+// src/guide.ts
+var GUIDE = `# afora.json guide
+
+\`afora.json\` describes a domain. \`afora_generate\` turns it into TypeScript on \`@afora/core\`
+(one file per kind of declaration, under \`output.dir\`, default \`src/domain\`). The generated files
+start with "// Generated by @afora/codegen from afora.json. Do not edit." and are overwritten on
+every run, so change the JSON, never those files. To add behavior, extend the generated class in
+a file of your own.
+
+## Workflow
+
+1. \`afora_catalog\`: what you can use (Std properties, record plugins, rules).
+2. \`afora_spec_read\`: the current spec (or the one extracted from the code).
+3. Edit with \`afora_spec_upsert\` / \`afora_spec_remove\` (one declaration at a time; the whole
+   spec must stay valid, so declare what a declaration uses first) or \`afora_spec_write\`.
+4. \`afora_spec_validate\`, then \`afora_generate\` (\`dryRun: true\` to preview). The result has the
+   TypeScript diagnostics of the generated files: fix the spec until there are none.
+
+## Shape
+
+\`\`\`json
+{
+  "version": 1,
+  "name": "blog",
+  "output": { "dir": "src/domain" },
+  "provider": "inMemory",
+  "properties":   { "Age": { "base": "integer", "with": { "min": 0, "max": 150 } },
+                    "Status": { "enum": ["draft", "published"] } },
+  "blueprints":   { "Address": { "fields": { "street": "string", "zip": "string" } } },
+  "records":      { "Money": { "fields": { "amount": "number", "currency": "string" } } },
+  "entities":     { "User": { "fields": { "name": "text", "email": "email", "password": "password",
+                                          "age": "Age?", "address": "Address", "tags": "string[]" },
+                              "unique": ["email"], "change": ["name"] },
+                    "Post": { "fields": { "title": "text", "status": "Status",
+                                          "author": "User", "coauthors": "User[]" } } },
+  "environments": { "Database": { "fields": { "DATABASE_URL": "url", "PORT": "integer" } } },
+  "repositories": { "Users": { "entity": "User", "actions": ["findById", "findByEmail", "create", "update"],
+                               "environments": ["Database"] },
+                    "Posts": { "entity": "Post", "actions": ["findById", "findManyByAuthor", "create"],
+                               "relations": ["Users"] } }
+}
+\`\`\`
+
+## Fields
+
+- Shorthand string: \`"email"\`, \`"Age?"\` (optional), \`"string[]"\` (list), \`"User[]?"\` (optional list).
+- Lowercase names are Std properties (see \`afora_catalog\`: id, slug, email, phone, url, ip, password,
+  string, text, number, integer, boolean, date, dateTime...). PascalCase names are declarations of
+  the spec (properties, blueprints, records, entities).
+- Object form: \`{ "type": "string", "optional": true, "list": { "minItems": 1, "maxItems": 5 }, "with": { "pattern": "^a" } }\`.
+  \`with\` applies to each item of a list and only takes options valid for the type (min/max/pattern for strings,
+  min/max/exclusiveMin/exclusiveMax/multipleOf for numbers, plus title/description/examples/deprecated/readOnly/writeOnly/default).
+- Enum: \`{ "enum": ["a", "b"] }\`. Nested object in place: \`{ "fields": { "lat": "number", "lng": "number" } }\`.
+- A property of your own: \`{ "base": "integer", "with": {...} }\`, \`{ "enum": [...] }\`, or
+  \`{ "opaque": true, "import": "./my-property" }\` for a hand-written one (imported as it is).
+
+## Rules the validator enforces
+
+- Declaration names are PascalCase and unique across every kind; names exported by @afora/core are taken.
+- No circular references between declarations (store an id instead of the entity).
+- An entity cannot declare \`id\`, \`createdAt\`, \`updatedAt\`, \`deletedAt\` (it gets them). No record member names
+  (\`toJSON\`, \`set\`, \`onSet\`...); see \`reservedRecordKeys\` in the catalog. \`blueprint\` and \`options\` are valid fields.
+- \`unique\`, \`sensitive\`, \`change\` must name fields (or keys of its plugins); \`change\` cannot name an identity key.
+  \`password\` is always sensitive and \`slug\` always unique; \`id\` is always unique.
+- \`plugins\`: Std record plugins (publishable, archivable, taggable, ownable, authenticatable); their keys cannot be declared again.
+- Repository actions: \`findById\`; \`findBy<Key>\` only for unique keys (id, \`unique\`, slug fields, unique plugin keys such as
+  \`email\` of authenticatable); \`findManyBy<Key>\` only for keys that are not unique; \`create\`, \`update\`, \`delete\`, \`count\`, and the
+  queries \`findMany\`, \`exists\`, \`findPage\` (no key needed; \`where\`, \`orderBy\`, \`limit\`, \`offset\` at runtime).
+- \`provider\` (top level for the application, and optionally on a repository, which then uses its own): \`"inMemory"\`,
+  \`{ "use": "<name>", "options": {...} }\` with a name from the \`providers\` of \`afora_catalog\` (external ones are given
+  to the server with \`--providers\`), or \`{ "import": "./db.ts#provider" }\` for one created by hand. Options are JSON or
+  \`{ "import": "./db.ts#db" }\` references (any depth); imports are relative to \`output.dir\` and never run by the validator.
+  Omitting \`provider\` is not the same as \`"inMemory"\`: a repository without one uses the application's. For a provider
+  not created with \`providerOf\`, \`afora_extract\` needs \`imports\` (\`provider\` / \`repositories.<Name>.provider\`).
+- Repository \`deletion\`: \`"hard"\` (default) physically removes rows; \`"soft"\` retains \`deletedAt\` and hides deleted rows from reads, counts and relations.
+- \`relations\` must list exactly one repository for each entity the repository's entity holds, at any depth (inside
+  records, blueprints and nested objects), not through another entity.
+- Environments hold properties only (no lists, no objects).
+- \`extends\`: other specs (relative path to their afora.json, or a package) whose declarations you can reference;
+  the same name for different declarations is a conflict.
+
+## Exceptions and use cases
+
+\`\`\`json
+{
+  "exceptions": { "UserAlreadyExists": { "layer": "use-case", "message": "A user with this email already exists." } },
+  "useCases": {
+    "Register": {
+      "description": "Signs a user up.", "tags": ["users"],
+      "input": { "fields": { "name": "text", "email": "email", "plainPassword": "string" } },
+      "response": { "fields": { "user": "User" } },
+      "dependencies": { "users": "Users" },
+      "errors": ["UserAlreadyExists", "RepositoryUniqueViolation"],
+      "implementation": { "steps": [
+        { "find": "users.findByEmail", "args": ["$input.email"], "as": "existing" },
+        { "ensure": "absent", "value": "$existing", "error": "UserAlreadyExists" },
+        { "run": "hashPassword", "fn": { "import": "../hash#hashPassword" }, "args": ["$input.plainPassword"], "as": "hash" },
+        { "build": "User", "values": { "name": "$input.name", "email": "$input.email", "password": "$hash" }, "as": "user" },
+        { "create": "users", "value": "$user", "as": "saved" },
+        { "return": { "user": "$saved" } }
+      ] }
+    }
+  }
+}
+\`\`\`
+
+- \`exceptions\`: \`{ layer, message? }\`; \`layer\` is one of \`exceptionLayers\` of \`afora_catalog\`; the message is "<Name>." when omitted.
+- \`useCases\`: \`input\`, \`response\` and \`context\` (optional) are a blueprint name or \`{ "fields": {...} }\`. \`dependencies\` map a key to a use case, repository
+  or environment. \`errors\` are declared exceptions or exceptions exported by @afora/core (\`coreExceptions\` of \`afora_catalog\`).
+- \`implementation\` is \`{ "steps": [...] }\` (generated complete, no hand-written file) or \`{ "import": "../handlers/x.ts#Name" }\`:
+  the generated file has \`abstract class <Name>Base\`; write \`class Name extends <Name>Base\` with \`execute\` at that path.
+  A use case cannot list an imported (hand-written) use case as a dependency.
+- Steps run in order and \`return\` is last, exactly once: \`find\` ("<repo>.<read action>"), \`ensure\` (exists | absent | equals | notEquals | true | false;
+  \`other\` for the comparisons, \`error\` a declared exception name or a core one, listed in \`errors\`; optional \`details\`), \`build\` (a record or
+  entity name, \`values\`, \`as\`), \`change\` ($ref, \`key\` in the class's change keys, \`value\`), \`invoke\` ($ref, \`method\`, \`args\`),
+  \`create\` / \`update\` / \`delete\` (repository key, \`value\`), \`call\` (use case key, \`input\`) and \`run\` (a unique name, \`fn\` is
+  \`{ "import": "../x.ts#fn" }\`, \`args\`; the function gets (...args, { context })). \`as\` binds the result.
+- Values: \`"$input.key"\`, \`"$context.key"\`, \`"$env.<dependency>.VAR"\`, \`"$name.path.0"\` (a bound result); a literal; \`{ "literal": "$5" }\` for a string that
+  starts with $; or an object/array of values. No expressions: compute with \`run\`.
+- \`afora_extract\` needs \`imports\` for \`useCases.<Name>\` (hand-written execute) and \`useCases.<Name>.run.<name>\` (run functions).
+
+## Commands and outputs
+
+\`\`\`json
+{
+  "commands": {
+    "Users": {
+      "description": "Accounts.", "tags": ["public"],
+      "context": { "fields": { "userId": "id?" } },
+      "useCases": { "register": "Register" },
+      "transaction": true
+    }
+  },
+  "outputs": {
+    "Api": {
+      "commands": ["Users"],
+      "statuses": { "UserAlreadyExists": 409 },
+      "pipe": [
+        { "transform": "select", "options": { "tags": ["public"] } },
+        { "sink": "openapi", "options": { "info": { "title": "Blog", "version": "1.0.0" } } }
+      ]
+    }
+  }
+}
+\`\`\`
+
+- \`commands\`: \`useCases\` maps an operation name (an identifier) to a declared use case; \`context\` is a blueprint name or \`{ "fields": {...} }\`.
+  \`transaction: true\` runs each call in a transaction of the repositories' provider: it is checked when the code runs, not by the validator
+  (the provider is unknown then). \`events\` is \`"after-commit"\` (default), \`"manual"\` or \`{ "import": "./events.ts#dispatch" }\` (a handler);
+  \`onEventError\` is an import and only with \`after-commit\`. Defaults (\`transaction: false\`, \`events: "after-commit"\`, no tags) are not written.
+- \`outputs\`: \`commands\` are declared commands; \`statuses\` maps an exception name (declared or exported by @afora/core) to a status from 400 to 599;
+  \`pipe\` is transforms and, last, at most one sink, each \`{ "transform" | "sink": name, "options"?: {...JSON} }\` with a name from the \`stages\` of
+  \`afora_catalog\` (\`select\`, \`openapi\`, plus the ones given to the server with \`--stages\`), or \`{ "import": "./stages.ts#auth" }\` for a stage written by hand.
+- \`afora_extract\` needs \`imports\` for \`commands.<Name>.events\`, \`commands.<Name>.onEventError\` and \`outputs.<Name>.pipe.<index>\` (hand-written ones).
+`;
+// src/server.ts
+import {
+  catalog as catalog2,
+  specSchema as specSchema2
+} from "@afora/codegen";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/extract.ts
+import { existsSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { confinePath } from "@afora/codegen";
+
+// src/process.ts
+import { spawn } from "node:child_process";
+function run(command, args, options) {
+  return new Promise((resolve) => {
+    let output = "";
+    let timedOut = false;
+    const child = spawn(command, [...args], {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, options.timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      output += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      output += chunk;
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve({ code: null, output, missing: true, timedOut });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code, output, missing: false, timedOut });
+    });
+  });
+}
+
+// src/extract.ts
+var START = `
+<<<AFORA_SPEC>>>
+`;
+var END = `
+<<<END_AFORA_SPEC>>>
+`;
+
+class ToolError extends Error {
+  name = "ToolError";
+}
+function childPath() {
+  for (const extension of ["js", "ts"]) {
+    const url = new URL(`./extract-child.${extension}`, import.meta.url);
+    const path = fileURLToPath(url);
+    if (existsSync(path))
+      return path;
+  }
+  throw new ToolError("The extract helper is missing from the installation.");
+}
+function parseAppReference(reference) {
+  const [file, name = "App"] = reference.split("#");
+  if (!file) {
+    throw new ToolError('Expected "path/to/file.ts#ExportName", e.g. "src/app.ts#App".');
+  }
+  return { file, name };
+}
+async function extractFromApp(root, reference, outputDir, imports) {
+  const { file, name } = parseAppReference(reference);
+  const confined = await confinePath(root, file);
+  if (!confined.ok) {
+    throw new ToolError(`The application file ${file} is ${confined.reason}.`);
+  }
+  if (!existsSync(confined.absolute)) {
+    throw new ToolError(`The application file ${file} does not exist.`);
+  }
+  const real = await realpath(confined.absolute);
+  const bun = process.versions.bun ? process.execPath : "bun";
+  const result = await run(bun, [
+    childPath(),
+    real,
+    name,
+    outputDir ?? "",
+    ...imports ? [JSON.stringify(imports)] : []
+  ], { cwd: root, timeoutMs: 60000 });
+  if (result.missing) {
+    throw new ToolError("Bun is needed to import the application and was not found on PATH.");
+  }
+  if (result.timedOut)
+    throw new ToolError("Importing the application timed out.");
+  const start = result.output.indexOf(START);
+  const end = result.output.indexOf(END, start);
+  if (result.code !== 0 || start === -1 || end === -1) {
+    throw new ToolError(`Could not extract the application:
+${result.output.trim().slice(-2000)}`);
+  }
+  return JSON.parse(result.output.slice(start + START.length, end));
+}
+
+// src/spec-file.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir, readFile, realpath as realpath2, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  COLLECTION_KEYS,
+  confinePath as confinePath2,
+  resolveExtended,
+  SpecLoadError,
+  validateSpec
+} from "@afora/codegen";
+var SPEC_FILE = "afora.json";
+function codegenOptionsOf(project) {
+  return {
+    ...project.providers ? { providers: project.providers } : {},
+    ...project.stages ? { stages: project.stages } : {}
+  };
+}
+async function openProject(directory, app, providers, stages) {
+  let root;
+  try {
+    root = await realpath2(directory);
+  } catch {
+    throw new Error(`The project directory ${directory} does not exist.`);
+  }
+  return {
+    root,
+    ...app ? { app } : {},
+    ...providers ? { providers } : {},
+    ...stages ? { stages } : {}
+  };
+}
+async function readSpec(project) {
+  const path = join(project.root, SPEC_FILE);
+  if (!existsSync2(path))
+    return;
+  const confined = await confinePath2(project.root, SPEC_FILE);
+  if (!confined.ok) {
+    throw new ToolError(`${SPEC_FILE} is ${confined.reason}.`);
+  }
+  try {
+    return JSON.parse(await readFile(confined.absolute, "utf8"));
+  } catch (error) {
+    throw new ToolError(`${SPEC_FILE} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function writeSpec(project, spec) {
+  const confined = await confinePath2(project.root, SPEC_FILE);
+  if (!confined.ok) {
+    throw new ToolError(`${SPEC_FILE} is ${confined.reason}; it was not written.`);
+  }
+  await mkdir(dirname(confined.absolute), { recursive: true });
+  await writeFile(confined.absolute, `${JSON.stringify(ordered(spec), null, "\t")}
+`);
+}
+var TOP_ORDER = [
+  "$schema",
+  "version",
+  "name",
+  "extends",
+  "output",
+  "provider",
+  ...COLLECTION_KEYS
+];
+function ordered(spec) {
+  const source = spec;
+  const keys = [
+    ...TOP_ORDER.filter((key) => (key in source)),
+    ...Object.keys(source).filter((key) => !TOP_ORDER.includes(key))
+  ];
+  return Object.fromEntries(keys.map((key) => [key, source[key]]));
+}
+async function extendedOf(project, spec) {
+  try {
+    return {
+      extended: await resolveExtended(spec, join(project.root, SPEC_FILE)),
+      issues: []
+    };
+  } catch (error) {
+    if (!(error instanceof SpecLoadError))
+      throw error;
+    return {
+      extended: {},
+      issues: [
+        {
+          path: ["extends"],
+          code: "unresolved_extends",
+          message: error.message
+        }
+      ]
+    };
+  }
+}
+async function validateInProject(project, spec) {
+  const loaded = typeof spec === "object" && spec !== null ? await extendedOf(project, spec) : { extended: {}, issues: [] };
+  const issues = validateSpec(spec, loaded.extended, codegenOptionsOf(project));
+  const known = new Set(issues.map((issue) => `${issue.code}@${issue.path.join(".")}`));
+  return {
+    extended: loaded.extended,
+    issues: [
+      ...issues,
+      ...loaded.issues.filter((issue) => !known.has(`${issue.code}@${issue.path.join(".")}`) && !issues.some((other) => other.code === "unresolved_extends"))
+    ]
+  };
+}
+
+// src/tools.ts
+import {
+  catalog,
+  declarationSchemas,
+  fieldDefinition,
+  generate,
+  InvalidSpecError,
+  specSchema,
+  writeGenerated
+} from "@afora/codegen";
+import { Type } from "typebox";
+
+// src/typecheck.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { join as join2, relative, resolve } from "node:path";
+var DIAGNOSTIC = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/;
+function parseDiagnostics(output) {
+  const found = [];
+  for (const text of output.split(/\r?\n/)) {
+    const match = DIAGNOSTIC.exec(text);
+    if (match) {
+      found.push({
+        path: match[1],
+        file: match[1],
+        line: Number(match[2]),
+        column: Number(match[3]),
+        code: match[4],
+        message: match[5]
+      });
+    } else if (/^\s+\S/.test(text) && found.length > 0) {
+      const last = found[found.length - 1];
+      last.message += `
+${text.trim()}`;
+    }
+  }
+  return found;
+}
+async function typecheck(root, files) {
+  if (!existsSync3(join2(root, "tsconfig.json"))) {
+    return { ran: false, reason: "The project has no tsconfig.json." };
+  }
+  const mine = new Set(files.map((file) => resolve(root, file)));
+  const commands = [
+    ["bunx", ["tsc", "--noEmit", "-p", root]],
+    ["npx", ["--no-install", "tsc", "--noEmit", "-p", root]]
+  ];
+  for (const [command, args] of commands) {
+    const result = await run(command, args, { cwd: root, timeoutMs: 180000 });
+    if (result.missing)
+      continue;
+    if (result.timedOut) {
+      return { ran: false, reason: "tsc timed out after 180 seconds." };
+    }
+    const all = parseDiagnostics(result.output);
+    if (all.length === 0 && result.code !== 0) {
+      return {
+        ran: false,
+        reason: `tsc failed without diagnostics: ${result.output.trim().slice(0, 500)}`
+      };
+    }
+    const diagnostics = all.filter((item) => mine.has(resolve(root, item.path))).map(({ path, ...item }) => ({
+      ...item,
+      file: relative(root, resolve(root, path))
+    }));
+    return {
+      ran: true,
+      ok: diagnostics.length === 0,
+      diagnostics,
+      otherErrors: all.length - diagnostics.length
+    };
+  }
+  return {
+    ran: false,
+    reason: "Neither bunx nor npx is available to run tsc."
+  };
+}
+
+// src/tools.ts
+var json = (schema) => JSON.parse(JSON.stringify(schema));
+var KINDS = [
+  "property",
+  "blueprint",
+  "record",
+  "entity",
+  "environment",
+  "repository",
+  "exception",
+  "useCase",
+  "command",
+  "output"
+];
+var COLLECTION_OF = {
+  property: "properties",
+  blueprint: "blueprints",
+  record: "records",
+  entity: "entities",
+  environment: "environments",
+  repository: "repositories",
+  exception: "exceptions",
+  useCase: "useCases",
+  command: "commands",
+  output: "outputs"
+};
+var specInput = () => {
+  const { $defs: _defs, ...schema } = json(specSchema);
+  return schema;
+};
+var FIELD_DEFS = { Field: json(fieldDefinition) };
+function issuesResult(issues) {
+  return { valid: issues.length === 0, issues };
+}
+async function currentSpec(project) {
+  const spec = await readSpec(project);
+  if (spec)
+    return { spec, source: "file" };
+  if (project.app) {
+    return {
+      spec: await extractFromApp(project.root, project.app),
+      source: "app"
+    };
+  }
+  return { spec: { version: 1 }, source: "new" };
+}
+function asSpec(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ToolError("`spec` must be a JSON object (the contents of afora.json).");
+  }
+  return value;
+}
+function kindOf(value) {
+  if (!KINDS.includes(value)) {
+    throw new ToolError(`\`kind\` must be one of: ${KINDS.join(", ")}.`);
+  }
+  return value;
+}
+function nameOf(value) {
+  if (typeof value !== "string" || value === "") {
+    throw new ToolError("`name` must be the PascalCase name of the declaration.");
+  }
+  return value;
+}
+async function saveIfValid(project, spec, extra = {}) {
+  const { issues } = await validateInProject(project, spec);
+  if (issues.length > 0) {
+    return {
+      written: false,
+      ...issuesResult(issues),
+      hint: "Nothing was written. Fix the issues (declare what a declaration uses first) and retry.",
+      ...extra
+    };
+  }
+  await writeSpec(project, spec);
+  return { written: true, path: "afora.json", ...issuesResult([]), ...extra };
+}
+var tools = [
+  {
+    name: "afora_catalog",
+    description: "What an afora.json can use, read from @afora/core: the Std properties (type, flags sensitive/unique/optional, and the `with` options each accepts), factories (enum), the Std record plugins (keys they add, unique/sensitive/change keys, methods), reserved record/entity keys, identity keys and the repository action rules. The `providers` list is what `provider.use` may name; `exceptionLayers` and `coreExceptions` are what an exception's `layer` and a use case's `errors` may use; `stages` (select, openapi and the ones given to the server with --stages) are what an output's `pipe` may name with `transform` or `sink`. Call this first; do not guess property names.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    readOnly: true,
+    handle: async (_args, project) => ({
+      ...catalog(),
+      providers: [
+        {
+          name: "inMemory",
+          builtin: true,
+          note: 'provider: "inMemory" (or { "use": "inMemory" }), no options.'
+        },
+        ...project.providers ?? []
+      ],
+      stages: [
+        ...catalog().stages,
+        ...(project.stages ?? []).map((stage) => ({
+          ...stage,
+          builtin: false
+        }))
+      ]
+    })
+  },
+  {
+    name: "afora_spec_read",
+    description: "Reads the project's afora.json, with its validation issues. If there is none and the server was started with --app, returns the spec extracted from that application's code (not written). Use it before editing.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    readOnly: true,
+    async handle(_args, project) {
+      const spec = await readSpec(project);
+      if (spec) {
+        const { issues } = await validateInProject(project, spec);
+        return {
+          source: "file",
+          path: "afora.json",
+          spec,
+          ...issuesResult(issues)
+        };
+      }
+      if (project.app) {
+        const extracted = await extractFromApp(project.root, project.app);
+        return {
+          source: "app",
+          app: project.app,
+          spec: extracted,
+          note: "Extracted from the code; nothing was written. afora_spec_write or afora_spec_upsert saves a spec as afora.json."
+        };
+      }
+      return {
+        source: "none",
+        spec: null,
+        note: 'There is no afora.json yet. Start with afora_spec_upsert (it creates one) or afora_spec_write with { "version": 1, ... }.'
+      };
+    }
+  },
+  {
+    name: "afora_extract",
+    description: "Extracts the spec from an existing @afora/core Application in the project, by importing the module in a Bun subprocess (this runs the module's code). Does not write anything: review it, then save with afora_spec_write. Properties that cannot be expressed in JSON become opaque imports.",
+    inputSchema: json(Type.Object({
+      app: Type.Optional(Type.String({
+        description: 'Path inside the project and export name, e.g. "src/app.ts#App". Defaults to the --app the server was started with.'
+      })),
+      outputDir: Type.Optional(Type.String({
+        description: "output.dir for the spec; src/domain by default."
+      })),
+      imports: Type.Optional(Type.Record(Type.String(), Type.String(), {
+        description: 'Where what cannot be described is imported from: a property name -> module, and "./file.ts#export" (relative to output.dir) for a provider not created with providerOf ("provider" or "repositories.<Name>.provider"), a use case with a hand-written execute ("useCases.<Name>") and a run function of a steps use case ("useCases.<Name>.run.<name>"), a command handler ("commands.<Name>.events", "commands.<Name>.onEventError") and a stage written by hand ("outputs.<Name>.pipe.<index>"). Without it extraction fails with an error naming the key.'
+      }))
+    }, { additionalProperties: false })),
+    readOnly: true,
+    async handle(args, project) {
+      const app = typeof args.app === "string" ? args.app : project.app;
+      if (!app) {
+        throw new ToolError('Pass `app` ("src/app.ts#App") or start the server with --app.');
+      }
+      const outputDir = typeof args.outputDir === "string" ? args.outputDir : undefined;
+      const imports = typeof args.imports === "object" && args.imports !== null && !Array.isArray(args.imports) ? args.imports : undefined;
+      const spec = await extractFromApp(project.root, app, outputDir, imports);
+      const { issues } = await validateInProject(project, spec);
+      return { source: "app", app, spec, ...issuesResult(issues) };
+    }
+  },
+  {
+    name: "afora_spec_validate",
+    description: "Validates a spec without writing anything and returns the issues ({ path, code, message }). Pass `spec` to check a draft, or omit it to check the afora.json on disk. Rules covered (use cases: references, dependency kinds, errors registered or core, every step rule with the codes unknown_step, invalid_reference, unbound_reference, unknown_key, unknown_dependency, unknown_action, write_in_find, undeclared_error, missing_return, misplaced_return, invalid_step_name, invalid_class, invalid_change_key, invalid_value, invalid_import; commands: unknown_use_case, invalid_use_cases, invalid_operation, invalid_events, event_error_requires_after_commit; outputs: unknown_command, invalid_commands, invalid_pipe, invalid_stage, unknown_stage, stage_kind_mismatch, sink_not_last, invalid_stage_options, invalid_statuses, invalid_status, unknown_exception): unknown references, name collisions, cycles, reserved and identity keys, unique/sensitive/change naming missing keys, repository action rules (findBy only for unique keys, findManyBy only for non-unique; findMany, exists, findPage need no key), providers (unknown_provider, invalid_provider, invalid_import), relations covering the entities held, invalid `with` options.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        spec: {
+          ...specInput(),
+          description: "A draft spec. Omit to validate afora.json on disk."
+        }
+      },
+      additionalProperties: false,
+      $defs: FIELD_DEFS
+    },
+    readOnly: true,
+    async handle(args, project) {
+      const spec = args.spec ?? await readSpec(project);
+      if (spec === undefined) {
+        throw new ToolError("There is no afora.json to validate; pass `spec`.");
+      }
+      const { issues } = await validateInProject(project, spec);
+      return issuesResult(issues);
+    }
+  },
+  {
+    name: "afora_spec_upsert",
+    description: "Adds or replaces ONE declaration in afora.json (creating the file if needed), validates the whole spec and writes only if it is valid. Cheaper than resending the spec. `kind` is property | blueprint | record | entity | environment | repository | exception | useCase | command | output; `declaration` is its JSON (see the schema). Declare what it references first (e.g. a blueprint before the entity that uses it, the entity before its repository). If invalid, nothing is written and the issues are returned.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: {
+          type: "string",
+          enum: [...KINDS],
+          description: "Which collection the declaration belongs to."
+        },
+        name: {
+          type: "string",
+          pattern: "^[A-Z][A-Za-z0-9]*$",
+          description: "PascalCase name, unique across all kinds."
+        },
+        declaration: {
+          description: 'The declaration. property: { base, with? } | { enum } | { opaque, import }. blueprint/environment: { fields }. record/entity: { fields, unique?, sensitive?, change?, plugins? }. repository: { entity, actions, provider?, deletion?: hard | soft, relations?, environments? }. exception: { layer, message? }. useCase: { description?, tags?, deprecated?, input, response, context?, dependencies?, errors?, implementation: { steps: [...] } | { import: "../handlers/x.ts#Name" } } (see the guide for steps). command: { description?, tags?, context?, useCases: { op: "UseCaseName" }, transaction?, events?: "after-commit" | "manual" | { import }, onEventError?: { import } }. output: { commands: [names], statuses?: { ExceptionName: 400-599 }, pipe: [{ transform, options? } | { sink, options? } | { import }] }. provider: "inMemory" | { use, options? } | { import: "./file.ts#name" } (the application provider is the top-level `provider` of the spec: afora_spec_write).',
+          anyOf: Object.values(declarationSchemas).map((schema) => json(schema))
+        }
+      },
+      required: ["kind", "name", "declaration"],
+      additionalProperties: false,
+      $defs: FIELD_DEFS
+    },
+    readOnly: false,
+    async handle(args, project) {
+      const kind = kindOf(args.kind);
+      const name = nameOf(args.name);
+      const declaration = args.declaration;
+      if (typeof declaration !== "object" || declaration === null || Array.isArray(declaration)) {
+        throw new ToolError("`declaration` must be a JSON object.");
+      }
+      const { spec, source } = await currentSpec(project);
+      const collection = COLLECTION_OF[kind];
+      const existing = spec[collection];
+      const next = {
+        ...spec,
+        [collection]: { ...existing ?? {}, [name]: declaration }
+      };
+      return saveIfValid(project, next, {
+        action: existing && name in existing ? "replaced" : "added",
+        kind,
+        name,
+        ...source === "app" ? {
+          note: "There was no afora.json: started from the spec extracted from the application."
+        } : {}
+      });
+    }
+  },
+  {
+    name: "afora_spec_remove",
+    description: "Removes ONE declaration from afora.json, validates the whole spec and writes only if it stays valid (so remove what depends on it first: a repository before its entity, an entity before the blueprint it uses is not needed, but anything referencing it must go or change).",
+    inputSchema: json(Type.Object({
+      kind: Type.Union(KINDS.map((kind) => Type.Literal(kind))),
+      name: Type.String()
+    }, { additionalProperties: false })),
+    readOnly: false,
+    async handle(args, project) {
+      const kind = kindOf(args.kind);
+      const name = nameOf(args.name);
+      const { spec } = await currentSpec(project);
+      const collection = COLLECTION_OF[kind];
+      const existing = spec[collection];
+      if (!existing || !(name in existing)) {
+        throw new ToolError(`There is no ${kind} named "${name}" in afora.json.`);
+      }
+      const { [name]: _removed, ...rest } = existing;
+      const next = { ...spec };
+      if (Object.keys(rest).length > 0)
+        next[collection] = rest;
+      else
+        delete next[collection];
+      return saveIfValid(project, next, {
+        action: "removed",
+        kind,
+        name
+      });
+    }
+  },
+  {
+    name: "afora_spec_write",
+    description: "Replaces the whole afora.json with `spec` (validated first; invalid specs are not written). Use it to create the spec in one go or to save one from afora_extract.",
+    inputSchema: {
+      type: "object",
+      properties: { spec: specInput() },
+      required: ["spec"],
+      additionalProperties: false,
+      $defs: FIELD_DEFS
+    },
+    readOnly: false,
+    async handle(args, project) {
+      return saveIfValid(project, asSpec(args.spec), { action: "replaced" });
+    }
+  },
+  {
+    name: "afora_generate",
+    description: "Generates the TypeScript from afora.json. With dryRun: true returns the files (path and contents) and writes nothing. Otherwise writes them under output.dir (overwriting or removing only files that carry the 'Generated by @afora/codegen' banner; anything else makes it refuse and write nothing), then runs `bunx tsc --noEmit -p <project>` if the project has a tsconfig.json and returns only the diagnostics of the generated files. Fix the spec, not the generated files.",
+    inputSchema: json(Type.Object({
+      dryRun: Type.Optional(Type.Boolean({ description: "Return the files without writing." })),
+      typecheck: Type.Optional(Type.Boolean({
+        description: "Run tsc after writing. Default true."
+      }))
+    }, { additionalProperties: false })),
+    readOnly: false,
+    async handle(args, project) {
+      const spec = await readSpec(project);
+      if (!spec) {
+        throw new ToolError("There is no afora.json to generate from. Create it with afora_spec_write or afora_spec_upsert.");
+      }
+      const { extended, issues } = await validateInProject(project, spec);
+      if (issues.length > 0)
+        return { generated: false, ...issuesResult(issues) };
+      let files;
+      try {
+        files = generate(spec, extended, codegenOptionsOf(project));
+      } catch (error) {
+        if (error instanceof InvalidSpecError) {
+          return { generated: false, ...issuesResult([...error.issues]) };
+        }
+        throw error;
+      }
+      if (args.dryRun === true) {
+        const preview = await writeGenerated(project.root, files, {
+          dryRun: true
+        });
+        return {
+          generated: true,
+          dryRun: true,
+          files,
+          wouldRemove: preview.removed,
+          refused: preview.refused
+        };
+      }
+      const result = await writeGenerated(project.root, files);
+      if (result.refused.length > 0) {
+        return {
+          generated: false,
+          refused: result.refused,
+          hint: "Nothing was written. These files exist and are not generated ones (no banner), or are outside the project. Change output.dir or move them."
+        };
+      }
+      const check = args.typecheck === false ? { ran: false, reason: "Skipped (typecheck: false)." } : await typecheck(project.root, files.map((file) => file.path));
+      return {
+        generated: true,
+        written: result.written,
+        unchanged: result.unchanged,
+        removed: result.removed,
+        typecheck: check
+      };
+    }
+  }
+];
+
+// src/server.ts
+var RESOURCES = [
+  {
+    uri: "afora://spec/schema",
+    name: "afora.json JSON Schema",
+    description: "The JSON Schema of afora.json (version 1).",
+    mimeType: "application/json",
+    read: () => JSON.stringify(specSchema2, null, 2)
+  },
+  {
+    uri: "afora://catalog",
+    name: "afora catalog",
+    description: "Std properties and their `with` options, record plugins, reserved keys and repository rules, read from @afora/core.",
+    mimeType: "application/json",
+    read: () => JSON.stringify(catalog2(), null, 2)
+  },
+  {
+    uri: "afora://spec/guide",
+    name: "afora.json guide",
+    description: "A short guide to writing afora.json: workflow, shape, fields and the rules the validator enforces.",
+    mimeType: "text/markdown",
+    read: () => GUIDE
+  }
+];
+async function createServer(options = {}) {
+  const project = await openProject(options.project ?? process.cwd(), options.app, options.providers, options.stages);
+  const server = new Server({ name: "afora", version: "0.0.1" }, {
+    capabilities: { tools: {}, resources: {} },
+    instructions: "Builds a domain from an afora.json: afora_catalog to see what exists, afora_spec_read, then afora_spec_upsert (one declaration at a time) or afora_spec_write, afora_spec_validate and afora_generate. Read the resource afora://spec/guide for the format and rules. Never edit the generated files; change the spec."
+  });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: {
+        readOnlyHint: tool.readOnly,
+        destructiveHint: false,
+        openWorldHint: false
+      }
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.find((candidate) => candidate.name === request.params.name);
+    if (!tool) {
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: `Unknown tool "${request.params.name}".` }
+        ]
+      };
+    }
+    try {
+      const result = await tool.handle(request.params.arguments ?? {}, project);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (error) {
+      const message = error instanceof ToolError || error instanceof Error ? error.message : String(error);
+      return { isError: true, content: [{ type: "text", text: message }] };
+    }
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: RESOURCES.map(({ uri, name, description, mimeType }) => ({
+      uri,
+      name,
+      description,
+      mimeType
+    }))
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const resource = RESOURCES.find((candidate) => candidate.uri === request.params.uri);
+    if (!resource)
+      throw new Error(`Unknown resource ${request.params.uri}.`);
+    return {
+      contents: [
+        {
+          uri: resource.uri,
+          mimeType: resource.mimeType,
+          text: resource.read()
+        }
+      ]
+    };
+  });
+  return server;
+}
+// src/sink.ts
+import {
+  InvalidOutputStage,
+  outputValueOf,
+  problemOf,
+  sinkOf,
+  stageCatalogOf,
+  statusOf,
+  toOpenAPI
+} from "@afora/core";
+import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema as CallToolRequestSchema2,
+  ListToolsRequestSchema as ListToolsRequestSchema2
+} from "@modelcontextprotocol/sdk/types.js";
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function validate(options) {
+  const given = options;
+  for (const key of Object.keys(given)) {
+    if (!["name", "version", "prefix", "include", "context"].includes(key)) {
+      return `mcpTools has no option "${key}".`;
+    }
+  }
+  for (const key of ["name", "version"]) {
+    if (typeof given[key] !== "string" || given[key] === "") {
+      return `Expected mcpTools.${key} to be a non-empty string.`;
+    }
+  }
+  const { prefix, include, context } = given;
+  if (prefix !== undefined && (typeof prefix !== "string" || !/^[A-Za-z0-9_.-]*$/.test(prefix))) {
+    return "Expected mcpTools.prefix to use only letters, digits, _, . and -.";
+  }
+  if (include !== undefined && (!Array.isArray(include) || include.some((id) => typeof id !== "string" || id === ""))) {
+    return "Expected mcpTools.include to be a list of operation ids.";
+  }
+  if (context !== undefined) {
+    if (!isObject(context))
+      return "Expected mcpTools.context to be an object.";
+    for (const [key, name] of Object.entries(context)) {
+      if (typeof name !== "string" || name === "") {
+        return `Expected mcpTools.context["${key}"] to be a value name.`;
+      }
+    }
+  }
+  return;
+}
+var kebab = (text) => text.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9_.-]+/g, "_").toLowerCase();
+function scalarTypesOf(blueprint) {
+  const schema = toOpenAPI(blueprint);
+  const types = {};
+  for (const [key, property] of Object.entries(schema.properties ?? {})) {
+    types[key] = [property.type ?? []].flat();
+  }
+  return types;
+}
+function coerce(text, types) {
+  if (!types || types.includes("string"))
+    return text;
+  const trimmed = text.trim();
+  if (types.includes("boolean") && (trimmed === "true" || trimmed === "false")) {
+    return trimmed === "true";
+  }
+  if (types.includes("integer") || types.includes("number")) {
+    const number = trimmed === "" ? Number.NaN : Number(trimmed);
+    if (Number.isFinite(number))
+      return number;
+  }
+  return text;
+}
+var text = (value, isError) => ({
+  ...isError ? { isError } : {},
+  content: [{ type: "text", text: JSON.stringify(value) }]
+});
+var mcpTools = sinkOf({
+  name: "mcpTools",
+  validate,
+  build: (operations, options, { output }) => {
+    const prefix = options.prefix ?? "";
+    const mapping = options.context ?? {};
+    const include = options.include;
+    if (include) {
+      const known = new Set(operations.map((operation) => operation.id));
+      const unknown = include.find((id) => !known.has(id));
+      if (unknown !== undefined) {
+        throw new InvalidOutputStage({
+          source: "mcpTools",
+          details: {
+            reason: `mcpTools.include names "${unknown}", which is not an operation.`
+          }
+        });
+      }
+    }
+    const entries = new Map;
+    for (const operation of operations) {
+      if (include && !include.includes(operation.id))
+        continue;
+      const name = `${prefix}${kebab(operation.command)}_${kebab(operation.name)}`;
+      if (name.length > 128 || entries.has(name)) {
+        throw new InvalidOutputStage({
+          source: "mcpTools",
+          details: {
+            reason: `mcpTools tool name "${name}" of ${operation.id} is duplicated or longer than 128 characters.`
+          }
+        });
+      }
+      const schema = toOpenAPI(operation.input);
+      const description = [
+        operation.description ?? `${operation.command}.${operation.name}`,
+        operation.deprecated ? "Deprecated." : undefined
+      ].filter(Boolean).join(" ");
+      entries.set(name, {
+        operation,
+        definition: Object.freeze({
+          name,
+          description,
+          inputSchema: {
+            ...schema,
+            type: "object"
+          },
+          operation: operation.id
+        })
+      });
+    }
+    const tools = [...entries.values()].map((entry) => entry.definition);
+    const call = async (name, args, extra) => {
+      const entry = entries.get(name);
+      if (!entry) {
+        return text({
+          type: "urn:afora:exception:NotFound",
+          title: "NotFound",
+          status: 404,
+          detail: `Unknown tool "${name}".`
+        }, true);
+      }
+      const { operation } = entry;
+      const options_ = {};
+      if (operation.context) {
+        const types = scalarTypesOf(operation.context);
+        const context = {};
+        for (const key of Object.keys(operation.context.properties)) {
+          const source = mapping[key];
+          const value = source === undefined ? undefined : extra?.values?.[source];
+          if (value !== undefined)
+            context[key] = coerce(value, types[key]);
+        }
+        options_.context = context;
+      }
+      try {
+        const response = await operation.invoke(args ?? {}, options_);
+        return text(outputValueOf(response) ?? null);
+      } catch (error) {
+        const status = statusOf(error, operation, output.statuses);
+        return text(problemOf(error, { status }), true);
+      }
+    };
+    const register = (server) => {
+      server.setRequestHandler(ListToolsRequestSchema2, async () => ({
+        tools: tools.map(({ name, description, inputSchema }) => ({
+          name,
+          description,
+          inputSchema
+        }))
+      }));
+      server.setRequestHandler(CallToolRequestSchema2, async (request, extra) => {
+        const values = {};
+        const meta = request.params._meta;
+        for (const [key, value] of Object.entries(meta ?? {})) {
+          if (typeof value === "string")
+            values[key] = value;
+        }
+        const headers = extra.requestInfo?.headers ?? {};
+        for (const [key, value] of Object.entries(headers)) {
+          const one = Array.isArray(value) ? value[0] : value;
+          if (one !== undefined)
+            values[key.toLowerCase()] = one;
+        }
+        const result = await call(request.params.name, request.params.arguments, { values });
+        return { ...result, content: [...result.content] };
+      });
+      return server;
+    };
+    return {
+      tools,
+      call,
+      register,
+      server: () => register(new Server2({ name: options.name, version: options.version }, { capabilities: { tools: {} } }))
+    };
+  }
+});
+var McpStages = stageCatalogOf(mcpTools);
+var stages = [
+  {
+    name: "mcpTools",
+    module: "@afora/mcp",
+    export: "mcpTools",
+    kind: "sink"
+  }
+];
+export {
+  GUIDE,
+  McpStages,
+  createServer,
+  mcpTools,
+  parseDiagnostics,
+  stages,
+  tools
+};