@eltonssouza/development-utility-kit 0.10.0

package/bin/lib/local-dir.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Provision `.claude/local/` with a README explaining the override contract
+ * (per ADR-032). Idempotent — never overwrites an existing README.
+ */
+
+const LOCAL_README = `# .claude/local/ — project-only overrides
+
+This directory is **never touched** by \`duk install\`. Anything you put
+here survives every harness update.
+
+Use it for customisations that apply ONLY to this project:
+
+  local/agents/        project-specific agent overrides
+  local/skills/        project-specific skills (non-canonical)
+  local/stacks/        proprietary or internal stack packs
+
+Loader priority (per ADR-032 §3):
+    .claude/local/<path>   wins over
+    .claude/<path>
+
+When to use \`.claude/local/\`:
+  - Stack proprietária da empresa (ex: \`local/stacks/internal/cobol.md\`)
+  - Regra de projeto que NÃO se aplica a outros
+  - Skill experimental que pode virar canônica via PR no harness
+
+When NOT to use:
+  - Algo que beneficia todos → PR no harness repo
+
+Drift detection: files under \`local/\` are excluded from \`.MANIFEST\`,
+so editing them never triggers a drift abort during \`duk install\`.
+`;
+
+/**
+ * Ensure `.claude/local/` exists with a README. Subdirs (agents/, skills/,
+ * stacks/) are NOT pre-created — they are lazy, born when the dev adds an
+ * override.
+ *
+ * @param {string} claudeDir absolute path to .claude/
+ * @param {boolean} dryRun
+ */
+function ensureLocalDir(claudeDir, dryRun) {
+  const localDir = path.join(claudeDir, 'local');
+  const readmePath = path.join(localDir, 'README.md');
+
+  if (dryRun) {
+    if (!fs.existsSync(localDir)) {
+      process.stdout.write('  [dry-run] would create .claude/local/ with README.md\n');
+    }
+    return;
+  }
+
+  if (!fs.existsSync(localDir)) {
+    fs.mkdirSync(localDir, { recursive: true });
+  }
+  if (!fs.existsSync(readmePath)) {
+    fs.writeFileSync(readmePath, LOCAL_README, 'utf8');
+  }
+}
+
+module.exports = {
+  ensureLocalDir,
+  LOCAL_README,
+};

package/bin/lib/manifest.js

