hex-audit 0.5.1 → 0.5.3

package/dashboard/components/DashboardLayout.tsx

@@ -361,7 +361,13 @@ function ThemeToggle() {
 }
 
 /* ── Layout ── */
-export function DashboardLayout({ children }: { children: React.ReactNode }) {
+export function DashboardLayout({
+  children,
+  version,
+}: {
+  children: React.ReactNode;
+  version: string;
+}) {
   const pathname = usePathname();
   const [sidebarOpen, setSidebarOpen] = useState(false);
 
@@ -401,7 +407,7 @@ export function DashboardLayout({ children }: { children: React.ReactNode }) {
         <div className="px-5 pb-4 pt-6">
           <div className="flex items-baseline gap-2">
             <span className="text-title font-semibold text-text-primary">Hex</span>
-            <span className="text-caption text-text-tertiary">v0.5.1</span>
+            <span className="text-caption text-text-tertiary">v{version}</span>
           </div>
         </div>
 
@@ -449,7 +455,9 @@ export function DashboardLayout({ children }: { children: React.ReactNode }) {
 
       {/* Main content */}
       <main className="min-h-screen bg-surface-0 p-6 pt-16 md:ml-[220px] md:pt-6">
-        <div className="mx-auto max-w-6xl">{children}</div>
+        <div className={`mx-auto ${pathname === '/issues' ? 'max-w-none' : 'max-w-6xl'}`}>
+          {children}
+        </div>
       </main>
     </div>
   );

package/dist/commands/note.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const noteCommand: Command;
+//# sourceMappingURL=note.d.ts.map

package/dist/commands/note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsJpC,eAAO,MAAM,WAAW,SAOC,CAAC"}

package/dist/commands/note.js

@@ -0,0 +1,145 @@
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../core/logger.js';
+import { loadProjectContext } from '../core/config.js';
+import { reportError } from '../core/errors.js';
+import { readNote, writeNote, appendNote, readNotesIndex, setActiveContract, createSession, latestUnprocessedSession, markSessionProcessed, } from '../core/notes.js';
+function resolveOutputDir(opts) {
+    return loadProjectContext(opts.project ?? process.cwd()).outputDir;
+}
+function readFileTrim(p) {
+    return fs.readFileSync(path.resolve(p), 'utf-8').trim();
+}
+const readCmd = new Command('read')
+    .description('Print a note doc (target: "general" or a contract name)')
+    .argument('<target>', '"general" or a contract name')
+    .option('--project <dir>', 'Project directory')
+    .action((target, opts) => {
+    try {
+        process.stdout.write(readNote(resolveOutputDir(opts), target));
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+const writeCmd = new Command('write')
+    .description('Replace a note doc with the contents of a file')
+    .argument('<target>', '"general" or a contract name')
+    .requiredOption('--body-file <path>', 'Read the note body from this file')
+    .option('--project <dir>', 'Project directory')
+    .action((target, opts) => {
+    try {
+        writeNote(resolveOutputDir(opts), target, readFileTrim(opts.bodyFile));
+        logger.success(`Wrote note: ${target}`);
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+const appendCmd = new Command('append')
+    .description('Append a block to a note doc (Diane accretes notes this way)')
+    .argument('<target>', '"general" or a contract name')
+    .requiredOption('--body-file <path>', 'Read the block to append from this file')
+    .option('--project <dir>', 'Project directory')
+    .action((target, opts) => {
+    try {
+        appendNote(resolveOutputDir(opts), target, readFileTrim(opts.bodyFile));
+        logger.success(`Appended to note: ${target}`);
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+const listCmd = new Command('list')
+    .description('Print the notes index (active contract, contracts, sessions) as JSON')
+    .option('--project <dir>', 'Project directory')
+    .action((opts) => {
+    try {
+        console.log(JSON.stringify(readNotesIndex(resolveOutputDir(opts)), null, 2));
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+const activeCmd = new Command('active')
+    .description('Set the active contract (the one being narrated)')
+    .argument('<name>', 'Contract name')
+    .option('--project <dir>', 'Project directory')
+    .action((name, opts) => {
+    try {
+        setActiveContract(resolveOutputDir(opts), name);
+        logger.success(`Active contract → ${name}`);
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+// ─── session subcommands ────────────────────────────────────────────
+const sessionLatestCmd = new Command('latest')
+    .description('Print the latest unprocessed narration session (with transcript) as JSON, for /diane')
+    .option('--project <dir>', 'Project directory')
+    .action((opts) => {
+    try {
+        const session = latestUnprocessedSession(resolveOutputDir(opts));
+        console.log(JSON.stringify(session, null, 2));
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+const sessionAddCmd = new Command('add')
+    .description('Register a session from an existing transcript file (no audio/whisper — useful for testing)')
+    .requiredOption('--transcript-file <path>', 'Transcript text file')
+    .requiredOption('--contract <name>', 'Contract this session covers')
+    .option('--ts <iso>', 'Timestamp (defaults to now)')
+    .option('--project <dir>', 'Project directory')
+    .action((opts) => {
+    try {
+        const ts = (opts.ts ?? new Date().toISOString()).replace(/[:.]/g, '-');
+        const session = createSession(resolveOutputDir(opts), {
+            ts,
+            contract: opts.contract,
+            transcript: readFileTrim(opts.transcriptFile),
+        });
+        logger.success(`Session added: ${session.file} (contract: ${session.contract})`);
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+const sessionMarkCmd = new Command('mark-processed')
+    .description('Mark a session as ingested by Diane')
+    .argument('<file>', 'Session file (relative path from `hex note session latest`)')
+    .option('--project <dir>', 'Project directory')
+    .action((file, opts) => {
+    try {
+        markSessionProcessed(resolveOutputDir(opts), file);
+        logger.success(`Session marked processed: ${file}`);
+    }
+    catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+});
+const sessionCmd = new Command('session')
+    .description('Manage narration sessions (latest / add / mark-processed)')
+    .addCommand(sessionLatestCmd)
+    .addCommand(sessionAddCmd)
+    .addCommand(sessionMarkCmd);
+export const noteCommand = new Command('note')
+    .description('Read and write Diane audit notes (read / write / append / list / active / session)')
+    .addCommand(readCmd)
+    .addCommand(writeCmd)
+    .addCommand(appendCmd)
+    .addCommand(listCmd)
+    .addCommand(activeCmd)
+    .addCommand(sessionCmd);
+//# sourceMappingURL=note.js.map

package/dist/commands/note.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"note.js","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"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"}

package/dist/core/notes.d.ts

@@ -0,0 +1,62 @@
+export interface SessionEntry {
+    /** Path relative to the notes dir, e.g. `sessions/2026-06-04T...md`. */
+    file: string;
+    /** Contract this session was recorded against (or `general`). */
+    contract: string;
+    /** ISO timestamp the session was created. */
+    ts: string;
+    /** Whether Diane has already ingested this transcript. */
+    processed: boolean;
+    /** Path (relative to notes dir) of the raw recording, if any. */
+    audio?: string;
+}
+export interface NotesIndex {
+    /** Contract currently being narrated (drives the dashboard default). */
+    active_contract: string | null;
+    /** Contracts that have a note doc. */
+    contracts: string[];
+    /** Recorded narration sessions, newest last. */
+    sessions: SessionEntry[];
+}
+/** Resolve a note target (`general` or a contract name) to its `.md` path. */
+export declare function notePath(outputDir: string, target: string): string;
+export declare function readNotesIndex(outputDir: string): NotesIndex;
+export declare function writeNotesIndex(outputDir: string, index: NotesIndex): void;
+/** Read a note doc. Returns '' when it doesn't exist yet. */
+export declare function readNote(outputDir: string, target: string): string;
+/** Replace a note doc wholesale (used by the dashboard editor's Save). */
+export declare function writeNote(outputDir: string, target: string, body: string): void;
+/**
+ * Append a block to a note doc, separated by a blank line. This is how `/diane`
+ * accretes structured notes across narration sessions.
+ */
+export declare function appendNote(outputDir: string, target: string, body: string): void;
+export declare function listContracts(outputDir: string): string[];
+export declare function setActiveContract(outputDir: string, name: string): void;
+/**
+ * Register a freshly recorded narration session and make its contract active.
+ * `file` / `audio` are paths relative to the notes dir.
+ */
+export declare function addSession(outputDir: string, entry: {
+    file: string;
+    contract: string;
+    ts: string;
+    audio?: string;
+}): SessionEntry;
+/** The most recent session Diane hasn't ingested yet, with its transcript. */
+export declare function latestUnprocessedSession(outputDir: string): (SessionEntry & {
+    text: string;
+}) | null;
+export declare function markSessionProcessed(outputDir: string, file: string): void;
+/**
+ * Write a transcript into `sessions/<ts>.md` and register it. Returns the
+ * session's relative file path. Used by the dashboard record route (after
+ * transcription) and by `hex note session add` (for testing without audio).
+ */
+export declare function createSession(outputDir: string, opts: {
+    ts: string;
+    contract: string;
+    transcript: string;
+    audio?: string;
+}): SessionEntry;
+//# sourceMappingURL=notes.d.ts.map

package/dist/core/notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/core/notes.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sCAAsC;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAeD,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGlE;AAsBD,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAa5D;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAK1E;AAUD,6DAA6D;AAC7D,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAK/E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIhF;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAEzD;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAKvE;AAID;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,YAAY,CAcd;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,GAChB,CAAC,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAU1C;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAM1E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE,YAAY,CAKd"}

package/dist/core/notes.js

@@ -0,0 +1,160 @@
+/**
+ * Canonical notes-mutation logic for Diane — the voice-narration audit
+ * companion. Shared by the `hex note` CLI command, the `/diane` skill (which
+ * shells `hex note ...`), and the dashboard's Notes API routes.
+ *
+ * Notes live under `<output_dir>/notes/`:
+ *   notes.json              index: active contract, contract list, sessions
+ *   general.md              cross-cutting / protocol-wide notes
+ *   contracts/<Name>.md     one Obsidian-style doc per contract
+ *   sessions/<ts>.md        raw transcripts (audit trail; never auto-deleted)
+ *   audio/<ts>.webm         raw recordings (kept until transcribed)
+ *
+ * Like src/core/issues.ts, this module depends ONLY on node:fs / node:path and
+ * is parameterized by `outputDir`, so the dashboard can import it across the
+ * src/ <-> dashboard/ boundary via `experimental.externalDir` without dragging
+ * CLI deps (chalk/ora/zod) into the Next.js bundle. Keep it that way.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const EMPTY_INDEX = { active_contract: null, contracts: [], sessions: [] };
+// ─── Paths ──────────────────────────────────────────────────────────
+function notesDir(outputDir) {
+    return path.join(outputDir, 'notes');
+}
+/** Filesystem-safe doc filename from a contract display name. */
+function safeName(name) {
+    return name.replace(/[/\\:*?"<>|]/g, '_').trim();
+}
+/** Resolve a note target (`general` or a contract name) to its `.md` path. */
+export function notePath(outputDir, target) {
+    if (target === 'general')
+        return path.join(notesDir(outputDir), 'general.md');
+    return path.join(notesDir(outputDir), 'contracts', safeName(target) + '.md');
+}
+// ─── Low-level IO (atomic) ──────────────────────────────────────────
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function writeTextAtomic(file, content) {
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const tmp = file + '.tmp';
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, file);
+}
+// ─── Index ──────────────────────────────────────────────────────────
+export function readNotesIndex(outputDir) {
+    const raw = readText(path.join(notesDir(outputDir), 'notes.json'));
+    if (!raw)
+        return { ...EMPTY_INDEX };
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            active_contract: parsed.active_contract ?? null,
+            contracts: Array.isArray(parsed.contracts) ? parsed.contracts : [],
+            sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
+        };
+    }
+    catch {
+        return { ...EMPTY_INDEX };
+    }
+}
+export function writeNotesIndex(outputDir, index) {
+    writeTextAtomic(path.join(notesDir(outputDir), 'notes.json'), JSON.stringify(index, null, 2) + '\n');
+}
+/** Ensure a contract is tracked in the index (no-op for `general`). */
+function trackContract(index, target) {
+    if (target === 'general')
+        return;
+    if (!index.contracts.includes(target))
+        index.contracts.push(target);
+}
+// ─── Notes ──────────────────────────────────────────────────────────
+/** Read a note doc. Returns '' when it doesn't exist yet. */
+export function readNote(outputDir, target) {
+    return readText(notePath(outputDir, target)) ?? '';
+}
+/** Replace a note doc wholesale (used by the dashboard editor's Save). */
+export function writeNote(outputDir, target, body) {
+    writeTextAtomic(notePath(outputDir, target), body.endsWith('\n') ? body : body + '\n');
+    const index = readNotesIndex(outputDir);
+    trackContract(index, target);
+    writeNotesIndex(outputDir, index);
+}
+/**
+ * Append a block to a note doc, separated by a blank line. This is how `/diane`
+ * accretes structured notes across narration sessions.
+ */
+export function appendNote(outputDir, target, body) {
+    const existing = readNote(outputDir, target);
+    const sep = existing.trim() === '' ? '' : (existing.endsWith('\n') ? '\n' : '\n\n');
+    writeNote(outputDir, target, existing + sep + body.trim() + '\n');
+}
+export function listContracts(outputDir) {
+    return readNotesIndex(outputDir).contracts;
+}
+export function setActiveContract(outputDir, name) {
+    const index = readNotesIndex(outputDir);
+    index.active_contract = name;
+    trackContract(index, name);
+    writeNotesIndex(outputDir, index);
+}
+// ─── Sessions ───────────────────────────────────────────────────────
+/**
+ * Register a freshly recorded narration session and make its contract active.
+ * `file` / `audio` are paths relative to the notes dir.
+ */
+export function addSession(outputDir, entry) {
+    const index = readNotesIndex(outputDir);
+    const session = {
+        file: entry.file,
+        contract: entry.contract,
+        ts: entry.ts,
+        processed: false,
+        ...(entry.audio ? { audio: entry.audio } : {}),
+    };
+    index.sessions.push(session);
+    index.active_contract = entry.contract;
+    trackContract(index, entry.contract);
+    writeNotesIndex(outputDir, index);
+    return session;
+}
+/** The most recent session Diane hasn't ingested yet, with its transcript. */
+export function latestUnprocessedSession(outputDir) {
+    const index = readNotesIndex(outputDir);
+    for (let i = index.sessions.length - 1; i >= 0; i--) {
+        const s = index.sessions[i];
+        if (!s.processed) {
+            const text = readText(path.join(notesDir(outputDir), s.file)) ?? '';
+            return { ...s, text };
+        }
+    }
+    return null;
+}
+export function markSessionProcessed(outputDir, file) {
+    const index = readNotesIndex(outputDir);
+    const session = index.sessions.find((s) => s.file === file);
+    if (!session)
+        throw new Error(`No session with file ${file}`);
+    session.processed = true;
+    writeNotesIndex(outputDir, index);
+}
+/**
+ * Write a transcript into `sessions/<ts>.md` and register it. Returns the
+ * session's relative file path. Used by the dashboard record route (after
+ * transcription) and by `hex note session add` (for testing without audio).
+ */
+export function createSession(outputDir, opts) {
+    const rel = path.join('sessions', `${opts.ts}.md`);
+    const header = `# Narration — ${opts.contract} — ${opts.ts}\n\n`;
+    writeTextAtomic(path.join(notesDir(outputDir), rel), header + opts.transcript.trim() + '\n');
+    return addSession(outputDir, { file: rel, contract: opts.contract, ts: opts.ts, audio: opts.audio });
+}
+//# sourceMappingURL=notes.js.map

package/dist/core/notes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes.js","sourceRoot":"","sources":["../../src/core/notes.ts"],"names":[],"mappings":"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"}

package/dist/core/whisper.d.ts

@@ -0,0 +1,24 @@
+/** Thrown when no local Whisper engine is installed. The caller turns this into
+ *  a setup hint and preserves the raw audio so no narration is lost. */
+export declare class WhisperMissingError extends Error {
+    constructor();
+}
+export type WhisperEngine = {
+    kind: 'openai';
+    bin: string;
+} | {
+    kind: 'faster';
+    bin: string;
+} | {
+    kind: 'cpp';
+    bin: string;
+    model: string;
+};
+/** Find an installed engine, or null. */
+export declare function detectWhisper(): WhisperEngine | null;
+/**
+ * Transcribe `audioPath` to plain text. Throws WhisperMissingError when no
+ * engine is installed; the caller keeps the raw audio and surfaces the hint.
+ */
+export declare function transcribe(audioPath: string): string;
+//# sourceMappingURL=whisper.d.ts.map

package/dist/core/whisper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whisper.d.ts","sourceRoot":"","sources":["../../src/core/whisper.ts"],"names":[],"mappings":"AAmBA;wEACwE;AACxE,qBAAa,mBAAoB,SAAQ,KAAK;;CAU7C;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBhD,yCAAyC;AACzC,wBAAgB,aAAa,IAAI,aAAa,GAAG,IAAI,CAUpD;AA0BD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAoCpD"}

package/dist/core/whisper.js

@@ -0,0 +1,124 @@
+/**
+ * Local speech-to-text for Diane. Records stay on the machine: we shell out to
+ * a locally-installed Whisper engine, never a cloud API. Audit confidentiality
+ * is the whole point of keeping this on-device.
+ *
+ * Engines, in detection order (all auto-download their model on first run):
+ *   1. openai-whisper  (`whisper` CLI, `pip install openai-whisper`)
+ *   2. faster-whisper  (python module, `pip install faster-whisper`)
+ *   3. whisper.cpp     (`whisper-cli`/`whisper-cpp`, needs HEX_WHISPER_MODEL=<model.bin>)
+ *
+ * Like src/core/notes.ts this stays node-builtins-only (child_process / fs /
+ * path / os) so the dashboard's record route can import it across the
+ * src/ <-> dashboard/ boundary without bundling CLI-only deps.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Thrown when no local Whisper engine is installed. The caller turns this into
+ *  a setup hint and preserves the raw audio so no narration is lost. */
+export class WhisperMissingError extends Error {
+    constructor() {
+        super('No local Whisper engine found. Install one (audio stays on your machine):\n' +
+            '  • pip install openai-whisper       (provides the `whisper` command)\n' +
+            '  • pip install faster-whisper       (lighter, faster on CPU)\n' +
+            '  • whisper.cpp + HEX_WHISPER_MODEL=/path/to/ggml-base.en.bin');
+        this.name = 'WhisperMissingError';
+    }
+}
+const MODEL = process.env.HEX_WHISPER_MODEL_NAME || 'base.en';
+function commandExists(bin) {
+    try {
+        execFileSync('sh', ['-c', `command -v ${bin}`], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pythonHasFasterWhisper(bin) {
+    try {
+        execFileSync(bin, ['-c', 'import faster_whisper'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Find an installed engine, or null. */
+export function detectWhisper() {
+    if (commandExists('whisper'))
+        return { kind: 'openai', bin: 'whisper' };
+    for (const py of ['python3', 'python']) {
+        if (commandExists(py) && pythonHasFasterWhisper(py))
+            return { kind: 'faster', bin: py };
+    }
+    const cppModel = process.env.HEX_WHISPER_MODEL;
+    for (const bin of ['whisper-cli', 'whisper-cpp']) {
+        if (cppModel && commandExists(bin))
+            return { kind: 'cpp', bin, model: cppModel };
+    }
+    return null;
+}
+function ensureFfmpeg() {
+    if (!commandExists('ffmpeg')) {
+        throw new Error('ffmpeg is required to convert recordings for transcription, but was not found.');
+    }
+}
+/** Convert any recording to 16 kHz mono WAV (what every engine wants). */
+function toWav(audioPath) {
+    ensureFfmpeg();
+    const wav = path.join(os.tmpdir(), `hex-narration-${path.basename(audioPath)}.wav`);
+    execFileSync('ffmpeg', ['-y', '-i', audioPath, '-ar', '16000', '-ac', '1', '-f', 'wav', wav], {
+        stdio: 'ignore',
+    });
+    return wav;
+}
+const FASTER_SCRIPT = `
+import sys
+from faster_whisper import WhisperModel
+model = WhisperModel(sys.argv[2], device="cpu", compute_type="int8")
+segments, _ = model.transcribe(sys.argv[1], language="en")
+sys.stdout.write(" ".join(s.text.strip() for s in segments).strip())
+`;
+/**
+ * Transcribe `audioPath` to plain text. Throws WhisperMissingError when no
+ * engine is installed; the caller keeps the raw audio and surfaces the hint.
+ */
+export function transcribe(audioPath) {
+    const engine = detectWhisper();
+    if (!engine)
+        throw new WhisperMissingError();
+    const wav = toWav(audioPath);
+    try {
+        if (engine.kind === 'openai') {
+            const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hex-whisper-'));
+            execFileSync(engine.bin, [wav, '--model', MODEL, '--language', 'en', '--output_format', 'txt', '--output_dir', outDir, '--task', 'transcribe'], { stdio: 'ignore' });
+            const txt = path.join(outDir, path.basename(wav).replace(/\.wav$/, '') + '.txt');
+            return (fs.readFileSync(txt, 'utf-8')).trim();
+        }
+        if (engine.kind === 'faster') {
+            const fasterModel = process.env.HEX_WHISPER_MODEL_NAME || 'base';
+            return execFileSync(engine.bin, ['-c', FASTER_SCRIPT, wav, fasterModel], {
+                encoding: 'utf-8',
+                maxBuffer: 64 * 1024 * 1024,
+            }).trim();
+        }
+        // whisper.cpp
+        const outBase = wav.replace(/\.wav$/, '');
+        execFileSync(engine.bin, ['-m', engine.model, '-f', wav, '-otxt', '-of', outBase, '-l', 'en'], {
+            stdio: 'ignore',
+        });
+        return fs.readFileSync(outBase + '.txt', 'utf-8').trim();
+    }
+    finally {
+        try {
+            fs.unlinkSync(wav);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+}
+//# sourceMappingURL=whisper.js.map

package/dist/core/whisper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whisper.js","sourceRoot":"","sources":["../../src/core/whisper.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
 import { statsCommand } from './commands/stats.js';
@@ -18,11 +19,15 @@ import { doctorCommand } from './commands/doctor.js';
 import { aiStatusCommand } from './commands/ai-status.js';
 import { updateCommand } from './commands/update.js';
 import { issueCommand } from './commands/issue.js';
+// Single source of truth for the version: package.json (always shipped at the
+// package root, one dir up from dist/index.js). Avoids drift between the npm
+// version and what `hex --version` reports.
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command();
 program
     .name('hex')
     .description('CLI toolkit for Solidity smart contract auditors')
-    .version('0.5.1');
+    .version(pkg.version);
 program.addCommand(initCommand);
 program.addCommand(statsCommand);
 program.addCommand(depsCommand);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,KAAK,CAAC;KACX,WAAW,CAAC,kDAAkD,CAAC;KAC/D,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACrC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAEjC,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,8EAA8E;AAC9E,6EAA6E;AAC7E,4CAA4C;AAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CACpB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC3C,CAAC;AAEzB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,KAAK,CAAC;KACX,WAAW,CAAC,kDAAkD,CAAC;KAC/D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAExB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACrC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAEjC,OAAO,CAAC,KAAK,EAAE,CAAC"}