@prism-d1/cli 1.1.2 → 1.2.0

package/dist/src/dashboard/server.js

@@ -0,0 +1,163 @@
+/**
+ * Loopback-only HTTP server for `prism-cli dashboard`.
+ *
+ * Access control, all enforced on every request:
+ *   - bound to 127.0.0.1 only (the host is a constant, not an option);
+ *   - a per-run 256-bit random token, accepted once from `/?token=` and
+ *     exchanged for an HttpOnly, SameSite=Strict cookie, then required as that
+ *     cookie on every request (compared in constant time);
+ *   - the Host header must be 127.0.0.1:<port> or localhost:<port>, which
+ *     defeats DNS rebinding (a rebound name arrives with its own Host);
+ *   - GET only, read-only routes, no CORS headers, strict CSP.
+ *
+ * Why a minted token and not a platform auth mechanism: the server is
+ * reachable only from this machine, the audience is the developer running it,
+ * and the CLI ships as public sample code, so it uses the loopback-plus-token
+ * pattern native to local developer tools (Jupyter, VS Code server) rather
+ * than any hosted identity provider. It must never be bound beyond loopback.
+ */
+import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { renderPage } from './page.js';
+import { renderReportHtml, renderReportMarkdown } from './report.js';
+export const BIND_HOST = '127.0.0.1';
+export function newToken() {
+    return randomBytes(32).toString('base64url');
+}
+export function cookieName(port) {
+    // Cookies are scoped by host, not port: two dashboards on different ports
+    // would otherwise overwrite each other's cookie.
+    return `prism_dash_${port}`;
+}
+function safeEqual(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+function readCookie(req, name) {
+    const raw = req.headers.cookie;
+    if (!raw)
+        return null;
+    for (const part of raw.split(';')) {
+        const i = part.indexOf('=');
+        if (i > 0 && part.slice(0, i).trim() === name)
+            return part.slice(i + 1).trim();
+    }
+    return null;
+}
+function baseHeaders(nonce) {
+    const csp = nonce
+        ? `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`
+        : "default-src 'none'; frame-ancestors 'none'";
+    return {
+        'Content-Security-Policy': csp,
+        'X-Content-Type-Options': 'nosniff',
+        'X-Frame-Options': 'DENY',
+        'Referrer-Policy': 'no-referrer',
+        'Cache-Control': 'no-store',
+        'Cross-Origin-Resource-Policy': 'same-origin',
+    };
+}
+function send(res, status, type, body, extra = {}, nonce) {
+    res.writeHead(status, { ...baseHeaders(nonce), 'Content-Type': type, ...extra });
+    res.end(body);
+}
+/** /report/<id> or /report/<id>.md; anything else (slashes, dots, %-escapes) does not match. */
+const REPORT_ROUTE = /^\/report\/([A-Za-z0-9_-]{1,120})(\.md)?$/;
+export function createHandler(opts) {
+    return async (req, res) => {
+        try {
+            const port = opts.getPort();
+            const host = String(req.headers.host || '').toLowerCase();
+            if (host !== `${BIND_HOST}:${port}` && host !== `localhost:${port}`) {
+                return send(res, 403, 'text/plain; charset=utf-8', 'Forbidden: unexpected Host header\n');
+            }
+            if (req.method !== 'GET') {
+                return send(res, 405, 'text/plain; charset=utf-8', 'Method Not Allowed\n', { Allow: 'GET' });
+            }
+            const url = new URL(req.url || '/', `http://${BIND_HOST}:${port}`);
+            const name = cookieName(port);
+            const cookie = readCookie(req, name);
+            const cookieOk = cookie !== null && safeEqual(cookie, opts.token);
+            // First load: exchange the URL token for the cookie, then drop it from the URL.
+            const qToken = url.searchParams.get('token');
+            if (url.pathname === '/' && qToken !== null) {
+                if (!safeEqual(qToken, opts.token))
+                    return send(res, 401, 'text/plain; charset=utf-8', 'Unauthorized\n');
+                return send(res, 303, 'text/plain; charset=utf-8', 'See Other\n', {
+                    Location: '/',
+                    'Set-Cookie': `${name}=${opts.token}; HttpOnly; SameSite=Strict; Path=/`,
+                });
+            }
+            if (!cookieOk) {
+                return send(res, 401, 'text/plain; charset=utf-8', 'Unauthorized: open the URL printed by prism-cli dashboard\n');
+            }
+            if (url.pathname === '/') {
+                const nonce = randomBytes(16).toString('base64');
+                return send(res, 200, 'text/html; charset=utf-8', renderPage(nonce), {}, nonce);
+            }
+            if (url.pathname === '/api/data') {
+                const payload = await opts.getPayload();
+                return send(res, 200, 'application/json; charset=utf-8', JSON.stringify(payload));
+            }
+            const m = REPORT_ROUTE.exec(url.pathname);
+            if (m && opts.getReport) {
+                const report = await opts.getReport(m[1]);
+                if (!report)
+                    return send(res, 404, 'text/plain; charset=utf-8', 'Report not found\n');
+                if (m[2]) {
+                    return send(res, 200, 'text/markdown; charset=utf-8', renderReportMarkdown(report), {
+                        'Content-Disposition': `attachment; filename="codewatch-report-${m[1]}.md"`,
+                    });
+                }
+                const nonce = randomBytes(16).toString('base64');
+                return send(res, 200, 'text/html; charset=utf-8', renderReportHtml(report, { nonce, links: { back: '/', markdown: `/report/${m[1]}.md` } }), {}, nonce);
+            }
+            return send(res, 404, 'text/plain; charset=utf-8', 'Not Found\n');
+        }
+        catch (e) {
+            if (!res.headersSent)
+                send(res, 500, 'text/plain; charset=utf-8', 'Internal Server Error\n');
+            else
+                res.end();
+            process.stderr.write(`prism dashboard: request failed: ${e?.message || e}\n`);
+        }
+    };
+}
+/** Starts the server on 127.0.0.1. `port` 0 (default) picks a free port. */
+export function startServer(opts) {
+    const token = opts.token || newToken();
+    let port = 0;
+    const server = createServer(createHandler({ token, getPort: () => port, getPayload: opts.getPayload, getReport: opts.getReport }));
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port ?? 0, BIND_HOST, () => {
+            const addr = server.address();
+            if (!addr || typeof addr === 'string' || addr.address !== BIND_HOST) {
+                server.close();
+                return reject(new Error(`refusing to serve: bound to ${JSON.stringify(addr)}, expected ${BIND_HOST}`));
+            }
+            port = addr.port;
+            resolve({
+                server, port, token,
+                url: `http://${BIND_HOST}:${port}/?token=${token}`,
+                close: () => new Promise((r) => server.close(() => r())),
+            });
+        });
+    });
+}
+/** Memoises the payload for `ttlMs` and shares one in-flight build between requests. */
+export function cachedPayload(build, ttlMs = 30_000) {
+    let at = 0;
+    let pending = null;
+    let value;
+    return () => {
+        if (value !== undefined && Date.now() - at < ttlMs)
+            return Promise.resolve(value);
+        if (!pending) {
+            pending = build().then((v) => { value = v; at = Date.now(); return v; }).finally(() => { pending = null; });
+        }
+        return pending;
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/src/dashboard/server.js.map

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

package/dist/src/dashboard/setup.d.ts

@@ -0,0 +1,52 @@
+import { gitleaksInstallHint } from '../codewatch/gitleaks.js';
+import { type GlobalStatus } from '../codewatch/globalHooks.js';
+export type CheckStatus = 'ok' | 'warn' | 'missing';
+export interface CheckItem {
+    id: string;
+    label: string;
+    status: CheckStatus;
+    detail: string;
+    /** One-line fix; empty when status is ok. */
+    fix: string;
+}
+export interface MachineDeps {
+    pathEnv?: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    scheduleExists?: () => boolean;
+    schedulerName?: () => string;
+    /** Global codewatch hooks state; computed once by the payload builder. */
+    global?: GlobalStatus;
+}
+export declare const GLOBAL_INSTALL_CMD = "prism-cli enable codewatch --global";
+export declare const GLOBAL_FORCE_CMD = "prism-cli enable codewatch --global --force";
+/** The machine row for the global hooks (~/.prism/hooks via git config --global core.hooksPath). */
+export declare function globalHooksCheck(g: GlobalStatus): CheckItem;
+export { gitleaksInstallHint };
+/** Checks that do not depend on a repository. */
+export declare function machineChecks(deps?: MachineDeps): CheckItem[];
+export interface CodewatchSetup {
+    /**
+     * ok: codewatch runs here (per-repo hooks, or the global hooks).
+     * warn: the global hooks are installed but this repo's own core.hooksPath bypasses them.
+     * opted-out: git config prism.codewatch false.
+     * missing: anything else (including hooks from before the rename).
+     */
+    status: 'ok' | 'warn' | 'missing' | 'opted-out';
+    /** Covered by the global hooks rather than per-repo hooks. */
+    global: boolean;
+    /** Reviewer the pre-push review would use here, or null when none is available. */
+    reviewer: string | null;
+    /** Where that choice came from: git-config, prism-config, detected, fallback or none. */
+    reviewerSource: string;
+    detail: string;
+    /** Empty when ok. */
+    fix: string;
+}
+export declare function enableCodewatchFix(repo: string): string;
+/** The only per-repo check: does codewatch run here (per repo or globally), and which reviewer would run. */
+export declare function codewatchSetup(repo: string, deps?: {
+    pathEnv?: string;
+    global?: GlobalStatus;
+}): CodewatchSetup;
+//# sourceMappingURL=setup.d.ts.map

package/dist/src/dashboard/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/dashboard/setup.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAA6E,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAK3I,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AACpD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,eAAO,MAAM,kBAAkB,wCAAwC,CAAC;AACxE,eAAO,MAAM,gBAAgB,gDAAgD,CAAC;AAE9E,oGAAoG;AACpG,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,SAAS,CAY3D;AAGD,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAM/B,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,IAAI,GAAE,WAAgB,GAAG,SAAS,EAAE,CAwCjE;AAWD,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;IAChD,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yFAAyF;IACzF,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,GAAG,EAAE,MAAM,CAAC;CACb;AAOD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAOD,6GAA6G;AAC7G,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAAG,cAAc,CA+BnH"}

package/dist/src/dashboard/setup.js

@@ -0,0 +1,129 @@
+/**
+ * Setup checklist. Local evidence only: no AWS, GitHub or GitLab calls, and no
+ * credential file is opened (only its existence is checked).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { checkTool } from '../utils/tool-check.js';
+import { lastSync, scheduleExists, schedulerName } from '../utils/otel-sync-schedule.js';
+import { HOOK_MARKER, MANAGED_HOOKS } from '../codewatch/hooks.js';
+import { gitleaksInstallHint } from '../codewatch/gitleaks.js';
+import { globalHooksDir, globalStatus, isOptedOut, OPT_OUT_KEY, repoLocalHooksPath } from '../codewatch/globalHooks.js';
+import { realpathSync } from 'node:fs';
+import { readEvalConfig, REVIEWER_GIT_CONFIG_KEY } from '../codewatch/config.js';
+import { detectReviewers, resolveReviewer } from '../codewatch/reviewers/index.js';
+export const GLOBAL_INSTALL_CMD = 'prism-cli enable codewatch --global';
+export const GLOBAL_FORCE_CMD = 'prism-cli enable codewatch --global --force';
+/** The machine row for the global hooks (~/.prism/hooks via git config --global core.hooksPath). */
+export function globalHooksCheck(g) {
+    const label = 'Codewatch global hooks';
+    switch (g.state) {
+        case 'installed':
+            return item('codewatch-global', label, 'ok', 'core.hooksPath -> ~/.prism/hooks; every repo is covered');
+        case 'elsewhere':
+            return item('codewatch-global', label, 'warn', `global core.hooksPath points to ${g.hooksPath}`, `${GLOBAL_FORCE_CMD} (its hooks still run)`);
+        case 'incomplete':
+            return item('codewatch-global', label, 'warn', 'core.hooksPath points to ~/.prism/hooks but its hooks are missing', GLOBAL_INSTALL_CMD);
+        default:
+            return item('codewatch-global', label, 'missing', 'not installed (optional: covers every repo at once)', GLOBAL_INSTALL_CMD);
+    }
+}
+// Shared with enable codewatch and the pre-commit warning so the three cannot drift.
+export { gitleaksInstallHint };
+const item = (id, label, status, detail, fix = '') => ({ id, label, status, detail, fix: status === 'ok' ? '' : fix });
+const AWS_ENV_VARS = ['AWS_PROFILE', 'AWS_ACCESS_KEY_ID', 'AWS_WEB_IDENTITY_TOKEN_FILE', 'AWS_CONTAINER_CREDENTIALS_FULL_URI', 'AWS_CONTAINER_CREDENTIALS_RELATIVE_URI'];
+/** Checks that do not depend on a repository. */
+export function machineChecks(deps = {}) {
+    const env = deps.env || process.env;
+    const home = deps.home || homedir();
+    const out = [];
+    const cb = checkTool('codeburn', { pathEnv: deps.pathEnv });
+    out.push(item('codeburn', 'codeburn installed', cb.installed ? 'ok' : 'missing', cb.installed ? (cb.version || 'version unknown') : 'not on PATH', 'npm install -g codeburn'));
+    const hasSchedule = (deps.scheduleExists || scheduleExists)();
+    const sched = (deps.schedulerName || schedulerName)();
+    const last = lastSync(home);
+    if (hasSchedule) {
+        out.push(item('codeburn-sync', 'Scheduled codeburn sync push', last ? 'ok' : 'warn', last ? `${sched} entry installed; last sync log write ${last.at}` : `${sched} entry installed; no sync log yet in ~/.prism/logs`, 'Wait for the next run, or check ~/.prism/logs/otel-sync.log'));
+    }
+    else {
+        out.push(item('codeburn-sync', 'Scheduled codeburn sync push', 'missing', `no ${sched} entry${last ? `; last sync log write ${last.at}` : ''}`, 'prism-cli bootstrapper setup-otel-sync'));
+    }
+    const gl = checkTool('gitleaks', { pathEnv: deps.pathEnv, versionArgs: ['version'] });
+    // warn, not missing: commits are still allowed, just not secret-scanned (decided).
+    out.push(item('gitleaks', 'gitleaks available', gl.installed ? 'ok' : 'warn', gl.installed ? (gl.version || 'version unknown') : 'not on PATH; secret scanning is off and commits are not scanned', gitleaksInstallHint()));
+    // Presence only. STS is never called and no credential or config file is read.
+    const envVar = AWS_ENV_VARS.find((k) => env[k]);
+    const configFile = env.AWS_CONFIG_FILE || join(home, '.aws', 'config');
+    const credsFile = env.AWS_SHARED_CREDENTIALS_FILE || join(home, '.aws', 'credentials');
+    const files = [configFile, credsFile].filter((f) => existsSync(f));
+    const awsOk = Boolean(envVar) || files.length > 0;
+    out.push(item('aws-credentials', 'AWS credentials configured', awsOk ? 'ok' : 'missing', envVar ? `${envVar} is set${envVar === 'AWS_PROFILE' ? ` (${env.AWS_PROFILE})` : ''} (not validated)`
+        : files.length ? `AWS config present (${files.length === 2 ? 'config and credentials files' : 'one file'}; not validated)`
+            : 'no AWS env var or ~/.aws config found', "aws configure (or aws sso login); then validate with 'aws sts get-caller-identity'"));
+    out.push(globalHooksCheck(deps.global || globalStatus(home)));
+    return out;
+}
+function git(repo, args) {
+    const r = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return r.status === 0 ? r.stdout.trim() : null;
+}
+function readText(p) {
+    try {
+        return readFileSync(p, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Shell-quotes a path for the copy-paste fix line. */
+function shellPath(p) {
+    return /^[A-Za-z0-9_./~+-]+$/.test(p) ? p : `'${p.replace(/'/g, `'\\''`)}'`;
+}
+export function enableCodewatchFix(repo) {
+    return `cd ${shellPath(repo)} && prism-cli enable codewatch`;
+}
+function samePath(a, b) {
+    const n = (p) => { try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    } };
+    return n(a) === n(b);
+}
+/** The only per-repo check: does codewatch run here (per repo or globally), and which reviewer would run. */
+export function codewatchSetup(repo, deps = {}) {
+    const g = deps.global || globalStatus();
+    const hooksDir = git(repo, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']) || resolve(repo, '.git/hooks');
+    const viaGlobal = g.state === 'installed' && samePath(hooksDir, globalHooksDir());
+    const state = MANAGED_HOOKS.map((h) => {
+        const t = readText(resolve(hooksDir, h));
+        return { h, ours: !!t && t.includes(HOOK_MARKER), old: !!t && !t.includes(HOOK_MARKER) && t.includes('# prism-cli enable security') };
+    });
+    const choice = resolveReviewer({
+        gitConfigValue: git(repo, ['config', '--get', REVIEWER_GIT_CONFIG_KEY]),
+        prismConfigValue: readEvalConfig(repo).reviewer,
+        available: detectReviewers(deps.pathEnv),
+    });
+    const reviewer = choice.id;
+    const base = { reviewer, reviewerSource: choice.source, global: viaGlobal };
+    if (isOptedOut(repo)) {
+        return { ...base, status: 'opted-out', fix: '', detail: `opted out (git config ${OPT_OUT_KEY} false)` };
+    }
+    if (state.every((x) => x.ours)) {
+        const where = viaGlobal ? 'covered by the global hooks (global)' : 'pre-commit and pre-push installed';
+        return { ...base, status: 'ok', fix: '', detail: reviewer ? where : `${where}; no reviewer on PATH (install kiro-cli or Claude Code)` };
+    }
+    const local = repoLocalHooksPath(repo);
+    if (local && g.state === 'installed') {
+        return { ...base, status: 'warn', fix: enableCodewatchFix(repo),
+            detail: `this repo's core.hooksPath (${local}) bypasses the global hooks; install codewatch into it` };
+    }
+    const have = state.filter((x) => x.ours).map((x) => x.h);
+    const detail = state.some((x) => x.old) ? 'hooks from before the codewatch rename'
+        : have.length ? `only ${have.join(', ')} installed` : 'not installed';
+    return { ...base, status: 'missing', detail, fix: enableCodewatchFix(repo) };
+}
+//# sourceMappingURL=setup.js.map

package/dist/src/dashboard/setup.js.map

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

package/dist/src/dashboard/usage.d.ts

@@ -0,0 +1,43 @@
+export declare const TOP_N = 5;
+export interface Totals {
+    cost: number;
+    calls: number;
+    sessions: number;
+}
+export interface UsagePanel {
+    status: 'ok' | 'not-installed' | 'no-data' | 'error';
+    message: string | null;
+    currency: string;
+    today: Totals | null;
+    month: (Totals & {
+        from: string;
+        to: string;
+    }) | null;
+    topModels: {
+        name: string;
+        cost: number;
+        calls: number;
+    }[];
+    /** `name` is the folder name; `path` is codeburn's full project path, for a tooltip. */
+    topProjects: {
+        name: string;
+        path: string;
+        cost: number;
+        sessions: number;
+    }[];
+    generated: string | null;
+    /** Shown as a note, never a link: codeburn web is a CLI command. */
+    fullView: string;
+}
+/** Runs `codeburn export -f json` with extra args and returns the parsed JSON. Injected in tests. */
+export type CodeburnExport = (args: string[]) => Promise<any>;
+export declare function realCodeburnExport(binary: string): CodeburnExport;
+/** Local calendar date, YYYY-MM-DD. */
+export declare function localDate(d: Date): string;
+export declare function emptyUsage(status: UsagePanel['status'], message: string): UsagePanel;
+export declare function collectUsage(opts?: {
+    now?: Date;
+    exporter?: CodeburnExport;
+    pathEnv?: string;
+}): Promise<UsagePanel>;
+//# sourceMappingURL=usage.d.ts.map

package/dist/src/dashboard/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/dashboard/usage.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,KAAK,IAAI,CAAC;AAGvB,MAAM,WAAW,MAAM;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AACzE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,IAAI,GAAG,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACtD,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3D,wFAAwF;IACxF,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qGAAqG;AACrG,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE9D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAWjE;AAQD,uCAAuC;AACvC,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAGzC;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAEpF;AAED,wBAAsB,YAAY,CAAC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CA4C9H"}

package/dist/src/dashboard/usage.js

@@ -0,0 +1,88 @@
+/**
+ * Usage panel data, from `codeburn export -f json` (schema codeburn.export.v2,
+ * checked against codeburn 0.9.24).
+ *
+ * Two exports: the default one for "Today", and a `--from <1st of month>
+ * --to <today>` one for this calendar month and its top models and projects.
+ * codeburn's own charts are not rebuilt; the panel points at `codeburn web`.
+ */
+import { execFile } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import { findOnPath } from '../utils/tool-check.js';
+const execFileP = promisify(execFile);
+export const TOP_N = 5;
+const EXPORT_TIMEOUT_MS = 60_000;
+export function realCodeburnExport(binary) {
+    return async (args) => {
+        const dir = mkdtempSync(join(tmpdir(), 'prism-dash-cb-'));
+        try {
+            const out = join(dir, 'export.json');
+            await execFileP(binary, ['export', '-f', 'json', '-o', out, ...args], { timeout: EXPORT_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 });
+            return JSON.parse(readFileSync(out, 'utf8'));
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    };
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+function totalsFrom(row) {
+    return { cost: num(row?.['Cost (USD)']), calls: num(row?.['API Calls']), sessions: num(row?.['Sessions']) };
+}
+/** Local calendar date, YYYY-MM-DD. */
+export function localDate(d) {
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+export function emptyUsage(status, message) {
+    return { status, message, currency: 'USD', today: null, month: null, topModels: [], topProjects: [], generated: null, fullView: 'codeburn web' };
+}
+export async function collectUsage(opts = {}) {
+    let exporter = opts.exporter;
+    if (!exporter) {
+        const bin = findOnPath('codeburn', opts.pathEnv);
+        if (!bin)
+            return emptyUsage('not-installed', 'codeburn is not installed. Install it with: npm install -g codeburn');
+        exporter = realCodeburnExport(bin);
+    }
+    const now = opts.now || new Date();
+    const to = localDate(now);
+    const from = `${to.slice(0, 8)}01`;
+    let base, month;
+    try {
+        [base, month] = await Promise.all([exporter([]), exporter(['--from', from, '--to', to])]);
+    }
+    catch (e) {
+        return emptyUsage('error', `codeburn export failed: ${String(e?.message || e).split('\n')[0].slice(0, 200)}`);
+    }
+    if (!String(base?.schema || '').startsWith('codeburn.export.')) {
+        return emptyUsage('error', `unrecognised codeburn export schema: ${String(base?.schema).slice(0, 40)}`);
+    }
+    const todayRow = (Array.isArray(base.summary) ? base.summary : []).find((r) => r?.Period === 'Today');
+    const monthRow = Array.isArray(month?.summary) ? month.summary[0] : null;
+    const monthModels = Array.isArray(month?.periods?.[0]?.models) ? month.periods[0].models : [];
+    const monthProjects = Array.isArray(month?.projects) ? month.projects : [];
+    const panel = {
+        status: 'ok',
+        message: null,
+        currency: String(base?.currency?.code || 'USD'),
+        today: todayRow ? totalsFrom(todayRow) : { cost: 0, calls: 0, sessions: 0 },
+        month: monthRow ? { ...totalsFrom(monthRow), from, to } : { cost: 0, calls: 0, sessions: 0, from, to },
+        topModels: monthModels
+            .map((m) => ({ name: String(m?.Model || 'unknown'), cost: num(m?.['Cost (USD)']), calls: num(m?.['API Calls']) }))
+            .sort((a, b) => b.cost - a.cost).slice(0, TOP_N),
+        topProjects: monthProjects
+            .map((p) => { const path = String(p?.Project || 'unknown'); return { name: basename(path.replace(/[\\/]+$/, '')) || path, path, cost: num(p?.['Cost (USD)']), sessions: num(p?.Sessions) }; })
+            .sort((a, b) => b.cost - a.cost).slice(0, TOP_N),
+        generated: typeof base?.generated === 'string' ? base.generated : null,
+        fullView: 'codeburn web',
+    };
+    if (panel.today.calls === 0 && panel.month.calls === 0) {
+        return { ...panel, status: 'no-data', message: 'codeburn found no usage this month.' };
+    }
+    return panel;
+}
+//# sourceMappingURL=usage.js.map

package/dist/src/dashboard/usage.js.map

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

package/dist/src/index.d.ts

@@ -3,6 +3,7 @@
  *
  * Structure:
  *   commands/
+ *     _top/<name>.js       → becomes `prism-cli <name>` (top-level command)
  *     <category>/          → becomes `prism-cli <category>`
  *       <command>.js       → becomes `prism-cli <category> <command>`
  *

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA0DA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,GAAG,iBAMlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,GAAG,iBAOlD"}

package/dist/src/index.js

@@ -3,6 +3,8 @@ import { resolve, dirname, basename } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const commandsDir = resolve(__dirname, 'commands');
+/** Files here register as top-level commands (`prism-cli <name>`), not as a group. */
+const TOP_LEVEL_DIR = '_top';
 function attach(program, category, command, def) {
     // Reuse an existing category command if it was already created
     let categoryCmd = program.commands.find((c) => c.name() === category);
@@ -15,6 +17,33 @@ function attach(program, category, command, def) {
     }
     sub.action((opts) => def.action(opts));
 }
+function attachTop(program, name, def) {
+    if (program.commands.find((c) => c.name() === name))
+        return;
+    const cmd = program.command(name).description(def.description || name);
+    if (def.options) {
+        for (const opt of def.options)
+            cmd.option(opt.flags, opt.description, opt.default);
+    }
+    cmd.action((opts) => def.action(opts));
+}
+function findModule(dir, name) {
+    for (const candidate of [`${name}.js`, `${name}.ts`]) {
+        const p = resolve(dir, candidate);
+        if (existsSync(p))
+            return p;
+    }
+    return '';
+}
+/** Fast path for a top-level command (`prism-cli dashboard --json`). */
+async function registerTop(program, name) {
+    const file = findModule(resolve(commandsDir, TOP_LEVEL_DIR), name);
+    if (!file)
+        return false;
+    const mod = await import(pathToFileURL(file).href);
+    attachTop(program, name, mod.default || mod);
+    return true;
+}
 /**
  * Fast path: import and register ONLY the `<category> <command>` module being
  * invoked. Returns false if the module can't be found (so we can fall back).
@@ -41,8 +70,15 @@ async function registerOne(program, category, command) {
 /** Full registration — imports every command module. Used for --help and unmatched invocations. */
 async function registerAll(program) {
     const categories = readdirSync(commandsDir).filter((entry) => {
-        return statSync(resolve(commandsDir, entry)).isDirectory();
+        return entry !== TOP_LEVEL_DIR && statSync(resolve(commandsDir, entry)).isDirectory();
     });
+    const topDir = resolve(commandsDir, TOP_LEVEL_DIR);
+    if (existsSync(topDir)) {
+        for (const file of readdirSync(topDir).filter((f) => f.endsWith('.js') && !f.endsWith('.d.ts'))) {
+            const mod = await import(pathToFileURL(resolve(topDir, file)).href);
+            attachTop(program, basename(file, '.js'), mod.default || mod);
+        }
+    }
     for (const category of categories) {
         const categoryDir = resolve(commandsDir, category);
         const files = readdirSync(categoryDir).filter((f) => f.endsWith('.js') && !f.endsWith('.d.ts'));
@@ -59,6 +95,7 @@ async function registerAll(program) {
  *
  * Structure:
  *   commands/
+ *     _top/<name>.js       → becomes `prism-cli <name>` (top-level command)
  *     <category>/          → becomes `prism-cli <category>`
  *       <command>.js       → becomes `prism-cli <category> <command>`
  *
@@ -73,6 +110,8 @@ async function registerAll(program) {
  */
 export async function registerCommands(program) {
     const [category, command] = process.argv.slice(2);
+    if (category && !category.startsWith('-') && (await registerTop(program, category)))
+        return;
     if (category && command && !category.startsWith('-') && !command.startsWith('-')) {
         if (await registerOne(program, category, command))
             return;