feat: add lifecycle harness (seedable E2E over scaffold + ep CLI)

- scripts/lifecycle-harness: randomized scenarios, mutations, ep commands
- ensureBunOnPath() so bun is resolvable when launched by absolute path
- repoPath existence guard to avoid misleading ENOENT when scaffold fails
- Unit tests for report, args, prng, list-parse, disk
- docs/Architecture: document scaffold and lifecycle harness
- package.json: lifecycle-harness script
- .gitignore: lifecycle-harness reports/

Made-with: Cursor

Author: PaulJPhilp

.gitignore

@@ -30,6 +30,9 @@ Thumbs.db
 # Coverage
 coverage/
 
+# Lifecycle harness run reports (generated)
+scripts/lifecycle-harness/reports/
+
 # Misc
 *.tgz
 .idea/

docs/Architecture.md

@@ -430,6 +430,11 @@ bun run ep:preflight
 bun run ep:smoke-test
 ```
 
+### Scripts (scaffold and lifecycle harness)
+
+- **Scaffold** (`bun run scaffold`) creates new projects under `$HOME/Projects/TestRepos` (see [scripts/scaffold-test-project.ts](../scripts/scaffold-test-project.ts) and [docs/development/SCAFFOLD_USER_GUIDE.md](development/SCAFFOLD_USER_GUIDE.md)).
+- **Lifecycle harness** (`bun run lifecycle-harness --seed <n>`) runs seedable E2E over real repos and the `ep` CLI. It depends on the scaffold’s output path: it uses the same root (`defaultScaffoldRootDir()` in `scripts/lifecycle-harness/src/paths.ts`). The harness discovers the monorepo root by walking up from `scripts/lifecycle-harness/src/` and looking for a root `package.json` containing `effect-patterns-hub` or a `"scaffold"` script.
+
 ### Testing
 
 **Unit and integration:**

package.json

@@ -98,7 +98,8 @@
     "ep:preflight": "bun run --filter @effect-patterns/ep-cli preflight",
     "ep:smoke-test": "bun run --filter @effect-patterns/ep-cli smoke-test",
     "seed:skills": "bun run scripts/seed-skills.ts",
-    "scaffold": "bun run scripts/scaffold-test-project.ts"
+    "scaffold": "bun run scripts/scaffold-test-project.ts",
+    "lifecycle-harness": "bun run scripts/lifecycle-harness/src/index.ts"
   },
   "dependencies": {
     "@effect/cli": "0.73.2",

scripts/__tests__/lifecycle-harness/args.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Unit tests for lifecycle harness args: parseArgs with given argv.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { parseArgs } from '../../lifecycle-harness/src/args.js'
+
+describe('parseArgs', () => {
+  it('returns help mode for --help', () => {
+    const out = parseArgs(['node', 'harness', '--help'])
+    expect(out.mode).toBe('help')
+  })
+
+  it('returns help mode for -h', () => {
+    const out = parseArgs(['node', 'harness', '-h'])
+    expect(out.mode).toBe('help')
+  })
+
+  it('returns version mode for --version', () => {
+    const out = parseArgs(['node', 'harness', '--version'])
+    expect(out.mode).toBe('version')
+  })
+
+  it('returns run mode with defaults when only node and script', () => {
+    const out = parseArgs(['node', 'scripts/lifecycle-harness/src/index.ts'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') {
+      expect(typeof out.seed).toBe('number')
+      expect(out.scenarios).toBe(10)
+      expect(out.budgetMinutes).toBe(14)
+      expect(out.scenarioTimeoutSeconds).toBe(90)
+      expect(out.diskBudgetMb).toBe(1024)
+      expect(out.commits).toBe('minimal')
+      expect(out.verbose).toBe(false)
+      expect(out.dryRun).toBe(false)
+      expect(out.epBin).toBe('ep')
+    }
+  })
+
+  it('parses --seed', () => {
+    const out = parseArgs(['node', 'harness', '--seed', '42'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') expect(out.seed).toBe(42)
+  })
+
+  it('parses --scenarios', () => {
+    const out = parseArgs(['node', 'harness', '--seed', '1', '--scenarios', '3'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') expect(out.scenarios).toBe(3)
+  })
+
+  it('parses --only-scenario', () => {
+    const out = parseArgs(['node', 'harness', '--seed', '1', '--only-scenario', '2'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') expect(out.onlyScenario).toBe(2)
+  })
+
+  it('ignores negative --only-scenario', () => {
+    const out = parseArgs(['node', 'harness', '--seed', '1', '--only-scenario', '-1'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') expect(out.onlyScenario).toBeUndefined()
+  })
+
+  it('parses --commits none', () => {
+    const out = parseArgs(['node', 'harness', '--seed', '1', '--commits', 'none'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') expect(out.commits).toBe('none')
+  })
+
+  it('parses --verbose and --dry-run', () => {
+    const out = parseArgs(['node', 'harness', '--seed', '1', '--verbose', '--dry-run'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') {
+      expect(out.verbose).toBe(true)
+      expect(out.dryRun).toBe(true)
+    }
+  })
+
+  it('parses --ep-bin', () => {
+    const out = parseArgs(['node', 'harness', '--seed', '1', '--ep-bin', '/usr/local/bin/ep'])
+    expect(out.mode).toBe('run')
+    if (out.mode === 'run') expect(out.epBin).toBe('/usr/local/bin/ep')
+  })
+})

scripts/__tests__/lifecycle-harness/disk.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Unit tests for lifecycle harness disk: dirSizeBytes, totalSizeBytes.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  bytesToMb,
+  dirSizeBytes,
+  totalSizeBytes,
+  totalSizeBytesIncludingNodeModules,
+} from '../../lifecycle-harness/src/disk.js'
+
+describe('dirSizeBytes', () => {
+  it('returns 0 for non-existent or empty dir', () => {
+    const tmp = path.join(import.meta.dirname, `disk-test-${Date.now()}`)
+    expect(dirSizeBytes(tmp)).toBe(0)
+  })
+
+  it('sums file sizes and excludes node_modules', () => {
+    const tmp = path.join(import.meta.dirname, `disk-test-${Date.now()}`)
+    fs.mkdirSync(tmp, { recursive: true })
+    fs.mkdirSync(path.join(tmp, 'node_modules'), { recursive: true })
+    fs.writeFileSync(path.join(tmp, 'a.txt'), 'hello', 'utf-8')
+    fs.writeFileSync(path.join(tmp, 'node_modules', 'big.js'), 'x'.repeat(1000), 'utf-8')
+    try {
+      const size = dirSizeBytes(tmp)
+      expect(size).toBe(5)
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('totalSizeBytes', () => {
+  it('sums multiple dirs', () => {
+    const tmp = path.join(import.meta.dirname, `disk-test-${Date.now()}`)
+    fs.mkdirSync(tmp, { recursive: true })
+    const d1 = path.join(tmp, 'd1')
+    const d2 = path.join(tmp, 'd2')
+    fs.mkdirSync(d1, { recursive: true })
+    fs.mkdirSync(d2, { recursive: true })
+    fs.writeFileSync(path.join(d1, 'f'), 'ab', 'utf-8')
+    fs.writeFileSync(path.join(d2, 'g'), 'c', 'utf-8')
+    try {
+      expect(totalSizeBytes([d1, d2])).toBe(3)
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('totalSizeBytesIncludingNodeModules', () => {
+  it('includes node_modules in sum', () => {
+    const tmp = path.join(import.meta.dirname, `disk-test-${Date.now()}`)
+    fs.mkdirSync(tmp, { recursive: true })
+    fs.writeFileSync(path.join(tmp, 'a.txt'), 'x', 'utf-8')
+    fs.mkdirSync(path.join(tmp, 'node_modules'), { recursive: true })
+    fs.writeFileSync(path.join(tmp, 'node_modules', 'pkg.js'), 'yy', 'utf-8')
+    try {
+      expect(totalSizeBytesIncludingNodeModules([tmp])).toBe(3)
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('bytesToMb', () => {
+  it('converts bytes to MB', () => {
+    expect(bytesToMb(1024 * 1024)).toBe(1)
+    expect(bytesToMb(1024 * 1024 * 2.5)).toBe(2.5)
+  })
+})

scripts/__tests__/lifecycle-harness/list-parse.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Unit tests for parseFirstPatternIdFromList (ep list output parsing).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { parseFirstPatternIdFromList } from '../../lifecycle-harness/src/list-parse.js'
+
+describe('parseFirstPatternIdFromList', () => {
+  it('returns id from "Next: ep show <id>" line', () => {
+    const stdout = 'Some header\nNext: ep show retry-with-backoff\nMore text'
+    expect(parseFirstPatternIdFromList(stdout)).toBe('retry-with-backoff')
+  })
+
+  it('returns id from slug line (indented 2+ spaces)', () => {
+    const stdout = '  retry-with-backoff\n  other-pattern'
+    expect(parseFirstPatternIdFromList(stdout)).toBe('retry-with-backoff')
+  })
+
+  it('prefers Next: ep show over slug line', () => {
+    const stdout = '  first-slug\nNext: ep show preferred-id'
+    expect(parseFirstPatternIdFromList(stdout)).toBe('preferred-id')
+  })
+
+  it('returns null for empty string', () => {
+    expect(parseFirstPatternIdFromList('')).toBe(null)
+  })
+
+  it('returns null when no match', () => {
+    expect(parseFirstPatternIdFromList('No pattern here\nJust text')).toBe(null)
+  })
+})

scripts/__tests__/lifecycle-harness/prng.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Unit tests for lifecycle harness PRNG: determinism and range.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  mulberry32,
+  pick,
+  randomInt,
+  randomIntInclusive,
+  randomSubset,
+  shortRand,
+} from '../../lifecycle-harness/src/prng.js'
+
+describe('mulberry32', () => {
+  it('is deterministic: same seed yields same sequence', () => {
+    const rng1 = mulberry32(12345)
+    const rng2 = mulberry32(12345)
+    for (let i = 0; i < 20; i++) {
+      expect(rng1()).toBe(rng2())
+    }
+  })
+
+  it('returns values in [0, 1)', () => {
+    const rng = mulberry32(999)
+    for (let i = 0; i < 100; i++) {
+      const v = rng()
+      expect(v).toBeGreaterThanOrEqual(0)
+      expect(v).toBeLessThan(1)
+    }
+  })
+
+  it('different seeds yield different sequences', () => {
+    const a = mulberry32(1)
+    const b = mulberry32(2)
+    const valsA = [a(), a(), a()]
+    const valsB = [b(), b(), b()]
+    expect(valsA).not.toEqual(valsB)
+  })
+})
+
+describe('randomInt', () => {
+  it('returns integer in [0, max)', () => {
+    const rng = mulberry32(42)
+    for (let i = 0; i < 50; i++) {
+      const v = randomInt(rng, 10)
+      expect(Number.isInteger(v)).toBe(true)
+      expect(v).toBeGreaterThanOrEqual(0)
+      expect(v).toBeLessThan(10)
+    }
+  })
+})
+
+describe('pick', () => {
+  it('returns one element from array', () => {
+    const rng = mulberry32(7)
+    const arr = ['a', 'b', 'c']
+    const v = pick(rng, arr)
+    expect(arr).toContain(v)
+  })
+})
+
+describe('randomIntInclusive', () => {
+  it('returns integer in [min, max] inclusive', () => {
+    const rng = mulberry32(11)
+    const seen = new Set<number>()
+    for (let i = 0; i < 200; i++) {
+      const v = randomIntInclusive(rng, 5, 10)
+      expect(Number.isInteger(v)).toBe(true)
+      expect(v).toBeGreaterThanOrEqual(5)
+      expect(v).toBeLessThanOrEqual(10)
+      seen.add(v)
+    }
+    expect(seen.size).toBe(6)
+  })
+})
+
+describe('shortRand', () => {
+  it('returns string of requested length', () => {
+    const rng = mulberry32(13)
+    const s = shortRand(rng, 6)
+    expect(s.length).toBe(6)
+    expect(s).toMatch(/^[a-z0-9]+$/)
+  })
+})
+
+describe('randomSubset', () => {
+  it('returns subset of array', () => {
+    const rng = mulberry32(17)
+    const arr = [1, 2, 3, 4, 5]
+    const sub = randomSubset(rng, arr, 3)
+    expect(sub.length).toBeLessThanOrEqual(3)
+    for (const x of sub) expect(arr).toContain(x)
+  })
+
+  it('returns empty array when input is empty', () => {
+    const rng = mulberry32(19)
+    expect(randomSubset(rng, [], 5)).toEqual([])
+  })
+})

scripts/__tests__/lifecycle-harness/report.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Unit tests for lifecycle harness report: classifyOutcome, truncateStderr.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { classifyOutcome, truncateStderr } from '../../lifecycle-harness/src/report.js'
+
+describe('truncateStderr', () => {
+  it('returns input when within limit', () => {
+    const s = 'a'.repeat(100)
+    expect(truncateStderr(s)).toBe(s)
+  })
+
+  it('truncates and appends when over limit', () => {
+    const s = 'a'.repeat(2500)
+    const out = truncateStderr(s)
+    expect(out.length).toBeLessThan(s.length)
+    expect(out.endsWith('...[truncated]')).toBe(true)
+    expect(out.slice(0, 2000)).toBe(s.slice(0, 2000))
+  })
+})
+
+describe('classifyOutcome', () => {
+  it('success when exit 0 and not expectFailure', () => {
+    expect(classifyOutcome(0, false, '', {})).toBe('success')
+  })
+
+  it('hard-fail when timed out', () => {
+    expect(classifyOutcome(0, true, '', {})).toBe('hard-fail')
+    expect(classifyOutcome(1, true, '', {})).toBe('hard-fail')
+  })
+
+  it('soft-fail when non-zero and stderr has known external pattern (401)', () => {
+    expect(classifyOutcome(1, false, 'Error: 401 Unauthorized', {})).toBe('soft-fail')
+  })
+
+  it('soft-fail when non-zero and stderr has 404', () => {
+    expect(classifyOutcome(1, false, '404 Not Found', {})).toBe('soft-fail')
+  })
+
+  it('soft-fail when non-zero and stderr has ENOTFOUND', () => {
+    expect(classifyOutcome(1, false, 'getaddrinfo ENOTFOUND api.example.com', {})).toBe('soft-fail')
+  })
+
+  it('soft-fail when non-zero and stderr has not found pattern', () => {
+    expect(classifyOutcome(1, false, 'no such pattern', {})).toBe('soft-fail')
+  })
+
+  it('hard-fail when non-zero and stderr has no known pattern', () => {
+    expect(classifyOutcome(1, false, 'SyntaxError: unexpected token', {})).toBe('hard-fail')
+  })
+
+  it('expectedToFail: non-zero -> success', () => {
+    expect(classifyOutcome(1, false, '', { expectFailure: true })).toBe('success')
+    expect(classifyOutcome(1, false, 'any stderr', { expectFailure: true })).toBe('success')
+  })
+
+  it('expectedToFail: exit 0 -> soft-fail', () => {
+    expect(classifyOutcome(0, false, '', { expectFailure: true })).toBe('soft-fail')
+  })
+})