fix(cli): all LLM CLIs spawn in temp staging dir instead of user's working directory

[Copilot]

Problem

Fixes #156 — Launching LLM CLI does not preserve current working directory

When running npx @alan-jowett/promptkit --cli claude (or any non-Copilot CLI), the LLM session started in the temporary staging directory (/tmp/promptkit-xxx/) instead of the user's actual working directory. This meant the LLM had no awareness of the user's project files and could not operate on their codebase.

Root cause: launch.js spawned all CLI child processes with cwd: tmpDir — the temporary directory where PromptKit content files are staged. The Copilot CLI happened to work around this because it resolved the working directory differently, but Claude and other CLIs honored the spawn cwd literally.

Additionally, the bootstrap prompt used a relative path ("Read and execute bootstrap.md"), which only resolved correctly when cwd was the staging directory. Changing cwd to the user's directory required switching to an absolute path.

---

Fix

Core change (cli/lib/launch.js)

1. Capture originalCwd — record process.cwd() before any directory changes.
2. Spawn with cwd: originalCwd — all CLI child processes now start in the user's working directory instead of the temp staging dir.
3. Absolute bootstrap path — the prompt is now "Read and execute /tmp/promptkit-xxx/bootstrap.md" (absolute), so the LLM can locate it regardless of working directory.
4. --add-dir <tmpDir> — all CLIs (copilot, gh-copilot, claude) receive --add-dir pointing at the staging directory, granting file access to PromptKit content without requiring cwd to be set there.

Spec updates (cli/specs/requirements.md)

• REQ-CLI-015 updated: spawn cwd must be the user's original directory (not temp dir).
• REQ-CLI-016 updated: bootstrap prompt must use an absolute path to bootstrap.md.
• REQ-CLI-017 updated: all CLIs must receive --add-dir <tmpDir> and absolute bootstrap path.
• REQ-CLI-024 added: CWD preservation requirement for all supported CLIs.
• REQ-CLI-025 added: --add-dir staging directory requirement for all CLIs.

Validation updates (cli/specs/validation.md)

• TC-CLI-080 updated: expected bootstrap prompt now contains an absolute path.
• TC-CLI-081 updated: expected spawn args include --add-dir and absolute path.
• TC-CLI-082 added: integration test verifying spawned CWD equals user's directory.
• TC-CLI-083 added: integration test verifying --add-dir is in spawn args.

Tests (cli/tests/launch.test.js)

• New test file with unit tests for the launch module covering the CWD and --add-dir behaviors.

Housekeeping

• docs/case-studies/ebpf_epoch.md → docs/case-studies/ebpf-epoch.md (snake_case → kebab-case filename convention; also fixes CRLF line endings via .gitattributes normalization).
• Version bump 0.2.0 → 0.5.0 in package-lock.json.

---

Changed Files

File	Change
cli/lib/launch.js	Core fix: CWD preservation, absolute paths, --add-dir
cli/specs/requirements.md	Added REQ-CLI-024, REQ-CLI-025; updated REQ-CLI-015/016/017
cli/specs/validation.md	Added TC-CLI-082, TC-CLI-083; updated TC-CLI-080/081
cli/tests/launch.test.js	New test file for launch module
cli/package-lock.json	Version bump 0.2.0 → 0.5.0
docs/case-studies/ebpf-epoch.md	Renamed from ebpf_epoch.md (kebab-case + LF fix)

[Copilot]

Pull request overview

Fixes PromptKit CLI interactive launch so spawned LLM CLIs start in the user’s original working directory (instead of the temp staging dir), while still granting access to staged PromptKit content via --add-dir and using an absolute bootstrap.md path.

Changes:

• Update launchInteractive() to preserve the user’s CWD, switch bootstrap prompt to an absolute staged path, and add --add-dir <tmpDir> for supported CLIs.
• Update CLI requirements/validation specs to codify the CWD preservation + --add-dir behavior.
• Add launch-module tests covering CWD preservation and presence of --add-dir.

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/case-studies/ebpf-epoch.md	Housekeeping/normalization of a case study doc (formatting/line endings).
cli/lib/launch.js	Spawn child CLIs with cwd: originalCwd, absolute bootstrap path, and --add-dir <tmpDir>.
cli/tests/launch.test.js	Adds tests for absolute bootstrap prompt, preserved CWD, and --add-dir.
cli/specs/requirements.md	Updates/extends requirements for CWD preservation + --add-dir staging access.
cli/specs/validation.md	Updates validation cases and traceability for new/updated requirements.
cli/package-lock.json	Version bump reflected in lockfile.

Files not reviewed (1)

• cli/package-lock.json: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 4 out of 6 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• cli/package-lock.json: Language not supported

[Alan-Jowett]

Review: PR #157 — CWD preservation for LLM CLIs

Overall

The core fix in launch.js is clean and correct — capturing originalCwd before staging, switching to an absolute bootstrap path, and adding --add-dir is the right approach. Spec updates are thorough, all 9 previous review comments have been addressed, and the 24 pre-existing tests pass. However, the 3 new integration tests (TC-CLI-082/083) all fail on Windows.

