@nathapp/nax 0.18.1 → 0.18.2

package/.gitlab-ci.yml

@@ -80,10 +80,10 @@ release:
 # --- Stage: Notify ---
 notify:
   stage: notify
-  image: nathapp/node-bun:22.21.0-1.3.9-alpine
+  image: registry-intl.cn-hongkong.aliyuncs.com/gkci/node:22.14.0-alpine-ci
   needs: [release]
   script:
-    - VERSION=$(bun -e "console.log(require('./package.json').version)")
+    - VERSION=$(node -e "console.log(require('./package.json').version)")
     - 'curl -s -X POST -H "Content-Type: application/json" -d "{\"chat_id\": \"$TELEGRAM_CHAT_ID\", \"text\": \"nax v${VERSION} released\"}" https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage'
   rules:
     - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'

package/docs/ROADMAP.md

@@ -24,32 +24,29 @@
 
 ---
 
-## v0.18.1 — Type Safety + Per-Story testStrategy
+## v0.18.1 — Type Safety + CI Pipeline ✅
 
-**Theme:** Fix all TypeScript/lint errors + fine-grained test strategy control
-**Status:** 🔲 Planned
+**Theme:** Fix all TypeScript/lint errors, establish CI pipeline
+**Status:** ✅ Shipped (2026-03-03)
 
 ### TypeScript Fixes (60 errors across 21 files)
-- [ ] **TS-001:** Fix context module exports — add `BuiltContext`, `ContextElement`, `ContextBudget`, `StoryContext` to `context/types.ts` (13 errors)
-- [ ] **TS-002:** Fix config/command type safety — type `{}` → proper types in `config/loader.ts`, `commands/logs.ts`, `agents/claude.ts` (12 errors)
-- [ ] **TS-003:** Fix review/verification types — add `softViolations`, `warnings`, `description` to review result types (9 errors)
-- [ ] **TS-004:** Fix escalation PRD type construction — ensure escalation produces valid `PRD` objects (4 errors)
-- [ ] **TS-005:** Fix misc — Logger mock types, null checks, missing exports (`RectificationState`, `TestSummary`, `TestFailure`) (6 errors)
-
-### Lint Fixes (12 errors)
-- [ ] **LINT-001:** Run `biome check --fix` + manual review of unsafe fixes
-
-### Verify Stage Fix
-- [ ] **TEST-001:** Fix hanging "test command that throws error" test — add timeout or proper process kill
-
-### Per-Story testStrategy
-- [ ] Add optional `testStrategy` field to userStory PRD schema (`"test-after" | "three-session-tdd" | "three-session-tdd-lite"`)
-- [ ] When set, overrides global config + task classification for that story
-- [ ] Update routing stage to check `story.testStrategy` before config/LLM
-- [ ] Docs + tests
-
-### Re-enable Checks
-- [ ] Re-enable `typecheck` in `nax/config.json` review checks after TS fixes land
+- [x] ~~**TS-001:** Fix context module exports (13 errors)~~
+- [x] ~~**TS-002:** Fix config/command type safety (12 errors)~~
+- [x] ~~**TS-003:** Fix review/verification types (9 errors)~~
+- [x] ~~**TS-004:** Fix escalation PRD type construction (4 errors)~~
+- [x] ~~**TS-005:** Fix misc types (6 errors)~~
+- [x] ~~**LINT-001:** Run biome check --fix + manual review~~
+
+### CI Pipeline (new)
+- [x] `.gitlab-ci.yml` — stages: test → release → notify
+- [x] Image: `nathapp/node-bun:22.21.0-1.3.9-alpine` (test/release), `gkci/node:22.14.0-alpine-ci` (notify)
+- [x] `before_script`: apk add git python3 make g++, safe.directory, git identity
+- [x] Test env: `NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000`
+- [x] CI skip guards for env-sensitive tests (claude binary, PID checks, subprocess integration)
+- [x] Fixed `checkClaudeCLI()` ENOENT crash — try/catch around Bun.spawn
+- [x] Release trigger: `[run-release]` in commit message on master
+- [x] Runner requirement: 8GB shared runner (`saas-linux-small-amd64`)
+- [x] **Result: 1952 pass, 56 skip, 0 fail**
 
 ---
 
@@ -96,6 +93,7 @@
 
 | Version | Theme | Date | Details |
 |:---|:---|:---|:---|
