@eltonssouza/development-utility-kit 1.0.0

package/bin/lib/help.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * Help text for the duk CLI.
+ *
+ * Three modes:
+ *   - printGeneralHelp()     → full usage page (`duk help`)
+ *   - printCommandHelp(cmd)  → detailed help for one command
+ *   - printShortHelp()       → terse usage shown when called with no args
+ */
+
+const GENERAL_HELP = `\
+duk — development-utility-kit CLI
+
+Usage: duk <command> [options]
+
+COMMANDS
+  new <name>          Scaffold new project + open Cowork for conversational stack discovery
+  install             Inject harness into CWD (idempotent). Detects existing stack
+  update              Alias for install
+  sync-all <dir>      Update harness in multiple projects under <dir>. Default dry-run
+  dashboard           Start local telemetry dashboard (Express + Chart.js)
+  help [command]      Show this message, or detailed help for <command>
+
+COMMON OPTIONS
+  --help, -h          Show help (this or command-specific)
+  --version, -v       Show duk version
+
+COMMAND-SPECIFIC OPTIONS
+
+  install / update:
+    --sub <dir>       Install in subdirectory instead of CWD
+    --dry-run         Print actions without writing
+    --check-only      Show "local vs latest harness", do not update
+    --force           Skip drift detection (overwrite local modifications)
+
+  sync-all:
+    --apply           Execute updates (default: dry-run)
+    --filter <expr>   Filter projects (repeat for AND logic):
+                        stack:<lang|framework>      e.g. stack:java
+                        type:<value>                e.g. type:fullstack
+                        age:<duration>              e.g. age:30d, age:6m
+                        harness-version:<semver>    e.g. harness-version:<0.2
+    --exclude <name>  Exclude project by folder name (repeat)
+
+  dashboard:
+    --port <n>        Port to bind (default: 4242)
+    --no-open         Do not open browser automatically
+
+EXAMPLES
+  duk new my-app
+  duk install
+  duk install --check-only
+  duk sync-all C:\\development\\source\\projects --filter stack:java --apply
+  duk dashboard --port 4243
+
+Run \`duk help <command>\` for detailed information.`;
+
+const SHORT_HELP = `\
+duk — development-utility-kit CLI
+
+Usage: duk <command> [options]
+
+Commands: new | install | update | sync-all | dashboard | help
+
+Run \`duk help\` for full usage, or \`duk help <command>\` for command details.`;
+
+const COMMAND_HELP = {
+  new: `\
+duk new <name> — Scaffold a new project
+
+Creates a folder <name> in the CWD, initialises a git repo, writes a
+CLAUDE.md template with an empty Project Identity, and injects the
+harness (.claude/, CLAUDE.md, HARNESS_VERSION, MANIFEST, local/).
+
+Usage:
+  duk new <name>
+
+Arguments:
+  <name>              Project folder name (kebab-case recommended).
+                      Must not already exist.
+
+After running:
+  1. cd <name>
+  2. Open Cowork or Claude Code in the new folder
+  3. First message: "sabatina pra projeto novo"
+     → stack-discovery skill walks you through 8 questions and fills
+       the Project Identity block.
+
+Examples:
+  duk new my-app
+  duk new payment-gateway`,
+
+  install: `\
+duk install — Inject the harness into a project
+
+Detects the existing stack (pom.xml, package.json, etc.) and writes
+.claude/, CLAUDE.md (preserving ## Project Identity if present),
+HARNESS_VERSION, MANIFEST, and a .claude/local/ placeholder.
+
+Usage:
+  duk install [options]
+
+Options:
+  --sub <dir>       Install into <dir> instead of the CWD.
+  --dry-run         Print what would be done without writing.
+  --check-only      Detect stack + report local-vs-latest harness;
+                    do not write anything.
+  --force           Skip drift detection (overwrite local changes).
+                    A backup is still created.
+  --help, -h        Show this help.
+
+Drift detection:
+  install reads .claude/.MANIFEST (sha256 of every file from the prior
+  install). If any file was modified locally, install aborts and asks
+  you to either:
+    1. Move customisations to .claude/local/ (never touched), or
+    2. Run with --force to overwrite (backup is preserved), or
+    3. Open a PR on the harness repo if the change is canonical.
+
+Examples:
+  duk install
+  duk install --sub backend
+  duk install --check-only
+  duk install --force
+  duk install --dry-run`,
+
+  update: `\
+duk update — Alias for "duk install"
+
+Identical to \`duk install\`. Provided for ergonomics when you are
+updating an already-adopted project.
+
+See \`duk help install\` for full options.`,
+
+  'sync-all': `\
+duk sync-all <dir> — Batch update the harness in many projects
+
+Iterates over every folder under <dir> that contains a .claude/
+directory and runs duk install. Default is dry-run; pass --apply to
+execute.
+
+Usage:
+  duk sync-all <dir> [options]
+
+Options:
+  --apply             Execute the updates (default: dry-run preview).
+  --filter <expr>     Filter projects (repeat for AND logic):
+                        stack:<lang|framework>     e.g. stack:java
+                        type:<value>               e.g. type:fullstack
+                        age:<duration>             e.g. age:30d, age:6m
+                        harness-version:<semver>   e.g. harness-version:<0.2
+  --exclude <name>    Skip project by folder name (repeat for multiple).
+  --help, -h          Show this help.
+
+Examples:
+  duk sync-all C:\\development\\source\\projects
+  duk sync-all . --filter stack:java --apply
+  duk sync-all . --filter age:60d
+  duk sync-all . --exclude prod-critical --apply
+  duk sync-all . --filter harness-version:<0.2 --apply`,
+
+  dashboard: `\
+duk dashboard — Start the local telemetry dashboard
+
+Boots an Express server + Chart.js UI that visualises hook telemetry
+from the local harness.
+
+Usage:
+  duk dashboard [options]
+
+Options:
+  --port <n>        Port to bind to. Default: 4242.
+  --no-open         Do not open the browser automatically.
+  --help, -h        Show this help.
+
+Examples:
+  duk dashboard
+  duk dashboard --port 4243
+  duk dashboard --no-open`,
+
+  help: `\
+duk help [command] — Show help
+
+Usage:
+  duk help                Show full usage page.
+  duk help <command>      Show detailed help for <command>.
+  duk <command> --help    Same as \`duk help <command>\`.
+
+Commands with detailed help:
+  new, install, update, sync-all, dashboard, help`,
+};
+
+/**
+ * Write the full general help to stdout.
+ */
+function printGeneralHelp() {
+  process.stdout.write(GENERAL_HELP + '\n');
+}
+
+/**
+ * Write the short usage page to stdout (used when called with no args).
+ */
+function printShortHelp() {
+  process.stdout.write(SHORT_HELP + '\n');
+}
+
+/**
+ * Write detailed help for a single command. Falls back to general help
+ * if the command is unknown.
+ * @param {string} command
+ */
+function printCommandHelp(command) {
+  if (!command) {
+    printGeneralHelp();
+    return;
+  }
+  const normalised = command === 'update' ? 'update' : command;
+  const text = COMMAND_HELP[normalised];
+  if (!text) {
+    process.stderr.write(`Unknown command: ${command}\n\n`);
+    printGeneralHelp();
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(text + '\n');
+}
+
+module.exports = {
+  printGeneralHelp,
+  printShortHelp,
+  printCommandHelp,
+};

package/bin/lib/identity.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * CLAUDE.md `## Project Identity` helpers.
+ *
+ *   - generateIdentitySection(dr)   build a fresh Project Identity block
+ *   - readIdentitySection(content)  extract the existing block from CLAUDE.md
+ *   - mergeClaudeMd(...)            inject identity into the template body
+ *   - emptyIdentitySection(name)    placeholder identity for `duk new`
+ */
+
+const IDENTITY_HEADING = '## Project Identity';
+
+/**
+ * Build the Project Identity block pre-filled with detected values.
+ * @param {{ type: string, stackHints: string[] }} dr
+ * @returns {string}
+ */
+function generateIdentitySection(dr) {
+  const stackLine = dr.stackHints && dr.stackHints.length > 0
+    ? dr.stackHints.join(', ')
+    : '<ex: Java 25 + Spring Boot 4 + Angular 21>';
+  return `## Project Identity
+
+> **Modifique apenas esta seção ao adotar o plugin em um novo projeto.**
+> Todas as demais seções são base do plugin e não devem ser alteradas diretamente
+> — use \`update-template\` para receber atualizações.
+
+- **Project name**: \`<project-name>\`
+- **Project type**: \`${dr.type}\`
+- **Primary stack**: \`${stackLine}\`
+- **Database**: \`<ex: PostgreSQL 17 + Redis 7>\`
+- **Domain**: \`<ex: e-commerce, fintech, healthcare>\`
+- **Team size**: \`<ex: 3 backend, 2 frontend>\`
+- **Additional rules**: _(deixe vazio se não houver)_`;
+}
+
+/**
+ * Placeholder identity used by `duk new <name>`. All fields are TODO so
+ * the stack-discovery skill can fill them in via conversation.
+ * @param {string} name
+ * @returns {string}
+ */
+function emptyIdentitySection(name) {
+  return `## Project Identity
+
+> **Modifique apenas esta seção ao adotar o plugin em um novo projeto.**
+> Todas as demais seções são base do plugin e não devem ser alteradas diretamente
+> — use \`update-template\` para receber atualizações.
+
+- **Project name**: \`${name}\`
+- **Project type**: \`<TODO: backend | frontend | fullstack | mobile | library | cli | data-pipeline>\`
+- **Primary stack**: \`<TODO: declare via stack-discovery skill>\`
+- **Database**: \`<TODO>\`
+- **Domain**: \`<TODO>\`
+- **Team size**: \`<TODO>\`
+- **Additional rules**: _(deixe vazio se não houver)_`;
+}
+
+/**
+ * Extract the existing ## Project Identity section from a CLAUDE.md string.
+ * Returns the full section text (from the heading to before the next ## heading),
+ * or null if not found.
+ * @param {string} content
+ * @returns {string|null}
+ */
+function readIdentitySection(content) {
+  const startIdx = content.indexOf(IDENTITY_HEADING);
+  if (startIdx === -1) return null;
+
+  const afterHeading = content.indexOf('\n## ', startIdx + IDENTITY_HEADING.length);
+  if (afterHeading === -1) {
+    return content.slice(startIdx).trimEnd();
+  }
+  return content.slice(startIdx, afterHeading).trimEnd();
+}
+
+/**
+ * Merge: replace the template's ## Project Identity placeholder with the
+ * preserved or generated identity section.
+ * @param {string} existing  - current file content (may be empty, kept for symmetry)
+ * @param {string} template  - template content from package
+ * @param {string} identity  - identity section text to inject
+ * @returns {string}
+ */
+function mergeClaudeMd(existing, template, identity) {
+  const templateStartIdx = template.indexOf(IDENTITY_HEADING);
+  if (templateStartIdx === -1) {
+    return identity + '\n\n' + template;
+  }
+
+  const afterHeading = template.indexOf('\n## ', templateStartIdx + IDENTITY_HEADING.length);
+  let rest;
+  if (afterHeading === -1) {
+    rest = '';
+  } else {
+    rest = template.slice(afterHeading);
+  }
+  return identity + rest;
+}
+
+module.exports = {
+  IDENTITY_HEADING,
+  generateIdentitySection,
+  emptyIdentitySection,
+  readIdentitySection,
+  mergeClaudeMd,
+};

package/bin/lib/local-dir.js

@@ -0,0 +1,69 @@
+'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:
+  - "Prefiro outro estilo" → Honcho (\`lembra que prefiro X\`)
+  - 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,
+};