@njeybe/nativ 2.0.0

package/dist/commands/db.js

@@ -0,0 +1,415 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import pc from 'picocolors';
+import { resolveConnections } from '../db/env-parser.js';
+import { disconnectedStatus, introspectDatabase } from '../db/introspector.js';
+import { diffSchemas, loadContractTables } from '../db/diff.js';
+import { DEFAULT_STUDIO_PORT, startStudioServer, writeContractSchema } from '../server/studio-server.js';
+import { renderStudioHtml } from '../server/studio-ui.js';
+/**
+ * `nativ db` command handlers.
+ * Air-gap: raw connection URLs are resolved in-process and never printed; all output
+ * (text and --json) uses masked URLs and structural metadata only.
+ */
+const ENGINE_LABEL = {
+    postgresql: 'PostgreSQL',
+    mysql: 'MySQL',
+    sqlite: 'SQLite',
+    mongodb: 'MongoDB',
+    firestore: 'Firebase Firestore',
+};
+function resolveDir(targetDirArg) {
+    return path.resolve(targetDirArg || process.cwd());
+}
+function packageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        return pkg.version ?? '1.0.0';
+    }
+    catch {
+        return '1.0.0';
+    }
+}
+function parseEnvOption(value, fallback) {
+    if (!value)
+        return fallback;
+    const v = value.toLowerCase();
+    if (v === 'dev' || v === 'prod')
+        return v;
+    console.error(pc.red(`\n✖ Invalid environment "${value}". Use 'dev' or 'prod'.\n`));
+    process.exitCode = 1;
+    return null;
+}
+async function introspectEnv(targetDir, env) {
+    const conns = resolveConnections(targetDir);
+    const conn = conns[env];
+    if (!conn) {
+        const missingKey = conns.templateInfo?.missingKeys.find((k) => k.targetEnv === env);
+        if (missingKey) {
+            const engineLabel = missingKey.engine ? ` (${ENGINE_LABEL[missingKey.engine] ?? missingKey.engine})` : '';
+            const templateName = conns.templateInfo?.templateFile ?? '.env.example';
+            const suggestion = `Found "${missingKey.key}"${engineLabel} in ${templateName}, but it is not set in your .env`;
+            return {
+                status: disconnectedStatus(`No ${env} database configured. ${suggestion}`, missingKey.engine ?? 'postgresql', '', {
+                    sourceKey: missingKey.key,
+                    detectedFromExample: true,
+                    exampleFile: templateName,
+                    suggestion,
+                }),
+                tables: [],
+            };
+        }
+        const key = env === 'dev' ? 'DEV_DATABASE_URL (or DATABASE_URL)' : 'PROD_DATABASE_URL';
+        return { status: disconnectedStatus(`No ${env} database configured. Set ${key} in .env`), tables: [] };
+    }
+    const result = await introspectDatabase(conn.url);
+    result.status.sourceKey = conn.sourceKey;
+    result.status.detectedFromExample = conn.detectedFromExample;
+    result.status.exampleFile = conn.exampleFile;
+    if (conn.synthesized)
+        result.status.synthesized = true;
+    if (!result.status.connected) {
+        const fragmentedKeys = env === 'dev' && conn.synthesized ? conns.templateInfo.fragmentedConfig?.sourceKeys : undefined;
+        const diagnostic = localStackDiagnostic(conn.url, conn.engine, result.status, fragmentedKeys ?? (conn.synthesized ? [conn.sourceKey] : undefined));
+        if (diagnostic)
+            result.status.suggestion = diagnostic;
+    }
+    return result;
+}
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0']);
+/**
+ * Actionable hint when a local MySQL/PostgreSQL server refuses the connection, e.g. MySQL not started in
+ * the XAMPP Control Panel. Only host/port are read from the URL; credentials are never touched.
+ */
+function localStackDiagnostic(url, engine, status, fragmentedKeys) {
+    if (engine !== 'mysql' && engine !== 'postgresql')
+        return null;
+    if (!/ECONNREFUSED|ETIMEDOUT|EHOSTUNREACH|connection refused/i.test(status.error ?? ''))
+        return null;
+    let host = '';
+    let port = engine === 'mysql' ? 3306 : 5432;
+    try {
+        const parsed = new URL(url);
+        host = parsed.hostname;
+        if (parsed.port)
+            port = Number(parsed.port);
+    }
+    catch {
+        return null;
+    }
+    const label = ENGINE_LABEL[engine];
+    const isLocal = LOCAL_HOSTS.has(host);
+    const action = engine === 'mysql'
+        ? isLocal
+            ? 'Ensure MySQL is started in XAMPP Control Panel.'
+            : `Ensure the MySQL server at ${host}:${port} is running and reachable.`
+        : `Ensure the PostgreSQL service is running on ${host}:${port}.`;
+    if (fragmentedKeys?.length) {
+        const shown = fragmentedKeys.filter((k) => /HOST|DATABASE|_DB$|DB_NAME$/.test(k));
+        return `Detected fragmented ${label} config (${(shown.length ? shown : fragmentedKeys).join(', ')}). ${action}`;
+    }
+    return isLocal ? `${label} refused connections on ${host}:${port}. ${action}` : null;
+}
+/** DB_HOST -> DB_*, PROD_DB_HOST -> PROD_DB_*, PGHOST -> PG*. */
+function keyFamily(key) {
+    const m = /^(.*_)[^_]*$/.exec(key);
+    return m ? `${m[1]}*` : `${key.slice(0, 2)}*`;
+}
+function printStatusLine(env, s) {
+    const label = pc.bold(env.toUpperCase().padEnd(4));
+    const synthBadge = s.synthesized && s.sourceKey ? ` ${pc.magenta(`[synthesized from ${keyFamily(s.sourceKey)}]`)}` : '';
+    if (!s.connected) {
+        console.log(`  ${pc.red('●')} ${label} ${pc.red('[OFFLINE]')}${synthBadge} ${pc.dim(s.error ?? 'Unknown error')}`);
+        if (s.suggestion) {
+            const isDiagnostic = /Ensure (MySQL|the MySQL|the PostgreSQL)/.test(s.suggestion);
+            console.log(`         ${pc.yellow(isDiagnostic ? `[DIAGNOSTIC] ${s.suggestion}` : `Tip: ${s.suggestion}`)}`);
+        }
+        if (s.maskedUrl)
+            console.log(pc.dim(`         ${s.maskedUrl}`));
+        return;
+    }
+    const count = s.entityCount ?? s.tableCount;
+    const isCollection = s.entityType === 'collection';
+    const entityWord = isCollection ? (count === 1 ? 'collection' : 'collections') : (count === 1 ? 'table' : 'tables');
+    const sourceInfo = synthBadge
+        ? synthBadge
+        : s.detectedFromExample && s.sourceKey
+            ? pc.cyan(` (via ${s.sourceKey} from ${s.exampleFile ?? '.env.example'})`)
+            : s.sourceKey
+                ? pc.dim(` (via ${s.sourceKey})`)
+                : '';
+    console.log(`  ${pc.green('●')} ${label} ${pc.green('[ONLINE]')} ${ENGINE_LABEL[s.engine] ?? s.engine}` +
+        `${s.database ? ` · ${s.database}` : ''} ${pc.dim(`(${s.pingMs}ms)`)} – ${count} ${entityWord}${sourceInfo}`);
+    console.log(pc.dim(`         ${s.maskedUrl}`));
+}
+function describeColumn(c) {
+    const flags = [];
+    if (c.primaryKey)
+        flags.push('PK');
+    if (c.isMedia)
+        flags.push('[IMAGE]');
+    if (c.isSubcollection)
+        flags.push('[SUBCOLLECTION]');
+    const flagStr = flags.length ? ` ${pc.magenta(flags.join(' '))}` : '';
+    return `${c.type}${c.nullable ? '' : ' NOT NULL'}${c.default != null ? ` DEFAULT ${c.default}` : ''}${flagStr}`;
+}
+function printDiff(diff, targetLabel) {
+    const s = diff.summary;
+    console.log(pc.bold(pc.cyan(`\nSchema Drift: Dev → ${targetLabel}`)));
+    console.log(`  ${pc.green(`+${s.addedTablesCount} added`)}  ${pc.yellow(`~${s.alteredTablesCount} altered`)}  ` +
+        `${pc.red(`-${s.droppedTablesCount} dropped`)}  ${pc.dim(`${s.unchangedTablesCount} unchanged`)}`);
+    if (!s.addedTablesCount && !s.alteredTablesCount && !s.droppedTablesCount) {
+        console.log(pc.green(`\n✔ In sync: Dev matches ${targetLabel}.\n`));
+        return;
+    }
+    for (const t of diff.addedTables) {
+        const isCol = t.entityType === 'collection';
+        const tag = isCol ? '[NEW COLLECTION]' : '[NEW TABLE]';
+        const fieldWord = isCol ? 'fields' : 'columns';
+        console.log(`\n  ${pc.green(tag)} ${pc.bold(t.name)} ${pc.dim(`(${t.columns.length} ${fieldWord})`)}`);
+    }
+    for (const t of diff.alteredTables) {
+        console.log(`\n  ${pc.yellow('[ALTERED]')} ${pc.bold(t.name)}${t.isDestructive ? ` ${pc.red('[DESTRUCTIVE]')}` : ''}`);
+        for (const c of t.addedColumns)
+            console.log(pc.green(`    + ${c.name}: ${describeColumn(c)}`));
+        for (const ch of t.alteredColumns) {
+            console.log(pc.yellow(`    ~ ${ch.name} (${ch.changedFields.join(', ')}): ${describeColumn(ch.before)} → ${describeColumn(ch.after)}`));
+        }
+        for (const c of t.droppedColumns)
+            console.log(pc.red(`    - ${c.name}: ${describeColumn(c)}`));
+        for (const i of t.addedIndexes)
+            console.log(pc.green(`    + index ${i.name} (${i.columns.join(', ')})${i.unique ? ' unique' : ''}`));
+        for (const i of t.droppedIndexes)
+            console.log(pc.red(`    - index ${i.name} (${i.columns.join(', ')})`));
+        for (const f of t.addedForeignKeys)
+            console.log(pc.green(`    + FK ${f.column} → ${f.referencedTable}.${f.referencedColumn}`));
+        for (const f of t.droppedForeignKeys)
+            console.log(pc.red(`    - FK ${f.column} → ${f.referencedTable}.${f.referencedColumn}`));
+    }
+    for (const t of diff.droppedTables) {
+        const isCol = t.entityType === 'collection';
+        const tag = isCol ? '[DROPPED COLLECTION]' : '[DROPPED]';
+        const fieldWord = isCol ? 'fields' : 'columns';
+        console.log(`\n  ${pc.red(tag)} ${pc.bold(t.name)} ${pc.dim(`(${t.columns.length} ${fieldWord})`)}`);
+    }
+    if (s.hasDestructiveChanges) {
+        console.log(pc.bgRed(pc.white(pc.bold(' HIGH SEVERITY '))) +
+            pc.red(` Destructive changes detected against ${targetLabel}. Applying them would drop data or fail on existing rows.`));
+    }
+    console.log('');
+}
+// ─── nativ db status ─────────────────────────────────────────────────────────
+export async function runDbStatus(targetDirArg, options = {}) {
+    const targetDir = resolveDir(targetDirArg);
+    const [dev, prod] = await Promise.all([introspectEnv(targetDir, 'dev'), introspectEnv(targetDir, 'prod')]);
+    if (options.json) {
+        console.log(JSON.stringify({ dev: dev.status, prod: prod.status }, null, 2));
+        return;
+    }
+    console.log(pc.bold(pc.cyan('\nnativ Database Telemetry')));
+    printStatusLine('dev', dev.status);
+    printStatusLine('prod', prod.status);
+    console.log('');
+    if (!dev.status.connected && !prod.status.connected)
+        process.exitCode = 1;
+}
+// ─── nativ db inspect ────────────────────────────────────────────────────────
+export async function runDbInspect(targetDirArg, options = {}) {
+    const env = parseEnvOption(options.env, 'dev');
+    if (!env)
+        return;
+    const targetDir = resolveDir(targetDirArg);
+    const result = await introspectEnv(targetDir, env);
+    if (!result.status.connected) {
+        if (options.json)
+            console.log(JSON.stringify({ status: result.status, tables: [] }, null, 2));
+        else
+            console.error(pc.red(`\n✖ ${env.toUpperCase()} database unavailable: ${result.status.error}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const isCollection = result.status.entityType === 'collection';
+    const entityWord = isCollection ? 'Collections' : 'Tables';
+    const singleEntityWord = isCollection ? 'Collection' : 'Table';
+    let tables = result.tables;
+    if (options.table) {
+        const wanted = options.table.toLowerCase();
+        tables = tables.filter((t) => t.name.toLowerCase() === wanted);
+        if (!tables.length) {
+            console.error(pc.red(`\n✖ ${singleEntityWord} "${options.table}" not found in ${env.toUpperCase()}.\n`));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ status: result.status, tables }, null, 2));
+        return;
+    }
+    console.log(pc.bold(pc.cyan(`\n${env.toUpperCase()} Schema (${entityWord})`)) + pc.dim(` · ${result.status.maskedUrl}`));
+    for (const t of tables) {
+        const isCol = t.entityType === 'collection' || isCollection;
+        const fieldWord = isCol ? 'fields' : 'columns';
+        const tag = isCol ? pc.green('[COLLECTION] ') : '';
+        console.log(`\n  ${tag}${pc.bold(t.name)} ${pc.dim(`(${t.columns.length} ${fieldWord})`)}`);
+        if (t.description)
+            console.log(pc.dim(`    ${t.description}`));
+        const fkByColumn = new Map(t.foreignKeys.map((f) => [f.column.toLowerCase(), f]));
+        const nameWidth = Math.max(...t.columns.map((c) => c.name.length), 4);
+        for (const c of t.columns) {
+            const fk = fkByColumn.get(c.name.toLowerCase());
+            const flags = [];
+            if (c.primaryKey)
+                flags.push(pc.magenta('PK'));
+            if (c.isMedia)
+                flags.push(pc.magenta('[IMAGE]'));
+            if (c.isSubcollection)
+                flags.push(pc.cyan('[SUBCOLLECTION]'));
+            if (fk)
+                flags.push(pc.cyan(`FK→${fk.referencedTable}.${fk.referencedColumn}`));
+            const tags = flags.join(' ');
+            console.log(`    ${c.name.padEnd(nameWidth)}  ${c.type}${c.nullable ? '' : pc.dim(' NOT NULL')}` +
+                `${c.default != null ? pc.dim(` DEFAULT ${c.default}`) : ''}${tags ? `  ${tags}` : ''}`);
+        }
+        for (const i of t.indexes)
+            console.log(pc.dim(`    index ${i.name} (${i.columns.join(', ')})${i.unique ? ' unique' : ''}`));
+    }
+    console.log('');
+}
+// ─── nativ db diff ───────────────────────────────────────────────────────────
+export async function runDbDiff(targetDirArg, options = {}) {
+    const target = (options.target ?? 'prod').toLowerCase();
+    if (target !== 'prod' && target !== 'contract') {
+        console.error(pc.red(`\n✖ Invalid --target "${options.target}". Use 'prod' or 'contract'.\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const targetDir = resolveDir(targetDirArg);
+    const dev = await introspectEnv(targetDir, 'dev');
+    if (!dev.status.connected) {
+        console.error(pc.red(`\n✖ Dev database unavailable: ${dev.status.error}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    let targetTables;
+    let targetLabel;
+    if (target === 'contract') {
+        targetTables = loadContractTables(targetDir);
+        targetLabel = '.ai/db_schema.json';
+    }
+    else {
+        const prod = await introspectEnv(targetDir, 'prod');
+        if (!prod.status.connected) {
+            console.error(pc.red(`\n✖ Prod database unavailable: ${prod.status.error}`));
+            console.log(pc.yellow('  Tip: use --target contract to compare Dev against .ai/db_schema.json instead.\n'));
+            process.exitCode = 1;
+            return;
+        }
+        targetTables = prod.tables;
+        targetLabel = 'Prod';
+    }
+    const diff = diffSchemas(dev.tables, targetTables);
+    if (options.json)
+        console.log(JSON.stringify(diff, null, 2));
+    else
+        printDiff(diff, targetLabel);
+    const s = diff.summary;
+    if (options.exitCode && s.addedTablesCount + s.alteredTablesCount + s.droppedTablesCount > 0)
+        process.exitCode = 1;
+}
+// ─── nativ db sync ───────────────────────────────────────────────────────────
+/** Exports a live schema into .ai/db_schema.json. Previews unless --yes is passed. */
+export async function runDbSync(targetDirArg, options = {}) {
+    const source = parseEnvOption(options.source, 'dev');
+    if (!source)
+        return;
+    const targetDir = resolveDir(targetDirArg);
+    const result = await introspectEnv(targetDir, source);
+    if (!result.status.connected) {
+        console.error(pc.red(`\n✖ ${source.toUpperCase()} database unavailable: ${result.status.error}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const diff = diffSchemas(result.tables, loadContractTables(targetDir));
+    const s = diff.summary;
+    const changed = s.addedTablesCount + s.alteredTablesCount + s.droppedTablesCount;
+    console.log(pc.bold(pc.cyan(`\nSync ${source.toUpperCase()} schema → .ai/db_schema.json`)) + pc.dim(` · ${result.status.maskedUrl}`));
+    if (!changed) {
+        console.log(pc.green('✔ Contract already matches the live schema. Nothing to write.\n'));
+        return;
+    }
+    printDiff(diff, '.ai/db_schema.json');
+    if (!options.yes) {
+        console.log(pc.yellow('Dry run: no files were changed. Re-run with --yes to write .ai/db_schema.json.\n'));
+        return;
+    }
+    const filePath = writeContractSchema(targetDir, result.status, result.tables);
+    const count = result.tables.length;
+    const isCollection = result.status.entityType === 'collection';
+    const entityWord = isCollection ? (count === 1 ? 'collection' : 'collections') : (count === 1 ? 'table' : 'tables');
+    console.log(pc.green(`✔ Wrote ${count} ${entityWord} (structure only, no credentials) to ${path.relative(targetDir, filePath)}\n`));
+}
+// ─── nativ db ui ─────────────────────────────────────────────────────────────
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '""', url]]
+        : process.platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        // Headless environment — the URL is printed anyway.
+    }
+}
+export async function runDbUi(targetDirArg, options = {}) {
+    const targetDir = resolveDir(targetDirArg);
+    const port = options.port ? Number.parseInt(options.port, 10) : DEFAULT_STUDIO_PORT;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        console.error(pc.red(`\n✖ Invalid --port "${options.port}".\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const version = packageVersion();
+    let handle;
+    try {
+        handle = await startStudioServer({ port, cwd: targetDir, html: () => renderStudioHtml({ version }) });
+    }
+    catch (err) {
+        console.error(pc.red(`\n✖ Failed to start DB Studio: ${err instanceof Error ? err.message : String(err)}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const conns = resolveConnections(targetDir);
+    console.log(pc.bold(pc.cyan(`\nNativ DB Studio v${version}`)));
+    const describeSource = (c) => !c
+        ? ''
+        : c.synthesized
+            ? ` [synthesized from ${keyFamily(c.sourceKey)}]`
+            : c.detectedFromExample
+                ? ` (from ${c.sourceKey} in ${c.exampleFile ?? '.env.example'})`
+                : c.sourceKey
+                    ? ` (${c.sourceKey})`
+                    : '';
+    const devSource = describeSource(conns.dev);
+    const prodSource = describeSource(conns.prod);
+    console.log(pc.dim(`  Dev:  ${conns.dev ? `${conns.dev.maskedUrl}${devSource}` : 'not configured'}`));
+    console.log(pc.dim(`  Prod: ${conns.prod ? `${conns.prod.maskedUrl}${prodSource}` : 'not configured'}`));
+    console.log(pc.dim('  Credentials stay in this process only. Press Ctrl+C to stop.\n'));
+    if (options.open !== false)
+        openBrowser(handle.url);
+    await new Promise((resolve) => {
+        const shutdown = () => {
+            process.off('SIGINT', shutdown);
+            process.off('SIGTERM', shutdown);
+            console.log(pc.dim('\nStopping DB Studio…'));
+            handle.server.closeAllConnections?.();
+            handle.close().then(resolve, resolve);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    });
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,38 @@
+import { type SetupOptions } from '../core/setup-assets.js';
+import type { ProviderDeps } from '../providers/index.js';
+export type CheckStatus = 'ok' | 'warn' | 'fail' | 'info';
+export interface DoctorCheck {
+    id: string;
+    status: CheckStatus;
+    message: string;
+    /** True when `nativ doctor --fix` (which runs setup) can repair it. */
+    fixable?: boolean;
+}
+export interface DoctorReport {
+    ok: boolean;
+    root: string;
+    fixed: string[];
+    checks: DoctorCheck[];
+}
+export interface DoctorOptions extends SetupOptions {
+    fix?: boolean;
+    json?: boolean;
+    /** Also ask Claude Code itself (`claude mcp list`, a few seconds) whether the nativ server connects and is not shadowed. */
+    deep?: boolean;
+    /** Returns the text of `claude mcp list`, or null when it could not run; injectable for tests. */
+    mcpList?: (cwd: string) => string | null;
+    /** Runs `<command> --version`; injectable so tests need no real binaries. */
+    runVersion?: (command: string, args: string[]) => {
+        ok: boolean;
+        output: string;
+    };
+    providerDeps?: ProviderDeps;
+}
+/**
+ * Reads Claude Code's own view of the nativ MCP server. A `nativ` server registered in the user's local or
+ * user scope silently shadows the project's `.mcp.json`, so setup can succeed while Claude runs something else.
+ */
+export declare function analyzeMcpList(text: string): DoctorCheck[];
+/** Collects every check without changing anything. */
+export declare function collectChecks(root: string, options?: DoctorOptions): DoctorCheck[];
+export declare function runDoctor(targetDirArg?: string, options?: DoctorOptions): DoctorReport;

package/dist/commands/doctor.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { spawnSync } from 'node:child_process';
+import { loadEnforcementMode, parseJsonLoose } from '../core/enforcement.js';
+import { resolveProjectRoot } from '../core/root-resolver.js';
+import { applySetup, defaultHasBinary, planSetup } from '../core/setup-assets.js';
+import { createProviders, providerCooldownRemaining } from '../providers/index.js';
+function defaultRunVersion(command, args) {
+    try {
+        // The Windows shims (nativ.cmd, npx.cmd) only start through a shell.
+        const result = spawnSync(command, [...args, '--version'], { encoding: 'utf8', timeout: 20_000, shell: process.platform === 'win32' });
+        return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim().split(/\r?\n/)[0] ?? '' };
+    }
+    catch (err) {
+        return { ok: false, output: err instanceof Error ? err.message : String(err) };
+    }
+}
+function defaultMcpList(cwd) {
+    try {
+        const result = spawnSync('claude', ['mcp', 'list'], { cwd, encoding: 'utf8', timeout: 60_000, shell: process.platform === 'win32' });
+        return result.status === 0 ? `${result.stdout ?? ''}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads Claude Code's own view of the nativ MCP server. A `nativ` server registered in the user's local or
+ * user scope silently shadows the project's `.mcp.json`, so setup can succeed while Claude runs something else.
+ */
+export function analyzeMcpList(text) {
+    const checks = [];
+    const line = text.split(/\r?\n/).find((l) => /^nativ:/.test(l.trim()));
+    if (!line) {
+        checks.push({ id: 'mcp-listed', status: 'warn', message: 'Claude Code does not list a "nativ" MCP server here. Check that the project .mcp.json is approved (enabledMcpjsonServers) and the workspace is trusted.' });
+    }
+    else if (/Connected/.test(line)) {
+        checks.push({ id: 'mcp-connected', status: 'ok', message: `Claude Code connects to the nativ MCP server (${line.replace(/\s+-\s+.*$/, '').trim()})` });
+    }
+    else {
+        checks.push({ id: 'mcp-connected', status: 'fail', message: `Claude Code lists the nativ MCP server but it is not connected: ${line.trim()}` });
+    }
+    // eslint-disable-next-line no-control-regex
+    const plain = text.replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, '');
+    const conflict = /Server "nativ" is defined in multiple scopes[^\n]*/.exec(plain);
+    if (conflict) {
+        checks.push({
+            id: 'mcp-scope-conflict',
+            status: 'warn',
+            message: `${conflict[0].trim()} The other scope wins over the project .mcp.json. Remove the one you do not want, e.g. \`claude mcp remove nativ -s local\`.`,
+        });
+    }
+    return checks;
+}
+/** Collects every check without changing anything. */
+export function collectChecks(root, options = {}) {
+    const checks = [];
+    const add = (id, status, message, fixable = false) => checks.push({ id, status, message, fixable });
+    const hasBinary = options.hasBinary ?? defaultHasBinary;
+    const runVersion = options.runVersion ?? defaultRunVersion;
+    const planFile = path.join(root, '.ai', 'master_plan.json');
+    if (!fs.existsSync(planFile)) {
+        add('project', 'fail', 'No .ai/master_plan.json. Run `nativ init` first.');
+    }
+    else {
+        try {
+            parseJsonLoose(fs.readFileSync(planFile, 'utf8'));
+            add('project', 'ok', '.ai/ workflow found');
+        }
+        catch (err) {
+            // Enforcement cannot see the active task in a plan it cannot read, so this must never be a quiet state.
+            add('project', 'fail', `.ai/master_plan.json cannot be parsed (${err instanceof Error ? err.message : String(err)}). Role enforcement cannot see the active task until it is fixed.`);
+        }
+    }
+    // Claude Code itself
+    if (hasBinary('claude')) {
+        const version = runVersion('claude', []);
+        add('claude', version.ok ? 'ok' : 'warn', version.ok ? `Claude Code found (${version.output})` : 'The claude executable is on PATH but did not run.');
+    }
+    else {
+        add('claude', 'warn', 'Claude Code (`claude`) is not on PATH. Install it from https://claude.com/claude-code; nativ still works without it for the CLI.');
+    }
+    // How the generated config will start nativ
+    const plan = planSetup(root, options);
+    const invocation = plan.invocation;
+    const cli = [invocation.command, ...invocation.prefixArgs];
+    if (!invocation.portable) {
+        add('cli-portable', 'warn', 'The nativ command points at an absolute path on this machine. Install nativ globally or run `nativ setup --command "npx -y @njeybe/nativ"`.');
+    }
+    const version = runVersion(invocation.command, invocation.prefixArgs);
+    add('cli-runs', version.ok ? 'ok' : 'fail', version.ok ? `\`${cli.join(' ')}\` runs (${version.output})` : `\`${cli.join(' ')}\` does not run: ${version.output || 'no output'}. The hooks and MCP server would fail.`);
+    // Generated assets: whatever setup would still change is drift
+    for (const change of plan.changes) {
+        if (change.action === 'created')
+            add(`asset:${change.path}`, 'fail', `${change.path} is missing`, true);
+        else if (change.action === 'updated')
+            add(`asset:${change.path}`, 'warn', `${change.path} is out of date${change.detail ? ` (${change.detail})` : ''}`, true);
+        else if (change.action === 'skipped')
+            add(`asset:${change.path}`, 'warn', `${change.path}: ${change.detail ?? 'not managed by nativ'}`);
+        else if (change.detail)
+            add(`asset:${change.path}`, 'info', `${change.path}: ${change.detail}`);
+    }
+    if (!plan.changes.some((c) => c.action === 'created' || c.action === 'updated'))
+        add('assets', 'ok', 'MCP server, hooks, permissions, agents and directives are in place');
+    // Claude Code's own view (opt-in: it connects to every configured MCP server)
+    if (options.deep && hasBinary('claude')) {
+        const listing = (options.mcpList ?? defaultMcpList)(root);
+        if (listing === null)
+            add('mcp-listed', 'warn', '`claude mcp list` could not run, so the live MCP connection was not checked.');
+        else
+            for (const c of analyzeMcpList(listing))
+                checks.push(c);
+    }
+    // Trust: Claude Code ignores a project's permissions.allow (and may skip its hooks) until the folder is trusted
+    add('trust', 'info', 'Open Claude Code in this folder once and accept the trust dialog, otherwise project permissions.allow entries are ignored.');
+    // Enforcement
+    const mode = loadEnforcementMode(root);
+    add('enforcement', mode === 'off' ? 'warn' : 'ok', mode === 'off' ? 'Role enforcement is off: nothing stops an agent editing outside its task.' : `Role enforcement is ${mode}`);
+    // Providers
+    const providers = createProviders(options.providerDeps);
+    const usable = [];
+    for (const [id, provider] of Object.entries(providers)) {
+        const cooling = providerCooldownRemaining(root, id);
+        if (provider.hasCredentials(root) && !cooling)
+            usable.push(id);
+        else if (cooling)
+            add(`provider:${id}`, 'info', `${id} is cooling down after a limit (${Math.ceil(cooling / 60_000)} min left)`);
+    }
+    if (usable.length)
+        add('providers', 'ok', `Triage can use: ${usable.join(', ')}`);
+    else
+        add('providers', 'warn', 'No AI provider is available for triage (sign in to Claude Code or set ANTHROPIC_API_KEY or GEMINI_API_KEY). The offline rules engine will be used.');
+    return checks;
+}
+export function runDoctor(targetDirArg, options = {}) {
+    const root = resolveProjectRoot(targetDirArg);
+    const fixed = [];
+    if (options.fix) {
+        const before = collectChecks(root, options).filter((c) => c.fixable);
+        if (before.length) {
+            const result = applySetup(root, options);
+            for (const change of result.changes)
+                if (change.action === 'created' || change.action === 'updated')
+                    fixed.push(change.path);
+        }
+    }
+    const checks = collectChecks(root, options);
+    const report = { ok: !checks.some((c) => c.status === 'fail'), root, fixed, checks };
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(pc.bold(pc.cyan('\nnativ doctor')) + pc.dim(`  ${root}`));
+        const paint = { ok: pc.green, warn: pc.yellow, fail: pc.red, info: pc.dim };
+        const mark = { ok: '✔', warn: '⚠', fail: '✖', info: '·' };
+        for (const c of checks)
+            console.log(paint[c.status](`  ${mark[c.status]} ${c.message}`) + (c.fixable && !options.fix ? pc.dim('  (fixable)') : ''));
+        if (fixed.length)
+            console.log(pc.green(`\n✔ Repaired: ${fixed.join(', ')}`));
+        const fixable = checks.filter((c) => c.fixable).length;
+        console.log(report.ok
+            ? pc.green(`\n✔ Healthy${checks.some((c) => c.status === 'warn') ? ' (with warnings)' : ''}.\n`)
+            : pc.red(`\n✖ Problems found.${fixable ? ' Run `nativ doctor --fix` to repair what can be repaired.' : ''}\n`));
+    }
+    if (!report.ok)
+        process.exitCode = 1;
+    return report;
+}

package/dist/commands/hook.d.ts

@@ -0,0 +1,31 @@
+import { type EnforcementMode } from '../core/enforcement.js';
+export interface HookCheckOptions {
+    /** Stdin and stdout are injectable for tests. */
+    input?: NodeJS.ReadableStream;
+    output?: (text: string) => void;
+    /** Forces a mode instead of reading .nativ/config.json. */
+    mode?: EnforcementMode;
+    role?: string;
+}
+/**
+ * `nativ hook check`: the PreToolUse hook entry point. Reads Claude Code's JSON from stdin and prints the
+ * hook decision to stdout. It always exits 0 and fails open: a broken payload, unreadable state or a bug
+ * here must never stop an agent's tool call. Only `block` mode ever denies, and only on a real violation.
+ */
+export declare function runHookCheck(targetDirArg?: string, options?: HookCheckOptions): Promise<void>;
+export interface HookStatus {
+    ok: true;
+    root: string;
+    mode: EnforcementMode;
+    role: string;
+    activeTasks: Array<{
+        id: string;
+        targetFiles: string[];
+        unlocked: boolean;
+    }>;
+}
+/** `nativ hook status`: what the hook would enforce right now. Read-only. */
+export declare function getHookStatus(targetDirArg?: string): HookStatus;
+export declare function runHookStatus(targetDirArg?: string, options?: {
+    json?: boolean;
+}): HookStatus;