@seanmars/tospec 0.14.0 → 0.14.2

package/dist/commands/metrics.d.ts

@@ -0,0 +1,145 @@
+/**
+ * `tospec skill-metrics` — how long each skill actually takes, as a served web
+ * page.
+ *
+ * Read-only, and derived from two independent sources: Claude Code
+ * transcripts (core/skill-metrics.ts) and Codex sessions
+ * (core/codex-metrics.ts). Nothing is written, so the command is safe to run
+ * at any point in a workflow.
+ *
+ * The two sources carry different confidence — Claude Code's attribution is
+ * read directly, Codex's is inferred by a heuristic — and are therefore never
+ * summed into one figure anywhere in the report; every row, chart, and
+ * statistic carries a `source` and the two stay distinguishable throughout
+ * (design.md D4 in the codex-metrics change).
+ *
+ * The page is the only output: seven columns of minutes per skill had to be
+ * compared by reading digits, and a median/max pair discarded the very
+ * distribution it summarised. See
+ * tospec/decisions/20260730_205609-metrics-web-only-output.md.
+ *
+ * The server is deliberately short-lived and unmanaged. It binds a fixed base
+ * port and advances on collision, so the URL is predictable enough to keep in
+ * your head or bookmark while a second run still starts rather than failing.
+ * None of the dashboard's registry, pid-file, or `--stop` machinery applies to
+ * something you open, read, and close: the walk-up is the whole collision story.
+ */
+import * as http from 'node:http';
+import { Command } from 'commander';
+import { type DurationStats, type MetricsSource, type MetricsThresholds, type SkillAggregate, type SkillRun, type TranscriptDirOptions, type TranscriptEntry } from '../core/skill-metrics.js';
+import { type CodexSessionScan, type CodexSessionsDirOptions } from '../core/codex-metrics.js';
+export interface MetricsOptions {
+    /** False only when `--no-open` was passed; commander defaults it to true. */
+    open?: boolean;
+}
+export interface MetricsServerOptions extends TranscriptDirOptions, CodexSessionsDirOptions {
+    port?: number;
+    host?: string;
+}
+interface ParsedSession {
+    session: string;
+    entries: TranscriptEntry[];
+}
+interface TranscriptCache {
+    transcriptDir: string;
+    /** False when the directory does not exist — no Claude Code history here. */
+    available: boolean;
+    /** Transcript files found, whether or not any carried skill attribution. */
+    sessions: number;
+    parsed: ParsedSession[];
+}
+export interface ReportQuery {
+    thresholds: MetricsThresholds;
+    /** Drop runs that ended before this instant. */
+    sinceMs?: number;
+}
+/**
+ * `DurationStats` carries median/max/total but no minimum, because the table it
+ * was written for never showed one. The distribution chart draws a range, so the
+ * minimum is added here rather than in the frontend — a minimum is a statistic,
+ * and the frontend holds none.
+ */
+export interface RangeStats extends DurationStats {
+    minMs: number;
+}
+export interface SkillReport extends Omit<SkillAggregate, 'span' | 'engaged'> {
+    span: RangeStats;
+    engaged: RangeStats;
+}
+/**
+ * Per-source availability, kept as two separate objects rather than one
+ * combined figure — the two sources are scanned independently, and one having
+ * history says nothing about the other (codex-metrics-source spec, "A project
+ * with no matching Codex sessions...").
+ */
+export interface MetricsSources {
+    claudeCode: MetricsSource;
+    codex: MetricsSource;
+}
+export interface MetricsReport {
+    sources: MetricsSources;
+    thresholds: MetricsThresholds;
+    /** One row per skill-and-source pair; the two are never summed together. */
+    skills: SkillReport[];
+    runs: SkillRun[];
+    series: TimeSeries;
+}
+export type Granularity = 'day' | 'week' | 'month';
+export interface TimeBucket {
+    /** Local period key: `yyyy-mm-dd` for a day or a week's Monday, `yyyy-mm` for a month. */
+    key: string;
+    /**
+     * Engaged ms per skill-and-source row (`skillRowKey`), never summed across
+     * sources. Rows with nothing in this bucket are absent.
+     */
+    byRow: Record<string, number>;
+}
+export interface TimeSeries {
+    granularity: Granularity;
+    buckets: TimeBucket[];
+}
+/**
+ * Engaged time per period per skill, in local calendar time.
+ *
+ * Each run is counted whole on the local date it *started*, so a run crossing
+ * midnight is not divided — "one run is one entity" is what the distribution and
+ * timeline charts also assume. Bucketing by UTC would misplace any run starting
+ * before the local day's UTC offset, which for a positive offset is every early
+ * morning.
+ *
+ * Periods with no runs are included as empty buckets: with most days empty in a
+ * typical history, dropping them would make three consecutive days and three
+ * days a week apart look identical, which is the pattern this series exists to
+ * show.
+ */
+export declare function buildTimeSeries(runs: SkillRun[]): TimeSeries;
+/**
+ * Pure: turns both sources' parsed caches plus a query into the report the
+ * page renders. Claude Code and Codex runs are built, filtered, and reported
+ * independently at every step — merged only into one sorted `runs` list and
+ * one `skills` list, which `aggregateRuns` already keeps apart by
+ * `(skill, source)` (design.md D4: never summed).
+ */
+export declare function reportFrom(claudeCache: TranscriptCache, codexCache: CodexSessionScan, query: ReportQuery): MetricsReport;
+/**
+ * Starts the metrics server. Side-effect free — no logging, no browser, no
+ * signal handlers — so tests can drive it directly.
+ *
+ * Binds `DEFAULT_PORT` and advances on collision, so two metrics runs — or a
+ * metrics run beside anything else already holding the port — both start.
+ * Tests pass `port: 0` to stay out of the fixed range entirely.
+ */
+export declare function startMetricsServer(projectRoot: string, opts?: MetricsServerOptions): Promise<{
+    server: http.Server;
+    url: string;
+    port: number;
+}>;
+/**
+ * CLI entry: start the server, print the URL, open a browser, and stay up until
+ * terminated. No signal handler — there is no registry entry, pid file, or temp
+ * file to clean up, so the default SIGINT behaviour is already correct.
+ */
+export declare function runMetrics(projectRoot: string, opts?: MetricsOptions): Promise<http.Server>;
+export declare function registerMetricsCommand(program: Command): void;
+export {};
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/commands/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAGlC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,aAAa,EAElB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC7B,MAAM,0BAA0B,CAAC;AAelC,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB,EAAE,uBAAuB;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAqBD,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,UAAU,eAAe;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAiCD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3E,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,4EAA4E;IAC5E,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;CACpB;AAUD,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAqDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,UAAU,CAmC5D;AAoDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,eAAe,EAC5B,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,WAAW,GACjB,aAAa,CA0Cf;AAyGD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC;IAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAiB7D;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAStB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmB7D"}

