@01.software/cli 0.10.6 → 0.11.1

package/dist/index.js

@@ -129,27 +129,32 @@ ${entry}
 // src/lib/output.ts
 import pc from "picocolors";
 
-// src/lib/admin-error.ts
-var PERMISSION_CODES = [
-  "tenant_mismatch",
-  "account_suspended",
-  "feature_disabled",
-  "role_denied",
-  "credential_invalid",
-  "pat_tenant_unpinned",
-  "publishable_key_mismatch",
-  "scope_denied"
-];
-var DEGRADED_CODES = [
-  "redis_unavailable",
-  "provider_unavailable",
-  "rate_limited"
-];
-var NETWORK_CODES = [
-  "upstream_timeout",
-  "upstream_5xx",
-  "dns_failure"
-];
+// ../errors/src/admin-error.ts
+var ADMIN_ERROR_CODES = {
+  permission: [
+    "tenant_mismatch",
+    "account_suspended",
+    "feature_disabled",
+    "role_denied",
+    "credential_invalid",
+    "pat_tenant_unpinned",
+    "publishable_key_mismatch",
+    "scope_denied"
+  ],
+  degraded: [
+    "redis_unavailable",
+    "provider_unavailable",
+    "rate_limited"
+  ],
+  network: [
+    "upstream_timeout",
+    "upstream_5xx",
+    "dns_failure"
+  ]
+};
+var PERMISSION_CODES = ADMIN_ERROR_CODES.permission;
+var DEGRADED_CODES = ADMIN_ERROR_CODES.degraded;
+var NETWORK_CODES = ADMIN_ERROR_CODES.network;
 function isPermissionCode(code) {
   return PERMISSION_CODES.includes(code);
 }
