@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/mcp/api-key-manager.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/mcp/api-key-manager.ts"],
-  "sourcesContent": ["/**\n * MCP API key lifecycle management\n *\n * The API key is a per-installation shared secret that authenticates MCP client\n * connections to `dr mcp` (see cli/src/commands/mcp.ts). It is generated once,\n * stored on disk at a user-chosen location, and its path is recorded under\n * `mcp.api_key_path` in ~/.dr-config.yaml so subsequent launches can find it\n * without re-prompting.\n */\n\nimport { randomBytes, timingSafeEqual } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { chmod, mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { DRConfig, DRConfigParseError, loadDRConfig, saveDRConfig } from \"../config.js\";\n\n/** Owner read/write only \u2014 the key file must not be group/world readable. */\nconst KEY_FILE_MODE = 0o600;\n\n/**\n * Default location for a newly generated API key. Resolved lazily (rather than\n * cached at module load) so it always reflects the current home directory \u2014\n * relevant for tests that override HOME.\n */\nexport function getDefaultApiKeyPath(): string {\n  return join(homedir(), \".dr-mcp-key\");\n}\n\nexport interface EnsureKeyResult {\n  key: string;\n  path: string;\n  /** True when a new key was generated on this call (vs. loaded from an existing path). */\n  isNew: boolean;\n}\n\nexport interface RotateKeyResult {\n  key: string;\n  path: string;\n}\n\n/** Prompts the user for a storage path, given the default path to offer. */\nexport type ApiKeyStoragePrompt = (defaultPath: string) => Promise<string>;\n\nexport class ApiKeyManager {\n  /**\n   * @param defaultKeyPath Path offered as the default storage location when no\n   *   key is yet configured. Defaults to `getDefaultApiKeyPath()`; overridable\n   *   for tests so they never touch the real home directory.\n   */\n  constructor(private readonly defaultKeyPath: string = getDefaultApiKeyPath()) {}\n\n  /** Generate a new random API key. */\n  generate(): string {\n    return `dr-mcp-${randomBytes(32).toString(\"base64url\")}`;\n  }\n\n  /** Read a previously stored key from disk. */\n  async load(path: string): Promise<string> {\n    const content = await readFile(path, \"utf-8\");\n    const key = content.trim();\n\n    if (!key) {\n      throw new Error(\n        `API key file at ${path} is empty or corrupt. ` +\n          \"Delete it and re-run to generate a new key, or restore a valid key file.\"\n      );\n    }\n\n    return key;\n  }\n\n  /** Write a key to disk with owner-only permissions. */\n  async store(path: string, key: string): Promise<void> {\n    await mkdir(dirname(path), { recursive: true });\n    await writeFile(path, `${key}\\n`, { mode: KEY_FILE_MODE });\n    // writeFile's mode is only applied when creating a new file; force it\n    // in case the file already existed with different permissions.\n    await chmod(path, KEY_FILE_MODE);\n  }\n\n  /** Constant-time comparison of a client-provided key against the expected key. */\n  validate(provided: string | undefined | null, expected: string): boolean {\n    if (!provided) return false;\n\n    const providedBuf = Buffer.from(provided);\n    const expectedBuf = Buffer.from(expected);\n    if (providedBuf.length !== expectedBuf.length) return false;\n\n    return timingSafeEqual(providedBuf, expectedBuf);\n  }\n\n  /**\n   * Load the DR config, refusing to proceed if the file exists but is\n   * corrupted. Without this, a corrupted config looks identical to \"no key\n   * configured yet\", which would cause `ensureKey`/`rotate` to silently\n   * generate a new key and overwrite `mcp.api_key_path` \u2014 orphaning any\n   * valid key already on disk and breaking every MCP client configured with\n   * the old one.\n   */\n  private async loadConfigOrThrow(): Promise<DRConfig> {\n    try {\n      return await loadDRConfig({ strict: true });\n    } catch (error) {\n      if (error instanceof DRConfigParseError) {\n        throw new Error(\n          `Cannot determine the configured MCP API key path: ${error.configPath} is corrupted. ` +\n            \"Fix or remove this file before continuing \u2014 proceeding could orphan an existing key \" +\n            \"and break already-configured MCP clients.\",\n          { cause: error }\n        );\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Resolve the API key to use for this session: load it from the previously\n   * configured path, or generate+store a new one on first use.\n   *\n   * @param promptForPath Called only when no key is yet configured, to ask the\n   *   user where to store it. When omitted (e.g. non-interactive launches),\n   *   `defaultKeyPath` is used without prompting.\n   */\n  async ensureKey(promptForPath?: ApiKeyStoragePrompt): Promise<EnsureKeyResult> {\n    const config = await this.loadConfigOrThrow();\n    const existingPath = config.mcp?.api_key_path;\n\n    if (existingPath && existsSync(existingPath)) {\n      const key = await this.load(existingPath);\n      return { key, path: existingPath, isNew: false };\n    }\n\n    const chosenPath = promptForPath\n      ? await promptForPath(this.defaultKeyPath)\n      : this.defaultKeyPath;\n\n    const key = this.generate();\n    await this.store(chosenPath, key);\n    await saveDRConfig({\n      ...config,\n      mcp: { ...config.mcp, api_key_path: chosenPath },\n    });\n\n    return { key, path: chosenPath, isNew: true };\n  }\n\n  /**\n   * Force-generate a new API key, overwriting whatever is at the configured\n   * (or default) storage path, regardless of whether a key already exists\n   * there. Unlike `ensureKey`, this always writes a fresh key.\n   *\n   * @param promptForPath Called only when no storage path is yet configured,\n   *   to ask the user where to store it. When omitted, `defaultKeyPath` is\n   *   used without prompting.\n   */\n  async rotate(promptForPath?: ApiKeyStoragePrompt): Promise<RotateKeyResult> {\n    const config = await this.loadConfigOrThrow();\n    const path =\n      config.mcp?.api_key_path ??\n      (promptForPath ? await promptForPath(this.defaultKeyPath) : this.defaultKeyPath);\n\n    const key = this.generate();\n    await this.store(path, key);\n    await saveDRConfig({\n      ...config,\n      mcp: { ...config.mcp, api_key_path: path },\n    });\n\n    return { key, path };\n  }\n}\n"],
-  "mappings": "AAUA,SAAS,aAAa,uBAAuB;AAC7C,SAAS,kBAAkB;AAC3B,SAAS,OAAO,OAAO,UAAU,iBAAiB;AAClD,SAAS,eAAe;AACxB,SAAS,SAAS,YAAY;AAC9B,SAAmB,oBAAoB,cAAc,oBAAoB;AAGzE,MAAM,gBAAgB;AAOhB,SAAU,uBAAoB;AAClC,SAAO,KAAK,QAAO,GAAI,aAAa;AACtC;AAiBM,MAAO,cAAa;EAMK;;;;;;EAA7B,YAA6B,iBAAyB,qBAAoB,GAAE;AAA/C,SAAA,iBAAA;EAAkD;;EAG/E,WAAQ;AACN,WAAO,UAAU,YAAY,EAAE,EAAE,SAAS,WAAW,CAAC;EACxD;;EAGA,MAAM,KAAK,MAAY;AAErB,UAAM,OADU,MAAM,SAAS,MAAM,OAAO,GACxB,KAAI;AAExB,QAAI,CAAC;AACH,YAAM,IAAI,MACR,mBAAmB,IAAI,gGACqD;AAIhF,WAAO;EACT;;EAGA,MAAM,MAAM,MAAc,KAAW;AACnC,UAAM,MAAM,QAAQ,IAAI,GAAG,EAAE,WAAW,GAAI,CAAE,GAC9C,MAAM,UAAU,MAAM,GAAG,GAAG;GAAM,EAAE,MAAM,cAAa,CAAE,GAGzD,MAAM,MAAM,MAAM,aAAa;EACjC;;EAGA,SAAS,UAAqC,UAAgB;AAC5D,QAAI,CAAC;AAAU,aAAO;AAEtB,UAAM,cAAc,OAAO,KAAK,QAAQ,GAClC,cAAc,OAAO,KAAK,QAAQ;AACxC,WAAI,YAAY,WAAW,YAAY,SAAe,KAE/C,gBAAgB,aAAa,WAAW;EACjD;;;;;;;;;EAUQ,MAAM,oBAAiB;AAC7B,QAAI;AACF,aAAO,MAAM,aAAa,EAAE,QAAQ,GAAI,CAAE;IAC5C,SAAS,OAAO;AACd,YAAI,iBAAiB,qBACb,IAAI,MACR,qDAAqD,MAAM,UAAU,qJAGrE,EAAE,OAAO,MAAK,CAAE,IAGd;IACR;EACF;;;;;;;;;EAUA,MAAM,UAAU,eAAmC;AACjD,UAAM,SAAS,MAAM,KAAK,kBAAiB,GACrC,eAAe,OAAO,KAAK;AAEjC,QAAI,gBAAgB,WAAW,YAAY;AAEzC,aAAO,EAAE,KADG,MAAM,KAAK,KAAK,YAAY,GAC1B,MAAM,cAAc,OAAO,GAAK;AAGhD,UAAM,aAAa,gBACf,MAAM,cAAc,KAAK,cAAc,IACvC,KAAK,gBAEH,MAAM,KAAK,SAAQ;AACzB,iBAAM,KAAK,MAAM,YAAY,GAAG,GAChC,MAAM,aAAa;MACjB,GAAG;MACH,KAAK,EAAE,GAAG,OAAO,KAAK,cAAc,WAAU;KAC/C,GAEM,EAAE,KAAK,MAAM,YAAY,OAAO,GAAI;EAC7C;;;;;;;;;;EAWA,MAAM,OAAO,eAAmC;AAC9C,UAAM,SAAS,MAAM,KAAK,kBAAiB,GACrC,OACJ,OAAO,KAAK,iBACX,gBAAgB,MAAM,cAAc,KAAK,cAAc,IAAI,KAAK,iBAE7D,MAAM,KAAK,SAAQ;AACzB,iBAAM,KAAK,MAAM,MAAM,GAAG,GAC1B,MAAM,aAAa;MACjB,GAAG;MACH,KAAK,EAAE,GAAG,OAAO,KAAK,cAAc,KAAI;KACzC,GAEM,EAAE,KAAK,KAAI;EACpB;;",
+  "sourcesContent": ["/**\n * MCP API key lifecycle management\n *\n * The API key is a per-installation shared secret that authenticates MCP client\n * connections to `dr mcp` (see cli/src/commands/mcp.ts). It is generated once,\n * stored on disk at a user-chosen location, and its path is recorded under\n * `mcp.api_key_path` in ~/.dr-config.yaml so subsequent launches can find it\n * without re-prompting.\n */\n\nimport { randomBytes, timingSafeEqual } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { chmod, mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { DRConfig, DRConfigParseError, loadDRConfig, saveDRConfig } from \"../config.js\";\n\n/** Owner read/write only \u2014 the key file must not be group/world readable. */\nconst KEY_FILE_MODE = 0o600;\n\n/**\n * Default location for a newly generated API key. Resolved lazily (rather than\n * cached at module load) so it always reflects the current home directory \u2014\n * relevant for tests that override HOME.\n */\nexport function getDefaultApiKeyPath(): string {\n  return join(homedir(), \".dr-mcp-key\");\n}\n\nexport interface EnsureKeyResult {\n  key: string;\n  path: string;\n  /** True when a new key was generated on this call (vs. loaded from an existing path). */\n  isNew: boolean;\n}\n\nexport interface RotateKeyResult {\n  key: string;\n  path: string;\n}\n\n/** Prompts the user for a storage path, given the default path to offer. */\nexport type ApiKeyStoragePrompt = (defaultPath: string) => Promise<string>;\n\nexport class ApiKeyManager {\n  /**\n   * @param defaultKeyPath Path offered as the default storage location when no\n   *   key is yet configured. Defaults to `getDefaultApiKeyPath()`; overridable\n   *   for tests so they never touch the real home directory.\n   */\n  constructor(private readonly defaultKeyPath: string = getDefaultApiKeyPath()) {}\n\n  /** Generate a new random API key. */\n  generate(): string {\n    return `dr-mcp-${randomBytes(32).toString(\"base64url\")}`;\n  }\n\n  /** Read a previously stored key from disk. */\n  async load(path: string): Promise<string> {\n    const content = await readFile(path, \"utf-8\");\n    const key = content.trim();\n\n    if (!key) {\n      throw new Error(\n        `API key file at ${path} is empty or corrupt. ` +\n          \"Delete it and re-run to generate a new key, or restore a valid key file.\"\n      );\n    }\n\n    return key;\n  }\n\n  /** The key stored at `path`, or null when there is no usable key file there. */\n  private async loadIfPresent(path: string): Promise<string | null> {\n    if (!existsSync(path)) return null;\n    try {\n      return await this.load(path);\n    } catch {\n      // Empty or unreadable: ensureKey replaces it with a fresh key, as it always has.\n      return null;\n    }\n  }\n\n  /** Write a key to disk with owner-only permissions. */\n  async store(path: string, key: string): Promise<void> {\n    await mkdir(dirname(path), { recursive: true });\n    await writeFile(path, `${key}\\n`, { mode: KEY_FILE_MODE });\n    // writeFile's mode is only applied when creating a new file; force it\n    // in case the file already existed with different permissions.\n    await chmod(path, KEY_FILE_MODE);\n  }\n\n  /** Constant-time comparison of a client-provided key against the expected key. */\n  validate(provided: string | undefined | null, expected: string): boolean {\n    if (!provided) return false;\n\n    const providedBuf = Buffer.from(provided);\n    const expectedBuf = Buffer.from(expected);\n    if (providedBuf.length !== expectedBuf.length) return false;\n\n    return timingSafeEqual(providedBuf, expectedBuf);\n  }\n\n  /**\n   * Load the DR config, refusing to proceed if the file exists but is\n   * corrupted. Without this, a corrupted config looks identical to \"no key\n   * configured yet\", which would cause `ensureKey`/`rotate` to silently\n   * generate a new key and overwrite `mcp.api_key_path` \u2014 orphaning any\n   * valid key already on disk and breaking every MCP client configured with\n   * the old one.\n   */\n  private async loadConfigOrThrow(): Promise<DRConfig> {\n    try {\n      return await loadDRConfig({ strict: true });\n    } catch (error) {\n      if (error instanceof DRConfigParseError) {\n        throw new Error(\n          `Cannot determine the configured MCP API key path: ${error.configPath} is corrupted. ` +\n            \"Fix or remove this file before continuing \u2014 proceeding could orphan an existing key \" +\n            \"and break already-configured MCP clients.\",\n          { cause: error }\n        );\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Resolve the API key to use for this session: load it from the previously\n   * configured path, or generate+store a new one on first use.\n   *\n   * @param promptForPath Called only when no key is yet configured, to ask the\n   *   user where to store it. When omitted (e.g. non-interactive launches),\n   *   `defaultKeyPath` is used without prompting.\n   */\n  async ensureKey(promptForPath?: ApiKeyStoragePrompt): Promise<EnsureKeyResult> {\n    const config = await this.loadConfigOrThrow();\n    const existingPath = config.mcp?.api_key_path;\n\n    if (existingPath && existsSync(existingPath)) {\n      const key = await this.load(existingPath);\n      return { key, path: existingPath, isNew: false };\n    }\n\n    const chosenPath = promptForPath\n      ? await promptForPath(this.defaultKeyPath)\n      : this.defaultKeyPath;\n\n    // A key already at the chosen path (e.g. the config was removed or never written) is\n    // adopted rather than overwritten: overwriting it would break every MCP client already\n    // configured with it.\n    const adopted = await this.loadIfPresent(chosenPath);\n    if (adopted) {\n      await saveDRConfig({ ...config, mcp: { ...config.mcp, api_key_path: chosenPath } });\n      return { key: adopted, path: chosenPath, isNew: false };\n    }\n\n    const key = this.generate();\n    await this.store(chosenPath, key);\n    await saveDRConfig({\n      ...config,\n      mcp: { ...config.mcp, api_key_path: chosenPath },\n    });\n\n    return { key, path: chosenPath, isNew: true };\n  }\n\n  /**\n   * Force-generate a new API key, overwriting whatever is at the configured\n   * (or default) storage path, regardless of whether a key already exists\n   * there. Unlike `ensureKey`, this always writes a fresh key.\n   *\n   * @param promptForPath Called only when no storage path is yet configured,\n   *   to ask the user where to store it. When omitted, `defaultKeyPath` is\n   *   used without prompting.\n   */\n  async rotate(promptForPath?: ApiKeyStoragePrompt): Promise<RotateKeyResult> {\n    const config = await this.loadConfigOrThrow();\n    const path =\n      config.mcp?.api_key_path ??\n      (promptForPath ? await promptForPath(this.defaultKeyPath) : this.defaultKeyPath);\n\n    const key = this.generate();\n    await this.store(path, key);\n    await saveDRConfig({\n      ...config,\n      mcp: { ...config.mcp, api_key_path: path },\n    });\n\n    return { key, path };\n  }\n}\n"],
+  "mappings": "AAUA,SAAS,aAAa,uBAAuB;AAC7C,SAAS,kBAAkB;AAC3B,SAAS,OAAO,OAAO,UAAU,iBAAiB;AAClD,SAAS,eAAe;AACxB,SAAS,SAAS,YAAY;AAC9B,SAAmB,oBAAoB,cAAc,oBAAoB;AAGzE,MAAM,gBAAgB;AAOhB,SAAU,uBAAoB;AAClC,SAAO,KAAK,QAAO,GAAI,aAAa;AACtC;AAiBM,MAAO,cAAa;EAMK;;;;;;EAA7B,YAA6B,iBAAyB,qBAAoB,GAAE;AAA/C,SAAA,iBAAA;EAAkD;;EAG/E,WAAQ;AACN,WAAO,UAAU,YAAY,EAAE,EAAE,SAAS,WAAW,CAAC;EACxD;;EAGA,MAAM,KAAK,MAAY;AAErB,UAAM,OADU,MAAM,SAAS,MAAM,OAAO,GACxB,KAAI;AAExB,QAAI,CAAC;AACH,YAAM,IAAI,MACR,mBAAmB,IAAI,gGACqD;AAIhF,WAAO;EACT;;EAGQ,MAAM,cAAc,MAAY;AACtC,QAAI,CAAC,WAAW,IAAI;AAAG,aAAO;AAC9B,QAAI;AACF,aAAO,MAAM,KAAK,KAAK,IAAI;IAC7B,QAAQ;AAEN,aAAO;IACT;EACF;;EAGA,MAAM,MAAM,MAAc,KAAW;AACnC,UAAM,MAAM,QAAQ,IAAI,GAAG,EAAE,WAAW,GAAI,CAAE,GAC9C,MAAM,UAAU,MAAM,GAAG,GAAG;GAAM,EAAE,MAAM,cAAa,CAAE,GAGzD,MAAM,MAAM,MAAM,aAAa;EACjC;;EAGA,SAAS,UAAqC,UAAgB;AAC5D,QAAI,CAAC;AAAU,aAAO;AAEtB,UAAM,cAAc,OAAO,KAAK,QAAQ,GAClC,cAAc,OAAO,KAAK,QAAQ;AACxC,WAAI,YAAY,WAAW,YAAY,SAAe,KAE/C,gBAAgB,aAAa,WAAW;EACjD;;;;;;;;;EAUQ,MAAM,oBAAiB;AAC7B,QAAI;AACF,aAAO,MAAM,aAAa,EAAE,QAAQ,GAAI,CAAE;IAC5C,SAAS,OAAO;AACd,YAAI,iBAAiB,qBACb,IAAI,MACR,qDAAqD,MAAM,UAAU,qJAGrE,EAAE,OAAO,MAAK,CAAE,IAGd;IACR;EACF;;;;;;;;;EAUA,MAAM,UAAU,eAAmC;AACjD,UAAM,SAAS,MAAM,KAAK,kBAAiB,GACrC,eAAe,OAAO,KAAK;AAEjC,QAAI,gBAAgB,WAAW,YAAY;AAEzC,aAAO,EAAE,KADG,MAAM,KAAK,KAAK,YAAY,GAC1B,MAAM,cAAc,OAAO,GAAK;AAGhD,UAAM,aAAa,gBACf,MAAM,cAAc,KAAK,cAAc,IACvC,KAAK,gBAKH,UAAU,MAAM,KAAK,cAAc,UAAU;AACnD,QAAI;AACF,mBAAM,aAAa,EAAE,GAAG,QAAQ,KAAK,EAAE,GAAG,OAAO,KAAK,cAAc,WAAU,EAAE,CAAE,GAC3E,EAAE,KAAK,SAAS,MAAM,YAAY,OAAO,GAAK;AAGvD,UAAM,MAAM,KAAK,SAAQ;AACzB,iBAAM,KAAK,MAAM,YAAY,GAAG,GAChC,MAAM,aAAa;MACjB,GAAG;MACH,KAAK,EAAE,GAAG,OAAO,KAAK,cAAc,WAAU;KAC/C,GAEM,EAAE,KAAK,MAAM,YAAY,OAAO,GAAI;EAC7C;;;;;;;;;;EAWA,MAAM,OAAO,eAAmC;AAC9C,UAAM,SAAS,MAAM,KAAK,kBAAiB,GACrC,OACJ,OAAO,KAAK,iBACX,gBAAgB,MAAM,cAAc,KAAK,cAAc,IAAI,KAAK,iBAE7D,MAAM,KAAK,SAAQ;AACzB,iBAAM,KAAK,MAAM,MAAM,GAAG,GAC1B,MAAM,aAAa;MACjB,GAAG;MACH,KAAK,EAAE,GAAG,OAAO,KAAK,cAAc,KAAI;KACzC,GAEM,EAAE,KAAK,KAAI;EACpB;;",
   "names": []
 }

