@abarcenas/ai-workflow-template 1.29.0 → 1.32.0

package/scripts/setup/sync-phase.js

@@ -0,0 +1,172 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// sync-phase.js — Phase 5: spawn sync.js and normalize-memory.js as child
+//                 processes (avoids process.exit() killing the parent setup)
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { spawn } from 'child_process'
+import { join } from 'path'
+
+import { resolvePackageRoot, logInfo, logWarn, logError } from './utils.js'
+
+// ── Main export ─────────────────────────────────────────────────────────────
+
+/**
+ * Runs the sync phase of the setup pipeline.
+ *
+ * Spawns `scripts/sync.js` and `scripts/normalize-memory.js` as child processes
+ * rather than importing them directly. This is required because `sync.js` calls
+ * `process.exit()` internally (line 83), which would terminate the entire setup
+ * process if it were imported as a module.
+ *
+ * **Early exits:**
+ * - `skipSync` is `true` → returns `{ action: 'skipped' }` without spawning
+ * - `dryRun`   is `true` → returns `{ action: 'dry-run' }` after logging intent
+ *
+ * **Normal execution:**
+ * Both scripts are spawned sequentially (sync.js first, normalize-memory.js
+ * second) with `INIT_CWD` set to `consumerRoot` so they resolve consumer
+ * paths correctly. If `flags.force` is set, the `--force` argument is
+ * forwarded to both child scripts.
+ *
+ * Non-zero exit codes from either script are treated as warnings, not
+ * failures — the overall action becomes `'partial'` but the pipeline
+ * continues (graceful degradation per REQ-04).
+ *
+ * @param {object} context - Setup context object.
+ * @param {string} context.consumerRoot - Absolute path to the consumer project root.
+ * @param {boolean} [context.dryRun=false] - If `true`, only simulate without spawning.
+ * @param {boolean} [context.skipSync=false] - If `true`, skip the entire sync phase.
+ * @param {object} [context.flags={}] - Parsed CLI flags (may include `force`).
+ * @returns {Promise<{
+ *   action: 'completed'|'partial'|'skipped'|'dry-run',
+ *   message: string,
+ *   results: Array<{
+ *     script: string,
+ *     success: boolean,
+ *     exitCode: number,
+ *     output: string
+ *   }>
+ * }>}
+ */
+export async function runSyncPhase(context) {
+  const { consumerRoot, dryRun = false, skipSync = false, flags = {} } = context
+
+  // ── Skip path ──────────────────────────────────────────────────────────
+  if (skipSync) {
+    const message = 'Sync phase skipped (--skip-sync)'
+    logInfo(`[setup] ${message}`)
+    return { action: 'skipped', message, results: [] }
+  }
+
+  // ── Dry-run path ───────────────────────────────────────────────────────
+  if (dryRun) {
+    const message =
+      `Would run sync.js and normalize-memory.js ` +
+      `with INIT_CWD="${consumerRoot}"`
+    logInfo(`[setup] dry-run: ${message}`)
+    return { action: 'dry-run', message, results: [] }
+  }
+
+  const packageRoot = resolvePackageRoot()
+  const extraArgs = flags.force ? ['--force'] : []
+
+  // ── Spawn sync.js ──────────────────────────────────────────────────────
+  const syncPath = join(packageRoot, 'scripts', 'sync.js')
+  const syncResult = await spawnScript(
+    'sync.js',
+    syncPath,
+    consumerRoot,
+    extraArgs,
+  )
+
+  // ── Spawn normalize-memory.js ──────────────────────────────────────────
+  const normPath = join(packageRoot, 'scripts', 'normalize-memory.js')
+  const normResult = await spawnScript(
+    'normalize-memory.js',
+    normPath,
+    consumerRoot,
+    extraArgs,
+  )
+
+  const results = [syncResult, normResult]
+  const allSucceeded = results.every((r) => r.success)
+  const action = allSucceeded ? 'completed' : 'partial'
+  const failureCount = results.filter((r) => !r.success).length
+
+  const message =
+    action === 'completed'
+      ? 'Sync phase completed'
+      : `Sync phase completed with ${failureCount} script failure(s)`
+
+  if (!allSucceeded) {
+    logWarn(`[setup] ${message}`)
+    for (const r of results) {
+      if (!r.success) {
+        logWarn(`[setup]   ${r.script} exited with code ${r.exitCode}`)
+      }
+    }
+  }
+
+  return { action, message, results }
+}
+
+// ── Internal helpers ───────────────────────────────────────────────────────
+
+/**
+ * Spawns a Node.js script as a child process and waits for it to complete.
+ *
+ * Both stdout and stderr are captured into a single `output` string
+ * (interleaved in the order data events arrive). The returned promise
+ * resolves when the child process exits or fails to spawn.
+ *
+ * Uses `process.execPath` so the child always runs the same Node.js
+ * binary as the parent setup process.
+ *
+ * @param {string} name - Display name for the script (e.g. `'sync.js'`).
+ * @param {string} scriptPath - Absolute path to the script to execute.
+ * @param {string} cwd - Working directory for the child process.
+ * @param {string[]} extraArgs - Extra CLI arguments forwarded to the script.
+ * @returns {Promise<{
+ *   script: string,
+ *   success: boolean,
+ *   exitCode: number,
+ *   output: string
+ * }>}
+ */
+function spawnScript(name, scriptPath, cwd, extraArgs) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [scriptPath, ...extraArgs], {
+      cwd,
+      env: { ...process.env, INIT_CWD: cwd },
+      stdio: 'pipe',
+    })
+
+    let output = ''
+
+    child.stdout.on('data', (data) => {
+      output += data.toString()
+    })
+
+    child.stderr.on('data', (data) => {
+      output += data.toString()
+    })
+
+    child.on('close', (exitCode) => {
+      resolve({
+        script: name,
+        success: exitCode === 0,
+        exitCode: exitCode ?? -1,
+        output: output.trim(),
+      })
+    })
+
+    child.on('error', (err) => {
+      resolve({
+        script: name,
+        success: false,
+        exitCode: -1,
+        output: `Failed to spawn child process: ${err.message}`,
+      })
+    })
+  })
+}

