Integration and Smoke Tests

Relevant Source Files

• src/cli/adopt.ts
• src/cli/config.ts
• src/cli/dashboard.ts
• src/cli/next.ts
• src/cli/plan.ts
• src/cli/progress.ts
• src/cli/review.ts
• src/cli/roadmap.ts
• src/cli/session.ts
• src/index.ts
• src/types.ts
• test/cli-adopt-batch.test.ts
• test/cli-commands.test.ts
• test/cli-exit-codes.test.ts
• test/cli-json-output.test.ts
• test/session-cli.test.ts
• test/smoke.test.ts

Integration and smoke tests in PALEE ensure that the CLI commands, storage layer, engine algorithms, and process contracts function seamlessly as an integrated system. The suite is partitioned into Subprocess Integration Tests (executing the compiled or tsx-bootstrapped binary against isolated vault fixtures), In-Process Stream Mocking Tests (verifying exit codes and JSON contracts under intercepted standard I/O), and Package Smoke Tests (verifying distribution bundle exports).

---

1. CLI Subprocess Integration Tests

Subprocess integration tests spawn real child processes through the shared launcher in test/palee-cli.ts — the prebuilt dist/bin/palee.js in normal runs, the TypeScript sources behind --import tsx under coverage (ADR-0029). They run in isolated OS temporary directories and verify end-to-end command execution, flag handling, environment variable redirection, and disk mutation.

Command Pipeline Suite (test/cli-commands.test.ts)

Tests in test/cli-commands.test.ts exercise complete multi-command workflows:

• Configuration Management: Verifies palee config set-vault <path> creates .palee/config.json and updates the active vault path.
• Topic Adoption & State Preservation: Confirms palee adopt initializes note frontmatter (palee_id, topic_mastery, due_at, repetition), and subsequent palee roadmap imports never overwrite existing progress.
• Review Progression: Validates that palee review <id> <score> calculates new SM-2 intervals, advances due dates, updates mastery scores, and logs session history.
• Vault Boundary Security: Enforces sandbox isolation by verifying that attempting to access notes outside the vault via ../ path traversal exits with code 2.
• Concurrency & OCC Conflicts: Simulates concurrent modification collisions and asserts that mismatched fingerprints abort with exit code 4.

Batch Adoption Suite (test/cli-adopt-batch.test.ts)

Tests in test/cli-adopt-batch.test.ts verify multi-note batch onboarding:

• Directory Scoping & Recursive Discovery: Verifies adopting entire directories (palee adopt src/notes/) or vaults (palee adopt --all).
• Dry-Run Mode: Asserts that palee adopt --dry-run reports planned adoptions without modifying any files on disk.
• Safety Prompts & Non-Interactive Invariance: Confirms that running batch adoption without -y / --yes in non-interactive environments aborts cleanly with exit code 2.
• Pattern & Tag Filtering: Validates --tag <tag>, --include <glob>, and --exclude <glob> filtering options.
• Title Fallback Resolution: Verifies title extraction hierarchy (frontmatter title $\to$ H1 header $\to$ filename).
• Idempotency: Asserts that already-adopted notes are detected and skipped without error or duplicate ID generation.

---

2. In-Process CLI & Stream Mocking Tests

In-process tests import command handlers directly (adoptCommand, reviewCommand, nextCommand, sessionCommand, etc.) and intercept console.log, console.error, and process.exitCode. This approach enables rapid, deterministic verification of output schemas, error channels, and exit code contracts.

Deterministic Exit Code Matrix (test/cli-exit-codes.test.ts)

Tests in test/cli-exit-codes.test.ts systematically verify the 0–5 exit code contract across the eight commands the suite imports — config, migrate, roadmap, dashboard, next, plan, progress, and validate. 5 of the 13 registered commands (adopt, review, assess, session, update) are not imported there and so fall outside this matrix:

Exit Code	Classification	Trigger Scenarios Tested
0	Success	Command executed successfully and desired state achieved.
2	Usage / Validation Error	Missing required arguments, invalid flag combinations, batch adoption without -y in non-interactive shell, path traversal outside vault.
3	Schema / Graph Error	Unparseable YAML frontmatter, malformed roadmap files, circular dependency cycles detected in topic graph.
4	Concurrency Conflict	Optimistic Concurrency Control (OCC) fingerprint mismatch, active file lock collision.
5	Internal Runtime Error	Unexpected runtime exceptions, I/O filesystem permission errors.

Machine-Readable JSON Output (test/cli-json-output.test.ts)

Tests in test/cli-json-output.test.ts enforce Invariant INV-30 (#45) on the commands that support --json: the CLI registers 13 top-level commands, and only some of them stream machine-readable output:

• Schema Stability: Verifies that every command supporting --json emits valid, parseable JSON conforming to documented TypeScript interfaces.
• Empty State Resilience: Ensures that uninitialized or empty vaults return structured JSON (with null fields or [] arrays) rather than crashing.
• Error JSON Formatting: Validates that errors under --json emit a structured payload { "error": "description" } to stderr with appropriate exit codes.
• Explicit JSON Selection: Sets PALEE_JSON=1 and confirms that PALEE emits JSON without requiring the explicit --json flag; piping alone keeps the human-readable report (#357).
• Human-Only Commands: A command that declares no --json (review, adopt, assess, roadmap, migrate) stays human end to end even under PALEE_JSON; the env var never splits one command's output across formats.

In-Process Session CLI Dispatch (test/session-cli.test.ts)

Tests in test/session-cli.test.ts exercise the active session command layer:

• Topic Resolution Fallback: Tests resolveSessionTopic resolution hierarchy: explicit CLI argument $\to$ .palee/hot.md active topic frontmatter $\to$ clean exit code 2 on failure.
• Session Lifecycle: Verifies start, draft, end, and list subcommands.
• Unknown Action Handling: Asserts that unmapped session actions set process.exitCode = 2 with informative diagnostic messages.

---

3. Package Smoke Tests

Build & Export Parity (test/smoke.test.ts)

Tests in test/smoke.test.ts (2 tests) provide lightweight sanity verification for package artifacts:

• Module Loading: Confirms that the top-level package export (src/index.ts) loads cleanly without syntax or import errors.
• Version Parity: Asserts that the exported version constant strictly matches the version field defined in package.json.

---

Master Command Integration Matrix

Command	Subprocess Tests (cli-commands, cli-adopt-batch)	In-Process Exit Codes (cli-exit-codes)	JSON Contract Tests (cli-json-output)
palee config	Passed	Passed (Codes 0, 2)	N/A
palee adopt	Passed	Passed (Codes 0, 2, 4)	N/A
palee roadmap	Passed	Passed (Codes 0, 1, 2, 3, 4)	N/A
palee review	Passed	Passed (Codes 0, 2, 4)	N/A
palee next	Passed	Passed (Codes 0, 2)	Passed (next --json)
palee plan	Passed	Passed (Codes 0, 2)	Passed (plan --json)
palee progress	Passed	Passed (Codes 0, 2)	Passed (progress --json)
palee dashboard	Passed	Passed (Codes 0, 2)	Passed (dashboard --json)
palee session	Passed	Passed (Codes 0, 2)	Passed (session --json)
palee validate	N/A	Passed (Codes 0, 2, 3, 5)	Passed (validate --json)