release-skill 0.1.1

package/src/readme/contract.mjs

@@ -0,0 +1,297 @@
+/**
+ * README contract evaluation for release-skill.
+ *
+ * Validates that README files in a snapshot directory contain
+ * machine-readable HTML-comment markers covering capability, command,
+ * safety, and version requirements. Also extracts executable code
+ * blocks annotated with release-skill:exec metadata.
+ *
+ * Marker formats supported:
+ *   - Simple:       <!-- release-skill:<name> -->
+ *   - Categorized:  <!-- release-skill:<category>:<name> -->
+ * Exec metadata:    <!-- release-skill:exec fixture=<id> -->
+ *
+ * @module readme/contract
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Marker definitions
+// ---------------------------------------------------------------------------
+
+/**
+ * All known contract markers with their category and bilingual key.
+ * Markers may appear in READMEs as:
+ *   <!-- release-skill:<name> -->              (simple)
+ *   <!-- release-skill:<category>:<name> -->   (categorized)
+ */
+const MARKER_DEFS = [
+  // capability
+  { category: 'capability', name: 'safe-first-command', bilingualKey: 'safe-first-command', required: true },
+  { category: 'capability', name: 'supported-topology', bilingualKey: 'supported-topology', required: false },
+  { category: 'capability', name: 'unsupported-scope', bilingualKey: 'unsupported-scope', required: false },
+  { category: 'capability', name: 'external-write-boundary', bilingualKey: 'external-write-boundary', required: true },
+  // command
+  { category: 'command', name: 'release-help', bilingualKey: 'release-help', required: false },
+  { category: 'command', name: 'safe-assess-command', bilingualKey: 'safe-assess-command', required: false },
+  // safety
+  { category: 'safety', name: 'publish-authorization', bilingualKey: 'publish-authorization', required: false },
+  { category: 'safety', name: 'reconcile-guidance', bilingualKey: 'reconcile-guidance', required: false },
+  { category: 'safety', name: 'security', bilingualKey: 'security', required: false },
+  { category: 'safety', name: 'troubleshooting', bilingualKey: 'troubleshooting', required: false },
+  // version
+  { category: 'version', name: 'skill-list', bilingualKey: 'skill-list', required: false },
+  { category: 'version', name: 'version-info', bilingualKey: 'version-info', required: false },
+];
+
+/** Set of required marker names. */
+const REQUIRED_MARKER_NAMES = new Set(
+  MARKER_DEFS.filter((d) => d.required).map((d) => d.name),
+);
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract all marker names present in a README string.
+ *
+ * Handles both simple (release-skill:<name>) and categorized
+ * (release-skill:<category>:<name>) formats. The "exec" pseudo-marker
+ * is excluded since it serves a different purpose (executable metadata).
+ *
+ * @param {string} content
+ * @returns {Set<string>} Set of plain marker names.
+ */
+function extractMarkers(content) {
+  const regex = /<!--\s*release-skill:((?:[\w-]+:)*[\w-]+)\s*-->/g;
+  const found = new Set();
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const raw = match[1];
+    // Skip exec metadata pseudo-marker
+    if (raw.startsWith('exec')) continue;
+    // The canonical name is the last colon-separated segment.
+    const parts = raw.split(':');
+    const name = parts[parts.length - 1];
+    found.add(name);
+  }
+  return found;
+}
+
+/**
+ * Extract executable commands from fenced code blocks that carry
+ * release-skill:exec metadata on the preceding line.
+ *
+ * @param {string} content
+ * @returns {Array<{ fixture: string, language: string, commands: string[] }>}
+ */
+function extractExecBlocks(content) {
+  const results = [];
+  const regex = /<!--\s*release-skill:exec\s+fixture=([\w-]+)\s*-->\s*\n```(sh|bash)\n([\s\S]*?)```/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const fixture = match[1];
+    const language = match[2];
+    const blockBody = match[3];
+    const commands = blockBody
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith('#'));
+    results.push({ fixture, language, commands });
+  }
+  return results;
+}
+
+/**
+ * Safely read a file; return null if absent.
+ * @param {string} filePath
+ * @returns {Promise<string | null>}
+ */
+async function safeRead(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a single skill entry to its name.
+ *
+ * Handles both the legacy object format ({ name: string }) and the
+ * official Codex plugin manifest string-path format
+ * (e.g. "../skills-src/release-help/SKILL.md").
+ *
+ * @param {string | { name: string }} entry
+ * @returns {string | null}
+ */
+function resolveSkillName(entry) {
+  if (typeof entry === 'string') {
+    // String path: extract directory name as skill name.
+    // "../skills-src/release-help/SKILL.md" → "release-help"
+    const parts = entry.replace(/\\/g, '/').split('/');
+    // Walk backwards to find the first segment that looks like a skill name
+    // (skipping SKILL.md or similar file names).
+    for (let i = parts.length - 1; i >= 0; i--) {
+      const seg = parts[i];
+      if (seg && !seg.includes('.')) return seg;
+    }
+    return null;
+  }
+  if (entry && typeof entry === 'object' && typeof entry.name === 'string') {
+    return entry.name;
+  }
+  return null;
+}
+
+/**
+ * Extract all skill names from a plugin manifest skills array.
+ * Supports both object arrays ({ name }) and string-path arrays.
+ *
+ * @param {Array<{ name: string } | string>} skills
+ * @returns {string[]}
+ */
+export function extractManifestSkillNames(skills) {
+  if (!Array.isArray(skills)) return [];
+  return skills.map(resolveSkillName).filter(Boolean);
+}
+
+/**
+ * Find Skill names mentioned in README content.
+ * @param {string} content
+ * @param {string[]} manifestSkillNames
+ * @returns {string[]}
+ */
+function findSkillNames(content, manifestSkillNames) {
+  return manifestSkillNames.filter((name) => content.includes(name));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate README files in a snapshot directory against the release-skill
+ * contract. Requires both README.md and README.zh-CN.md to be present.
+ *
+ * @param {object} options
+ * @param {string} options.snapshotDir  Path to the snapshot directory.
+ * @param {{ name?: string, entrySkill?: string, skills?: Array<{ name: string }> }} [options.pluginManifest]
+ *   Optional plugin manifest for Skill name validation.
+ * @returns {Promise<ReadmeReport>}
+ *
+ * @typedef {object} ReadmeReport
+ * @property {string[]} present   Required marker names found in README.md.
+ * @property {string[]} missing   Required marker names absent from README.md.
+ * @property {object}   bilingualMarkers  Per-category arrays of { en, zh-CN } values.
+ * @property {object}   firstScreen  Booleans for the four first-screen questions.
+ * @property {string[]} skillNames  Skill names found in README content.
+ * @property {Array<{ fixture: string, language: string, commands: string[] }>} execCommands
+ * @property {Array<{ code: string, message: string, language?: string }>} findings
+ */
+export async function evaluateReadme({ snapshotDir, pluginManifest }) {
+  const findings = [];
+
+  // ---- 1. Read README files ----
+  const enPath = path.join(snapshotDir, 'README.md');
+  const zhPath = path.join(snapshotDir, 'README.zh-CN.md');
+
+  const enContent = await safeRead(enPath);
+  const zhContent = await safeRead(zhPath);
+
+  if (!enContent) {
+    findings.push({
+      code: 'README_MISSING',
+      message: 'README.md not found in snapshot directory',
+    });
+  }
+  if (!zhContent) {
+    findings.push({
+      code: 'LANG_MISSING',
+      message: 'README.zh-CN.md not found in snapshot directory',
+      language: 'zh-CN',
+    });
+  }
+
+  // ---- 2. Extract markers from each README ----
+  const enMarkers = enContent ? extractMarkers(enContent) : new Set();
+  const zhMarkers = zhContent ? extractMarkers(zhContent) : new Set();
+
+  // ---- 3. Determine present / missing for required markers ----
+  const present = [...REQUIRED_MARKER_NAMES].filter((name) => enMarkers.has(name)).sort();
+  const missing = [...REQUIRED_MARKER_NAMES].filter((name) => !enMarkers.has(name)).sort();
+
+  // ---- 4. Build bilingual markers per category ----
+  const bilingualMarkers = {};
+  for (const category of ['capability', 'command', 'safety', 'version']) {
+    bilingualMarkers[category] = [];
+  }
+
+  for (const def of MARKER_DEFS) {
+    bilingualMarkers[def.category].push({
+      en: enMarkers.has(def.name) ? def.bilingualKey : '',
+      'zh-CN': zhMarkers.has(def.name) ? def.bilingualKey : '',
+    });
+  }
+
+  // ---- 5. First-screen questions and readability checks ----
+  const firstScreen = {
+    identity: enContent ? /^#\s+.+$/m.test(enContent) : false,
+    audienceProblem: enContent
+      ? enMarkers.has('unsupported-scope') ||
+        (enContent.includes('release-skill') && /who|适合|需要|problem|问题/i.test(enContent))
+      : false,
+    externalWriteBoundary: enMarkers.has('external-write-boundary'),
+    safeFirstCommand: enMarkers.has('safe-first-command'),
+  };
+
+  // Readability checks: installation, minimal example, failure diagnosis
+  const readabilityChecks = {
+    hasInstall: enContent
+      ? /npm\s+install|npx\s+release-skill|npm\s+i\s+release-skill/i.test(enContent)
+      : false,
+    hasMinimalExample: enContent
+      ? /```[\s\S]*?(release-skill|assess|prepare|help)[\s\S]*?```/i.test(enContent)
+      : false,
+    hasFailureDiagnosis: enContent
+      ? /CONFIG_INVALID|PARTIAL|GATE_FAILED|if.*fail|如果.*失败|故障|troubleshoot/i.test(enContent)
+      : false,
+    hasNextSteps: enContent
+      ? /next.*step|下一步|后续|see.*also|参阅|进一步/i.test(enContent)
+      : false,
+  };
+
+  // ---- 6. Skill names from manifest ----
+  const manifestSkillNames = extractManifestSkillNames(pluginManifest?.skills);
+  const skillNames = enContent
+    ? findSkillNames(enContent, manifestSkillNames)
+    : [];
+
+  // ---- 7. Extract executable commands ----
+  const execCommands = enContent ? extractExecBlocks(enContent) : [];
+  if (zhContent) {
+    const zhExec = extractExecBlocks(zhContent);
+    for (const block of zhExec) {
+      const existing = execCommands.find(
+        (e) => e.fixture === block.fixture && e.language === block.language,
+      );
+      if (!existing) {
+        execCommands.push(block);
+      }
+    }
+  }
+
+  return {
+    present,
+    missing,
+    bilingualMarkers,
+    firstScreen,
+    readabilityChecks,
+    skillNames,
+    execCommands,
+    findings,
+  };
+}

package/src/readme/examples.mjs

@@ -0,0 +1,288 @@
+/**
+ * README executable examples extraction and sandboxed execution.
+ *
+ * Extracts fenced code blocks annotated with <!-- release-skill:exec fixture=<id> -->
+ * metadata from README files, copies the referenced fixture into a temporary
+ * directory, and executes each command using `execFile` (never shell) in isolation.
+ * The original fixture directory is never modified.
+ *
+ * @module readme/examples
+ */
+
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, cp, mkdtemp, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { ReleaseError } from '../core/errors.mjs';
+
+const execFileAsync = promisify(execFileCb);
+
+/** Default command timeout in milliseconds (30 seconds). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Maximum buffer for child process stdout/stderr (10 MiB). */
+const MAX_BUFFER = 10 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract executable command blocks from README content.
+ *
+ * A block is executable when the line immediately before the opening fence
+ * contains: <!-- release-skill:exec fixture=<id> -->
+ *
+ * @param {string} content - README file content.
+ * @returns {Array<{ fixture: string, language: string, commands: string[] }>}
+ */
+function extractExecBlocks(content) {
+  const results = [];
+  const regex =
+    /<!--\s*release-skill:exec\s+fixture=([\w-]+)\s*-->\s*\n```(sh|bash)\n([\s\S]*?)```/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const fixture = match[1];
+    const language = match[2];
+    const blockBody = match[3];
+    const commands = blockBody
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith('#'));
+    results.push({ fixture, language, commands });
+  }
+  return results;
+}
+
+/**
+ * Parse a shell-style command line into [executable, ...args].
+ *
+ * Handles quoted arguments (single and double) and strips inline comments.
+ * This is a simple parser -- it does NOT invoke a shell.
+ *
+ * @param {string} line - A single command line.
+ * @returns {string[]}  - [executable, ...args]
+ */
+function parseCommand(line) {
+  const tokens = [];
+  let current = '';
+  let inSingle = false;
+  let inDouble = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+
+    if (inSingle) {
+      if (ch === "'") {
+        inSingle = false;
+      } else {
+        current += ch;
+      }
+    } else if (inDouble) {
+      if (ch === '"') {
+        inDouble = false;
+      } else if (ch === '\\' && i + 1 < line.length) {
+        current += line[++i];
+      } else {
+        current += ch;
+      }
+    } else if (ch === '#') {
+      // Inline comment -- stop processing this line
+      break;
+    } else if (ch === "'") {
+      inSingle = true;
+    } else if (ch === '"') {
+      inDouble = true;
+    } else if (ch === ' ' || ch === '\t') {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = '';
+      }
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.length > 0) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+/**
+ * Safely read a file; return null if absent.
+ * @param {string} filePath
+ * @returns {Promise<string | null>}
+ */
+async function safeRead(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} ExecResult
+ * @property {string}   fixture   - The fixture id from the exec metadata.
+ * @property {string}   command   - The original command line string.
+ * @property {string[]} parsed    - Parsed [executable, ...args].
+ * @property {string}   stdout    - Captured stdout.
+ * @property {string}   stderr    - Captured stderr.
+ * @property {number}   exitCode  - Process exit code (0 for success).
+ * @property {string}   cwd       - Absolute path to the sandboxed working directory.
+ * @property {'ok'|'timeout'|'error'} status - Execution outcome.
+ */
+
+/**
+ * Extract executable commands from README files and run them in isolated
+ * fixture copies using `execFile` (never shell).
+ *
+ * For each fixture referenced by exec metadata:
+ * 1. The fixture directory is copied to a fresh temporary directory.
+ * 2. Every command in the block is executed in that copy via `execFile`.
+ * 3. The original fixture is never modified.
+ *
+ * @param {object}  options
+ * @param {string}  options.snapshotDir  - Directory containing README.md / README.zh-CN.md.
+ * @param {string}  options.fixturesDir  - Directory containing fixture subdirectories.
+ * @param {number}  [options.timeoutMs=30000] - Per-command timeout in milliseconds.
+ * @returns {Promise<ExecResult[]>}
+ */
+export async function extractExecutableCommands({
+  snapshotDir,
+  fixturesDir,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  // 1. Read README files and extract exec blocks
+  const enContent = await safeRead(path.join(snapshotDir, 'README.md'));
+  const zhContent = await safeRead(path.join(snapshotDir, 'README.zh-CN.md'));
+
+  /** @type {Map<string, { fixture: string, commands: string[] }>} */
+  const blocksByFixture = new Map();
+
+  const addBlocks = (content) => {
+    if (!content) return;
+    for (const block of extractExecBlocks(content)) {
+      if (!blocksByFixture.has(block.fixture)) {
+        blocksByFixture.set(block.fixture, {
+          fixture: block.fixture,
+          commands: block.commands,
+        });
+      }
+    }
+  };
+
+  addBlocks(enContent);
+  addBlocks(zhContent);
+
+  if (blocksByFixture.size === 0) {
+    return [];
+  }
+
+  // 2. Create a parent temp directory for all fixture copies
+  const parentTmp = await mkdtemp(path.join(os.tmpdir(), 'release-skill-examples-'));
+
+  /** @type {ExecResult[]} */
+  const results = [];
+
+  try {
+    for (const [fixtureId, block] of blocksByFixture) {
+      const srcDir = path.join(fixturesDir, fixtureId);
+
+      // Create an isolated copy for this fixture
+      const sandboxDir = path.join(parentTmp, fixtureId);
+      await cp(srcDir, sandboxDir, { recursive: true });
+
+      for (const line of block.commands) {
+        const parsed = parseCommand(line);
+        if (parsed.length === 0) continue;
+
+        const executable = parsed[0];
+        const args = parsed.slice(1);
+
+        /** @type {ExecResult} */
+        let result;
+
+        try {
+          // Set up timeout via AbortController
+          const controller = new AbortController();
+          const handle = setTimeout(() => controller.abort(), timeoutMs);
+
+          try {
+            const { stdout, stderr } = await execFileAsync(executable, args, {
+              cwd: sandboxDir,
+              shell: false,
+              maxBuffer: MAX_BUFFER,
+              signal: controller.signal,
+            });
+
+            result = {
+              fixture: fixtureId,
+              command: line,
+              parsed,
+              stdout: stdout ?? '',
+              stderr: stderr ?? '',
+              exitCode: 0,
+              cwd: sandboxDir,
+              status: 'ok',
+            };
+          } finally {
+            clearTimeout(handle);
+          }
+        } catch (err) {
+          // Timeout detection: AbortError or killed via SIGTERM
+          if (err.name === 'AbortError' || (err.killed && err.signal === 'SIGTERM')) {
+            result = {
+              fixture: fixtureId,
+              command: line,
+              parsed,
+              stdout: err.stdout ?? '',
+              stderr: err.stderr ?? '',
+              exitCode: 16, // HOOK_TIMEOUT exit code
+              cwd: sandboxDir,
+              status: 'timeout',
+            };
+          } else if ('stdout' in err) {
+            // Non-zero exit
+            result = {
+              fixture: fixtureId,
+              command: line,
+              parsed,
+              stdout: err.stdout ?? '',
+              stderr: err.stderr ?? '',
+              exitCode: typeof err.code === 'number' ? err.code : 1,
+              cwd: sandboxDir,
+              status: 'error',
+            };
+          } else {
+            // Unexpected failure (e.g., ENOENT)
+            result = {
+              fixture: fixtureId,
+              command: line,
+              parsed,
+              stdout: '',
+              stderr: err.message ?? String(err),
+              exitCode: 1,
+              cwd: sandboxDir,
+              status: 'error',
+            };
+          }
+        }
+
+        results.push(result);
+      }
+    }
+  } finally {
+    // Clean up the temporary directory tree
+    await rm(parentTmp, { recursive: true, force: true });
+  }
+
+  return results;
+}

package/src/readme/parity.mjs

@@ -0,0 +1,122 @@
+/**
+ * Bilingual README parity check for release-skill.
+ *
+ * Compares machine-readable HTML-comment markers between README.md and
+ * README.zh-CN.md to ensure capability, command, safety, and version
+ * markers are present in both languages. Does NOT perform natural
+ * language semantic comparison -- only marker set equality.
+ *
+ * Marker formats supported:
+ *   - Simple:       <!-- release-skill:<name> -->
+ *   - Categorized:  <!-- release-skill:<category>:<name> -->
+ *
+ * @module readme/parity
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract all release-skill marker names from a README string.
+ *
+ * Matches HTML comments of the form:
+ *   <!-- release-skill:<name> -->
+ *   <!-- release-skill:<category>:<name> -->
+ *
+ * The canonical name is the last colon-separated segment.
+ * The "exec" pseudo-marker is excluded (it serves a different purpose).
+ *
+ * @param {string} content
+ * @returns {Set<string>} Set of marker names.
+ */
+function extractMarkers(content) {
+  const regex = /<!--\s*release-skill:((?:[\w-]+:)*[\w-]+)\s*-->/g;
+  const found = new Set();
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const raw = match[1];
+    // Skip exec metadata pseudo-marker
+    if (raw.startsWith('exec')) continue;
+    // The canonical name is the last colon-separated segment.
+    const parts = raw.split(':');
+    const name = parts[parts.length - 1];
+    found.add(name);
+  }
+  return found;
+}
+
+/**
+ * Safely read a file; return null if absent.
+ * @param {string} filePath
+ * @returns {Promise<string | null>}
+ */
+async function safeRead(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare bilingual README markers and report any drift.
+ *
+ * Extracts machine-readable markers from both README.md and
+ * README.zh-CN.md in the given snapshot directory, then computes:
+ * - enOnly:  markers present in English but missing from Chinese
+ * - zhOnly:  markers present in Chinese but missing from English
+ * - balanced: markers present in both languages
+ *
+ * @param {object} options
+ * @param {string} options.snapshotDir  Path to the snapshot directory.
+ * @returns {Promise<ParityReport>}
+ *
+ * @typedef {object} ParityReport
+ * @property {string[]} enOnly    Markers found only in README.md.
+ * @property {string[]} zhOnly    Markers found only in README.zh-CN.md.
+ * @property {string[]} balanced  Markers found in both README files.
+ *
+ * @throws {Error} With code 'LANG_MISSING' if README.zh-CN.md is absent.
+ */
+export async function checkBilingualParity({ snapshotDir }) {
+  const enPath = path.join(snapshotDir, 'README.md');
+  const zhPath = path.join(snapshotDir, 'README.zh-CN.md');
+
+  const enContent = await safeRead(enPath);
+  const zhContent = await safeRead(zhPath);
+
+  if (!enContent) {
+    const error = new Error('README.md not found in snapshot directory');
+    error.code = 'README_MISSING';
+    throw error;
+  }
+
+  if (!zhContent) {
+    const error = new Error('README.zh-CN.md not found in snapshot directory');
+    error.code = 'LANG_MISSING';
+    throw error;
+  }
+
+  const enMarkers = extractMarkers(enContent);
+  const zhMarkers = extractMarkers(zhContent);
+
+  const enOnly = [...enMarkers]
+    .filter((name) => !zhMarkers.has(name))
+    .sort();
+  const zhOnly = [...zhMarkers]
+    .filter((name) => !enMarkers.has(name))
+    .sort();
+  const balanced = [...enMarkers]
+    .filter((name) => zhMarkers.has(name))
+    .sort();
+
+  return { enOnly, zhOnly, balanced };
+}