@jeremiewerner/motto 0.0.3

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@jeremiewerner/motto",
+  "version": "0.0.3",
+  "type": "module",
+  "description": "Framework for authoring, validating, and packaging Claude Code Agent Skills",
+  "author": "Jérémie Werner",
+  "license": "MIT",
+  "repository": "github:jeremiewerner/motto",
+  "homepage": "https://github.com/jeremiewerner/motto",
+  "keywords": ["claude", "agent-skills", "claude-code", "cli"],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "motto": "./bin/motto.js"
+  },
+  "files": ["bin/", "src/", "dist/public/"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "prepare": "husky",
+    "test": "node --test",
+    "prepublishOnly": "node bin/motto.js build",
+    "version": "node -e \"const fs=require('fs'); let c=fs.readFileSync('motto.yaml','utf8'); c=c.replace(/^version: .+$/m,'version: \\\"'+process.env.npm_new_version+'\\\"'); fs.writeFileSync('motto.yaml',c);\" && git add motto.yaml"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7"
+  }
+}

package/src/build.js

@@ -0,0 +1,214 @@
+/**
+ * Motto build orchestrator.
+ *
+ * Exports a single async function `buildProject(projectRoot)` that turns a
+ * lint-passing source tree into self-contained, distributable Claude Code
+ * plugin folders under `dist/`.
+ *
+ * Load-bearing order (D3-02, extended per RESEARCH):
+ *   1. lintProject gate — on failure, return errors without touching dist/
+ *   2. Load config + skill data from disk (Option A — re-read, D3-01 reuse)
+ *   3. Pre-pack checks — collision (D3-07) + private-contradiction (D3-12)
+ *   4. Wipe dist/ — ONLY after ALL checks pass (D3-03)
+ *   5. Pack skills — verbatim copy (verbatimSymlinks:true) + shared-ref bundling
+ *   6. Emit plugin.json per bucket (D3-13)
+ *   7. Return result
+ *
+ * Return shape:
+ *   { ok, outDir, errors, skillCount, bucketCount }
+ *
+ * Exit code: callers set process.exitCode (never process.exit(1)) to avoid
+ * truncating buffered stdout (Phase 2 Pitfall 7).
+ */
+
+import { readFile, readdir, rm, mkdir, cp, writeFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { lintProject } from './lint.js';
+import { loadConfig } from './config.js';
+import { parseFrontmatter } from './frontmatter.js';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover skill directory names under `skillsDir` (one level deep, sorted).
+ * Returns an empty array when skillsDir is missing (ENOENT).
+ *
+ * @param {string} skillsDir
+ * @returns {Promise<string[]>}
+ */
+async function discoverSkillNames(skillsDir) {
+  let entries;
+  try {
+    entries = await readdir(skillsDir, { withFileTypes: true });
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+  return entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((e) => e.name);
+}
+
+/**
+ * Read the frontmatter fields needed for packaging: audience + shared_references.
+ * Lint has already validated this SKILL.md, so we trust the data shape.
+ *
+ * @param {string} skillsDir
+ * @param {string} skillName
+ * @returns {Promise<{ audience: string, sharedRefs: string[] }>}
+ */
+async function loadSkillData(skillsDir, skillName) {
+  const text = await readFile(join(skillsDir, skillName, 'SKILL.md'), 'utf8');
+  const { data } = parseFrontmatter(text);
+  return {
+    audience: typeof data.audience === 'string' ? data.audience : 'public',
+    sharedRefs: Array.isArray(data.shared_references) ? data.shared_references : [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// buildProject — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a Motto project rooted at `projectRoot`.
+ *
+ * @param {string} projectRoot - absolute path to the project root
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   outDir: string|null,
+ *   errors: Array<{skill: string, message: string}>,
+ *   skillCount: number,
+ *   bucketCount: number
+ * }>}
+ */
+export async function buildProject(projectRoot) {
+  // ── STEP 1: Lint gate (D3-01, D3-02) ──────────────────────────────────────
+  // The gate runs BEFORE any mutation. A failing lint means zero writes to dist/.
+  const lintResult = await lintProject(projectRoot);
+  if (!lintResult.ok) {
+    return { ok: false, outDir: null, errors: lintResult.errors, skillCount: 0, bucketCount: 0 };
+  }
+
+  // ── STEP 2: Load config + skill data (Option A — re-read, RESEARCH §Reuse) ─
+  const configText = await readFile(join(projectRoot, 'motto.yaml'), 'utf8');
+  const { config } = loadConfig(configText); // lint passed → config is valid
+
+  const skillsDir = join(projectRoot, 'skills');
+  const skillNames = await discoverSkillNames(skillsDir);
+
+  const skills = [];
+  for (const name of skillNames) {
+    const skillData = await loadSkillData(skillsDir, name);
+    skills.push({ name, ...skillData });
+  }
+
+  // ── STEP 3: Pre-pack checks (D3-07, D3-12) — run BEFORE the wipe ──────────
+  // Task 2 adds collision and private-contradiction checks here.
+  // The buildErrors array is checked after all skills are scanned so that
+  // ALL errors are reported in a single pass (collect-don't-throw pattern).
+  const buildErrors = [];
+
+  // D3-07: Collision check — declared shared_ref vs local skill references/<ref>.md
+  for (const skill of skills) {
+    for (const ref of skill.sharedRefs) {
+      try {
+        await stat(join(skillsDir, skill.name, 'references', ref + '.md'));
+        // If stat succeeds, the file exists in the SOURCE tree → collision
+        buildErrors.push({
+          skill: skill.name,
+          message: `shared reference '${ref}' collides with a local references/${ref}.md`,
+        });
+      } catch (e) {
+        if (e.code !== 'ENOENT') throw e; // unexpected I/O error — propagate
+        // ENOENT = no collision — continue
+      }
+    }
+  }
+
+  // D3-12: Private-contradiction check
+  for (const skill of skills) {
+    if (skill.audience === 'private' && !config.plugins?.private) {
+      buildErrors.push({
+        skill: skill.name,
+        message: 'audience private but plugins.private not set in motto.yaml',
+      });
+    }
+  }
+
+  // Return early on any pre-pack errors — BEFORE the wipe (D3-02 extended)
+  if (buildErrors.length > 0) {
+    return { ok: false, outDir: null, errors: buildErrors, skillCount: 0, bucketCount: 0 };
+  }
+
+  // ── STEP 4: Wipe dist/ (D3-03) — only after ALL checks pass ──────────────
+  const distDir = join(projectRoot, 'dist');
+  await rm(distDir, { recursive: true, force: true }); // force:true silences ENOENT
+
+  // ── STEP 5: Pack each skill, routed by audience (D3-09) ─────────────────
+  // public is always in bucketsUsed (D3-10); private is added when a skill
+  // declares audience:private (and plugins.private is guaranteed set by Step 3).
+  const bucketsUsed = new Set(['public']);
+
+  for (const skill of skills) {
+    const audience = skill.audience; // 'public' | 'private' (validated by lint)
+    const dstSkillDir = join(distDir, audience, skill.name);
+
+    // Verbatim copy — verbatimSymlinks:true is MANDATORY (RESEARCH CRITICAL).
+    // Default and dereference:false silently rewrite relative symlinks to
+    // absolute paths pointing into the source tree on macOS (Node 24 verified).
+    await cp(join(skillsDir, skill.name), dstSkillDir, {
+      recursive: true,
+      verbatimSymlinks: true,
+    });
+
+    // Bundle declared shared_references (D3-06)
+    if (skill.sharedRefs.length > 0) {
+      const outRefsDir = join(dstSkillDir, 'references');
+      // Idempotent guard: creates references/ even if the skill had no local
+      // references/ dir — cp would not have created it (RESEARCH Pitfall 3)
+      await mkdir(outRefsDir, { recursive: true });
+      for (const ref of skill.sharedRefs) {
+        await cp(
+          join(projectRoot, 'shared', 'references', ref + '.md'),
+          join(outRefsDir, ref + '.md'),
+        );
+      }
+    }
+
+    if (audience === 'private') bucketsUsed.add('private');
+  }
+
+  // ── STEP 6: Emit plugin.json for each bucket used (D3-13) ────────────────
+  // public bucket: always emitted (D3-10); private bucket: emitted only when
+  // bucketsUsed has 'private' (D3-11 — the D3-12 check above ensures this only
+  // happens when plugins.private is set, so plugins.private is always present here).
+  const plugins = config.plugins ?? {};
+
+  for (const audience of bucketsUsed) {
+    const pluginName = audience === 'public' ? plugins.public : plugins.private;
+    const pluginDir = join(distDir, audience, '.claude-plugin');
+    await mkdir(pluginDir, { recursive: true });
+    await writeFile(
+      join(pluginDir, 'plugin.json'),
+      JSON.stringify(
+        { name: pluginName, version: config.version, description: config.description },
+        null,
+        2,
+      ) + '\n',
+    );
+  }
+
+  // ── STEP 7: Return result ─────────────────────────────────────────────────
+  return {
+    ok: true,
+    outDir: distDir,
+    errors: [],
+    skillCount: skills.length,
+    bucketCount: bucketsUsed.size,
+  };
+}

package/src/config.js

@@ -0,0 +1,105 @@
+/**
+ * Motto project-config validator.
+ *
+ * Pure validator — no filesystem I/O, never throws (D-01). All validation failures
+ * surface through the returned errors[].
+ *
+ * Exports:
+ *   - loadConfig(text: string) -> { config: object, errors: Array<{ message: string }> }
+ */
+
+import { parseDocument } from "yaml";
+import { safeToJS } from "./frontmatter.js";
+// src/schema.js is the sole source of NAME_KEBAB (REVIEW-11, D-16).
+// schema.js has no imports, so there is no circular dependency.
+import { NAME_KEBAB } from "./schema.js";
+
+// Re-export so config.js's public surface is preserved — dogfood DOG-04 imports
+// NAME_KEBAB from config.js to assert reference identity with schema.js.
+export { NAME_KEBAB };
+
+/**
+ * Parse and validate a raw motto.yaml text string.
+ *
+ * Error-aggregation model:
+ *   - YAML parse errors are mapped from doc.errors[] into returned errors[] (D-02, D-18).
+ *   - ALL missing required fields are collected together — no short-circuit (D-15, CONF-01).
+ *   - Plugin names are validated against NAME_KEBAB only when the field is present (D-16).
+ *   - plugins.private is optional — its ABSENCE is never an error (CONF-03, D-17).
+ *
+ * This function performs NO filesystem I/O. Phase 2 wires in the file read; this
+ * function owns only the parse + validation logic.
+ *
+ * @param {string} text — raw motto.yaml content (a string, not a path)
+ * @returns {{ config: object, errors: Array<{ message: string }> }}
+ *   `config` — the parsed JS object (possibly partial on parse error; {} when null/empty).
+ *   `errors` — empty array when the config is fully valid; one object per error otherwise.
+ */
+export function loadConfig(text) {
+  const errors = [];
+  let config = {};
+
+  // ── YAML PARSE (D-02, D-18) ────────────────────────────────────────────────
+  // parseDocument accumulates errors in doc.errors[] without throwing (D-01).
+  let doc;
+  try {
+    doc = parseDocument(text);
+  } catch (e) {
+    // Defensive: parseDocument is specified not to throw, but D-01 requires we
+    // never throw regardless of input. Catch and surface any unexpected exception.
+    errors.push({ message: String(e.message || e) });
+    return { config, errors };
+  }
+
+  // Map each YAML parse error into the returned errors[] (D-18).
+  for (const yamlErr of doc.errors) {
+    errors.push({ message: yamlErr.message || String(yamlErr) });
+  }
+
+  // Resolve to a plain JS object. safeToJS guards against toJS() throwing on an
+  // unresolved alias (e.g. `name: *foo` — D-01, REVIEW-03). src/schema.js is
+  // the sole source of NAME_KEBAB (REVIEW-11); safeToJS is the sole helper (REVIEW-02/03).
+  const { value, threw, message } = safeToJS(doc);
+  if (threw) {
+    errors.push({ message });
+  }
+  config = value != null && typeof value === "object" ? value : {};
+
+  // ── REQUIRED FIELDS (CONF-01, D-15) ───────────────────────────────────────
+  // Collect ALL missing required fields together — no short-circuit (D-15).
+  if (!config.name) {
+    errors.push({ message: "missing name" });
+  }
+  if (!config.version) {
+    errors.push({ message: "missing version" });
+  }
+  if (!config.description) {
+    errors.push({ message: "missing description" });
+  }
+
+  // ── PLUGIN NAMES (CONF-02, D-16) ──────────────────────────────────────────
+  const plugins =
+    config.plugins != null && typeof config.plugins === "object"
+      ? config.plugins
+      : {};
+
+  // plugins.public is required (CONF-01). Validate its format only when present.
+  if (!plugins.public) {
+    errors.push({ message: "missing plugins.public" });
+  } else if (!NAME_KEBAB.test(plugins.public)) {
+    errors.push({
+      message: `plugins.public "${plugins.public}" must be letter-start kebab-case (/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/)`,
+    });
+  }
+
+  // plugins.private is OPTIONAL (CONF-03, D-17). Only validate format when present.
+  if (plugins.private != null) {
+    if (!NAME_KEBAB.test(plugins.private)) {
+      errors.push({
+        message: `plugins.private "${plugins.private}" must be letter-start kebab-case (/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/)`,
+      });
+    }
+  }
+
+  return { config, errors };
+}

package/src/frontmatter.js

@@ -0,0 +1,134 @@
+import YAML from "yaml";
+
+/**
+ * Safely convert a YAML Document node to a plain JS value without throwing.
+ *
+ * YAML's doc.toJS() throws a ReferenceError when the document contains an
+ * unresolved alias (e.g. `description: *foo` where anchor `foo` is not defined).
+ * The parsers in this project must NEVER throw (D-01, REVIEW-02, REVIEW-03);
+ * this helper centralises the guard so neither parseFrontmatter nor loadConfig
+ * needs its own try/catch.
+ *
+ * @param {import('yaml').Document} doc
+ * @returns {{ value: any, threw: boolean, message: string|null }}
+ */
+export function safeToJS(doc) {
+  try {
+    return { value: doc.toJS(), threw: false, message: null };
+  } catch (e) {
+    return { value: null, threw: true, message: String(e?.message ?? e) };
+  }
+}
+
+/**
+ * Split a SKILL.md into frontmatter `data` + Markdown `body`, normalizing the
+ * input first, and report every structural malformation through a uniform
+ * `errors[]` array. NEVER throws (D-01, D-03): every failure path returns via
+ * `errors[]`.
+ *
+ * @param {string} text - raw SKILL.md contents
+ * @returns {{ data: object, body: string, errors: Array<{ message: string }> }}
+ */
+export function parseFrontmatter(text) {
+  const errors = [];
+
+  // (1) NORMALIZE FIRST (D-04, D-05): strip a single leading UTF-8 BOM, then
+  // CRLF -> LF. Nothing else — no lone-CR handling, no trailing-whitespace
+  // munging. All downstream delimiter logic stays LF-anchored.
+  let normalized = text;
+  if (normalized.charCodeAt(0) === 0xfeff) {
+    normalized = normalized.slice(1);
+  }
+  normalized = normalized.replace(/\r\n/g, "\n");
+
+  const lines = normalized.split("\n");
+
+  // (2) OPENING DELIMITER: normalized text must begin with a bare "---" line.
+  if (lines[0] !== "---") {
+    errors.push({
+      message: "missing frontmatter: file must begin with a '--- ... ---' block",
+    });
+    return { data: {}, body: normalized, errors };
+  }
+
+  // (3) CLOSING DELIMITER: the first subsequent bare "---" line is the close.
+  let close = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      close = i;
+      break;
+    }
+  }
+  if (close === -1) {
+    errors.push({
+      message: "unterminated frontmatter: no closing '---' delimiter found",
+    });
+    return { data: {}, body: normalized, errors };
+  }
+
+  const block = lines.slice(1, close).join("\n");
+  const body = lines.slice(close + 1).join("\n");
+
+  // (4) STRAY DETECTION (PARSE-04, D-06): a valid file has exactly one opening
+  // and one closing bare "---". If the region immediately following the close —
+  // up to the next bare "---" — has a node shape consistent with a leaked YAML
+  // mapping, it is leaked frontmatter split by a stray delimiter, not body.
+  //
+  // Node-shape detection (REVIEW-05): instead of calling toJS() (which throws on
+  // unresolved aliases such as `key: *foo` or `**Role:**` alias nodes — D-01),
+  // we inspect the PARSED NODE TREE directly. The region is treated as a leaked
+  // mapping iff:
+  //   - regionDoc.errors.length === 0  (clean parse — not a syntax error)
+  //   - YAML.isMap(regionDoc.contents) (top-level node is a mapping, not a scalar)
+  //   - regionDoc.contents.items.length > 0 (at least one key-value pair present)
+  //
+  // This catches `key: *foo` (alias value — errors.length 0, isMap true) while
+  // leaving body text (Scalar) and horizontal rules (Scalar/null) unflagged (B7).
+  // The B8 region ("**Role:** Guide.\n\n") resolves to an Alias node with
+  // errors.length > 0, so it stays correctly unflagged (B8).
+  //
+  // Zero unguarded toJS() calls remain in this file; safeToJS() owns the guard
+  // for the main block parse (step 5b above).
+  let nextDelim = -1;
+  for (let i = close + 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      nextDelim = i;
+      break;
+    }
+  }
+  if (nextDelim !== -1) {
+    const region = lines.slice(close + 1, nextDelim).join("\n");
+    const regionDoc = YAML.parseDocument(region);
+    const isLeakedMapping =
+      regionDoc.errors.length === 0 &&
+      YAML.isMap(regionDoc.contents) &&
+      regionDoc.contents.items.length > 0;
+    if (isLeakedMapping) {
+      errors.push({
+        message:
+          "stray '---' delimiter in frontmatter: the block must contain exactly one closing '---'",
+      });
+    }
+  }
+
+  // (5) PARSE THE BLOCK with YAML.parseDocument (NOT YAML.parse — D-02). Map
+  // every parse error into the returned errors[] (D-02, PARSE-03). An empty
+  // block yields data {} with NO parse error (D-07). toJS() is deferred to (5b).
+  const doc = YAML.parseDocument(block);
+  for (const e of doc.errors) {
+    errors.push({ message: e.message });
+  }
+
+  // (5b) RESOLVE to plain JS. safeToJS guards against toJS() throwing on an
+  // unresolved alias (e.g. `description: *foo` — D-01, REVIEW-02).
+  const { value, threw, message } = safeToJS(doc);
+  if (threw) {
+    errors.push({ message });
+  }
+  let data = value;
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    data = {};
+  }
+
+  return { data, body, errors };
+}