@@ -159,7 +164,10 @@ function isDegradedCode(code) {
 function isNetworkCode(code) {
   return NETWORK_CODES.includes(code);
 }
-function classifyError(err) {
+function isUnknownAdminError(err) {
+  return err.type === "validation" && err.code === "unknown";
+}
+function classifyAdminError(err) {
   if (err && typeof err === "object") {
     const obj = err;
     if (typeof obj.code === "string") {
@@ -167,9 +175,6 @@ function classifyError(err) {
       if (isPermissionCode(code)) {
         return { type: "permission", code };
       }
-      if (code === "auth_error" || code === "permission_error") {
-        return { type: "permission", code: "credential_invalid" };
-      }
       if (isDegradedCode(code)) {
         const out = { type: "degraded", code };
         if (typeof obj.retryAfter === "number") {
@@ -189,33 +194,6 @@ function classifyError(err) {
       }
       return out;
     }
-    const name = typeof obj.name === "string" ? obj.name : void 0;
-    const status = typeof obj.status === "number" ? obj.status : void 0;
-    if (name === "ConfigError" || name === "AuthError" || name === "PermissionError" || status === 401 || status === 403) {
-      return { type: "permission", code: "credential_invalid" };
-    }
-    if (name === "NetworkError" || name === "TimeoutError" || status === 408 || status === 503) {
-      return { type: "network", code: "upstream_timeout" };
-    }
-    if (name === "GoneError" || status === 404) {
-      return {
-        type: "validation",
-        code: "not_found",
-        detail: typeof obj.message === "string" ? { message: obj.message } : void 0
-      };
-    }
-    if (name === "UsageLimitError" || status === 429) {
-      const out = { type: "degraded", code: "rate_limited" };
-      if (typeof obj.retryAfter === "number") out.retryAfter = obj.retryAfter;
-      return out;
-    }
-    if (name === "ValidationError" || status === 400 || status === 422) {
-      return {
-        type: "validation",
-        code: "invalid_argument",
-        detail: typeof obj.message === "string" ? { message: obj.message } : void 0
-      };
-    }
   }
   return {
     type: "validation",
@@ -223,6 +201,48 @@ function classifyError(err) {
     detail: { message: err instanceof Error ? err.message : String(err) }
   };
 }
+
+// src/lib/admin-error.ts
+function classifyCliExtensions(err) {
+  if (!err || typeof err !== "object") return null;
+  const obj = err;
+  if (obj.code === "auth_error" || obj.code === "permission_error") {
+    return { type: "permission", code: "credential_invalid" };
+  }
+  const name = typeof obj.name === "string" ? obj.name : void 0;
+  const status = typeof obj.status === "number" ? obj.status : void 0;
+  if (name === "ConfigError" || name === "AuthError" || name === "PermissionError" || status === 401 || status === 403) {
+    return { type: "permission", code: "credential_invalid" };
+  }
+  if (name === "NetworkError" || name === "TimeoutError" || status === 408 || status === 503) {
+    return { type: "network", code: "upstream_timeout" };
+  }
+  if (name === "GoneError" || status === 404) {
+    return {
+      type: "validation",
+      code: "not_found",
+      detail: typeof obj.message === "string" ? { message: obj.message } : void 0
+    };
+  }
+  if (name === "UsageLimitError" || status === 429) {
+    const out = { type: "degraded", code: "rate_limited" };
+    if (typeof obj.retryAfter === "number") out.retryAfter = obj.retryAfter;
+    return out;
+  }
+  if (name === "ValidationError" || status === 400 || status === 422) {
+    return {
+      type: "validation",
+      code: "invalid_argument",
+      detail: typeof obj.message === "string" ? { message: obj.message } : void 0
+    };
+  }
+  return null;
+}
+function classifyError(err) {
+  const classified = classifyAdminError(err);
+  if (!isUnknownAdminError(classified)) return classified;
+  return classifyCliExtensions(err) ?? classified;
+}
 function adminErrorExitCode(err) {
   if (err.code === "unknown") return 1;
   switch (err.type) {
@@ -1312,7 +1332,7 @@ async function exchangeCode(code) {
   }
 }
 function startAuthServer(options) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const server = createServer((req, res) => {
       if (!req.url) {
         res.writeHead(400).end();
@@ -1387,7 +1407,7 @@ Logged in successfully!`));
         );
         cleanup(4);
       }, TIMEOUT_MS);
-      resolve2({ port: addr.port, cleanup });
+      resolve3({ port: addr.port, cleanup });
     });
     server.on("error", (err) => {
       reject(err);
@@ -1831,6 +1851,22 @@ Prerequisites:
 import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
 
 // src/lib/agent-output.ts
+var PLAN_AGENT_ERROR_CODES = /* @__PURE__ */ new Set([
+  "PLAN_EXPIRED",
+  "PLAN_MISMATCH",
+  "PLAN_STALE",
+  "UNSUPPORTED_OPERATION"
+]);
+function agentPlanError(code, message) {
+  const error = new Error(message);
+  Object.assign(error, {
+    type: "validation",
+    code: code.toLowerCase(),
+    agentCode: code,
+    detail: { message, agentCode: code }
+  });
+  return error;
+}
 function stringifyAgentJson(data, options = {}) {
   return options.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
 }
@@ -1862,6 +1898,10 @@ function isRawNotFound(error) {
 function agentErrorExitCode(code) {
   switch (code) {
     case "INVALID_INPUT":
+    case "PLAN_EXPIRED":
+    case "PLAN_MISMATCH":
+    case "PLAN_STALE":
+    case "UNSUPPORTED_OPERATION":
       return 2;
     case "AUTH_FAILED":
       return 3;
@@ -1872,8 +1912,15 @@ function agentErrorExitCode(code) {
   }
 }
 function classifyAgentError(error) {
-  const adminError = classifyError(error);
+  const raw = asRecord(error);
   const message = errorMessage(error);
+  const detail = raw?.detail;
+  const detailRecord = detail && typeof detail === "object" ? detail : null;
+  const agentCode = raw?.agentCode ?? detailRecord?.agentCode;
+  if (typeof agentCode === "string" && PLAN_AGENT_ERROR_CODES.has(agentCode)) {
+    return { error: { code: agentCode, message } };
+  }
+  const adminError = classifyError(error);
   if (isRawNotFound(error) || adminError.code === "not_found") {
     return { error: { code: "NOT_FOUND", message } };
   }
@@ -1898,6 +1945,641 @@ function exitWithAgentError(error, options = {}) {
   process.exit(agentErrorExitCode(envelope.error.code));
 }
 
+// src/lib/agent-plan-allowlist.ts
+var AGENT_PLAN_COLLECTIONS = [
+  "articles",
+  "article-categories",
+  "article-tags",
+  "links",
+  "link-categories",
+  "link-tags"
+];
+var AGENT_PLAN_COLLECTION_SET = new Set(AGENT_PLAN_COLLECTIONS);
+function isAgentPlanCollection(collection) {
+  return AGENT_PLAN_COLLECTION_SET.has(collection);
+}
+function assertAgentPlanCollection(collection) {
+  if (isAgentPlanCollection(collection)) {
+    return collection;
+  }
+  throw agentPlanError(
+    "UNSUPPORTED_OPERATION",
+    `Collection "${collection}" is not supported for agent plan mutations.`
+  );
+}
+
+// src/lib/agent-plan-auth.ts
+import { createHash } from "crypto";
+function buildAuthContextFingerprint(input) {
+  const apiUrl = input.apiUrl ?? process.env.SOFTWARE_API_URL ?? process.env.NEXT_PUBLIC_SOFTWARE_API_URL ?? "";
+  const tenantId = input.tenantId ?? process.env.SOFTWARE_TENANT_ID ?? "";
+  const secretDigest = createHash("sha256").update(input.secretKey).digest("hex");
+  const material = [input.publishableKey, secretDigest, apiUrl, tenantId].join("\n");
+  return createHash("sha256").update(material).digest("hex");
+}
+
+// src/lib/agent-plan-store.ts
+import { mkdir, open, readFile, unlink, writeFile } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { randomUUID } from "crypto";
+
+// src/lib/agent-plan-hash.ts
+import { createHash as createHash2 } from "crypto";
+function sortKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  if (value && typeof value === "object") {
+    return Object.keys(value).sort().reduce((acc, key) => {
+      acc[key] = sortKeys(value[key]);
+      return acc;
+    }, {});
+  }
+  return value;
+}
+function hashPlanPayload(payload) {
+  const canonical = JSON.stringify(sortKeys(payload));
+  return createHash2("sha256").update(canonical).digest("hex");
+}
+function hashAgentPlanEnvelope(input) {
+  return hashPlanPayload({
+    operation: input.operation,
+    collection: input.collection,
+    documentId: input.documentId,
+    payload: input.payload
+  });
+}
+
+// src/lib/agent-plan-id.ts
+import { resolve as resolve2, sep } from "path";
+var PLAN_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function assertValidPlanId(planId) {
+  if (!PLAN_ID_PATTERN.test(planId)) {
+    throw agentPlanError("INVALID_INPUT", "Invalid plan token.");
+  }
+}
+function safePlanPath(planDir, planId) {
+  assertValidPlanId(planId);
+  const resolvedDir = resolve2(planDir);
+  const resolvedPath = resolve2(resolvedDir, `${planId}.json`);
+  if (resolvedPath !== resolvedDir && !resolvedPath.startsWith(`${resolvedDir}${sep}`)) {
+    throw agentPlanError("INVALID_INPUT", "Invalid plan token.");
+  }
+  return resolvedPath;
+}
+
+// src/lib/agent-plan-store.ts
+var AGENT_PLAN_TTL_MS = 15 * 60 * 1e3;
+function resolveAgentPlanDir() {
+  const override = process.env.SOFTWARE_AGENT_PLAN_DIR?.trim();
+  if (override) {
+    return override;
+  }
+  return join2(homedir2(), ".01software", "agent-plans");
+}
+function parseExpiresAtMs(expiresAt) {
+  const ms = Date.parse(expiresAt);
+  if (!Number.isFinite(ms)) {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan has invalid expiresAt.");
+  }
+  return ms;
+}
+function parseStoredAgentPlan(raw, planId) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan is corrupted.");
+  }
+  const record = raw;
+  if (record.planId !== planId) {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan id does not match token.");
+  }
+  if (typeof record.planHash !== "string" || typeof record.operation !== "string" || typeof record.collection !== "string" || typeof record.authFingerprint !== "string" || typeof record.createdAt !== "string" || typeof record.expiresAt !== "string" || typeof record.status !== "string") {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan is missing required fields.");
+  }
+  if (record.status !== "pending" && record.status !== "claimed" && record.status !== "consumed") {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan has invalid status.");
+  }
+  if (!isAgentPlanCollection(record.collection)) {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan has unsupported collection.");
+  }
+  const collection = record.collection;
+  const operation = record.operation;
+  if (operation !== "create" && operation !== "update" && operation !== "delete") {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan has invalid operation.");
+  }
+  const payload = record.payload == null ? void 0 : typeof record.payload === "object" && !Array.isArray(record.payload) ? record.payload : (() => {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan payload is invalid.");
+  })();
+  const documentId = record.documentId == null ? void 0 : typeof record.documentId === "string" ? record.documentId : (() => {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan documentId is invalid.");
+  })();
+  const baseUpdatedAt = record.baseUpdatedAt == null ? void 0 : typeof record.baseUpdatedAt === "string" ? record.baseUpdatedAt : (() => {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan baseUpdatedAt is invalid.");
+  })();
+  return {
+    planId,
+    planHash: record.planHash,
+    operation,
+    collection,
+    documentId,
+    payload,
+    baseUpdatedAt,
+    authFingerprint: record.authFingerprint,
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt,
+    status: record.status
+  };
+}
+function assertStoredPlanHashMatches(plan) {
+  const expected = hashAgentPlanEnvelope({
+    operation: plan.operation,
+    collection: plan.collection,
+    documentId: plan.documentId,
+    payload: plan.payload
+  });
+  if (plan.planHash !== expected) {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan hash does not match plan contents.");
+  }
+}
+function assertPlanNotExpired(plan) {
+  if (Date.now() > parseExpiresAtMs(plan.expiresAt)) {
+    throw agentPlanError("PLAN_EXPIRED", "Plan expired.");
+  }
+}
+async function readAgentPlanFile(planDir, planId) {
+  assertValidPlanId(planId);
+  let raw;
+  try {
+    raw = await readFile(safePlanPath(planDir, planId), "utf8");
+  } catch {
+    throw agentPlanError("PLAN_MISMATCH", "Plan not found.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw agentPlanError("PLAN_MISMATCH", "Stored plan is corrupted.");
+  }
+  return parseStoredAgentPlan(parsed, planId);
+}
+async function writeAgentPlanFile(planDir, plan) {
+  await writeFile(safePlanPath(planDir, plan.planId), JSON.stringify(plan), {
+    encoding: "utf8",
+    mode: 384
+  });
+}
+async function writeAgentPlan(input) {
+  await mkdir(input.planDir, { recursive: true, mode: 448 });
+  const planId = input.record.planId ?? randomUUID();
+  assertValidPlanId(planId);
+  const plan = {
+    ...input.record,
+    planId,
+    status: "pending"
+  };
+  assertStoredPlanHashMatches(plan);
+  await writeAgentPlanFile(input.planDir, plan);
+  return plan;
+}
+async function claimAgentPlan(input) {
+  assertValidPlanId(input.planId);
+  const planPath = safePlanPath(input.planDir, input.planId);
+  const lockPath = `${planPath}.lock`;
+  let lockHandle;
+  try {
+    lockHandle = await open(lockPath, "wx", 384);
+  } catch {
+    throw agentPlanError("PLAN_MISMATCH", "Plan was already claimed or consumed.");
+  }
+  try {
+    const plan = await readAgentPlanFile(input.planDir, input.planId);
+    assertPlanNotExpired(plan);
+    assertStoredPlanHashMatches(plan);
+    if (plan.planHash !== input.planHash) {
+      throw agentPlanError("PLAN_MISMATCH", "Plan hash does not match stored plan.");
+    }
+    if (plan.authFingerprint !== input.authFingerprint) {
+      throw agentPlanError(
+        "PLAN_MISMATCH",
+        "Plan auth context does not match current credentials."
+      );
+    }
+    if (plan.status !== "pending") {
+      throw agentPlanError("PLAN_MISMATCH", "Plan was already claimed or consumed.");
+    }
+    const claimed = { ...plan, status: "claimed" };
+    await writeAgentPlanFile(input.planDir, claimed);
+    return claimed;
+  } finally {
+    if (lockHandle) {
+      await lockHandle.close().catch(() => {
+      });
+    }
+    await unlink(lockPath).catch(() => {
+    });
+  }
+}
+async function releaseAgentPlanClaim(input) {
+  const plan = await readAgentPlanFile(input.planDir, input.planId);
+  if (plan.status !== "claimed") {
+    return;
+  }
+  await writeAgentPlanFile(input.planDir, { ...plan, status: "pending" });
+}
+async function markAgentPlanConsumed(input) {
+  const plan = await readAgentPlanFile(input.planDir, input.planId);
+  await writeAgentPlanFile(input.planDir, { ...plan, status: "consumed" });
+}
+
+// src/lib/agent-plan-stale.ts
+function readDocumentUpdatedAt(doc) {
+  if (!doc || typeof doc !== "object") {
+    return void 0;
+  }
+  const updatedAt = doc.updatedAt;
+  return typeof updatedAt === "string" && updatedAt.length > 0 ? updatedAt : void 0;
+}
+function assertPlanBaseUpdatedAt(operation, baseUpdatedAt) {
+  if (operation === "create") {
+    return;
+  }
+  if (!baseUpdatedAt) {
+    throw agentPlanError(
+      "INVALID_INPUT",
+      "Document is missing updatedAt; cannot plan update or delete."
+    );
+  }
+}
+async function assertPlanNotStale(input) {
+  if (input.operation === "create") {
+    return;
+  }
+  if (!input.baseUpdatedAt || !input.currentUpdatedAt) {
+    throw agentPlanError(
+      "PLAN_STALE",
+      "Document is missing updatedAt for stale check."
+    );
+  }
+  if (input.baseUpdatedAt !== input.currentUpdatedAt) {
+    throw agentPlanError(
+      "PLAN_STALE",
+      "Document changed since the plan was created."
+    );
+  }
+}
+
+// src/lib/agent-plan-confirm.ts
+async function executeAgentPlanMutation(client, plan) {
+  const collection = client.collections.from(plan.collection);
+  if (plan.operation === "create") {
+    const response = await collection.create(plan.payload ?? {});
+    return response.doc;
+  }
+  if (!plan.documentId) {
+    throw agentPlanError("PLAN_MISMATCH", "Plan is missing document id.");
+  }
+  if (plan.operation === "update") {
+    const current2 = await collection.findById(plan.documentId);
+    await assertPlanNotStale({
+      operation: plan.operation,
+      baseUpdatedAt: plan.baseUpdatedAt,
+      currentUpdatedAt: readDocumentUpdatedAt(current2)
+    });
+    const response = await collection.update(plan.documentId, plan.payload ?? {});
+    return response.doc;
+  }
+  const current = await collection.findById(plan.documentId);
+  await assertPlanNotStale({
+    operation: plan.operation,
+    baseUpdatedAt: plan.baseUpdatedAt,
+    currentUpdatedAt: readDocumentUpdatedAt(current)
+  });
+  return collection.remove(plan.documentId);
+}
+async function finalizeAgentPlan(plan) {
+  await markAgentPlanConsumed({
+    planDir: resolveAgentPlanDir(),
+    planId: plan.planId
+  });
+}
+
+// src/lib/agent-plan-payload.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { stdin } from "process";
+async function readStdinUtf8() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readAgentPlanPayload(opts) {
+  const sourceCount = [opts.dataStdin, opts.dataFile].filter(Boolean).length;
+  if (sourceCount !== 1) {
+    throw agentPlanError(
+      "INVALID_INPUT",
+      "Exactly one of --data-stdin or --data-file is required."
+    );
+  }
+  let raw;
+  try {
+    raw = opts.dataStdin ? await readStdinUtf8() : readFileSync3(opts.dataFile, "utf8");
+  } catch {
+    throw agentPlanError(
+      "INVALID_INPUT",
+      "Mutation data file could not be read."
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw agentPlanError("INVALID_INPUT", "Mutation data must be valid JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw agentPlanError("INVALID_INPUT", "Mutation data must be a JSON object.");
+  }
+  return parsed;
+}
+
+// src/lib/agent-plan-secrets.ts
+var SECRET_KEY = /(?:^|_)(?:secret|password|token|api[_-]?key|private[_-]?key|credential)(?:$|_)/i;
+function isSecretFieldName(key) {
+  if (SECRET_KEY.test(key)) {
+    return true;
+  }
+  const snake = key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+  return SECRET_KEY.test(snake);
+}
+function assertNoSecretFields(value, path = "") {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      assertNoSecretFields(item, `${path}[${index}]`);
+    });
+    return;
+  }
+  if (!value || typeof value !== "object") {
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const fieldPath = path ? `${path}.${key}` : key;
+    if (isSecretFieldName(key)) {
+      throw agentPlanError(
+        "INVALID_INPUT",
+        `Secret-looking field "${fieldPath}" is not allowed in agent mutation payloads.`
+      );
+    }
+    assertNoSecretFields(child, fieldPath);
+  }
+}
+
+// src/lib/agent-plan-token.ts
+function encodePlanToken(token) {
+  return Buffer.from(JSON.stringify(token), "utf8").toString("base64url");
+}
+function decodePlanToken(raw) {
+  try {
+    const parsed = JSON.parse(
+      Buffer.from(raw, "base64url").toString("utf8")
+    );
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("invalid token");
+    }
+    const record = parsed;
+    if (typeof record.planId !== "string" || typeof record.planHash !== "string" || typeof record.expiresAt !== "string") {
+      throw new Error("invalid token fields");
+    }
+    assertValidPlanId(record.planId);
+    return {
+      planId: record.planId,
+      planHash: record.planHash,
+      expiresAt: record.expiresAt
+    };
+  } catch {
+    throw agentPlanError("INVALID_INPUT", "Invalid plan token.");
+  }
+}
+function buildConfirmCommand(planToken, planHash) {
+  return `01 agent confirm ${planToken} --hash ${planHash}`;
+}
+
+// src/commands/agent-plan.ts
+function invalidInput(message, field) {
+  const error = new Error(message);
+  Object.assign(error, {
+    type: "validation",
+    code: "invalid_argument",
+    field,
+    detail: { message, field }
+  });
+  return error;
+}
+function handleCommanderError(error) {
+  if (error.code === "commander.helpDisplayed") {
+    process.exit(error.exitCode);
+  }
+  exitWithAgentError(invalidInput(error.message, "command"));
+}
+function configureAgentParser(command) {
+  command.configureOutput({
+    writeErr: () => {
+    },
+    writeOut: (str) => {
+      process.stdout.write(str);
+    }
+  });
+  command.exitOverride(handleCommanderError);
+  return command;
+}
+async function captureBaseUpdatedAt(client, collection, documentId) {
+  const doc = await client.collections.from(collection).findById(documentId);
+  return readDocumentUpdatedAt(doc);
+}
+async function runPlanAction(input) {
+  const collection = assertAgentPlanCollection(input.collection);
+  if (input.operation !== "create" && !input.documentId) {
+    throw invalidInput("Missing required argument: id", "id");
+  }
+  let payload;
+  if (input.operation === "create" || input.operation === "update") {
+    payload = await readAgentPlanPayload({
+      dataStdin: input.dataStdin,
+      dataFile: input.dataFile
+    });
+    assertNoSecretFields(payload);
+  }
+  const client = input.getClient();
+  const authFingerprint = buildAuthContextFingerprint({
+    publishableKey: client.publishableKey,
+    secretKey: client.secretKey
+  });
+  let baseUpdatedAt;
+  if (input.operation !== "create" && input.documentId) {
+    baseUpdatedAt = await captureBaseUpdatedAt(
+      client,
+      collection,
+      input.documentId
+    );
+    assertPlanBaseUpdatedAt(input.operation, baseUpdatedAt);
+  }
+  const planHash = hashAgentPlanEnvelope({
+    operation: input.operation,
+    collection,
+    documentId: input.documentId,
+    payload
+  });
+  const createdAt = /* @__PURE__ */ new Date();
+  const expiresAt = new Date(createdAt.getTime() + AGENT_PLAN_TTL_MS);
+  const stored = await writeAgentPlan({
+    planDir: resolveAgentPlanDir(),
+    record: {
+      planHash,
+      operation: input.operation,
+      collection,
+      documentId: input.documentId,
+      payload,
+      baseUpdatedAt,
+      authFingerprint,
+      createdAt: createdAt.toISOString(),
+      expiresAt: expiresAt.toISOString()
+    }
+  });
+  const planToken = encodePlanToken({
+    planId: stored.planId,
+    planHash: stored.planHash,
+    expiresAt: stored.expiresAt
+  });
+  printAgentSuccess(
+    {
+      planToken,
+      planHash: stored.planHash,
+      planId: stored.planId,
+      expiresAt: stored.expiresAt,
+      operation: stored.operation,
+      collection: stored.collection,
+      documentId: stored.documentId,
+      confirmCommand: buildConfirmCommand(planToken, stored.planHash)
+    },
+    { pretty: Boolean(input.pretty) }
+  );
+}
+function registerAgentPlanCommands(agent, getClient2) {
+  const plan = configureAgentParser(
+    agent.command("plan").description("Plan a mutation without executing")
+  );
+  configureAgentParser(
+    plan.command("create <collection>").description("Plan a document create").option("--data-stdin", "Read mutation JSON from stdin").option("--data-file <path>", "Read mutation JSON from file").option("--pretty", "Print 2-space indented JSON").action(
+      async (collection, opts) => {
+        try {
+          await runPlanAction({
+            operation: "create",
+            collection,
+            dataStdin: opts.dataStdin,
+            dataFile: opts.dataFile,
+            pretty: opts.pretty,
+            getClient: getClient2
+          });
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+  configureAgentParser(
+    plan.command("update <collection> <id>").description("Plan a document update").option("--data-stdin", "Read mutation JSON from stdin").option("--data-file <path>", "Read mutation JSON from file").option("--pretty", "Print 2-space indented JSON").action(
+      async (collection, id, opts) => {
+        try {
+          await runPlanAction({
+            operation: "update",
+            collection,
+            documentId: id,
+            dataStdin: opts.dataStdin,
+            dataFile: opts.dataFile,
+            pretty: opts.pretty,
+            getClient: getClient2
+          });
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+  configureAgentParser(
+    plan.command("delete <collection> <id>").description("Plan a document delete").option("--pretty", "Print 2-space indented JSON").action(
+      async (collection, id, opts) => {
+        try {
+          await runPlanAction({
+            operation: "delete",
+            collection,
+            documentId: id,
+            pretty: opts.pretty,
+            getClient: getClient2
+          });
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+  configureAgentParser(
+    agent.command("confirm <planToken>").description("Execute a previously planned mutation").requiredOption("--hash <planHash>", "Plan hash from plan output").option("--pretty", "Print 2-space indented JSON").action(
+      async (planTokenRaw, opts) => {
+        try {
+          const token = decodePlanToken(planTokenRaw);
+          if (token.planHash !== opts.hash) {
+            throw agentPlanError(
+              "PLAN_MISMATCH",
+              "Plan token does not match --hash."
+            );
+          }
+          const client = getClient2();
+          const authFingerprint = buildAuthContextFingerprint({
+            publishableKey: client.publishableKey,
+            secretKey: client.secretKey
+          });
+          const planDir = resolveAgentPlanDir();
+          const plan2 = await claimAgentPlan({
+            planDir,
+            planId: token.planId,
+            planHash: opts.hash,
+            authFingerprint
+          });
+          if (token.planId !== plan2.planId) {
+            throw agentPlanError(
+              "PLAN_MISMATCH",
+              "Plan token does not match stored plan."
+            );
+          }
+          let doc;
+          try {
+            doc = await executeAgentPlanMutation(client, plan2);
+          } catch (mutationError) {
+            await releaseAgentPlanClaim({
+              planDir,
+              planId: plan2.planId
+            }).catch(() => {
+            });
+            throw mutationError;
+          }
+          await finalizeAgentPlan(plan2);
+          printAgentSuccess(
+            {
+              applied: true,
+              operation: plan2.operation,
+              collection: plan2.collection,
+              id: doc && typeof doc === "object" && "id" in doc ? String(doc.id) : plan2.documentId,
+              doc
+            },
+            { pretty: Boolean(opts.pretty) }
+          );
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+}
+
 // src/commands/agent.ts
 var AGENT_PROTOCOL_VERSION = "1";
 function buildStableAgentFields() {
@@ -1907,7 +2589,7 @@ function buildStableAgentFields() {
     updatedAt: { type: "string", queryable: true }
   };
 }
-function invalidInput(message, field, value) {
+function invalidInput2(message, field, value) {
   const error = new Error(message);
   Object.assign(error, {
     type: "validation",
@@ -1920,15 +2602,15 @@ function invalidInput(message, field, value) {
 function parsePositiveInteger(value, field) {
   if (value == null) return void 0;
   if (/^[1-9]\d*$/.test(value)) return Number(value);
-  throw invalidInput(`--${field} must be a positive integer`, field, value);
+  throw invalidInput2(`--${field} must be a positive integer`, field, value);
 }
-function handleCommanderError(error) {
+function handleCommanderError2(error) {
   if (error.code === "commander.helpDisplayed") {
     process.exit(error.exitCode);
   }
-  exitWithAgentError(invalidInput(error.message, "command"));
+  exitWithAgentError(invalidInput2(error.message, "command"));
 }
-function configureAgentParser(command) {
+function configureAgentParser2(command) {
   command.configureOutput({
     writeErr: () => {
     },
@@ -1936,7 +2618,7 @@ function configureAgentParser(command) {
       process.stdout.write(str);
     }
   });
-  command.exitOverride(handleCommanderError);
+  command.exitOverride(handleCommanderError2);
   return command;
 }
 function parseWhere(value) {
@@ -1947,15 +2629,22 @@ function parseWhere(value) {
       return parsed;
     }
   } catch {
-    throw invalidInput("--where must be a JSON object", "where", value);
+    throw invalidInput2("--where must be a JSON object", "where", value);
   }
-  throw invalidInput("--where must be a JSON object", "where", value);
+  throw invalidInput2("--where must be a JSON object", "where", value);
 }
+var AGENT_READ_OPERATIONS = ["query", "get"];
+var AGENT_PLAN_OPERATIONS = [
+  "plan:create",
+  "plan:update",
+  "plan:delete"
+];
 function buildAgentManifest() {
   const collections = {};
   for (const collection of COLLECTIONS3) {
+    const operations = isAgentPlanCollection(collection) ? [...AGENT_READ_OPERATIONS, ...AGENT_PLAN_OPERATIONS] : [...AGENT_READ_OPERATIONS];
     collections[collection] = {
-      operations: ["query", "get"],
+      operations,
       fields: buildStableAgentFields()
     };
   }
@@ -1969,22 +2658,22 @@ function validateAgentCollection(collection) {
     return validateCollection(collection);
   } catch (error) {
     const message = error instanceof Error ? error.message : `Unknown collection "${collection}".`;
-    throw invalidInput(message, "collection", collection);
+    throw invalidInput2(message, "collection", collection);
   }
 }
 function registerAgentCommands(program2, getClient2) {
-  const agent = configureAgentParser(
+  const agent = configureAgentParser2(
     program2.command("agent").description("Machine-stable CLI namespace for coding agents").addHelpText(
       "after",
       "\nContract: docs/agent-cli-contract.md\nJSON only on stdout; no TTY effects."
     )
   );
-  configureAgentParser(
+  configureAgentParser2(
     agent.command("manifest").description("Print the Agent CLI protocol manifest").option("--pretty", "Print 2-space indented JSON").action((opts) => {
       printAgentSuccess(buildAgentManifest(), { pretty: Boolean(opts.pretty) });
     })
   );
-  configureAgentParser(
+  configureAgentParser2(
     agent.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions as a JSON object").option("--limit <n>", "Max results").option("--page <n>", "Page number").option("--sort <field>", "Sort field; prefix with - for descending").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
       async (collection, opts) => {
         try {
@@ -2007,13 +2696,13 @@ function registerAgentCommands(program2, getClient2) {
       }
     )
   );
-  configureAgentParser(
+  configureAgentParser2(
     agent.command("get <collection> [id]").description("Get a document by ID").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
       async (collection, id, opts) => {
         try {
           const col = validateAgentCollection(collection);
           if (!id) {
-            throw invalidInput("Missing required argument: id", "id");
+            throw invalidInput2("Missing required argument: id", "id");
           }
           const options = {};
           if (opts.select) options.select = parseSelect(opts.select);
@@ -2026,6 +2715,7 @@ function registerAgentCommands(program2, getClient2) {
       }
     )
   );
+  registerAgentPlanCommands(agent, getClient2);
 }
 
 // src/index.ts