vgxness 1.0.5 → 1.1.1

package/README.md

@@ -10,9 +10,114 @@ OpenCode is the primary supported provider. Other providers remain preview/manua
 
 ## Requirements
 
-- Node.js >= 22
-- npm
-- A platform supported by `better-sqlite3` for your Node/runtime combination
+- Bun >= 1.3.14 for the installed `vgxness`/`vgx` CLI/MCP runtime and repository verification
+- Node.js >= 22 for repository development, build, test, and helper-script tooling
+- A platform supported by Bun SQLite (`bun:sqlite`) for runtime storage
+
+Bun is the canonical installed runtime and verification tool. Node remains development/build/test tooling for TypeScript, `node:test`, and selected helper scripts; package consumer metadata (`bin` and `files`) remains part of the npm install contract.
+
+### Bun-first staged toolchain
+
+Use Bun for development verification and CI parity:
+
+```bash
+bun install --frozen-lockfile
+bun run check:bun-lock
+bun run verify:typecheck
+bun run verify:test
+bun run verify:bun-sqlite
+bun run verify:package
+bun run package:bun:evidence -- --require-pass
+```
+
+```bash
+bun run verify
+```
+
+Package evidence is Bun-only after the npm publication bridge retirement:
+
+| Area | Current owner | Why |
+|---|---|---|
+| Typecheck, tests, Bun SQLite probe, package evidence | Bun | This is the canonical CI verification path. |
+| Package artifact and isolated install smoke | `bun run package:bun:evidence -- --require-pass` | It creates/inspects the artifact, validates package contents, installs in an isolated Bun environment, checks both CLI bins, and records Bun runtime identity. |
+| Installed CLI runtime | Bun >=1.3.14 | Published `vgxness`/`vgx` execute `dist/cli/bun-bin.js`, which records optional runtime evidence and then imports the CLI. |
+| Lockfile review | `bun.lock` | The npm bridge lockfile has been retired; do not treat that as dropping npm consumer installability. |
+
+Do not remove npm package metadata, `bin`, or `files` as part of bridge cleanup; those remain the package consumer contract. The product runtime engine is `engines.bun`, not `engines.node`.
+
+When `package.json` dependency specifiers change, refresh and review `bun.lock` intentionally. To check manifest/lock drift without mutating `node_modules`, run:
+
+```bash
+bun run check:bun-lock
+```
+
+The manual compatibility probe remains useful when diagnosing Bun/package-manager behavior:
+
+```bash
+npm run probe:bun
+npm run probe:bun -- --yes   # mutates dependencies only after explicit consent
+```
+
+Runtime SQLite readiness is proven only with `bun:sqlite`. `bun run verify:bun-sqlite` copies the source migrations into a temporary directory, applies them against a temporary database, checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup. Node.js remains development/build/test tooling, but real local SQLite storage is supported through the Bun runtime path.
+
+#### Bun package evidence
+
+To collect diagnostic package artifact and isolated install-smoke evidence without publishing, run:
+
+```bash
+bun run package:bun:evidence
+```
+
+Diagnostic mode may emit `status: incompatible` and still exit `0` so maintainers can inspect JSON. For release-readiness, require a passing result explicitly:
+
+```bash
+bun run package:bun:evidence -- --require-pass
+```
+
+The probe is the authoritative release evidence path for package contents. It does not invoke registry publication commands, writes optional JSON only where requested, records `publicationAttempted: false`, and reports `releaseReadiness` diagnostics when evaluating the gate.
+
+It protects:
+
+- package metadata, `files`, `bin`, license, Bun engine, README/LICENSE, docs, migrations, and shipped seed assets;
+- absence of workspace-only content such as `src/`, `test/`, `.opencode/`, `openspec/`, source maps, SQLite/database files, and OS junk;
+- both installed commands: `vgxness --help` and `vgx --help`.
+
+Release-candidate checklist, still non-publishing:
+
+1. `bun install --frozen-lockfile` completes on a clean checkout.
+2. `bun run check:bun-lock` passes.
+3. `bun run verify:typecheck`, `bun run verify:test`, and `bun run verify:bun-sqlite` pass.
+4. `bun run package:bun:evidence -- --require-pass` passes on supported CI OSes.
+5. JSON evidence shows `status: pass`, artifact/install smoke pass, no retired bridge scripts, no `package-lock.json`, `publicationAttempted: false`, and `releaseReadiness.status: pass`.
+6. Version, release notes, proprietary license boundary, and rollback criteria are reviewed.
+7. Publishing remains a separate explicit human-approved process.
+
+This checklist does **not** run `npm publish`, `bun publish`, registry dry-runs that contact a registry, registry token use, provenance upload, release creation, or dist-tag mutation.
+
+#### Temporary rollback if Bun package evidence misses a release regression
+
+Rollback is release-impacting and temporary. Use it only when Bun package evidence misses a package regression, downstream install verification fails in a way Bun did not catch, or a release candidate needs short-lived npm bridge validation while the Bun evidence gap is investigated.
+
+Restore these bridge elements from the previous known-good main commit:
+
+- `package-lock.json`
+- package scripts: `prepack`, `package:release-check`, `package:dry-run`, and `package:smoke:install`
+- deleted helper scripts: `scripts/validate-package-release.mjs` and `scripts/smoke-tarball-install.mjs`
+- npm validation wiring and tests that enforced the bridge
+- the `.github/workflows/node22.yml` `npm-publication-bridge` job and its artifact/install-smoke steps
+
+Do not publish during rollback verification unless a separate explicit approval covers publication. Follow up with an investigation or SDD change before retiring the bridge again.
+
+### Legacy Bun probe commands
+
+These commands are retained for compatibility investigation, not as a replacement for `bun run verify`:
+
+```bash
+npm run check:bun:typecheck
+bun run typecheck
+bun run build
+bun run package:bun:evidence
+```
 
 ## Install globally
 
