@lumoai/cli 1.29.1 → 1.30.0

package/assets/skill/SKILL.md

@@ -97,10 +97,10 @@ The command catalog below is a **map**: it lists every command grouped by domain
 
 **Documents** — see [docs.md](references/docs.md)
 
-- `lumo doc create/update/show/list/delete` — document CRUD; `doc show` prints the body revision, `doc update` takes `--if-revision <n>` (mismatch → 409 conflict, re-read and retry — no silent overwrite)
+- `lumo doc create/update/show/list/delete` — document CRUD; `doc show` prints the body revision, `doc update` takes `--if-revision <n>` (mismatch → 409 conflict, re-read and retry — no silent overwrite); a body update that drops tables/rows/headings vs the stored body is rejected 422 by the built-in structure guard unless `--allow-shrink` is passed (intentional deletions only — on 422 first suspect a stale edit base)
 - `lumo doc show <doc> --raw` — print the byte-identical markdown source of the last markdown upload (the only legal edit base; errors when no source is stored — never falls back to the lossy HTML→md render)
 - `lumo doc show <doc> --section "<heading>"` — print just one heading-addressed section of the markdown source (byte-faithful slice, subsections included; revision on stderr; prefix `#…` pins depth)
-- `lumo doc patch <doc> --section "<heading>" --content/--file/stdin [--if-revision N]` — replace ONLY that section (heading line included); every byte outside it is untouched; concurrent edits 409 instead of clobbering
+- `lumo doc patch <doc> --section "<heading>" --content/--file/stdin [--if-revision N] [--allow-shrink]` — replace ONLY that section (heading line included); every byte outside it is untouched; concurrent edits 409 instead of clobbering; the structure guard 422s a replacement that drops the section's tables/rows/headings unless `--allow-shrink` (appends are never guarded)
 - `lumo doc append <doc> [--section "<heading>"] --content/--file/stdin [--if-revision N]` — append at section end (or doc end without `--section`); pure insertion, no existing byte modified — the safest write for running logs/ledgers
 - `lumo doc diff <doc> --file <local.md>` — compare the server-side markdown source against a local file (exit 0 identical, 1 with unified diff)
 - `lumo doc move` — reparent under a parent / to root

package/assets/skill/references/docs.md

@@ -63,8 +63,11 @@ The `Tags:` line is omitted when no tags were attached.
 | `--add-tag-id <cuid>`    | string (repeatable) | Attach tag by id. Max 20.                                                                                                                                                                                                                                             |
 | `--remove-tag <name>`    | string (repeatable) | Detach tag by name. `--remove-tag <name>` resolves the name via find-or-create on the workspace. If the name was unknown, a new Tag row is created (orphan, no attachments) before the detach runs as a no-op. Use `--remove-tag-id <cuid>` to avoid orphans. Max 20. |
 | `--remove-tag-id <cuid>` | string (repeatable) | Detach tag by id. Unknown ids are a no-op (no side effects). Max 20.                                                                                                                                                                                                  |
+| `--allow-shrink`         | boolean             | Let a body update through even when it drops tables/rows/headings versus the stored body (see structure guard below).                                                                                                                                                 |
 
