@abarcenas/ai-workflow-template 1.29.0 → 1.32.0

package/.agents/instructions/learned-knowledge.instructions.md

@@ -20,3 +20,26 @@
 - unit-tester: Must be told to look in `scripts/` for source and test files, not `src/`
 - coder: Must be told the project uses ES module syntax (import/export, not require/module.exports)
 - implementer: Plans should target `scripts/` for production code and tests
+
+## Session: 2026-07-24
+
+**Pipeline:** researcher → architect → implementer → coder (6 parallel batches) → unit-tester → tracker
+**Coverage:** 88/88 tests passing across 4 test files (discover 21, hooks 16, prepare 27, index 24)
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **npm v12 blocks postinstall scripts from dependencies** — this is a critical ecosystem shift that affects ALL npm library distribution. Postinstall auto-sync is no longer viable; explicit setup commands are required
+- **npx-based setup command pattern** (following Playwright, Prisma, Cypress convention) is the future-proof distribution mechanism for CLI tools that need to configure consumer projects
+- **Husky v9 programmatic API** is dead simple: `import husky from 'husky'; husky(consumerRoot)` — no need to shell out or manually manage shim files
+- **`child_process.spawn` for scripts with `process.exit()`** — importing sync.js (which calls `process.exit()`) directly into the setup process would kill the parent. Spawn as a child process to isolate exit behavior
+- **Marker comment idempotency** — a first-line comment (`# Managed by @abarcenas/ai-workflow-template setup`) on hook files enables content-based detection for safe re-runs. This pattern should be used for any managed file that needs idempotent installation
+- **6-batch parallel execution worked well**: Batch A (3 foundation: constants, utils, ui) → Batch B (5 core: discover, hooks, prepare, husky-init, sync-phase) → Batch C (2 orchestrator: index.js, bin/setup.js) → Batches D+E (3 config: pre-commit marker, post-merge marker, package.json) → Batch F (4 tests). Clear interface definitions were essential for parallelism
+- **Duplicate-marker trap** — constants.js `TEMPLATE_HOOKS.content` must stay in sync with actual `.husky/` hook files. During T12 (post-merge marker), a mismatch was discovered between the template content in constants.js (which already had the marker via `buildHookContent()`) and the actual disk file. Solution: update constants.js template content whenever hook files are modified
+
+**Agent tuning notes:**
+- **researcher**: Should explicitly investigate npm ecosystem changes (version-specific behavior, deprecations) — the npm v12 postinstall discovery was the single most important finding that drove the architecture
+- **architect**: Modular design with clear interface contracts (Context object shape, return types) paid off — all 5 Batch B modules could be implemented in parallel without coordination issues
+- **implementer**: The parallel batch plan with explicit dependency edges (Batch A → B → C, D+E → F) was critical for the 6 sub-agent coder execution. Without this structure, 6 concurrent coders would have had race conditions on shared files
+- **coder (parallel batches)**: Batch ordering discipline worked — foundation first, then core, then orchestrator. The truly independent batches (D: markers, F: tests) could run alongside later batches. Key lesson: define interfaces (Context shape, return types) before splitting work across parallel coders
+- **unit-tester**: Using real temp directories (`mkdtempSync`) over mocking filesystem operations catches path resolution and permission issues that mocks would miss. Mock only environment-dependent utilities (CI detection, Node version), not filesystem
+- **tracker**: Should capture ecosystem discoveries alongside implementation details — the npm v12 finding and marker idempotency pattern are valuable knowledge for future pipeline sessions

package/.github/workflows/npm-publish.yml

@@ -19,6 +19,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Run unit tests
+        run: npm run test:unit
+
       - name: Publish to npm
         run: npm publish --access public
         env:

package/.github/workflows/pr-test.yml

@@ -0,0 +1,23 @@
+name: PR Unit Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm run test:unit

package/.husky/post-merge

@@ -1,3 +1,4 @@
+# Managed by @abarcenas/ai-workflow-template setup
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 

package/.husky/pre-commit

@@ -1,2 +1,4 @@
+# Managed by @abarcenas/ai-workflow-template setup
+
 node scripts/bump-version.js
 node scripts/validate-memory-schema.js

package/README.md

