@eltonssouza/development-utility-kit 0.10.0

package/bin/lib/help.js

@@ -0,0 +1,328 @@
+'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)
+  doctor              Validate environment (Node, git, paths, hooks, packs, credentials)
+  lint                Validate harness .claude/ structure (frontmatter, refs, ADRs, packs)
+  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
+
+  doctor:
+    --json            Machine-readable JSON output
+    --strict          Exit non-zero on WARN too (default: only FAIL fails)
+
+  lint:
+    --json            Machine-readable JSON output
+    --category <name> Run only one category (comma-separated for many):
+                        skills, agents, refs, adrs, stacks, d1-contract
+
+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
+  duk doctor
+  duk doctor --strict
+  duk lint
+  duk lint --category skills,agents
+
+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 | doctor | lint | 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`,
+
+  doctor: `\
+duk doctor — Validate the environment
+
+Mechanical, deterministic check (no LLM, no API calls). Per ADR-034
+("Mecânico → CLI"), validates everything needed for the harness to
+work day-to-day. Safe to run anywhere.
+
+Usage:
+  duk doctor [options]
+
+Options:
+  --json              Machine-readable JSON output (good for CI).
+  --strict            Exit non-zero on WARN too (default: only FAIL fails).
+  --help, -h          Show this help.
+
+Checks (categories):
+  environment         Node >= 18, git, npx, python availability.
+  harness             .claude/{agents,skills,stacks}, CLAUDE.md,
+                      package.json, bin/cli.js exist.
+  settings            ~/.claude/settings.json is valid JSON + hook
+                      command paths point to existing files.
+  stacks              .claude/stacks/ has packs + README index.
+  credentials         C:\\development\\tools\\credentials\\vps.txt
+                      present (warn-only — not fatal).
+  project             If CWD is an adopted project: .MANIFEST exists +
+                      Project Identity is filled (not placeholder).
+
+Exit code:
+  0   all PASS, or only WARN (unless --strict)
+  1   any FAIL, or any WARN with --strict
+
+Examples:
+  duk doctor
+  duk doctor --strict
+  duk doctor --json | jq .summary`,
+
+  lint: `\
+duk lint — Validate the harness .claude/ structure
+
+Mechanical, deterministic check (no LLM, no API calls). Per ADR-034
+("Mecânico → CLI"), validates structural correctness of skills,
+agents, ADRs, and stack packs. Replaces scripts/lint-harness.mjs.
+
+Usage:
+  duk lint [options]
+
+Options:
+  --json              Machine-readable JSON output (good for CI).
+  --category <name>   Run only one category. Comma-separated for many.
+                      Valid: skills, agents, refs, adrs, stacks, d1-contract
+  --help, -h          Show this help.
+
+Categories:
+  skills              SKILL.md frontmatter: required fields
+                      (name, description, tools, model) + name matches
+                      directory.
+  agents              Agent .md frontmatter: required fields
+                      (name, description, model) + name matches file.
+  refs                Agents mentioned in skill routing tables exist
+                      in .claude/agents/.
+  adrs                ADRs referenced across decisions exist
+                      + numbering gaps reported.
+  stacks              Each stack pack has the recommended sections
+                      (Build & run, Code patterns, Anti-patterns,
+                      Security, Testing).
+  d1-contract         Pattern 1 pairs (skill↔agent share name):
+                      skill body forbids "checklist/golden rule/
+                      inviolable rules" sections; agent body forbids
+                      "PT triggers:" sections.
+
+Exit code:
+  0   no ERROR found
+  1   at least one ERROR (WARN never fails the exit code)
+
+Examples:
+  duk lint
+  duk lint --category skills
+  duk lint --category adrs,refs
+  duk lint --json > lint-report.json`,
+
+  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, doctor, lint, 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/lint-allowlist.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "internal — consumed by bin/lib/lint.js",
+  "_doc": "Known intentional gaps and exemptions for duk lint. Edit only when adding a documented exception with rationale.",
+
+  "adr-gaps-known": [
+    "001",
+    "002",
+    "003",
+    "004",
+    "005",
+    "006",
+    "009"
+  ],
+  "_adr-gaps-known-rationale": "ADRs 001-006 were deleted in early Hermes housekeeping commits; ADR-009 was deleted by design (no live reference in CLAUDE.md). Recorded in docs/brain/architecture/tech-debt.md Item 4 (rodada 2026-05-27) and Item 20 (rodada 2026-05-28)."
+}