c64bridge 0.5.1 → 0.6.0

package/dist/tools/programRunners.js

@@ -1,8 +1,10 @@
-import { AssemblyError } from "../assemblyConverter.js";
+import { assemblyToPrg, AssemblyError } from "../assemblyConverter.js";
+import { basicToPrg } from "../basicConverter.js";
 import { defineToolModule } from "./types.js";
 import { objectSchema, stringSchema } from "./schema.js";
 import { textResult } from "./responses.js";
 import { ToolExecutionError, ToolError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { pollForProgramOutcome } from "./pollValidator.js";
 function extractFailureDetails(details) {
     if (details === undefined || details === null) {
         return undefined;
@@ -21,6 +23,161 @@ function toRecord(details) {
     }
     return { value: details };
 }
+const BASIC_MAX_LINE = 63999;
+function parseBasicRuntimeErrors(screen) {
+    const errors = [];
+    const seen = new Set();
+    const rows = screen.replace(/\r\n?/g, "\n").split("\n");
+    for (const row of rows) {
+        if (!row || !row.toUpperCase().includes("ERROR IN")) {
+            continue;
+        }
+        const match = /ERROR\s+IN\s+(\d{1,5})/i.exec(row);
+        if (!match) {
+            continue;
+        }
+        const lineNumber = Number.parseInt(match[1] ?? "", 10);
+        if (!Number.isInteger(lineNumber) || lineNumber < 1 || lineNumber > BASIC_MAX_LINE) {
+            continue;
+        }
+        if (seen.has(lineNumber)) {
+            continue;
+        }
+        seen.add(lineNumber);
+        const typeMatch = /\?([A-Z ?]+?)\s+ERROR\s+IN/i.exec(row.toUpperCase());
+        const type = typeMatch?.[1]?.trim().replace(/\s+/g, " ") || undefined;
+        errors.push({
+            line: lineNumber,
+            type,
+            raw: row.trim(),
+        });
+    }
+    return errors;
+}
+function attemptAutoFixBasicProgram(program, errors) {
+    if (errors.length === 0) {
+        return undefined;
+    }
+    const normalized = program.replace(/\r\n?/g, "\n");
+    const lines = normalized.split("\n");
+    const indexByLine = new Map();
+    for (let index = 0; index < lines.length; index += 1) {
+        const rawLine = lines[index];
+        if (!rawLine) {
+            continue;
+        }
+        const match = /^\s*(\d+)\s*(.*)$/u.exec(rawLine);
+        if (!match) {
+            continue;
+        }
+        const lineNumber = Number.parseInt(match[1] ?? "", 10);
+        if (!Number.isInteger(lineNumber)) {
+            continue;
+        }
+        if (!indexByLine.has(lineNumber)) {
+            indexByLine.set(lineNumber, index);
+        }
+    }
+    const changes = [];
+    for (const error of errors) {
+        const index = indexByLine.get(error.line);
+        if (index === undefined) {
+            continue;
+        }
+        const rawLine = lines[index] ?? "";
+        const match = /^\s*(\d+)\s*(.*)$/u.exec(rawLine);
+        if (!match) {
+            continue;
+        }
+        const lineNumber = Number.parseInt(match[1] ?? "", 10);
+        let content = match[2] ?? "";
+        const notes = [];
+        const quoteAdjusted = content.replace(/""/g, "");
+        const quoteCount = (quoteAdjusted.match(/"/g) ?? []).length;
+        if (quoteCount % 2 !== 0) {
+            content = `${content}"`;
+            notes.push('appended missing closing quote (")');
+        }
+        const sanitized = stripRemarks(stripStrings(content));
+        const openParens = (sanitized.match(/\(/g) ?? []).length;
+        const closeParens = (sanitized.match(/\)/g) ?? []).length;
+        if (openParens > closeParens) {
+            const deficit = openParens - closeParens;
+            content = `${content}${")".repeat(deficit)}`;
+            notes.push(`appended ${deficit} closing parenthesis${deficit > 1 ? "es" : ""}`);
+        }
+        if (notes.length > 0) {
+            const updated = content.length > 0 ? `${lineNumber} ${content}` : `${lineNumber}`;
+            lines[index] = updated;
+            changes.push({
+                line: lineNumber,
+                notes,
+            });
+        }
+    }
+    if (changes.length === 0) {
+        return undefined;
+    }
+    return {
+        program: lines.join("\n"),
+        changes,
+    };
+}
+function stripStrings(content) {
+    let result = "";
+    let inString = false;
+    for (let index = 0; index < content.length; index += 1) {
+        const char = content[index];
+        if (char === '"') {
+            if (inString && content[index + 1] === '"') {
+                index += 1;
+                continue;
+            }
+            inString = !inString;
+            continue;
+        }
+        if (!inString) {
+            result += char;
+        }
+    }
+    return result;
+}
+function stripRemarks(content) {
+    const upper = content.toUpperCase();
+    const remIndex = upper.search(/(^|:)\s*REM\b/);
+    if (remIndex >= 0) {
+        return content.slice(0, remIndex);
+    }
+    return content;
+}
+function normalizeRuntimeErrors(errors) {
+    return errors.map((error) => ({
+        line: error.line,
+        ...(error.type ? { type: error.type } : {}),
+        text: error.raw,
+    }));
+}
+function structuredExecutionError(message, data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+        metadata: {
+            error: {
+                kind: "execution",
+                details: data,
+            },
+        },
+        structuredContent: {
+            type: "json",
+            data,
+        },
+        isError: true,
+    };
+}
 const uploadBasicArgsSchema = objectSchema({
     description: "Arguments for uploading and running a BASIC program.",
     properties: {
@@ -85,7 +242,7 @@ export const programRunnersModule = defineToolModule({
             description: "Upload a BASIC program to the C64 and execute it immediately. Refer to c64://specs/basic for syntax and device I/O.",
             summary: "Uploads Commodore BASIC v2 source and runs it via Ultimate 64 firmware.",
             inputSchema: uploadBasicArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/basic", "c64://context/bootstrap"],
+            relatedResources: ["c64://specs/basic", "c64://docs/basic/pitfalls", "c64://context/bootstrap"],
             relatedPrompts: ["basic-program"],
             tags: ["basic", "execution"],
             prerequisites: ["read_screen"],
@@ -105,17 +262,143 @@ export const programRunnersModule = defineToolModule({
                 try {
                     const parsed = uploadBasicArgsSchema.parse(args);
                     ctx.logger.info("Uploading BASIC program", { sourceLength: parsed.program.length });
-                    const result = await ctx.client.uploadAndRunBasic(parsed.program);
+                    const originalProgram = parsed.program;
+                    // Compute PRG locally to expose structured metadata
+                    let activeProgram = originalProgram;
+                    let prg = basicToPrg(activeProgram);
+                    let entryAddress = prg.readUInt16LE(0);
+                    const runBasic = async (source) => ctx.client.uploadAndRunBasic(source);
+                    let result = await runBasic(activeProgram);
                     if (!result.success) {
                         throw new ToolExecutionError("C64 firmware reported failure while running BASIC program", {
                             details: extractFailureDetails(result.details),
                         });
                     }
-                    const base = textResult("BASIC program uploaded and executed successfully.", {
+                    let screenOutput;
+                    try {
+                        screenOutput = await ctx.client.readScreen();
+                    }
+                    catch (screenError) {
+                        ctx.logger.warn("Unable to read screen after BASIC execution", toRecord(screenError));
+                    }
+                    let autoFixInfo;
+                    if (screenOutput) {
+                        const errors = parseBasicRuntimeErrors(screenOutput);
+                        if (errors.length > 0) {
+                            ctx.logger.warn("Detected BASIC runtime errors", {
+                                errors: errors.map((error) => ({ line: error.line, type: error.type })),
+                            });
+                            const normalizedErrors = normalizeRuntimeErrors(errors);
+                            const fixAttempt = attemptAutoFixBasicProgram(activeProgram, errors);
+                            if (!fixAttempt) {
+                                const data = {
+                                    kind: "basic_runtime_error",
+                                    programSource: originalProgram,
+                                    errors: normalizedErrors,
+                                    ...(screenOutput ? { screen: screenOutput } : {}),
+                                    autoFix: {
+                                        attempted: false,
+                                    },
+                                };
+                                return structuredExecutionError("Detected BASIC runtime errors after execution.", data);
+                            }
+                            ctx.logger.info("Attempting BASIC auto-fix", {
+                                changes: fixAttempt.changes.map((change) => ({
+                                    line: change.line,
+                                    notes: change.notes,
+                                })),
+                            });
+                            const retryResult = await ctx.client.uploadAndRunBasic(fixAttempt.program);
+                            if (!retryResult.success) {
+                                const data = {
+                                    kind: "basic_runtime_error",
+                                    programSource: originalProgram,
+                                    errors: normalizedErrors,
+                                    ...(screenOutput ? { screen: screenOutput } : {}),
+                                    autoFix: {
+                                        attempted: true,
+                                        changes: fixAttempt.changes,
+                                        programSource: fixAttempt.program,
+                                        failure: {
+                                            reason: "firmware_failure",
+                                            details: extractFailureDetails(retryResult.details),
+                                        },
+                                    },
+                                };
+                                return structuredExecutionError("Auto-fix failed due to firmware error while re-running BASIC program.", data);
+                            }
+                            let retryScreen;
+                            try {
+                                retryScreen = await ctx.client.readScreen();
+                            }
+                            catch (retryScreenError) {
+                                ctx.logger.warn("Unable to read screen after BASIC auto-fix execution", toRecord(retryScreenError));
+                            }
+                            const remainingErrors = retryScreen ? parseBasicRuntimeErrors(retryScreen) : [];
+                            if (remainingErrors.length > 0) {
+                                const data = {
+                                    kind: "basic_runtime_error",
+                                    programSource: originalProgram,
+                                    errors: normalizedErrors,
+                                    ...(screenOutput ? { screen: screenOutput } : {}),
+                                    autoFix: {
+                                        attempted: true,
+                                        changes: fixAttempt.changes,
+                                        programSource: fixAttempt.program,
+                                        resultingErrors: normalizeRuntimeErrors(remainingErrors),
+                                        ...(retryScreen ? { screen: retryScreen } : {}),
+                                    },
+                                };
+                                return structuredExecutionError("BASIC program still reports errors after auto-fix attempt.", data);
+                            }
+                            activeProgram = fixAttempt.program;
+                            prg = basicToPrg(activeProgram);
+                            entryAddress = prg.readUInt16LE(0);
+                            result = retryResult;
+                            screenOutput = retryScreen;
+                            autoFixInfo = {
+                                changes: fixAttempt.changes,
+                                originalErrors: errors,
+                            };
+                        }
+                    }
+                    const message = autoFixInfo
+                        ? "Detected BASIC errors on execution; applied auto-fix and re-ran successfully."
+                        : "BASIC program uploaded and executed successfully.";
+                    const metadata = {
                         success: true,
+                        entryAddress,
+                        prgSize: prg.length,
                         details: result.details ?? null,
-                    });
-                    return base;
+                        ...(screenOutput ? { screen: screenOutput } : {}),
+                        ...(autoFixInfo
+                            ? {
+                                autoFix: {
+                                    applied: true,
+                                    changes: autoFixInfo.changes,
+                                    originalErrors: autoFixInfo.originalErrors,
+                                },
+                            }
+                            : {}),
+                    };
+                    const data = {
+                        kind: "upload_and_run_basic",
+                        format: "prg",
+                        entryAddress,
+                        prgSize: prg.length,
+                        resources: ["c64://specs/basic", "c64://context/bootstrap"],
+                        ...(screenOutput ? { screen: screenOutput } : {}),
+                        ...(autoFixInfo
+                            ? {
+                                autoFix: {
+                                    changes: autoFixInfo.changes,
+                                    originalErrors: autoFixInfo.originalErrors,
+                                },
+                            }
+                            : {}),
+                    };
+                    const base = textResult(message, metadata);
+                    return { ...base, structuredContent: { type: "json", data } };
                 }
                 catch (error) {
                     if (error instanceof ToolError) {
@@ -150,16 +433,47 @@ export const programRunnersModule = defineToolModule({
                 try {
                     const parsed = uploadAsmArgsSchema.parse(args);
                     ctx.logger.info("Uploading assembly program", { sourceLength: parsed.program.length });
+                    // Assemble locally to expose structured metadata
+                    const prg = assemblyToPrg(parsed.program);
+                    const entryAddress = prg.readUInt16LE(0);
                     const result = await ctx.client.uploadAndRunAsm(parsed.program);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while running assembly program", {
+                        return toolErrorResult(new ToolExecutionError("C64 firmware reported failure while running assembly program", {
                             details: extractFailureDetails(result.details),
-                        });
+                        }));
+                    }
+                    // Poll for ASM execution outcome
+                    let pollResult;
+                    try {
+                        const outcome = await pollForProgramOutcome("ASM", ctx.client, ctx.logger);
+                        if (outcome.status === "crashed") {
+                            pollResult = {
+                                status: "crashed",
+                                reason: outcome.reason,
+                            };
+                            ctx.logger.warn("Polling detected ASM program crash", pollResult);
+                            return toolErrorResult(new ToolExecutionError("Assembly program appears to have crashed (no screen changes detected)", {
+                                details: { reason: outcome.reason },
+                            }));
+                        }
+                    }
+                    catch (pollError) {
+                        ctx.logger.debug("Polling encountered an error", toRecord(pollError));
                     }
-                    return textResult("Assembly program assembled, uploaded, and executed successfully.", {
+                    const data = {
+                        kind: "upload_and_run_asm",
+                        format: "prg",
+                        entryAddress,
+                        prgSize: prg.length,
+                        resources: ["c64://specs/assembly", "c64://context/bootstrap"],
+                    };
+                    const base = textResult("Assembly program assembled, uploaded, and executed successfully.", {
                         success: true,
+                        entryAddress,
+                        prgSize: prg.length,
                         details: result.details ?? null,
                     });
+                    return { ...base, structuredContent: { type: "json", data } };
                 }
                 catch (error) {
                     if (error instanceof ToolError) {
@@ -210,11 +524,20 @@ export const programRunnersModule = defineToolModule({
                             details: extractFailureDetails(result.details),
                         });
                     }
-                    return textResult(`PRG ${parsed.path} loaded into memory.`, {
+                    const data = {
+                        kind: "load_prg_file",
+                        format: "prg",
+                        path: parsed.path,
+                        entryAddress: null,
+                        resources: ["c64://context/bootstrap"],
+                    };
+                    const base = textResult(`PRG ${parsed.path} loaded into memory.`, {
                         success: true,
                         path: parsed.path,
+                        entryAddress: null,
                         details: toRecord(result.details) ?? null,
                     });
+                    return { ...base, structuredContent: { type: "json", data } };
                 }
                 catch (error) {
                     if (error instanceof ToolError) {
@@ -254,11 +577,20 @@ export const programRunnersModule = defineToolModule({
                             details: extractFailureDetails(result.details),
                         });
                     }
-                    return textResult(`PRG ${parsed.path} loaded and executed.`, {
+                    const data = {
+                        kind: "run_prg_file",
+                        format: "prg",
+                        path: parsed.path,
+                        entryAddress: null,
+                        resources: ["c64://context/bootstrap"],
+                    };
+                    const base = textResult(`PRG ${parsed.path} loaded and executed.`, {
                         success: true,
                         path: parsed.path,
+                        entryAddress: null,
                         details: toRecord(result.details) ?? null,
                     });
+                    return { ...base, structuredContent: { type: "json", data } };
                 }
                 catch (error) {
                     if (error instanceof ToolError) {
@@ -297,11 +629,19 @@ export const programRunnersModule = defineToolModule({
                             details: extractFailureDetails(result.details),
                         });
                     }
-                    return textResult(`CRT ${parsed.path} mounted and started.`, {
+                    const data = {
+                        kind: "run_crt_file",
+                        format: "crt",
+                        path: parsed.path,
+                        entryAddress: null,
+                        resources: ["c64://context/bootstrap"],
+                    };
+                    const base = textResult(`CRT ${parsed.path} mounted and started.`, {
                         success: true,
                         path: parsed.path,
                         details: toRecord(result.details) ?? null,
                     });
+                    return { ...base, structuredContent: { type: "json", data } };
                 }
                 catch (error) {
                     if (error instanceof ToolError) {

package/dist/tools/rag.js

@@ -165,14 +165,8 @@ function serializeReference(ref) {
         payload.sourceUrl = ref.sourceUrl;
     if (ref.sourceRepoUrl)
         payload.sourceRepoUrl = ref.sourceRepoUrl;
-    if (ref.license)
-        payload.license = ref.license;
     if (ref.licenseSpdxId)
-        payload.licenseSpdxId = ref.licenseSpdxId;
-    if (ref.licenseName)
-        payload.licenseName = ref.licenseName;
-    if (ref.licenseUrl)
-        payload.licenseUrl = ref.licenseUrl;
+        payload.spdxId = ref.licenseSpdxId;
     if (ref.attribution)
         payload.attribution = ref.attribution;
     return payload;

package/doc/MCP_SETUP.md

@@ -129,7 +129,13 @@ To exercise a real device, ensure your config points at the desired host/port an
 npm test -- --real
 ```
 
-`npm run coverage` captures c8 coverage for CI parity.
+To run tests with coverage analysis:
+
+```bash
+npm run coverage
+```
+
+Note: The coverage command uses Bun internally for faster execution, but the published package remains fully compatible with Node.js.
 
 ## 6. Common Tasks
 

package/doc/bun/baseline-metrics.md

@@ -0,0 +1,16 @@
+# Bun Migration Baseline (Node.js)
+
+Captured before introducing Bun tooling. All commands executed on the `bun-migration` branch using Node.js 18 (system default).
+
+| Command | Notes | Duration |
+|---------|-------|----------|
+| `npm run build` | TypeScript compile + postbuild + README update | **10.44 s** |
+| `npm test` | Full TAP suite via `scripts/run-tests.mjs` | **47.61 s** |
+
+Additional context:
+
+- Dependencies installed with `npm install` (fresh, no cache) before measuring.
+- No Bun tooling in use; these timings represent our current Node-only baseline.
+- Results recorded on 2025-10-29 to anchor future comparisons.
+
+Next step: use these numbers to evaluate improvements once Bun drives install/build/test tasks.

package/doc/bun/migration-checklist.md

@@ -0,0 +1,55 @@
+# Bun Migration Checklist
+
+> Track the incremental migration from Node.js/npm tooling to Bun.  
+> Update each item as it is completed and keep a short note/date beside the checkbox.
+> Before doing any work, ensure you understand the [Bun Migration Strategy](./migration.md).
+> Keep notes of any deviations or important observations in the checklist itself.
+
+## 1. Foundations
+
+- [x] **1.1** Capture baseline metrics (install/build/test timings, coverage reports) for comparison. *(doc/bun/baseline-metrics.md, 2025-10-29)*
+- [x] **1.2** Introduce Bun toolchain alongside existing Node workflow (lockfile, `packageManager`, basic `bun install` smoke test).
+
+## 2. Package & Tooling
+
+- [x] **2.1** Update `package.json` scripts to use Bun equivalents while keeping Node fallbacks where required. *(added Bun packageManager + `check:node-compat`)*
+- [x] **2.2** Ensure `bun run build` reproduces the existing `dist/` layout (compare key artifacts). *(verified 2025-10-29)*
+- [x] **2.3** Add an automated check that validates the published package still runs under `npm install` + `node`. *(npm script + compatibility harness)*
+
+## 3. Test Suite
+
+- [x] **3.1** Migrate test runner to `bun test`, converting assertion helpers and harness utilities. *(bun harness + timeout guardrails, 2025-10-29)*
+- [x] **3.2** Ensure `bun test` runs the full suite with the same semantics (mock servers, fixtures, CLI tools). *(`bun scripts/run-tests.ts --mock`, 2025-10-29)*
+- [x] **3.3** Provide an explicit npm/node compatibility test (e.g., `npm test` wrapper or integration smoke test). *(`npm run test:node`, 2025-10-29)*
+
+## 4. Coverage & Reporting
+
+- [x] **4.1** Replace `c8` with Bun’s coverage tooling and export lcov output. *(bun coverage emits `coverage/lcov.info`, 2025-10-29)*
+- [x] **4.2** Verify Codecov integration with the new coverage artifacts. *(workflow uploads Bun lcov, 2025-10-29)*
+
+## 5. Scripts & Utilities
+
+- [x] **5.1** Port repository scripts (`scripts/*.mjs`) from Node-specific loaders/`ts-node` to Bun-native execution. *(start, rag, CLI now Bun-aware; Node fallbacks use dist, 2025-10-29)*
+- [x] **5.2** Replace `register-ts-node` usage with Bun-compatible module loading. *(ts-node loader inlined; helper removed, 2025-10-29)*
+- [x] **5.3** Update shell helpers (e.g., `run-mcp-check.sh`, `c64-tool.sh`) to call Bun commands by default. *(preferred Bun paths with Node fallback, 2025-10-29)*
+
+## 6. Automation & CI
+
+- [x] **6.1** Update GitHub Actions to install Bun (`oven-sh/setup-bun`) and run build/test/coverage using Bun. *(added setup-bun, switched to `bun run build`, ensured LCOV output for Codecov, 2025-10-30)*
+- [x] **6.2** Ensure Docker-based checks (if any) consume the new Bun workflow without regressions. *(builder image now includes Bun; CI jobs use container and run Bun successfully, 2025-10-30)*
+
+## 7. Docker & Runtime
+
+- [x] **7.1** Rebuild the Dockerfile using an official Bun base image; retain runtime parity and entrypoints. *(deviation: kept `ubuntu:24.04` base but installed Bun system-wide; image provides both Node and Bun for CI parity, 2025-10-30)*
+- [x] **7.2** Confirm resulting image passes existing smoke tests and compatibility checks. *(Docker workflow builds `mcp-builder` and downstream package smoke tests pass, 2025-10-30)*
+
+## 8. Documentation
+
+- [x] **8.1** Refresh README, developer docs, and setup guides to reference Bun (with a note about Node compatibility). *(README Build & Test updated to include Bun; dev docs already referenced Bun, 2025-10-30)*
+- [x] **8.2** Document the npm/node compatibility verification process for external consumers. *(`npm run check:node-compat` documented in dev docs; retained, 2025-10-30)*
+
+## 9. Final Verification
+
+- [x] **9.1** Run full validation suite: `bun install`, `bun run build`, `bun test --coverage`, npm compatibility smoke test. *(wired in CI; local scripts use Bun runner; coverage emits LCOV, 2025-10-30)*
+- [x] **9.2** Compare final artifacts and confirm no API/package layout changes. *(build parity verified earlier; CI keeps packaging check, 2025-10-30)*
+- [x] **9.3** Remove obsolete Node-only tooling and close out migration notes. *(no remaining Node-only paths required for CI; kept Node paths for consumer compatibility, 2025-10-30)*

package/doc/bun/migration.md

@@ -0,0 +1,83 @@
+# Bun Migration Strategy
+
+Our goal is to adopt Bun everywhere it improves speed (local dev, CI, container builds) **without sacrificing Node compatibility** for downstream consumers.
+
+---
+
+## Approach Overview
+
+1. **Track incremental work via the checklist** (`doc/bun/migration-checklist.md`).
+2. **Introduce Bun tooling in parallel** with Node/npm. Validate parity before turning off Node paths.
+3. **Port the build/test pipeline** to Bun (`bun install`, `bun run build`, `bun test --coverage`) and keep comparing against Node outputs (especially `dist/` packaging).
+4. **Update automation and docs** once Bun passes all checks.
+5. **Retain Node smoke tests** to ensure published artifacts remain consumable by Node users.
+
+### Current Status (2025-10-29)
+
+- Baseline Node metrics captured (`npm run build` ~10.44 s, `npm test` ~47.61 s) in `doc/bun/baseline-metrics.md`.
+- Bun toolchain bootstrapped alongside Node (`bun.lock`, `packageManager`, smoke `bun install`).
+- Added `npm run check:node-compat` (packs the module, installs via npm, and imports key ESM modules with Node) to guard compatibility as we iterate.
+- `bun run build` verified to produce the same `dist/` output as the Node workflow.
+
+---
+
+## Guardrails
+
+### 1. Build & Runtime Rules
+
+- Sources remain TypeScript, emitting standard ESM/CJS modules compatible with Node.
+- Published code may not depend on Bun-only APIs (no `Bun.file`, `Bun.serve`, etc.).
+- The compiled `dist/` must execute under both **Bun ≥1.1** and **Node ≥18**.
+- `package.json` stays valid for npm clients (no Bun-only metadata).
+
+### 2. CI Strategy (Asymmetric Validation)
+
+- **Primary path (PRs, default CI):**
+
+  ```bash
+  bun install
+  bun run build
+  bun test --coverage
+  ```
+
+- **Release/nightly Node validation (reuse `dist/`):**
+
+  ```bash
+  npm ci --omit=dev
+  node dist/index.js --version
+  npm test -- --smoke
+  ```
+
+### 3. Docker Strategy
+
+Build with Bun, run with Node:
+
+```dockerfile
+FROM oven/bun:latest AS build
+WORKDIR /app
+COPY . .
+RUN bun install && bun run build
+
+FROM node:20-slim
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY package.json .
+CMD ["node", "dist/index.js"]
+```
+
+### 4. Validation Matrix
+
+- **Bun:** install/build/test/coverage on every PR.
+- **Node:** smoke tests on main branch, releases, or nightly jobs.
+- **Rule:** only build once; reuse Bun artifacts for Node checks.
+
+### 5. Documentation Messaging
+>
+> Built and tested with **Bun** ⚡  
+> Fully compatible with **Node.js 18+** 🟩
+
+---
+
+## Next Steps
+
+Use this document together with the checklist to plan each migration phase. Update both as milestones are completed and ensure the guardrails stay enforced.