+| v0.18.1 | Type Safety + CI Pipeline | 2026-03-03 | 60 TS errors + 12 lint errors fixed, GitLab CI green (1952/56/0) |
 | v0.18.0 | Orchestration Quality | 2026-03-03 | BUG-016/017/018/019/020/021/022/023/025 all fixed |
 | v0.17.0 | Config Management | 2026-03-02 | CM-001 --explain, CM-002 --diff, CM-003 default view |
 | v0.16.4 | Bugfixes: Routing + Env Allowlist | 2026-03-02 | BUG-012/013/014 |

package/nax/config.json

@@ -63,11 +63,14 @@
     "verificationTimeoutSeconds": 300,
     "maxStoriesPerFeature": 15,
     "rectification": {
-      "enabled": true,
+      "enabled": false,
       "maxRetries": 2,
-      "fullSuiteTimeoutSeconds": 120,
+      "fullSuiteTimeoutSeconds": 600,
       "maxFailureSummaryChars": 2000,
       "abortOnIncreasingFailures": true
+    },
+    "regressionGate": {
+      "enabled": false
     }
   },
   "quality": {
@@ -75,9 +78,9 @@
     "requireLint": true,
     "requireTests": true,
     "commands": {
-      "test": "bun test --no-coverage",
-      "typecheck": "bun x tsc --noEmit",
-      "lint": "bun x biome check src/ bin/"
+      "test": "bun run test",
+      "typecheck": "bun run typecheck",
+      "lint": "bun run lint"
     },
     "forceExit": false,
     "detectOpenHandles": true,
@@ -114,15 +117,15 @@
     "maxCodebaseSummaryTokens": 5000
   },
   "review": {
-    "enabled": true,
+    "enabled": false,
     "checks": [
       "test",
       "lint"
     ],
     "commands": {
-      "test": "bun test --no-coverage",
-      "typecheck": "bun x tsc --noEmit",
-      "lint": "bun x biome check src/ bin/"
+      "test": "bun run test",
+      "typecheck": "bun run typecheck",
+      "lint": "bun run lint"
     }
   },
   "plan": {

package/nax/features/smart-test-runner/plan.md

@@ -0,0 +1,7 @@
+# Plan: smart-test-runner
+
+## Architecture
+
+## Phases
+
+## Dependencies

package/nax/features/smart-test-runner/prd.json

@@ -0,0 +1,203 @@
+{
+  "project": "nax",
+  "feature": "smart-test-runner",
+  "branchName": "feat/v0.18.2-smart-runner",
+  "userStories": [
+    {
+      "id": "FIX-001",
+      "title": "Fix partial routing override in routing stage",
+      "description": "In `src/pipeline/stages/routing.ts`, the code unconditionally overwrites complexity and testStrategy from story.routing, even if undefined. Fix: only override when the field is actually set. Change line 41 `routing.complexity = ctx.story.routing.complexity` to `if (ctx.story.routing?.complexity) routing.complexity = ctx.story.routing.complexity`. Same for testStrategy on the next line. This allows PRD authors to set just `\"routing\": { \"testStrategy\": \"test-after\" }` without needing complexity/modelTier. Add test in `test/unit/pipeline/routing-partial-override.test.ts` verifying: (1) partial override with only testStrategy works, (2) LLM-classified complexity is preserved when not overridden, (3) full override still works.",
+      "complexity": "simple",
+      "status": "passed",
+      "tags": [
+        "bugfix"
+      ],
+      "acceptanceCriteria": [
+        "routing.complexity is only overridden when ctx.story.routing.complexity is defined",
+        "routing.testStrategy is only overridden when ctx.story.routing.testStrategy is defined",
+        "PRD with only routing.testStrategy set uses LLM for complexity",
+        "Test file test/unit/pipeline/routing-partial-override.test.ts exists with 3 passing tests"
+      ],
+      "dependencies": [],
+      "escalations": [],
+      "attempts": 1,
+      "passes": true,
+      "routing": {
+        "testStrategy": "test-after"
+      },
+      "priorErrors": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "STR-001",
+      "title": "Git diff file detection",
+      "description": "Create module `src/verification/smart-runner.ts` with exported function `getChangedSourceFiles(workdir: string): Promise<string[]>`. Runs `git diff --name-only HEAD~1` in the workdir to get changed files. Filter to only `.ts` files that start with `src/`. Use Bun.spawn for the git command. Handle git errors gracefully (return empty array on failure).",
+      "complexity": "simple",
+      "status": "passed",
+      "tags": [
+        "core"
+      ],
+      "acceptanceCriteria": [
+        "getChangedSourceFiles returns only .ts files under src/",
+        "Returns empty array when git command fails",
+        "Uses Bun.spawn (not child_process)"
+      ],
+      "dependencies": [
+        "FIX-001"
+      ],
+      "escalations": [],
+      "attempts": 0,
+      "passes": true,
+      "routing": {
+        "testStrategy": "test-after",
+        "modelTier": "powerful"
+      },
+      "priorErrors": [
+        "REGRESSION: full-suite regression detected",
+        "Attempt 2 failed with model tier: fast",
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "storyPoints": 1
+    },
+    {
+      "id": "STR-002",
+      "title": "Source-to-test file mapping",
+      "description": "Add `mapSourceToTests(sourceFiles: string[], workdir: string): Promise<string[]>` to `src/verification/smart-runner.ts`. Convention: `src/foo/bar.ts` → `test/unit/foo/bar.test.ts`. Also check `test/integration/foo/bar.test.ts`. Only return paths where the file actually exists on disk (use Bun.file(path).exists()). Return empty array if no test files map.",
+      "complexity": "simple",
+      "status": "passed",
+      "tags": [
+        "core"
+      ],
+      "acceptanceCriteria": [
+        "Maps src/foo/bar.ts to test/unit/foo/bar.test.ts correctly",
+        "Also checks test/integration/ path",
+        "Only returns files that exist on disk",
+        "Returns empty array when no test files match"
+      ],
+      "dependencies": [
+        "STR-001"
+      ],
+      "escalations": [],
+      "attempts": 0,
+      "passes": true,
+      "routing": {
+        "testStrategy": "test-after"
+      },
+      "priorErrors": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "STR-003",
+      "title": "Smart test command builder",
+      "description": "Add `buildSmartTestCommand(testFiles: string[], baseCommand: string): string` to `src/verification/smart-runner.ts`. When testFiles is non-empty: replace the last path argument in baseCommand with the specific test file paths joined by spaces. E.g., `bun test test/` with files `[test/unit/foo.test.ts]` → `bun test test/unit/foo.test.ts`. When testFiles is empty: return the original baseCommand unchanged (full suite fallback).",
+      "complexity": "simple",
+      "status": "passed",
+      "tags": [
+        "core"
+      ],
+      "acceptanceCriteria": [
+        "Builds scoped command with specific test files",
+        "Returns original command when testFiles is empty",
+        "Works with bun test test/ base command"
+      ],
+      "dependencies": [
+        "STR-002"
+      ],
+      "escalations": [],
+      "attempts": 0,
+      "passes": true,
+      "routing": {
+        "testStrategy": "test-after"
+      },
+      "priorErrors": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "STR-004",
+      "title": "Smart runner config flag",
+      "description": "Add `execution.smartTestRunner: boolean` (default: true) to the config in `src/config/types.ts` (ExecutionConfig interface) and the Zod schema in `src/config/loader.ts`. When false, the verify stage skips smart runner entirely and uses the full test suite command.",
+      "complexity": "simple",
+      "status": "passed",
+      "tags": [
+        "config"
+      ],
+      "acceptanceCriteria": [
+        "execution.smartTestRunner field exists in ExecutionConfig interface",
+        "Zod schema accepts and defaults to true",
+        "Config loads correctly with and without the field"
+      ],
+      "dependencies": [
+        "STR-003"
+      ],
+      "escalations": [],
+      "attempts": 0,
+      "passes": true,
+      "routing": {
+        "testStrategy": "test-after"
+      },
+      "priorErrors": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "STR-005",
+      "title": "Integrate smart runner into verify stage",
+      "description": "Modify `src/pipeline/stages/verify.ts` to use smart runner when `ctx.config.execution.smartTestRunner` is true (default). Before calling regression(): call getChangedSourceFiles(ctx.workdir) → mapSourceToTests(files, ctx.workdir) → buildSmartTestCommand(testFiles, testCommand). Use the result as the command for regression(). Log which mode was selected: `[smart-runner] Running N targeted test files` or `[smart-runner] No mapped tests — falling back to full suite`.",
+      "complexity": "medium",
+      "status": "passed",
+      "tags": [
+        "integration"
+      ],
+      "acceptanceCriteria": [
+        "Verify stage uses scoped test command when smart runner finds test files",
+        "Falls back to full suite when no test files map",
+        "Skips smart runner entirely when config.execution.smartTestRunner is false",
+        "Logs the mode used"
+      ],
+      "dependencies": [
+        "STR-004"
+      ],
+      "escalations": [],
+      "attempts": 1,
+      "passes": true,
+      "routing": {
+        "testStrategy": "test-after",
+        "modelTier": "powerful"
+      },
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast",
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "storyPoints": 1
+    },
+    {
+      "id": "STR-006",
+      "title": "Unit tests for smart runner module",
+      "description": "Write `test/unit/verification/smart-runner.test.ts` with tests: (1) getChangedSourceFiles filters to .ts src/ files only, (2) mapSourceToTests maps paths correctly and checks file existence, (3) mapSourceToTests returns empty when files don't exist, (4) buildSmartTestCommand builds scoped command with test files, (5) buildSmartTestCommand returns original command when testFiles is empty. Use temp dirs with Bun.write for file existence tests.",
+      "complexity": "medium",
+      "status": "failed",
+      "tags": [
+        "test"
+      ],
+      "acceptanceCriteria": [
+        "5 test cases all pass",
+        "Uses temp dirs for file existence tests",
+        "No external process spawning in unit tests (mock Bun.spawn)"
+      ],
+      "dependencies": [
+        "STR-005"
+      ],
+      "escalations": [],
+      "attempts": 1,
+      "passes": false,
+      "routing": {
+        "testStrategy": "test-after",
+        "modelTier": "powerful"
+      },
+      "priorErrors": [
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "storyPoints": 1
+    }
+  ],
+  "updatedAt": "2026-03-03T14:17:09.852Z"
+}

package/nax/features/smart-test-runner/progress.txt

@@ -0,0 +1,13 @@
+# Progress: smart-test-runner
+
+Created: 2026-03-03T11:45:10.257Z
+
+---
+[2026-03-03T12:12:58.473Z] FIX-001 — FAILED — Fix partial routing override in routing stage — Review failed: test failed (exit code 132)
+[2026-03-03T12:27:31.803Z] STR-001 — PASSED — Git diff file detection — Cost: $0.0994
+[2026-03-03T12:29:37.971Z] STR-001 — FAILED — Git diff file detection -- REGRESSION: full-suite regression detected
+[2026-03-03T12:52:43.615Z] STR-002 — PASSED — Source-to-test file mapping — Cost: $0.0889
+[2026-03-03T12:59:34.497Z] STR-003 — PASSED — Smart test command builder — Cost: $0.0862
+[2026-03-03T13:05:48.251Z] STR-004 — PASSED — Smart runner config flag — Cost: $0.1583
+[2026-03-03T13:21:09.123Z] STR-005 — FAILED — Integrate smart runner into verify stage — Execution failed
+[2026-03-03T14:17:09.853Z] STR-006 — FAILED — Unit tests for smart runner module — Execution failed

package/nax/features/smart-test-runner/spec.md

@@ -0,0 +1,7 @@
+# Feature: smart-test-runner
+
+## Overview
+
+## Requirements
+
+## Acceptance Criteria

package/nax/features/smart-test-runner/tasks.md

@@ -0,0 +1,8 @@
+# Tasks: smart-test-runner
+
+## US-001: [Title]
+
+### Description
+
+### Acceptance Criteria
+- [ ] Criterion 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/config/defaults.ts

@@ -68,6 +68,7 @@ export const DEFAULT_CONFIG: NaxConfig = {
       timeoutSeconds: 120,
     },
     contextProviderTokenBudget: 2000,
+    smartTestRunner: true,
   },
   quality: {
     requireTypecheck: true,

package/src/config/schemas.ts

@@ -81,6 +81,7 @@ const ExecutionConfigSchema = z.object({
   lintCommand: z.string().nullable().optional(),
   typecheckCommand: z.string().nullable().optional(),
   dangerouslySkipPermissions: z.boolean().default(true),
+  smartTestRunner: z.boolean().default(true),
 });
 
 const QualityConfigSchema = z.object({

package/src/config/types.ts

@@ -106,6 +106,8 @@ export interface ExecutionConfig {
   typecheckCommand?: string | null;
   /** Use --dangerously-skip-permissions flag for agent (default: true for backward compat, SEC-1 fix) */
   dangerouslySkipPermissions?: boolean;
+  /** Enable smart test runner to scope test runs to changed files (default: true) */
+  smartTestRunner?: boolean;
 }
 
 /** Quality gate config */

package/src/pipeline/stages/routing.ts

@@ -36,10 +36,10 @@ export const routingStage: PipelineStage = {
     if (ctx.story.routing) {
       // Use cached complexity/testStrategy, but re-derive modelTier from current config
       routing = await routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
-      // Override with cached complexity if available
-      routing.complexity = ctx.story.routing.complexity;
-      routing.testStrategy = ctx.story.routing.testStrategy;
-      // Re-derive modelTier from cached complexity and current config
+      // Override with cached values only when they are actually set
+      if (ctx.story.routing?.complexity) routing.complexity = ctx.story.routing.complexity;
+      if (ctx.story.routing?.testStrategy) routing.testStrategy = ctx.story.routing.testStrategy;
+      // Re-derive modelTier from (possibly overridden) complexity and current config
       routing.modelTier = complexityToModelTier(routing.complexity as import("../../config").Complexity, ctx.config);
     } else {
       // Fresh classification

package/src/pipeline/stages/verify.ts

@@ -22,6 +22,7 @@
 
 import { getLogger } from "../../logger";
 import { regression } from "../../verification/gate";
+import { _smartRunnerDeps } from "../../verification/smart-runner";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
 export const verifyStage: PipelineStage = {
@@ -46,10 +47,28 @@ export const verifyStage: PipelineStage = {
 
     logger.info("verify", "Running verification", { storyId: ctx.story.id });
 
+    // Determine effective test command (smart runner or full suite)
+    let effectiveCommand = testCommand;
+    const smartRunnerEnabled = ctx.config.execution.smartTestRunner !== false;
+
+    if (smartRunnerEnabled) {
+      const sourceFiles = await _smartRunnerDeps.getChangedSourceFiles(ctx.workdir);
+      const testFiles = await _smartRunnerDeps.mapSourceToTests(sourceFiles, ctx.workdir);
+
+      if (testFiles.length > 0) {
+        effectiveCommand = _smartRunnerDeps.buildSmartTestCommand(testFiles, testCommand);
+        logger.info("verify", `[smart-runner] Running ${testFiles.length} targeted test files`, {
+          storyId: ctx.story.id,
+        });
+      } else {
+        logger.info("verify", "[smart-runner] No mapped tests — falling back to full suite", { storyId: ctx.story.id });
+      }
+    }
+
     // Use unified regression gate (includes 2s wait for agent process cleanup)
     const result = await regression({
       workdir: ctx.workdir,
-      command: testCommand,
+      command: effectiveCommand,
       timeoutSeconds: ctx.config.execution.verificationTimeoutSeconds,
     });
 

package/src/precheck/index.ts

@@ -62,6 +62,8 @@ export interface PrecheckOptions {
   format?: "human" | "json";
   /** Working directory */
   workdir: string;
+  /** Suppress console output (for programmatic use) */
+  silent?: boolean;
 }
 
 /** Extended result with exit code for CLI usage */
@@ -87,6 +89,7 @@ export async function runPrecheck(
 ): Promise<PrecheckResultWithCode> {
   const workdir = options?.workdir || process.cwd();
   const format = options?.format || "human";
+  const silent = options?.silent ?? false;
 
   const passed: Check[] = [];
   const blockers: Check[] = [];
@@ -196,10 +199,12 @@ export async function runPrecheck(
     exitCode = hasPRDError ? EXIT_CODES.INVALID_PRD : EXIT_CODES.BLOCKER;
   }
 
-  if (format === "json") {
-    console.log(JSON.stringify(output, null, 2));
-  } else {
-    printSummary(output);
+  if (!silent) {
+    if (format === "json") {
+      console.log(JSON.stringify(output, null, 2));
+    } else {
+      printSummary(output);
+    }
   }
 
   return {

package/src/verification/smart-runner.ts

@@ -0,0 +1,146 @@
+/**
+ * Smart Runner — Git diff file detection
+ *
+ * Detects changed TypeScript source files using git diff,
+ * enabling targeted test runs on only the files that changed.
+ */
+
+/**
+ * Get TypeScript source files changed since the previous commit.
+ *
+ * Runs `git diff --name-only HEAD~1` in the given workdir and filters
+ * results to only `.ts` files under `src/`. Returns an empty array on
+ * any git error (not a repo, no previous commit, etc.).
+ *
+ * @param workdir - Working directory to run git command in
+ * @returns Array of changed .ts file paths relative to the repo root
+ *
+ * @example
+ * ```typescript
+ * const files = await getChangedSourceFiles("/path/to/repo");
+ * // Returns: ["src/foo/bar.ts", "src/utils/git.ts"]
+ * ```
+ */
+/**
+ * Map source files to their corresponding test files.
+ *
+ * For each file in `sourceFiles`, checks both:
+ *   - `<workdir>/test/unit/<relative-path>.test.ts`
+ *   - `<workdir>/test/integration/<relative-path>.test.ts`
+ *
+ * where `<relative-path>` is the file path with the leading `src/` stripped
+ * and the `.ts` extension replaced with `.test.ts`.
+ *
+ * Only returns paths that actually exist on disk.
+ *
+ * @param sourceFiles - Array of source file paths (e.g. `["src/foo/bar.ts"]`)
+ * @param workdir     - Absolute path to the repository root
+ * @returns Existing test file paths (absolute)
+ *
+ * @example
+ * ```typescript
+ * const tests = await mapSourceToTests(["src/foo/bar.ts"], "/repo");
+ * // Returns: ["/repo/test/unit/foo/bar.test.ts"] (if it exists)
+ * ```
+ */
+export async function mapSourceToTests(sourceFiles: string[], workdir: string): Promise<string[]> {
+  const result: string[] = [];
+
+  for (const sourceFile of sourceFiles) {
+    // Strip leading "src/" and replace ".ts" with ".test.ts"
+    const relative = sourceFile.replace(/^src\//, "").replace(/\.ts$/, ".test.ts");
+
+    const candidates = [`${workdir}/test/unit/${relative}`, `${workdir}/test/integration/${relative}`];
+
+    for (const candidate of candidates) {
+      if (await Bun.file(candidate).exists()) {
+        result.push(candidate);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a scoped test command targeting specific test files.
+ *
+ * When `testFiles` is non-empty, replaces the last path-like argument in
+ * `baseCommand` (a token containing `/`) with the specific test file paths
+ * joined by spaces. If no path argument is found, appends the test files.
+ *
+ * When `testFiles` is empty, returns `baseCommand` unchanged (full-suite
+ * fallback).
+ *
+ * @param testFiles   - Test file paths to scope the run to
+ * @param baseCommand - Full test command (e.g. `"bun test test/"`)
+ * @returns Scoped command string
+ *
+ * @example
+ * ```typescript
+ * buildSmartTestCommand(["test/unit/foo.test.ts"], "bun test test/")
+ * // => "bun test test/unit/foo.test.ts"
+ *
+ * buildSmartTestCommand([], "bun test test/")
+ * // => "bun test test/"
+ * ```
+ */
+export function buildSmartTestCommand(testFiles: string[], baseCommand: string): string {
+  if (testFiles.length === 0) {
+    return baseCommand;
+  }
+
+  const parts = baseCommand.trim().split(/\s+/);
+
+  // Find the last token that looks like a path (contains '/')
+  let lastPathIndex = -1;
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (parts[i].includes("/")) {
+      lastPathIndex = i;
+      break;
+    }
+  }
+
+  if (lastPathIndex === -1) {
+    // No path argument — append test files
+    return `${baseCommand} ${testFiles.join(" ")}`;
+  }
+
+  // Replace the last path argument with the specific test files
+  const newParts = [...parts.slice(0, lastPathIndex), ...testFiles];
+  return newParts.join(" ");
+}
+
+export async function getChangedSourceFiles(workdir: string): Promise<string[]> {
+  try {
+    const proc = Bun.spawn({
+      cmd: ["git", "diff", "--name-only", "HEAD~1"],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) return [];
+
+    const stdout = await new Response(proc.stdout).text();
+    const lines = stdout.trim().split("\n").filter(Boolean);
+
+    return lines.filter((f) => f.startsWith("src/") && f.endsWith(".ts"));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Injectable dependencies for testing.
+ * Allows tests to swap implementations without using mock.module(),
+ * which leaks across files in Bun 1.x due to shared module registry.
+ *
+ * @internal - test use only. Do not use in production code.
+ */
+export const _smartRunnerDeps = {
+  getChangedSourceFiles,
+  mapSourceToTests,
+  buildSmartTestCommand,
+};