@@ -35,7 +35,53 @@ Install directly into the project that needs AI workflow configuration:
 npm install @abarcenas/ai-workflow-template
 ```
 
-The package runs `postinstall` automatically to sync configurations.
+The package runs `postinstall` automatically to sync files. For full setup including git hooks, run the one-step setup command below.
+
+---
+
+## 🪝 Git Hook Setup
+
+After installing the package, configure husky git hooks with one command:
+
+```bash
+# One-step setup (fetches from npm registry automatically):
+npx @abarcenas/ai-workflow-template
+
+# Or if the package is already installed:
+npx ai-workflow-setup
+```
+
+### What It Does
+
+The setup command automatically:
+
+| Phase | Action |
+|-------|--------|
+| 🔍 **Discover** | Detects git repo, existing hooks, CI mode |
+| 🪝 **Hooks** | Installs `pre-commit` (version bump + validation) and `post-merge` (memory index update) |
+| 📦 **Prepare** | Merges `"husky"` into your `package.json` prepare script |
+| ⚙️ **Husky Init** | Initializes husky and sets `core.hooksPath` |
+| 🔄 **Sync** | Copies agent configurations, skills, and memory bank scaffolding |
+
+### Options
+
+```bash
+npx ai-workflow-setup --dry-run     # Preview without changes
+npx ai-workflow-setup --force       # Overwrite existing hooks
+npx ai-workflow-setup --skip-hooks  # Skip hook installation
+npx ai-workflow-setup --skip-sync   # Skip file sync
+npx ai-workflow-setup --help        # Show all options
+```
+
+### Hook Merging
+
+If you already have existing husky hooks, the setup command intelligently merges:
+- **Your hooks are never overwritten** — new content is appended after a separator
+- **Managed hooks are detected** via marker comments and updated idempotently
+- **Complex hooks** trigger a warning with manual merge instructions
+- **CI environments** auto-skip hook configuration
+
+> **ℹ️ npm v12 note:** Future npm versions block automatic `postinstall` scripts. The explicit `npx setup` command is the recommended, future-proof approach.
 
 ---
 
@@ -416,6 +462,7 @@ npm run memory:normalize
 - 📖 `AGENTS.md` is the main instruction file agents should read
 - 🎯 Package assumes public npm registry
 - 🎭 Playwright MCP integration documented in `docs/` folder
+- 🪝 Run `npx ai-workflow-setup` after install to configure git hooks (npm v12+ compatible)
 
 ---
 

package/bin/setup.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// ═════════════════════════════════════════════════════════════════════════════
+// bin/setup.js — CLI entry point for `npx ai-workflow-setup`
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Minimal shim that delegates to the orchestrator (scripts/setup/index.js).
+// Uses top-level await via ESM (requires "type": "module" in package.json).
+//
+// Exit codes:
+//   0 — All phases completed successfully
+//   1 — One or more phases had warnings / were skipped
+//   2 — Fatal error (discovery failure or unexpected exception)
+// ═════════════════════════════════════════════════════════════════════════════
+
+try {
+  const { main } = await import('../scripts/setup/index.js')
+  const exitCode = await main(process.argv.slice(2))
+  process.exit(exitCode)
+} catch (err) {
+  console.error('Fatal error:', err.message)
+  process.exit(2)
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.29.0",
+  "version": "1.32.0",
   "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
   "main": "index.js",
+  "bin": {
+    "ai-workflow-setup": "./bin/setup.js"
+  },
   "scripts": {
     "test": "playwright test",
     "test:headed": "playwright test --headed",
@@ -14,7 +17,7 @@
     "test:unit:watch": "vitest",
     "prepare": "husky",
     "sync": "node ./scripts/sync.js",
-    "postinstall": "node ./scripts/sync.js && node ./scripts/normalize-memory.js",
+    "postinstall": "node ./scripts/sync.js && node ./scripts/normalize-memory.js && echo '' && echo '⚠️  IMPORTANT: Run npx ai-workflow-setup to configure git hooks' && echo '   (npm postinstall scripts will be blocked by npm v12+)'",
     "memory:search": "node ./scripts/memory-cli.js search",
     "memory:rebuild": "node ./scripts/memory-cli.js rebuild",
     "memory:update": "node ./scripts/memory-cli.js update",
@@ -33,9 +36,11 @@
   },
   "homepage": "https://github.com/abarcenas29/ai-workflow-template#readme",
   "files": [
+    "bin/",
     ".agents/",
     ".github/workflows/",
     "scripts/",
+    "scripts/setup/",
     ".opencode/agents/",
     ".opencode/commands/",
     ".husky/",

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
+}