package/dist/mcp/changeset-only.js

@@ -0,0 +1,34 @@
+import { isChangesetOnly, CHANGESET_ONLY_ENV } from "../core/changeset-only-guard.js";
+import { StagingAreaManager } from "../core/staging-area.js";
+import { CLIError, ErrorCategory, getErrorMessage } from "../utils/errors.js";
+import { activeStagedChangeset } from "./tools/changeset-shared.js";
+const BASE_MODEL_WRITE_TOOLS = /* @__PURE__ */ new Set([
+  "model_add",
+  "model_update",
+  "model_delete",
+  "relationship_add",
+  "relationship_delete"
+]);
+function changesetOnlyError(toolName) {
+  const retry = toolName ? `Then call "${toolName}" again` : "Then retry the call";
+  return new CLIError("This session can only change the model through a changeset, and no changeset is active.", ErrorCategory.USER, [
+    'Call "changeset_create" with a name for the change (it activates the new changeset), or "changeset_activate" to resume one from "changeset_list"',
+    `${retry}: it will be staged in the changeset for the user to review and commit`
+  ], { operation: toolName ?? "save model", context: `${CHANGESET_ONLY_ENV}=${process.env[CHANGESET_ONLY_ENV] ?? "true"}` });
+}
+async function changesetOnlyRefusal(toolName, rootPath, loadModel, env = process.env) {
+  if (!isChangesetOnly(env) || !BASE_MODEL_WRITE_TOOLS.has(toolName))
+    return null;
+  try {
+    const model = await loadModel(rootPath);
+    return await activeStagedChangeset(new StagingAreaManager(model.rootPath, model)) ? null : changesetOnlyError(toolName);
+  } catch (error) {
+    return console.error(`[mcp] changeset-only check for ${toolName} skipped: ${getErrorMessage(error)}`), null;
+  }
+}
+export {
+  BASE_MODEL_WRITE_TOOLS,
+  changesetOnlyError,
+  changesetOnlyRefusal
+};
+//# sourceMappingURL=changeset-only.js.map

