@abarcenas/ai-workflow-template 1.28.0 → 1.32.0

package/scripts/setup/constants.js

@@ -0,0 +1,226 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// constants.js — Shared constants for the setup command pipeline
+// ═════════════════════════════════════════════════════════════════════════════
+
+// ── Package identity ──────────────────────────────────────────────────────────
+
+/** npm package name */
+export const PACKAGE_NAME = '@abarcenas/ai-workflow-template'
+
+/** CLI binary name (npm "bin" entry) */
+export const BIN_NAME = 'ai-workflow-setup'
+
+// ── Idempotency markers ───────────────────────────────────────────────────────
+
+/**
+ * First-line comment injected into every template hook file.
+ * Used to detect whether an existing consumer hook was installed by us
+ * (idempotency check in hooks.js, CASE C). Must be the first line of
+ * each template hook file.
+ */
+export const HOOK_MARKER = '# Managed by @abarcenas/ai-workflow-template setup'
+
+/**
+ * Separator inserted between a consumer's existing hook content and our
+ * appended content during hook merging (hooks.js, CASE D).
+ */
+export const HOOK_MERGE_SEPARATOR = '# --- @abarcenas/ai-workflow-template ---'
+
+// ── Template hook definitions ─────────────────────────────────────────────────
+
+/**
+ * Map of hook names → metadata for every git hook the setup command manages.
+ *
+ * Each entry carries:
+ *   `source`      — Relative path from the package root to the template file.
+ *                   Resolved at runtime by hooks.js.
+ *   `content`     — Exact content that will be written (or appended) to the
+ *                   consumer's hook file. This mirrors the actual file on disk.
+ *   `description` — Human-readable purpose, shown in output messages.
+ */
+export const TEMPLATE_HOOKS = {
+  'pre-commit': {
+    source: '.husky/pre-commit',
+    content:
+      '# Managed by @abarcenas/ai-workflow-template setup\n\nnode scripts/bump-version.js\nnode scripts/validate-memory-schema.js\n',
+    description:
+      'Auto-bump version + validate memory-bank schema before commits',
+  },
+  'post-merge': {
+    source: '.husky/post-merge',
+    content: [
+      '# Managed by @abarcenas/ai-workflow-template setup',
+      '#!/bin/sh',
+      '. "$(dirname "$0")/_/husky.sh"',
+      '',
+      '# After git pull/merge, check if memory-bank files changed',
+      '# and update the vector index incrementally',
+      '',
+      'if git diff HEAD@{1} --name-only 2>/dev/null | grep -q "^memory-bank\\|^docs/"; then',
+      '  echo "[memory-bank] Memory bank files changed. Updating vector index..."',
+      '  node scripts/memory-cli.js update 2>/dev/null || echo "[memory-bank] Index update skipped (service not installed)"',
+      'fi',
+      '',
+    ].join('\n'),
+    description:
+      'Auto-update memory bank vector index after pull/merge',
+  },
+}
+
+// ── CI/CD environment detection ───────────────────────────────────────────────
+
+/**
+ * Environment variable names checked to determine if the command is running
+ * inside a CI/CD pipeline.
+ *
+ * When `isCI()` from utils.js returns true, the setup command skips git hook
+ * installation entirely (REQ-07) and only performs file sync + memory-bank
+ * scaffolding.
+ *
+ * @note `NODE_ENV` is included here but is evaluated as
+ *       `process.env.NODE_ENV === 'production'` (equality check), whereas
+ *       all other entries are evaluated as simple truthiness checks.
+ */
+export const CI_ENV_VARS = [
+  'CI',
+  'GITHUB_ACTIONS',
+  'GITLAB_CI',
+  'CIRCLECI',
+  'TRAVIS',
+  'JENKINS_URL',
+  'BITBUCKET_BUILD_NUMBER',
+  'APPVEYOR',
+  'CODEBUILD_BUILD_ID',
+  'AZURE_HTTP_USER_AGENT',
+  'NODE_ENV',
+]
+
+// ── CLI flags ─────────────────────────────────────────────────────────────────
+
+/**
+ * Map of CLI argument strings (long and short forms) to their canonical
+ * camelCase property names on the flags object.
+ *
+ * Usage: `parseCliArgs()` in utils.js iterates over argv, looks up each
+ * element in this map, and sets the corresponding property to `true` on
+ * the returned flags object.
+ */
+export const SUPPORTED_FLAGS = {
+  '--force': 'force',
+  '--dry-run': 'dryRun',
+  '--yes': 'yes',
+  '-y': 'yes',
+  '--skip-hooks': 'skipHooks',
+  '--skip-prepare': 'skipPrepare',
+  '--skip-sync': 'skipSync',
+  '--help': 'help',
+  '-h': 'help',
+  '--version': 'version',
+  '-v': 'version',
+  '--quiet': 'quiet',
+  '-q': 'quiet',
+  '--verbose': 'verbose',
+  '-V': 'verbose',
+}
+
+// ── Exit codes ────────────────────────────────────────────────────────────────
+
+/**
+ * Numeric exit codes returned by the setup command.
+ *
+ *   SUCCESS  → All phases completed without errors or warnings
+ *   WARNINGS → One or more phases had non-fatal warnings (exit code 1)
+ *   FATAL    → A required phase encountered an unrecoverable error (exit code 2)
+ */
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  WARNINGS: 1,
+  FATAL: 2,
+}
+
+// ── Required directories ──────────────────────────────────────────────────────
+
+/**
+ * Relative paths (from the consumer project root) of directories that the
+ * setup command must ensure exist before running its pipeline.
+ */
+export const REQUIRED_DIRS = [
+  '.husky',
+  'memory-bank',
+]
+
+// ── Output symbols ────────────────────────────────────────────────────────────
+
+/**
+ * Unicode characters used as status indicators in the CLI output.
+ * Referenced by the ui.js module.
+ */
+export const UNICODE_CHARS = {
+  CHECK: '\u2713',  // ✓
+  WARN: '\u26A0',   // ⚠
+  CROSS: '\u2717',  // ✗
+  BULLET: '\u2022', // •
+  ARROW: '\u2192',  // →
+}
+
+// ── Memory bank stubs ─────────────────────────────────────────────────────────
+
+/**
+ * Template content for scaffolding a fresh memory-bank/ directory.
+ * Exact mirror of the `memoryBankStubs` object in `scripts/sync.js`
+ * (lines 204–254). Each key is a filename; each value is the file content.
+ *
+ * Used by the setup command's sync-phase when the consumer project lacks
+ * a memory-bank/ directory.
+ */
+export const MEMORY_BANK_STUBS = {
+  'projectbrief.md': `# projectbrief
+
+> Foundation document — defines core requirements and goals.
+
+- **Purpose**: {{describe project purpose}}
+- **Goals**: {{list project goals}}
+- **Scope**: {{define scope}}
+`,
+  'productContext.md': `# productContext
+
+> Why this project exists and what problems it solves.
+
+- **Problem**: {{describe the problem}}
+- **Solution**: {{describe the solution}}
+- **User Experience**: {{describe UX goals}}
+`,
+  'activeContext.md': `# activeContext
+
+> Current work focus, recent changes, next steps.
+
+- **Current Focus**: {{current task or goal}}
+- **Recent Changes**: {{list of recent changes}}
+- **Next Steps**: {{next actions}}
+`,
+  'systemPatterns.md': `# systemPatterns
+
+> Architecture, key decisions, design patterns.
+
+- **Architecture**: {{describe architecture}}
+- **Key Decisions**: {{list key technical decisions}}
+- **Patterns**: {{list design patterns in use}}
+`,
+  'techContext.md': `# techContext
+
+> Technologies, setup, constraints, dependencies.
+
+- **Stack**: {{list technologies}}
+- **Setup**: {{describe dev setup}}
+- **Constraints**: {{list technical constraints}}
+`,
+  'progress.md': `# progress
+
+> What works, what's left, current status.
+
+- **Working**: {{what's implemented and working}}
+- **To Build**: {{what remains}}
+- **Status**: {{overall project status}}
+- **Known Issues**: {{list known issues}}
+`,
+}

