superbee 0.1.4 → 0.1.5-pre.2

package/README.md

@@ -40,24 +40,36 @@ know invisible to the humans they work for. Superbee fixes all three:
 The npm package ships one self-contained executable with zero runtime dependencies, plus an
 Agent Skill that teaches agents how to use it.
 
-## Install Steps
+## How do I download Superbee on Windows?
 
-**Requirements: Node.js 20 or newer on macOS, Linux, or Windows.** On Windows, Superbee keeps
-per-user operational state under `%LOCALAPPDATA%\Superbee` and uses Windows-native containment and
-path-identity checks instead of relying on synthesized POSIX mode bits. Native Windows behavior and
-the globally installed `superbee.cmd` entrypoint are covered by the required CI contract.
+**Requirements: Node.js 20 or newer on macOS, Linux, or native Windows.** You do not need WSL,
+Ubuntu, or Docker. On Windows, Superbee keeps per-user operational state under
+`%LOCALAPPDATA%\Superbee`; npm installs the command as `superbee.cmd`.
 
-1. Install the CLI globally:
+Superbee currently has two npm release channels:
 
-   ```sh
-   npm install -g superbee
-   ```
+- `latest` is the stable channel selected by bare `superbee`. Its current release predates native
+  Windows support.
+- `next` is the prerelease channel. It contains the current native-Windows build.
 
-2. Once superbee is installed, ask your AI agent to run `superbee setup`. Setup walks the
-   agent through the remaining integration steps (Agent Skill, SessionStart hook, MCP
-   registration) and orients it to the Superbee environment. It is read-only — it inspects
-   your configuration and returns one safe next command at a time, so the agent (with your
-   approval) performs any actual changes.
+Install the current prerelease on Windows:
+
+```powershell
+npm install -g superbee@next
+superbee.cmd setup
+```
+
+On macOS or Linux, the stable channel remains available with `npm install -g superbee`. To test the
+same prerelease as Windows, install `superbee@next` instead.
+
+After installation, ask your AI agent to run `superbee setup` (`superbee.cmd setup` when invoking
+the Windows shim explicitly). Setup walks the agent through Agent Skill, SessionStart hook, and MCP
+registration. It is read-only: it inspects your configuration and returns one safe next command at
+a time, so the agent performs any actual changes with your approval.
+
+The managed Agent Skill works in Claude Code, Codex, and OpenCode. OpenCode discovers Superbee from
+its documented Claude-compatible Skill path. It shares Claude Code's Skill bytes by default; if
+Claude Code is explicitly relocated, the installer manages the two documented host paths separately.
 
 Upgrading from the legacy `@holaxis/aslite` package or the retired marketplace plugin? Install
 `superbee` alongside it, have your agent run `superbee setup` to migrate the exact legacy

package/dist/publication-bridge.mjs

