superbee 0.4.4-pre.14 → 0.4.4-pre.15

package/README.md

@@ -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

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}
 `);
@@ -3998,24 +4008,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 +4039,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 = [];

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}
 `);
@@ -31959,24 +31969,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 +32000,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 = [];