@abarcenas/ai-workflow-template 1.28.0 → 1.32.0

package/scripts/setup/discover.test.js

@@ -0,0 +1,388 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// discover.test.js — Unit tests for the discover module
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// ── Mock utils: environment-dependent functions; keep fs helpers real ─────
+
+/** Mutable variable so the mock factory can return different roots per test */
+let mockConsumerRoot = ''
+
+vi.mock('./utils.js', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getConsumerRoot: () => mockConsumerRoot,
+    getNodeVersion: vi.fn(() => 20),
+    isCI: vi.fn(() => false),
+  }
+})
+
+import { discover } from './discover.js'
+import { HOOK_MARKER, TEMPLATE_HOOKS } from './constants.js'
+import { getNodeVersion, isCI } from './utils.js'
+
+// ── Test helpers ──────────────────────────────────────────────────────────
+
+const tempDirs = new Set()
+
+/**
+ * Creates a temporary project directory with a configurable structure.
+ *
+ * @param {object}   opts
+ * @param {boolean}  [opts.git=true]        – Create a `.git/` directory
+ * @param {boolean}  [opts.huskyDir=false]  – Create a `.husky/` directory
+ * @param {object|boolean} [opts.packageJson=true] – `false` = skip, object = custom
+ * @param {object}   [opts.hooks={}]        – Map of hook filename → content
+ * @returns {string} Path to the created temp directory.
+ */
+function createProject(opts = {}) {
+  const {
+    git = true,
+    huskyDir = false,
+    packageJson = true,
+    hooks = {},
+  } = opts
+
+  const dir = mkdtempSync(join(tmpdir(), 'discover-test-'))
+  tempDirs.add(dir)
+
+  if (git) mkdirSync(join(dir, '.git'), { recursive: true })
+  if (huskyDir) mkdirSync(join(dir, '.husky'), { recursive: true })
+  if (packageJson) {
+    const pkg =
+      typeof packageJson === 'object' ? packageJson : { name: 'test-pkg' }
+    writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg))
+  }
+  for (const [name, content] of Object.entries(hooks)) {
+    const hookDir = join(dir, '.husky')
+    if (!existsSync(hookDir)) mkdirSync(hookDir, { recursive: true })
+    writeFileSync(join(hookDir, name), content)
+  }
+
+  return dir
+}
+
+function cleanupTempDirs() {
+  for (const dir of tempDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true })
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+  tempDirs.clear()
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe('discover()', () => {
+  beforeEach(() => {
+    vi.mocked(getNodeVersion).mockReturnValue(20)
+    vi.mocked(isCI).mockReturnValue(false)
+  })
+
+  afterEach(() => {
+    cleanupTempDirs()
+  })
+
+  // ── 1. Fresh project (no .husky/) ──────────────────────────────────────
+
+  it('should detect a fresh project with git but no .husky/ directory', async () => {
+    const dir = createProject({ git: true, huskyDir: false })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.consumerRoot).toBe(dir)
+    expect(ctx.hasGit).toBe(true)
+    expect(ctx.hasHuskyDir).toBe(false)
+    for (const name of Object.keys(TEMPLATE_HOOKS)) {
+      expect(ctx.existingHooks[name].exists).toBe(false)
+    }
+    expect(ctx.hasPackageJson).toBe(true)
+    expect(ctx.isCI).toBe(false)
+    expect(ctx.nodeVersion).toBe(20)
+    expect(ctx.dryRun).toBe(false)
+  })
+
+  // ── 2. Project with .husky/ but no hooks ───────────────────────────────
+
+  it('should detect .husky/ directory but no hook files inside', async () => {
+    const dir = createProject({ huskyDir: true, hooks: {} })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.hasHuskyDir).toBe(true)
+    for (const name of Object.keys(TEMPLATE_HOOKS)) {
+      expect(ctx.existingHooks[name].exists).toBe(false)
+      expect(ctx.existingHooks[name].content).toBeNull()
+      expect(ctx.existingHooks[name].isManaged).toBe(false)
+    }
+  })
+
+  // ── 3. Existing unmanaged hooks ────────────────────────────────────────
+
+  it('should detect unmanaged hooks (first line is NOT the HOOK_MARKER)', async () => {
+    const dir = createProject({
+      huskyDir: true,
+      hooks: { 'pre-commit': '#!/bin/sh\necho "custom hook"\n' },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    const h = ctx.existingHooks['pre-commit']
+    expect(h.exists).toBe(true)
+    expect(h.content).toBe('#!/bin/sh\necho "custom hook"\n')
+    expect(h.isManaged).toBe(false)
+  })
+
+  // ── 4. Existing managed hooks ──────────────────────────────────────────
+
+  it('should detect managed hooks (first line matches HOOK_MARKER)', async () => {
+    const dir = createProject({
+      huskyDir: true,
+      hooks: { 'pre-commit': `${HOOK_MARKER}\n\necho "managed hook"\n` },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    const h = ctx.existingHooks['pre-commit']
+    expect(h.exists).toBe(true)
+    expect(h.isManaged).toBe(true)
+  })
+
+  // ── 5. No package.json ─────────────────────────────────────────────────
+
+  it('should handle a project with no package.json', async () => {
+    const dir = createProject({
+      git: true,
+      huskyDir: false,
+      packageJson: false,
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.hasPackageJson).toBe(false)
+    expect(ctx.consumerPackageJson).toBeNull()
+    expect(ctx.existingPrepare).toBeNull()
+  })
+
+  // ── 6. Package.json with no prepare script ─────────────────────────────
+
+  it('should set existingPrepare=null when prepare script is missing', async () => {
+    const dir = createProject({
+      packageJson: { name: 'test', scripts: {} },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.existingPrepare).toBeNull()
+  })
+
+  // ── 7. Simple prepare script ───────────────────────────────────────────
+
+  it('should detect a simple prepare script and classify as simple', async () => {
+    const dir = createProject({
+      packageJson: { scripts: { prepare: 'npm run build' } },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.existingPrepare).toBe('npm run build')
+    expect(ctx.prepareIsSimple).toBe(true)
+  })
+
+  // ── 8. Complex prepare (multi-line) ────────────────────────────────────
+
+  it('should classify a multi-line prepare script as complex', async () => {
+    const dir = createProject({
+      packageJson: { scripts: { prepare: 'echo "line1"\necho "line2"' } },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.prepareIsSimple).toBe(false)
+  })
+
+  // ── 9. Prepare already containing "husky" ──────────────────────────────
+
+  it('should detect prepare script set to exactly "husky"', async () => {
+    const dir = createProject({
+      packageJson: { scripts: { prepare: 'husky' } },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.existingPrepare).toBe('husky')
+    expect(ctx.prepareIsSimple).toBe(true)
+  })
+
+  // ── 10. CI environment ─────────────────────────────────────────────────
+
+  it('should detect CI environment when isCI() returns true', async () => {
+    vi.mocked(isCI).mockReturnValue(true)
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.isCI).toBe(true)
+  })
+
+  // ── 11. Non-CI environment ─────────────────────────────────────────────
+
+  it('should detect non-CI environment when isCI() returns false', async () => {
+    vi.mocked(isCI).mockReturnValue(false)
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.isCI).toBe(false)
+  })
+
+  // ── 12. Node version detection ─────────────────────────────────────────
+
+  it('should report the correct Node.js major version', async () => {
+    vi.mocked(getNodeVersion).mockReturnValue(18)
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.nodeVersion).toBe(18)
+  })
+
+  // ── 13. dryRun flag passthrough ────────────────────────────────────────
+
+  it('should set dryRun=true when the dryRun flag is passed', async () => {
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover({ dryRun: true })
+
+    expect(ctx.dryRun).toBe(true)
+  })
+
+  it('should set dryRun=false by default', async () => {
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.dryRun).toBe(false)
+  })
+
+  // ── 14. Complex prepare with `||` ──────────────────────────────────────
+
+  it('should classify a prepare script containing || as complex', async () => {
+    const dir = createProject({
+      packageJson: { scripts: { prepare: 'cmd1 || cmd2' } },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.prepareIsSimple).toBe(false)
+  })
+
+  // ── 15. Complex prepare with `;` ───────────────────────────────────────
+
+  it('should classify a prepare script containing ; as complex', async () => {
+    const dir = createProject({
+      packageJson: { scripts: { prepare: 'cmd1; cmd2' } },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.prepareIsSimple).toBe(false)
+  })
+
+  // ── 16. No git repository ──────────────────────────────────────────────
+
+  it('should set hasGit=false when no .git/ directory exists', async () => {
+    const dir = createProject({ git: false })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.hasGit).toBe(false)
+  })
+
+  // ── 17. Both hooks detected ────────────────────────────────────────────
+
+  it('should detect both pre-commit and post-merge hooks', async () => {
+    const dir = createProject({
+      huskyDir: true,
+      hooks: {
+        'pre-commit': `${HOOK_MARKER}\n\necho "pre"\n`,
+        'post-merge': `${HOOK_MARKER}\n#!/bin/sh\necho "post"\n`,
+      },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.existingHooks['pre-commit'].exists).toBe(true)
+    expect(ctx.existingHooks['post-merge'].exists).toBe(true)
+    expect(ctx.existingHooks['post-merge'].isManaged).toBe(true)
+  })
+
+  // ── 18. Empty prepare string ───────────────────────────────────────────
+
+  it('should treat an empty string prepare script as null', async () => {
+    const dir = createProject({
+      packageJson: { scripts: { prepare: '' } },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.existingPrepare).toBeNull()
+  })
+
+  // ── 19. Consumer package JSON content ──────────────────────────────────
+
+  it('should correctly parse consumer package.json content', async () => {
+    const pkg = { name: 'test-pkg', version: '1.0.0', scripts: { test: 'vitest' } }
+    const dir = createProject({ packageJson: pkg })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.hasPackageJson).toBe(true)
+    expect(ctx.consumerPackageJson).toEqual(pkg)
+  })
+
+  // ── 20. Post-merge hook content ────────────────────────────────────────
+
+  it('should correctly detect post-merge hook content and managed flag', async () => {
+    const content = `${HOOK_MARKER}\n#!/bin/sh\necho "custom post-merge"\n`
+    const dir = createProject({
+      huskyDir: true,
+      hooks: { 'post-merge': content },
+    })
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    const h = ctx.existingHooks['post-merge']
+    expect(h.exists).toBe(true)
+    expect(h.content).toBe(content)
+    expect(h.isManaged).toBe(true)
+  })
+})

package/scripts/setup/hooks.js

@@ -0,0 +1,261 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// hooks.js — Hook installation and merging for the setup command pipeline
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Implements the 6-case merge algorithm for installing template git hooks
+// (pre-commit, post-merge) into a consumer project's .husky/ directory:
+//
+//   Case A : No .husky/ directory           → Create + write
+//   Case B : No existing hook file          → Write
+//   Case C : Existing, isManaged (= ours)   → Overwrite (idempotent re-run)
+//   Case D : Existing, not ours, --force    → Backup + overwrite
+//   Case E : Existing, not ours, no --force → Append with separator
+//   Case F : dry-run mode                   → Log only, no writes
+//
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { resolve } from 'path'
+
+import { HOOK_MARKER, HOOK_MERGE_SEPARATOR, TEMPLATE_HOOKS } from './constants.js'
+import {
+  chmodX,
+  ensureDir,
+  safeReadFile,
+  safeWriteFile,
+} from './utils.js'
+import {
+  dryRunBanner,
+  step,
+  stepError,
+  stepSuccess,
+  stepWarn,
+} from './ui.js'
+
+// ── Content builder ──────────────────────────────────────────────────────────
+
+/**
+ * Builds the final content for a hook file.
+ *
+ * The marker comment (`HOOK_MARKER`) is placed on the very first line for
+ * idempotency detection.  The template hook content from `TEMPLATE_HOOKS`
+ * follows immediately.
+ *
+ * @param {string} hookName - Key from `TEMPLATE_HOOKS` (e.g. `'pre-commit'`).
+ * @returns {string} Complete file content with the marker as line 1.
+ *
+ * @example
+ * buildHookContent('pre-commit')
+ * // → "# Managed by @abarcenas/ai-workflow-template setup\nnode scripts/bump-version.js\n..."
+ */
+function buildHookContent(hookName) {
+  const template = TEMPLATE_HOOKS[hookName]
+  // The `content` field is always a string in our constants (pre-composed).
+  const raw = template.content
+  // Marker is first line, then content.
+  return HOOK_MARKER + '\n' + raw
+}
+
+// ── Hook file path helper ────────────────────────────────────────────────────
+
+/**
+ * Returns the absolute path to a hook file inside the consumer's `.husky/`
+ * directory.
+ *
+ * @param {string} consumerRoot - Consumer project root.
+ * @param {string} hookName     - Hook filename (e.g. `'pre-commit'`).
+ * @returns {string} Absolute path.
+ */
+function hookPath(consumerRoot, hookName) {
+  return resolve(consumerRoot, '.husky', hookName)
+}
+
+// ── Dry-run result helper ────────────────────────────────────────────────────
+
+/**
+ * Determines what action *would* be taken for a hook, without performing any
+ * writes.  Used exclusively by dry-run mode (Case F) and also provides the
+ * human-readable message for the result entry.
+ *
+ * @param {object} context   - Context object from `discover.js`.
+ * @param {string} hookName  - Key from `TEMPLATE_HOOKS`.
+ * @returns {{ action: string, message: string }}
+ */
+function dryRunResult(context, hookName) {
+  const hook = context.existingHooks?.[hookName]
+  const hasHuskyDir = !!context.hasHuskyDir
+  const existing = hook?.exists ?? false
+  const isManaged = hook?.isManaged ?? false
+  const force = !!(context.force || context.flags?.force)
+  const desc = TEMPLATE_HOOKS[hookName]?.description ?? ''
+
+  if (!hasHuskyDir) {
+    return {
+      action: 'dry-run',
+      message: `Would create .husky/ and ${hookName} hook (${desc})`,
+    }
+  }
+  if (!existing) {
+    return {
+      action: 'dry-run',
+      message: `Would write ${hookName} hook (${desc})`,
+    }
+  }
+  if (isManaged) {
+    return {
+      action: 'dry-run',
+      message: `Would overwrite existing ${hookName} hook (idempotent update, ${desc})`,
+    }
+  }
+  if (force) {
+    return {
+      action: 'dry-run',
+      message: `Would back up existing ${hookName} hook and overwrite with force (${desc})`,
+    }
+  }
+  // Case E equivalent in dry-run
+  return {
+    action: 'dry-run',
+    message: `Would append to existing ${hookName} hook (${desc})`,
+  }
+}
+
+// ── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * Installs or merges template hooks into the consumer project's `.husky/`
+ * directory.
+ *
+ * Implements the **6-case merge algorithm** per the setup command design
+ * (§4.3).  Each hook in `TEMPLATE_HOOKS` (pre-commit, post-merge) is processed
+ * independently:
+ *
+ * | Case | Condition                                    | Action                      | Result key  |
+ * |------|----------------------------------------------|-----------------------------|-------------|
+ * | A    | No `.husky/` directory                       | Create dir + write hook     | `created`   |
+ * | B    | No existing hook file                        | Write hook file             | `created`   |
+ * | C    | Hook exists + `isManaged` (= ours)           | Overwrite (idempotent)      | `overwritten` |
+ * | D    | Hook exists + not ours + `--force`           | Backup `.bak` + overwrite   | `overwritten` |
+ * | E    | Hook exists + not ours + no `--force`        | Append with separator       | `merged`    |
+ * | F    | `context.dryRun` is `true`                   | Log only, no writes         | `dry-run`   |
+ *
+ * Every operation is wrapped in a try/catch.  A failure for one hook does not
+ * prevent the other from being processed.
+ *
+ * @param {object} context - Context object from `discover.js`.
+ * @param {string} context.consumerRoot - Absolute path to consumer project root.
+ * @param {boolean} [context.hasHuskyDir] - Whether `.husky/` already exists.
+ * @param {Record<string, {exists: boolean, content: string|null, isManaged: boolean}>}
+ *        [context.existingHooks] - Descriptors for each hook.
+ * @param {boolean} [context.dryRun] - When `true`, no files are modified.
+ * @param {boolean} [context.force] - When `true`, existing hooks are overwritten.
+ * @param {{force?: boolean}} [context.flags] - Parsed CLI flags (alternative to
+ *        `context.force`).
+ * @returns {Promise<Array<{hook: string, action: string, message: string}>>}
+ *          A result entry for each hook in `TEMPLATE_HOOKS`.
+ *
+ * @example
+ * ```js
+ * const ctx = await discover({ dryRun: true })
+ * const results = await installHooks(ctx)
+ * // → [{ hook: 'pre-commit', action: 'dry-run', message: '...' }, ...]
+ * ```
+ */
+export async function installHooks(context) {
+  const hookNames = Object.keys(TEMPLATE_HOOKS)
+  const results = []
+
+  // ── Case F: dry-run mode ────────────────────────────────────────────
+  if (context.dryRun) {
+    dryRunBanner()
+
+    for (const hookName of hookNames) {
+      const r = dryRunResult(context, hookName)
+      step(r.message)
+      results.push({ hook: hookName, action: 'dry-run', message: r.message })
+    }
+
+    return results
+  }
+
+  // ── Process each hook ───────────────────────────────────────────────
+  for (const hookName of hookNames) {
+    const hookInfo = context.existingHooks?.[hookName]
+    const hasHuskyDir = !!context.hasHuskyDir
+    const existing = hookInfo?.exists ?? false
+    const isManaged = hookInfo?.isManaged ?? false
+    const force = !!(context.force || context.flags?.force)
+    const desc = TEMPLATE_HOOKS[hookName]?.description ?? ''
+    const target = hookPath(context.consumerRoot, hookName)
+    const content = buildHookContent(hookName)
+
+    try {
+      // ── Case A: No .husky/ directory — create it and write hook ──
+      if (!hasHuskyDir) {
+        ensureDir(resolve(context.consumerRoot, '.husky'))
+        safeWriteFile(target, content)
+        chmodX(target)
+        const msg = `${hookName} hook created (\u2713 ${desc})`
+        stepSuccess(msg)
+        results.push({ hook: hookName, action: 'created', message: msg })
+        continue
+      }
+
+      // ── Case B: .husky/ exists but no hook file ─────────────────
+      if (!existing) {
+        safeWriteFile(target, content)
+        chmodX(target)
+        const msg = `${hookName} hook created (\u2713 ${desc})`
+        stepSuccess(msg)
+        results.push({ hook: hookName, action: 'created', message: msg })
+        continue
+      }
+
+      // ── Case C: Hook exists AND is managed by us — overwrite ────
+      if (isManaged) {
+        safeWriteFile(target, content)
+        chmodX(target)
+        const msg = `${hookName} hook overwritten (idempotent update, ${desc})`
+        stepSuccess(msg)
+        results.push({ hook: hookName, action: 'overwritten', message: msg })
+        continue
+      }
+
+      // ── Case D: Hook exists, not ours, --force — back up + overwrite
+      if (force) {
+        const bakPath = target + '.bak'
+        const originalContent = safeReadFile(target)
+        safeWriteFile(bakPath, originalContent ?? '')
+        safeWriteFile(target, content)
+        chmodX(target)
+        const msg =
+          `${hookName} hook overwritten (original backed up to .bak, ${desc})`
+        stepSuccess(msg)
+        results.push({ hook: hookName, action: 'overwritten', message: msg })
+        continue
+      }
+
+      // ── Case E: Hook exists, not ours, no --force — append ──────
+      const existingContent = safeReadFile(target)
+      const mergedContent =
+        (existingContent ?? '') + '\n' + HOOK_MERGE_SEPARATOR + '\n' + content
+      safeWriteFile(target, mergedContent)
+      chmodX(target)
+      const msg = `${hookName} hook merged with existing content (${desc})`
+      stepSuccess(msg)
+      results.push({ hook: hookName, action: 'merged', message: msg })
+    } catch (err) {
+      // Any error during file operations (permission denied, .husky/
+      // is a file not a directory, read-only filesystem, etc.) is
+      // caught here — non-fatal for the other hook.
+      const errMsg = `${hookName} hook: ${err.message}`
+      stepError(errMsg)
+      results.push({
+        hook: hookName,
+        action: 'skipped',
+        message: errMsg,
+      })
+    }
+  }
+
+  return results
+}