@@ -0,0 +1,236 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * `.claude/.MANIFEST` — hash-based drift detection per ADR-032.
+ *
+ *   generateManifest(claudeDir)   walk .claude/ and return Map<relPath, sha256>
+ *   writeManifest(claudeDir, harnessVersion)
+ *   loadManifest(claudeDir)       parse .claude/.MANIFEST or return null
+ *   detectDrift(claudeDir)        compare current files vs stored manifest
+ *
+ * Paths excluded from the manifest (managed independently):
+ *   - local/         (per-project overrides — never touched by install)
+ *   - .MANIFEST      (the manifest file itself)
+ *   - HARNESS_VERSION
+ *   - Anything under .claude.bak / .claude.backup-* (lives outside .claude/)
+ */
+
+const MANIFEST_FILENAME = '.MANIFEST';
+const HARNESS_VERSION_FILENAME = 'HARNESS_VERSION';
+const LOCAL_DIR = 'local';
+
+/**
+ * Walk dir recursively, returning relative POSIX-style paths of files,
+ * skipping any directory or filename that matches `shouldSkip(name, relPath)`.
+ * @param {string} root
+ * @param {(name: string, relPath: string) => boolean} shouldSkip
+ * @returns {string[]} sorted relative paths
+ */
+function walkFiles(root, shouldSkip) {
+  const out = [];
+
+  function recur(absDir, relDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (shouldSkip(entry.name, relPath)) continue;
+      const absPath = path.join(absDir, entry.name);
+      if (entry.isDirectory()) {
+        recur(absPath, relPath);
+      } else if (entry.isFile()) {
+        out.push(relPath);
+      }
+    }
+  }
+
+  recur(root, '');
+  out.sort();
+  return out;
+}
+
+/**
+ * Return sha256 hex of a file's bytes.
+ * @param {string} absPath
+ * @returns {string}
+ */
+function sha256OfFile(absPath) {
+  const buf = fs.readFileSync(absPath);
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Default skip rule for manifest walks.
+ * @param {string} name
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+function defaultSkip(name, relPath) {
+  // Skip top-level local/, MANIFEST, HARNESS_VERSION
+  if (relPath === LOCAL_DIR) return true;
+  if (relPath.startsWith(`${LOCAL_DIR}/`)) return true;
+  if (relPath === MANIFEST_FILENAME) return true;
+  if (relPath === HARNESS_VERSION_FILENAME) return true;
+  return false;
+}
+
+/**
+ * Build a Map<relPath, sha256> for every file under .claude/ except the
+ * exclusions listed above.
+ * @param {string} claudeDir absolute path to the .claude/ directory
+ * @returns {Map<string, string>}
+ */
+function generateManifest(claudeDir) {
+  const result = new Map();
+  if (!fs.existsSync(claudeDir)) return result;
+  const files = walkFiles(claudeDir, defaultSkip);
+  for (const rel of files) {
+    const abs = path.join(claudeDir, rel);
+    result.set(rel, sha256OfFile(abs));
+  }
+  return result;
+}
+
+/**
+ * Render a manifest Map to the on-disk format and write it to
+ * `<claudeDir>/.MANIFEST`.
+ * @param {string} claudeDir
+ * @param {string} harnessVersion
+ * @param {Map<string, string>} [manifest] - pre-computed; if omitted, regenerates
+ */
+function writeManifest(claudeDir, harnessVersion, manifest) {
+  const map = manifest || generateManifest(claudeDir);
+  const ts = new Date().toISOString();
+  const header = [
+    '# .claude/.MANIFEST',
+    `# Auto-generated by duk install at ${ts}.`,
+    `# Harness version: ${harnessVersion}`,
+    '# Format: <relative-path> <sha256>',
+    '# Do not edit by hand.',
+  ];
+  const lines = [...map.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([rel, sha]) => `${rel} ${sha}`);
+  const body = header.concat(lines).join('\n') + '\n';
+  const target = path.join(claudeDir, MANIFEST_FILENAME);
+  fs.writeFileSync(target, body, 'utf8');
+}
+
+/**
+ * Read and parse `.claude/.MANIFEST`. Returns null if missing or unreadable.
+ * @param {string} claudeDir
+ * @returns {Map<string, string> | null}
+ */
+function loadManifest(claudeDir) {
+  const target = path.join(claudeDir, MANIFEST_FILENAME);
+  if (!fs.existsSync(target)) return null;
+
+  let content;
+  try {
+    content = fs.readFileSync(target, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const map = new Map();
+  for (const line of content.split(/\r?\n/)) {
+    if (!line || line.startsWith('#')) continue;
+    // last whitespace-separated chunk is the sha; rest is path
+    const idx = line.lastIndexOf(' ');
+    if (idx === -1) continue;
+    const rel = line.slice(0, idx).trim();
+    const sha = line.slice(idx + 1).trim();
+    if (rel && /^[a-f0-9]{64}$/i.test(sha)) {
+      map.set(rel, sha);
+    }
+  }
+  return map;
+}
+
+/**
+ * Compare current files in .claude/ against the stored manifest. Returns
+ *   { hasManifest, drifted, added, removed }
+ * where each list contains relative paths.
+ *
+ * - hasManifest=false → no baseline (first install ever) → not blocking.
+ * - drifted → file present in both but sha differs.
+ * - added → file present on disk but not in manifest.
+ * - removed → file in manifest but missing on disk.
+ *
+ * @param {string} claudeDir
+ * @returns {{ hasManifest: boolean, drifted: string[], added: string[], removed: string[] }}
+ */
+function detectDrift(claudeDir) {
+  const stored = loadManifest(claudeDir);
+  if (stored === null) {
+    return { hasManifest: false, drifted: [], added: [], removed: [] };
+  }
+  const current = generateManifest(claudeDir);
+
+  const drifted = [];
+  const added = [];
+  const removed = [];
+
+  for (const [rel, sha] of current.entries()) {
+    if (!stored.has(rel)) {
+      added.push(rel);
+    } else if (stored.get(rel) !== sha) {
+      drifted.push(rel);
+    }
+  }
+  for (const rel of stored.keys()) {
+    if (!current.has(rel)) {
+      removed.push(rel);
+    }
+  }
+
+  drifted.sort();
+  added.sort();
+  removed.sort();
+  return { hasManifest: true, drifted, added, removed };
+}
+
+/**
+ * Write the plain-text HARNESS_VERSION file (single line, semver).
+ * @param {string} claudeDir
+ * @param {string} version
+ */
+function writeHarnessVersion(claudeDir, version) {
+  const target = path.join(claudeDir, HARNESS_VERSION_FILENAME);
+  fs.writeFileSync(target, version + '\n', 'utf8');
+}
+
+/**
+ * Read HARNESS_VERSION, returning null if missing.
+ * @param {string} claudeDir
+ * @returns {string | null}
+ */
+function readHarnessVersion(claudeDir) {
+  const target = path.join(claudeDir, HARNESS_VERSION_FILENAME);
+  if (!fs.existsSync(target)) return null;
+  try {
+    return fs.readFileSync(target, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  MANIFEST_FILENAME,
+  HARNESS_VERSION_FILENAME,
+  LOCAL_DIR,
+  generateManifest,
+  writeManifest,
+  loadManifest,
+  detectDrift,
+  writeHarnessVersion,
+  readHarnessVersion,
+};

package/bin/lib/sync-all.js

@@ -0,0 +1,394 @@
+'use strict';
+
+/**
+ * sync-all.js — Batch update of harness across multiple project subdirectories.
+ *
+ * Default = dry-run preview. `--apply` actually invokes the adoption pipeline
+ * via the main CLI's adoptProject() function.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { compareVersions } = require('./version-check');
+
+const HARNESS_DIR_SKIP = new Set([
+  'node_modules',
+  '.git',
+  '.idea',
+  '.vscode',
+  'dist',
+  'build',
+  'target',
+  'out',
+]);
+
+/**
+ * @typedef {{
+ *   key: 'stack'|'type'|'age'|'harness-version',
+ *   value: string|number,
+ *   op: string
+ * }} ParsedFilter
+ */
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   path: string,
+ *   harnessVersion: string|null,
+ *   projectType: string|null,
+ *   primaryStack: string|null,
+ *   ageMs: number
+ * }} ProjectCandidate
+ */
+
+// ─── filter parsing ──────────────────────────────────────────────────────────
+
+/**
+ * Convert a duration string ("30d", "6m", "1y", "12h") to milliseconds.
+ * @param {string} s
+ * @returns {number|null}
+ */
+function parseDuration(s) {
+  if (!s || typeof s !== 'string') return null;
+  const m = s.match(/^(\d+)([hdmy])$/i);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  const unit = m[2].toLowerCase();
+  switch (unit) {
+    case 'h':
+      return n * 60 * 60 * 1000;
+    case 'd':
+      return n * 24 * 60 * 60 * 1000;
+    case 'm':
+      return n * 30 * 24 * 60 * 60 * 1000; // month ≈ 30d
+    case 'y':
+      return n * 365 * 24 * 60 * 60 * 1000;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Parse a single filter expression like "stack:java" or "harness-version:<0.2".
+ * @param {string} expr
+ * @returns {ParsedFilter|null}
+ */
+function parseFilterExpr(expr) {
+  if (!expr || typeof expr !== 'string') return null;
+  const idx = expr.indexOf(':');
+  if (idx === -1) return null;
+  const key = expr.slice(0, idx).trim().toLowerCase();
+  const rawValue = expr.slice(idx + 1).trim();
+  if (!rawValue) return null;
+
+  switch (key) {
+    case 'stack':
+    case 'type':
+      return { key, value: rawValue.toLowerCase(), op: '=' };
+    case 'age': {
+      const ms = parseDuration(rawValue);
+      if (ms === null) return null;
+      return { key, value: ms, op: '>=' }; // ageMs >= threshold = "older than"
+    }
+    case 'harness-version': {
+      const opMatch = rawValue.match(/^(>=|<=|>|<|=)/);
+      if (opMatch) {
+        return { key, value: rawValue, op: opMatch[1] };
+      }
+      return { key, value: '=' + rawValue, op: '=' };
+    }
+    default:
+      return null;
+  }
+}
+
+// ─── CLAUDE.md parsing ───────────────────────────────────────────────────────
+
+/**
+ * Extract a key from the `## Project Identity` block of a CLAUDE.md string.
+ * Returns the raw value (without surrounding backticks).
+ * @param {string} content
+ * @param {string} key
+ * @returns {string|null}
+ */
+function extractIdentityField(content, key) {
+  if (!content) return null;
+  const idIdx = content.indexOf('## Project Identity');
+  if (idIdx === -1) return null;
+  const nextIdx = content.indexOf('\n## ', idIdx + 1);
+  const block = nextIdx === -1 ? content.slice(idIdx) : content.slice(idIdx, nextIdx);
+
+  const re = new RegExp(
+    `[*-]\\s*\\*\\*${key.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\*\\*\\s*:\\s*\`?([^\`\n]+?)\`?\\s*$`,
+    'im'
+  );
+  const m = block.match(re);
+  return m ? m[1].trim() : null;
+}
+
+// ─── project discovery ──────────────────────────────────────────────────────
+
+/**
+ * Find candidate projects under dir (subdirs containing .claude/).
+ * @param {string} dir
+ * @returns {ProjectCandidate[]}
+ */
+function discoverProjects(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    if (ent.name.startsWith('.')) continue;
+    if (HARNESS_DIR_SKIP.has(ent.name)) continue;
+
+    const projectPath = path.join(dir, ent.name);
+    const claudeDir = path.join(projectPath, '.claude');
+    if (!fs.existsSync(claudeDir)) continue;
+
+    const candidate = inspectProject(projectPath);
+    if (candidate) out.push(candidate);
+  }
+
+  return out;
+}
+
+/**
+ * Build a ProjectCandidate by reading .claude/HARNESS_VERSION + CLAUDE.md.
+ * @param {string} projectPath
+ * @returns {ProjectCandidate|null}
+ */
+function inspectProject(projectPath) {
+  const claudeDir = path.join(projectPath, '.claude');
+  const versionFile = path.join(claudeDir, 'HARNESS_VERSION');
+  const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+
+  let harnessVersion = null;
+  try {
+    harnessVersion = fs.readFileSync(versionFile, 'utf8').trim() || null;
+  } catch {
+    harnessVersion = null;
+  }
+
+  let projectType = null;
+  let primaryStack = null;
+  try {
+    const content = fs.readFileSync(claudeMdPath, 'utf8');
+    projectType = extractIdentityField(content, 'Project type');
+    primaryStack = extractIdentityField(content, 'Primary stack');
+  } catch {
+    // no CLAUDE.md or unreadable
+  }
+
+  let ageMs = 0;
+  try {
+    const stat = fs.statSync(claudeDir);
+    ageMs = Date.now() - stat.mtimeMs;
+  } catch {
+    ageMs = 0;
+  }
+
+  return {
+    name: path.basename(projectPath),
+    path: projectPath,
+    harnessVersion,
+    projectType,
+    primaryStack,
+    ageMs,
+  };
+}
+
+// ─── filter application ──────────────────────────────────────────────────────
+
+/**
+ * Check whether a project matches one parsed filter.
+ * @param {ProjectCandidate} proj
+ * @param {ParsedFilter} filter
+ * @returns {boolean}
+ */
+function matchesFilter(proj, filter) {
+  if (!filter) return true;
+  switch (filter.key) {
+    case 'stack': {
+      const stack = (proj.primaryStack || '').toLowerCase();
+      return stack.includes(String(filter.value));
+    }
+    case 'type': {
+      const t = (proj.projectType || '').toLowerCase();
+      return t === String(filter.value) || t.includes(String(filter.value));
+    }
+    case 'age': {
+      return proj.ageMs >= Number(filter.value);
+    }
+    case 'harness-version': {
+      if (!proj.harnessVersion) return false;
+      const expr = String(filter.value);
+      const cmp = compareVersions(proj.harnessVersion, expr);
+      // compareVersions returns -1 when the version satisfies the constraint
+      // (or 0 for "=X" matches)
+      return cmp <= 0;
+    }
+    default:
+      return true;
+  }
+}
+
+/**
+ * Apply all filters (AND) and excludes (NOT) to a candidate list.
+ * @param {ProjectCandidate[]} candidates
+ * @param {ParsedFilter[]} filters
+ * @param {string[]} excludes
+ * @returns {ProjectCandidate[]}
+ */
+function applyFilters(candidates, filters, excludes) {
+  const excludeSet = new Set((excludes || []).map((x) => x.toLowerCase()));
+  return candidates.filter((c) => {
+    if (excludeSet.has(c.name.toLowerCase())) return false;
+    return filters.every((f) => matchesFilter(c, f));
+  });
+}
+
+// ─── humanizers ──────────────────────────────────────────────────────────────
+
+/**
+ * Convert ageMs to a short human-readable string.
+ * @param {number} ms
+ * @returns {string}
+ */
+function humanAge(ms) {
+  if (!ms || ms < 0) return 'unknown';
+  const days = Math.floor(ms / (24 * 60 * 60 * 1000));
+  if (days < 1) return '<1d';
+  if (days < 30) return `${days}d`;
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months}m`;
+  const years = Math.floor(days / 365);
+  return `${years}y`;
+}
+
+// ─── runSyncAll ──────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{ filters: string[], excludes: string[], apply: boolean,
+ *             adopt?: (opts: {cwd: string, sub: string|null, dryRun: boolean}) => void }} SyncOptions
+ */
+
+/**
+ * Run sync-all over a directory.
+ *
+ * The `adopt` option lets the CLI inject its own adoptProject implementation
+ * (avoids a circular require with bin/cli.js). When omitted, lazy-loads
+ * `../cli.js#adoptProject`.
+ *
+ * @param {string} dir
+ * @param {SyncOptions} options
+ * @returns {{ matched: ProjectCandidate[], updated: number, skipped: number, errors: number }}
+ */
+function runSyncAll(dir, options) {
+  const opts = options || {};
+  const filterStrs = opts.filters || [];
+  const excludes = opts.excludes || [];
+  const apply = !!opts.apply;
+
+  if (!dir || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    process.stderr.write(`Error: directory "${dir}" not found or not a directory.\n`);
+    process.exit(1);
+  }
+
+  // Parse filters
+  const parsedFilters = [];
+  for (const f of filterStrs) {
+    const parsed = parseFilterExpr(f);
+    if (!parsed) {
+      process.stderr.write(`Warning: ignoring unrecognized filter "${f}"\n`);
+      continue;
+    }
+    parsedFilters.push(parsed);
+  }
+
+  // Discover + filter
+  const candidates = discoverProjects(dir);
+  const matched = applyFilters(candidates, parsedFilters, excludes);
+
+  // Print plan
+  process.stdout.write(`\nkud sync-all — scanning ${dir}\n`);
+  process.stdout.write(`Found ${candidates.length} project(s) with .claude/\n`);
+  if (parsedFilters.length) {
+    process.stdout.write(`Filters: ${filterStrs.join(', ')}\n`);
+  }
+  if (excludes.length) {
+    process.stdout.write(`Excludes: ${excludes.join(', ')}\n`);
+  }
+  process.stdout.write(`Matched ${matched.length} project(s)${apply ? '' : ' (dry-run)'}\n\n`);
+
+  if (matched.length === 0) {
+    process.stdout.write('Nothing to do.\n');
+    return { matched: [], updated: 0, skipped: 0, errors: 0 };
+  }
+
+  // Print table
+  for (const p of matched) {
+    process.stdout.write(
+      `  ${p.name.padEnd(30)} ` +
+        `v${(p.harnessVersion || '?').padEnd(8)} ` +
+        `${(p.projectType || '?').padEnd(15)} ` +
+        `age:${humanAge(p.ageMs).padEnd(6)} ` +
+        `${(p.primaryStack || '').slice(0, 40)}\n`
+    );
+  }
+
+  if (!apply) {
+    process.stdout.write('\nDry-run only. Re-run with --apply to perform updates.\n');
+    return { matched, updated: 0, skipped: 0, errors: 0 };
+  }
+
+  // Resolve adopt function (lazy require to avoid cycles)
+  let adopt = opts.adopt;
+  if (!adopt) {
+    try {
+      const cli = require('../cli');
+      adopt = cli.adoptProject;
+    } catch (e) {
+      process.stderr.write(`Error: could not load adoptProject from bin/cli.js — ${e.message}\n`);
+      return { matched, updated: 0, skipped: 0, errors: matched.length };
+    }
+  }
+
+  // Apply per project
+  let updated = 0;
+  let errors = 0;
+  process.stdout.write('\nApplying updates...\n');
+  for (const p of matched) {
+    try {
+      adopt({ cwd: p.path, sub: null, dryRun: false });
+      process.stdout.write(`  [OK]   ${p.name}\n`);
+      updated += 1;
+    } catch (e) {
+      process.stdout.write(`  [FAIL] ${p.name} — ${e.message}\n`);
+      errors += 1;
+    }
+  }
+
+  process.stdout.write(
+    `\nSummary: updated=${updated}, errors=${errors}, skipped=${matched.length - updated - errors}\n`
+  );
+  return { matched, updated, skipped: matched.length - updated - errors, errors };
+}
+
+module.exports = {
+  runSyncAll,
+  // exported for tests
+  parseDuration,
+  parseFilterExpr,
+  extractIdentityField,
+  discoverProjects,
+  inspectProject,
+  matchesFilter,
+  applyFilters,
+  humanAge,
+};