@@ -101,25 +206,28 @@ Rollback validates the backup, creates a pre-rollback backup of the current targ
 
 Common issues:
 
-- Node < 22: upgrade Node and reinstall.
-- Native SQLite install failure: verify your platform has compatible `better-sqlite3` binaries/build tools.
+- Bun < 1.3.14: upgrade Bun and reinstall.
+- Node < 22 while developing from source: upgrade Node for repository tooling.
+- Bun SQLite failure: include the Bun version, OS/CPU, whether migrations applied, and the failing `verify:bun-sqlite` output.
 - JSONC or malformed OpenCode config: convert to valid JSON or resolve manually; VGXNESS refuses unsafe rewrites.
 - Existing `mcp.vgxness`: inspect the existing entry before rerunning setup; VGXNESS refuses overwrite by default.
 
 ## Release verification matrix
 
-CI and manual release checks target Node 22 on macOS, Linux, and Windows:
+CI verifies Bun on macOS, Linux, and Windows:
 
 ```bash
-npm ci
-npm run typecheck
-npm test
-npm run package:release-check
-npm run package:dry-run
-npm run package:smoke:install
+bun install --frozen-lockfile
+bun run check:bun-lock
+bun run verify:typecheck
+bun run verify:test
+bun run verify:bun-sqlite
+bun run package:bun:evidence -- --require-pass
 ```
 
-Do not publish from CI. Use `npm publish --dry-run --tag latest` as the final manual gate for the stable path before any explicit publish decision.
+Run `bun run check:bun-lock` when dependency specifiers or `bun.lock` changed. It is read-only and helps review lock drift without installing dependencies.
+
+Do not publish from CI. Publication or registry dry-run checks require separate explicit approval outside this verification path.
 
 ## Uninstall
 

