@abarcenas/ai-workflow-template 1.29.0 → 1.33.0

package/scripts/setup/discover.js

@@ -0,0 +1,261 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// discover.js — Consumer project state detection for the setup command pipeline
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { resolve } from 'path'
+
+import { HOOK_MARKER, TEMPLATE_HOOKS } from './constants.js'
+import {
+  dirExists,
+  getConsumerRoot,
+  getNodeVersion,
+  isCI,
+  safeReadFile,
+  safeReadJson,
+} from './utils.js'
+
+import { verbose } from './ui.js'
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a default hook descriptor for cases where detection fails.
+ *
+ * @returns {{ exists: boolean, content: null, isManaged: boolean }}
+ */
+function defaultHookEntry() {
+  return { exists: false, content: null, isManaged: false }
+}
+
+/**
+ * Builds a minimal Context object with every property initialised to a safe
+ * default.  Callers can always destructure the returned Context without
+ * checking for undefined.
+ *
+ * @param {object} [flags={}]
+ * @returns {Context}
+ */
+function createDefaultContext(flags = {}) {
+  /** @type {Record<string, { exists: boolean, content: string|null, isManaged: boolean }>} */
+  const existingHooks = {}
+  for (const name of Object.keys(TEMPLATE_HOOKS)) {
+    existingHooks[name] = defaultHookEntry()
+  }
+
+  return {
+    consumerRoot: '',
+    hasGit: false,
+    hasHuskyDir: false,
+    hasPackageJson: false,
+    consumerPackageJson: null,
+    existingHooks,
+    existingPrepare: null,
+    prepareIsSimple: false,
+    isCI: false,
+    nodeVersion: 0,
+    dryRun: !!flags.dryRun,
+    verbose: !!flags.verbose,
+  }
+}
+
+// ── Prepare script classifier ────────────────────────────────────────────────
+
+/**
+ * Determines whether an existing `prepare` script is "simple" enough for
+ * automatic `&& husky` appending.
+ *
+ * A script is considered **simple** when it is a single-line command or a basic
+ * `&&` chain.  It is **complex** (and will not be auto-merged) when any of
+ * these apply:
+ *
+ *   - Multi-line (contains `\n`)
+ *   - Contains the `||` (OR) operator
+ *   - Contains a semicolon `;` command separator
+ *
+ * @param {string|null} prepare - The current `prepare` script value.
+ * @returns {boolean} `true` if auto-merge is safe.
+ */
+function isPrepareSimple(prepare) {
+  if (typeof prepare !== 'string' || prepare.trim() === '') return false
+
+  const val = prepare.trim()
+  if (val.includes('\n')) return false
+  if (val.includes('||')) return false
+  if (val.includes(';')) return false
+
+  return true
+}
+
+// ── Hook detection helpers ───────────────────────────────────────────────────
+
+/**
+ * Reads a single hook file from the consumer's `.husky/` directory and returns
+ * a descriptor containing the existence, raw content, and managed status.
+ *
+ * A hook is considered **managed** when its very first line (trimmed) matches
+ * the `HOOK_MARKER` constant.
+ *
+ * @param {string} consumerRoot - Absolute path to the consumer project root.
+ * @param {string} hookName     - Hook filename (e.g. `'pre-commit'`).
+ * @returns {{ exists: boolean, content: string|null, isManaged: boolean }}
+ */
+function detectHook(consumerRoot, hookName) {
+  try {
+    const hookPath = resolve(consumerRoot, '.husky', hookName)
+    const content = safeReadFile(hookPath)
+    const exists = content !== null
+
+    if (!exists) return { exists, content: null, isManaged: false }
+
+    const firstLine = content.split('\n')[0]
+    const isManaged =
+      firstLine != null && firstLine.trim() === HOOK_MARKER
+
+    return { exists, content, isManaged }
+  } catch {
+    return defaultHookEntry()
+  }
+}
+
+// ── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * Discovers the consumer project's state and returns a Context object.
+ *
+ * The returned Context captures the environment before any modifications are
+ * made, so the orchestrator (and downstream pipeline modules) can decide which
+ * phases to run and how to handle each edge case.
+ *
+ * All detection steps are wrapped in individual try/catch blocks so that a
+ * failure in one area (e.g., reading package.json) does not prevent the rest
+ * of the discovery from completing.  The Context is **always** returned, even
+ * if every detection step fails.
+ *
+ * @param {object} [flags={}] - Parsed CLI flags from `parseCliArgs()`.
+ * @param {boolean} [flags.dryRun] - When `true`, discovery notes dry-run mode.
+ * @returns {Promise<Context>} Resolved context object.
+ *
+ * @example
+ * ```js
+ * import { parseCliArgs } from './utils.js'
+ * import { discover } from './discover.js'
+ *
+ * const flags = parseCliArgs(process.argv.slice(2))
+ * const ctx = await discover(flags)
+ * console.log(ctx.hasGit) // true / false
+ * ```
+ */
+export async function discover(flags = {}) {
+  const ctx = createDefaultContext(flags)
+  const verboseEnabled = !!flags.verbose
+
+  // ── 1. Resolve consumer root ──────────────────────────────────────────
+  verbose(verboseEnabled, 'Resolving consumer root from INIT_CWD\u2026')
+  try {
+    ctx.consumerRoot = getConsumerRoot()
+  } catch {
+    // If consumerRoot cannot be resolved we return early — no further
+    // detection is possible without a target directory.
+    ctx.nodeVersion = getNodeVersion()
+    ctx.isCI = isCI()
+    return ctx
+  }
+
+  if (!ctx.consumerRoot) {
+    ctx.nodeVersion = getNodeVersion()
+    ctx.isCI = isCI()
+    return ctx
+  }
+
+  // ── 2. Detect git repository ──────────────────────────────────────────
+  verbose(verboseEnabled, 'Checking for .git directory\u2026')
+  try {
+    ctx.hasGit = dirExists(resolve(ctx.consumerRoot, '.git'))
+    verbose(verboseEnabled, ctx.hasGit ? 'Git repository found' : 'No git repository')
+  } catch {
+    // Non-fatal — hasGit stays false
+  }
+
+  // ── 3. Detect .husky/ directory ───────────────────────────────────────
+  verbose(verboseEnabled, 'Checking for .husky/ directory\u2026')
+  try {
+    ctx.hasHuskyDir = dirExists(resolve(ctx.consumerRoot, '.husky'))
+    verbose(verboseEnabled, ctx.hasHuskyDir ? '.husky/ directory found' : '.husky/ directory not found')
+  } catch {
+    // Non-fatal — hasHuskyDir stays false
+  }
+
+  // ── 4. Detect + parse package.json ────────────────────────────────────
+  verbose(verboseEnabled, 'Reading package.json\u2026')
+  try {
+    const pkgPath = resolve(ctx.consumerRoot, 'package.json')
+    const pkg = safeReadJson(pkgPath)
+    ctx.hasPackageJson = pkg !== undefined
+    ctx.consumerPackageJson = pkg ?? null
+    verbose(verboseEnabled, ctx.hasPackageJson ? 'package.json found' : 'package.json not found')
+  } catch {
+    // Non-fatal — hasPackageJson stays false, consumerPackageJson stays null
+  }
+
+  // ── 5. Detect existing hooks ──────────────────────────────────────────
+  // existingHooks is pre-initialised by createDefaultContext() so the loop
+  // below only overrides the entries it successfully reads.  Any hook that
+  // cannot be read keeps its safe default (exists: false).
+  verbose(verboseEnabled, 'Detecting existing hooks\u2026')
+  try {
+    for (const hookName of Object.keys(TEMPLATE_HOOKS)) {
+      ctx.existingHooks[hookName] = detectHook(ctx.consumerRoot, hookName)
+      const hook = ctx.existingHooks[hookName]
+      if (hook.exists) {
+        verbose(verboseEnabled, `${hookName}: ${hook.isManaged ? 'managed' : 'found (unmanaged)'}`)
+      } else {
+        verbose(verboseEnabled, `${hookName}: not found`)
+      }
+    }
+  } catch {
+    // Non-fatal — existingHooks already contains default entries
+  }
+
+  // ── 6. Extract existing prepare script ────────────────────────────────
+  verbose(verboseEnabled, 'Extracting prepare script\u2026')
+  try {
+    const prepare = ctx.consumerPackageJson?.scripts?.prepare
+    ctx.existingPrepare =
+      typeof prepare === 'string' && prepare.trim().length > 0
+        ? prepare.trim()
+        : null
+    verbose(verboseEnabled, ctx.existingPrepare ? `Prepare script: ${ctx.existingPrepare}` : 'No prepare script')
+  } catch {
+    // Non-fatal — existingPrepare stays null
+  }
+
+  // ── 7. Classify prepare script simplicity ─────────────────────────────
+  try {
+    ctx.prepareIsSimple = isPrepareSimple(ctx.existingPrepare)
+  } catch {
+    ctx.prepareIsSimple = false
+  }
+
+  // ── 8. Detect CI environment ──────────────────────────────────────────
+  verbose(verboseEnabled, 'Detecting CI environment\u2026')
+  try {
+    ctx.isCI = isCI()
+    verbose(verboseEnabled, ctx.isCI ? 'CI detected' : 'Not CI')
+  } catch {
+    ctx.isCI = false
+  }
+
+  // ── 9. Detect Node.js version ─────────────────────────────────────────
+  verbose(verboseEnabled, 'Detecting Node.js version\u2026')
+  try {
+    ctx.nodeVersion = getNodeVersion()
+    verbose(verboseEnabled, `Node.js v${ctx.nodeVersion}`)
+  } catch {
+    ctx.nodeVersion = 0
+  }
+
+  // NOTE: `ctx.dryRun` is already set by createDefaultContext(flags)
+
+  verbose(verboseEnabled, 'Discovery complete')
+  return ctx
+}

package/scripts/setup/discover.test.js

@@ -0,0 +1,408 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// 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)
+  })
+
+  // ── 21. verbose flag passthrough ─────────────────────────────────────────
+
+  it('should set verbose=true when verbose flag is passed', async () => {
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover({ verbose: true })
+
+    expect(ctx.verbose).toBe(true)
+  })
+
+  it('should set verbose=false when verbose flag is absent', async () => {
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.verbose).toBe(false)
+  })
+})