superbee 0.4.4-pre.14 → 0.4.4-pre.16

package/README.md

@@ -78,7 +78,7 @@ first-party support promise for native Windows. An older installed version is no
 removed by this source change, and existing bundle files are not migrated by it. Review the affected release's notes before changing an existing
 Windows installation. macOS/Linux users can continue using the normal installation and setup flow.
 
-Run `superbee version --check` to compare your install with the current stable release.
+Run `superbee version` to see which build you have. `superbee version --check` is not available on published builds yet: it exits 1 with `policy_disabled` and makes no network request. Check the npm page or `npm view superbee version` for the current release.
 
 ## First run: let your agent finish setup
 
@@ -127,6 +127,51 @@ In a hosted checkout, `superbee view read <id>` prints a View page's version on
 `superbee view update <id> --expected-version <version>` replaces the page there (sync never sends
 `views/`). Uploading a page never approves its execution.
 
+## Copying documents between bundles
+
+`superbee doc import` copies chosen documents from another bundle with new ids and rewritten links.
+Declare the source first, then review the plan before applying it:
+
+```sh
+superbee deps add wave --bundle-id <source-bundle-id> --path ../wave
+superbee doc import --from wave --with wave=../wave --select type=Theme --prefix wave
+superbee doc import --from wave --with wave=../wave --select type=Theme --prefix wave --apply <plan-token>
+superbee doc import --from wave --with wave=../wave --refresh <record-id>
+```
+
+The first import command only prints the plan and its token. Applying writes new documents and one
+Promotion record, and never overwrites a document. `--resume <record-id>` finishes an interrupted
+run. `--refresh <record-id>` updates the copies from their sources with the same plan and apply
+steps; a copy edited since the import is a conflict until you name it with `--overwrite <id>` or
+`--skip <id>`. The target must be a local bundle or Git board. `superbee doc import --help` has the
+full reference.
+
+## When a document cannot be read
+
+Superbee bounds how much frontmatter it parses: 262,144 characters of YAML, 32 levels of nesting, and limits on
+YAML alias use. Ordinary documents are far below these limits. A write over a limit is refused with
+`USAGE` and nothing is stored. A document already in the bundle that is over a limit, or whose YAML
+is invalid, cannot be read:
+
+- `doc read` on it fails with `RUNTIME`. `details.frontmatter.code` is `FRONTMATTER_TOO_LARGE`,
+  `FRONTMATTER_TOO_DEEP`, `FRONTMATTER_ALIAS_LIMIT`, `FRONTMATTER_CYCLE` or
+  `FRONTMATTER_MALFORMED`, and `details.frontmatter.document` names the file.
+- To find every affected document, run `superbee status` (the `malformed` count and rows) or
+  `superbee list` (the `skipped` rows). `search`, `query`, `index generate`, `link list`,
+  `link show`, `view list` and `kinds --coverage` also skip it, say so, and keep working.
+- To fix it, edit the lines between the `---` markers in a text editor, or remove the document with
+  `superbee doc delete <id>`. `doc update` and `doc field` cannot change a document they cannot read.
+
+On a Git board, `sync` holds a changed file it cannot read: it exits 5, names the file, and commits
+and pushes nothing until you fix it. If a conflict kept a version that cannot be read, the receipt
+tells you to copy your saved export over the document.
+
+In a hosted checkout, a host document this client cannot store comes back as a `held` row named with
+its `FRONTMATTER_*` code, exit 5, and everything else proceeds. The next sync places it once it is
+repaired on the host. If the checkout's own local store holds a copy it cannot read, sync stops with
+`store_damaged` and sends and places nothing. Reads continue and `status` reports it. Copy out any
+unsent edits and make a fresh checkout, as the error's help describes.
+
 ## Upgrading from aslite
 
 If you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install