@@ -1153,7 +1153,7 @@ var require_omap = __commonJS({
     var _toString = Object.prototype.toString;
     function resolveYamlOmap(data) {
       if (data === null) return true;
-      var objectKeys = [], index, length, pair, pairKey, pairHasKey, object = data;
+      var objectKeys = {}, index, length, pair, pairKey, pairHasKey, object = data;
       for (index = 0, length = object.length; index < length; index += 1) {
         pair = object[index];
         pairHasKey = false;
@@ -1165,8 +1165,8 @@ var require_omap = __commonJS({
           }
         }
         if (!pairHasKey) return false;
-        if (objectKeys.indexOf(pairKey) === -1) objectKeys.push(pairKey);
-        else return false;
+        if (_hasOwnProperty.call(objectKeys, pairKey)) return false;
+        Object.defineProperty(objectKeys, pairKey, { value: true });
       }
       return true;
     }
@@ -1603,17 +1603,22 @@ var require_loader = __commonJS({
         state.result += _result;
       }
     }
+    function chargeMergeWork(state) {
+      state.totalMergeKeys += 1;
+      if (state.maxTotalMergeKeys !== -1 && state.totalMergeKeys > state.maxTotalMergeKeys) {
+        throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
+      }
+    }
     function mergeMappings(state, destination, source, overridableKeys) {
       var sourceKeys, key, index, quantity;
       if (!common.isObject(source)) {
         throwError(state, "cannot merge mappings; the provided source object is unacceptable");
       }
+      chargeMergeWork(state);
       sourceKeys = Object.keys(source);
       for (index = 0, quantity = sourceKeys.length; index < quantity; index += 1) {
         key = sourceKeys[index];
-        if (state.maxTotalMergeKeys !== -1 && ++state.totalMergeKeys > state.maxTotalMergeKeys) {
-          throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
-        }
+        chargeMergeWork(state);
         if (!_hasOwnProperty.call(destination, key)) {
           setProperty(destination, key, source[key]);
           overridableKeys[key] = true;
@@ -1642,6 +1647,9 @@ var require_loader = __commonJS({
       }
       if (keyTag === "tag:yaml.org,2002:merge") {
         if (Array.isArray(valueNode)) {
+          if (valueNode.length > 100) {
+            throwError(state, "abnormal merge sequence size");
+          }
           for (index = 0, quantity = valueNode.length; index < quantity; index += 1) {
             mergeMappings(state, _result, valueNode[index], overridableKeys);
           }
@@ -3582,6 +3590,13 @@ var MalformedDocumentError = class extends Error {
   }
 };
 function parseMarkdown(raw, context) {
+  if (/^---(?:\r?\n|$)/.test(raw)) {
+    const firstLineEnd = raw.indexOf("\n");
+    const afterOpening = firstLineEnd === -1 ? "" : raw.slice(firstLineEnd + 1);
+    if (!/^---\r?$/m.test(afterOpening)) {
+      throw new MalformedDocumentError(context, new Error("unterminated YAML frontmatter delimiter"));
+    }
+  }
   let parsed;
   try {
     parsed = (0, import_gray_matter.default)(raw, { engines: { yaml: yamlEngine } });
@@ -3591,16 +3606,20 @@ function parseMarkdown(raw, context) {
   const frontmatter2 = normalizeFrontmatter(parsed.data ?? {});
   return { frontmatter: frontmatter2, body: parsed.content };
 }
+function normalizeDocumentBodyForStorage(body) {
+  return body.endsWith("\n") ? body : `${body}
+`;
+}
 function stringifyWithData(data, body) {
   const engines2 = import_gray_matter.default.engines;
   const yaml3 = engines2.yaml.stringify(data).trim();
   const content = body ?? "";
   const newline = (value) => value.endsWith("\n") ? value : `${value}
 `;
-  if (yaml3 === "{}") return newline(content);
+  if (yaml3 === "{}") return normalizeDocumentBodyForStorage(content);
   return `---
 ${newline(yaml3)}---
-${newline(content)}`;
+${normalizeDocumentBodyForStorage(content)}`;
 }
 function stringifyDoc(frontmatter2, body) {
   return stringifyWithData(frontmatter2, body);
@@ -3885,6 +3904,33 @@ function processExists(pid) {
     return err.code !== "ESRCH";
   }
 }
+function staleLockQuarantinePath(lockPath, owner) {
+  const tokenHash = createHash("sha256").update(owner.token).digest("hex");
+  return `${lockPath}.stale-${tokenHash}`;
+}
+async function pathExists(candidate) {
+  try {
+    await fs.lstat(candidate);
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+async function quarantineStaleLock(lockPath, owner) {
+  if (owner.hostname !== hostname() || processExists(owner.pid)) return false;
+  const quarantinePath = staleLockQuarantinePath(lockPath, owner);
+  try {
+    await fs.rename(lockPath, quarantinePath);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") return false;
+    if (await pathExists(quarantinePath)) return false;
+    if (process.platform === "win32" && WINDOWS_DIRECTORY_CONTENTION_CODES.has(code ?? "")) return false;
+    throw err;
+  }
+}
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -3947,46 +3993,74 @@ async function selectLockRoot(options2) {
   await ensurePrivateLockRoot(lockRoot);
   return lockRoot;
 }
+var WINDOWS_DIRECTORY_CONTENTION_CODES = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
+async function classifyLockClaimFailure(error, lockPath) {
+  const code = error.code;
+  if (code === "EEXIST") return "contention";
+  if (process.platform !== "win32" || !WINDOWS_DIRECTORY_CONTENTION_CODES.has(code ?? "")) return "terminal";
+  try {
+    await fs.lstat(lockPath);
+    return "contention";
+  } catch (probeError) {
+    const probeCode = probeError.code;
+    return probeCode === "ENOENT" || probeCode === "ENOTDIR" ? "unwitnessed-windows-sharing-error" : "terminal";
+  }
+}
 async function claimLockPath(lockPath, owner, waitMs, pollMs) {
   const started = owner.created_at_ms;
+  let unwitnessedWindowsRetryUsed = false;
   while (true) {
     try {
       await fs.mkdir(lockPath, { mode: 448 });
-      try {
-        await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
-`, {
-          encoding: "utf8",
-          flag: "wx",
-          mode: 384
-        });
-      } catch (err) {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {
-        });
-        throw err;
+    } catch (err) {
+      const failure = await classifyLockClaimFailure(err, lockPath);
+      if (failure === "terminal") throw err;
+      if (failure === "unwitnessed-windows-sharing-error") {
+        if (unwitnessedWindowsRetryUsed) throw err;
+        unwitnessedWindowsRetryUsed = true;
+        continue;
+      } else {
+        unwitnessedWindowsRetryUsed = false;
       }
-      return async () => {
-        const current = await readOwner(lockPath);
-        if (current?.token !== owner.token) {
-          throw new FilesystemMutationLockError(
-            `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
-            { lockPath, owner: current, stale: false, malformed: current === null }
-          );
-        }
-        try {
-          await fs.rm(lockPath, { recursive: true, force: false });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          throw new FilesystemMutationLockError(
-            `mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`,
-            { lockPath, owner: current, stale: false, malformed: false }
-          );
-        }
-      };
+      let existingOwner = await readOwner(lockPath);
+      if (existingOwner !== null) {
+        if (await quarantineStaleLock(lockPath, existingOwner)) continue;
+        existingOwner = await readOwner(lockPath);
+      }
+      if (Date.now() - started >= waitMs) throw timeoutError(lockPath, existingOwner, owner.target);
+      await delay(pollMs);
+      continue;
+    }
+    try {
+      await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
+`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 384
+      });
     } catch (err) {
-      if (err.code !== "EEXIST") throw err;
+      await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {
+      });
+      throw err;
     }
-    if (Date.now() - started >= waitMs) throw timeoutError(lockPath, await readOwner(lockPath), owner.target);
-    await delay(pollMs);
+    return async () => {
+      const current = await readOwner(lockPath);
+      if (current?.token !== owner.token) {
+        throw new FilesystemMutationLockError(
+          `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
+          { lockPath, owner: current, stale: false, malformed: current === null }
+        );
+      }
+      try {
+        await fs.rm(lockPath, { recursive: true, force: false });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new FilesystemMutationLockError(
+          `mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`,
+          { lockPath, owner: current, stale: false, malformed: false }
+        );
+      }
+    };
   }
 }
 function newOwner(target) {
@@ -5038,6 +5112,10 @@ var VALID_FIELDS_KEYS = /* @__PURE__ */ new Set([
   "descriptions"
 ]);
 var MISPLACED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["enum", "enums", "values", "constraints"]);
+var CLAIM_COORDINATE_KEYS = [
+  ["owner_field", "ownerField"],
+  ["state_field", "stateField"]
+];
 function parseConventionDoc(doc) {
   const fm = doc.frontmatter;
   const governs = typeof fm.governs === "string" ? fm.governs.trim() : "";
@@ -5346,6 +5424,35 @@ function parseConventionDoc(doc) {
       if (Object.keys(parsed).length > 0) expectsInbound = parsed;
     }
   }
+  const claimSource = fm.claim;
+  let claim;
+  if (claimSource !== void 0) {
+    if (!isPlainObject(claimSource)) {
+      warnings.push({
+        code: "KIND_CONVENTION_BAD_SHAPE",
+        message: `kind convention '${doc.id}' has a non-map 'claim' key (${describeShape(claimSource)}; expected a map declaring 'owner_field' and/or 'state_field'); ignoring it.`,
+        field: "claim",
+        severity: "warning"
+      });
+    } else {
+      const parsed = {};
+      for (const [key, target] of CLAIM_COORDINATE_KEYS) {
+        const declared = claimSource[key];
+        if (declared === void 0) continue;
+        if (!isScalar(declared) || String(declared).trim() === "") {
+          warnings.push({
+            code: "KIND_CONVENTION_BAD_MEMBER",
+            message: `kind convention '${doc.id}' has a malformed 'claim.${key}' (${describeShape(declared)}; expected a declared field name); skipping it.`,
+            field: `claim.${key}`,
+            severity: "warning"
+          });
+          continue;
+        }
+        parsed[target] = String(declared).trim();
+      }
+      if (parsed.ownerField !== void 0 || parsed.stateField !== void 0) claim = parsed;
+    }
+  }
   const sections = Array.isArray(fm.sections) ? fm.sections.filter((s) => typeof s === "string" && s.trim() !== "") : void 0;
   const title = typeof fm.title === "string" && fm.title.trim() !== "" ? fm.title.trim() : governs;
   let description;
@@ -5378,6 +5485,7 @@ function parseConventionDoc(doc) {
   if (sections && sections.length > 0) kind.sections = sections;
   if (freshnessHorizon !== void 0) kind.freshnessHorizon = freshnessHorizon;
   if (browseCollapsed !== void 0) kind.browseCollapsed = browseCollapsed;
+  if (claim !== void 0) kind.claim = claim;
   return {
     ok: true,
     kind,