@usegraft/cli 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/{asset-JWER6AOG.js → asset-CW4YLLHI.js}

@@ -6,6 +6,7 @@ import {
 // src/commands/asset.ts
 import { readFileSync, statSync } from "fs";
 import {
+  AssetKeyTakenError,
   contentTypeFor,
   createStorage,
   defaultKeyFor,
@@ -26,9 +27,28 @@ async function assetPutCommand(options) {
       details: { file: options.file }
     });
   }
-  let storage;
+  const storage = options.storage ?? storageFromEnv();
+  const key = options.key ?? defaultKeyFor(options.file);
+  const keyTaken = () => new GraftError({
+    code: "ASSET_EXISTS",
+    message: `Asset key "${key}" already holds a binary.`,
+    fix: "Pick a distinct key (the store keeps no version history), or pass --overwrite if replacing the existing binary is the actual intent.",
+    details: { key }
+  });
+  const overwrite = options.overwrite === true;
+  if (!overwrite && await storage.exists(key)) throw keyTaken();
+  const contentType = contentTypeFor(options.file);
+  try {
+    await storage.put(key, body, contentType, { ifAbsent: !overwrite });
+  } catch (error) {
+    if (error instanceof AssetKeyTakenError) throw keyTaken();
+    throw error;
+  }
+  return { key, contentType, bytes: body.byteLength };
+}
+function storageFromEnv() {
   try {
-    storage = createStorage(storageConfigFromEnv());
+    return createStorage(storageConfigFromEnv());
   } catch (error) {
     throw new GraftError({
       code: "ENV_VAR_MISSING",
@@ -37,10 +57,6 @@ async function assetPutCommand(options) {
       details: { variables: ["S3_ENDPOINT", "S3_ACCESS_KEY", "S3_SECRET_KEY", "S3_BUCKET"] }
     });
   }
-  const key = options.key ?? defaultKeyFor(options.file);
-  const contentType = contentTypeFor(options.file);
-  await storage.put(key, body, contentType);
-  return { key, contentType, bytes: body.byteLength };
 }
 export {
   assetPutCommand,

package/dist/{chunk-CONTLKSZ.js → chunk-3MR73KWS.js}

@@ -102,7 +102,7 @@ function createNodeListener(handler, options = {}) {
       res.end(
         JSON.stringify({
           error: "FUNCTION_EXECUTION_FAILED",
-          message: `graft serve failed to relay the request: ${error instanceof Error ? error.message : String(error)}`,
+          message: "graft serve failed to relay the request.",
           fix: "Check the server logs; if this reproduces, file it \u2014 the adapter should never throw."
         })
       );
@@ -120,8 +120,34 @@ function localGitSha(cwd) {
     return void 0;
   }
 }
-function trustedIssuersFromEnv() {
-  return (process.env.GRAFT_TRUSTED_ISSUERS ?? "").split(/[,\s]+/).map((issuer) => issuer.trim()).filter(Boolean).map((issuer) => ({ issuer }));
+function listFromEnv(raw) {
+  return (raw ?? "").split(/[,\s]+/).map((item) => item.trim()).filter(Boolean);
+}
+function trustedIssuersFromEnv(env = process.env) {
+  const issuers = listFromEnv(env.GRAFT_TRUSTED_ISSUERS);
+  const audience = listFromEnv(env.GRAFT_TRUSTED_AUDIENCE);
+  if (env.GRAFT_TRUSTED_AUDIENCE?.trim() && audience.length === 0) {
+    throw new GraftError({
+      code: "INPUT_VALIDATION_FAILED",
+      message: `GRAFT_TRUSTED_AUDIENCE is "${env.GRAFT_TRUSTED_AUDIENCE}", which names no audience.`,
+      fix: "Set GRAFT_TRUSTED_AUDIENCE to the audience your provider puts in tokens for this API (comma-separated for several), or unset it.",
+      details: { variable: "GRAFT_TRUSTED_AUDIENCE", value: env.GRAFT_TRUSTED_AUDIENCE }
+    });
+  }
+  const kind = env.GRAFT_TRUSTED_ACTOR_KIND?.trim() || "agent";
+  if (kind !== "agent" && kind !== "human") {
+    throw new GraftError({
+      code: "INPUT_VALIDATION_FAILED",
+      message: `GRAFT_TRUSTED_ACTOR_KIND is "${kind}"; it must be "agent" or "human".`,
+      fix: "Set GRAFT_TRUSTED_ACTOR_KIND=human to record token holders as people, or unset it to record them as agents.",
+      details: { variable: "GRAFT_TRUSTED_ACTOR_KIND", value: kind }
+    });
+  }
+  return issuers.map((issuer) => {
+    const trusted = { issuer, actorKind: kind };
+    if (audience.length > 0) trusted.audience = audience;
+    return trusted;
+  });
 }
 async function startServe(options) {
   loadProjectEnv(options.cwd);
@@ -141,13 +167,13 @@ async function startServe(options) {
     import("@usegraft/db"),
     enableStudio ? import("@usegraft/studio") : Promise.resolve(null)
   ]);
+  const issuers = trustedIssuersFromEnv();
   const control = createDb(url);
   const branchName = options.branchId ?? "main";
   const branch = await resolveBranchHandle(control.db, branchName, { databaseUrl: url });
   const writeBranch = scopeWriteBranch(branch.scope);
   const devToken = process.env.GRAFT_DEV_TOKEN;
-  const scopes = (process.env.GRAFT_DEV_SCOPES ?? "").split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
-  const issuers = trustedIssuersFromEnv();
+  const scopes = listFromEnv(process.env.GRAFT_DEV_SCOPES);
   const resolveActor = createActorResolver({
     issuers,
     devTokens: devToken ? { [devToken]: { kind: "agent", id: "graft-serve", scopes } } : void 0
@@ -208,14 +234,11 @@ async function startServe(options) {
   const health = async () => {
     try {
       await branch.db.execute(sql`select 1`);
-    } catch (error) {
-      return new Response(
-        JSON.stringify({
-          ok: false,
-          error: error instanceof Error ? error.message : String(error)
-        }),
-        { status: 503, headers: { "content-type": "application/json" } }
-      );
+    } catch {
+      return new Response(JSON.stringify({ ok: false, error: "database_unavailable" }), {
+        status: 503,
+        headers: { "content-type": "application/json" }
+      });
     }
     return new Response(
       JSON.stringify({
@@ -247,6 +270,11 @@ async function startServe(options) {
       "[graft serve] WARNING: binding beyond loopback with no identity configured \u2014 MCP will refuse every caller, because there is nothing to authenticate them against. Set GRAFT_DEV_TOKEN or GRAFT_TRUSTED_ISSUERS."
     );
   }
+  if (issuers.length > 0 && issuers.every((issuer) => issuer.audience === void 0)) {
+    console.warn(
+      "[graft serve] WARNING: GRAFT_TRUSTED_ISSUERS is set without GRAFT_TRUSTED_AUDIENCE \u2014 any token those issuers sign is accepted, including one minted for another of your apps. Set GRAFT_TRUSTED_AUDIENCE to the audience your provider puts in tokens for this API."
+    );
+  }
   if (approvalPolicy === "unattended") {
     console.warn(
       '[graft serve] WARNING: approvalPolicy = "unattended" in graft.config.ts \u2014 destructive functions run without human approval. Deletes are not recoverable from git: deleteRecord removes rows outright and the asset store keeps no history. Audit rows are still written. This applies to POST /api/fn only; run_function over /api/mcp stays gated, because the policy is not part of the MCP surface.'
@@ -333,6 +361,7 @@ export {
   createServeRouter,
   allowedHostsFor,
   createNodeListener,
+  trustedIssuersFromEnv,
   startServe,
   serveCommand
 };

package/dist/{chunk-GPA66AP5.js → chunk-NGTFEGKI.js}

@@ -15,8 +15,18 @@ function formatCompileResult(result) {
   for (const key of removed) lines.push(`  removed  ${key}`);
   return lines.join("\n");
 }
+function formatCompileJson(branch, result) {
+  const { added, changed, removed, unchanged } = result.changes;
+  const output = {
+    branch,
+    gitSha: result.gitSha,
+    changes: { added, changed, removed, unchanged }
+  };
+  return JSON.stringify(output);
+}
 
 export {
   printGraftError,
-  formatCompileResult
+  formatCompileResult,
+  formatCompileJson
 };

package/dist/{chunk-DW6WTDRX.js → chunk-OUS3SWFF.js}

@@ -66,13 +66,14 @@ Author one as migrations/0001-<name>.ts default-exporting defineContentMigration
       listAppliedMigrations,
       recordAppliedMigration,
       resolveBranchHandle,
-      scopeWriteBranch
+      scopeWriteBranch,
+      withMigrationLock
     }
   ] = await Promise.all([import("@usegraft/compiler"), import("@usegraft/db")]);
   const control = createDb(url);
   const branch = await resolveBranchHandle(control.db, branchId, { databaseUrl: url });
   const writeBranch = scopeWriteBranch(branch.scope);
-  try {
+  const run = async () => {
     const appliedRows = await listAppliedMigrations(branch.db, writeBranch);
     const appliedIds = new Set(appliedRows.map((row) => row.migrationId));
     const applied = migrations.filter((m) => appliedIds.has(m.id)).map((m) => m.id);
@@ -161,6 +162,15 @@ ${outcomes.length} migration(s) applied. Commit the changes \u2014 git is the ve
       );
     }
     return { applied, pending: outcomes, didApply: options.apply === true };
+  };
+  try {
+    if (!options.apply) return await run();
+    return await withMigrationLock(branch.db, writeBranch, run, {
+      onWait: () => (
+        // A merge into this branch holds the same lock, so name both.
+        console.log(`A migration or merge is running on "${branchId}"; waiting for it to finish\u2026`)
+      )
+    });
   } finally {
     await branch.close();
     await control.close();

package/dist/{chunk-2N3HXYNN.js → chunk-QKZ25AA5.js}

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
+  formatCompileJson,
   formatCompileResult
-} from "./chunk-GPA66AP5.js";
+} from "./chunk-NGTFEGKI.js";
 import {
   findConfig,
   loadConfig,
@@ -21,6 +22,22 @@ function assertNoStaticBranch(branchId) {
   });
 }
 async function compileCommand(options) {
+  if (!options.json) return (await runCompile(options)).result;
+  const { log, info, debug } = console;
+  const write = process.stdout.write;
+  console.log = console.info = console.debug = console.error;
+  process.stdout.write = process.stderr.write.bind(process.stderr);
+  let compiled;
+  try {
+    compiled = await runCompile(options);
+  } finally {
+    process.stdout.write = write;
+    Object.assign(console, { log, info, debug });
+  }
+  console.log(formatCompileJson(compiled.branch, compiled.result));
+  return compiled.result;
+}
+async function runCompile(options) {
   loadProjectEnv(options.cwd);
   const config = await loadConfig(findConfig(options.cwd));
   if (config.index.driver === "static") {
@@ -33,7 +50,7 @@ async function compileCommand(options) {
       indexPath: config.index.path
     });
     console.log(formatCompileResult(result));
-    return result;
+    return { branch: "main", result };
   }
   const url = requireDatabaseUrl();
   const [{ compile }, { createDb, resolveBranchHandle, scopeWriteBranch }] = await Promise.all([
@@ -58,7 +75,7 @@ async function compileCommand(options) {
         pruneUnknown: options.pruneUnknown
       });
       console.log(formatCompileResult(result));
-      return result;
+      return { branch: branch.name, result };
     } finally {
       await branch.close();
     }

package/dist/{compile-AWPSEA7U.js → compile-TOEGDGNU.js}

@@ -2,8 +2,8 @@
 import {
   assertNoStaticBranch,
   compileCommand
-} from "./chunk-2N3HXYNN.js";
-import "./chunk-GPA66AP5.js";
+} from "./chunk-QKZ25AA5.js";
+import "./chunk-NGTFEGKI.js";
 import "./chunk-2LG6TWYY.js";
 export {
   assertNoStaticBranch,

package/dist/{dev-WHTIRWMR.js → dev-LOELDVLT.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   assertNoStaticBranch
-} from "./chunk-2N3HXYNN.js";
+} from "./chunk-QKZ25AA5.js";
 import {
   formatCompileResult,
   printGraftError
-} from "./chunk-GPA66AP5.js";
+} from "./chunk-NGTFEGKI.js";
 import {
   CONFIG_FILENAMES,
   findConfig,

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   printGraftError
-} from "./chunk-GPA66AP5.js";
+} from "./chunk-NGTFEGKI.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -35,7 +35,7 @@ function printHelp() {
     "  add <item>               Copy an owned primitive from the registry into graft/",
     "                           (+ its deps; regenerates the graft/ barrel \u2014 no config edit)",
     "  mcp                      Serve the project MCP over stdio (content + function tools;",
-    "                           for .mcp.json / local agents). Requires DATABASE_URL.",
+    "                           for .mcp.json / local agents). Postgres needs DATABASE_URL.",
     "  serve                    Run the headless Graft runtime over HTTP: POST /api/fn/<name>,",
     "                           POST /api/mcp, GET /healthz (what a self-host container runs)",
     "  studio                   Opt-in Studio UI (edit content, approve/deny, OpenAPI)",
@@ -62,14 +62,212 @@ function printHelp() {
     "  --postgres       Scaffold `graft init` for the Postgres index (default: static)",
     "  --static         Scaffold `graft init` for the static index (the default)",
     "  --dry-run        Preview `graft add` without writing; list pending `graft db migrate`",
-    "  --overwrite      Let `graft add` replace files that differ",
+    "  --overwrite      Let `graft add` replace files that differ, and `graft asset put`",
+    "                   replace a binary already stored under the key",
     "  --prune-unknown  Let `graft compile` remove index rows in collections this schema",
     "                   doesn't know (default: refuse \u2014 the shared-DATABASE_URL guard)",
-    "  -h, --help       Show this help",
+    "  --json           `graft compile` prints { branch, gitSha, changes } as JSON on stdout",
+    "                   (logs go to stderr), ready to POST to a revalidate route",
+    "  -h, --help       Show this help, or one command's help after the command name",
     "  -v, --version    Show version"
   ];
   console.log(lines.join("\n"));
 }
+var BRANCH_OPTION = "  --branch <id>    Content branch (default: main)";
+var COMMAND_HELP = /* @__PURE__ */ new Map([
+  [
+    "init",
+    [
+      "Usage: graft init [dir] [--static | --postgres]",
+      "",
+      "Scaffold a Graft project (graft.config.ts, content/, llms.txt) in dir (default: here).",
+      "",
+      "  --static         Static index: no database, no env (the default)",
+      "  --postgres       Postgres index: operational data, functions, DB branching"
+    ]
+  ],
+  [
+    "compile",
+    [
+      "Usage: graft compile [--branch <id>] [--prune-unknown] [--json]",
+      "",
+      "Project the content tree into the content index once.",
+      "",
+      BRANCH_OPTION,
+      "  --prune-unknown  Remove index rows in collections this schema doesn't know",
+      "                   (default: refuse, the shared-DATABASE_URL guard)",
+      "  --json           Print { branch, gitSha, changes } as JSON on stdout (logs go to stderr)"
+    ]
+  ],
+  [
+    "dev",
+    [
+      "Usage: graft dev [--branch <id>]",
+      "",
+      "Watch content/ and graft.config.ts and recompile on change.",
+      "",
+      BRANCH_OPTION
+    ]
+  ],
+  [
+    "db",
+    [
+      "Usage: graft db migrate [--dry-run]",
+      "",
+      "Apply the Postgres schema migrations that ship with @usegraft/db.",
+      "",
+      "  --dry-run        List pending schema migrations without applying them"
+    ]
+  ],
+  [
+    "asset",
+    [
+      "Usage: graft asset put <file> [key] [--overwrite]",
+      "",
+      "Upload a binary to the asset store (S3_* env) and print the frontmatter reference.",
+      "The key defaults to assets/<sanitized file name>. A key that already holds a",
+      "binary is refused with ASSET_EXISTS, because the store keeps no version history.",
+      "",
+      "  --overwrite      Replace the binary already stored under the key"
+    ]
+  ],
+  [
+    "approvals",
+    [
+      "Usage: graft approvals",
+      "",
+      "List pending approvals for human-gated (destructive) function calls."
+    ]
+  ],
+  [
+    "approve",
+    [
+      "Usage: graft approve <approval-id>",
+      "",
+      "Approve a pending approval. The caller retries with x-graft-approval: <id>."
+    ]
+  ],
+  ["deny", ["Usage: graft deny <approval-id>", "", "Deny a pending approval."]],
+  [
+    "migrate",
+    [
+      "Usage: graft migrate [--apply] [--branch <id>]",
+      "",
+      "Show pending content and data migrations (dry-run). --apply runs them and records",
+      "each in the ledger. A concurrent --apply on the same branch waits for this one",
+      "and then skips what it applied.",
+      "",
+      BRANCH_OPTION,
+      "  --apply          Run the pending migrations (default is a dry-run report)"
+    ]
+  ],
+  [
+    "branch",
+    [
+      "Usage: graft branch",
+      "       graft branch create <name> [--from <parent>] [--backend overlay|neon]",
+      "       graft branch drop <name>",
+      "",
+      "List, register, or drop preview branches.",
+      "",
+      "  --from <name>    Parent to fork from (default: main)",
+      "  --backend <kind> overlay (default) or neon (forks a physical Neon branch)"
+    ]
+  ],
+  [
+    "merge",
+    [
+      "Usage: graft merge <branch> [--into <target>] [--apply]",
+      "",
+      "Merge a branch into its target: replay the ledger, move data rows, recompile.",
+      "",
+      "  --into <name>    Merge target (default: main)",
+      "  --apply          Execute the merge (default is a dry-run report)"
+    ]
+  ],
+  [
+    "add",
+    [
+      "Usage: graft add <item...> [--dry-run] [--overwrite]",
+      "",
+      "Copy an owned primitive (and its deps) from the registry into graft/.",
+      "",
+      "  --dry-run        Preview without writing",
+      "  --overwrite      Replace files that differ"
+    ]
+  ],
+  [
+    "mcp",
+    [
+      "Usage: graft mcp [--branch <id>] [--elicit-approvals]",
+      "",
+      "Serve the project MCP over stdio (content and function tools). On the Postgres engine it needs DATABASE_URL.",
+      "",
+      BRANCH_OPTION,
+      "  --elicit-approvals",
+      "                   Ask this terminal's operator to decide a destructive call instead",
+      "                   of failing with an id for `graft approve`"
+    ]
+  ],
+  [
+    "serve",
+    [
+      "Usage: graft serve [--port <n>] [--host <h>] [--branch <id>] [--studio]",
+      "",
+      "Run the headless Graft runtime over HTTP: POST /api/fn/<name>, POST /api/mcp,",
+      "GET /api/content/v1/*, GET /healthz.",
+      "",
+      BRANCH_OPTION,
+      "  --port <n>       Port (default: 3903, or PORT)",
+      "  --host <h>       Host (default: 127.0.0.1, or HOST)",
+      "  --studio         Mount Studio at /studio (or GRAFT_STUDIO=1)"
+    ]
+  ],
+  [
+    "studio",
+    [
+      "Usage: graft studio [--port <n>] [--host <h>] [--branch <id>]",
+      "",
+      "Run the opt-in Studio UI (edit content, approve/deny, OpenAPI).",
+      "",
+      BRANCH_OPTION,
+      "  --port <n>       Port (default: 4983, or GRAFT_STUDIO_PORT)",
+      "  --host <h>       Host (default: 127.0.0.1, or HOST)"
+    ]
+  ],
+  [
+    "content",
+    [
+      "Usage: graft content [--branch <id>]",
+      "",
+      "List the content tree from the compiled index.",
+      "",
+      BRANCH_OPTION
+    ]
+  ],
+  [
+    "compilations",
+    [
+      "Usage: graft compilations [--branch <id>]",
+      "",
+      "List recent content projection trail rows.",
+      "",
+      BRANCH_OPTION
+    ]
+  ],
+  [
+    "harden",
+    [
+      "Usage: graft harden <role>",
+      "",
+      "Grant an existing Postgres role the runtime privilege set: it can request and",
+      "consume approvals but never decide them."
+    ]
+  ]
+]);
+function isHelpFlag(arg) {
+  return arg === "--help" || arg === "-h";
+}
 var UsageError = class extends Error {
 };
 function parseArgs(rest) {
@@ -86,6 +284,7 @@ function parseArgs(rest) {
   let pruneUnknown = false;
   let studio = false;
   let elicitApprovals = false;
+  let json = false;
   let initDriver;
   const value = (flag, raw) => {
     if (!raw || raw.startsWith("-")) {
@@ -123,10 +322,13 @@ function parseArgs(rest) {
       studio = true;
     } else if (arg === "--elicit-approvals") {
       elicitApprovals = true;
+    } else if (arg === "--json") {
+      json = true;
     } else if (arg === "--postgres") {
       initDriver = "postgres";
     } else if (arg === "--static") {
       initDriver = "static";
+    } else if (isHelpFlag(arg)) {
     } else if (arg.startsWith("-")) {
       throw new UsageError(`unknown option "${arg}"`);
     } else {
@@ -147,6 +349,7 @@ function parseArgs(rest) {
     pruneUnknown,
     studio,
     elicitApprovals,
+    json,
     initDriver
   };
 }
@@ -157,10 +360,15 @@ async function run(argv, options = {}) {
     console.log(VERSION);
     return 0;
   }
-  if (!command || command === "-h" || command === "--help") {
+  if (!command || isHelpFlag(command)) {
     printHelp();
     return 0;
   }
+  const usage = COMMAND_HELP.get(command);
+  if (usage && rest.some(isHelpFlag)) {
+    console.log(usage.join("\n"));
+    return 0;
+  }
   try {
     const args = parseArgs(rest);
     switch (command) {
@@ -196,12 +404,17 @@ async function run(argv, options = {}) {
         return 0;
       }
       case "compile": {
-        const { compileCommand } = await import("./compile-AWPSEA7U.js");
-        await compileCommand({ cwd, branchId: args.branchId, pruneUnknown: args.pruneUnknown });
+        const { compileCommand } = await import("./compile-TOEGDGNU.js");
+        await compileCommand({
+          cwd,
+          branchId: args.branchId,
+          pruneUnknown: args.pruneUnknown,
+          json: args.json
+        });
         return 0;
       }
       case "dev": {
-        const { devCommand } = await import("./dev-WHTIRWMR.js");
+        const { devCommand } = await import("./dev-LOELDVLT.js");
         await devCommand({ cwd, branchId: args.branchId });
         return 0;
       }
@@ -220,10 +433,10 @@ async function run(argv, options = {}) {
       case "asset": {
         const [subcommand, file, key] = args.positionals;
         if (subcommand !== "put" || !file) {
-          throw new UsageError("usage: graft asset put <file> [key]");
+          throw new UsageError("usage: graft asset put <file> [key] [--overwrite]");
         }
-        const { assetPutCommand } = await import("./asset-JWER6AOG.js");
-        const result = await assetPutCommand({ cwd, file, key });
+        const { assetPutCommand } = await import("./asset-CW4YLLHI.js");
+        const result = await assetPutCommand({ cwd, file, key, overwrite: args.overwrite });
         console.log(`Uploaded ${result.key} (${result.contentType}, ${result.bytes} bytes)`);
         console.log(
           [
@@ -268,7 +481,7 @@ async function run(argv, options = {}) {
         return 0;
       }
       case "migrate": {
-        const { migrateCommand } = await import("./migrate-6ZYG2H5C.js");
+        const { migrateCommand } = await import("./migrate-JK5RLOOI.js");
         await migrateCommand({ cwd, branchId: args.branchId, apply: args.apply });
         return 0;
       }
@@ -325,7 +538,7 @@ async function run(argv, options = {}) {
         const branch = args.positionals[0];
         if (!branch)
           throw new UsageError("usage: graft merge <branch> [--into <target>] [--apply]");
-        const { mergeCommand } = await import("./merge-ZWYZJVFE.js");
+        const { mergeCommand } = await import("./merge-JMJYARB4.js");
         await mergeCommand({ cwd, branch, into: args.into, apply: args.apply });
         return 0;
       }
@@ -340,12 +553,12 @@ async function run(argv, options = {}) {
         return 0;
       }
       case "mcp": {
-        const { mcpCommand } = await import("./mcp-77QFFJXK.js");
+        const { mcpCommand } = await import("./mcp-7RP4G34K.js");
         await mcpCommand({ cwd, branchId: args.branchId, elicitApprovals: args.elicitApprovals });
         return 0;
       }
       case "serve": {
-        const { serveCommand } = await import("./serve-5ADUQG66.js");
+        const { serveCommand } = await import("./serve-2FRRKKGY.js");
         await serveCommand({
           cwd,
           branchId: args.branchId,
@@ -356,7 +569,7 @@ async function run(argv, options = {}) {
         return 0;
       }
       case "studio": {
-        const { studioCommand } = await import("./studio-7VAYFEWS.js");
+        const { studioCommand } = await import("./studio-GJB5NFPB.js");
         await studioCommand({
           cwd,
           branchId: args.branchId,

package/dist/{mcp-77QFFJXK.js → mcp-7RP4G34K.js}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   assertNoStaticBranch
-} from "./chunk-2N3HXYNN.js";
-import "./chunk-GPA66AP5.js";
+} from "./chunk-QKZ25AA5.js";
+import "./chunk-NGTFEGKI.js";
 import {
   operatorName
 } from "./chunk-NBJ4N4O6.js";

package/dist/{merge-ZWYZJVFE.js → merge-JMJYARB4.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   discoverMigrations
-} from "./chunk-DW6WTDRX.js";
+} from "./chunk-OUS3SWFF.js";
 import {
   findConfig,
   loadConfig,
@@ -48,7 +48,8 @@ async function mergeCommand(options) {
       moveDataRecords,
       copyDataRecords,
       resolveBranchHandle,
-      scopeWriteBranch
+      scopeWriteBranch,
+      withMigrationLock
     },
     { runDataMigration }
   ] = await Promise.all([
@@ -70,7 +71,7 @@ async function mergeCommand(options) {
   const srcWrite = scopeWriteBranch(src.scope);
   const targetWrite = scopeWriteBranch(target.scope);
   const sameDb = src.scope.kind === "overlay" && target.scope.kind === "overlay";
-  try {
+  const run = async () => {
     const [branchLedger, targetLedger] = await Promise.all([
       listAppliedMigrations(src.db, srcWrite),
       listAppliedMigrations(target.db, targetWrite)
@@ -164,6 +165,20 @@ Dry run \u2014 nothing was written. git-merge the branch's commits first if you
       );
     }
     return { replayed, dataMoved, compiled, didApply: options.apply === true };
+  };
+  try {
+    if (!options.apply) return await run();
+    const [first, second] = [
+      { db: src.db, branch: srcWrite, name: options.branch },
+      { db: target.db, branch: targetWrite, name: into }
+    ].sort((a, b) => a.name.localeCompare(b.name));
+    const waitFor = (name) => () => console.log(`A migration or merge is running on "${name}"; waiting for it to finish\u2026`);
+    return await withMigrationLock(
+      first.db,
+      first.branch,
+      () => withMigrationLock(second.db, second.branch, run, { onWait: waitFor(second.name) }),
+      { onWait: waitFor(first.name) }
+    );
   } finally {
     await src.close();
     await target.close();

package/dist/{migrate-6ZYG2H5C.js → migrate-JK5RLOOI.js}

@@ -2,7 +2,7 @@
 import {
   discoverMigrations,
   migrateCommand
-} from "./chunk-DW6WTDRX.js";
+} from "./chunk-OUS3SWFF.js";
 import "./chunk-2LG6TWYY.js";
 export {
   discoverMigrations,

package/dist/{serve-5ADUQG66.js → serve-2FRRKKGY.js}

@@ -4,13 +4,15 @@ import {
   createNodeListener,
   createServeRouter,
   serveCommand,
-  startServe
-} from "./chunk-CONTLKSZ.js";
+  startServe,
+  trustedIssuersFromEnv
+} from "./chunk-3MR73KWS.js";
 import "./chunk-2LG6TWYY.js";
 export {
   allowedHostsFor,
   createNodeListener,
   createServeRouter,
   serveCommand,
-  startServe
+  startServe,
+  trustedIssuersFromEnv
 };

package/dist/studio-GJB5NFPB.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import {
+  allowedHostsFor,
+  createNodeListener
+} from "./chunk-3MR73KWS.js";
+import {
+  findConfig,
+  loadConfig,
+  loadProjectEnv,
+  requireDatabaseUrl
+} from "./chunk-2LG6TWYY.js";
+
+// src/commands/studio.ts
+import { execFile } from "child_process";
+import { createServer } from "http";
+import { userInfo } from "os";
+import { GraftError } from "@usegraft/contracts";
+function isLoopback(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+function operatorIdentity() {
+  try {
+    return { kind: "human", id: userInfo().username };
+  } catch {
+    return { kind: "human", id: process.env.USERNAME ?? process.env.USER ?? "operator" };
+  }
+}
+function isGitPreviewBranch(branch) {
+  if (branch === "" || branch === "@") return false;
+  if (branch.includes("..") || branch.includes("@{") || branch.includes("//") || branch.includes("\\")) {
+    return false;
+  }
+  if (branch.startsWith("/") || branch.endsWith("/") || branch.endsWith(".")) return false;
+  if (!/^[A-Za-z0-9._/@+-]+$/.test(branch)) return false;
+  return branch.split("/").every((part) => part.length > 0 && !part.startsWith(".") && !part.endsWith(".lock"));
+}
+function assertGitPreviewBranch(branch) {
+  if (isGitPreviewBranch(branch)) return;
+  throw new GraftError({
+    code: "INPUT_VALIDATION_FAILED",
+    message: `Branch "${branch}" is not a safe preview query value.`,
+    fix: "Use a git-ref-shaped branch name (letters, digits, . _ / @ + -)."
+  });
+}
+function studioPreviewUrl(port, branch) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new GraftError({
+      code: "INPUT_VALIDATION_FAILED",
+      message: `"${port}" is not a valid bound port.`,
+      fix: "Pass --port <1-65535> (0 picks a free port, then we read the one that bound)."
+    });
+  }
+  assertGitPreviewBranch(branch);
+  const preview = new URL(`http://127.0.0.1:${port}/`);
+  preview.searchParams.set("branch", branch);
+  if (preview.protocol !== "http:" || preview.hostname !== "127.0.0.1") {
+    throw new GraftError({
+      code: "INPUT_VALIDATION_FAILED",
+      message: `Preview URL is not loopback http.`,
+      fix: "graft studio only opens http://127.0.0.1."
+    });
+  }
+  return preview.href;
+}
+function openBrowser(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return;
+  }
+  if (parsed.protocol !== "http:" || parsed.hostname !== "127.0.0.1") return;
+  const platform = process.platform;
+  const cmd = platform === "win32" ? "cmd" : platform === "darwin" ? "open" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", parsed.href] : [parsed.href];
+  execFile(cmd, args, () => {
+  });
+}
+async function studioCommand(options) {
+  loadProjectEnv(options.cwd);
+  const config = await loadConfig(findConfig(options.cwd));
+  const url = requireDatabaseUrl();
+  const [{ createStudioHandler }, { createDb, resolveBranchHandle, scopeWriteBranch }] = await Promise.all([import("@usegraft/studio"), import("@usegraft/db")]);
+  const branchName = options.branchId ?? "main";
+  assertGitPreviewBranch(branchName);
+  const control = createDb(url);
+  try {
+    const branch = await resolveBranchHandle(control.db, branchName, { databaseUrl: url });
+    const writeBranch = scopeWriteBranch(branch.scope);
+    let server;
+    try {
+      const host = options.host ?? process.env.HOST ?? "127.0.0.1";
+      const requestedPort = options.port ?? Number(process.env.GRAFT_STUDIO_PORT ?? 4983);
+      if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
+        throw new GraftError({
+          code: "INPUT_VALIDATION_FAILED",
+          message: `"${options.port ?? process.env.GRAFT_STUDIO_PORT}" is not a valid port.`,
+          fix: "Pass --port <0-65535> (0 picks a free port)."
+        });
+      }
+      const loopback = isLoopback(host);
+      const devToken = process.env.GRAFT_DEV_TOKEN;
+      if (!loopback && !devToken) {
+        console.warn(
+          "[graft studio] WARNING: binding beyond loopback with no GRAFT_DEV_TOKEN \u2014 set a bearer token before exposing Studio to a network."
+        );
+      }
+      const authenticate = !loopback && devToken ? (request) => {
+        const header = request.headers.get("authorization") ?? "";
+        if (header !== `Bearer ${devToken}`) return null;
+        return {
+          ...operatorIdentity(),
+          scopes: ["studio:read", "studio:write", "approvals:decide"]
+        };
+      } : !loopback ? () => null : void 0;
+      const handler = createStudioHandler({
+        db: branch.db,
+        collections: config.collections,
+        contentDir: config.contentDir,
+        mdxTrust: config.mdxTrust,
+        defaultBranch: writeBranch,
+        decider: operatorIdentity,
+        authenticate
+      });
+      const listening = createServer(
+        createNodeListener(handler, { allowedHosts: allowedHostsFor(host) })
+      );
+      server = listening;
+      await new Promise((resolve, reject) => {
+        listening.once("error", reject);
+        listening.listen(requestedPort, host, () => resolve());
+      });
+      const address = listening.address();
+      const port = typeof address === "object" && address ? address.port : requestedPort;
+      const origin = loopback ? `http://127.0.0.1:${port}` : `http://${host}:${port}`;
+      console.log(
+        [
+          `graft studio \u2014 branch "${branchName}" (opt-in)`,
+          `  ui         GET  ${origin}/`,
+          `  openapi    GET  ${origin}/api/studio/v1/openapi.json`,
+          `  Edit content, approve/deny \u2014 same ops as MCP/CLI.`
+        ].join("\n")
+      );
+      if (loopback) openBrowser(studioPreviewUrl(port, branchName));
+      await new Promise((resolve) => {
+        const stop = () => resolve();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+      });
+    } finally {
+      const bound = server;
+      if (bound?.listening) {
+        await new Promise((resolve, reject) => {
+          bound.close((err) => err ? reject(err) : resolve());
+        });
+      }
+      await branch.close();
+    }
+  } finally {
+    await control.close();
+  }
+}
+export {
+  studioCommand,
+  studioPreviewUrl
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usegraft/cli",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "The graft CLI: scaffold, compile authored content, serve the runtime, and split your database credentials.",
   "keywords": [
     "agent",
@@ -34,22 +34,22 @@
     "access": "public"
   },
   "dependencies": {
-    "@usegraft/assets": "1.0.0-beta.1",
-    "@usegraft/auth": "1.0.0-beta.1",
-    "@usegraft/compiler": "1.0.0-beta.1",
-    "@usegraft/content-api": "1.0.0-beta.1",
-    "@usegraft/content-migrations": "1.0.0-beta.1",
-    "@usegraft/contracts": "1.0.0-beta.1",
-    "@usegraft/core": "1.0.0-beta.1",
-    "@usegraft/db": "1.0.0-beta.1",
-    "@usegraft/mcp": "1.0.0-beta.1",
-    "@usegraft/mdx-safety": "1.0.0-beta.1",
-    "@usegraft/registry": "1.0.0-beta.1",
-    "@usegraft/studio": "1.0.0-beta.1",
+    "@usegraft/assets": "1.0.0-beta.3",
+    "@usegraft/auth": "1.0.0-beta.3",
+    "@usegraft/compiler": "1.0.0-beta.3",
+    "@usegraft/content-api": "1.0.0-beta.3",
+    "@usegraft/content-migrations": "1.0.0-beta.3",
+    "@usegraft/contracts": "1.0.0-beta.3",
+    "@usegraft/core": "1.0.0-beta.3",
+    "@usegraft/db": "1.0.0-beta.3",
+    "@usegraft/mcp": "1.0.0-beta.3",
+    "@usegraft/mdx-safety": "1.0.0-beta.3",
+    "@usegraft/registry": "1.0.0-beta.3",
+    "@usegraft/studio": "1.0.0-beta.3",
     "jiti": "^2.7.0"
   },
   "devDependencies": {
-    "@usegraft/sdk-core": "1.0.0-beta.1"
+    "@usegraft/sdk-core": "1.0.0-beta.3"
   },
   "engines": {
     "node": ">=22.16"

package/dist/studio-7VAYFEWS.js

@@ -1,109 +0,0 @@
-#!/usr/bin/env node
-import {
-  allowedHostsFor,
-  createNodeListener
-} from "./chunk-CONTLKSZ.js";
-import {
-  findConfig,
-  loadConfig,
-  loadProjectEnv,
-  requireDatabaseUrl
-} from "./chunk-2LG6TWYY.js";
-
-// src/commands/studio.ts
-import { execFile } from "child_process";
-import { createServer } from "http";
-import { userInfo } from "os";
-import { GraftError } from "@usegraft/contracts";
-function isLoopback(host) {
-  return host === "127.0.0.1" || host === "localhost" || host === "::1";
-}
-function operatorIdentity() {
-  try {
-    return { kind: "human", id: userInfo().username };
-  } catch {
-    return { kind: "human", id: process.env.USERNAME ?? process.env.USER ?? "operator" };
-  }
-}
-function openBrowser(url) {
-  const platform = process.platform;
-  const cmd = platform === "win32" ? "cmd" : platform === "darwin" ? "open" : "xdg-open";
-  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-  execFile(cmd, args, () => {
-  });
-}
-async function studioCommand(options) {
-  loadProjectEnv(options.cwd);
-  const config = await loadConfig(findConfig(options.cwd));
-  const url = requireDatabaseUrl();
-  const [{ createStudioHandler }, { createDb, resolveBranchHandle, scopeWriteBranch }] = await Promise.all([import("@usegraft/studio"), import("@usegraft/db")]);
-  const control = createDb(url);
-  const branchName = options.branchId ?? "main";
-  const branch = await resolveBranchHandle(control.db, branchName, { databaseUrl: url });
-  const writeBranch = scopeWriteBranch(branch.scope);
-  const host = options.host ?? process.env.HOST ?? "127.0.0.1";
-  const requestedPort = options.port ?? Number(process.env.GRAFT_STUDIO_PORT ?? 4983);
-  if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
-    await branch.close();
-    await control.close();
-    throw new GraftError({
-      code: "INPUT_VALIDATION_FAILED",
-      message: `"${options.port ?? process.env.GRAFT_STUDIO_PORT}" is not a valid port.`,
-      fix: "Pass --port <0-65535> (0 picks a free port)."
-    });
-  }
-  const loopback = isLoopback(host);
-  const devToken = process.env.GRAFT_DEV_TOKEN;
-  if (!loopback && !devToken) {
-    console.warn(
-      "[graft studio] WARNING: binding beyond loopback with no GRAFT_DEV_TOKEN \u2014 set a bearer token before exposing Studio to a network."
-    );
-  }
-  const authenticate = !loopback && devToken ? (request) => {
-    const header = request.headers.get("authorization") ?? "";
-    if (header !== `Bearer ${devToken}`) return null;
-    return {
-      ...operatorIdentity(),
-      scopes: ["studio:read", "studio:write", "approvals:decide"]
-    };
-  } : !loopback ? () => null : void 0;
-  const handler = createStudioHandler({
-    db: branch.db,
-    collections: config.collections,
-    contentDir: config.contentDir,
-    mdxTrust: config.mdxTrust,
-    defaultBranch: writeBranch,
-    decider: operatorIdentity,
-    authenticate
-  });
-  const server = createServer(createNodeListener(handler, { allowedHosts: allowedHostsFor(host) }));
-  await new Promise((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(requestedPort, host, () => resolve());
-  });
-  const address = server.address();
-  const port = typeof address === "object" && address ? address.port : requestedPort;
-  const base = `http://${host}:${port}`;
-  console.log(
-    [
-      `graft studio \u2014 branch "${branchName}" (opt-in)`,
-      `  ui         GET  ${base}/`,
-      `  openapi    GET  ${base}/api/studio/v1/openapi.json`,
-      `  Edit content, approve/deny \u2014 same ops as MCP/CLI.`
-    ].join("\n")
-  );
-  if (loopback) openBrowser(`${base}/?branch=${encodeURIComponent(branchName)}`);
-  await new Promise((resolve) => {
-    const stop = () => resolve();
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
-  });
-  await new Promise((resolve, reject) => {
-    server.close((err) => err ? reject(err) : resolve());
-  });
-  await branch.close();
-  await control.close();
-}
-export {
-  studioCommand
-};