hex-audit 0.5.0 → 0.5.2

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.0');
+    .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"}

package/dist/skills/diane.md

@@ -0,0 +1,99 @@
+---
+description: "Diane — your audit recorder. Ingest the latest voice narration into structured per-contract notes, route spoken triggers, and answer questions from the codebase."
+---
+
+# Skill: Diane
+
+**Recommended model:** Sonnet
+
+You are **Diane**, the auditor's recording companion — the Twin Peaks framing: the auditor is Agent Cooper, narrating their thought process aloud while reading a contract, and you are Diane, who receives the dictation, organizes it into clean notes, and assists. The auditor records narration from the dashboard **Notes** tab (Record button + contract dropdown); the recording is transcribed locally and lands as a *session*. This skill picks up that session and processes it.
+
+Persona: attentive, measured, observational. Address the auditor by name occasionally ("Got it, Cooper — logging your read of the withdraw path"). Be concise. Never sycophantic, never narrate your own process at length.
+
+## Step 1 — Pick up the latest narration
+
+```bash
+npx hex note session latest
+```
+
+This prints JSON: `{ file, contract, ts, processed, text }` for the most recent unprocessed session, or `null`. If `null`, tell the auditor there's nothing new to process and stop. Otherwise:
+
+- `contract` is the **active contract** the notes belong under (the dropdown selection). `general` means cross-cutting.
+- `text` is the raw transcript — disfluent, with filler, repetition, and false starts. That's expected.
+
+## Step 2 — Segment the transcript into thought-units
+
+Read `text` and split it into discrete thoughts. For each, classify it as a **trigger** or a **note**:
+
+- A **trigger** is an explicit instruction to you. Recognize these three (match intent, not exact words):
+  - **create a finding** — "this is a bug", "write a finding", "flag this", "log an issue".
+  - **answer a question** — "how is this encoded?", "is this reachable?", "where is X set?", "what calls this?".
+  - **search online** — "look up EIP-x", "search for the spec", "find the reference for…".
+- Everything else is a **note**: observations, hypotheses, things to revisit.
+
+When a unit is ambiguous, treat it as a note (the safe default — nothing is lost, and the auditor can re-narrate a real instruction).
+
+## Step 3 — Route the triggers
+
+**create a finding** → invoke the existing `/write-finding` skill, prefilled from the narration (the affected contract/function and the auditor's stated impact). Let that skill own duplicate-checking and the board write. After it returns, drop a one-line pointer into the contract note (`- Finding logged: <H-NNN> <title>`).
+
+**answer a question** → answer it yourself using codebase access (Read / Grep over the project scope). Be concrete and cite `file:line`. Then log the exchange into the active contract's note:
+
+```
+**Q:** <the question, cleaned up>
+**A:** <your answer, with file:line references>
+```
+
+**search online** → use WebSearch, read the most relevant result, and summarize it into the active contract's note under a short heading, with the source link. Keep it to what's relevant to the audit.
+
+## Step 4 — File everything else as structured notes
+
+Turn the remaining thought-units into clean, organized notes. **Clean up** filler, repetition, and false starts — preserve the auditor's reasoning, not their disfluency. Organize under these headings (include only the ones that apply):
+
+```
+## <ts>
+
+### Observations
+- …
+
+### Questions
+- …  (open questions the auditor raised but didn't ask you to answer)
+
+### Risks
+- …  (suspected issues not yet ready to be findings)
+
+### TODO
+- …
+```
+
+Write to the active contract's doc (cross-cutting remarks go to `general`). Use a temp file to preserve newlines, then append:
+
+```bash
+cat > /tmp/diane_<ts>.md <<'EOF'
+## <ts>
+
+### Observations
+- ...
+EOF
+npx hex note append "<contract>" --body-file /tmp/diane_<ts>.md
+```
+
+`<contract>` is the session's `contract` value verbatim (e.g. `Vault.sol`). Q&A blocks and search summaries from Step 3 can be appended in the same block under their own subheadings.
+
+## Step 5 — Close the loop
+
+Mark the session processed so it isn't ingested again:
+
+```bash
+npx hex note session mark-processed "<file>"
+```
+
+Then report a one-line summary, Diane-style: what you filed, any findings created, any questions answered. Example:
+
+> "Filed 4 observations and 2 risks on Vault.sol, answered your question about `_convertToShares` rounding (it rounds down — see Vault.sol:142), and logged finding H-007. Marked the session processed."
+
+## Notes
+
+- **Never hand-edit** `notes.json` or the `.md` files directly — always go through `npx hex note …`, exactly as the other skills route through `npx hex issue …`.
+- One session per invocation. If the auditor wants the next one, they run `/diane` again (or process them in a loop if they ask).
+- Do not create PoCs from narration — that stays an explicit, auditor-driven `/validate-issue` step.

package/dist/skills/ingest-aa-report.md

@@ -63,7 +63,7 @@ Parse the AuditAgent output (markdown with severity-tagged sections per finding)
   "tool": "auditagent",
   "title": "<finding title>",
   "severity": "Critical | High | Medium | Low | Info",
-  "description": "<full description from the report>",
+  "description": "<concise description — what it is, why it exists, the impact; trim AuditAgent's verbosity. The verbatim original stays in raw-output.md>",
   "affected_code": [
     { "file": "<path>", "snippet": "<relevant code if present>" }
   ],

package/dist/skills/sync-issues.md

@@ -30,6 +30,14 @@ All board mutations go through `hex issue` — never hand-edit `tracking.json` /
 
 **0c.** `gh repo view <repo> --json viewerPermission`. If `READ`/null, **AskUserQuestion**: "Read-only access — push will fail. Continue pull-only? (yes/no)". Track `push_enabled`.
 
+**0d. Fetch the repo's existing labels** — Hex stamps issues it creates, but **never creates a label**, so it can only use labels that already exist:
+
+```bash
+gh label list --repo <repo> --json name --jq '.[].name'
+```
+
+Keep the result as the set `EXISTING`. If the call fails or returns nothing, treat `EXISTING` as empty (issues are then created without labels rather than failing).
+
 ## Phase 1 — Pull (all issues, GitHub → local)
 
 **1a. Fetch every issue — no label filter.** Audit repos contain only audit findings, so pull them all:
@@ -108,12 +116,24 @@ Skip if `push_enabled` is false.
 
 Candidates: findings whose tracking status is in `settings.github.publish_status` (default `["verified"]`) **and** which have no `github.issue_number` yet, **and** which Phase 1.5 did not flag as duplicates. (Synced findings are already on GitHub; duplicates/rejected/unverified are never pushed.)
 
-For each candidate, render the body with the exact five-field template (see Phase 1b — `dashboard/lib/finding-markdown.ts::findingToGithubBody` is the canonical renderer). Write it to a temp file. **No labels, no footer.**
+For each candidate, render the body with the exact five-field template (see Phase 1b — `dashboard/lib/finding-markdown.ts::findingToGithubBody` is the canonical renderer). Write it to a temp file. **No body footer.**
+
+**Labels (creation only).** Stamp each newly-created issue with the standard finding labels, keeping **only those present in `EXISTING`** (Hex never creates a label):
+
+- `Draft`
+- `Finding`
+- `Severity: <Severity>` — the finding's severity verbatim (`Critical` / `High` / `Medium` / `Low` / `Info`).
+- `Status: Unresolved` — new findings start Unresolved.
+
+Drop any of these four that aren't in `EXISTING`, then pass the survivors as repeated `--label` flags:
 
 ```bash
-gh issue create --repo <repo> --title "[<Severity>] <title>" --body-file <tmp>
+gh issue create --repo <repo> --title "[<Severity>] <title>" --body-file <tmp> \
+  --label "Draft" --label "Finding" --label "Severity: <Severity>" --label "Status: Unresolved"
 ```
 
+Stamp labels **only at creation** — never edit labels on an issue that already exists, and never create a new label.
+
 Parse the returned URL for `#N`, then lock it into Synced and record the number:
 
 ```bash
@@ -151,7 +171,7 @@ GitHub sync complete (<repo>)
 
 - Authenticate (use `gh auth login`).
 - Post or read comments.
-- Apply, create, or remove labels (the repo owner manages labels).
+- Create a new label, or touch labels on issues that already exist. (Hex only stamps the fixed set — `Draft`, `Finding`, `Severity: <X>`, `Status: Unresolved`, filtered to labels already present on the repo — on issues it creates.)
 - Embed any hidden footer or marker in the issue body.
 - Delete remote issues.
 - Push `rejected`, `unverified`, `duplicate`, or already-`synced` findings.

package/dist/skills/validate-issue.md

@@ -95,6 +95,8 @@ For conformance items, the "claim" is `spec_text` + the finding paragraph — i.
 
    For a memo-only verdict, the same two commands apply (the PoC fields just stay unset). For `--description-file`, you may pass either the memo or a dedicated description file; prefer a clean description file if the memo is long.
 
+   Any description you write must be **flat prose** (plus a fenced code block only when a snippet is genuinely needed) — no markdown headings or header-like section labels (`Summary`/`Details`/`Impact`/`Affected code`); weave impact into the prose. **Keep it concise** — a single tight paragraph covering what the issue is, why it exists, and its impact, plus a 1–2 sentence hedged recommendation; trim anything that doesn't drive the point home. This matches the finding template used by the dashboard copy and the GitHub issue body. If the affected files are missing or wrong, set them with `--file` (repeatable) rather than narrating them in the description: `npx hex issue patch <id> --file src/Foo.sol [--file src/Bar.sol]`.
+
    Hex does not write `@audit-issue` comments into the client's source files — the board and finding record are the only place the issue lives.
 
 5. Use **AskUserQuestion** to ask:

package/dist/skills/write-finding.md

@@ -59,7 +59,7 @@ The `id`, `poc`, and `created_at` fields are managed by `hex issue new` (see Act
   "title": "<concise, descriptive title>",
   "severity": "Critical|High|Medium|Low|Info",
   "category": "<e.g., Math / Rounding, Access Control, Reentrancy, Oracle Manipulation>",
-  "description": "<clear, self-contained description covering what the vulnerability is, why it exists, and what the impact would be if exploited>",
+  "description": "<flat prose covering what the vulnerability is, why it exists, and its impact — no markdown headings; see Description format below>",
   "root_cause": {
     "locations": [
       { "file": "<path>", "snippet": "<relevant code>" }
@@ -84,10 +84,19 @@ Phrase recommendations as suggestions, not commands. The auditor proposes direct
 
 - Start with `Consider...`, `One option is...`, `The team may want to...`, `It would be worth...`.
 - Avoid `Replace X with Y`, `You must...`, `Always do...`, `Never do...`.
-- Keep under three sentences when possible. Detailed analysis belongs in the description.
+- Keep it to 1–2 sentences. Detailed analysis belongs in the description, not here.
 
 **Recommendation must be prose only.** No code snippets in the `recommendation` field. Code belongs in `root_cause.locations[].snippet`.
 
+### Description format (STRICT)
+
+The finding is rendered as a flat template (`## [Severity] Title`, then `**Description**:`, `**Recommendation(s)**:` …). The description goes inline after `**Description**:`, so it must read as **flat prose**:
+
+- **No markdown headings and nothing that looks like one** — no `#`/`##`/`###`, and no section labels such as `Summary`, `Details`, `Impact`, `Affected code`, whether as a heading or a bold line on its own. Weave the impact into the prose instead of giving it its own section.
+- **Code blocks are allowed when a snippet is genuinely needed** — a fenced ```` ```solidity ```` block illustrating the bug is fine. Keep it to what's relevant; follow the Code Block Formatting Rules below.
+- Affected file paths belong in `--file` (the File(s) line), not in an "Affected code" section in the description.
+- **Be concise.** Prefer a single tight paragraph: what the issue is, why it exists, and its impact — just enough to drive the point home. Don't restate the title, don't pad with background the reader doesn't need, and don't repeat the recommendation. There's no hard word count; brevity is the goal.
+
 ## Code Block Formatting Rules (STRICT)
 
 When including code snippets in the finding:
@@ -112,9 +121,10 @@ All inserted audit comments must be full sentences starting with a capital lette
 
 Persist through the `hex issue` CLI — never hand-edit `findings.json` or `tracking.json`. The CLI allocates the uniform `H-NNN` id, writes the tracking entry (`status: pending_validation`, `source: manual`), and creates the findings.json skeleton.
 
-1. **Create the issue:**
+1. **Create the issue** — pass `--file` once per affected file so the **File(s)** line is populated (repeatable). Do **not** narrate the affected files in the description instead:
    ```bash
-   npx hex issue new --source manual --title "<concise title>" --severity <Severity>
+   npx hex issue new --source manual --title "<concise title>" --severity <Severity> \
+     --file src/Foo.sol [--file src/Bar.sol]
    ```
    This prints the allocated id (e.g. `H-007`). Capture it.
 
@@ -122,7 +132,7 @@ Persist through the `hex issue` CLI — never hand-edit `findings.json` or `trac
    ```bash
    npx hex issue patch <id> --description-file /tmp/<id>_desc.md --recommendation-file /tmp/<id>_reco.md
    ```
-   The description must be self-contained (what the issue is, why it exists, the impact). The recommendation is prose only, hedged (`Consider...`), no code.
+   The description must be self-contained (what the issue is, why it exists, the impact) and follow the **Description format** rules below. The recommendation is prose only, hedged (`Consider...`), no code.
 
 There is **no source-file annotation** — Hex does not write `@audit-issue` comments into the client's `.sol` files. The board and the finding record are the single place the issue lives.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hex-audit",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "description": "CLI toolkit for Solidity smart contract auditors",
   "bin": {

package/dashboard/.next/server/chunks/557.js

@@ -1 +0,0 @@
-"use strict";exports.id=557,exports.ids=[557],exports.modules={983:(e,t,r)=>{r.d(t,{v:()=>o});var n=r(9899),s=r(5507),i=r(665),l=r(1492);function o({columns:e,data:t,title:r,defaultOpen:o=!0,rowClassName:a,onRowClick:d,expandedRow:c}){let[u,x]=(0,s.useState)(o),[f,m]=(0,s.useState)([]),[p,h]=(0,s.useState)([]),[g,b]=(0,s.useState)(null),y=(0,s.useMemo)(()=>e.map(e=>({id:e.id,accessorKey:e.accessorKey,header:e.header,enableColumnFilter:e.enableColumnFilter??!1,filterFn:e.enableColumnFilter?"equalsString":void 0,...e.sortingFn?{sortingFn:e.sortingFn}:{},cell:e.cell?({row:t})=>e.cell(t.original):({getValue:e})=>n.jsx("span",{className:"text-text-primary",children:String(e()??"")})})),[e]),v=(0,i.b7)({data:t,columns:y,state:{sorting:f,columnFilters:p},onSortingChange:m,onColumnFiltersChange:h,getCoreRowModel:(0,l.sC)(),getFilteredRowModel:(0,l.vL)(),getSortedRowModel:(0,l.tj)()}),j=(0,s.useMemo)(()=>{let r={};for(let n of e){if(!n.enableColumnFilter)continue;let e=new Set;for(let r of t){let t=r[n.accessorKey];null!=t&&e.add(String(t))}let s=[...e];if(n.filterOrder){let e=n.filterOrder;s.sort((t,r)=>{let n=e.indexOf(t),s=e.indexOf(r);return(-1===n?999:n)-(-1===s?999:s)})}else s.sort();r[n.id]=s}return r},[e,t]),S=e.filter(e=>e.enableColumnFilter);return(0,n.jsxs)("div",{className:"overflow-hidden border border-border-default",style:{borderRadius:"var(--radius-sm)"},children:[r&&(0,n.jsxs)("button",{type:"button",onClick:()=>x(!u),"aria-expanded":u,className:"flex w-full items-center justify-between bg-surface-2 px-sp-4 py-sp-3 text-left hover:bg-surface-3",children:[(0,n.jsxs)("span",{className:"text-heading font-medium text-text-primary",children:[r," (",t.length,")"]}),n.jsx("svg",{className:`h-4 w-4 text-text-tertiary ${u?"rotate-180":""}`,"aria-hidden":"true",fill:"none",viewBox:"0 0 24 24",stroke:"currentColor",strokeWidth:2,children:n.jsx("path",{strokeLinecap:"round",strokeLinejoin:"round",d:"m19 9-7 7-7-7"})})]}),u&&(0,n.jsxs)(n.Fragment,{children:[S.length>0&&n.jsx("div",{className:"flex flex-wrap gap-2 border-b border-border-subtle bg-surface-1 px-sp-4 py-sp-2",children:S.map(e=>{let r=p.find(t=>t.id===e.id);return(0,n.jsxs)("div",{className:"flex flex-wrap gap-1",children:[(0,n.jsxs)("button",{type:"button",onClick:()=>h(t=>t.filter(t=>t.id!==e.id)),"aria-pressed":!r?.value,className:`rounded-md px-3 py-1.5 text-caption font-medium focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent ${r?.value?"bg-surface-3 text-text-secondary hover:text-text-primary":"bg-accent text-surface-0"}`,children:["All ",e.header]}),(j[e.id]??[]).map(s=>{let i=t.filter(t=>String(t[e.accessorKey])===s).length,l=r?.value===s;return(0,n.jsxs)("button",{type:"button",onClick:()=>h(t=>{let r=t.filter(t=>t.id!==e.id);return l?r:[...r,{id:e.id,value:s}]}),"aria-pressed":l,className:`rounded-md px-3 py-1.5 text-caption font-medium focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent ${l?"bg-accent text-surface-0":"bg-surface-3 text-text-secondary hover:text-text-primary"}`,children:[s,n.jsx("span",{className:"ml-1 opacity-60",children:i})]},s)})]},e.id)})}),n.jsx("div",{className:"overflow-x-auto",children:(0,n.jsxs)("table",{className:"w-full text-left text-body",children:[n.jsx("thead",{className:"border-b border-border-default bg-surface-2 text-caption font-medium uppercase tracking-wider text-text-tertiary",children:n.jsx("tr",{children:v.getHeaderGroups().map(e=>e.headers.map(e=>n.jsx("th",{scope:"col","aria-sort":"asc"===e.column.getIsSorted()?"ascending":"desc"===e.column.getIsSorted()?"descending":void 0,className:"cursor-pointer select-none px-sp-4 py-sp-2 hover:text-text-secondary",onClick:e.column.getToggleSortingHandler(),children:(0,n.jsxs)("div",{className:"flex items-center gap-1",children:[(0,i.ie)(e.column.columnDef.header,e.getContext()),"asc"===e.column.getIsSorted()&&n.jsx("svg",{className:"h-3 w-3","aria-hidden":"true",viewBox:"0 0 12 12",fill:"currentColor",children:n.jsx("path",{d:"M6 2l4 5H2z"})}),"desc"===e.column.getIsSorted()&&n.jsx("svg",{className:"h-3 w-3","aria-hidden":"true",viewBox:"0 0 12 12",fill:"currentColor",children:n.jsx("path",{d:"M6 10l4-5H2z"})})]})},e.id)))})}),n.jsx("tbody",{className:"divide-y divide-border-subtle",children:v.getRowModel().rows.map(t=>{let r=t.original,l=r.id?String(r.id):t.id,o=g===l,u=!!d||!!c;return(0,n.jsxs)(s.Fragment,{children:[n.jsx("tr",{className:`${a?a(r):"bg-surface-1 hover:bg-surface-3"} ${u?"cursor-pointer":""}`,role:u?"button":void 0,tabIndex:u?0:void 0,"aria-expanded":c?o:void 0,onClick:()=>{c&&b(o?null:l),d?.(r)},onKeyDown:u?e=>{("Enter"===e.key||" "===e.key)&&(e.preventDefault(),c&&b(o?null:l),d?.(r))}:void 0,children:t.getVisibleCells().map(e=>n.jsx("td",{className:"h-9 px-sp-4 py-sp-2",children:(0,i.ie)(e.column.columnDef.cell,e.getContext())},e.id))}),c&&o&&n.jsx("tr",{children:n.jsx("td",{colSpan:e.length,className:"bg-surface-0 px-sp-5 py-sp-4",children:c(r)})})]},t.id)})})]})})]})]})}},446:(e,t,r)=>{r.d(t,{v:()=>s});var n=r(5023);function s({command:e}){return(0,n.jsxs)("div",{className:"flex flex-col items-center justify-center border border-dashed border-border-default bg-surface-1 px-sp-5 py-sp-8 text-center",style:{borderRadius:"var(--radius-sm)"},children:[n.jsx("svg",{className:"mb-4 h-12 w-12 text-text-tertiary",fill:"none",viewBox:"0 0 24 24",stroke:"currentColor",strokeWidth:1.5,children:n.jsx("path",{strokeLinecap:"round",strokeLinejoin:"round",d:"M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m6.75 12H9.75m3 0H9.75m0 0v3m-3-6h1.5m-1.5 0v3m6-6h.008v.008H15V9.75Z"})}),n.jsx("h3",{className:"mb-2 text-heading font-medium text-text-primary",children:"Data not yet generated"}),n.jsx("p",{className:"mb-4 text-body text-text-secondary",children:"Run the following command to generate this data:"}),n.jsx("code",{className:"border border-border-default bg-surface-0 px-sp-4 py-sp-2 font-mono text-body text-accent",style:{borderRadius:"var(--radius-sm)"},children:e})]})}},1760:(e,t,r)=>{r.d(t,{J1:()=>f,V9:()=>m,ZN:()=>x,au:()=>c,gn:()=>a,ki:()=>u,ws:()=>d});var n=r(7561),s=r.n(n),i=r(9411),l=r.n(i);function o(){let e=process.cwd();try{let t=l().join(e,".hex","config.json");if(s().existsSync(t))return l().join(e,".hex");let r=l().join(e,".solaudit","config.json");if(s().existsSync(r))return l().join(e,".solaudit")}catch{}return l().join(e,".hex")}function a(e){try{let t=l().join(o(),e),r=s().readFileSync(t,"utf-8");return JSON.parse(r)}catch{return null}}function d(e){try{let t=l().join(o(),e);return s().readFileSync(t,"utf-8")}catch{return null}}function c(e,t){let r=l().join(o(),e);s().writeFileSync(r,JSON.stringify(t,null,2),"utf-8")}function u(e){try{let t=l().join(o(),e);return s().existsSync(t)}catch{return!1}}function x(){return o()}function f(e){try{let t=l().join(o(),e);if(!s().existsSync(t))return[];return s().readdirSync(t,{withFileTypes:!0}).filter(e=>e.isDirectory()).map(e=>e.name)}catch{return[]}}function m(e){try{let t=l().join(o(),e),r=s().readFileSync(t,"utf-8");return JSON.parse(r)}catch{return null}}},2950:(e,t,r)=>{r.r(t),r.d(t,{default:()=>s});var n=r(1645);let s=e=>[{type:"image/svg+xml",sizes:"any",url:(0,n.fillMetadataSegment)(".",e.params,"icon.svg")+"?83fa4bf1ef0d214d"}]}};