@rckflr/llms-skills 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to the [`@rckflr/llms-skills`](https://www.npmjs.com/package/@rckflr/llms-skills)
+package. Format based on [Keep a Changelog](https://keepachangelog.com/); dates
+are the npm publish dates.
+
+## [Unreleased] — 0.3.0
+
+### Added
+- **`--scope <name>` on `memory`** (Executable Skills v0.5 §2.5, resolves
+  core RFC v0.10 Open Question 6). Declares the project namespace for
+  multi-project origins: the manifest's `memory` block and every generated
+  `published` entry carry `scope`, and `publish` renders it as the **last**
+  key of both the skill lines and the `skills-memory` line
+  (`"scope":"kdd"`). Runtimes (mcpwasm ≥ 0.6.0) expose the tools as
+  `<scope>__<toolName>` and bind each scope's memory to its own snapshot.
+  Pattern `^[a-z][a-z0-9_-]*$`; invalid values fail fast. Re-running
+  `memory` with a different `--scope` (or none) refreshes the manifest
+  entries idempotently.
+- `validate` understands scopes: accepts multiple `skills-memory` lines when
+  each carries a distinct `scope` (at most one unscoped), and reports invalid
+  `scope` values and duplicated scopes as errors.
+- New test part: scoped fixture end-to-end (manifest wiring, key order,
+  validate, and **byte-identity with `scripts/generate.py`** on scoped
+  output — the mirror contract now covers scopes).
+
+### Changed
+- `scripts/generate.py` mirrored: manifest entries and the `memory` block
+  accept `scope` and render it identically (byte-identity enforced by
+  `cli/test.mjs` Part 6). No `scope` anywhere ⇒ output identical to 0.2.1.
+
+## [0.2.1] — 2026-07-10
+
+### Fixed
+- **Frontmatter values quoted with single quotes** (`type: 'Concept'`) are now
+  unquoted correctly: one *matching* pair of quotes (double or single) is
+  stripped. Found with a real OKF bundle (KDD) whose frontmatter uses single
+  quotes; before this fix the quotes leaked into concept `type`/`title`.
+  Mirrored in `scripts/generate.py` (`parse_yaml_frontmatter`) — byte-identity
+  between both generators re-verified.
+
+## [0.2.0] — 2026-07-10
+
+### Added
+- **`memory <bundle-dir>` — the RAG-OKF builder.** Turns a directory of
+  [OKF 0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+  concepts (`*.md` with `type`/`title` frontmatter; `index.md`/`log.md`
+  reserved) into a serverless RAG:
+  - a **byte-deterministic** BM25 snapshot (`minimemory-okf-v1`), pinned by
+    `snapshot_sha256` in the `skills-memory` line. Determinism requires
+    canonicalization: minimemory's export order comes from a Rust HashMap and
+    varies run to run — chunks are sorted by id and re-serialized, which is
+    what makes `--check`/CI content-addressing possible at all;
+  - three generated executable skills: `search_knowledge` (a **universal
+    template** — identical bytes for every publisher, so its `tool_sha256` is
+    a stable ecosystem-wide constant: audit once, attest once), `get_concept`
+    and `list_concepts` (concept metadata embedded at build time,
+    content-addressed);
+  - manifest wiring (`memory` block + `published` entries) so a plain
+    `publish` emits everything, and a `.gitattributes` pin
+    (`skills-index.snapshot -text`) so git CRLF conversion can never break
+    the published hash.
+  - `memory <bundle> --check` is the CI drift guard. Consumers need nothing
+    new: `@rckflr/mcpwasm` ≥ 0.4.0 verifies the snapshot and injects
+    `host.memorySearch` on both runtimes (covered by a real end-to-end test
+    against the published mcpwasm tarball).
+
+### Changed
+- `@rckflr/minimemory` (~630 KB wasm BM25 engine) added as an
+  **optionalDependency**: installed by default, lazily imported by `memory`;
+  if omitted, `memory` fails with a clear message and every other command
+  works exactly as before (the CLI keeps zero hard dependencies).
+
+## [0.1.0] — 2026-07-10
+
+### Added
+- Initial release: one-command publisher CLI for the llms.txt Skills
+  standard — `init` (scaffold SKILL.md + optional tool.js + manifest),
+  `publish [--check]` (sha256, `## Skills` into llms.txt,
+  `.well-known/agent-skills/index.json`, ed25519 signing), `validate`
+  (llms.txt + skills, local path or URL), `keygen`. Zero dependencies
+  (hashing and ed25519 via `node:crypto`); output **byte-identical** to the
+  reference Python generator (`scripts/generate.py`), enforced by
+  `cli/test.mjs` in CI.

package/README.md

@@ -67,6 +67,21 @@ What it generates: a **byte-deterministic** BM25 snapshot (canonicalized, so
 content-addressed). It also pins the snapshot as `-text` in `.gitattributes`
 so git's CRLF conversion can never break the published hash.
 
+**Multi-project origins (scopes).** Publishing several projects on one origin
+(e.g. a GitHub Pages root)? Add `--scope <name>` (pattern
+`^[a-z][a-z0-9_-]*$`, Executable Skills v0.5 §2.5):
+
+```bash
+npx @rckflr/llms-skills memory ./knowledge --scope kdd
+```
+
+The manifest and the rendered lines carry `"scope":"kdd"`; runtimes
+(mcpwasm ≥ 0.6.0) expose the tools as `kdd__search_knowledge` etc. and bind
+each scope's memory to its own snapshot — no name collisions, one
+`skills-memory` line per scope. Published bytes and hashes are untouched
+(the rename is runtime-side), so `search_knowledge` stays the universal
+template.
+
 Consumers need nothing new: `npx -y @rckflr/mcpwasm <origin>` (>= 0.4.0)
 verifies the snapshot and injects `host.memorySearch` on both runtimes.
 `memory <bundle> --check` is the CI guard. The BM25 engine

package/bin/llms-skills.mjs

@@ -29,7 +29,7 @@ const USAGE = `llms-skills — publisher CLI for the llms.txt Skills standard
 
 Usage:
   llms-skills init <name> [--tool] [--root <dir>]   scaffold SKILL.md (+ tool.js) + manifest entry
-  llms-skills memory <bundle-dir> [--check] [--root <dir>] [--license <spdx>]
+  llms-skills memory <bundle-dir> [--check] [--root <dir>] [--license <spdx>] [--scope <name>]
                                                     OKF bundle -> BM25 snapshot + knowledge skills (RAG)
   llms-skills publish [--check] [--manifest <p>] [--root <dir>]   generate llms.txt ## Skills + index.json
   llms-skills validate <src> [--strict]             validate an llms.txt (path or URL)
@@ -125,7 +125,7 @@ async function cmdMemory() {
     : { section_intro: "Remote Agent Skills published by this domain.", published: [] };
 
   const { targets, warnings, manifest: newManifest, snapshotSha, conceptCount } =
-    await buildMemoryTargets({ root, bundleDir, manifest, license: flag("--license") });
+    await buildMemoryTargets({ root, bundleDir, manifest, license: flag("--license"), scope: flag("--scope") });
   for (const w of warnings) console.error(`[warn] ${w}`);
 
   const rel = (p) => (relative(root, p) || p).replaceAll("\\", "/");

package/lib/core.mjs

@@ -30,13 +30,25 @@ export function parseFrontmatter(text) {
   const result = {};
   for (const line of body.split(/\r?\n/)) {
     const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/);
-    if (m) result[m[1]] = m[2].trim().replace(/^"|"$/g, "");
+    if (m) {
+      let v = m[2].trim();
+      // strip one MATCHING pair of quotes (double or single) — real-world YAML
+      // frontmatter uses both (e.g. type: 'Concept'), and stripping only one
+      // style leaves quote characters inside the value.
+      if (v.length >= 2 && ((v[0] === '"' && v[v.length - 1] === '"') || (v[0] === "'" && v[v.length - 1] === "'"))) {
+        v = v.slice(1, -1);
+      }
+      result[m[1]] = v;
+    }
   }
   return result;
 }
 
 const REQUIRED_FRONTMATTER = ["name", "description", "version", "license"];
 
+// Executable Skills v0.5 SS2.5: namespace declarativo para origins multi-proyecto.
+const SCOPE_RE = /^[a-z][a-z0-9_-]*$/;
+
 // ---- load skills from a manifest (mirrors generate.py load_skills) ----
 export function loadSkills(manifest, repoRoot) {
   const skills = [];
@@ -55,10 +67,14 @@ export function loadSkills(manifest, repoRoot) {
       toolUrl = entry.tool_url;
       toolSha256 = sha256NormalizedFile(toolPath);
     }
+    if (entry.scope !== undefined && !SCOPE_RE.test(String(entry.scope))) {
+      throw new Error(`${entry.path}: invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)`);
+    }
     skills.push({
       name: fm.name, description: fm.description, version: fm.version, license: fm.license,
       homepage: fm.homepage || null, url: entry.url, summary: entry.summary,
       sha256: sha256NormalizedFile(path), path, toolUrl, toolSha256,
+      scope: entry.scope !== undefined ? String(entry.scope) : null,
     });
   }
   return skills;
@@ -72,7 +88,14 @@ export function loadMemory(manifest, repoRoot) {
   }
   const snapshotPath = join(repoRoot, memory.snapshot_path);
   if (!existsSync(snapshotPath)) throw new Error(`snapshot not found: ${memory.snapshot_path}`);
-  return { snapshot_url: memory.snapshot_url, format: memory.format, snapshot_sha256: sha256NormalizedFile(snapshotPath) };
+  if (memory.scope !== undefined && !SCOPE_RE.test(String(memory.scope))) {
+    throw new Error("manifest.memory: invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)");
+  }
+  return {
+    snapshot_url: memory.snapshot_url, format: memory.format,
+    snapshot_sha256: sha256NormalizedFile(snapshotPath),
+    scope: memory.scope !== undefined ? String(memory.scope) : null,
+  };
 }
 
 // ---- render: ## Skills section (compact JSON, exact key order of generate.py) ----
@@ -81,6 +104,7 @@ export function renderSkillsSection(manifest, skills) {
   for (const s of skills) {
     const meta = { version: s.version, license: s.license, sha256: s.sha256 };
     if (s.toolUrl && s.toolSha256) { meta.tool = s.toolUrl; meta.tool_sha256 = s.toolSha256; }
+    if (s.scope) meta.scope = s.scope;
     lines.push(`- [${s.name}](${s.url}): ${s.summary} <!-- skill: ${JSON.stringify(meta)} -->`);
   }
   return lines.join("\n") + "\n";
@@ -89,6 +113,7 @@ export function renderSkillsSection(manifest, skills) {
 export function renderSkillsMemoryLine(memory) {
   if (!memory) return "";
   const meta = { snapshot: memory.snapshot_url, snapshot_sha256: memory.snapshot_sha256, format: memory.format };
+  if (memory.scope) meta.scope = memory.scope;
   return `<!-- skills-memory: ${JSON.stringify(meta)} -->\n\n`;
 }
 
@@ -182,9 +207,20 @@ export function validateLlmsTxt(source, text) {
   const err = (message, line = "") => errors.push({ message, line });
   const warn = (message, line = "") => warnings.push({ message, line });
 
-  // origin memory line (optional)
-  const memMatch = text.split(/\r?\n/).map((l) => l.trim().match(MEMORY_CAPTURE_RE)).find(Boolean);
-  if (memMatch) validateMemory(memMatch[1], source, err, warn);
+  // origin memory lines (optional; Executable Skills v0.5 SS2.5: one per
+  // scope, at most one without scope)
+  const memScopes = [];
+  for (const l of text.split(/\r?\n/)) {
+    const memMatch = l.trim().match(MEMORY_CAPTURE_RE);
+    if (!memMatch) continue;
+    const scopeKey = validateMemory(memMatch[1], source, err, warn);
+    if (scopeKey === undefined) continue; // JSON invalido, ya reportado
+    if (memScopes.includes(scopeKey)) {
+      err(scopeKey === ""
+        ? "skills-memory: more than one line without 'scope' (at most one allowed)"
+        : `skills-memory: duplicate line for scope '${scopeKey}'`);
+    } else memScopes.push(scopeKey);
+  }
 
   // find ## Skills section
   const lines = text.split(/\r?\n/);
@@ -229,6 +265,8 @@ export function validateLlmsTxt(source, text) {
         if (hasToolSha && !hasTool) err("'tool_sha256' declared without 'tool' (both required together)", raw.slice(0, 80));
         if (hasToolSha && !/^[a-fA-F0-9]{64}$/.test(String(metaParsed.tool_sha256)))
           err("Invalid tool_sha256 (must be 64 hex chars)", raw.slice(0, 80));
+        if ("scope" in metaParsed && !SCOPE_RE.test(String(metaParsed.scope)))
+          err("Invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)", raw.slice(0, 80));
       } catch (e) { err(`Invalid metadata JSON: ${e.message}`, raw.slice(0, 80)); }
     }
     const resolved = resolveSkillPath(url, source);
@@ -263,12 +301,15 @@ const MEMORY_CAPTURE_RE = /^<!--\s*skills-memory:\s*(.*?)\s*-->\s*$/;
 function validateMemory(memJson, source, err, warn) {
   let meta;
   try { meta = JSON.parse(memJson); }
-  catch (e) { err(`skills-memory: invalid JSON: ${e.message}`); return; }
+  catch (e) { err(`skills-memory: invalid JSON: ${e.message}`); return undefined; }
+  const scopeKey = meta.scope === undefined ? "" : String(meta.scope);
+  if (meta.scope !== undefined && !SCOPE_RE.test(String(meta.scope)))
+    err(`skills-memory: invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)`);
   let ok = true;
   for (const key of ["snapshot", "snapshot_sha256", "format"]) {
     if (typeof meta[key] !== "string") { err(`skills-memory: missing or invalid '${key}' (must be string)`); ok = false; }
   }
-  if (!ok) return;
+  if (!ok) return scopeKey;
   if (!/^[a-fA-F0-9]{64}$/.test(meta.snapshot_sha256)) err("skills-memory: invalid snapshot_sha256 (must be 64 hex chars)");
   if (meta.format !== "minimemory-okf-v1") warn(`skills-memory: format '${meta.format}' is not the only one recognized today (minimemory-okf-v1)`);
   const resolved = resolveSkillPath(meta.snapshot, source);
@@ -279,4 +320,5 @@ function validateMemory(memJson, source, err, warn) {
       if (actual !== meta.snapshot_sha256) err(`skills-memory: snapshot_sha256 mismatch: declared ${meta.snapshot_sha256}, actual ${actual}`);
     }
   }
+  return scopeKey;
 }

package/lib/memory.mjs

@@ -192,7 +192,11 @@ runtime executes it verbatim in a sandbox.
 // ---- orchestrator --------------------------------------------------------------
 // Builds everything under `root`. Returns { targets, warnings, snapshotSha, manifest }
 // where targets is [path, content] pairs (the caller writes or checks them).
-export async function buildMemoryTargets({ root, bundleDir, manifest, license }) {
+export async function buildMemoryTargets({ root, bundleDir, manifest, license, scope }) {
+  // Executable Skills v0.5 SS2.5: namespace declarativo para origins multi-proyecto.
+  if (scope !== undefined && scope !== null && !/^[a-z][a-z0-9_-]*$/.test(String(scope))) {
+    throw new Error("memory: invalid --scope (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)");
+  }
   const bundleRel = relative(root, bundleDir).replaceAll("\\", "/");
   if (bundleRel.startsWith("..")) {
     throw new Error("memory: the bundle must live inside the publisher root (it is served as static content)");
@@ -236,17 +240,26 @@ export async function buildMemoryTargets({ root, bundleDir, manifest, license })
     snapshot_url: "/skills-index.snapshot",
     format: SNAPSHOT_FORMAT,
   };
+  if (scope) newManifest.memory.scope = String(scope);
+  else delete newManifest.memory.scope;
   if (!Array.isArray(newManifest.published)) newManifest.published = [];
   for (const [name, , summary] of SKILLS) {
     const path = `skills/${name}/SKILL.md`;
-    if (!newManifest.published.some((e) => e && e.path === path)) {
-      newManifest.published.push({
+    const existing = newManifest.published.find((e) => e && e.path === path);
+    if (!existing) {
+      const entry = {
         path,
         url: `/skills/${name}/SKILL.md`,
         summary,
         tool: `skills/${name}/tool.js`,
         tool_url: `/skills/${name}/tool.js`,
-      });
+      };
+      if (scope) entry.scope = String(scope);
+      newManifest.published.push(entry);
+    } else if (scope) {
+      existing.scope = String(scope); // re-run con --scope: refresca el namespace
+    } else {
+      delete existing.scope; // re-run sin --scope: vuelve al default global
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rckflr/llms-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One-command publisher CLI for the llms.txt Skills standard: scaffold, hash, sign, and sync the ## Skills section + .well-known/agent-skills/index.json. Byte-identical to the reference Python generator; zero hard dependencies (BM25 knowledge snapshots via an optional wasm engine).",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "./memory": "./lib/memory.mjs"
   },
   "files": [
+    "CHANGELOG.md",
     "bin/llms-skills.mjs",
     "lib/core.mjs",
     "lib/memory.mjs",