@@ -139,6 +184,8 @@ run `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and
 The [repository](https://github.com/Holaxis-ai/superbee) holds the source, the
 [CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/superbee/AXI-CONTRACT.md),
 and the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).
+Site builders can read a publication's Site declaration through `superbee/publication/site-manifest`;
+see [Site declarations](https://github.com/Holaxis-ai/superbee/blob/main/packages/publication/SITE-MANIFEST.md).
 
 ## License
 

package/SKILL.md

@@ -74,7 +74,7 @@ files, and stop. Use `superbee <command> --help` for exact current syntax rather
 copied command manual. Use `--body-file` for multiline Markdown. `list` / `query` filter metadata, not body text; `doc update` / `doc field` patch metadata while preserving omitted fields and body. For body edits, read the complete body with `doc read <id> --body-out <temp-file>` outside the bundle, edit that temporary file, then `doc update <id> --body-file <temp-file> --expected-version <head_version> --actor <actor>` using the version from the read. Re-read and reconcile on a version conflict. Never feed a truncated preview or a full-document `--out` export to `--body-file`: body input is Markdown only; tooling owns YAML frontmatter. With MCP, use available tools and version preconditions; check tool schemas rather than inventing search or patch verbs.
 
 Focused shipped material is available under `$REFS/recipes/` for portable examples,
-`$REFS/views/` for View authoring and examples, and `$REFS/sample-bundle/` for OKF interop. Integration authoring and explicit local source bind/run use `$REFS/author-an-integration.md`; recorded `$REFS/integrations/` examples need no credentials.
+`$REFS/views/` for View authoring and examples, and `$REFS/sample-bundle/` for OKF interop. Integration authoring and explicit local source bind/run use `$REFS/author-an-integration.md`; recorded `$REFS/integrations/` examples need no credentials. `RUNTIME` with `details.frontmatter.code` means a document cannot be read: see "When a document cannot be read" in `$REFS/modeling-and-delivery.md`, which also covers `superbee doc import`.
 Read only what the accepted work requires.
 
 ## Make the value visible
@@ -93,7 +93,7 @@ When the tone fits, a single 🐝 may mark a successful Superbee outcome.
 
 ## Sync conflicts
 
-- A Git board and a hosted checkout share one playbook. When `superbee sync` exits 5 with conflict rows, run `superbee sync --inspect --doc <id>` to see your version and theirs, then `superbee sync --resolve keep|take|revise --doc <id>`: keep writes yours over theirs, take keeps theirs, revise keeps the document as you edited it to the merged result. `--resolve` never sends: run `superbee sync` after keep or revise. A Git board has already kept the teammate's version and saved yours aside; a hosted checkout keeps your file, treats any concurrent change to one document (even different frontmatter keys) as a conflict, and is explained in `$REFS/hosted-checkout.md`.
+- A Git board and a hosted checkout share one playbook. When `superbee sync` exits 5 with conflict rows, run `superbee sync --inspect --doc <id>` to see your version and theirs, then `superbee sync --resolve keep|take|revise --doc <id>`: keep writes yours over theirs, take keeps theirs, revise keeps the document as you edited it to the merged result. `--resolve` never sends: run `superbee sync` after keep or revise. A Git board has already kept the teammate's version and saved yours aside, and only the new conflict exits 5: `status` and later `sync` runs keep naming the saved copy, with the command that discards it, until it is settled; keep is refused when your copy also differs in frontmatter, so edit the document to the result and use revise. A hosted checkout keeps your file, treats any concurrent change to one document (even different frontmatter keys) as a conflict, and is explained in `$REFS/hosted-checkout.md`.
 
 ## Host setup
 

package/dist/publication-bridge.mjs

@@ -3175,8 +3175,18 @@ function parseFrontmatter(source, context, options = {}) {
   }
   return normalizeFrontmatter(parsed, options);
 }
+function isStackExhaustion(error) {
+  if (error instanceof RangeError) return /call stack/i.test(error.message);
+  return error?.name === "InternalError" && /recursion/i.test(error.message);
+}
 function stringifyFrontmatter(data) {
-  const dumped = import_js_yaml2.default.safeDump(data).trim();
+  let dumped;
+  try {
+    dumped = import_js_yaml2.default.safeDump(data).trim();
+  } catch (error) {
+    if (isStackExhaustion(error)) throw new FrontmatterRefusedError("FRONTMATTER_TOO_DEEP", `YAML nesting is deeper than ${FRONTMATTER_LIMITS.depth} levels`);
+    throw error;
+  }
   try {
     yamlEngine.parse(`${dumped}
 `);
@@ -3268,6 +3278,17 @@ function isReservedFile(relPath) {
   const base = toPosix(relPath).split("/").pop() ?? "";
   return RESERVED_FILENAMES.includes(base);
 }
+function isHiddenWalkEntry(name) {
+  return name.startsWith(".");
+}
+function hasMarkdownExtension(name) {
+  return name.toLowerCase().endsWith(".md");
+}
+function classifyWalkPath(relPath) {
+  const segments = toPosix(relPath).split("/").filter((segment) => segment !== "");
+  if (segments.some(isHiddenWalkEntry)) return "hidden";
+  return hasMarkdownExtension(segments.at(-1) ?? "") ? "markdown" : "other";
+}
 function conceptIdFromPath(relPath) {
   const norm = toPosix(relPath).replace(/^\.?\//, "").split("/").filter((segment) => segment !== ".").join("/");
   return norm.endsWith(".md") ? norm.slice(0, -3) : norm;
@@ -3998,24 +4019,7 @@ function hasSourceIdentity(sources, identity) {
   return Array.isArray(sources) && sources.some((entry) => matchesSourceIdentity(entry, identity));
 }
 
-// ../core/src/engine.ts
-async function readBundleOkfVersion(backend) {
-  const index = await backend.readReserved("", "index.md");
-  if (!index) return void 0;
-  const value = parseLeadingFrontmatter(index.content, "index.md").okf_version;
-  return typeof value === "string" && value.trim() !== "" ? value : void 0;
-}
-function assertReadableConceptId(id) {
-  assertSafeConceptId(id);
-  const rel = pathFromConceptId(id);
-  if (isReservedFile(rel)) {
-    throw new InvalidInputError(`'${id}' is a reserved file (index.md / log.md), not a concept document.`);
-  }
-}
-async function readDocVersioned(backend, id) {
-  assertReadableConceptId(id);
-  return backend.read(id);
-}
+// ../core/src/document-scan.ts
 function isEnoent(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
@@ -4046,6 +4050,25 @@ async function readManyExisting(backend, ids, onMalformed, onAliased) {
     return out;
   }
 }
+
+// ../core/src/engine.ts
+async function readBundleOkfVersion(backend) {
+  const index = await backend.readReserved("", "index.md");
+  if (!index) return void 0;
+  const value = parseLeadingFrontmatter(index.content, "index.md").okf_version;
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+function assertReadableConceptId(id) {
+  assertSafeConceptId(id);
+  const rel = pathFromConceptId(id);
+  if (isReservedFile(rel)) {
+    throw new InvalidInputError(`'${id}' is a reserved file (index.md / log.md), not a concept document.`);
+  }
+}
+async function readDocVersioned(backend, id) {
+  assertReadableConceptId(id);
+  return backend.read(id);
+}
 async function scanMatching(backend, filter, onSkip) {
   const ids = await backend.list(filter.prefix);
   const results = [];
@@ -5321,7 +5344,7 @@ async function walkFiles(port, root, keep, sub = "") {
   const entries = await port.entries(path3.join(root, sub)) ?? [];
   const out = [];
   for (const entry of entries) {
-    if (entry.name.startsWith(".")) continue;
+    if (isHiddenWalkEntry(entry.name)) continue;
     const rel = sub === "" ? entry.name : `${sub}/${entry.name}`;
     if (entry.kind === "directory") {
       out.push(...await walkFiles(port, root, keep, rel));
@@ -5580,12 +5603,15 @@ var FilesystemBackend = class _FilesystemBackend {
     return observed.state === "exact" && observed.value.kind === "file";
   }
   async listBlobs(prefix) {
-    const files = await walkFiles(this.#port, this.#root, (name) => !name.toLowerCase().endsWith(".md"));
+    const files = await walkFiles(this.#port, this.#root, (name) => !hasMarkdownExtension(name));
     const keys2 = files.map(toPosix);
     const filtered = prefix ? keys2.filter((k) => k.startsWith(prefix)) : keys2;
     filtered.sort(compareStorageKeys);
     return filtered;
   }
+  classifyChangedPath(relPath) {
+    return classifyWalkPath(relPath);
+  }
   capabilities() {
     return {
       history: false,

package/dist/publication.mjs

@@ -31129,8 +31129,18 @@ function parseFrontmatter(source, context, options = {}) {
   }
   return normalizeFrontmatter(parsed, options);
 }
+function isStackExhaustion(error) {
+  if (error instanceof RangeError) return /call stack/i.test(error.message);
+  return error?.name === "InternalError" && /recursion/i.test(error.message);
+}
 function stringifyFrontmatter(data) {
-  const dumped = import_js_yaml2.default.safeDump(data).trim();
+  let dumped;
+  try {
+    dumped = import_js_yaml2.default.safeDump(data).trim();
+  } catch (error) {
+    if (isStackExhaustion(error)) throw new FrontmatterRefusedError("FRONTMATTER_TOO_DEEP", `YAML nesting is deeper than ${FRONTMATTER_LIMITS.depth} levels`);
+    throw error;
+  }
   try {
     yamlEngine.parse(`${dumped}
 `);
@@ -31222,6 +31232,17 @@ function isReservedFile(relPath) {
   const base = toPosix(relPath).split("/").pop() ?? "";
   return RESERVED_FILENAMES.includes(base);
 }
+function isHiddenWalkEntry(name) {
+  return name.startsWith(".");
+}
+function hasMarkdownExtension(name) {
+  return name.toLowerCase().endsWith(".md");
+}
+function classifyWalkPath(relPath) {
+  const segments = toPosix(relPath).split("/").filter((segment) => segment !== "");
+  if (segments.some(isHiddenWalkEntry)) return "hidden";
+  return hasMarkdownExtension(segments.at(-1) ?? "") ? "markdown" : "other";
+}
 function conceptIdFromPath(relPath) {
   const norm = toPosix(relPath).replace(/^\.?\//, "").split("/").filter((segment) => segment !== ".").join("/");
   return norm.endsWith(".md") ? norm.slice(0, -3) : norm;
@@ -31959,24 +31980,7 @@ function hasSourceIdentity(sources, identity) {
   return Array.isArray(sources) && sources.some((entry) => matchesSourceIdentity(entry, identity));
 }
 
-// ../core/src/engine.ts
-async function readBundleOkfVersion(backend) {
-  const index2 = await backend.readReserved("", "index.md");
-  if (!index2) return void 0;
-  const value = parseLeadingFrontmatter(index2.content, "index.md").okf_version;
-  return typeof value === "string" && value.trim() !== "" ? value : void 0;
-}
-function assertReadableConceptId(id) {
-  assertSafeConceptId(id);
-  const rel = pathFromConceptId(id);
-  if (isReservedFile(rel)) {
-    throw new InvalidInputError(`'${id}' is a reserved file (index.md / log.md), not a concept document.`);
-  }
-}
-async function readDocVersioned(backend, id) {
-  assertReadableConceptId(id);
-  return backend.read(id);
-}
+// ../core/src/document-scan.ts
 function isEnoent(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
@@ -32007,6 +32011,25 @@ async function readManyExisting(backend, ids, onMalformed, onAliased) {
     return out;
   }
 }
+
+// ../core/src/engine.ts
+async function readBundleOkfVersion(backend) {
+  const index2 = await backend.readReserved("", "index.md");
+  if (!index2) return void 0;
+  const value = parseLeadingFrontmatter(index2.content, "index.md").okf_version;
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+function assertReadableConceptId(id) {
+  assertSafeConceptId(id);
+  const rel = pathFromConceptId(id);
+  if (isReservedFile(rel)) {
+    throw new InvalidInputError(`'${id}' is a reserved file (index.md / log.md), not a concept document.`);
+  }
+}
+async function readDocVersioned(backend, id) {
+  assertReadableConceptId(id);
+  return backend.read(id);
+}
 async function scanMatching(backend, filter, onSkip) {
   const ids = await backend.list(filter.prefix);
   const results = [];
@@ -33282,7 +33305,7 @@ async function walkFiles(port, root, keep, sub = "") {
   const entries = await port.entries(path3.join(root, sub)) ?? [];
   const out = [];
   for (const entry of entries) {
-    if (entry.name.startsWith(".")) continue;
+    if (isHiddenWalkEntry(entry.name)) continue;
     const rel = sub === "" ? entry.name : `${sub}/${entry.name}`;
     if (entry.kind === "directory") {
       out.push(...await walkFiles(port, root, keep, rel));
@@ -33541,12 +33564,15 @@ var FilesystemBackend = class _FilesystemBackend {
     return observed.state === "exact" && observed.value.kind === "file";
   }
   async listBlobs(prefix) {
-    const files = await walkFiles(this.#port, this.#root, (name) => !name.toLowerCase().endsWith(".md"));
+    const files = await walkFiles(this.#port, this.#root, (name) => !hasMarkdownExtension(name));
     const keys2 = files.map(toPosix);
     const filtered = prefix ? keys2.filter((k) => k.startsWith(prefix)) : keys2;
     filtered.sort(compareStorageKeys);
     return filtered;
   }
+  classifyChangedPath(relPath) {
+    return classifyWalkPath(relPath);
+  }
   capabilities() {
     return {
       history: false,