package/dist/commands/metrics.js

@@ -0,0 +1,380 @@
+/**
+ * `tospec skill-metrics` — how long each skill actually takes, as a served web
+ * page.
+ *
+ * Read-only, and derived from two independent sources: Claude Code
+ * transcripts (core/skill-metrics.ts) and Codex sessions
+ * (core/codex-metrics.ts). Nothing is written, so the command is safe to run
+ * at any point in a workflow.
+ *
+ * The two sources carry different confidence — Claude Code's attribution is
+ * read directly, Codex's is inferred by a heuristic — and are therefore never
+ * summed into one figure anywhere in the report; every row, chart, and
+ * statistic carries a `source` and the two stay distinguishable throughout
+ * (design.md D4 in the codex-metrics change).
+ *
+ * The page is the only output: seven columns of minutes per skill had to be
+ * compared by reading digits, and a median/max pair discarded the very
+ * distribution it summarised. See
+ * tospec/decisions/20260730_205609-metrics-web-only-output.md.
+ *
+ * The server is deliberately short-lived and unmanaged. It binds a fixed base
+ * port and advances on collision, so the URL is predictable enough to keep in
+ * your head or bookmark while a second run still starts rather than failing.
+ * None of the dashboard's registry, pid-file, or `--stop` machinery applies to
+ * something you open, read, and close: the walk-up is the whole collision story.
+ */
+import * as http from 'node:http';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { resolveRootForCommand } from '../core/root-selection.js';
+import { isAllowedHostHeader, listenFrom, openBrowser, packageAssetsDir, sendJson, serveAsset, } from '../core/local-server.js';
+import { DEFAULT_IDLE_GAP_MS, DEFAULT_SPLIT_GAP_MS, aggregateRuns, buildRuns, parseTranscript, resolveTranscriptDir, skillRowKey, } from '../core/skill-metrics.js';
+import { scanCodexSessions, } from '../core/codex-metrics.js';
+import { formatLocalDate } from '../utils/timestamp.js';
+import { emitFailure } from './shared-output.js';
+const DEFAULT_HOST = '127.0.0.1';
+/**
+ * Well clear of the dashboard's 5620 base, so the two commands' walk-up ranges
+ * can never meet each other.
+ */
+const DEFAULT_PORT = 26693;
+/** This command's shipped frontend; `serveAsset` is confined to it. */
+const ASSETS_DIR = packageAssetsDir('metrics');
+async function readTranscripts(projectRoot, dirOptions) {
+    const transcriptDir = resolveTranscriptDir(projectRoot, dirOptions);
+    let fileNames;
+    try {
+        fileNames = (await fs.readdir(transcriptDir)).filter((f) => f.endsWith('.jsonl'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { transcriptDir, available: false, sessions: 0, parsed: [] };
+        }
+        throw error;
+    }
+    const parsed = [];
+    for (const fileName of fileNames) {
+        let text;
+        try {
+            text = await fs.readFile(path.join(transcriptDir, fileName), 'utf8');
+        }
+        catch {
+            // A session file can vanish between readdir and read; skip it.
+            continue;
+        }
+        parsed.push({ session: path.basename(fileName, '.jsonl'), entries: parseTranscript(text) });
+    }
+    return { transcriptDir, available: true, sessions: fileNames.length, parsed };
+}
+function withMinimum(stats, values) {
+    return { ...stats, minMs: values.length === 0 ? 0 : Math.min(...values) };
+}
+/**
+ * Above this the bars stop being readable — 120 across a typical chart width is
+ * already only a few pixels each — so the unit widens rather than the bars
+ * shrinking. Driven by the resulting count rather than by which range option was
+ * picked, so adding a range option later cannot reintroduce three-pixel bars.
+ */
+const MAX_BUCKETS = 120;
+/** Local midnight of the day containing `ms`. */
+function startOfLocalDay(ms) {
+    const d = new Date(ms);
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+/** Local Monday of the week containing `date`. */
+function startOfLocalWeek(date) {
+    // getDay(): 0 = Sunday, so Sunday is 6 days after its Monday.
+    const back = (date.getDay() + 6) % 7;
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate() - back);
+}
+function bucketStart(ms, granularity) {
+    const day = startOfLocalDay(ms);
+    if (granularity === 'week')
+        return startOfLocalWeek(day);
+    if (granularity === 'month')
+        return new Date(day.getFullYear(), day.getMonth(), 1);
+    return day;
+}
+function bucketKey(start, granularity) {
+    return granularity === 'month' ? formatLocalDate(start).slice(0, 7) : formatLocalDate(start);
+}
+/** The next bucket start after `start`, in local time (DST- and month-length-safe). */
+function nextBucket(start, granularity) {
+    const { 0: y, 1: m, 2: d } = [start.getFullYear(), start.getMonth(), start.getDate()];
+    if (granularity === 'month')
+        return new Date(y, m + 1, 1);
+    return new Date(y, m, d + (granularity === 'week' ? 7 : 1));
+}
+function countBuckets(firstMs, lastMs, granularity) {
+    let cursor = bucketStart(firstMs, granularity);
+    const end = bucketStart(lastMs, granularity).getTime();
+    let n = 1;
+    while (cursor.getTime() < end) {
+        cursor = nextBucket(cursor, granularity);
+        n++;
+        if (n > 10000)
+            break; // defensive: never spin on a corrupt timestamp
+    }
+    return n;
+}
+/**
+ * Engaged time per period per skill, in local calendar time.
+ *
+ * Each run is counted whole on the local date it *started*, so a run crossing
+ * midnight is not divided — "one run is one entity" is what the distribution and
+ * timeline charts also assume. Bucketing by UTC would misplace any run starting
+ * before the local day's UTC offset, which for a positive offset is every early
+ * morning.
+ *
+ * Periods with no runs are included as empty buckets: with most days empty in a
+ * typical history, dropping them would make three consecutive days and three
+ * days a week apart look identical, which is the pattern this series exists to
+ * show.
+ */
+export function buildTimeSeries(runs) {
+    if (runs.length === 0)
+        return { granularity: 'day', buckets: [] };
+    const firstMs = Math.min(...runs.map((r) => r.startMs));
+    const lastMs = Math.max(...runs.map((r) => r.startMs));
+    let granularity = 'day';
+    if (countBuckets(firstMs, lastMs, 'day') > MAX_BUCKETS)
+        granularity = 'week';
+    if (granularity === 'week' && countBuckets(firstMs, lastMs, 'week') > MAX_BUCKETS) {
+        granularity = 'month';
+    }
+    const totals = new Map();
+    for (const run of runs) {
+        const key = bucketKey(bucketStart(run.startMs, granularity), granularity);
+        const bucket = totals.get(key) ?? {};
+        const row = skillRowKey(run.skill, run.source);
+        // Keyed by skill-and-source, not skill alone: a day with runs from both
+        // sources for the same skill must keep the two figures apart rather than
+        // summing them into one bucket entry.
+        bucket[row] = (bucket[row] ?? 0) + run.engagedMs;
+        totals.set(key, bucket);
+    }
+    const buckets = [];
+    let cursor = bucketStart(firstMs, granularity);
+    const end = bucketStart(lastMs, granularity).getTime();
+    for (;;) {
+        const key = bucketKey(cursor, granularity);
+        buckets.push({ key, byRow: totals.get(key) ?? {} });
+        if (cursor.getTime() >= end)
+            break;
+        cursor = nextBucket(cursor, granularity);
+    }
+    return { granularity, buckets };
+}
+/**
+ * Builds runs for one source's parsed sessions and applies the since-filter.
+ * Shared by both sources: `TranscriptCache.parsed` and
+ * `CodexTranscriptCache.parsed` have the identical `{ session, entries }`
+ * shape, so the same assembly works for either — only the `source` tag
+ * `buildRuns` stamps onto each run differs.
+ */
+function runsFrom(parsed, query, source) {
+    const runs = [];
+    let attributedSessions = 0;
+    for (const { session, entries } of parsed) {
+        const sessionRuns = buildRuns(entries, session, { ...query.thresholds, source });
+        // Counted before the since-filter: a session that produced runs did carry
+        // attribution, whether or not the selected range keeps any of them.
+        if (sessionRuns.length > 0)
+            attributedSessions++;
+        for (const run of sessionRuns) {
+            if (query.sinceMs !== undefined && run.endMs < query.sinceMs)
+                continue;
+            runs.push(run);
+        }
+    }
+    return { runs, attributedSessions };
+}
+function sourceStats(transcriptDir, available, sessions, result) {
+    return {
+        transcriptDir,
+        available,
+        sessions,
+        attributedSessions: result.attributedSessions,
+        firstSeen: result.runs.length > 0 ? new Date(Math.min(...result.runs.map((r) => r.startMs))).toISOString() : null,
+        lastSeen: result.runs.length > 0 ? new Date(Math.max(...result.runs.map((r) => r.endMs))).toISOString() : null,
+    };
+}
+/**
+ * Pure: turns both sources' parsed caches plus a query into the report the
+ * page renders. Claude Code and Codex runs are built, filtered, and reported
+ * independently at every step — merged only into one sorted `runs` list and
+ * one `skills` list, which `aggregateRuns` already keeps apart by
+ * `(skill, source)` (design.md D4: never summed).
+ */
+export function reportFrom(claudeCache, codexCache, query) {
+    const claude = runsFrom(claudeCache.parsed, query, 'claude-code');
+    const codex = runsFrom(codexCache.sessions, query, 'codex');
+    const runs = [...claude.runs, ...codex.runs].sort((a, b) => a.startMs - b.startMs);
+    const byRow = new Map();
+    for (const run of runs) {
+        const key = skillRowKey(run.skill, run.source);
+        const bucket = byRow.get(key);
+        if (bucket)
+            bucket.push(run);
+        else
+            byRow.set(key, [run]);
+    }
+    const skills = aggregateRuns(runs).map((a) => {
+        const rowRuns = byRow.get(skillRowKey(a.skill, a.source)) ?? [];
+        return {
+            ...a,
+            span: withMinimum(a.span, rowRuns.map((r) => r.spanMs)),
+            engaged: withMinimum(a.engaged, rowRuns.map((r) => r.engagedMs)),
+        };
+    });
+    return {
+        sources: {
+            claudeCode: sourceStats(claudeCache.transcriptDir, claudeCache.available, claudeCache.sessions, claude),
+            codex: sourceStats(codexCache.sessionsDir, codexCache.available, codexCache.sessions.length, codex),
+        },
+        thresholds: query.thresholds,
+        skills,
+        series: buildTimeSeries(runs),
+        runs,
+    };
+}
+/** A malformed query parameter: the client's fault, so 400 rather than 500. */
+class BadQuery extends Error {
+}
+/**
+ * Reads a positive-duration parameter.
+ *
+ * With the CLI flags removed, the page is the only source of these values, so
+ * nothing upstream has checked them — this restates the rule the deleted
+ * `positiveMinutes` argParser enforced, at the boundary where the values now
+ * actually arrive.
+ */
+function positiveMs(params, name, fallback) {
+    const raw = params.get(name);
+    if (raw === null)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new BadQuery(`${name} expects a positive number of milliseconds, got '${raw}'.`);
+    }
+    return value;
+}
+function queryFrom(params) {
+    const query = {
+        thresholds: {
+            idleGapMs: positiveMs(params, 'idleGap', DEFAULT_IDLE_GAP_MS),
+            splitGapMs: positiveMs(params, 'splitGap', DEFAULT_SPLIT_GAP_MS),
+        },
+    };
+    const since = params.get('since');
+    if (since !== null) {
+        const sinceMs = Number(since);
+        if (!Number.isFinite(sinceMs)) {
+            throw new BadQuery(`since expects a millisecond timestamp, got '${since}'.`);
+        }
+        // Absent means all-time, which is the default the page opens on. A `since`
+        // only ever narrows.
+        query.sinceMs = sinceMs;
+    }
+    return query;
+}
+async function handleRequest(ctx, req, res) {
+    try {
+        // Host allowlist runs before any route (DNS-rebinding guard).
+        if (!isAllowedHostHeader(req.headers.host, ctx.host)) {
+            return sendJson(res, 403, { error: 'forbidden host' });
+        }
+        if (req.method !== 'GET') {
+            return sendJson(res, 405, { error: 'method not allowed' });
+        }
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname === '/')
+            return await serveAsset(res, ASSETS_DIR, 'index.html');
+        if (url.pathname.startsWith('/assets/')) {
+            return await serveAsset(res, ASSETS_DIR, url.pathname.slice('/assets/'.length));
+        }
+        if (url.pathname === '/api/report') {
+            const query = queryFrom(url.searchParams);
+            // Still a read, so still a GET — it just declines the cache. Transcripts
+            // grow while the page is open, including from the session viewing it, so
+            // this is the only way to see anything recorded since startup.
+            if (url.searchParams.get('refresh') !== null) {
+                ctx.claudeCache = await readTranscripts(ctx.projectRoot, ctx.dirOptions);
+                ctx.codexCache = await scanCodexSessions(ctx.projectRoot, ctx.dirOptions);
+            }
+            return sendJson(res, 200, reportFrom(ctx.claudeCache, ctx.codexCache, query));
+        }
+        sendJson(res, 404, { error: 'not found' });
+    }
+    catch (err) {
+        if (err instanceof BadQuery) {
+            return sendJson(res, 400, { error: err.message });
+        }
+        // A single handler failure must never crash the server.
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+}
+// -----------------------------------------------------------------------------
+// Lifecycle
+// -----------------------------------------------------------------------------
+/**
+ * Starts the metrics server. Side-effect free — no logging, no browser, no
+ * signal handlers — so tests can drive it directly.
+ *
+ * Binds `DEFAULT_PORT` and advances on collision, so two metrics runs — or a
+ * metrics run beside anything else already holding the port — both start.
+ * Tests pass `port: 0` to stay out of the fixed range entirely.
+ */
+export async function startMetricsServer(projectRoot, opts = {}) {
+    const host = opts.host ?? DEFAULT_HOST;
+    // Read up front rather than on the first request, so the URL is only printed
+    // once the report behind it can actually be produced.
+    const ctx = {
+        host,
+        projectRoot,
+        dirOptions: opts,
+        claudeCache: await readTranscripts(projectRoot, opts),
+        codexCache: await scanCodexSessions(projectRoot, opts),
+    };
+    const server = http.createServer((req, res) => {
+        void handleRequest(ctx, req, res);
+    });
+    const port = await listenFrom(server, opts.port ?? DEFAULT_PORT, host);
+    return { server, url: `http://${host}:${port}`, port };
+}
+/**
+ * CLI entry: start the server, print the URL, open a browser, and stay up until
+ * terminated. No signal handler — there is no registry entry, pid file, or temp
+ * file to clean up, so the default SIGINT behaviour is already correct.
+ */
+export async function runMetrics(projectRoot, opts = {}) {
+    const { server, url } = await startMetricsServer(projectRoot);
+    console.log(`Metrics running at ${url} (Ctrl+C to stop)`);
+    if (opts.open !== false) {
+        openBrowser(url);
+    }
+    return server;
+}
+export function registerMetricsCommand(program) {
+    program
+        // Named for what it measures, not for the generic notion of metrics: the
+        // report is entirely about skill durations, and the bare `metrics` name
+        // invited the reading that it covered project or CLI statistics at large.
+        .command('skill-metrics')
+        .description('Open a local web report of how long every skill takes')
+        .option('--no-open', 'Print the URL without opening a browser')
+        .action(async (options) => {
+        try {
+            const root = await resolveRootForCommand({});
+            if (!root) {
+                return;
+            }
+            await runMetrics(root.path, options);
+        }
+        catch (error) {
+            emitFailure(undefined, {}, error, 'metrics_error');
+        }
+    });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/commands/metrics.js.map

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

package/dist/core/codex-metrics.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Codex skill duration metrics — a second, less precise source for the same
+ * report `skill-metrics.ts` builds from Claude Code transcripts.
+ *
+ * Codex keeps one session tree shared by every project
+ * (`<CODEX_HOME or ~/.codex>/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl`),
+ * partitioned by date rather than by project, with the working directory
+ * recorded once per session (`type: "session_meta"`, `payload.cwd`) rather than
+ * encoded into a directory name. Project scoping therefore reads that field
+ * instead of resolving a path (see codex-metrics-source spec, "Codex sessions
+ * are scoped to a project by their recorded working directory").
+ *
+ * Codex transcripts carry nothing like Claude Code's `attributionSkill`. Every
+ * session's system prompt lists all installed skills identically whether or
+ * not any of them were used, so that listing carries no signal. The one event
+ * confirmed (against this project's own real `~/.codex` history) to correlate
+ * with a skill actually being used is a tool-call command whose text reads a
+ * path ending in `<skill-name>/SKILL.md` — the moment the agent pulls in that
+ * skill's instructions. Skill attribution here is therefore a heuristic, not a
+ * recorded fact, and undercounts by construction: a skill run that never
+ * re-reads its own instructions file is invisible to it.
+ */
+import { type RunGroupingOptions, type SkillMetrics, type TranscriptEntry } from './skill-metrics.js';
+export interface CodexSessionsDirOptions {
+    env?: NodeJS.ProcessEnv;
+    homedir?: string;
+}
+/**
+ * Locates Codex's session tree. `CODEX_HOME` is honoured the same way
+ * `CLAUDE_CONFIG_DIR` is for Claude Code; without it the default is
+ * `~/.codex`. This is the directory to search, not a per-project one — Codex
+ * has no equivalent of Claude Code's per-project transcript directory.
+ */
+export declare function resolveCodexSessionsDir(options?: CodexSessionsDirOptions): string;
+/**
+ * Whether a session's recorded working directory names the given project.
+ * `null` (no `session_meta` seen, or no `cwd` field) never matches — a session
+ * with nothing recorded cannot be attributed to any project.
+ */
+export declare function sessionBelongsToProject(cwd: string | null, rootPath: string): boolean;
+export interface CodexSessionResult {
+    /** The session's recorded working directory, or null if never seen. */
+    cwd: string | null;
+    entries: TranscriptEntry[];
+}
+/**
+ * Parses one Codex rollout `.jsonl` file into the recorded project directory
+ * plus a sorted, timestamped, skill-labelled entry list — the same shape
+ * `parseTranscript` produces for Claude Code, so `buildRuns`/`aggregateRuns`
+ * apply unchanged (design.md D3). Malformed lines are skipped rather than
+ * fatal, for the same reason Claude Code transcripts are: an append-only log
+ * that can be torn at the tail while a session is live.
+ *
+ * Only `function_call`/`custom_tool_call` entries are ever inspected for a
+ * `SKILL.md` read. Every other entry — including the one carrying the fixed
+ * skill-listing text every session opens with — is folded in unattributed
+ * (`skill: null`), exactly as an unattributed Claude Code entry is: it cannot
+ * end a run, but it is not evidence a skill became active either.
+ */
+export declare function parseCodexSession(text: string): CodexSessionResult;
+export interface CodexProjectSession {
+    /** Rollout file stem — the session id runs are labelled with. */
+    session: string;
+    entries: TranscriptEntry[];
+}
+export interface CodexSessionScan {
+    sessionsDir: string;
+    /** False when the sessions directory does not exist — Codex has never run here. */
+    available: boolean;
+    /** Only the sessions whose recorded cwd names this project. */
+    sessions: CodexProjectSession[];
+}
+/**
+ * Finds and parses every Codex session belonging to one project.
+ *
+ * Shared by `collectCodexSkillMetrics` and the metrics server, which need
+ * exactly this and previously each carried their own copy of the walk — so the
+ * probe optimisation could otherwise have been applied to one and not the other.
+ */
+export declare function scanCodexSessions(rootPath: string, options?: CodexSessionsDirOptions): Promise<CodexSessionScan>;
+export interface CollectCodexMetricsOptions extends RunGroupingOptions, CodexSessionsDirOptions {
+    /** Drop runs that ended before this instant. */
+    sinceMs?: number;
+}
+/**
+ * Derives skill timings from the `SKILL.md`-read heuristic over this project's
+ * Codex sessions — the Codex-flavoured equivalent of `collectSkillMetrics`.
+ * `scanCodexSessions` does the finding and scoping.
+ *
+ * A missing sessions directory is a reportable state (`available: false`), not
+ * an error, for the same reason it is for Claude Code: the project may simply
+ * never have been opened in Codex.
+ */
+export declare function collectCodexSkillMetrics(rootPath: string, options?: CollectCodexMetricsOptions): Promise<SkillMetrics>;
+//# sourceMappingURL=codex-metrics.d.ts.map

package/dist/core/codex-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-metrics.d.ts","sourceRoot":"","sources":["../../src/core/codex-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,EAQL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAQ5B,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM,CAMrF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKrF;AAMD,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AA8CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CA4ClE;AAsED,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CA8B3B;AAMD,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB,EAAE,uBAAuB;IAC7F,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,YAAY,CAAC,CAqDvB"}