package/dist/mcp/changeset-only.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/mcp/changeset-only.ts"],
+  "sourcesContent": ["/**\n * Changeset-only mode on the MCP server.\n *\n * When `dr mcp` runs with DR_CHANGESET_ONLY=true (DrBot under `dr visualize --with-changesets`\n * starts it that way), an agent may change the model only by staging into an active changeset.\n * The tools below write the base model when no changeset is active, so the tool registry asks\n * `changesetOnlyRefusal()` before running them and returns its refusal instead: the agent is told\n * to call changeset_create (or changeset_activate) and retry.\n *\n * This check runs before the handler so a refused call never touches the cached in-memory model.\n * Any other base-model save still hits the core guard (core/changeset-only-guard.ts), whose\n * ChangesetOnlyError runTool turns into the same refusal, after dropping the model cache so a\n * half-applied in-memory edit can't linger.\n */\n\nimport type { Model } from \"../core/model.js\";\nimport { isChangesetOnly, CHANGESET_ONLY_ENV } from \"../core/changeset-only-guard.js\";\nimport { StagingAreaManager } from \"../core/staging-area.js\";\nimport { CLIError, ErrorCategory, getErrorMessage } from \"../utils/errors.js\";\nimport { activeStagedChangeset } from \"./tools/changeset-shared.js\";\n\n/** Tools that write the base model when no changeset is active. */\nexport const BASE_MODEL_WRITE_TOOLS: ReadonlySet<string> = new Set([\n  \"model_add\",\n  \"model_update\",\n  \"model_delete\",\n  \"relationship_add\",\n  \"relationship_delete\",\n]);\n\n/** The error an agent gets for a base-model write in changeset-only mode. */\nexport function changesetOnlyError(toolName?: string): CLIError {\n  const retry = toolName ? `Then call \"${toolName}\" again` : \"Then retry the call\";\n  return new CLIError(\n    \"This session can only change the model through a changeset, and no changeset is active.\",\n    ErrorCategory.USER,\n    [\n      'Call \"changeset_create\" with a name for the change (it activates the new changeset), or ' +\n        '\"changeset_activate\" to resume one from \"changeset_list\"',\n      `${retry}: it will be staged in the changeset for the user to review and commit`,\n    ],\n    { operation: toolName ?? \"save model\", context: `${CHANGESET_ONLY_ENV}=${process.env[CHANGESET_ONLY_ENV] ?? \"true\"}` }\n  );\n}\n\n/**\n * The refusal for this call, or null when it may run: always null outside changeset-only mode,\n * for tools that don't write the base model, and when a staged changeset is active.\n *\n * If the model or the active changeset can't be read, the check steps aside (null, logged) and\n * the tool reports that failure itself; the core guard still stops any base-model save.\n */\nexport async function changesetOnlyRefusal(\n  toolName: string,\n  rootPath: string | undefined,\n  loadModel: (rootPath?: string) => Promise<Model>,\n  env: NodeJS.ProcessEnv = process.env\n): Promise<CLIError | null> {\n  if (!isChangesetOnly(env) || !BASE_MODEL_WRITE_TOOLS.has(toolName)) {\n    return null;\n  }\n  try {\n    const model = await loadModel(rootPath);\n    const active = await activeStagedChangeset(new StagingAreaManager(model.rootPath, model));\n    return active ? null : changesetOnlyError(toolName);\n  } catch (error) {\n    console.error(`[mcp] changeset-only check for ${toolName} skipped: ${getErrorMessage(error)}`);\n    return null;\n  }\n}\n"],
+  "mappings": "AAgBA,SAAS,iBAAiB,0BAA0B;AACpD,SAAS,0BAA0B;AACnC,SAAS,UAAU,eAAe,uBAAuB;AACzD,SAAS,6BAA6B;AAG/B,MAAM,yBAA8C,oBAAI,IAAI;EACjE;EACA;EACA;EACA;EACA;CACD;AAGK,SAAU,mBAAmB,UAAiB;AAClD,QAAM,QAAQ,WAAW,cAAc,QAAQ,YAAY;AAC3D,SAAO,IAAI,SACT,2FACA,cAAc,MACd;IACE;IAEA,GAAG,KAAK;KAEV,EAAE,WAAW,YAAY,cAAc,SAAS,GAAG,kBAAkB,IAAI,QAAQ,IAAI,kBAAkB,KAAK,MAAM,GAAE,CAAE;AAE1H;AASA,eAAsB,qBACpB,UACA,UACA,WACA,MAAyB,QAAQ,KAAG;AAEpC,MAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC,uBAAuB,IAAI,QAAQ;AAC/D,WAAO;AAET,MAAI;AACF,UAAM,QAAQ,MAAM,UAAU,QAAQ;AAEtC,WADe,MAAM,sBAAsB,IAAI,mBAAmB,MAAM,UAAU,KAAK,CAAC,IACxE,OAAO,mBAAmB,QAAQ;EACpD,SAAS,OAAO;AACd,mBAAQ,MAAM,kCAAkC,QAAQ,aAAa,gBAAgB,KAAK,CAAC,EAAE,GACtF;EACT;AACF;",
+  "names": []
+}

package/dist/mcp/tool-registry.js

@@ -1,5 +1,9 @@
 import { isTelemetryEnabled, startActiveSpan } from "../telemetry/index.js";
