release-skill 0.1.10 → 0.2.1

package/scripts/sync-public-files.mjs

@@ -0,0 +1,481 @@
+#!/usr/bin/env node
+/**
+ * sync-public-files.mjs
+ *
+ * Generate the `publicFiles` and `requiredPublicFiles` arrays of
+ * `.release-skill/project.yaml` from the platform registry and the actual
+ * package directory contents.  This replaces the hand-maintained ~600-line
+ * file lists with a registry-driven generator.
+ *
+ * The generator scans `packages/release-skill/` for all regular files,
+ * excludes the `adapters/` subtree (generated by build-adapters), then adds:
+ *   1. Platform manifest files derived from the registry (manifestPaths +
+ *      buildAdapter fields), plus the root manifests of build-only
+ *      distribution adapters (BUILD_ONLY_ADAPTERS, e.g. workbuddy).
+ *   2. All files under `adapters/{platform.id}/` for each registry platform
+ *      and each build-only adapter.
+ *
+ * Usage (run from the package directory):
+ *   node scripts/sync-public-files.mjs            # rewrite drifted arrays
+ *   node scripts/sync-public-files.mjs --check    # read-only; exit 1 on drift
+ *
+ * Zero runtime dependencies; Node.js standard library only.
+ */
+
+import { readFile, writeFile, readdir, stat, realpath } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Platform registry import
+// ---------------------------------------------------------------------------
+
+import { PLATFORMS } from '../src/platforms/registry.mjs';
+import { BUILD_ONLY_ADAPTERS } from '../src/producers/build-adapters.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const SCRIPT_DIR = new URL('.', import.meta.url).pathname;
+const PKG_ROOT = process.env.RELEASE_SKILL_PKG_ROOT ?? join(SCRIPT_DIR, '..');
+const PROJECT_YAML = join(PKG_ROOT, '..', '..', '.release-skill', 'project.yaml');
+const SOURCE_PREFIX = 'packages/release-skill/';
+
+// ---------------------------------------------------------------------------
+// File scanning
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively collect all regular file paths (relative to `baseDir`) under
+ * `baseDir`, sorted lexicographically.
+ */
+async function scanFiles(baseDir, relPrefix = '') {
+  const results = [];
+  let entries;
+  try {
+    entries = await readdir(baseDir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    if (entry.isDirectory()) {
+      results.push(...await scanFiles(join(baseDir, entry.name), relPath));
+    } else if (entry.isFile()) {
+      results.push(relPath);
+    }
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Platform manifest path derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive all manifest file paths for a platform from the registry.
+ * Returns paths relative to the package root.
+ */
+function deriveManifestPaths(platform) {
+  const paths = [];
+  const mp = platform.manifestPaths;
+
+  // plugin manifest
+  if (mp.plugin && typeof mp.plugin === 'string') {
+    paths.push(mp.plugin);
+  }
+  // kimi has pluginCandidates (array) instead of a single plugin path
+  if (Array.isArray(mp.pluginCandidates)) {
+    for (const candidate of mp.pluginCandidates) {
+      paths.push(candidate);
+    }
+  }
+  // marketplace manifest (codex root marketplace)
+  if (mp.marketplace && typeof mp.marketplace === 'string') {
+    paths.push(mp.marketplace);
+  }
+
+  return paths;
+}
+
+/**
+ * Derive all adapter-relative file paths for a platform from the registry.
+ * These are the static structure inside adapters/{name}/ that is NOT generated
+ * by build-adapters (i.e., plugin manifests).  The rest of the adapter
+ * directory is scanned from disk.
+ */
+function deriveAdapterManifestPaths(platform) {
+  const paths = [];
+  const ba = platform.buildAdapter;
+
+  // Plugin manifest directory
+  if (ba.pluginDirName) {
+    paths.push(`${ba.pluginDirName}/${ba.templateFileName}`);
+    if (ba.marketplaceFileName) {
+      paths.push(`${ba.pluginDirName}/${ba.marketplaceFileName}`);
+    }
+  }
+
+  return paths;
+}
+
+// ---------------------------------------------------------------------------
+// YAML manipulation
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the line range of a YAML top-level array property.
+ * Returns { start, end } (0-indexed, inclusive) or null if not found.
+ * `start` is the line of the property key; `end` is the last line of the array.
+ */
+function findArrayRange(lines, key, parentIndent = 4) {
+  const keyLine = `${' '.repeat(parentIndent)}${key}:`;
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i] === keyLine || lines[i] === `${keyLine} []`) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return null;
+
+  // If the key line ends with `[]`, the array is empty and on the same line.
+  if (lines[start].endsWith('[]')) {
+    return { start, end: start };
+  }
+
+  // Find the end of the array: the last line that is indented more than the
+  // key line, or is a `- ` item at the array indentation level.
+  const arrayIndent = parentIndent + 2; // typical: key at 4, items at 6
+  let end = start;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    // Empty lines within the array
+    if (line.trim() === '') {
+      // Check if next non-empty line is still part of the array
+      let nextNonEmpty = i + 1;
+      while (nextNonEmpty < lines.length && lines[nextNonEmpty].trim() === '') {
+        nextNonEmpty++;
+      }
+      if (nextNonEmpty < lines.length && isIndentedAtLeast(lines[nextNonEmpty], arrayIndent)) {
+        end = i;
+        continue;
+      }
+      break;
+    }
+    if (isIndentedAtLeast(line, arrayIndent)) {
+      end = i;
+    } else {
+      break;
+    }
+  }
+  return { start, end };
+}
+
+function isIndentedAtLeast(line, indent) {
+  if (line.trim() === '') return false;
+  let count = 0;
+  for (const ch of line) {
+    if (ch === ' ') count++;
+    else break;
+  }
+  return count >= indent;
+}
+
+// ---------------------------------------------------------------------------
+// YAML generation
+// ---------------------------------------------------------------------------
+
+function buildPublicFilesYaml(entries, indent = 6) {
+  const prefix = ' '.repeat(indent);
+  const lines = [];
+  for (const entry of entries) {
+    lines.push(`${prefix}- from: ${SOURCE_PREFIX}${entry}`);
+    lines.push(`${prefix}  to: ${entry}`);
+    lines.push(`${prefix}  mode: preserve`);
+  }
+  return lines.join('\n');
+}
+
+function buildRequiredPublicFilesYaml(entries, indent = 6) {
+  const prefix = ' '.repeat(indent);
+  return entries.map((e) => `${prefix}- ${e}`).join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Entry collection
+// ---------------------------------------------------------------------------
+
+async function collectEntries() {
+  // 1. Scan all files in the package directory
+  const allFiles = await scanFiles(PKG_ROOT);
+  const allSet = new Set(allFiles);
+
+  // 2. Build the adapter exclusion set (all files under adapters/)
+  const adapterFiles = new Set();
+  for (const f of allFiles) {
+    if (f.startsWith('adapters/')) {
+      adapterFiles.add(f);
+    }
+  }
+
+  // 3. Base files = all files except adapters/ and non-public directories/files.
+  //    Excluded:
+  //    - test/               (test files, not shipped)
+  //    - test-fixtures/      (test fixtures, not shipped)
+  //    - release-notes/      (consumed by docs-refresh, not a public artifact)
+  //    - native/*/build/     (native build artifacts, only prebuilds are shipped)
+  //    - scripts/*           (mostly dev-only; explicit whitelist below)
+  const baseFiles = allFiles.filter((f) => {
+    if (f.startsWith('adapters/')) return false;
+    if (f.startsWith('test/')) return false;
+    if (f.startsWith('test-fixtures/')) return false;
+    if (f.startsWith('release-notes/')) return false;
+    if (f.startsWith('native/') && f.includes('/build/')) return false;
+    if (f.startsWith('scripts/')) return false;
+    return true;
+  });
+
+  // 4. Public scripts: explicit whitelist (most scripts are dev-only).
+  const PUBLIC_SCRIPTS = Object.freeze([
+    'scripts/build-bundle.mjs',
+    'scripts/sync-public-files.mjs',
+  ]);
+  for (const script of PUBLIC_SCRIPTS) {
+    if (allSet.has(script)) {
+      baseFiles.push(script);
+    }
+  }
+
+  // 4. Collect platform-specific files
+  const platformManifestFiles = [];
+  const platformAdapterFiles = [];
+
+  for (const platform of PLATFORMS) {
+    // Root-level manifest files
+    for (const mp of deriveManifestPaths(platform)) {
+      if (allSet.has(mp)) {
+        platformManifestFiles.push(mp);
+      }
+    }
+
+    // Adapter directory files
+    const adapterDir = `adapters/${platform.id}`;
+    const adapterDirPrefix = `${adapterDir}/`;
+    for (const f of allFiles) {
+      if (f.startsWith(adapterDirPrefix)) {
+        platformAdapterFiles.push(f);
+      }
+    }
+  }
+
+  // Build-only distribution adapters (e.g. workbuddy): not publish-pipeline
+  // platforms, but their generated adapter trees and root manifests ship
+  // publicly just like the pipeline platforms'.
+  for (const adapter of BUILD_ONLY_ADAPTERS) {
+    const rootManifest = `${adapter.pluginDirName}/${adapter.templateFileName}`;
+    if (allSet.has(rootManifest)) {
+      platformManifestFiles.push(rootManifest);
+    }
+    const adapterDirPrefix = `adapters/${adapter.name}/`;
+    for (const f of allFiles) {
+      if (f.startsWith(adapterDirPrefix)) {
+        platformAdapterFiles.push(f);
+      }
+    }
+  }
+
+  // 5. Combine, deduplicate, sort
+  const combined = [...baseFiles, ...platformManifestFiles, ...platformAdapterFiles];
+  const unique = [...new Set(combined)];
+  unique.sort();
+
+  return unique;
+}
+
+// ---------------------------------------------------------------------------
+// Check / write
+// ---------------------------------------------------------------------------
+
+async function readProjectYaml() {
+  return await readFile(PROJECT_YAML, 'utf8');
+}
+
+function extractExistingEntries(yamlText, key) {
+  const lines = yamlText.split('\n');
+  const range = findArrayRange(lines, key);
+  if (!range) return [];
+
+  if (range.start === range.end && lines[range.start].endsWith('[]')) {
+    return [];
+  }
+
+  const entries = [];
+  for (let i = range.start + 1; i <= range.end; i++) {
+    const line = lines[i];
+    // Match `- from: ...` pattern (publicFiles)
+    const fromMatch = line.match(/^ +- from: (.+)$/);
+    if (fromMatch) {
+      // The `to` is on the next line
+      for (let j = i + 1; j <= Math.min(i + 2, range.end); j++) {
+        const toMatch = lines[j].match(/^ +to: (.+)$/);
+        if (toMatch) {
+          entries.push(toMatch[1]);
+          break;
+        }
+      }
+      continue;
+    }
+    // Match `- <value>` pattern (requiredPublicFiles)
+    const simpleMatch = line.match(/^ +- (.+)$/);
+    if (simpleMatch) {
+      entries.push(simpleMatch[1]);
+    }
+  }
+  return entries;
+}
+
+function replaceArrayInYaml(yamlText, key, newContent) {
+  const lines = yamlText.split('\n');
+  const range = findArrayRange(lines, key);
+  if (!range) {
+    throw new Error(`sync-public-files: cannot find "${key}" in project.yaml`);
+  }
+
+  // Replace the array content (everything after the key line through the end)
+  const before = lines.slice(0, range.start + 1);
+  const after = lines.slice(range.end + 1);
+
+  // If newContent is empty, use `[]` notation
+  if (newContent.trim() === '') {
+    return [...before.map((l) => l), `${' '.repeat(4)}${key}: []`, ...after].join('\n');
+  }
+
+  return [...before, newContent, ...after].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Sync the publicFiles and requiredPublicFiles arrays in project.yaml.
+ *
+ * @param {object} options
+ * @param {string} options.packageDir - Package directory.
+ * @param {boolean} [options.check] - Read-only drift detection.
+ * @returns {Promise<{mode: string, clean?: boolean, diff?: object}>}
+ */
+export async function syncPublicFiles({ packageDir, check = false } = {}) {
+  if (typeof packageDir !== 'string' || packageDir.length === 0) {
+    const err = new Error('sync-public-files: packageDir is required');
+    err.code = 'SYNC_PUBLIC_FILES_INVALID_ARGUMENT';
+    throw err;
+  }
+
+  const entries = await collectEntries();
+  const yamlText = await readProjectYaml();
+
+  const existingPublic = extractExistingEntries(yamlText, 'publicFiles');
+  const existingRequired = extractExistingEntries(yamlText, 'requiredPublicFiles');
+
+  // Compare sets (order-independent)
+  const publicSet = new Set(entries);
+  const existingPublicSet = new Set(existingPublic);
+  const requiredSet = new Set(entries);
+  const existingRequiredSet = new Set(existingRequired);
+
+  const publicMissing = entries.filter((e) => !existingPublicSet.has(e));
+  const publicExtra = existingPublic.filter((e) => !publicSet.has(e));
+  const requiredMissing = entries.filter((e) => !existingRequiredSet.has(e));
+  const requiredExtra = existingRequired.filter((e) => !requiredSet.has(e));
+
+  const isClean = publicMissing.length === 0 && publicExtra.length === 0
+    && requiredMissing.length === 0 && requiredExtra.length === 0;
+
+  if (check) {
+    return {
+      mode: 'check',
+      entryCount: entries.length,
+      clean: isClean,
+      diff: isClean ? undefined : {
+        publicFiles: { missing: publicMissing, extra: publicExtra },
+        requiredPublicFiles: { missing: requiredMissing, extra: requiredExtra },
+      },
+    };
+  }
+
+  if (isClean) {
+    return { mode: 'write', entryCount: entries.length, changed: false };
+  }
+
+  // Generate new YAML content
+  const publicYaml = buildPublicFilesYaml(entries);
+  const requiredYaml = buildRequiredPublicFilesYaml(entries);
+
+  let newYaml = replaceArrayInYaml(yamlText, 'publicFiles', publicYaml);
+  newYaml = replaceArrayInYaml(newYaml, 'requiredPublicFiles', requiredYaml);
+
+  await writeFile(PROJECT_YAML, newYaml, 'utf8');
+
+  // Verify write
+  const reread = await readFile(PROJECT_YAML, 'utf8');
+  if (reread !== newYaml) {
+    const err = new Error('sync-public-files: post-write verification failed');
+    err.code = 'SYNC_PUBLIC_FILES_WRITE_VERIFY_FAILED';
+    throw err;
+  }
+
+  return { mode: 'write', entryCount: entries.length, changed: true };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const invokedPath = process.argv[1]
+  ? await realpath(process.argv[1]).catch(() => process.argv[1])
+  : '';
+const isMain = invokedPath.length > 0 && fileURLToPath(import.meta.url) === invokedPath;
+
+if (isMain) {
+  const checkMode = process.argv.includes('--check');
+  try {
+    const result = await syncPublicFiles({ packageDir: PKG_ROOT, check: checkMode });
+    if (checkMode) {
+      if (result.clean) {
+        console.log(`[sync-public-files] OK: all ${result.entryCount} entries in sync.`);
+      } else {
+        console.error(`[sync-public-files] drift detected:`);
+        const d = result.diff;
+        if (d.publicFiles.missing.length > 0) {
+          console.error(`  publicFiles missing (${d.publicFiles.missing.length}):`);
+          for (const e of d.publicFiles.missing) console.error(`    + ${e}`);
+        }
+        if (d.publicFiles.extra.length > 0) {
+          console.error(`  publicFiles extra (${d.publicFiles.extra.length}):`);
+          for (const e of d.publicFiles.extra) console.error(`    - ${e}`);
+        }
+        if (d.requiredPublicFiles.missing.length > 0) {
+          console.error(`  requiredPublicFiles missing (${d.requiredPublicFiles.missing.length}):`);
+          for (const e of d.requiredPublicFiles.missing) console.error(`    + ${e}`);
+        }
+        if (d.requiredPublicFiles.extra.length > 0) {
+          console.error(`  requiredPublicFiles extra (${d.requiredPublicFiles.extra.length}):`);
+          for (const e of d.requiredPublicFiles.extra) console.error(`    - ${e}`);
+        }
+        console.error('Run "node scripts/sync-public-files.mjs" from the package directory to sync.');
+        process.exit(1);
+      }
+    } else if (!result.changed) {
+      console.log(`[sync-public-files] already in sync (${result.entryCount} entries).`);
+    } else {
+      console.log(`[sync-public-files] synced ${result.entryCount} entries.`);
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}

package/src/adapters/contract.mjs

@@ -13,6 +13,8 @@
  * @module adapters/contract
  */
 
+import { writeFile, rename, rm } from 'node:fs/promises';
+
 import { ReleaseError, AUTH_MISSING } from '../core/errors.mjs';
 
 /**
@@ -146,6 +148,64 @@ export function matchObservation(expected, observation) {
   return { matches: mismatches.length === 0, mismatches };
 }
 
+/** Safe identifier pattern: lowercase alphanumeric, hyphens, dots, underscores. */
+export const SAFE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+/**
+ * Resolve and validate the frozen timeoutMs from the expanded adapter action.
+ *
+ * The publish/reconcile/verify call path expands plan actions as
+ * `{ actionType, ...action.parameters }`, so `parameters.timeoutMs` in the
+ * plan becomes `action.timeoutMs` at the adapter level. This function reads
+ * from the top-level action, not from a nested `parameters` sub-object.
+ *
+ * Rules:
+ * - Missing field (undefined): returns 300000 default (legacy compatibility).
+ * - Present but null/invalid (null, string, NaN, Infinity, non-integer,
+ *   out of range): fail-closed, throws.
+ * - Valid integer in [30000, 900000]: returns the value as-is.
+ *
+ * @param {object} action - The expanded adapter action (top-level).
+ * @returns {number} Validated timeout in milliseconds.
+ * @throws {Error} If the value is present but invalid.
+ */
+export function resolveTimeoutMs(action) {
+  const raw = action?.timeoutMs;
+  if (raw === undefined) {
+    return 300000;
+  }
+  if (raw === null || typeof raw !== 'number' || !Number.isFinite(raw) || !Number.isInteger(raw)) {
+    throw new Error(
+      `action.timeoutMs must be a finite integer, got: ${JSON.stringify(raw)}`,
+    );
+  }
+  if (raw < 30000 || raw > 900000) {
+    throw new Error(
+      `action.timeoutMs must be between 30000 and 900000, got: ${raw}`,
+    );
+  }
+  return raw;
+}
+
+/**
+ * Atomically write a JSON evidence/requirement file (mode 0o600, exclusive
+ * create, rename into place). Crash-safe: a partial write never replaces an
+ * existing file.
+ *
+ * @param {string} filePath
+ * @param {object} value
+ */
+export async function writeEvidenceAtomic(filePath, value) {
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    await rename(tempPath, filePath);
+  } catch (err) {
+    await rm(tempPath, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
 /**
  * Adapter interface type documentation (not enforced at runtime, but all
  * adapters must follow this shape):