@cerefox/memory 1.9.1 → 1.10.0

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.9.1";
+var PKG_VERSION = "1.10.0";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -23530,9 +23530,9 @@ function isAuditCheckError(message) {
 function isDuplicateKeyError(message) {
   return /duplicate key|unique constraint|23505/i.test(message);
 }
-function storeWriteRemediation(message, fnName) {
+function storeWriteRemediation(message, fnName, requiredSchema = "0.14.0") {
   if (isMissingFunctionError(message, fnName)) {
-    return "The deployed server predates schema 0.14.0 — or PostgREST's schema cache " + "is stale right after a deploy. If you just deployed, retry in a few " + "seconds; otherwise run `cerefox server deploy`.";
+    return `The deployed server predates schema ${requiredSchema} — or PostgREST's schema cache ` + "is stale right after a deploy. If you just deployed, retry in a few " + "seconds; otherwise run `cerefox server deploy`.";
   }
   if (isAuditCheckError(message)) {
     return "The server's audit-log constraint predates migration 0028 (partial " + "deploy). Run `cerefox server deploy` to apply pending migrations, then retry.";
@@ -25598,6 +25598,221 @@ var init_src = __esm(() => {
   src_default = Postgres;
 });
 
+// ../../_shared/mcp-tools/_document-meta.ts
+function stableStringify(value) {
+  if (Array.isArray(value))
+    return `[${value.map(stableStringify).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function normalizeMetadata(value) {
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (v !== null)
+      out[k] = v;
+  }
+  return out;
+}
+async function changeDocumentTitle(supabase, documentId, newTitle, who) {
+  const trimmed = (newTitle ?? "").trim();
+  if (!trimmed)
+    throw new FacetValidationError("Title cannot be empty.");
+  const { data, error } = await supabase.rpc("cerefox_rename_document", {
+    p_document_id: documentId,
+    p_new_title: trimmed,
+    p_author: who.author,
+    p_author_type: who.authorType
+  });
+  if (error) {
+    const msg = error.message ?? String(error);
+    if (/not found/i.test(msg))
+      throw new FacetNotFoundError(msg);
+    if (/cannot be empty/i.test(msg))
+      throw new FacetValidationError(msg);
+    const remediation = storeWriteRemediation(msg, "cerefox_rename_document", "0.15.0");
+    if (remediation)
+      throw new Error(`Title update failed: ${remediation}`);
+    throw new Error(`Title update failed: ${msg}`);
+  }
+  const row = data?.[0];
+  return { changed: row?.renamed ?? false, title: row?.new_title ?? trimmed };
+}
+async function applyMembershipReplace(supabase, opts) {
+  const { data: current, error: curErr } = await supabase.from("cerefox_document_projects").select("project_id").eq("document_id", opts.documentId);
+  if (curErr)
+    throw new Error(`Membership read failed: ${curErr.message}`);
+  const currentSet = new Set((current ?? []).map((r) => r.project_id));
+  if (opts.projectIds.length === currentSet.size && opts.projectIds.every((id) => currentSet.has(id))) {
+    return { changed: false };
+  }
+  const { error: delErr } = await supabase.from("cerefox_document_projects").delete().eq("document_id", opts.documentId);
+  if (delErr)
+    throw new Error(`Membership replace failed: ${delErr.message}`);
+  if (opts.projectIds.length > 0) {
+    const rows = opts.projectIds.map((pid) => ({
+      document_id: opts.documentId,
+      project_id: pid
+    }));
+    const { error: insErr } = await supabase.from("cerefox_document_projects").insert(rows);
+    if (insErr)
+      throw new Error(`Membership replace failed: ${insErr.message}`);
+  }
+  const { error: auditErr } = await supabase.rpc("cerefox_create_audit_entry", {
+    p_document_id: opts.documentId,
+    p_version_id: null,
+    p_operation: "update-metadata",
+    p_author: opts.author,
+    p_author_type: opts.authorType,
+    p_size_before: null,
+    p_size_after: null,
+    p_description: opts.projectNames.length > 0 ? `Set document projects to [${opts.projectNames.join(", ")}]` : "Cleared all project memberships"
+  });
+  if (auditErr)
+    console.warn("applyMembershipReplace: audit entry failed", auditErr.message);
+  logUsage(supabase, {
+    operation: "set-document-projects",
+    accessPath: opts.accessPath,
+    requestor: opts.author,
+    document_id: opts.documentId,
+    result_count: opts.projectIds.length
+  });
+  return { changed: true };
+}
+async function assertDocumentLive(supabase, documentId) {
+  const { data, error } = await supabase.from("cerefox_documents").select("id").eq("id", documentId).is("deleted_at", null).limit(1);
+  if (error)
+    throw new Error(`Document read failed: ${error.message}`);
+  if (!data?.length) {
+    throw new FacetNotFoundError(`Document not found (or in the trash): ${documentId}`);
+  }
+}
+async function setDocumentProjectsByIds(supabase, opts) {
+  const wanted = [...new Set(opts.projectIds)];
+  const { data: current, error: curErr } = await supabase.from("cerefox_document_projects").select("project_id").eq("document_id", opts.documentId);
+  if (curErr)
+    throw new Error(`Membership read failed: ${curErr.message}`);
+  const currentSet = new Set((current ?? []).map((r2) => r2.project_id));
+  if (wanted.length === currentSet.size && wanted.every((id) => currentSet.has(id))) {
+    return { changed: false, names: [] };
+  }
+  await assertDocumentLive(supabase, opts.documentId);
+  let names = [];
+  if (wanted.length > 0) {
+    const { data: found, error: valErr } = await supabase.from("cerefox_projects").select("id, name").in("id", wanted);
+    if (valErr)
+      throw new Error(`Project validation failed: ${valErr.message}`);
+    const byId = new Map((found ?? []).map((r2) => [r2.id, r2.name]));
+    const missing = wanted.filter((id) => !byId.has(id));
+    if (missing.length > 0) {
+      throw new FacetValidationError(`Unknown project id(s): ${missing.join(", ")} — memberships left unchanged.`);
+    }
+    names = wanted.map((id) => byId.get(id));
+  }
+  const r = await applyMembershipReplace(supabase, {
+    documentId: opts.documentId,
+    projectIds: wanted,
+    projectNames: names,
+    accessPath: opts.accessPath,
+    author: opts.author,
+    authorType: opts.authorType
+  });
+  return { changed: r.changed, names };
+}
+async function updateDocumentFacets(supabase, opts) {
+  const result = {
+    titleChanged: false,
+    metadataChanged: false,
+    projectsChanged: false
+  };
+  const who = { author: opts.author, authorType: opts.authorType };
+  const step = async (fn) => {
+    try {
+      return await fn();
+    } catch (err) {
+      throw err instanceof FacetUpdateError ? err : new FacetUpdateError(result, err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  if (opts.metadata !== undefined) {
+    await step(async () => {
+      const { data: doc, error } = await supabase.from("cerefox_documents").select("metadata").eq("id", opts.documentId).is("deleted_at", null).limit(1);
+      if (error)
+        throw new Error(`Metadata read failed: ${error.message}`);
+      if (!doc?.length) {
+        throw new FacetNotFoundError(`Document not found (or in the trash): ${opts.documentId}`);
+      }
+      const stored = doc[0].metadata ?? {};
+      const wanted = normalizeMetadata(opts.metadata);
+      if (stableStringify(stored) !== stableStringify(wanted)) {
+        const { error: rpcErr } = await supabase.rpc("cerefox_set_document_metadata", {
+          p_document_id: opts.documentId,
+          p_metadata: wanted,
+          p_replace: true,
+          p_author: opts.author,
+          p_author_type: opts.authorType
+        });
+        if (rpcErr) {
+          const msg = rpcErr.message ?? String(rpcErr);
+          if (/not found/i.test(msg))
+            throw new FacetNotFoundError(msg);
+          throw new Error(`Metadata update failed: ${msg}`);
+        }
+        result.metadataChanged = true;
+      }
+    });
+  }
+  if (opts.projectIds !== undefined) {
+    await step(async () => {
+      const r = await setDocumentProjectsByIds(supabase, {
+        documentId: opts.documentId,
+        projectIds: opts.projectIds,
+        accessPath: opts.accessPath,
+        ...who
+      });
+      result.projectsChanged = r.changed;
+    });
+  }
+  if (opts.title !== undefined) {
+    await step(async () => {
+      const r = await changeDocumentTitle(supabase, opts.documentId, opts.title, who);
+      result.titleChanged = r.changed;
+    });
+  }
+  return result;
+}
+var FacetNotFoundError, FacetValidationError, FacetUpdateError;
+var init__document_meta = __esm(() => {
+  init__utils();
+  FacetNotFoundError = class FacetNotFoundError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "FacetNotFoundError";
+    }
+  };
+  FacetValidationError = class FacetValidationError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "FacetValidationError";
+    }
+  };
+  FacetUpdateError = class FacetUpdateError extends Error {
+    applied;
+    constructor(applied, cause) {
+      const done = [
+        applied.metadataChanged ? "metadata" : null,
+        applied.projectsChanged ? "projects" : null,
+        applied.titleChanged ? "title" : null
+      ].filter(Boolean);
+      super(done.length > 0 ? `${cause.message} (already applied before the failure: ${done.join(", ")})` : cause.message);
+      this.name = "FacetUpdateError";
+      this.applied = applied;
+      this.cause = cause;
+    }
+  };
+});
+
 // ../../_shared/mcp-tools/_projects.ts
 async function resolveOrCreateProject(supabase, projectName, audit) {
   const { data, error } = await supabase.rpc("cerefox_create_project", {
@@ -25670,31 +25885,13 @@ async function replaceDocumentProjects(supabase, opts) {
     throw new Error(`Could not resolve project(s): ${failed.join(", ")} — memberships left unchanged.`);
   }
   const projectIds = resolved.map((r) => r.projectId);
-  await supabase.from("cerefox_document_projects").delete().eq("document_id", documentId);
-  if (projectIds.length > 0) {
-    const rows = projectIds.map((pid) => ({ document_id: documentId, project_id: pid }));
-    await supabase.from("cerefox_document_projects").insert(rows);
-  }
-  try {
-    await supabase.rpc("cerefox_create_audit_entry", {
-      p_document_id: documentId,
-      p_version_id: null,
-      p_operation: "update-metadata",
-      p_author: author,
-      p_author_type: authorType,
-      p_size_before: null,
-      p_size_after: null,
-      p_description: cleanNames.length > 0 ? `Set document projects to [${cleanNames.join(", ")}]` : "Cleared all project memberships"
-    });
-  } catch (err) {
-    console.warn("replaceDocumentProjects: audit entry failed", err);
-  }
-  logUsage(supabase, {
-    operation: "set-document-projects",
+  await applyMembershipReplace(supabase, {
+    documentId,
+    projectIds,
+    projectNames: cleanNames,
     accessPath,
-    requestor: author,
-    document_id: documentId,
-    result_count: projectIds.length
+    author,
+    authorType
   });
   return { documentTitle: doc[0].title, cleanNames, projectIds };
 }
@@ -25705,6 +25902,7 @@ async function lookupProjectId(supabase, projectName) {
   return data[0].id;
 }
 var init__projects = __esm(() => {
+  init__document_meta();
   init__utils();
 });
 
@@ -25802,7 +26000,7 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.9.1", CEREFOX_VERSION = "1.9.1", EF_LAST_CHANGED = "1.9.0";
+var EF_VERSION = "1.10.0", CEREFOX_VERSION = "1.10.0", EF_LAST_CHANGED = "1.10.0";
 var init_ef_meta = () => {};
 
 // ../../_shared/compatibility/index.ts
@@ -73413,6 +73611,7 @@ Proceed with deployment to Supabase?`, true);
   println(c.green(`
 ✓ Server deploy complete.`));
   println(c.dim("Verify with: cerefox doctor"));
+  println(c.dim("Refresh the bundled guides: cerefox guides ingest"));
 }
 function registerDeployServer(program2) {
   program2.command("deploy-server").description("Deploy/update the Cerefox server side (schema + RPCs + Edge Functions) on Supabase.").option("--dry-run", "Print the plan + pre-flight without deploying.").option("--schema-only", "Deploy/update only the schema + RPCs (skip Edge Functions).").option("--functions-only", "Deploy only the Edge Functions (skip the schema/RPCs).").option("--project-ref <ref>", "Supabase project ref for Edge Function deploys (default: derived from CEREFOX_SUPABASE_URL).").option("--yes", "Non-interactive (skip the deployment confirmation).").action(action10);
@@ -73420,6 +73619,7 @@ function registerDeployServer(program2) {
 
 // src/cli/commands/document-edit.ts
 init_cli_core();
+init__document_meta();
 init_client();
 function parseMetaPair(pair) {
   const eq = pair.indexOf("=");
@@ -73483,27 +73683,17 @@ async function action11(documentId, options) {
       throw systemError(`Metadata update failed: ${metaErr.message}`);
     }
   }
-  if (hasTitle) {
-    const { error: updErr } = await client.raw.from("cerefox_documents").update({ title: newTitle, updated_at: new Date().toISOString() }).eq("id", documentId);
-    if (updErr)
-      throw systemError(`Update failed: ${updErr.message}`);
-  }
-  if (titleChanged) {
-    const { error: ftsErr } = await client.raw.rpc("cerefox_update_chunk_fts", {
-      p_document_id: documentId,
-      p_new_title: newTitle
-    });
-    if (ftsErr)
-      throw systemError(`Title updated but FTS refresh failed: ${ftsErr.message}`);
-  }
-  if (titleChanged) {
-    await client.raw.rpc("cerefox_create_audit_entry", {
-      p_document_id: documentId,
-      p_operation: "update-metadata",
-      p_author: author,
-      p_author_type: authorType,
-      p_description: "Edited title"
-    });
+  if (hasTitle && titleChanged) {
+    try {
+      await changeDocumentTitle(client.raw, documentId, newTitle, { author, authorType });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (err instanceof FacetNotFoundError)
+        throw notFound(msg);
+      if (err instanceof FacetValidationError)
+        throw userError(msg);
+      throw systemError(msg);
+    }
   }
   println(c.green(`✓ Edited "${newTitle}" (id: ${documentId}).`));
   if (titleChanged) {
@@ -80660,14 +80850,10 @@ async function action33(options) {
   println("");
   println(c.green(`✓ Upgraded to ${target}.`));
   println("");
-  println(c.dim("Refreshing bundled-docs ingest (using the new version)…"));
-  const sync = spawnSync5(process.execPath, [process.argv[1], "guides", "ingest"], {
-    stdio: "inherit"
-  });
-  if (sync.status !== 0) {
-    println(cErr.yellow("⚠ ") + "Could not refresh self-docs (see output above).");
-    println(c.dim("  Run `cerefox guides ingest` manually after a successful `cerefox init`."));
-  }
+  println("Next steps:");
+  println("  1. " + c.bold("cerefox server deploy") + "   apply this release's schema/RPC/EF updates");
+  println("  2. " + c.bold("cerefox guides ingest") + "   re-sync the bundled guides into your KB");
+  println(c.dim("  (order matters: the new client may require the new schema — run the deploy first)"));
 }
 function registerSelfUpdate(program2) {
   const desc = "Upgrade Cerefox in place. Alias: `cerefox upgrade`.";
@@ -85301,6 +85487,7 @@ function registerDocumentReadRoutes(app, ctx) {
   });
 }
 // src/web/routes/documents-write.ts
+init__document_meta();
 init__utils();
 async function createAuditEntry(ctx, args) {
   try {
@@ -85316,16 +85503,6 @@ async function createAuditEntry(ctx, args) {
     });
   } catch {}
 }
-async function assignDocumentProjects(ctx, documentId, projectIds) {
-  await ctx.supabase.from("cerefox_document_projects").delete().eq("document_id", documentId);
-  if (projectIds.length > 0) {
-    const rows = projectIds.map((pid) => ({
-      document_id: documentId,
-      project_id: pid
-    }));
-    await ctx.supabase.from("cerefox_document_projects").insert(rows);
-  }
-}
 async function getCurrentDoc(ctx, documentId) {
   const { data } = await ctx.supabase.from("cerefox_documents").select("*").eq("id", documentId).maybeSingle();
   return data ?? null;
@@ -85378,7 +85555,7 @@ function registerDocumentWriteRoutes(app, ctx) {
           title: title || doc2.title,
           source: "manual",
           projectIds: Array.isArray(body.project_ids) ? body.project_ids : undefined,
-          metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+          metadata: body.metadata != null ? metadata : undefined,
           author: "web-ui",
           authorType: "user",
           expectedContentHash: typeof body.expected_content_hash === "string" ? body.expected_content_hash : null
@@ -85419,33 +85596,28 @@ function registerDocumentWriteRoutes(app, ctx) {
         return c2.json({ success: false, error: msg }, 500);
       }
     }
-    const updates = {};
-    if (title && title !== doc2.title) {
-      updates.title = title;
-    }
-    if (Object.keys(metadata).length > 0) {
-      updates.metadata = metadata;
-    }
-    if (Object.keys(updates).length > 0) {
-      updates.updated_at = new Date().toISOString();
-      const { error: error3 } = await ctx.supabase.from("cerefox_documents").update(updates).eq("id", documentId);
-      if (error3)
-        return c2.json({ success: false, error: error3.message }, 500);
-    }
-    const projectsTouched = Array.isArray(body.project_ids);
-    if (projectsTouched) {
-      await assignDocumentProjects(ctx, documentId, projectIds);
-    }
-    const anythingChanged = "title" in updates || "metadata" in updates || projectsTouched;
-    if (anythingChanged) {
-      await createAuditEntry(ctx, {
-        operation: "update-metadata",
-        author: "web-ui",
+    try {
+      const facets = await updateDocumentFacets(ctx.supabase, {
         documentId,
-        description: `Updated via web UI (title=${"title" in updates}, metadata=${"metadata" in updates}, projects=${projectsTouched})`
+        title: body.title !== undefined && title !== doc2.title ? title : undefined,
+        metadata: body.metadata != null ? metadata : undefined,
+        projectIds: Array.isArray(body.project_ids) ? projectIds : undefined,
+        author: "web-ui",
+        authorType: "user",
+        accessPath: "webapp"
       });
+      return c2.json({ success: true, reindexed: false, ...facets });
+    } catch (err) {
+      const cause = err instanceof FacetUpdateError ? err.cause : err;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (cause instanceof FacetNotFoundError) {
+        return c2.json({ success: false, error: msg, detail: msg }, 404);
+      }
+      if (cause instanceof FacetValidationError) {
+        return c2.json({ success: false, error: msg, detail: msg }, 400);
+      }
+      return c2.json({ success: false, error: msg, detail: msg }, 500);
     }
-    return c2.json({ success: true, reindexed: false });
   });
   app.delete("/api/v1/documents/:document_id", async (c2) => {
     const documentId = c2.req.param("document_id");