package/dist/cli/bun-bin.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+import { writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+writeRuntimeEvidence();
+await import('./index.js');
+function writeRuntimeEvidence() {
+    const evidencePath = process.env.VGXNESS_RUNTIME_EVIDENCE_FILE;
+    if (evidencePath === undefined || evidencePath.length === 0)
+        return;
+    const bunVersion = globalThis.Bun?.version;
+    const argv0 = process.argv[0] ?? null;
+    const entrypoint = process.argv[1] ?? null;
+    const binName = entrypoint === null ? null : basename(entrypoint).replace(/\.cmd$/i, '');
+    const command = process.argv.slice(2);
+    const evidence = {
+        runtime: 'bun',
+        bunVersion: typeof bunVersion === 'string' && bunVersion.length > 0 ? bunVersion : null,
+        execPath: process.execPath,
+        argv0,
+        entrypoint,
+        binName,
+        argv: process.argv,
+        platform: {
+            os: process.platform,
+            arch: process.arch,
+        },
+        commandContext: {
+            command,
+            commandName: command[0] ?? null,
+            isHelp: command.includes('--help') || command.includes('-h'),
+            cwd: process.cwd(),
+        },
+    };
+    try {
+        writeFileSync(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // Runtime evidence is diagnostic only; do not block the CLI if the path is invalid.
+    }
+}

package/dist/cli/commands/setup-dispatcher.js

@@ -318,16 +318,24 @@ export function promptLineExport(environment, prompt) {
 export function renderSetupPlanForHumansExport(plan) {
     return renderSetupPlanForHumans(plan);
 }
-export async function runInitCommand(parsed, environment) {
+export function resolveInitDispatchMode(parsed, environment) {
     if (parsed.flags.plan === true || parsed.flags.json === true)
-        return runSetupPlanCommand(parsed, environment);
+        return 'setup-plan';
     if (parsed.flags.yes === true)
-        return runSetupApplyCommand({ ...parsed, flags: { ...parsed.flags, yes: true } }, environment);
-    const terminal = environment.stdin?.isTTY === true && environment.stdout?.isTTY === true;
-    if (!terminal)
+        return 'setup-apply';
+    return environment.stdin?.isTTY === true && environment.stdout?.isTTY === true ? 'setup-tui' : 'setup-plan';
+}
+export async function runInitCommand(parsed, environment) {
+    return runInitCommandWithSetupTui(parsed, environment, runSetupTuiCommand);
+}
+export async function runInitCommandWithSetupTui(parsed, environment, setupTui) {
+    const mode = resolveInitDispatchMode(parsed, environment);
+    if (mode === 'setup-plan')
         return runSetupPlanCommand(parsed, environment);
+    if (mode === 'setup-apply')
+        return runSetupApplyCommand({ ...parsed, flags: { ...parsed.flags, yes: true } }, environment);
     const project = optionalStringFlag(parsed.flags, 'project');
-    return runSetupTuiCommand(environment, project === undefined ? undefined : { project });
+    return setupTui(environment, project === undefined ? undefined : { project });
 }
 export async function runSetupTuiCommand(environment, input) {
     if (!canRunInteractiveTui(environment.stdin, environment.stdout))

package/dist/cli/dispatcher.js

@@ -1,6 +1,6 @@
 // Thin CLI router -- all command handlers live in src/cli/commands/*.ts
 import { isWorkflowId } from '../workflows/schema.js';
-import { databasePathFor, parseArgs } from './cli-flags.js';
+import { databasePathFor, parseArgs, requiredFlag } from './cli-flags.js';
 import { okText, usageFailure, visibleHelpText } from './cli-help.js';
 import { openCliDatabase, resultFailure } from './cli-helpers.js';
 import { runAgentCommand, runApprovalsCommand, runCodeCliCommand, runDashboardCommand, runDashboardInteractiveCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runInitCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupRollbackCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
@@ -25,6 +25,14 @@ export function dispatchCli(argv, environment) {
         return runVerificationPlanCommand(command, parsed);
     if (isWorkflowId(area) && command === 'preview')
         return runWorkflowPreviewCommand(area, parsed);
+    if (area === 'orchestrator' && command === 'preview') {
+        const project = requiredFlag(parsed.flags, 'project');
+        if (!project.ok)
+            return resultFailure(project);
+        const intent = requiredFlag(parsed.flags, 'intent');
+        if (!intent.ok)
+            return resultFailure(intent);
+    }
     if (area === 'memory' && command === 'import')
         return runMemoryImportCommand(parsed, environment);
     const selectedDatabasePath = databasePathFor(parsed.flags, environment);

package/dist/cli/sdd-renderer.js

@@ -2,15 +2,19 @@ import { normalizeSddArtifact, sddPhases } from '../sdd/schema.js';
 export function renderSddStatus(input) {
     const missing = input.status.phases.filter((phase) => !phase.present).map((phase) => phase.topicKey);
     const blockers = input.status.phases.filter((phase) => phase.present && phase.accepted !== true);
+    const complete = input.status.phases.length > 0 && input.status.phases.every((phase) => phase.present && phase.accepted === true);
+    const statusLabel = complete ? 'complete' : input.status.nextReadyPhase === undefined ? 'blocked' : 'ready';
     const directPhaseCommand = input.status.nextReadyPhase === undefined ? undefined : `vgx code sdd ${input.status.change} ${input.status.nextReadyPhase} --save-artifact`;
-    const recommendedAction = input.status.nextReadyPhase === undefined
-        ? 'Review blockers or accept present draft artifacts before continuing.'
-        : `Run or draft the ${input.status.nextReadyPhase} phase with ${directPhaseCommand}.`;
+    const recommendedAction = complete
+        ? 'No next SDD phase remains for this change.'
+        : input.status.nextReadyPhase === undefined
+            ? 'Review blockers or accept present draft artifacts before continuing.'
+            : `Run or draft the ${input.status.nextReadyPhase} phase with ${directPhaseCommand}.`;
     const lines = [
         'SDD Status',
         `Project: ${input.project}`,
         `Change: ${input.status.change}`,
-        `Status: ${input.status.nextReadyPhase === undefined ? 'blocked' : 'ready'}`,
+        `Status: ${statusLabel}`,
         `Next ready phase: ${input.status.nextReadyPhase ?? 'none'}`,
         '',
         'Phases:',

package/dist/code/runtime/project-detection.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 const ignoredDirectories = new Set(['.git', 'node_modules', 'dist', 'build', '.next', 'coverage']);
 export function detectProject(workspaceRoot, fileLimit = 250) {
     const root = resolve(workspaceRoot);
@@ -28,7 +28,14 @@ function findRepositoryRoot(start) {
 function listFiles(root, limit) {
     const files = [];
     const visit = (directory) => {
-        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
             if (files.length >= limit)
                 return;
             if (entry.isDirectory() && ignoredDirectories.has(entry.name))
@@ -37,7 +44,7 @@ function listFiles(root, limit) {
             if (entry.isDirectory())
                 visit(full);
             else
-                files.push(relative(root, full));
+                files.push(toPortablePath(relative(root, full)));
         }
     };
     visit(root);
@@ -46,6 +53,9 @@ function listFiles(root, limit) {
 function isConfigFile(file) {
     return /(^|\/)(package\.json|tsconfig[^/]*\.json|vite\.config\.|eslint\.config\.|\.eslintrc|vitest\.config\.|jest\.config\.|playwright\.config\.|pyproject\.toml|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|settings\.gradle|pubspec\.yaml|Package\.swift)$/.test(file);
 }
+function toPortablePath(path) {
+    return sep === '/' ? path : path.split(sep).join('/');
+}
 function stackHints(root, files) {
     const hints = new Set();
     if (files.includes('package.json'))

package/dist/code/tools/read-only-executor.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, join, relative, resolve } from 'node:path';
+import { basename, join, relative, resolve, sep } from 'node:path';
 import { normalizeToolError, normalizeToolSuccess } from './tool-result-normalizer.js';
 export class ReadOnlyToolExecutor {
     registry;
@@ -75,7 +75,8 @@ export class ReadOnlyToolExecutor {
 }
 function safePath(root, path) {
     const resolved = resolve(root, path);
-    if (resolved !== root && !resolved.startsWith(`${root}/`))
+    const fromRoot = relative(root, resolved);
+    if (fromRoot.startsWith('..') || fromRoot === '..' || resolve(fromRoot) === fromRoot)
         throw new Error('Path escapes workspace root');
     return resolved;
 }
@@ -89,7 +90,7 @@ function listFiles(root, limit) {
             if (entry.isDirectory())
                 visit(full);
             else
-                files.push(relative(root, full));
+                files.push(toPortablePath(relative(root, full)));
         }
     };
     visit(root);
@@ -124,6 +125,9 @@ function inspectProject(root) {
         configFiles: listFiles(root, 200).filter((file) => /(^|\/)(package|tsconfig|vite|eslint|vitest|jest|playwright)/.test(file)),
     };
 }
+function toPortablePath(path) {
+    return sep === '/' ? path : path.split(sep).join('/');
+}
 function git(root, args) {
     return execFileSync('git', args, {
         cwd: root,

package/dist/mcp/doctor.js

@@ -66,7 +66,7 @@ async function runRealMcpSmoke(options) {
     const client = new Client({ name: 'vgxness-doctor', version: '0.1.0' }, { capabilities: {} });
     const invocation = resolveDoctorCliInvocation(options.databasePath);
     const transport = new StdioClientTransport({
-        command: process.execPath,
+        command: invocation.command,
         args: invocation.args,
         cwd: options.cwd,
         stderr: 'pipe',
@@ -173,11 +173,17 @@ function parseMcpToolResult(result) {
         return { ok: false, error: { code: 'validation_failed', message: 'MCP response did not contain text JSON' } };
     return JSON.parse(text);
 }
-export function resolveDoctorCliInvocation(databasePath, moduleUrl = import.meta.url) {
+export function resolveDoctorCliInvocation(databasePath, moduleUrl = import.meta.url, options = {}) {
+    const runtime = options.runtime ?? currentRuntime();
     const builtCliPath = fileURLToPath(new URL('../cli/index.js', moduleUrl));
     if (existsSync(builtCliPath))
-        return { args: [builtCliPath, 'mcp', 'start', '--db', databasePath] };
-    return { args: ['--import', import.meta.resolve('tsx'), cliSourcePath(moduleUrl), 'mcp', 'start', '--db', databasePath] };
+        return { command: process.execPath, args: [builtCliPath, 'mcp', 'start', '--db', databasePath] };
+    if (runtime === 'bun')
+        return { command: process.execPath, args: [cliSourcePath(moduleUrl), 'mcp', 'start', '--db', databasePath] };
+    return { command: process.execPath, args: ['--import', import.meta.resolve('tsx'), cliSourcePath(moduleUrl), 'mcp', 'start', '--db', databasePath] };
+}
+function currentRuntime() {
+    return typeof globalThis.Bun === 'undefined' ? 'node' : 'bun';
 }
 function cliSourcePath(moduleUrl) {
     return fileURLToPath(new URL('../cli/index.ts', moduleUrl));

package/dist/memory/sqlite/database.js

@@ -1,18 +1,10 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import Database from 'better-sqlite3';
 const migrationsDirectory = join(dirname(fileURLToPath(import.meta.url)), 'migrations');
 export const sqliteBusyTimeoutMs = 5000;
-const nativeBindingDiagnosticGuidance = 'Detected a likely better-sqlite3 native binding problem. Ensure npm install scripts are enabled, then rebuild or reinstall dependencies for the active Node.js version (for example: npm rebuild better-sqlite3 --ignore-scripts=false).';
-const nativeBindingFailurePatterns = [
-    /better_sqlite3\.node/i,
-    /better-sqlite3/i,
-    /NODE_MODULE_VERSION/i,
-    /ERR_DLOPEN_FAILED/i,
-    /Could not locate the bindings file/i,
-    /compiled against a different Node\.js version/i,
-];
+const bunRequiredGuidance = 'Real local SQLite storage requires Bun. Use the installed Bun-backed vgxness/vgx runtime, or run Bun storage verification with bun run verify:bun-sqlite.';
 export class MemoryDatabase {
     connection;
     constructor(connection) {
@@ -20,7 +12,7 @@ export class MemoryDatabase {
     }
     static open(options) {
         try {
-            const connection = new Database(options.path, { readonly: options.readonly ?? false });
+            const connection = openSqliteConnection(options);
             connection.pragma('foreign_keys = ON');
             connection.pragma(`busy_timeout = ${sqliteBusyTimeoutMs}`);
             const memoryDatabase = new MemoryDatabase(connection);
@@ -100,13 +92,133 @@ export function openMemoryDatabase(options) {
 }
 export function buildMemoryStoreUnavailableMessage(path, cause) {
     const message = `Unable to open local memory store at ${path}`;
-    if (!isLikelyBetterSqlite3NativeBindingFailure(cause))
+    if (!isUnsupportedSqliteRuntimeError(cause))
         return message;
-    return `${message}. ${nativeBindingDiagnosticGuidance}`;
+    return `${message}. ${bunRequiredGuidance}`;
 }
-export function isLikelyBetterSqlite3NativeBindingFailure(cause) {
-    const values = collectDiagnosticValues(cause);
-    return values.some((value) => nativeBindingFailurePatterns.some((pattern) => pattern.test(value)));
+function openSqliteConnection(options) {
+    return resolveSqliteDriver()(options);
+}
+function resolveSqliteDriver() {
+    if (isBunRuntime())
+        return resolveBunSqliteDriver();
+    throw createUnsupportedSqliteRuntimeError();
+}
+function isBunRuntime() {
+    return typeof globalThis.Bun !== 'undefined';
+}
+function resolveBunSqliteDriver() {
+    const require = createRequire(import.meta.url);
+    const module = require('bun:sqlite');
+    const BunDatabase = module.Database;
+    if (typeof BunDatabase !== 'function')
+        throw new Error('bun:sqlite Database constructor is unavailable');
+    return (options) => createBunSqliteConnection(new BunDatabase(options.path, { readonly: options.readonly ?? false, strict: true }));
+}
+function createUnsupportedSqliteRuntimeError() {
+    const error = new Error(bunRequiredGuidance);
+    error.name = 'UnsupportedSqliteRuntimeError';
+    return error;
+}
+function isUnsupportedSqliteRuntimeError(cause) {
+    return cause instanceof Error && cause.name === 'UnsupportedSqliteRuntimeError';
+}
+function createBunSqliteConnection(database) {
+    const record = database;
+    return {
+        prepare(sql) {
+            const prepare = record.prepare;
+            if (typeof prepare !== 'function')
+                throw new Error('bun:sqlite prepare() is unavailable');
+            return createBunSqliteStatement(prepare.call(database, sql));
+        },
+        exec(sql) {
+            const exec = record.exec;
+            if (typeof exec === 'function')
+                return exec.call(database, sql);
+            const run = record.run;
+            if (typeof run === 'function')
+                return run.call(database, sql);
+            throw new Error('bun:sqlite exec() is unavailable');
+        },
+        pragma(statement) {
+            return runBunPragma(database, statement);
+        },
+        transaction(operation) {
+            const transaction = record.transaction;
+            if (typeof transaction !== 'function')
+                throw new Error('bun:sqlite transaction() is unavailable');
+            const run = transaction.call(database, operation);
+            if (typeof run !== 'function')
+                throw new Error('bun:sqlite transaction() did not return a callable transaction');
+            const transactionRunner = run;
+            if (typeof transactionRunner.immediate !== 'function') {
+                throw new Error('bun:sqlite transaction().immediate() is unavailable');
+            }
+            return transactionRunner;
+        },
+        close() {
+            const close = record.close;
+            if (typeof close !== 'function')
+                return;
+            close.call(database, false);
+        },
+    };
+}
+function createBunSqliteStatement(statement) {
+    const record = statement;
+    return {
+        get(...params) {
+            const get = record.get;
+            if (typeof get !== 'function')
+                throw new Error('bun:sqlite statement.get() is unavailable');
+            const row = get.call(statement, ...params);
+            return row === null ? undefined : row;
+        },
+        all(...params) {
+            const all = record.all;
+            if (typeof all !== 'function')
+                throw new Error('bun:sqlite statement.all() is unavailable');
+            return all.call(statement, ...params);
+        },
+        run(...params) {
+            const run = record.run;
+            if (typeof run !== 'function')
+                throw new Error('bun:sqlite statement.run() is unavailable');
+            return run.call(statement, ...params);
+        },
+    };
+}
+function runBunPragma(database, statement) {
+    const normalizedStatement = statement.trim();
+    if (isPragmaSetter(normalizedStatement)) {
+        const exec = database.exec;
+        if (typeof exec !== 'function')
+            throw new Error('bun:sqlite exec() is unavailable for PRAGMA setter');
+        return exec.call(database, `PRAGMA ${normalizedStatement}`);
+    }
+    const prepare = database.prepare;
+    if (typeof prepare !== 'function')
+        throw new Error('bun:sqlite prepare() is unavailable for PRAGMA reader');
+    const rows = prepare.call(database, `PRAGMA ${normalizedStatement}`).all();
+    if (/^busy_timeout\b/i.test(normalizedStatement))
+        return normalizeBusyTimeoutRows(rows);
+    return rows;
+}
+function isPragmaSetter(statement) {
+    return /=/.test(statement);
+}
+function normalizeBusyTimeoutRows(rows) {
+    return rows.map((row) => {
+        if (row === null || typeof row !== 'object')
+            return row;
+        const record = row;
+        if (typeof record.timeout === 'number')
+            return row;
+        if (typeof record.busy_timeout === 'number')
+            return { timeout: record.busy_timeout };
+        return row;
+    });
 }
 function migrationFailure(message, cause) {
     const error = { code: 'migration_failed', message };
@@ -114,26 +226,3 @@ function migrationFailure(message, cause) {
         error.cause = cause;
     return { ok: false, error };
 }
-function collectDiagnosticValues(value, seen = new Set()) {
-    if (value === undefined || value === null)
-        return [];
-    if (typeof value === 'string')
-        return [value];
-    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol')
-        return [String(value)];
-    if (typeof value !== 'object')
-        return [];
-    if (seen.has(value))
-        return [];
-    seen.add(value);
-    const diagnosticValues = [];
-    const record = value;
-    for (const key of ['code', 'message', 'stack', 'name']) {
-        const property = record[key];
-        if (property !== undefined)
-            diagnosticValues.push(...collectDiagnosticValues(property, seen));
-    }
-    if (record.cause !== undefined)
-        diagnosticValues.push(...collectDiagnosticValues(record.cause, seen));
-    return diagnosticValues;
-}

package/dist/verification/verification-plan-service.js

@@ -40,8 +40,8 @@ const templates = {
         manualChecks: [manualCheck('review-provider-config-writes', 'Review provider config write gating', 'Confirm provider config writes still require explicit consent and backup/rollback where applicable.')],
     },
     'package-release': {
-        rationale: ['Package release changes need packaging checks, but package scripts are not allowlisted in the workflow executor.', 'Recommendations are deliberately copy-only except for harmless allowlisted environment/type checks.'],
-        recommendations: [nodeVersionRecommendation(), typecheckRecommendation(), manualRecommendation('manual-release-check', 'Run release package validation manually', 'Package script npm run package:release-check is copy-only in this slice.', 'npm run package:release-check'), manualRecommendation('manual-package-dry-run', 'Run package dry-run manually', 'Package script npm run package:dry-run is copy-only in this slice.', 'npm run package:dry-run'), manualRecommendation('manual-smoke-install', 'Run package smoke install manually', 'Package script npm run package:smoke:install is copy-only in this slice.', 'npm run package:smoke:install')],
+        rationale: ['Package release changes need packaging checks, but package scripts are not allowlisted in the workflow executor.', 'Bun package evidence is the authoritative artifact and isolated install-smoke path; recommendations stay copy-only except for harmless allowlisted environment/type checks.'],
+        recommendations: [nodeVersionRecommendation(), typecheckRecommendation(), manualRecommendation('manual-bun-package-evidence', 'Run authoritative Bun package evidence manually', 'Bun package evidence validates package metadata, artifact contents, isolated install smoke, and no-publication safety as copy-only guidance.', 'bun run package:bun:evidence')],
         manualChecks: [manualCheck('review-package-files', 'Review package contents', 'Confirm package whitelist changes are intentional and runtime files are included.')],
     },
     'workflow-runs': {

package/docs/cli.md

@@ -1,36 +1,29 @@
 # Use the local CLI
 
-Run `vgxness` commands from the repo with `npm run cli -- ...`. The CLI is intentionally thin: it parses flags, opens the local SQLite store, and calls the existing domain services for memory, agents, runs, and permissions.
+Run `vgxness` commands from the repo with `bun run cli -- ...`. The CLI is intentionally thin: it parses flags, opens the local SQLite store, and calls the existing domain services for memory, agents, runs, and permissions. `npm run cli -- ...` remains available for Node development tooling compatibility when dependencies are already installed, but installed `vgxness`/`vgx` bins require Bun.
 
 ## Local tarball install and dogfood
 
-Use this workflow to dogfood the installable package without publishing to npm. It builds the package, installs the tarball into an isolated temporary prefix, and uses an explicit temporary database so your default global memory store is untouched.
+Use the Bun package evidence workflow to dogfood the installable package without publishing. It builds package artifacts, validates package contents, installs into an isolated Bun environment, and checks both CLI bins.
 
 ```bash
-npm run build
-VGXNESS_TARBALL=$(npm pack --json | node -e 'const fs = require("node:fs"); const [pkg] = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(pkg.filename);')
+bun run package:bun:evidence
+```
 
-VGXNESS_SMOKE_PREFIX=$(mktemp -d)
-VGXNESS_SMOKE_WORKDIR=$(mktemp -d)
-VGXNESS_SMOKE_DB="$VGXNESS_SMOKE_WORKDIR/smoke.sqlite"
+That command is diagnostic. For release-readiness, require a passing result explicitly:
 
-npm install --prefix "$VGXNESS_SMOKE_PREFIX" --global --no-audit --no-fund "./$VGXNESS_TARBALL"
-export PATH="$VGXNESS_SMOKE_PREFIX/bin:$PATH"
+```bash
+bun run package:bun:evidence -- --require-pass
 ```
 
-Run the smoke checks from the temporary workdir:
+The evidence includes these smoke checks from the isolated install location:
 
 ```bash
-cd "$VGXNESS_SMOKE_WORKDIR"
 vgxness --help
 vgx --help
-vgx setup plan
-vgx setup status --db "$VGXNESS_SMOKE_DB"
-vgxness dashboard status --project vgxness --db "$VGXNESS_SMOKE_DB"
-vgxness mcp install opencode --plan --db "$VGXNESS_SMOKE_DB"
 ```
 
-`vgx setup plan` and `vgx setup status` are human-readable and read-only by default; pass `--json` when you need parseable automation output. The MCP plan is read-only. With the explicit smoke DB above, it should show an installed server command that starts with `vgxness mcp start --db "$VGXNESS_SMOKE_DB"` and must not mention `npm run cli`, `tsx`, or repository-relative source paths. If `--db` is omitted, the installed command should be `vgxness mcp start` and use the global default at runtime.
+`vgx setup plan` and `vgx setup status` are human-readable and read-only by default; pass `--json` when you need parseable automation output. The MCP plan is read-only. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
 
 Only apply the OpenCode user/global config after reviewing the plan (use `--scope project` only when you intentionally want project config):
 
@@ -38,15 +31,7 @@ Only apply the OpenCode user/global config after reviewing the plan (use `--scop
 vgxness mcp install opencode --yes --db "$VGXNESS_SMOKE_DB"
 ```
 
-Rollback cleanup:
-
-```bash
-rm -rf "$VGXNESS_SMOKE_PREFIX"
-rm -rf "$VGXNESS_SMOKE_WORKDIR"
-rm -f "./$VGXNESS_TARBALL"
-```
-
-For the automated version of this workflow, run `npm run package:smoke:install`.
+For deeper manual troubleshooting, create temporary directories outside the checkout and do not treat npm tarball/install smoke commands as current release evidence.
 
 ## Stable npm/global setup
 
@@ -54,7 +39,9 @@ The npm package name is `vgxness`, the stable release path uses the default/late
 
 Release defaults used by the guided setup are:
 
-- Node.js `>=22`.
+- Bun `>=1.3.14` as the installed CLI/MCP runtime and repository verification path.
+- Node.js `>=22` for repository development/build/test tooling only.
+- Bun package evidence as the release artifact and isolated install-smoke path.
 - Provider: OpenCode.
 - Database: global user data location by default.
 - OpenCode scope: user/global config by default (`$HOME/.config/opencode/opencode.json`).
@@ -79,6 +66,125 @@ vgx setup rollback --backup <path>
 
 `vgx init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgx doctor`, `vgx sdd status`, `vgx sdd next`, `vgx sdd get-artifact`, and `vgx sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
 
+## Bun-first repository verification
+
+VGXNESS uses Bun as the canonical installed runtime and verification path for repository development and CI. Node.js `>=22` remains development/build/test tooling for TypeScript, `node:test`, and helper scripts. npm package consumer metadata remains supported, but the product runtime engine is `engines.bun`.
+
+Happy path for local verification:
+
+```bash
+bun install --frozen-lockfile
+bun run check:bun-lock
+bun run verify:typecheck
+bun run verify:test
+bun run verify:test:bun-storage
+bun run verify:bun-sqlite
+bun run verify:package
+bun run package:bun:evidence -- --require-pass
+```
+
+`bun run verify:bun-sqlite` is the SQLite runtime release gate. It uses `bun:sqlite` against a temporary database, copies/applies the source migrations, and checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup. `bun run verify:test:bun-storage` covers storage-backed tests under Bun. Node.js remains development/build/test tooling, but real local SQLite storage is supported through the Bun runtime path.
+
+Keep lockfile changes intentional: when `package.json` dependency specifiers change, refresh and review the root `bun.lock` diff. The read-only drift check does not run `bun install` and does not mutate `node_modules`:
+
+```bash
+bun run check:bun-lock
+```
+
+### Bun package evidence
+
+The authoritative package evidence path is:
+
+```bash
+bun run package:bun:evidence
+```
+
+This default mode is diagnostic: it may emit `status: incompatible` and exit `0` so maintainers can collect and review JSON evidence. The release-readiness gate is:
+
+```bash
+bun run package:bun:evidence -- --require-pass
+```
+
+It validates package metadata, artifact contents, forbidden workspace-only files, isolated Bun global install behavior, both `vgxness --help` and `vgx --help`, Bun runtime identity evidence for the installed wrapper, retired bridge invariants, no `package-lock.json`, and `publicationAttempted: false`. It must not invoke registry publication commands.
+
+Release-candidate checklist, without publishing:
+
+1. `bun install --frozen-lockfile` completes on a clean checkout.
+2. `bun run check:bun-lock` passes.
+3. `bun run verify:typecheck`, `bun run verify:test`, and `bun run verify:bun-sqlite` pass.
+4. `bun run package:bun:evidence -- --require-pass` passes on supported CI OSes.
+5. Uploaded JSON shows `status: pass`, artifact/install smoke pass, no retired scripts, no `package-lock.json`, `publicationAttempted: false`, and `releaseReadiness.status: pass`.
+6. Version, release notes, proprietary license boundary, and rollback criteria are reviewed.
+7. Publishing remains a separate explicit human-approved process.
+
+This path does **not** run `npm publish`, `bun publish`, registry dry-runs that contact a registry, registry token use, provenance upload, release creation, or dist-tag mutation.
+
+### Temporary npm bridge rollback
+
+The npm publication bridge is retired as a current release path. Restore it only temporarily if Bun package evidence misses a release regression, downstream install verification fails in a way Bun did not catch, or a release candidate needs short-lived npm bridge validation while a Bun evidence gap is investigated.
+
+Restore these elements from the previous known-good main commit:
+
+- `package-lock.json`
+- package scripts: `prepack`, `package:release-check`, `package:dry-run`, and `package:smoke:install`
+- deleted helper scripts: `scripts/validate-package-release.mjs` and `scripts/smoke-tarball-install.mjs`
+- npm validation wiring and tests that enforced the bridge
+- the `.github/workflows/node22.yml` `npm-publication-bridge` job and its artifact/install-smoke steps
+
+Rollback is release-impacting and temporary. Do not publish during rollback verification unless a separate explicit approval covers publication. Open a follow-up investigation or SDD change before retiring the bridge again.
+
+### Bun package evidence probe details
+
+Run the evidence probe:
+
+```bash
+bun run package:bun:evidence
+```
+
+By default, the probe exits `0` for `pass` or `incompatible` results and exits `1` only for probe malfunction or safety violations. JSON evidence is written to stdout and optionally to a path via `--json-out <path>`. With `--require-pass`, JSON is still emitted/written first, but the process exits non-zero unless `releaseReadiness.status` is `pass`.
+
+A `pass` status means Bun produced and inspected package artifact evidence on this OS. An `incompatible` status means Bun is available but lacks a required packaging/install capability; treat it as a release blocker until resolved or explicitly accepted.
+
+The probe never invokes `npm publish`, `bun publish`, or any registry publication command. It records retired bridge status as a release-readiness invariant.
+
+### Compatibility probe
+
+The Bun runtime compatibility probe is bounded extra evidence for the built CLI entrypoint and MCP stdio server under Bun. It does not replace installed-bin package evidence and does not use the installed bin shebang. Build first; the probe intentionally requires `dist/cli/index.js` and does not auto-build or fall back to `src/`, `tsx`, or `npm run cli`:
+
+```bash
+bun run build
+bun run probe:bun-runtime
+bun run probe:bun-runtime -- --require-pass
+```
+
+The probe runs `bun dist/cli/index.js --help`, then starts `bun dist/cli/index.js mcp start --db <tmp>/memory.sqlite` with isolated temporary state. It lists MCP tools, requires `verification_plan`, calls it with `{ changeType: 'mcp' }`, and emits JSON evidence to stdout or `--json-out <path>`. Default diagnostic mode reports missing Bun as `status: incompatible` and exits `0`; `--require-pass` exits non-zero unless the full CLI + MCP smoke passes.
+
+For a strict alias, use:
+
+```bash
+bun run verify:bun-runtime
+```
+
+This alias is intentionally not part of the aggregate `verify` script.
+
+Use the older probe only when diagnosing package-manager behavior. Review the plan before allowing mutation:
+
+```bash
+npm run probe:bun
+npm run probe:bun -- --yes
+```
+
+Additional compatibility-only checks:
+
+```bash
+npm run check:bun:typecheck
+bun run typecheck
+bun run build
+bun run package:bun:evidence
+```
+
+When reporting a Bun failure, include the Bun version, OS/CPU, Node version, whether `bun install --frozen-lockfile` completed, which `bun run verify:*` command failed, and whether the error points to `bun:sqlite`, migration application, package evidence, or another install step.
+
 ## Quick path
 
 ```bash

package/docs/funcionamiento-del-sistema.md

@@ -43,13 +43,12 @@ Esa capa no reemplaza a OpenCode, Claude Code o futuros adapters. Los coordina.
 
 ## Como esta construido
 
-El proyecto esta escrito en TypeScript y corre sobre Node.js 22 o superior.
+El proyecto esta escrito en TypeScript. Node.js 22 o superior sigue siendo tooling de desarrollo/build/tests; la persistencia local real en SQLite corre por el runtime Bun soportado.
 
 Dependencias principales:
 
 | Dependencia | Uso |
 |---|---|
-| `better-sqlite3` | Persistencia local en SQLite. |
 | `@modelcontextprotocol/sdk` | Servidor MCP por stdio. |
 | `zod` | Validacion de schemas de entrada. |
 | `tsx` | Ejecucion TypeScript en desarrollo. |
@@ -63,8 +62,7 @@ Scripts principales:
 | `npm run build` | Compila TypeScript y copia migraciones. |
 | `npm run test` | Ejecuta tests con el runner nativo de Node. |
 | `npm run typecheck` | Valida tipos sin emitir archivos. |
-| `npm run package:dry-run` | Simula el empaquetado npm. |
-| `npm run package:smoke:install` | Prueba instalacion local del tarball. |
+| `bun run package:bun:evidence` | Valida el paquete con Bun: artefacto, contenido, instalacion aislada y ambos bins. |
 
 ## Vista de alto nivel
 
@@ -136,9 +134,9 @@ Archivo clave:
 src/memory/sqlite/database.ts
 ```
 
-Al abrir la base, el sistema:
+Al abrir la base con el runtime Bun, el sistema:
 
-1. Crea una conexion con `better-sqlite3`.
+1. Crea una conexion SQLite usando `bun:sqlite`.
 2. Activa `foreign_keys`.
 3. Configura `busy_timeout`.
 4. Aplica migraciones SQL si la base no esta en modo readonly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.0.5",
+  "version": "1.1.1",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -22,16 +22,26 @@
   "scripts": {
     "cli": "tsx src/cli/index.ts",
     "build": "tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
-    "prepack": "npm run build",
-    "package:dry-run": "npm pack --dry-run --json",
-    "package:release-check": "node scripts/validate-package-release.mjs",
-    "package:smoke:install": "node scripts/smoke-tarball-install.mjs",
-    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "verify": "bun run verify:typecheck && bun run verify:test && bun run verify:test:bun-storage && bun run verify:bun-sqlite && bun run verify:package",
+    "verify:typecheck": "tsc --noEmit",
+    "verify:test": "node scripts/run-node-tests.mjs",
+    "verify:test:bun-storage": "node scripts/run-bun-storage-tests.mjs",
+    "verify:package": "bun run package:bun:evidence",
+    "verify:bun-sqlite": "bun scripts/probe-bun-sqlite.mjs",
+    "ci:bun": "bun run check:bun-lock && bun run verify",
+    "check:bun-lock": "node scripts/check-bun-lock.mjs",
+    "check:vgxcode:bun-lock": "node scripts/check-bun-lock.mjs --package-json packages/vgxcode/package.json --bun-lock packages/vgxcode/bun.lock",
+    "check:bun:typecheck": "node scripts/run-bun-typecheck.mjs",
+    "probe:bun": "node scripts/probe-bun-compat.mjs",
+    "probe:bun-runtime": "node scripts/probe-bun-runtime-cli-mcp.mjs",
+    "verify:bun-runtime": "node scripts/probe-bun-runtime-cli-mcp.mjs --require-pass",
+    "package:bun:evidence": "node scripts/probe-bun-package-evidence.mjs",
+    "test": "node scripts/run-node-tests.mjs",
     "typecheck": "tsc --noEmit"
   },
   "bin": {
-    "vgxness": "dist/cli/index.js",
-    "vgx": "dist/cli/index.js"
+    "vgxness": "dist/cli/bun-bin.js",
+    "vgx": "dist/cli/bun-bin.js"
   },
   "files": [
     "dist",
@@ -43,19 +53,17 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "^12.10.0",
     "ink": "^7.0.3",
     "react": "^19.2.6",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.18",
     "@types/react": "^19.2.15",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3"
   },
   "engines": {
-    "node": ">=22"
+    "bun": ">=1.3.14"
   }
 }