-import { annotationCreateTool, annotationDeleteTool, annotationGetTool, annotationListTool, annotationReplyTool, annotationUpdateTool, changesetListTool, changesetShowTool, chatLaunchTool, chatStatusTool, modelAddTool, modelDeleteTool, modelExportTool, modelInfoTool, modelListTool, modelReloadTool, modelSearchTool, modelShowTool, modelStatsTool, modelTraceTool, modelUpdateTool, modelValidateTool } from "./tools/index.js";
+import { annotationCreateTool, annotationDeleteTool, annotationGetTool, annotationListTool, annotationReplyTool, annotationUpdateTool, changesetActivateTool, changesetBriefTool, changesetCreateTool, changesetDeactivateTool, changesetImpactTool, changesetListTool, changesetShowTool, chatLaunchTool, chatStatusTool, modelAddTool, modelDeleteTool, modelExportTool, modelInfoTool, modelListTool, modelReloadTool, modelSearchTool, modelShowTool, modelStatsTool, modelTraceTool, modelUpdateTool, modelValidateTool, relationshipAddTool, relationshipDeleteTool, specTypeTool } from "./tools/index.js";
+import { changesetDiscardTool, changesetUnstageTool, changesetUpdateTool } from "./tools/index.js";
+import { changesetVerifyTool } from "./tools/index.js";
+import { errorResult, loadModel } from "./tools/shared.js";
+import { changesetOnlyRefusal } from "./changeset-only.js";
 const MODEL_TOOLS = [
   modelListTool,
   modelShowTool,
@@ -15,6 +19,14 @@ const MODEL_TOOLS = [
   modelReloadTool,
   changesetListTool,
   changesetShowTool,
+  changesetCreateTool,
+  changesetActivateTool,
+  changesetDeactivateTool,
+  relationshipAddTool,
+  relationshipDeleteTool,
+  specTypeTool,
+  changesetImpactTool,
+  changesetBriefTool,
   chatStatusTool,
   chatLaunchTool,
   annotationListTool,
@@ -22,14 +34,18 @@ const MODEL_TOOLS = [
   annotationCreateTool,
   annotationUpdateTool,
   annotationDeleteTool,
-  annotationReplyTool
+  annotationReplyTool,
+  changesetUpdateTool,
+  changesetUnstageTool,
+  changesetDiscardTool,
+  changesetVerifyTool
 ];
 class McpToolRegistry {
   /** Registers every model tool onto the given MCP server instance. */
   registerAll(server) {
     for (const tool of MODEL_TOOLS)
       server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, (args) => startActiveSpan(`mcp.tool.${tool.name}`, async (span) => {
-        const result = await tool.handler(args);
+        const refusal = await changesetOnlyRefusal(tool.name, args.rootPath, loadModel), result = refusal ? errorResult(refusal) : await tool.handler(args);
         if (isTelemetryEnabled && result?.isError) {
           const firstContent = result.content?.[0], message = firstContent?.type === "text" ? firstContent.text : "Tool returned an error";
           span.setStatus({ code: 2, message });

package/dist/mcp/tool-registry.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/mcp/tool-registry.ts"],
-  "sourcesContent": ["/**\n * McpToolRegistry \u2014 registers the DR model tool surface onto an MCP server.\n *\n * Read-only tools: model_list, model_show, model_search, model_stats,\n * model_info, model_trace.\n * Mutation tools: model_add, model_update, model_delete (via MutationHandler).\n * Pipeline tools: model_validate, model_export (via the shared validator\n * pipeline and export handlers).\n * Lifecycle tools: model_reload (force a full re-read from disk).\n * Changeset tools: changeset_list, changeset_show (via StagingAreaManager).\n * Chat tools: chat_status, chat_launch (via the coding-agents chat clients).\n * Annotation tools: annotation_list, annotation_get, annotation_create,\n * annotation_update, annotation_delete, annotation_reply (via AnnotationStore),\n * mirroring the REST server's /api/annotations/* endpoints.\n */\n\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { isTelemetryEnabled, startActiveSpan } from \"../telemetry/index.js\";\nimport {\n  annotationCreateTool,\n  annotationDeleteTool,\n  annotationGetTool,\n  annotationListTool,\n  annotationReplyTool,\n  annotationUpdateTool,\n  changesetListTool,\n  changesetShowTool,\n  chatLaunchTool,\n  chatStatusTool,\n  modelAddTool,\n  modelDeleteTool,\n  modelExportTool,\n  modelInfoTool,\n  modelListTool,\n  modelReloadTool,\n  modelSearchTool,\n  modelShowTool,\n  modelStatsTool,\n  modelTraceTool,\n  modelUpdateTool,\n  modelValidateTool,\n  type McpToolDefinition,\n} from \"./tools/index.js\";\n\nconst MODEL_TOOLS: McpToolDefinition[] = [\n  modelListTool,\n  modelShowTool,\n  modelSearchTool,\n  modelStatsTool,\n  modelInfoTool,\n  modelTraceTool,\n  modelAddTool,\n  modelUpdateTool,\n  modelDeleteTool,\n  modelValidateTool,\n  modelExportTool,\n  modelReloadTool,\n  changesetListTool,\n  changesetShowTool,\n  chatStatusTool,\n  chatLaunchTool,\n  annotationListTool,\n  annotationGetTool,\n  annotationCreateTool,\n  annotationUpdateTool,\n  annotationDeleteTool,\n  annotationReplyTool,\n];\n\nexport class McpToolRegistry {\n  /** Registers every model tool onto the given MCP server instance. */\n  registerAll(server: McpServer): void {\n    for (const tool of MODEL_TOOLS) {\n      server.registerTool(\n        tool.name,\n        { description: tool.description, inputSchema: tool.inputSchema },\n        (args: Parameters<typeof tool.handler>[0]) =>\n          startActiveSpan(\n            `mcp.tool.${tool.name}`,\n            async (span) => {\n              const result = await tool.handler(args);\n              if (isTelemetryEnabled && result?.isError) {\n                const firstContent = result.content?.[0];\n                const message =\n                  firstContent?.type === \"text\" ? firstContent.text : \"Tool returned an error\";\n                span.setStatus({ code: 2, message });\n              }\n              return result;\n            },\n            { \"mcp.tool.name\": tool.name }\n          )\n      );\n    }\n  }\n}\n"],
-  "mappings": "AAiBA,SAAS,oBAAoB,uBAAuB;AACpD,SACE,sBACA,sBACA,mBACA,oBACA,qBACA,sBACA,mBACA,mBACA,gBACA,gBACA,cACA,iBACA,iBACA,eACA,eACA,iBACA,iBACA,eACA,gBACA,gBACA,iBACA,yBAEK;AAEP,MAAM,cAAmC;EACvC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAGI,MAAO,gBAAe;;EAE1B,YAAY,QAAiB;AAC3B,eAAW,QAAQ;AACjB,aAAO,aACL,KAAK,MACL,EAAE,aAAa,KAAK,aAAa,aAAa,KAAK,YAAW,GAC9D,CAAC,SACC,gBACE,YAAY,KAAK,IAAI,IACrB,OAAO,SAAQ;AACb,cAAM,SAAS,MAAM,KAAK,QAAQ,IAAI;AACtC,YAAI,sBAAsB,QAAQ,SAAS;AACzC,gBAAM,eAAe,OAAO,UAAU,CAAC,GACjC,UACJ,cAAc,SAAS,SAAS,aAAa,OAAO;AACtD,eAAK,UAAU,EAAE,MAAM,GAAG,QAAO,CAAE;QACrC;AACA,eAAO;MACT,GACA,EAAE,iBAAiB,KAAK,KAAI,CAAE,CAC/B;EAGT;;",
+  "sourcesContent": ["/**\n * McpToolRegistry \u2014 registers the DR model tool surface onto an MCP server.\n *\n * Read-only tools: model_list, model_show, model_search, model_stats,\n * model_info, model_trace.\n * Mutation tools: model_add, model_update, model_delete (via MutationHandler).\n * Pipeline tools: model_validate, model_export (via the shared validator\n * pipeline and export handlers).\n * Lifecycle tools: model_reload (force a full re-read from disk).\n * Changeset tools: changeset_list, changeset_show (via StagingAreaManager).\n * Change-modeling tools (docs/CHANGE_MODELING.md): changeset_create, changeset_activate,\n * changeset_deactivate, relationship_add, relationship_delete, spec_type, changeset_impact,\n * changeset_brief, changeset_verify. Commit and apply are deliberately not exposed: landing a change\n * is the human's step.\n * Changeset editing (changeset-editing.ts): changeset_update, changeset_unstage, and\n * changeset_discard (requires confirm: true; it deletes the staged changes).\n * Chat tools: chat_status, chat_launch (via the coding-agents chat clients).\n * Annotation tools: annotation_list, annotation_get, annotation_create,\n * annotation_update, annotation_delete, annotation_reply (via AnnotationStore),\n * mirroring the REST server's /api/annotations/* endpoints.\n */\n\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { isTelemetryEnabled, startActiveSpan } from \"../telemetry/index.js\";\nimport {\n  annotationCreateTool,\n  annotationDeleteTool,\n  annotationGetTool,\n  annotationListTool,\n  annotationReplyTool,\n  annotationUpdateTool,\n  changesetActivateTool,\n  changesetBriefTool,\n  changesetCreateTool,\n  changesetDeactivateTool,\n  changesetImpactTool,\n  changesetListTool,\n  changesetShowTool,\n  chatLaunchTool,\n  chatStatusTool,\n  modelAddTool,\n  modelDeleteTool,\n  modelExportTool,\n  modelInfoTool,\n  modelListTool,\n  modelReloadTool,\n  modelSearchTool,\n  modelShowTool,\n  modelStatsTool,\n  modelTraceTool,\n  modelUpdateTool,\n  modelValidateTool,\n  relationshipAddTool,\n  relationshipDeleteTool,\n  specTypeTool,\n  type McpToolDefinition,\n} from \"./tools/index.js\";\nimport { changesetDiscardTool, changesetUnstageTool, changesetUpdateTool } from \"./tools/index.js\";\nimport { changesetVerifyTool } from \"./tools/index.js\";\nimport { errorResult, loadModel } from \"./tools/shared.js\";\nimport { changesetOnlyRefusal } from \"./changeset-only.js\";\n\nconst MODEL_TOOLS: McpToolDefinition[] = [\n  modelListTool,\n  modelShowTool,\n  modelSearchTool,\n  modelStatsTool,\n  modelInfoTool,\n  modelTraceTool,\n  modelAddTool,\n  modelUpdateTool,\n  modelDeleteTool,\n  modelValidateTool,\n  modelExportTool,\n  modelReloadTool,\n  changesetListTool,\n  changesetShowTool,\n  changesetCreateTool,\n  changesetActivateTool,\n  changesetDeactivateTool,\n  relationshipAddTool,\n  relationshipDeleteTool,\n  specTypeTool,\n  changesetImpactTool,\n  changesetBriefTool,\n  chatStatusTool,\n  chatLaunchTool,\n  annotationListTool,\n  annotationGetTool,\n  annotationCreateTool,\n  annotationUpdateTool,\n  annotationDeleteTool,\n  annotationReplyTool,\n  changesetUpdateTool,\n  changesetUnstageTool,\n  changesetDiscardTool,\n  changesetVerifyTool,\n];\n\nexport class McpToolRegistry {\n  /** Registers every model tool onto the given MCP server instance. */\n  registerAll(server: McpServer): void {\n    for (const tool of MODEL_TOOLS) {\n      server.registerTool(\n        tool.name,\n        { description: tool.description, inputSchema: tool.inputSchema },\n        (args: Parameters<typeof tool.handler>[0]) =>\n          startActiveSpan(\n            `mcp.tool.${tool.name}`,\n            async (span) => {\n              // Changeset-only mode (DR_CHANGESET_ONLY): refuse base-model writes up front.\n              const refusal = await changesetOnlyRefusal(tool.name, (args as { rootPath?: string }).rootPath, loadModel);\n              const result = refusal ? errorResult(refusal) : await tool.handler(args);\n              if (isTelemetryEnabled && result?.isError) {\n                const firstContent = result.content?.[0];\n                const message =\n                  firstContent?.type === \"text\" ? firstContent.text : \"Tool returned an error\";\n                span.setStatus({ code: 2, message });\n              }\n              return result;\n            },\n            { \"mcp.tool.name\": tool.name }\n          )\n      );\n    }\n  }\n}\n"],
+  "mappings": "AAuBA,SAAS,oBAAoB,uBAAuB;AACpD,SACE,sBACA,sBACA,mBACA,oBACA,qBACA,sBACA,uBACA,oBACA,qBACA,yBACA,qBACA,mBACA,mBACA,gBACA,gBACA,cACA,iBACA,iBACA,eACA,eACA,iBACA,iBACA,eACA,gBACA,gBACA,iBACA,mBACA,qBACA,wBACA,oBAEK;AACP,SAAS,sBAAsB,sBAAsB,2BAA2B;AAChF,SAAS,2BAA2B;AACpC,SAAS,aAAa,iBAAiB;AACvC,SAAS,4BAA4B;AAErC,MAAM,cAAmC;EACvC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAGI,MAAO,gBAAe;;EAE1B,YAAY,QAAiB;AAC3B,eAAW,QAAQ;AACjB,aAAO,aACL,KAAK,MACL,EAAE,aAAa,KAAK,aAAa,aAAa,KAAK,YAAW,GAC9D,CAAC,SACC,gBACE,YAAY,KAAK,IAAI,IACrB,OAAO,SAAQ;AAEb,cAAM,UAAU,MAAM,qBAAqB,KAAK,MAAO,KAA+B,UAAU,SAAS,GACnG,SAAS,UAAU,YAAY,OAAO,IAAI,MAAM,KAAK,QAAQ,IAAI;AACvE,YAAI,sBAAsB,QAAQ,SAAS;AACzC,gBAAM,eAAe,OAAO,UAAU,CAAC,GACjC,UACJ,cAAc,SAAS,SAAS,aAAa,OAAO;AACtD,eAAK,UAAU,EAAE,MAAM,GAAG,QAAO,CAAE;QACrC;AACA,eAAO;MACT,GACA,EAAE,iBAAiB,KAAK,KAAI,CAAE,CAC/B;EAGT;;",
   "names": []
 }

package/dist/mcp/tools/changeset-analysis-tools.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { AnnotationStore } from "../../core/annotation-store.js";
+import { buildBrief, computeImpact, DEFAULT_HUB_THRESHOLD } from "../../core/changeset-analysis.js";
+import { briefDelta } from "../../core/changeset-brief-delta.js";
+import { describeDrift } from "../../core/changeset-base-index.js";
+import { getErrorMessage } from "../../utils/errors.js";
+import { jsonResult, loadModel, rootPathSchema, runTool } from "./shared.js";
+import { loadChangesetGraph } from "./changeset-shared.js";
+const changesetIdSchema = z.string().optional().describe("Changeset ID or name. Defaults to the active changeset."), impactInputSchema = {
+  changesetId: changesetIdSchema,
+  depth: z.number().int().min(1).max(6).optional().describe("Hops to walk out from the changed elements (default 2)."),
+  maxElements: z.number().int().positive().optional().describe("Stop after this many reached elements (default 200)."),
+  from: z.array(z.string()).optional().describe("Element ids or paths to walk from instead of every changed element. Ids the projected model does not have are listed in unknownFrom."),
+  hubThreshold: z.number().int().min(0).optional().describe(`An element with more relationships than this is a hub: listed in hubs with its degree and not walked through (default ${DEFAULT_HUB_THRESHOLD}).`),
+  expandHubs: z.boolean().optional().describe("Walk through hubs too (default false)."),
+  rootPath: rootPathSchema
+};
+async function changesetImpactHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), { changeset, graph } = await loadChangesetGraph(model, args.changesetId), report = computeImpact(graph, {
+      depth: args.depth,
+      maxElements: args.maxElements,
+      from: args.from,
+      hubThreshold: args.hubThreshold,
+      expandHubs: args.expandHubs
+    });
+    return jsonResult({ changeset: { id: changeset.id, name: changeset.name }, ...report });
+  });
+}
+const changesetImpactTool = {
+  name: "changeset_impact",
+  description: "Walk the model outward from everything a changeset adds, changes or removes (relationships included), or from the elements named in `from`, and list the existing elements it reaches, by layer, with how each was reached and its source files, plus how many each hop reached (perHop). These are what the change can break or must update. Hubs (elements with more than hubThreshold relationships) are listed with their degree and not walked through unless expandHubs is set.",
+  inputSchema: impactInputSchema,
+  handler: changesetImpactHandler
+}, briefInputSchema = {
+  changesetId: changesetIdSchema,
+  unwired: z.enum(["summary", "full", "none"]).optional().describe("Unwired connections (catalog connections an added or updated element has no relationship for): summary (default) counts them per layer and lists the ones in layers the change already reaches whose other type the model has (existing or added), counting the rest as typesNotInModel; full lists them all; none omits them."),
+  unwiredLayers: z.array(z.string()).optional().describe("Only show unwired connections whose other end is in these layers (and list them)."),
+  since: z.union([z.number().int().min(-1), z.string().regex(/^(-1|\d+):[0-9a-f]+$/, "a revisionToken from a brief")]).optional().describe("A revision (or, better, the revisionToken) an earlier brief returned. Adds a delta: elements added, removed or updated (with the fields), relationships added or removed, changes unstaged, gaps opened and closed, unwired connections wired, layers newly reached or no longer reached, intent newly traced since then. Unstaging does not invalidate it. With the token, the delta warns when a change up to that revision was rewritten in place since."),
+  rootPath: rootPathSchema
+};
+async function changesetBriefHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), { manager, changeset, graph } = await loadChangesetGraph(model, args.changesetId), annotations = await new AnnotationStore(model.rootPath).list();
+    let drift;
+    if (changeset.status === "staged") {
+      let hash;
+      try {
+        hash = await manager.detectDrift(changeset.id);
+      } catch (error) {
+        hash = { isDrifted: !1, warnings: [`Drift check failed: ${getErrorMessage(error)}`] };
+      }
+      try {
+        drift = await describeDrift(model, graph, hash);
+      } catch (error) {
+        drift = {
+          isDrifted: hash.isDrifted,
+          warnings: [...hash.warnings, `Could not name what drifted: ${getErrorMessage(error)}`]
+        };
+      }
+    }
+    const brief = buildBrief({ graph, annotations, drift, unwired: args.unwired, unwiredLayers: args.unwiredLayers });
+    return args.since === void 0 ? jsonResult(brief, { compact: !0 }) : jsonResult({ ...brief, delta: await briefDelta(model, { graph, brief }, args.since) }, { compact: !0 });
+  });
+}
+const changesetBriefTool = {
+  name: "changeset_brief",
+  description: "Render a changeset as the spec for its change: every added, updated and deleted element by layer with its connections; which layers the change reaches and which it does not; gaps (unconnected additions, missing required relationships, connections its peers have); unwired connections (every catalog connection an added or updated element has no relationship for, by the other end's layer, with how many elements of the other type exist); changes that trace to no goal, requirement or feature; the source files touched; open review annotations; and how the base drifted since the changeset was created (staged adds the base already has are counted as alreadyInBase, apart from the adds). It returns a revision and a revisionToken: pass the token back as since on the next pass to get what changed. Use it to pressure-test a plan and as the input to building it.",
+  inputSchema: briefInputSchema,
+  handler: changesetBriefHandler
+};
+export {
+  changesetBriefHandler,
+  changesetBriefTool,
+  changesetImpactHandler,
+  changesetImpactTool
+};
+//# sourceMappingURL=changeset-analysis-tools.js.map

