@bli-cockpit/cli 0.2.135 → 0.2.137

package/dist/commands/docs-notion.js

@@ -0,0 +1,90 @@
+/**
+ * `cockpit docs link` and `cockpit docs sync-status` — the Notion half of the
+ * document library (BLI-10430). A sibling of `docs.ts` rather than more of it:
+ * that file is the five library verbs, and this one is the two-way sync's.
+ *
+ * `link <id|slug> <notion-url|page-id>` → `PUT /api/docs/documents/[id]/notion-link`
+ * `link <id|slug> --clear`             → `DELETE` on the same door
+ * `sync-status [<id|slug>]`            → `GET /api/docs/notion-sync`
+ *
+ * The door folds any Notion URL or id to the page id the importer stores, and
+ * refuses by name: `invalid_notion_page`, `notion_page_already_linked`,
+ * `document_not_writable`. A link means the page is the truth: the next sync
+ * pulls it over the Tower copy and keeps the copy as a version
+ * (`docs/architecture/docs.md`, "Two-way sync with Notion").
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+/**
+ * `sync-status [<id|slug>]` → `GET /api/docs/notion-sync[?document_id=]`. Tower's
+ * half of the answer only (synced / tower_changed / never_synced); the door
+ * never claims anything about Notion it has not read.
+ */
+export async function syncStatusDocs(command, door) {
+    let path = "/api/docs/notion-sync";
+    if (command.docRef) {
+        const resolved = await resolveDocId(door, command.docRef);
+        if (resolved.status === "list_failed")
+            return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+        if (resolved.status === "not_found") {
+            return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${command.docRef}`);
+        }
+        path = `${path}?document_id=${encodeURIComponent(resolved.id)}`;
+    }
+    const answer = await askAgentDoor(door, { path, method: "GET", label: "docs sync-status", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, counts: body.counts, documents: body.documents ?? [] });
+    const documents = body.documents ?? [];
+    for (const doc of documents) {
+        writeLine(door.io.stdout, `${doc.id}  ${doc.state.padEnd(13)}  ${(doc.notion_synced_at ?? "never").padEnd(25)}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    const byState = body.counts?.by_state ?? {};
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${body.counts?.linked ?? documents.length} linked: ${Object.entries(byState)
+        .map(([state, count]) => `${count} ${state}`)
+        .join(", ")}. A Notion edit shows up at the next pull, not here.`);
+    return 0;
+}
+export async function linkDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot write to it: ${ref}`);
+    }
+    const path = `/api/docs/documents/${encodeURIComponent(resolved.id)}/notion-link`;
+    const answer = command.clearLink
+        ? await askAgentDoor(door, { path, method: "DELETE", label: "docs link", timeoutMs: WRITE_DEADLINE_MS })
+        : await askAgentDoor(door, {
+            path,
+            method: "PUT",
+            label: "docs link",
+            timeoutMs: WRITE_DEADLINE_MS,
+            body: { notion_page: command.notionPage ?? "" },
+        });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    const document = result.document ?? {};
+    writeLine(door.io.stderr, `${TAG} link ${JSON.stringify({ document_id: document["id"] ?? resolved.id, outcome: result.outcome ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, outcome: result.outcome, document });
+    const title = String(document["title"] ?? "");
+    const page = document["notion_page_id"];
+    const sentence = {
+        linked: `Linked ${title} to Notion page ${String(page)}. The next sync pulls the page over this copy and keeps the copy as a version.`,
+        already_linked: `${title} was already linked to Notion page ${String(page)}. Nothing changed.`,
+        unlinked: `Unlinked ${title} from Notion. It is a Tower-only document now.`,
+        already_unlinked: `${title} was not linked to Notion. Nothing changed.`,
+    };
+    writeLine(door.io.stdout, sentence[result.outcome ?? ""] ?? `Done: ${title}.`);
+    return 0;
+}

package/dist/commands/docs.js

@@ -29,6 +29,7 @@
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { linkDoc, syncStatusDocs } from "./docs-notion.js";
 import { readNoteFile } from "./notes-file.js";
 const TAG = "[docs cli]";
 const READ_DEADLINE_MS = 30_000;
@@ -47,6 +48,10 @@ export async function runDocs(command, io) {
             return createDoc(command, door);
         case "update":
             return updateDoc(command, door);
+        case "link":
+            return linkDoc(command, door);
+        case "sync-status":
+            return syncStatusDocs(command, door);
     }
 }
 /** `--parent`, `--query`, `--limit` as the door's own query parameters (BLI-3737). */
@@ -112,7 +117,7 @@ async function treeDocs(door) {
     return 0;
 }
 /** Finds a document id by exact id or exact slug against the flat list. Never fuzzy. */
-async function resolveDocId(door, ref) {
+export async function resolveDocId(door, ref) {
     const answer = await askAgentDoor(door, {
         path: "/api/docs/documents",
         method: "GET",

package/dist/commands/local-args-tower-docs-msg.js

@@ -7,8 +7,8 @@
  * added both without stretching either existing family's own doc comment.
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
-const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update"]);
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update"]);
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "link", "sync-status"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update", "link"]);
 export function parseDocsArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -23,20 +23,46 @@ export function parseDocsArgs(args) {
             "--body-stdin",
             "--query",
             "--limit",
+            "--clear",
             "--json",
         ],
         valueFlags: ["--home", "--dashboard-url", "--title", "--parent", "--visibility", "--file", "--query", "--limit"],
     });
     const { action, rest } = parseDocsAction(values.positionals);
-    const docRef = parseDocsDocumentReference(action, rest);
+    const link = parseDocsLink(action, rest, values.booleans.has("--clear"));
+    const docRef = parseDocsDocumentReference(action, link.rest);
     const { visibility, clearParent, parentId, allowEmpty, title, query, limit } = parseDocsFlags(action, values);
-    return buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit);
+    return buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit, link);
+}
+/**
+ * BLI-10430: `docs link <id|slug> <notion-url|page-id>` ties a document to a
+ * Notion page; `docs link <id|slug> --clear` unties it. Exactly one of the two:
+ * a link with neither says nothing, and one with both says two things.
+ */
+function parseDocsLink(action, rest, clear) {
+    if (action !== "link") {
+        if (clear)
+            throw new Error("--clear belongs to `cockpit docs link`.");
+        return { rest };
+    }
+    // No document at all: the document-reference check says so, first.
+    if (rest.length === 0)
+        return { rest };
+    const notionPage = optionalNonEmpty(rest[1]);
+    if (clear && notionPage)
+        throw new Error("docs link takes a Notion page OR --clear, not both.");
+    if (!clear && !notionPage) {
+        throw new Error("docs link needs a Notion page URL or id after the document, or --clear to unlink it.");
+    }
+    if (rest.length > 2)
+        throw new Error(`docs link takes a document and a Notion page, not ${rest.length} arguments.`);
+    return { rest: rest.slice(0, 1), ...(notionPage ? { notionPage } : {}), ...(clear ? { clearLink: true } : {}) };
 }
 function parseDocsAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!DOCS_ACTIONS.has(action)) {
-        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, or update.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, link, or sync-status.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -49,6 +75,12 @@ function parseDocsDocumentReference(action, rest) {
             throw new Error(`docs ${action} takes one document reference, not ${rest.length}.`);
         return docRef;
     }
+    // BLI-10430: `sync-status` reports the whole linked library, or one document.
+    if (action === "sync-status") {
+        if (rest.length > 1)
+            throw new Error(`docs sync-status takes at most one document reference, not ${rest.length}.`);
+        return optionalNonEmpty(rest[0]);
+    }
     if (rest.length > 0)
         throw new Error(`docs ${action} does not take "${rest[0]}".`);
     return undefined;
@@ -92,7 +124,7 @@ function parseDocsFlags(action, values) {
     }
     return { visibility, clearParent, parentId, allowEmpty, title, query, limit };
 }
-function buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit) {
+function buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit, link) {
     return {
         kind: "docs",
         action,
@@ -108,6 +140,8 @@ function buildDocsCommand(values, action, docRef, visibility, clearParent, paren
         bodyStdin: values.booleans.has("--body-stdin"),
         ...(query ? { query } : {}),
         ...(limit === undefined ? {} : { limit }),
+        ...(link.notionPage ? { notionPage: link.notionPage } : {}),
+        ...(link.clearLink ? { clearLink: true } : {}),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local-help-commands-tower.js

@@ -42,7 +42,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "docs",
         [
-            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
+            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>|link <id|slug> <notion-page>|sync-status [<id|slug>]] [flags]",
             "",
             "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
             "list [--parent <id>|root] [--query <text>] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB).",
@@ -54,6 +54,8 @@ export const TOWER_COMMAND_HELP = [
             "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
             "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
             "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
+            "link <id|slug> <notion-url|page-id> — ties the document to a Notion page so the two-way sync moves it both ways. The page is the truth from then on: the next sync pulls it over this copy and keeps the copy as a version. `link <id|slug> --clear` unties it. Refusals: invalid_notion_page, notion_page_already_linked, document_not_writable.",
+            "sync-status [<id|slug>] — every linked document's Notion sync state, or one's: synced (the body is what both sides last agreed on), tower_changed (edited here since; the next write-back pushes it), never_synced (linked, no baseline yet). Tower's half only: a Notion edit shows up at the next pull, not here. Metadata only, never a body.",
             "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
             "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.135");
+    writeLine(io?.stdout ?? process.stdout, "0.2.137");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.135",
+  "version": "0.2.137",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.35",
-    "@bli-cockpit/mcp": "0.1.61",
+    "@bli-cockpit/mcp": "0.1.63",
     "@bli-cockpit/telemetry-core": "0.1.48"
   }
 }