package/scripts/setup/ui.js

@@ -0,0 +1,503 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// ui.js — User interface / output formatting for the setup command pipeline
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+import {
+  UNICODE_CHARS,
+  PACKAGE_NAME,
+  BIN_NAME,
+  SUPPORTED_FLAGS,
+} from './constants.js'
+import { resolvePackageRoot } from './utils.js'
+
+// ── Colour support ──────────────────────────────────────────────────────────
+
+/** `true` when stdout is a TTY — ANSI escape codes are emitted. */
+const useColor = process.stdout.isTTY
+
+/**
+ * Builds an ANSI SGR escape sequence.
+ *
+ * Returns an empty string when colours are disabled (piped / non-TTY output)
+ * so that log files stay clean.
+ *
+ * @param {string} code - SGR parameter(s), e.g. `'1'`, `'32m'`, `'1;31m'`.
+ * @returns {string} Escape sequence, or `''` when colours are off.
+ */
+function ansi(code) {
+  return useColor ? `\x1b[${code}` : ''
+}
+
+/** ANSI reset. */
+const RST = ansi('0m')
+/** ANSI bold / increased intensity. */
+const BLD = ansi('1m')
+/** ANSI dim / decreased intensity. */
+const DIM = ansi('2m')
+/** ANSI green foreground. */
+const GRN = ansi('32m')
+/** ANSI yellow foreground. */
+const YLW = ansi('33m')
+/** ANSI red foreground. */
+const RED = ansi('31m')
+/** ANSI cyan foreground. */
+const CYN = ansi('36m')
+
+/**
+ * Read-only colour palette for use by downstream consumers.
+ *
+ * @type {{ reset: string, bold: string, dim: string, green: string,
+ *          yellow: string, red: string, cyan: string }}
+ */
+export const COLORS = Object.freeze({
+  reset: RST,
+  bold: BLD,
+  dim: DIM,
+  green: GRN,
+  yellow: YLW,
+  red: RED,
+  cyan: CYN,
+})
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Strips ANSI escape sequences from a string.
+ *
+ * @param {string} str - Input that may contain ANSI codes.
+ * @returns {string} Plain text without escape sequences.
+ */
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '')
+}
+
+/**
+ * Returns the visible display width of a string, treating ANSI codes as
+ * zero-width.
+ *
+ * @param {string} str - Input that may contain ANSI codes.
+ * @returns {number} Number of visible characters.
+ */
+function visibleWidth(str) {
+  return stripAnsi(str).length
+}
+
+/**
+ * Returns a horizontal rule of the given character, bounded by the terminal
+ * width.
+ *
+ * @param {string} [char='─'] - Character to repeat.
+ * @param {number} [maxWidth] - Maximum available width (defaults to terminal
+ *                              columns, capped at 72).
+ * @returns {string} Rule string.
+ */
+function rule(char = '\u2500', maxWidth) {
+  const width = maxWidth ?? Math.min(process.stdout.columns || 72, 72)
+  return char.repeat(width)
+}
+
+// ── Version caching ─────────────────────────────────────────────────────────
+
+/** @type {string|null} */
+let _version = null
+
+/**
+ * Reads the package version from the project's `package.json`.
+ *
+ * The result is cached after the first successful read so repeated calls
+ * (e.g. `header()` then `help()`) don't re-read the filesystem.
+ *
+ * @returns {string} Semver string (e.g. `'1.29.0'`). Falls back to `'0.0.0'`.
+ */
+function getVersion() {
+  if (_version === null) {
+    try {
+      const pkgRoot = resolvePackageRoot()
+      const pkgPath = join(pkgRoot, 'package.json')
+      const raw = readFileSync(pkgPath, 'utf-8')
+      _version = JSON.parse(raw).version || '0.0.0'
+    } catch {
+      _version = '0.0.0'
+    }
+  }
+  return _version
+}
+
+// ── Write helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Writes one or more lines to stdout.
+ *
+ * @param {...string} lines - Lines to print.
+ */
+function write(...lines) {
+  for (const line of lines) {
+    console.log(line)
+  }
+}
+
+// ── Public output API ───────────────────────────────────────────────────────
+
+/**
+ * Prints the setup banner showing the package name and version.
+ *
+ * Example:
+ *
+ *   ────────────────────────────────────────────────────────────
+ *     @abarcenas/ai-workflow-template v1.29.0 — Setup
+ *   ────────────────────────────────────────────────────────────
+ */
+export function header() {
+  const version = getVersion()
+  const width = Math.min(process.stdout.columns || 72, 72)
+  const sep = DIM + rule() + RST
+  const title =
+    `  ${BLD}${PACKAGE_NAME}${RST}` +
+    ` ${GRN}v${version}${RST}` +
+    ` ${DIM}\u2014${RST}` +
+    ` ${BLD}Setup${RST}`
+
+  write()
+  write(sep)
+  write(title)
+  write(sep)
+  write()
+}
+
+/**
+ * Prints a progress step indicator with a rightwards arrow.
+ *
+ * @param {string} message - Description of the step being performed.
+ * @example
+ *   step('Checking environment…')
+ *   // → Checking environment…
+ */
+export function step(message) {
+  write(` ${UNICODE_CHARS.ARROW} ${message}`)
+}
+
+/**
+ * Prints a step that completed successfully (checkmark).
+ *
+ * @param {string} message - Description of the completed step.
+ * @example
+ *   stepSuccess('Environment ready')
+ *   // ✓ Environment ready
+ */
+export function stepSuccess(message) {
+  write(` ${GRN}${UNICODE_CHARS.CHECK}${RST} ${message}`)
+}
+
+/**
+ * Prints a step that completed with a warning.
+ *
+ * @param {string} message - Warning description.
+ * @example
+ *   stepWarn('Husky version is newer than expected')
+ *   // ⚠ Husky version is newer than expected
+ */
+export function stepWarn(message) {
+  write(` ${YLW}${UNICODE_CHARS.WARN}${RST} ${message}`)
+}
+
+/**
+ * Prints a step that failed.
+ *
+ * @param {string} message - Error description.
+ * @example
+ *   stepError('Git repository not found')
+ *   // ✗ Git repository not found
+ */
+export function stepError(message) {
+  write(` ${RED}${UNICODE_CHARS.CROSS}${RST} ${message}`)
+}
+
+/**
+ * Prints an informational message (default colour, stdout).
+ *
+ * @param {string} message - Message to display.
+ */
+export function info(message) {
+  write(message)
+}
+
+/**
+ * Prints a warning message (yellow, bold) to stderr.
+ *
+ * @param {string} message - Warning message.
+ */
+export function warn(message) {
+  console.error(`${YLW}${BLD}warning${RST}  ${message}`)
+}
+
+/**
+ * Prints an error message (red, bold) to stderr.
+ *
+ * @param {string} message - Error message.
+ */
+export function error(message) {
+  console.error(`${RED}${BLD}error${RST}    ${message}`)
+}
+
+/**
+ * Prints a success message (green) to stdout.
+ *
+ * @param {string} message - Success message.
+ */
+export function success(message) {
+  write(`${GRN}${UNICODE_CHARS.CHECK}${RST} ${message}`)
+}
+
+/**
+ * Prints a bold section header.
+ *
+ * @param {string} title - Section title.
+ * @example
+ *   section('Environment Discovery')
+ *   // Environment Discovery
+ */
+export function section(title) {
+  write(`${BLD}${title}${RST}`)
+}
+
+/**
+ * Prints a formatted summary table from phase results.
+ *
+ * Each result entry is rendered as a single row in a text table with three
+ * columns: **Phase**, **Status**, and **Message**.  The table is followed by
+ * an overall result line (success / warnings / errors).
+ *
+ * @param {Array<{ phase: string, status: string, message: string }>} results
+ *   Phase results to display.
+ *   - `phase`   — Short phase name (e.g. `'discover'`, `'hooks'`)
+ *   - `status`  — One of `'success'`, `'warn'`, `'error'`, or a custom string
+ *   - `message` — Human-readable result description
+ *
+ * @example
+ *   summary([
+ *     { phase: 'discover', status: 'success', message: 'Git repo found' },
+ *     { phase: 'hooks',    status: 'error',   message: 'Permission denied' },
+ *   ])
+ */
+export function summary(results) {
+  if (!results || results.length === 0) return
+
+  const headerPhase = 'Phase'
+  const headerStatus = 'Status'
+  const headerMessage = 'Message'
+
+  // ── Column widths ───────────────────────────────────────────────────
+  const phases = results.map((r) => r.phase)
+  const statuses = results.map((r) => r.status)
+  const colPhase = Math.max(headerPhase.length, ...phases.map((s) => s.length))
+  const colStatus = Math.max(headerStatus.length, ...statuses.map((s) => s.length))
+  const colMsg = Math.max(
+    headerMessage.length,
+    ...results.map((r) => visibleWidth(r.message || '')),
+  )
+
+  // ── Status rendering ────────────────────────────────────────────────
+  /**
+   * Formats a status string with a colour-coded symbol.
+   *
+   * @param {string} s - Status key.
+   * @returns {string} Formatted status (may contain ANSI codes).
+   */
+  const fmtStatus = (s) => {
+    switch (s) {
+      case 'success':
+        return `${GRN}${UNICODE_CHARS.CHECK}${RST} success`
+      case 'warn':
+        return `${YLW}${UNICODE_CHARS.WARN}${RST} warn`
+      case 'error':
+        return `${RED}${UNICODE_CHARS.CROSS}${RST} error`
+      default:
+        return s
+    }
+  }
+
+  // Number of extra invisible chars added by the colour wrapper in fmtStatus
+  const statusAnsiExtra =
+    useColor && ['success', 'warn', 'error'].includes(statuses[0])
+      ? // Each coloured status wraps the symbol in open + close = 2 escapes
+        // e.g. `\x1b[32m✓\x1b[0m success` = 5+5+8 = 18 visible, but 28 chars
+        // The extra is the ANSI codes length per status
+        10
+      : 0
+
+  // ── Print ───────────────────────────────────────────────────────────
+  write()
+  section('Setup Summary')
+  divider()
+
+  // Header
+  write(
+    `  ${headerPhase.padEnd(colPhase)}  ` +
+      `${headerStatus.padEnd(colStatus + statusAnsiExtra)}  ` +
+      `${headerMessage}`,
+  )
+
+  // Separator
+  write(
+    `  ${DIM}${'\u2500'.repeat(colPhase)}` +
+      `  ${'\u2500'.repeat(Math.max(colStatus, 6))}` +
+      `  ${'\u2500'.repeat(colMsg)}${RST}`,
+  )
+
+  // Rows
+  for (const r of results) {
+    const p = r.phase.padEnd(colPhase)
+    const s = fmtStatus(r.status).padEnd(colStatus + statusAnsiExtra)
+    write(`  ${p}  ${s}  ${r.message || ''}`)
+  }
+
+  divider()
+
+  // Overall result
+  const hasErrors = results.some((r) => r.status === 'error')
+  const hasWarnings = results.some((r) => r.status === 'warn')
+  if (hasErrors) {
+    error('Setup completed with errors.')
+  } else if (hasWarnings) {
+    warn('Setup completed with warnings.')
+  } else {
+    success('Setup completed successfully.')
+  }
+  write()
+}
+
+/**
+ * Prints usage / help information showing all available CLI flags and their
+ * descriptions.
+ */
+export function help() {
+  const version = getVersion()
+
+  // ── Build flag display groups ───────────────────────────────────────
+  // Invert SUPPORTED_FLAGS to group short + long forms per canonical key.
+  /** @type {Record<string, string[]>} */
+  const groups = {}
+  for (const [flag, canonical] of Object.entries(SUPPORTED_FLAGS)) {
+    ;(groups[canonical] || (groups[canonical] = [])).push(flag)
+  }
+
+  // Sort each group so shorter flags come first, then build display text.
+  /** @type {Record<string, string>} */
+  const display = {}
+  let maxLen = 0
+  for (const [canonical, flags] of Object.entries(groups)) {
+    flags.sort((a, b) => a.length - b.length)
+    const text = flags.join(', ')
+    display[canonical] = text
+    maxLen = Math.max(maxLen, text.length)
+  }
+
+  // Ordered flag descriptions.
+  /** @type {Record<string, string>} */
+  const descriptions = {
+    force: 'Overwrite existing hooks (a .bak backup is created)',
+    dryRun: 'Show what would be done without making any changes',
+    yes: 'Skip confirmation prompts (non-interactive mode)',
+    skipHooks: 'Skip git hook installation phase',
+    skipPrepare: 'Skip prepare script modification phase',
+    skipSync: 'Skip file sync phase',
+    help: 'Show this help message and exit',
+    version: 'Show the version number and exit',
+    quiet: 'Suppress non-error output (quiet mode)',
+    verbose: 'Show detailed debug information',
+  }
+
+  const order = [
+    'force',
+    'dryRun',
+    'yes',
+    'skipHooks',
+    'skipPrepare',
+    'skipSync',
+    'help',
+    'version',
+    'quiet',
+    'verbose',
+  ]
+
+  // ── Print help text ─────────────────────────────────────────────────
+  write()
+  write(`${BLD}${PACKAGE_NAME}${RST} ${GRN}v${version}${RST}`)
+  write()
+  write(`  ${BLD}Usage:${RST}`)
+  write(`    npx ${PACKAGE_NAME} setup [options]`)
+  write(`    ${BIN_NAME} [options]`)
+  write()
+  write(`  ${BLD}Description:${RST}`)
+  write(
+    `    Sets up a consumer project with git hooks, memory-bank scaffolding,` +
+      ` and AI workflow`,
+  )
+  write(`    integration for the ${PACKAGE_NAME} framework.`)
+  write()
+  write(`  ${BLD}Options:${RST}`)
+
+  for (const key of order) {
+    const d = display[key]
+    const desc = descriptions[key] || ''
+    if (d) {
+      write(`    ${d.padEnd(maxLen)}  ${desc}`)
+    }
+  }
+
+  write()
+  write(`  ${BLD}Examples:${RST}`)
+  write(`    npx ${PACKAGE_NAME} setup`)
+  write(`    npx ${PACKAGE_NAME} setup --dry-run --verbose`)
+  write(`    npx ${PACKAGE_NAME} setup --force --skip-hooks`)
+  write(`    ${BIN_NAME} --help`)
+  write()
+}
+
+/**
+ * Prints a horizontal rule for visual separation.
+ */
+export function divider() {
+  write(` ${DIM}${rule()}${RST}`)
+}
+
+/**
+ * Prints a prominent banner indicating that `--dry-run` mode is active and no
+ * files will be modified.
+ */
+export function dryRunBanner() {
+  const width = Math.min(process.stdout.columns || 72, 72)
+  const sep = YLW + rule() + RST
+  write()
+  write(sep)
+  write(
+    `  ${YLW}${UNICODE_CHARS.WARN}${RST}` +
+      ` ${BLD}DRY RUN MODE${RST}` +
+      ` ${DIM}\u2014${RST} No files will be modified.` +
+      ` ${YLW}${UNICODE_CHARS.WARN}${RST}`,
+  )
+  write(sep)
+  write()
+}
+
+/**
+ * Prints a banner indicating CI mode is detected and git hooks will be
+ * skipped.
+ */
+export function ciModeBanner() {
+  const width = Math.min(process.stdout.columns || 72, 72)
+  const sep = CYN + rule() + RST
+  write()
+  write(sep)
+  write(
+    `  ${CYN}${UNICODE_CHARS.BULLET}${RST}` +
+      ` ${BLD}CI MODE DETECTED${RST}` +
+      ` ${DIM}\u2014${RST} Git hooks will be skipped.` +
+      ` Use ${CYN}--skip-hooks${RST} to suppress this message.`,
+  )
+  write(sep)
+  write()
+}