package/dist/mcp/tools/changeset-analysis-tools.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mcp/tools/changeset-analysis-tools.ts"],
+  "sourcesContent": ["/**\n * changeset_impact, changeset_brief \u2014 pressure-test a planned change against the model.\n * See `cli/src/core/changeset-analysis.ts` and docs/CHANGE_MODELING.md.\n */\n\nimport { z } from \"zod\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport { AnnotationStore } from \"../../core/annotation-store.js\";\nimport { buildBrief, computeImpact, DEFAULT_HUB_THRESHOLD, type BriefDrift } from \"../../core/changeset-analysis.js\";\nimport { briefDelta } from \"../../core/changeset-brief-delta.js\";\nimport { describeDrift } from \"../../core/changeset-base-index.js\";\nimport { getErrorMessage } from \"../../utils/errors.js\";\nimport { jsonResult, loadModel, rootPathSchema, runTool, type McpToolDefinition } from \"./shared.js\";\nimport { loadChangesetGraph } from \"./changeset-shared.js\";\n\nconst changesetIdSchema = z.string().optional().describe(\"Changeset ID or name. Defaults to the active changeset.\");\n\n// ---------------------------------------------------------------------------\n// changeset_impact\n// ---------------------------------------------------------------------------\n\nconst impactInputSchema = {\n  changesetId: changesetIdSchema,\n  depth: z.number().int().min(1).max(6).optional().describe(\"Hops to walk out from the changed elements (default 2).\"),\n  maxElements: z.number().int().positive().optional().describe(\"Stop after this many reached elements (default 200).\"),\n  from: z\n    .array(z.string())\n    .optional()\n    .describe(\n      \"Element ids or paths to walk from instead of every changed element. Ids the projected model does not have \" +\n        \"are listed in unknownFrom.\"\n    ),\n  hubThreshold: z\n    .number()\n    .int()\n    .min(0)\n    .optional()\n    .describe(\n      `An element with more relationships than this is a hub: listed in hubs with its degree and not walked ` +\n        `through (default ${DEFAULT_HUB_THRESHOLD}).`\n    ),\n  expandHubs: z.boolean().optional().describe(\"Walk through hubs too (default false).\"),\n  rootPath: rootPathSchema,\n};\n\nexport type ChangesetImpactArgs = z.infer<z.ZodObject<typeof impactInputSchema>>;\n\nexport async function changesetImpactHandler(args: ChangesetImpactArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    const model = await loadModel(args.rootPath);\n    const { changeset, graph } = await loadChangesetGraph(model, args.changesetId);\n    const report = computeImpact(graph, {\n      depth: args.depth,\n      maxElements: args.maxElements,\n      from: args.from,\n      hubThreshold: args.hubThreshold,\n      expandHubs: args.expandHubs,\n    });\n    return jsonResult({ changeset: { id: changeset.id, name: changeset.name }, ...report });\n  });\n}\n\nexport const changesetImpactTool: McpToolDefinition<typeof impactInputSchema> = {\n  name: \"changeset_impact\",\n  description:\n    \"Walk the model outward from everything a changeset adds, changes or removes (relationships included), or \" +\n    \"from the elements named in `from`, and list the existing elements it reaches, by layer, with how each was \" +\n    \"reached and its source files, plus how many each hop reached (perHop). These are what the change can break \" +\n    \"or must update. Hubs (elements with more than hubThreshold relationships) are listed with their degree and \" +\n    \"not walked through unless expandHubs is set.\",\n  inputSchema: impactInputSchema,\n  handler: changesetImpactHandler,\n};\n\n// ---------------------------------------------------------------------------\n// changeset_brief\n// ---------------------------------------------------------------------------\n\nconst briefInputSchema = {\n  changesetId: changesetIdSchema,\n  unwired: z\n    .enum([\"summary\", \"full\", \"none\"])\n    .optional()\n    .describe(\n      \"Unwired connections (catalog connections an added or updated element has no relationship for): summary \" +\n        \"(default) counts them per layer and lists the ones in layers the change already reaches whose other type \" +\n        \"the model has (existing or added), counting the rest as typesNotInModel; full lists them all; none omits them.\"\n    ),\n  unwiredLayers: z\n    .array(z.string())\n    .optional()\n    .describe(\"Only show unwired connections whose other end is in these layers (and list them).\"),\n  since: z\n    .union([z.number().int().min(-1), z.string().regex(/^(-1|\\d+):[0-9a-f]+$/, \"a revisionToken from a brief\")])\n    .optional()\n    .describe(\n      \"A revision (or, better, the revisionToken) an earlier brief returned. Adds a delta: elements added, removed \" +\n        \"or updated (with the fields), relationships added or removed, changes unstaged, gaps opened and closed, \" +\n        \"unwired connections wired, layers newly reached or no longer reached, intent newly traced since then. \" +\n        \"Unstaging does not invalidate it. With the token, the delta warns when a change up to that revision was \" +\n        \"rewritten in place since.\"\n    ),\n  rootPath: rootPathSchema,\n};\n\nexport type ChangesetBriefArgs = z.infer<z.ZodObject<typeof briefInputSchema>>;\n\nexport async function changesetBriefHandler(args: ChangesetBriefArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    const model = await loadModel(args.rootPath);\n    const { manager, changeset, graph } = await loadChangesetGraph(model, args.changesetId);\n\n    const annotations = await new AnnotationStore(model.rootPath).list();\n\n    let drift: BriefDrift | undefined;\n    if (changeset.status === \"staged\") {\n      // Each part is reported on failure and the brief goes on: the hash check, then the structured view.\n      let hash: { isDrifted: boolean; warnings: string[]; baseSnapshotId?: string; currentSnapshotId?: string };\n      try {\n        hash = await manager.detectDrift(changeset.id);\n      } catch (error) {\n        hash = { isDrifted: false, warnings: [`Drift check failed: ${getErrorMessage(error)}`] };\n      }\n      try {\n        drift = await describeDrift(model, graph, hash);\n      } catch (error) {\n        drift = {\n          isDrifted: hash.isDrifted,\n          warnings: [...hash.warnings, `Could not name what drifted: ${getErrorMessage(error)}`],\n        };\n      }\n    }\n\n    const brief = buildBrief({ graph, annotations, drift, unwired: args.unwired, unwiredLayers: args.unwiredLayers });\n    // The brief is the largest result: same JSON, short objects kept on one line.\n    if (args.since === undefined) return jsonResult(brief, { compact: true });\n    return jsonResult({ ...brief, delta: await briefDelta(model, { graph, brief }, args.since) }, { compact: true });\n  });\n}\n\nexport const changesetBriefTool: McpToolDefinition<typeof briefInputSchema> = {\n  name: \"changeset_brief\",\n  description:\n    \"Render a changeset as the spec for its change: every added, updated and deleted element by layer with its \" +\n    \"connections; which layers the change reaches and which it does not; gaps (unconnected additions, missing \" +\n    \"required relationships, connections its peers have); unwired connections (every catalog connection an added \" +\n    \"or updated element has no relationship for, by the other end's layer, with how many elements of the other \" +\n    \"type exist); changes that trace to no goal, requirement or feature; the source files touched; open review \" +\n    \"annotations; and how the base drifted since the changeset was created (staged adds the base already has are \" +\n    \"counted as alreadyInBase, apart from the adds). It returns a revision and a revisionToken: pass the token back \" +\n    \"as since on the next pass to get what changed. Use it to pressure-test a plan and as the input to building it.\",\n  inputSchema: briefInputSchema,\n  handler: changesetBriefHandler,\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/mcp/tools/changeset-editing.js

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { ChangesetGraph } from "../../core/changeset-graph.js";
+import { StagingAreaManager } from "../../core/staging-area.js";
+import { stagedRelationshipChangesAtEnds, stagedRelationshipTriple } from "../../core/relationship-staging.js";
+import { CLIError, ErrorCategory, getErrorMessage } from "../../utils/errors.js";
+import { jsonResult, loadModel, reloadModel, rootPathSchema, runTool } from "./shared.js";
+import { resolveChangeset } from "./changeset-shared.js";
+const changesetIdSchema = z.string().optional().describe("Changeset ID or name. Defaults to the active changeset.");
+function requireStaged(changeset, action) {
+  if (changeset.status !== "staged")
+    throw new CLIError(`Changeset '${changeset.name}' is ${changeset.status}; cannot ${action}`, ErrorCategory.USER, [
+      'Use "changeset_list" to find a staged changeset, or "changeset_create" to start a new one'
+    ]);
+}
+async function asUserError(fn, suggestions) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw error instanceof CLIError ? error : new CLIError(getErrorMessage(error), ErrorCategory.USER, suggestions);
+  }
+}
+function summarize(change) {
+  const triple = change.type.startsWith("relationship-") ? stagedRelationshipTriple(change) : null;
+  return {
+    type: change.type,
+    elementId: change.elementId,
+    layer: change.layerName,
+    ...triple ? { relationship: triple } : {}
+  };
+}
+const updateInputSchema = {
+  changesetId: changesetIdSchema,
+  name: z.string().min(1).optional().describe("New name. Must not be another changeset's name."),
+  description: z.string().optional().describe("New description: the change's intent and what done looks like. An empty string clears it."),
+  rootPath: rootPathSchema
+};
+async function changesetUpdateHandler(args) {
+  return runTool(async () => {
+    if (args.name === void 0 && args.description === void 0)
+      throw new CLIError("Nothing to update", ErrorCategory.USER, ['Pass "name" and/or "description"']);
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model), changeset = await resolveChangeset(manager, args.changesetId), updated = await asUserError(() => manager.update(changeset.id, { name: args.name, description: args.description }), ['Use "changeset_list" to see the names already taken']);
+    return await reloadModel(args.rootPath), jsonResult({
+      id: updated.id,
+      name: updated.name,
+      ...changeset.name !== updated.name ? { previousName: changeset.name } : {},
+      description: updated.description ?? null,
+      status: updated.status,
+      changes: updated.changes.length
+    });
+  });
+}
+const changesetUpdateTool = {
+  name: "changeset_update",
+  description: "Rename a changeset or change its description (the change's intent). Staged changes are untouched. Defaults to the active changeset.",
+  inputSchema: updateInputSchema,
+  handler: changesetUpdateHandler
+}, unstageInputSchema = {
+  changesetId: changesetIdSchema,
+  elementId: z.string().optional().describe("Drop every staged change to this element (its add, updates or delete). ID or path."),
+  source: z.string().optional().describe("Drop staged relationship changes (adds and deletes) from this element: to target when given, otherwise to any element. The element's own changes are not touched."),
+  target: z.string().optional().describe("Drop staged relationship changes (adds and deletes) to this element: from source when given, otherwise from any element. The element's own changes are not touched."),
+  predicate: z.string().optional().describe("Only relationship changes with this predicate. Omit for any."),
+  keepRelationships: z.boolean().optional().describe("With elementId: keep the staged relationship changes that depend on the element's change. By default, unstaging an element's add also drops staged relationships to it (they would dangle), and unstaging its delete also drops the relationship removals its cascade staged (removals staged before the delete are kept)."),
+  rootPath: rootPathSchema
+};
+function describeEnds(args) {
+  return args.source && args.target ? `from ${args.source} to ${args.target}` : args.source ? `from ${args.source}` : `to ${args.target}`;
+}
+async function changesetUnstageHandler(args) {
+  return runTool(async () => {
+    const byElement = args.elementId !== void 0, byRelationship = args.source !== void 0 || args.target !== void 0;
+    if (byElement === byRelationship)
+      throw new CLIError("Name either an element or a relationship to unstage", ErrorCategory.USER, [
+        `Pass "elementId" to drop an element's staged changes`,
+        'Or pass "source" and/or "target" (and optionally "predicate") to drop staged relationship changes'
+      ]);
+    if (byRelationship && !args.source && !args.target)
+      throw new CLIError('"source" or "target" must not be empty', ErrorCategory.USER);
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model), changeset = await resolveChangeset(manager, args.changesetId);
+    requireStaged(changeset, "unstage changes");
+    const graph = await ChangesetGraph.build(model, changeset), changes = changeset.changes, keys = /* @__PURE__ */ new Set(), notes = [];
+    if (byElement) {
+      const element = graph.getElement(args.elementId), ids = /* @__PURE__ */ new Set([args.elementId, ...element ? [element.id, element.uuid ?? element.id] : []]), own = changes.filter((c) => !c.type.startsWith("relationship-") && ids.has(c.elementId));
+      for (const change of own)
+        keys.add(change.elementId);
+      const dependentType = own.some((c) => c.type === "add") ? "relationship-add" : own.some((c) => c.type === "delete") ? "relationship-delete" : null, touching = dependentType ? changes.filter((c) => {
+        if (c.type !== dependentType)
+          return !1;
+        const triple = stagedRelationshipTriple(c);
+        return !!triple && (ids.has(triple.source) || ids.has(triple.target) || element && (graph.resolve(triple.source) === element.id || graph.resolve(triple.target) === element.id));
+      }) : [], seq = (c) => c.sequenceNumber ?? changes.indexOf(c), deleteSeqs = own.filter((c) => c.type === "delete").map(seq), firstDelete = deleteSeqs.length > 0 ? Math.min(...deleteSeqs) : -1, dependent = dependentType === "relationship-delete" ? touching.filter((c) => seq(c) > firstDelete) : touching, deliberate = touching.filter((c) => !dependent.includes(c));
+      if (deliberate.length > 0 && notes.push(`${deliberate.length} relationship removal(s) on ${args.elementId} staged before its delete were kept (${deliberate.map((c) => c.elementId).join(", ")}); unstage them by source and target if they should go too`), dependent.length > 0)
+        if (args.keepRelationships)
+          notes.push(`${dependent.length} staged relationship change(s) on ${args.elementId} were kept (keepRelationships)` + (dependentType === "relationship-add" ? "; they will dangle unless the element is staged again" : ""));
+        else
+          for (const change of dependent)
+            keys.add(change.elementId);
+    } else {
+      const matched = stagedRelationshipChangesAtEnds(graph, changeset, {
+        source: args.source || void 0,
+        target: args.target || void 0,
+        predicate: args.predicate
+      }), seq = (c) => c.sequenceNumber ?? changes.indexOf(c), deleteSeq = /* @__PURE__ */ new Map();
+      for (const change of changes) {
+        if (change.type !== "delete")
+          continue;
+        const id = graph.resolve(change.elementId);
+        deleteSeq.set(id, Math.min(deleteSeq.get(id) ?? 1 / 0, seq(change)));
+      }
+      const deletedEndOf = (change) => {
+        if (change.type !== "relationship-delete")
+          return;
+        const triple = stagedRelationshipTriple(change);
+        if (triple)
+          return [graph.resolve(triple.source), graph.resolve(triple.target)].find((end) => deleteSeq.has(end) && deleteSeq.get(end) < seq(change));
+      }, cascaded = matched.filter((c) => deletedEndOf(c) !== void 0), deletedEnds = [...new Set(cascaded.map((c) => deletedEndOf(c)))].join(", "), cascadeList = cascaded.map((c) => c.elementId).join(", "), bothEnds = !!args.source && !!args.target;
+      for (const change of matched)
+        !bothEnds && cascaded.includes(change) || keys.add(change.elementId);
+      cascaded.length > 0 && bothEnds ? notes.push(`Unstaged ${cascaded.length} relationship removal(s) cascaded from the staged delete of ${deletedEnds} (${cascadeList}): those relationships now dangle, so the changeset will not commit until they are removed again or the delete is unstaged ("changeset_unstage" with elementId)`) : cascaded.length > 0 && notes.push(`Kept ${cascaded.length} relationship removal(s) cascaded from the staged delete of ${deletedEnds} (${cascadeList}): dropping them would leave those relationships dangling. Unstage the delete ("changeset_unstage" with elementId) to restore them, or name both source and target to drop one anyway`);
+    }
+    const removed = changes.filter((c) => keys.has(c.elementId));
+    if (removed.length === 0)
+      return jsonResult({
+        status: "not-staged",
+        changeset: changeset.name,
+        message: byElement ? `No staged change to ${args.elementId} in '${changeset.name}'` : `No staged relationship change ${describeEnds(args)}${args.predicate ? ` (${args.predicate})` : ""} in '${changeset.name}'`,
+        suggestions: ['Use "changeset_show" to list the staged changes'],
+        ...notes.length > 0 ? { notes } : {}
+      });
+    for (const key of keys)
+      await manager.unstage(changeset.id, key);
+    return await reloadModel(args.rootPath), jsonResult({
+      status: "unstaged",
+      changeset: changeset.name,
+      unstaged: removed.map(summarize),
+      remainingChanges: changes.length - removed.length,
+      ...notes.length > 0 ? { notes } : {}
+    });
+  });
+}
+const changesetUnstageTool = {
+  name: "changeset_unstage",
+  description: "Undo part of a staged changeset: drop the staged changes to one element (elementId), or the staged relationship adds/deletes between source and target, or every one from source alone or to target alone (optionally one predicate). The base model is not touched. Defaults to the active changeset. Use changeset_show to see what is staged.",
+  inputSchema: unstageInputSchema,
+  handler: changesetUnstageHandler
+}, discardInputSchema = {
+  changesetId: z.string().describe("Changeset ID or name to discard. Required: discard is never implied."),
+  confirm: z.boolean().describe("Must be true. Discarding deletes the changeset's staged changes permanently (only its name, description and a 'discarded' status remain), so confirm only when the plan is to be abandoned."),
+  rootPath: rootPathSchema
+};
+async function changesetDiscardHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model), changeset = await resolveChangeset(manager, args.changesetId);
+    if (requireStaged(changeset, "discard it"), args.confirm !== !0)
+      throw new CLIError(`Discarding '${changeset.name}' deletes its ${changeset.changes.length} staged change(s) permanently`, ErrorCategory.USER, [
+        'Pass "confirm": true to discard it',
+        'Use "changeset_unstage" to drop individual changes instead',
+        'Use "changeset_deactivate" to stop staging into it and keep its changes'
+      ]);
+    const wasActive = await manager.getActiveId() === changeset.id, discardedChanges = changeset.changes.length;
+    return await manager.discard(changeset.id), wasActive && await manager.clearActive(), await reloadModel(args.rootPath), jsonResult({
+      id: changeset.id,
+      name: changeset.name,
+      status: "discarded",
+      discardedChanges,
+      deactivated: wasActive
+    });
+  });
+}
+const changesetDiscardTool = {
+  name: "changeset_discard",
+  description: "Abandon a staged changeset: PERMANENTLY deletes its staged changes and marks it discarded (deactivating it if active). Not recoverable, so it requires confirm: true. The base model is not touched. To undo part of a plan use changeset_unstage; to pause it use changeset_deactivate.",
+  inputSchema: discardInputSchema,
+  handler: changesetDiscardHandler
+};
+export {
+  changesetDiscardHandler,
+  changesetDiscardTool,
+  changesetUnstageHandler,
+  changesetUnstageTool,
+  changesetUpdateHandler,
+  changesetUpdateTool
+};
+//# sourceMappingURL=changeset-editing.js.map