---

🔴 All 3 new integration tests fail on Windows

Running npm test on Windows (Node v22, Windows 11):

✖ TC-CLI-082/083: claude spawned with originalCwd and --add-dir for staging dir
✖ TC-CLI-082/083: copilot spawned with originalCwd and --add-dir for staging dir
✖ TC-CLI-082/083: gh-copilot spawned with originalCwd and --add-dir for staging dir

AssertionError [ERR_ASSERTION]: mock claude should have written capture file

Root cause: spawn() on Windows cannot execute .cmd files without shell: true.

The tests create mock CLI executables as .cmd wrapper scripts (e.g., claude.cmd). However, launchInteractive() in launch.js calls spawn(cmd, args, { cwd, stdio }) without shell: true. On Windows, spawn() without shell: true only resolves .exe files — it gives ENOENT for .cmd/.bat files, even when they are on PATH.

The result: the .cmd mocks are invisible to spawn(), the real .exe CLI binaries further down PATH get invoked instead, and the capture files are never written.

Empirical verification

I tested all three behaviors independently on this machine:

Operation	.cmd on PATH	Result
where fakecli (used by detectCli)	✅ Finds it	Returns full path to fakecli.cmd
spawn('fakecli') — no shell (used by launchInteractive)	❌ ENOENT	Cannot execute
spawn('fakecli', [], { shell: true })	✅ Works	Executes correctly

Test script:

const { execFileSync, spawn } = require('child_process');
const fs = require('fs');
const path = require('path');
const os = require('os');

const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'spawn-test-'));
fs.writeFileSync(path.join(tmpDir, 'fakecli.cmd'), '@echo FOUND_ME\r\n');

// 'where' finds .cmd files
execFileSync('where', ['fakecli'], {
  env: { ...process.env, PATH: tmpDir + ';' + process.env.PATH },
  encoding: 'utf8'
});
// => "C:\Users\...\spawn-test-xxx\fakecli.cmd"

// spawn WITHOUT shell: true — FAILS
spawn('fakecli', [], { env: { ...process.env, PATH: tmpDir }, stdio: 'pipe' });
// => error event: ENOENT

// spawn WITH shell: true — WORKS
spawn('fakecli', [], { env: { ...process.env, PATH: tmpDir }, stdio: 'pipe', shell: true });
// => exits 0, output: "FOUND_ME"

Detection-vs-execution mismatch (pre-existing)

This also reveals a pre-existing issue in launch.js (not introduced by this PR): detectCli() uses where/which via execFileSync, which does find .cmd files. But launchInteractive() uses spawn() without shell: true, which cannot execute them. So a CLI installed as a .cmd wrapper (e.g., npm install -g @anthropic-ai/claude-code on Windows, which creates claude.cmd) would be detected successfully but then fail to launch.

On this machine all three CLIs are .exe (WinGet/installer), so it works in practice:

copilot : C:\Users\alanjo\AppData\Local\Microsoft\WinGet\Links\copilot.exe
claude  : C:\Users\alanjo\.claude-cli\CurrentVersion\claude.exe
gh      : C:\Program Files\GitHub CLI\gh.exe

But npm global installs on Windows produce .cmd wrappers, and those would hit this bug.

Suggested fix

Adding shell: true to the spawn() call in launch.js would fix both the test failures and the pre-existing production issue:

const child = spawn(cmd, args, {
  cwd: originalCwd,
  stdio: "inherit",
  shell: true,  // Required on Windows to resolve .cmd/.bat files
});

The args are all programmatically constructed (no user input), so there's no shell-injection risk.

---

🟡 Minor: Traceability matrix ordering

In validation.md, REQ-CLI-024/025 appear after REQ-CLI-019 but before REQ-CLI-020, breaking the sequential ordering in the table. Cosmetic, but could confuse readers.

---

ℹ️ Notes

• package-lock.json 0.2.0 → 0.5.0: Just syncing with package.json which was already at 0.5.0 on main. Fine.
• ebpf-epoch.md rename: Content-identical, kebab-case + CRLF→LF normalization. Inflates the diff but correct per repo conventions.
• All 24 pre-existing tests pass ✅
• CLA check passes ✅

[abeltrano]

Both items addressed in 7797ba0:

🔴 Windows .cmd spawn failure (TC-CLI-082/083)

Added shell: true to the spawn() call in launch.js. This fixes both:

• The test failures: mock .cmd wrappers are now executable by spawn()
• The pre-existing production issue: CLIs installed via npm install -g (which produce .cmd wrappers) would be detected by detectCli() but then fail to launch

All spawn args are programmatically constructed (no user input), so there is no shell-injection risk. All 27 tests now pass (including the 3 previously-failing TC-CLI-082/083 integration tests).

🟡 Traceability matrix ordering

Moved REQ-CLI-024/025 after REQ-CLI-023 so the table follows sequential REQ numbering.