-Optimistic concurrency (LUM-409): `--if-revision <n>` only applies the update if the doc body is still at revision `n` (from `doc show`). Mismatch → 409 conflict, nothing written — re-read, rebase, retry. `--if-revision` alone is not an update (still errors "no fields to update").
+Optimistic concurrency (LUM-409): `--if-revision <n>` only applies the update if the doc body is still at revision `n` (from `doc show`). Mismatch → 409 conflict, nothing written — re-read, rebase, retry. `--if-revision` alone is not an update (still errors "no fields to update"); same for `--allow-shrink`.
+
+**Structure guard (LUM-410), built into the server:** a body update whose new render has **fewer `table` / `tr` / heading elements than the stored body** is rejected with **422** before anything is written — the error names each shrunk category with old→new counts (e.g. `table 1→0, tr 4→0`). This is the `verify-live-doc.ts` reconciliation moved into the write path, so table flattening (LUM-349) and stale-base section loss (#460) fail loudly even when nobody remembers to run the script. When the deletion is intentional (you really are removing a section/table), re-run with `--allow-shrink`. On a 422: don't reach for `--allow-shrink` reflexively — first check whether your edit base is stale (`doc show <doc> --raw`) and rebase. Only markdown-path writes are guarded; web-editor edits and `doc sync` (Google authority) are not.
 
 `--tag` / `--tag-id` (bulk replace) are mutually exclusive with `--add-tag` / `--add-tag-id` / `--remove-tag` / `--remove-tag-id`. The CLI errors before any network call if both families are mixed.
 
@@ -88,6 +91,7 @@ lumo doc update RFC --tag final --add-tag oops
 - After running `lumo doc list` or `doc show`, if the user wants to change a doc's scope, title, or content.
 - For a small edit inside one section, prefer `doc patch` / `doc append` (below) — full `doc update` has the maximum clobber radius.
 - When replacing the body from a previously fetched base, pass `--if-revision` so a concurrent edit fails loudly (409) instead of being overwritten.
+- When the update intentionally deletes a section or table, pass `--allow-shrink` up front; otherwise expect (and want) the 422 structure guard on accidental structure loss.
 
 ### `lumo doc show <doc> [--raw | --section <heading>]` — print one document's detail
 
@@ -134,10 +138,13 @@ Replaces the **whole addressed section** (heading line included, subsections inc
 | `--content <text>`    | string | New section content (include the heading line — the whole section is replaced verbatim).            |
 | `--file <path>`       | string | New section content from file (project-local sandbox).                                              |
 | `--if-revision <n>`   | int    | Only apply if the body is still at revision `n`. Recommended whenever the edit base was read earlier. |
+| `--allow-shrink`      | boolean | Let the patch through even when it drops tables/rows/headings within the addressed section (422 otherwise). |
 
 Concurrency: the splice always commits **conditionally** on the revision the server read the source at — even without `--if-revision`, a concurrent body edit between read and write returns 409 instead of clobbering. On 409 the CLI prints the server reason plus a re-read-and-retry hint and exits 1.
 
-Requires a stored markdown source (same rule as `--raw`); errors with the rebuild hint otherwise. Replacement is verbatim — if the new content omits the heading line, the heading is gone (that is an explicit choice, not a merge).
+Structure guard (LUM-410), **scoped to the addressed section**: a replacement whose render has fewer `table`/`tr`/heading elements than the old section's render is rejected with 422 naming each shrunk category (old→new counts); structure elsewhere in the document never factors in. Dropping the heading line itself trips the guard too (heading count shrinks). Pass `--allow-shrink` when the deletion is intentional. `doc append` is pure insertion and is never guarded.
+
+Requires a stored markdown source (same rule as `--raw`); errors with the rebuild hint otherwise. Replacement is verbatim — if the new content omits the heading line, the heading is gone (an explicit choice the guard makes you confirm with `--allow-shrink`).
 
 ```bash
 lumo doc show cmd_xxx --section "D 状态表" > sec.md   # stderr: Revision: 6
@@ -151,6 +158,7 @@ lumo doc patch cmd_xxx --section "D 状态表" --file sec.md --if-revision 6
 - User wants to change one section of a live doc ("update the status table", "rewrite section D") — patch beats full `doc update` on clobber radius and context size.
 - Live-doc status updates that used to be read-whole/edit/upload-whole round-trips.
 - If the patch 409s: re-read the section, rebase the edit, retry — never fall back to a full-body upload from the stale base.
+- If the patch 422s (structure guard): the replacement drops tables/rows/headings the section has. Re-check the edit base first; add `--allow-shrink` only when the deletion is what the user wants.
 
 ### `lumo doc append <doc> [--section <heading>]` — append to a section (or the doc)
 

package/dist/cli/src/commands/doc-section-edit.js

@@ -69,6 +69,8 @@ async function docSectionEdit(mode, reference, opts) {
     }
     if (ifRevision !== undefined)
         body.ifRevision = ifRevision;
+    if (opts.allowShrink)
+        body.allowShrink = true;
     const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}/section`, {
         method: 'POST',
         headers: {
@@ -79,18 +81,20 @@ async function docSectionEdit(mode, reference, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
-        let message = text;
-        try {
-            message = JSON.parse(text).error ?? text;
-        }
-        catch {
-            // non-JSON error body — print as-is
-        }
+        const message = (0, api_1.extractErrorMessage)(text);
         if (res.status === 409) {
             console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
             console.error(`Hint: re-read the section (lumo doc show ${reference}${opts.section ? ` --section "${opts.section}"` : ''}), rebase your edit on it, then retry with --if-revision <current>.`);
             return 1;
         }
+        if (res.status === 422) {
+            // Structure guard rejection (LUM-410): the replacement drops structure
+            // the addressed section has (the message names each category, old→new).
+            console.error(`Error: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: if the deletion is intentional, re-run with --allow-shrink. ` +
+                `Otherwise re-read the section (lumo doc show ${reference}${opts.section ? ` --section "${opts.section}"` : ''}) and rebase your edit on it.`);
+            return 1;
+        }
         console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(message)}`);
         return 1;
     }

package/dist/cli/src/commands/doc-update.js

@@ -82,6 +82,8 @@ async function docUpdate(reference, opts) {
         }
         body.ifRevision = Number(opts.ifRevision);
     }
+    if (opts.allowShrink)
+        body.allowShrink = true;
     // Resolve tag refs into ids
     const deps = { apiUrl, token: creds.token };
     let tagIds;
@@ -114,8 +116,10 @@ async function docUpdate(reference, opts) {
         body.addTagIds = addTagIds;
     if (removeTagIds !== undefined)
         body.removeTagIds = removeTagIds;
-    // --if-revision is a precondition, not a field — alone it's not an update.
-    if (Object.keys(body).filter(k => k !== 'ifRevision').length === 0) {
+    // --if-revision / --allow-shrink are modifiers, not fields — alone they
+    // are not an update.
+    if (Object.keys(body).filter(k => k !== 'ifRevision' && k !== 'allowShrink')
+        .length === 0) {
         console.error('Error: no fields to update — provide at least one flag');
         return 1;
     }
@@ -130,19 +134,22 @@ async function docUpdate(reference, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
+        const message = (0, api_1.extractErrorMessage)(text);
         if (res.status === 409 && opts.ifRevision !== undefined) {
-            let message = text;
-            try {
-                message = JSON.parse(text).error ?? text;
-            }
-            catch {
-                // non-JSON error body — print as-is
-            }
             console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
             console.error(`Hint: re-read the doc (lumo doc show ${reference} --raw), rebase your edit ` +
                 `on the current source, then retry with --if-revision <current>.`);
             return 1;
         }
+        if (res.status === 422) {
+            // Structure guard rejection (LUM-410): the new body drops structure
+            // the stored body has (the message names each category, old→new).
+            console.error(`Error: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: if the deletion is intentional, re-run with --allow-shrink. ` +
+                `Otherwise re-read the current source (lumo doc show ${reference} --raw) ` +
+                `and rebase your edit on it.`);
+            return 1;
+        }
         console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }

package/dist/cli/src/index.js

@@ -660,7 +660,7 @@ doc
     .action(wrap(ref => (0, doc_sync_1.docSync)(ref)));
 doc
     .command('update <doc>')
-    .description('Update an existing document. <doc> accepts a cuid or a case-insensitive title (ambiguous titles fail with candidates). Replacement body comes from --content, --file, or piped stdin (pick one). --tag/--tag-id (bulk replace) cannot be combined with --add-tag/--add-tag-id/--remove-tag/--remove-tag-id.')
+    .description('Update an existing document. <doc> accepts a cuid or a case-insensitive title (ambiguous titles fail with candidates). Replacement body comes from --content, --file, or piped stdin (pick one). A body update that drops tables/rows/headings versus the stored body is rejected with 422 (structure guard) unless --allow-shrink is passed. --tag/--tag-id (bulk replace) cannot be combined with --add-tag/--add-tag-id/--remove-tag/--remove-tag-id.')
     .option('--title <text>', 'New title')
     .option('--content <text>', 'Replace content (inline)')
     .option('--file <path>', 'Replace content from file')
@@ -673,6 +673,7 @@ doc
     .option('--remove-tag <name>', 'Remove tag by name (repeatable). Unknown names are find-or-create, so prefer --remove-tag-id to avoid orphan rows.', collect, [])
     .option('--remove-tag-id <cuid>', 'Remove tag by id (repeatable). Unknown ids are a no-op.', collect, [])
     .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show); mismatch fails with a 409 conflict')
+    .option('--allow-shrink', 'Let the update through even when it drops tables/rows/headings versus the stored body (default: rejected with 422)')
     .action(wrap((reference, opts) => (0, doc_update_1.docUpdate)(reference, opts)));
 doc
     .command('show <doc>')
@@ -682,11 +683,12 @@ doc
     .action(wrap((reference, opts) => (0, doc_show_1.docShow)(reference, opts)));
 doc
     .command('patch <doc>')
-    .description('Replace one heading-addressed section of the markdown source (heading line included), leaving every byte outside the section untouched. Requires the doc to have a stored markdown source. Commits conditionally on the body revision: a concurrent edit fails with 409 instead of being overwritten.')
+    .description('Replace one heading-addressed section of the markdown source (heading line included), leaving every byte outside the section untouched. Requires the doc to have a stored markdown source. Commits conditionally on the body revision: a concurrent edit fails with 409 instead of being overwritten. A replacement that drops tables/rows/headings within the addressed section is rejected with 422 (structure guard) unless --allow-shrink is passed.')
     .requiredOption('--section <heading>', 'Heading of the section to replace (prefix with #… to pin depth)')
     .option('--content <text>', 'New section content (inline markdown)')
     .option('--file <path>', 'New section content from file')
     .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show)')
+    .option('--allow-shrink', 'Let the patch through even when it drops tables/rows/headings within the addressed section (default: rejected with 422)')
     .action(wrap((reference, opts) => (0, doc_section_edit_1.docPatch)(reference, opts)));
 doc
     .command('append <doc>')

package/dist/cli/src/lib/api.js

@@ -5,6 +5,7 @@ exports.hostMismatchWarning = hostMismatchWarning;
 exports.resolveAuthedApiUrl = resolveAuthedApiUrl;
 exports.resolveApiUrl = resolveApiUrl;
 exports.trimTrailingSlash = trimTrailingSlash;
+exports.extractErrorMessage = extractErrorMessage;
 exports.verifyToken = verifyToken;
 const DEFAULT_API_URL = 'https://www.uselumo.ai';
 // Hostnames allowed to use plaintext http:// — local dev only. Everything
@@ -91,6 +92,18 @@ function resolveApiUrl() {
 function trimTrailingSlash(url) {
     return url.replace(/\/+$/, '');
 }
+/**
+ * Pull the `error` field out of a JSON API error body; non-JSON bodies (or
+ * JSON without an `error` string) fall back to the raw text unchanged.
+ */
+function extractErrorMessage(text) {
+    try {
+        return JSON.parse(text).error ?? text;
+    }
+    catch {
+        return text;
+    }
+}
 async function verifyToken(apiUrl, token) {
     let res;
     try {

package/dist/shared/src/html-structure.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Structural tag counting over rendered document HTML.
+ *
+ * Single source of truth shared by the server-side structure guard on the
+ * document update path (LUM-410) and `scripts/verify-live-doc.ts`, so the
+ * guard and the script can never drift on what counts as "structure".
+ *
+ * Counting is regex-based over the rendered HTML. That is safe here because
+ * both inputs always come out of the same `markdownToHtml` renderer (or the
+ * Tiptap editor's serializer), which emits plain lowercase tags — this is
+ * not a general-purpose HTML parser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAG_PATTERNS = void 0;
+exports.countPattern = countPattern;
+exports.compareStructure = compareStructure;
+exports.hardMismatches = hardMismatches;
+exports.softMismatches = softMismatches;
+exports.structureShrinks = structureShrinks;
+exports.formatStructureShrinks = formatStructureShrinks;
+/** Categories `verify-live-doc.ts` reports on (hard = table structure). */
+exports.TAG_PATTERNS = [
+    { tag: 'table', pattern: /<table/g, hard: true },
+    { tag: 'tr', pattern: /<tr/g, hard: true },
+    { tag: 'h1', pattern: /<h1/g, hard: false },
+    { tag: 'h2', pattern: /<h2/g, hard: false },
+    { tag: 'h3', pattern: /<h3/g, hard: false },
+    { tag: 'li', pattern: /<li/g, hard: false },
+    { tag: 'a', pattern: /<a[\s>]/g, hard: false },
+    { tag: 'strong', pattern: /<strong/g, hard: false },
+    { tag: 'code', pattern: /<code/g, hard: false },
+    { tag: 'blockquote', pattern: /<blockquote/g, hard: false },
+];
+function countPattern(html, pattern) {
+    return (html.match(pattern) ?? []).length;
+}
+function compareStructure(renderedHtml, storedHtml) {
+    return exports.TAG_PATTERNS.map(({ tag, pattern, hard }) => ({
+        tag,
+        rendered: countPattern(renderedHtml, pattern),
+        stored: countPattern(storedHtml, pattern),
+        hard,
+    }));
+}
+function hardMismatches(checks) {
+    return checks.filter(c => c.hard && c.rendered !== c.stored);
+}
+function softMismatches(checks) {
+    return checks.filter(c => !c.hard && c.rendered !== c.stored);
+}
+/**
+ * Categories the update guard protects. Headings are counted as one
+ * aggregate bucket (h1–h6) so promoting/demoting a heading level is not a
+ * loss — only dropping a section heading outright is.
+ */
+const GUARD_PATTERNS = [
+    { tag: 'table', pattern: /<table/g },
+    { tag: 'tr', pattern: /<tr/g },
+    { tag: 'heading', pattern: /<h[1-6][\s>]/g },
+];
+/**
+ * Compare two rendered HTML bodies and report every guarded category whose
+ * count shrank. Empty result = the edit loses no guarded structure.
+ */
+function structureShrinks(oldHtml, newHtml) {
+    const shrinks = [];
+    for (const { tag, pattern } of GUARD_PATTERNS) {
+        const before = countPattern(oldHtml, pattern);
+        const after = countPattern(newHtml, pattern);
+        if (after < before)
+            shrinks.push({ tag, before, after });
+    }
+    return shrinks;
+}
+/** "table 3→0, tr 12→0" — the per-category loss detail for error messages. */
+function formatStructureShrinks(shrinks) {
+    return shrinks.map(s => `${s.tag} ${s.before}→${s.after}`).join(', ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.29.1",
+  "version": "1.30.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",