package/dist/mcp/tools/changeset-editing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mcp/tools/changeset-editing.ts"],
+  "sourcesContent": ["/**\n * changeset_update, changeset_unstage, changeset_discard \u2014 revise a staged changeset while\n * planning a change. Mirror `dr changeset unstage|discard` and add the rename / re-describe step\n * the CLI has no command for, all through StagingAreaManager.\n *\n * Every mutation reloads the cached model afterwards, like changeset-lifecycle.ts: the model\n * projects the active changeset's elements at load time, and the projection cache is keyed by\n * what is staged.\n *\n * Commit and apply stay off the MCP surface (landing a change is the human's step). Discard is\n * exposed because an agent must be able to abandon its own plan, but it clears the staged changes\n * for good, so it needs `confirm: true`. See docs/CHANGE_MODELING.md.\n */\n\nimport { z } from \"zod\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport { ChangesetGraph } from \"../../core/changeset-graph.js\";\nimport type { Changeset, StagedChange } from \"../../core/changeset.js\";\nimport { StagingAreaManager } from \"../../core/staging-area.js\";\nimport { stagedRelationshipChangesAtEnds, stagedRelationshipTriple } from \"../../core/relationship-staging.js\";\nimport { CLIError, ErrorCategory, getErrorMessage } from \"../../utils/errors.js\";\nimport { jsonResult, loadModel, reloadModel, rootPathSchema, runTool, type McpToolDefinition } from \"./shared.js\";\nimport { resolveChangeset } from \"./changeset-shared.js\";\n\nconst changesetIdSchema = z\n  .string()\n  .optional()\n  .describe(\"Changeset ID or name. Defaults to the active changeset.\");\n\nfunction requireStaged(changeset: Changeset, action: string): void {\n  if (changeset.status !== \"staged\") {\n    throw new CLIError(`Changeset '${changeset.name}' is ${changeset.status}; cannot ${action}`, ErrorCategory.USER, [\n      'Use \"changeset_list\" to find a staged changeset, or \"changeset_create\" to start a new one',\n    ]);\n  }\n}\n\n/** Wraps a StagingAreaManager error (plain Error) as a user error the agent can act on. */\nasync function asUserError<T>(fn: () => Promise<T>, suggestions: string[]): Promise<T> {\n  try {\n    return await fn();\n  } catch (error) {\n    if (error instanceof CLIError) throw error;\n    throw new CLIError(getErrorMessage(error), ErrorCategory.USER, suggestions);\n  }\n}\n\nfunction summarize(change: StagedChange): Record<string, unknown> {\n  const triple = change.type.startsWith(\"relationship-\") ? stagedRelationshipTriple(change) : null;\n  return {\n    type: change.type,\n    elementId: change.elementId,\n    layer: change.layerName,\n    ...(triple ? { relationship: triple } : {}),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// changeset_update\n// ---------------------------------------------------------------------------\n\nconst updateInputSchema = {\n  changesetId: changesetIdSchema,\n  name: z.string().min(1).optional().describe(\"New name. Must not be another changeset's name.\"),\n  description: z\n    .string()\n    .optional()\n    .describe(\"New description: the change's intent and what done looks like. An empty string clears it.\"),\n  rootPath: rootPathSchema,\n};\n\nexport type ChangesetUpdateArgs = z.infer<z.ZodObject<typeof updateInputSchema>>;\n\nexport async function changesetUpdateHandler(args: ChangesetUpdateArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    if (args.name === undefined && args.description === undefined) {\n      throw new CLIError(\"Nothing to update\", ErrorCategory.USER, ['Pass \"name\" and/or \"description\"']);\n    }\n    const model = await loadModel(args.rootPath);\n    const manager = new StagingAreaManager(model.rootPath, model);\n    const changeset = await resolveChangeset(manager, args.changesetId);\n\n    const updated = await asUserError(\n      () => manager.update(changeset.id!, { name: args.name, description: args.description }),\n      ['Use \"changeset_list\" to see the names already taken']\n    );\n    await reloadModel(args.rootPath);\n\n    return jsonResult({\n      id: updated.id,\n      name: updated.name,\n      ...(changeset.name !== updated.name ? { previousName: changeset.name } : {}),\n      description: updated.description ?? null,\n      status: updated.status,\n      changes: updated.changes.length,\n    });\n  });\n}\n\nexport const changesetUpdateTool: McpToolDefinition<typeof updateInputSchema> = {\n  name: \"changeset_update\",\n  description:\n    \"Rename a changeset or change its description (the change's intent). Staged changes are untouched. \" +\n    \"Defaults to the active changeset.\",\n  inputSchema: updateInputSchema,\n  handler: changesetUpdateHandler,\n};\n\n// ---------------------------------------------------------------------------\n// changeset_unstage\n// ---------------------------------------------------------------------------\n\nconst unstageInputSchema = {\n  changesetId: changesetIdSchema,\n  elementId: z\n    .string()\n    .optional()\n    .describe(\"Drop every staged change to this element (its add, updates or delete). ID or path.\"),\n  source: z\n    .string()\n    .optional()\n    .describe(\n      \"Drop staged relationship changes (adds and deletes) from this element: to target when given, otherwise to \" +\n        \"any element. The element's own changes are not touched.\"\n    ),\n  target: z\n    .string()\n    .optional()\n    .describe(\n      \"Drop staged relationship changes (adds and deletes) to this element: from source when given, otherwise from \" +\n        \"any element. The element's own changes are not touched.\"\n    ),\n  predicate: z.string().optional().describe(\"Only relationship changes with this predicate. Omit for any.\"),\n  keepRelationships: z\n    .boolean()\n    .optional()\n    .describe(\n      \"With elementId: keep the staged relationship changes that depend on the element's change. By default, \" +\n        \"unstaging an element's add also drops staged relationships to it (they would dangle), and unstaging its \" +\n        \"delete also drops the relationship removals its cascade staged (removals staged before the delete are kept).\"\n    ),\n  rootPath: rootPathSchema,\n};\n\nexport type ChangesetUnstageArgs = z.infer<z.ZodObject<typeof unstageInputSchema>>;\n\nfunction describeEnds(args: { source?: string; target?: string }): string {\n  if (args.source && args.target) return `from ${args.source} to ${args.target}`;\n  return args.source ? `from ${args.source}` : `to ${args.target}`;\n}\n\nexport async function changesetUnstageHandler(args: ChangesetUnstageArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    const byElement = args.elementId !== undefined;\n    const byRelationship = args.source !== undefined || args.target !== undefined;\n    if (byElement === byRelationship) {\n      throw new CLIError(\"Name either an element or a relationship to unstage\", ErrorCategory.USER, [\n        'Pass \"elementId\" to drop an element\\'s staged changes',\n        'Or pass \"source\" and/or \"target\" (and optionally \"predicate\") to drop staged relationship changes',\n      ]);\n    }\n    if (byRelationship && !args.source && !args.target) {\n      throw new CLIError('\"source\" or \"target\" must not be empty', ErrorCategory.USER);\n    }\n\n    const model = await loadModel(args.rootPath);\n    const manager = new StagingAreaManager(model.rootPath, model);\n    const changeset = await resolveChangeset(manager, args.changesetId);\n    requireStaged(changeset, \"unstage changes\");\n    const graph = await ChangesetGraph.build(model, changeset);\n    const changes = changeset.changes as StagedChange[];\n\n    const keys = new Set<string>();\n    const notes: string[] = [];\n\n    if (byElement) {\n      const element = graph.getElement(args.elementId!);\n      const ids = new Set([args.elementId!, ...(element ? [element.id, element.uuid ?? element.id] : [])]);\n      const own = changes.filter((c) => !c.type.startsWith(\"relationship-\") && ids.has(c.elementId));\n      for (const change of own) keys.add(change.elementId);\n\n      // Relationship changes that only make sense with the element's change.\n      const dependentType = own.some((c) => c.type === \"add\")\n        ? \"relationship-add\"\n        : own.some((c) => c.type === \"delete\")\n          ? \"relationship-delete\"\n          : null;\n      const touching = dependentType\n        ? changes.filter((c) => {\n            if (c.type !== dependentType) return false;\n            const triple = stagedRelationshipTriple(c);\n            return (\n              !!triple &&\n              (ids.has(triple.source) ||\n                ids.has(triple.target) ||\n                (element && (graph.resolve(triple.source) === element.id || graph.resolve(triple.target) === element.id)))\n            );\n          })\n        : [];\n      // A delete cascades into relationship removals staged right after it. Removals staged before the\n      // delete were the agent's own decisions, not the cascade's, so they stay.\n      const seq = (c: StagedChange): number => c.sequenceNumber ?? changes.indexOf(c);\n      const deleteSeqs = own.filter((c) => c.type === \"delete\").map(seq);\n      const firstDelete = deleteSeqs.length > 0 ? Math.min(...deleteSeqs) : -1;\n      const dependent =\n        dependentType === \"relationship-delete\" ? touching.filter((c) => seq(c) > firstDelete) : touching;\n      const deliberate = touching.filter((c) => !dependent.includes(c));\n      if (deliberate.length > 0) {\n        notes.push(\n          `${deliberate.length} relationship removal(s) on ${args.elementId} staged before its delete were kept ` +\n            `(${deliberate.map((c) => c.elementId).join(\", \")}); unstage them by source and target if they should go too`\n        );\n      }\n      if (dependent.length > 0) {\n        if (args.keepRelationships) {\n          notes.push(\n            `${dependent.length} staged relationship change(s) on ${args.elementId} were kept (keepRelationships)` +\n              (dependentType === \"relationship-add\" ? \"; they will dangle unless the element is staged again\" : \"\")\n          );\n        } else {\n          for (const change of dependent) keys.add(change.elementId);\n        }\n      }\n    } else {\n      const matched = stagedRelationshipChangesAtEnds(graph, changeset, {\n        source: args.source || undefined,\n        target: args.target || undefined,\n        predicate: args.predicate,\n      });\n      // A relationship removal staged after the delete of one of its ends is that delete's cascade:\n      // without it the deleted element's relationship dangles and the changeset no longer commits.\n      const seq = (c: StagedChange): number => c.sequenceNumber ?? changes.indexOf(c);\n      const deleteSeq = new Map<string, number>();\n      for (const change of changes) {\n        if (change.type !== \"delete\") continue;\n        const id = graph.resolve(change.elementId);\n        deleteSeq.set(id, Math.min(deleteSeq.get(id) ?? Infinity, seq(change)));\n      }\n      const deletedEndOf = (change: StagedChange): string | undefined => {\n        if (change.type !== \"relationship-delete\") return undefined;\n        const triple = stagedRelationshipTriple(change);\n        if (!triple) return undefined;\n        return [graph.resolve(triple.source), graph.resolve(triple.target)].find(\n          (end) => deleteSeq.has(end) && deleteSeq.get(end)! < seq(change)\n        );\n      };\n      const cascaded = matched.filter((c) => deletedEndOf(c) !== undefined);\n      const deletedEnds = [...new Set(cascaded.map((c) => deletedEndOf(c)!))].join(\", \");\n      const cascadeList = cascaded.map((c) => c.elementId).join(\", \");\n      // One end sweeps every relationship there, so it leaves a delete's cascade alone. Naming both\n      // ends asks for those relationships specifically, so they go, with a warning.\n      const bothEnds = !!args.source && !!args.target;\n      for (const change of matched) {\n        if (!bothEnds && cascaded.includes(change)) continue;\n        keys.add(change.elementId);\n      }\n      if (cascaded.length > 0 && bothEnds) {\n        notes.push(\n          `Unstaged ${cascaded.length} relationship removal(s) cascaded from the staged delete of ${deletedEnds} ` +\n            `(${cascadeList}): those relationships now dangle, so the changeset will not commit until they are ` +\n            `removed again or the delete is unstaged (\"changeset_unstage\" with elementId)`\n        );\n      } else if (cascaded.length > 0) {\n        notes.push(\n          `Kept ${cascaded.length} relationship removal(s) cascaded from the staged delete of ${deletedEnds} ` +\n            `(${cascadeList}): dropping them would leave those relationships dangling. Unstage the delete ` +\n            `(\"changeset_unstage\" with elementId) to restore them, or name both source and target to drop one anyway`\n        );\n      }\n    }\n\n    const removed = changes.filter((c) => keys.has(c.elementId));\n    if (removed.length === 0) {\n      return jsonResult({\n        status: \"not-staged\",\n        changeset: changeset.name,\n        message: byElement\n          ? `No staged change to ${args.elementId} in '${changeset.name}'`\n          : `No staged relationship change ${describeEnds(args)}` +\n            `${args.predicate ? ` (${args.predicate})` : \"\"} in '${changeset.name}'`,\n        suggestions: ['Use \"changeset_show\" to list the staged changes'],\n        ...(notes.length > 0 ? { notes } : {}),\n      });\n    }\n\n    for (const key of keys) {\n      await manager.unstage(changeset.id!, key);\n    }\n    await reloadModel(args.rootPath);\n\n    return jsonResult({\n      status: \"unstaged\",\n      changeset: changeset.name,\n      unstaged: removed.map(summarize),\n      remainingChanges: changes.length - removed.length,\n      ...(notes.length > 0 ? { notes } : {}),\n    });\n  });\n}\n\nexport const changesetUnstageTool: McpToolDefinition<typeof unstageInputSchema> = {\n  name: \"changeset_unstage\",\n  description:\n    \"Undo part of a staged changeset: drop the staged changes to one element (elementId), or the staged \" +\n    \"relationship adds/deletes between source and target, or every one from source alone or to target alone \" +\n    \"(optionally one predicate). The base model is not touched. \" +\n    \"Defaults to the active changeset. Use changeset_show to see what is staged.\",\n  inputSchema: unstageInputSchema,\n  handler: changesetUnstageHandler,\n};\n\n// ---------------------------------------------------------------------------\n// changeset_discard\n// ---------------------------------------------------------------------------\n\nconst discardInputSchema = {\n  changesetId: z.string().describe(\"Changeset ID or name to discard. Required: discard is never implied.\"),\n  confirm: z\n    .boolean()\n    .describe(\n      \"Must be true. Discarding deletes the changeset's staged changes permanently (only its name, description and \" +\n        \"a 'discarded' status remain), so confirm only when the plan is to be abandoned.\"\n    ),\n  rootPath: rootPathSchema,\n};\n\nexport type ChangesetDiscardArgs = z.infer<z.ZodObject<typeof discardInputSchema>>;\n\nexport async function changesetDiscardHandler(args: ChangesetDiscardArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    const model = await loadModel(args.rootPath);\n    const manager = new StagingAreaManager(model.rootPath, model);\n    const changeset = await resolveChangeset(manager, args.changesetId);\n    requireStaged(changeset, \"discard it\");\n\n    if (args.confirm !== true) {\n      throw new CLIError(\n        `Discarding '${changeset.name}' deletes its ${changeset.changes.length} staged change(s) permanently`,\n        ErrorCategory.USER,\n        [\n          'Pass \"confirm\": true to discard it',\n          'Use \"changeset_unstage\" to drop individual changes instead',\n          'Use \"changeset_deactivate\" to stop staging into it and keep its changes',\n        ]\n      );\n    }\n\n    const wasActive = (await manager.getActiveId()) === changeset.id;\n    const discardedChanges = changeset.changes.length;\n    await manager.discard(changeset.id!);\n    if (wasActive) {\n      await manager.clearActive();\n    }\n    await reloadModel(args.rootPath);\n\n    return jsonResult({\n      id: changeset.id,\n      name: changeset.name,\n      status: \"discarded\",\n      discardedChanges,\n      deactivated: wasActive,\n    });\n  });\n}\n\nexport const changesetDiscardTool: McpToolDefinition<typeof discardInputSchema> = {\n  name: \"changeset_discard\",\n  description:\n    \"Abandon a staged changeset: PERMANENTLY deletes its staged changes and marks it discarded (deactivating it if \" +\n    \"active). Not recoverable, so it requires confirm: true. The base model is not touched. To undo part of a \" +\n    \"plan use changeset_unstage; to pause it use changeset_deactivate.\",\n  inputSchema: discardInputSchema,\n  handler: changesetDiscardHandler,\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/mcp/tools/changeset-lifecycle.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { StagingAreaManager } from "../../core/staging-area.js";
+import { CLIError, ErrorCategory } from "../../utils/errors.js";
+import { jsonResult, loadModel, reloadModel, rootPathSchema, runTool } from "./shared.js";
+import { resolveChangeset } from "./changeset-shared.js";
+const createInputSchema = {
+  name: z.string().min(1).describe("Short name for the change, e.g. 'add-order-export'."),
+  description: z.string().optional().describe("The change's intent: what it is for and what done looks like. Shown to the human reviewing it."),
+  activate: z.boolean().optional().describe("Make it the active changeset so mutations stage into it (default true)."),
+  rootPath: rootPathSchema
+};
+async function changesetCreateHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model);
+    if (await manager.load(args.name))
+      throw new CLIError(`Changeset '${args.name}' already exists`, ErrorCategory.USER, [
+        `Use "changeset_activate" with "${args.name}" to continue it`,
+        "Or choose another name"
+      ]);
+    const changeset = await manager.create(args.name, args.description), activate = args.activate ?? !0, previouslyActive = activate ? await manager.getActiveId() : null;
+    return activate && (await manager.setActive(changeset.id), await reloadModel(args.rootPath)), jsonResult({
+      id: changeset.id,
+      name: changeset.name,
+      ...changeset.description ? { description: changeset.description } : {},
+      status: changeset.status,
+      active: activate,
+      ...previouslyActive && previouslyActive !== changeset.id ? { deactivated: previouslyActive } : {}
+    });
+  });
+}
+const changesetCreateTool = {
+  name: "changeset_create",
+  description: "Start planning a change: create a changeset carrying the change's intent and (by default) activate it, so model_add / model_update / model_delete / relationship_add / relationship_delete stage into it instead of writing the model. The human commits it later; it is never committed over MCP.",
+  inputSchema: createInputSchema,
+  handler: changesetCreateHandler
+}, activateInputSchema = {
+  changesetId: z.string().describe("Changeset ID or name."),
+  rootPath: rootPathSchema
+};
+async function changesetActivateHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model), changeset = await resolveChangeset(manager, args.changesetId);
+    if (changeset.status !== "staged")
+      throw new CLIError(`Changeset '${changeset.name}' is ${changeset.status} and cannot accept changes`, ErrorCategory.USER, ['Use "changeset_create" to start a new one']);
+    const previouslyActive = await manager.getActiveId();
+    return await manager.setActive(changeset.id), await reloadModel(args.rootPath), jsonResult({
+      id: changeset.id,
+      name: changeset.name,
+      active: !0,
+      changes: changeset.changes.length,
+      ...previouslyActive && previouslyActive !== changeset.id ? { deactivated: previouslyActive } : {}
+    });
+  });
+}
+const changesetActivateTool = {
+  name: "changeset_activate",
+  description: "Make an existing staged changeset the active one, so mutations stage into it.",
+  inputSchema: activateInputSchema,
+  handler: changesetActivateHandler
+}, deactivateInputSchema = {
+  rootPath: rootPathSchema
+};
+async function changesetDeactivateHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model), activeId = await manager.getActiveId();
+    return activeId && (await manager.clearActive(), await reloadModel(args.rootPath)), jsonResult({ deactivated: activeId ?? null });
+  });
+}
+const changesetDeactivateTool = {
+  name: "changeset_deactivate",
+  description: "Deactivate the active changeset. Its changes stay staged; afterwards mutations write the base model directly.",
+  inputSchema: deactivateInputSchema,
+  handler: changesetDeactivateHandler
+};
+export {
+  changesetActivateHandler,
+  changesetActivateTool,
+  changesetCreateHandler,
+  changesetCreateTool,
+  changesetDeactivateHandler,
+  changesetDeactivateTool
+};
+//# sourceMappingURL=changeset-lifecycle.js.map