package/scripts/setup/discover.js

@@ -0,0 +1,236 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// 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'
+
+// ── 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,
+  }
+}
+
+// ── 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)
+
+  // ── 1. Resolve consumer root ──────────────────────────────────────────
+  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 ──────────────────────────────────────────
+  try {
+    ctx.hasGit = dirExists(resolve(ctx.consumerRoot, '.git'))
+  } catch {
+    // Non-fatal — hasGit stays false
+  }
+
+  // ── 3. Detect .husky/ directory ───────────────────────────────────────
+  try {
+    ctx.hasHuskyDir = dirExists(resolve(ctx.consumerRoot, '.husky'))
+  } catch {
+    // Non-fatal — hasHuskyDir stays false
+  }
+
+  // ── 4. Detect + parse package.json ────────────────────────────────────
+  try {
+    const pkgPath = resolve(ctx.consumerRoot, 'package.json')
+    const pkg = safeReadJson(pkgPath)
+    ctx.hasPackageJson = pkg !== undefined
+    ctx.consumerPackageJson = pkg ?? null
+  } 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).
+  try {
+    for (const hookName of Object.keys(TEMPLATE_HOOKS)) {
+      ctx.existingHooks[hookName] = detectHook(ctx.consumerRoot, hookName)
+    }
+  } catch {
+    // Non-fatal — existingHooks already contains default entries
+  }
+
+  // ── 6. Extract existing prepare script ────────────────────────────────
+  try {
+    const prepare = ctx.consumerPackageJson?.scripts?.prepare
+    ctx.existingPrepare =
+      typeof prepare === 'string' && prepare.trim().length > 0
+        ? prepare.trim()
+        : null
+  } 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 ──────────────────────────────────────────
+  try {
+    ctx.isCI = isCI()
+  } catch {
+    ctx.isCI = false
+  }
+
+  // ── 9. Detect Node.js version ─────────────────────────────────────────
+  try {
+    ctx.nodeVersion = getNodeVersion()
+  } catch {
+    ctx.nodeVersion = 0
+  }
+
+  // NOTE: `ctx.dryRun` is already set by createDefaultContext(flags)
+
+  return ctx
+}