@skillstate/cli 2.0.0

package/bin/skillstate.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// skillstate CLI shim (ESM) — @skillstate/cli bin entry.
+import { main } from '../dist/index.js';
+
+const code = await main(process.argv.slice(2), process.cwd());
+process.exit(code);

package/dist/commands.d.ts

@@ -0,0 +1,40 @@
+import type { SkillStateConfig } from '@skillstate/core';
+import type { ProceduralSpec, SkillState } from '@skillstate/core';
+export declare const CLI_USAGE = "Usage: skillstate init | run [--config <path>] [--resume] | report [--format json|md]";
+/** Parsed `run` flags. */
+export interface RunFlags {
+    configPath?: string;
+    resume: boolean;
+}
+/** Parsed `report` flags. */
+export interface ReportFlags {
+    format: 'json' | 'md';
+}
+/** Resolve `p` against `cwd` (absolute paths pass through). */
+export declare function resolveInCwd(cwd: string, p: string): string;
+/**
+ * Parse `run` flags: `--config <path>`, `--config=<path>`, `--resume`.
+ * Throws an `Error` with {@link CLI_USAGE} on unknown flags or a missing
+ * `--config` value.
+ */
+export declare function parseRunArgs(args: string[]): RunFlags;
+/**
+ * Parse `report` flags: `--format json|md` (default `json`).
+ * Throws an `Error` with {@link CLI_USAGE} on unknown/invalid flags.
+ */
+export declare function parseReportArgs(args: string[]): ReportFlags;
+/** Load config: `loadConfig(cwd)`, or the `--config` file overlaid with env. */
+export declare function loadCliConfig(cwd: string, configPath?: string): SkillStateConfig;
+/** Load the procedural spec: JSON file at `specPath`, else the builtin CTF spec. */
+export declare function loadCliSpec(cwd: string, specPath: string): ProceduralSpec;
+/** Load persisted state for `--resume` (null = fresh start, never throws). */
+export declare function loadResumeState(cwd: string, statePath: string): SkillState | null;
+/** Deterministic offline stub LLM: valid empty patch + `noop` action. */
+export declare function stubLlmResponse(): string;
+/**
+ * CLI entry: `argv` without the node/bin prefix, `cwd` defaulting to
+ * `process.cwd()`. Returns a process exit code (0 ok, 1 runtime error,
+ * 2 usage error). Never throws for usage errors.
+ */
+export declare function main(argv: string[], cwd?: string): Promise<number>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAOzD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnE,eAAO,MAAM,SAAS,0FACmE,CAAC;AAE1F,0BAA0B;AAC1B,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,6BAA6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAMD,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAOD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CAyBrD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAsB3D;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAWhF;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAoBzE;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAOjF;AAED,yEAAyE;AACzE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AA6ID;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBxE"}

package/dist/commands.js

@@ -0,0 +1,302 @@
+// skillstate CLI — init | run [--config <path>] [--resume] | report [--format json|md].
+//
+// @non-paper Wave-4 DX layer (additive): thin file orchestration over the
+// paper-exact runtime. `run` uses a deterministic offline stub LLM (empty
+// patch + `noop` action) so `init → run → report` works from a clean
+// directory with no network; bring your own `LLMFn`/`LLMProvider` for real
+// runs via the library API.
+//
+// Units are raw string CHARS throughout (paper §4.3).
+/// <reference types="node" />
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defaultConfig, loadConfig, mergeConfig, CONFIG_FILE_NAME, } from '@skillstate/core';
+import { SkillStateRuntime } from '@skillstate/core';
+import { TokenTracker } from '@skillstate/core';
+import { atomicWriteFile } from '@skillstate/core';
+import { migrate } from '@skillstate/core';
+import { generateReport } from './dashboard.js';
+import { INTERCODE_CTF_SPEC } from '@skillstate/core/schemas';
+export const CLI_USAGE = 'Usage: skillstate init | run [--config <path>] [--resume] | report [--format json|md]';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Resolve `p` against `cwd` (absolute paths pass through). */
+export function resolveInCwd(cwd, p) {
+    return path.isAbsolute(p) ? p : path.join(cwd, p);
+}
+function readJsonFile(absPath) {
+    const raw = fs.readFileSync(absPath, 'utf-8');
+    return JSON.parse(raw);
+}
+/**
+ * Parse `run` flags: `--config <path>`, `--config=<path>`, `--resume`.
+ * Throws an `Error` with {@link CLI_USAGE} on unknown flags or a missing
+ * `--config` value.
+ */
+export function parseRunArgs(args) {
+    let configPath;
+    let resume = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--resume') {
+            resume = true;
+        }
+        else if (arg === '--config') {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new Error(`Missing value for --config\n${CLI_USAGE}`);
+            }
+            configPath = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--config=')) {
+            const value = arg.slice('--config='.length);
+            if (value.length === 0) {
+                throw new Error(`Missing value for --config\n${CLI_USAGE}`);
+            }
+            configPath = value;
+        }
+        else {
+            throw new Error(`Unknown flag for run: ${arg}\n${CLI_USAGE}`);
+        }
+    }
+    return { configPath, resume };
+}
+/**
+ * Parse `report` flags: `--format json|md` (default `json`).
+ * Throws an `Error` with {@link CLI_USAGE} on unknown/invalid flags.
+ */
+export function parseReportArgs(args) {
+    let format = 'json';
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--format') {
+            const next = args[i + 1];
+            if (next !== 'json' && next !== 'md') {
+                throw new Error(`Invalid --format (want json|md)\n${CLI_USAGE}`);
+            }
+            format = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--format=')) {
+            const value = arg.slice('--format='.length);
+            if (value !== 'json' && value !== 'md') {
+                throw new Error(`Invalid --format (want json|md)\n${CLI_USAGE}`);
+            }
+            format = value;
+        }
+        else {
+            throw new Error(`Unknown flag for report: ${arg}\n${CLI_USAGE}`);
+        }
+    }
+    return { format };
+}
+/** Load config: `loadConfig(cwd)`, or the `--config` file overlaid with env. */
+export function loadCliConfig(cwd, configPath) {
+    if (configPath === undefined) {
+        return loadConfig(cwd);
+    }
+    let parsed = {};
+    try {
+        parsed = readJsonFile(resolveInCwd(cwd, configPath));
+    }
+    catch {
+        parsed = {};
+    }
+    return mergeConfig(parsed);
+}
+/** Load the procedural spec: JSON file at `specPath`, else the builtin CTF spec. */
+export function loadCliSpec(cwd, specPath) {
+    if (specPath === '@intercode-ctf') {
+        return INTERCODE_CTF_SPEC;
+    }
+    try {
+        const parsed = readJsonFile(resolveInCwd(cwd, specPath));
+        if (isRecord(parsed) &&
+            typeof parsed['id'] === 'string' &&
+            typeof parsed['name'] === 'string' &&
+            typeof parsed['instructions'] === 'string' &&
+            isRecord(parsed['schema']) &&
+            typeof parsed['version'] === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to the builtin below.
+    }
+    return INTERCODE_CTF_SPEC;
+}
+/** Load persisted state for `--resume` (null = fresh start, never throws). */
+export function loadResumeState(cwd, statePath) {
+    try {
+        const parsed = readJsonFile(resolveInCwd(cwd, statePath));
+        return migrate(parsed).state;
+    }
+    catch {
+        return null;
+    }
+}
+/** Deterministic offline stub LLM: valid empty patch + `noop` action. */
+export function stubLlmResponse() {
+    return `noop step\n\n\`\`\`json\n${JSON.stringify({ state_patch: {}, action: 'noop' })}\n\`\`\``;
+}
+async function cmdInit(cwd) {
+    const configPath = path.join(cwd, CONFIG_FILE_NAME);
+    const defaults = defaultConfig();
+    if (fs.existsSync(configPath) === false) {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, `${JSON.stringify(defaults, null, 2)}\n`, 'utf-8');
+        console.log(`Created ${CONFIG_FILE_NAME}`);
+    }
+    else {
+        console.log(`${CONFIG_FILE_NAME} already exists`);
+    }
+    const specAbs = resolveInCwd(cwd, defaults.specPath);
+    if (fs.existsSync(specAbs) === false) {
+        fs.mkdirSync(path.dirname(specAbs), { recursive: true });
+        fs.writeFileSync(specAbs, `${JSON.stringify(INTERCODE_CTF_SPEC, null, 2)}\n`, 'utf-8');
+        console.log(`Created ${defaults.specPath}`);
+    }
+    return 0;
+}
+async function cmdRun(cwd, flags) {
+    const config = loadCliConfig(cwd, flags.configPath);
+    const spec = loadCliSpec(cwd, config.specPath);
+    const tracker = new TokenTracker({
+        platform: config.platform,
+        sessionName: config.sessionName,
+    });
+    const resumed = flags.resume ? loadResumeState(cwd, config.statePath) : null;
+    const runtime = new SkillStateRuntime({
+        spec,
+        llm: async () => stubLlmResponse(),
+        execute: async (action) => ({
+            content: `executed:${action}`,
+            timestamp: Date.now(),
+            source: 'cli',
+        }),
+        tracker,
+        maxValidationRetries: config.maxValidationRetries,
+        ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
+        ...(resumed !== null ? { initialState: resumed } : {}),
+    });
+    const maxSteps = config.maxSteps;
+    await runtime.run({ content: 'cli start', timestamp: Date.now(), source: 'cli' }, () => false, maxSteps);
+    const stateAbs = resolveInCwd(cwd, config.statePath);
+    await atomicWriteFile(stateAbs, JSON.stringify({ version: 1, state: runtime.state }));
+    const reportAbs = resolveInCwd(cwd, config.reportPath);
+    fs.mkdirSync(path.dirname(reportAbs), { recursive: true });
+    tracker.save(reportAbs);
+    console.log(`Ran ${tracker.getBookkeeping().stepCount} steps`);
+    return 0;
+}
+async function cmdReport(cwd, flags) {
+    const config = loadConfig(cwd);
+    const reportAbs = resolveInCwd(cwd, config.reportPath);
+    let raw;
+    try {
+        raw = fs.readFileSync(reportAbs, 'utf-8');
+    }
+    catch {
+        console.error(`No report at ${config.reportPath} (run first)`);
+        return 1;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        console.error(`Corrupt report at ${config.reportPath}`);
+        return 1;
+    }
+    if (flags.format === 'json') {
+        console.log(raw);
+        return 0;
+    }
+    if (isRecord(parsed) === false) {
+        console.error(`Corrupt report at ${config.reportPath}`);
+        return 1;
+    }
+    const rec = parsed;
+    const steps = Array.isArray(rec['steps'])
+        ? rec['steps']
+        : [];
+    let stateChars = 0;
+    let conversationChars = 0;
+    let running = 0;
+    for (const s of steps) {
+        const pc = typeof s?.promptChars === 'number' && s.promptChars >= 0 ? s.promptChars : 0;
+        running += pc;
+        stateChars += pc;
+        conversationChars += running;
+    }
+    const metrics = isRecord(rec['metrics'])
+        ? rec['metrics']
+        : {
+            sessionName: config.sessionName,
+            totalChars: 0,
+            stepCount: steps.length,
+            averagePromptSize: 0,
+        };
+    const session = isRecord(rec['session'])
+        ? rec['session']
+        : {
+            name: config.sessionName,
+            platform: config.platform,
+            startedAt: new Date().toISOString(),
+        };
+    const md = generateReport({
+        metrics: {
+            sessionName: metrics.sessionName,
+            totalChars: metrics.totalChars,
+            stepCount: metrics.stepCount,
+            averagePromptSize: metrics.averagePromptSize,
+            accuracy: metrics.accuracy ?? null,
+        },
+        comparison: {
+            conversationChars,
+            stateChars,
+            reductionFactor: stateChars > 0 ? conversationChars / stateChars : 0,
+        },
+        history: steps,
+        session: {
+            name: session.name,
+            platform: session.platform,
+            startedAt: session.startedAt,
+        },
+    });
+    console.log(md);
+    return 0;
+}
+/**
+ * CLI entry: `argv` without the node/bin prefix, `cwd` defaulting to
+ * `process.cwd()`. Returns a process exit code (0 ok, 1 runtime error,
+ * 2 usage error). Never throws for usage errors.
+ */
+export async function main(argv, cwd) {
+    const dir = cwd ?? process.cwd();
+    const [command, ...rest] = argv;
+    try {
+        if (command === 'init') {
+            if (rest.length > 0) {
+                console.error(`Unknown flag for init: ${rest[0]}\n${CLI_USAGE}`);
+                return 2;
+            }
+            return await cmdInit(dir);
+        }
+        if (command === 'run') {
+            return await cmdRun(dir, parseRunArgs(rest));
+        }
+        if (command === 'report') {
+            return await cmdReport(dir, parseReportArgs(rest));
+        }
+        console.error(CLI_USAGE);
+        return 2;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

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

package/dist/dashboard.d.ts

@@ -0,0 +1,41 @@
+import type { ExecutionStep } from '@skillstate/core';
+export interface DashboardMetrics {
+    sessionName: string;
+    totalChars: number;
+    totalPromptChars?: number;
+    stepCount: number;
+    averagePromptSize: number;
+    /** Task Accuracy (paper §4.3). Null/undefined renders as 'n/a'. */
+    accuracy?: number | null;
+    lastStepTimestamp?: number | null;
+}
+export interface BaselineComparison {
+    conversationChars: number;
+    stateChars: number;
+    reductionFactor: number;
+}
+export interface SessionInfo {
+    name: string;
+    platform: string;
+    startedAt: string | number;
+}
+export interface BudgetProgress {
+    used: number;
+    budget: number;
+}
+export interface ReportInput {
+    metrics: DashboardMetrics;
+    comparison: BaselineComparison;
+    history: ExecutionStep[];
+    session: SessionInfo;
+}
+export interface DashboardInput extends ReportInput {
+    progress?: BudgetProgress;
+}
+export declare function formatMetricsTable(metrics: DashboardMetrics): string;
+export declare function formatComparisonTable(comparison: BaselineComparison): string;
+export declare function formatStepHistory(steps: ExecutionStep[]): string;
+export declare function formatProgressBar(progressOrPercent: BudgetProgress | number, width?: number): string;
+export declare function generateReport(input: ReportInput): string;
+export declare function printDashboard(input: DashboardInput): string;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAQtD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAID,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAID,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAGD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AA4ED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAqBpE;AAMD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAY5E;AAMD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,CAehE;AAQD,wBAAgB,iBAAiB,CAC/B,iBAAiB,EAAE,cAAc,GAAG,MAAM,EAC1C,KAAK,GAAE,MAAW,GACjB,MAAM,CAeR;AAMD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA0BzD;AAQD,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAkC5D"}

package/dist/dashboard.js

@@ -0,0 +1,187 @@
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const RESET = '\x1b[0m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+// Checked at call time (not module load) so env changes like FORCE_COLOR
+// set by tests are honored.
+function colorEnabled() {
+    if (process.env['NO_COLOR'])
+        return false;
+    const force = process.env['FORCE_COLOR'];
+    if (force !== undefined && force !== '')
+        return force !== '0';
+    return Boolean(process.stdout?.isTTY);
+}
+function paint(text, code) {
+    if (!colorEnabled())
+        return text;
+    return `${code}${text}${RESET}`;
+}
+// Plain number formatting — never locale-aware (tests assert exact digits,
+// e.g. "4500" must not become "4,500"). Integers print exactly; fractions
+// are trimmed to one decimal.
+function fmtNum(n) {
+    if (Number.isInteger(n))
+        return String(n);
+    return String(Math.round(n * 10) / 10);
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, Math.max(0, max - 3))}...` : text;
+}
+// Renders a timestamp that may be an epoch-ms number or an ISO string.
+// Falls back to the raw value when unparsable.
+function formatTimestamp(ts) {
+    const d = new Date(ts);
+    return Number.isNaN(d.getTime()) ? String(ts) : d.toISOString();
+}
+// Renders a box-drawing table with computed column widths.
+// Precondition: every row has exactly one cell per header column —
+// all call sites construct rows via .map over the column list, and
+// `widths` is derived from `headers`, so index access is always in range.
+function renderTable(title, headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const bar = (left, mid, right) => left + widths.map((w) => '─'.repeat(w + 2)).join(mid) + right;
+    const lines = [paint(title, BOLD)];
+    lines.push(bar('┌', '┬', '┐'));
+    lines.push(`│${headers.map((h, i) => ` ${h.padEnd(widths[i], ' ')} `).join('│')}│`);
+    lines.push(bar('├', '┼', '┤'));
+    for (const row of rows) {
+        lines.push(`│${headers
+            .map((_, i) => ` ${row[i].padEnd(widths[i], ' ')} `)
+            .join('│')}│`);
+    }
+    lines.push(bar('└', '┴', '┘'));
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// 1. formatMetricsTable
+// ---------------------------------------------------------------------------
+export function formatMetricsTable(metrics) {
+    // Task Accuracy (paper §4.3): '75.0%' when actionable steps exist, 'n/a'
+    // otherwise (null from TokenTracker, or absent on legacy metric shapes).
+    const accuracyText = metrics.accuracy == null
+        ? 'n/a'
+        : `${(metrics.accuracy * 100).toFixed(1)}%`;
+    const rows = [
+        ['Session', metrics.sessionName],
+        ['Total Chars', fmtNum(metrics.totalChars)],
+        ['Steps', fmtNum(metrics.stepCount)],
+        ['Accuracy', accuracyText],
+        ['Avg Prompt Size', `${fmtNum(metrics.averagePromptSize)} chars`],
+    ];
+    return renderTable(`Session Metrics (${metrics.sessionName})`, ['Metric', 'Value'], rows);
+}
+// ---------------------------------------------------------------------------
+// 2. formatComparisonTable
+// ---------------------------------------------------------------------------
+export function formatComparisonTable(comparison) {
+    const rows = [
+        ['Conversation Chars', fmtNum(comparison.conversationChars)],
+        ['State Chars', fmtNum(comparison.stateChars)],
+        ['Reduction Factor', `${comparison.reductionFactor.toFixed(1)}x`],
+    ];
+    return renderTable('Comparison vs Conversation Baseline', ['Metric', 'Value'], rows);
+}
+// ---------------------------------------------------------------------------
+// 3. formatStepHistory
+// ---------------------------------------------------------------------------
+export function formatStepHistory(steps) {
+    const rows = steps.length
+        ? steps.map((s) => [
+            String(s.step),
+            truncate(s.action ?? '', 24),
+            fmtNum(s.promptChars),
+            fmtNum(s.responseChars),
+        ])
+        : [['-', '(no steps recorded)', '-', '-']];
+    return renderTable('Step History', ['Step', 'Action', 'Prompt Chars', 'Response Chars'], rows);
+}
+// ---------------------------------------------------------------------------
+// 4. formatProgressBar
+// ---------------------------------------------------------------------------
+// Accepts either a ready percent or a { used, budget } pair (as supplied by
+// the CLI when rendering token budget usage). Width defaults to 20 cells.
+export function formatProgressBar(progressOrPercent, width = 20) {
+    let percent;
+    if (typeof progressOrPercent === 'number') {
+        percent = progressOrPercent;
+    }
+    else {
+        const { used, budget } = progressOrPercent;
+        percent = budget > 0 ? (used / budget) * 100 : 0;
+    }
+    const clamped = Math.max(0, Math.min(100, percent));
+    const filled = Math.round((clamped / 100) * width);
+    const empty = width - filled;
+    const bar = '█'.repeat(filled) + '░'.repeat(empty);
+    return `[${bar}] ${Math.round(clamped)}%`;
+}
+// ---------------------------------------------------------------------------
+// 5. generateReport
+// ---------------------------------------------------------------------------
+export function generateReport(input) {
+    const { metrics, comparison, history, session } = input;
+    const generatedAt = new Date().toISOString();
+    const startedAt = formatTimestamp(session.startedAt);
+    return [
+        `# SkillState Report: ${session.name}`,
+        '',
+        `- **Generated:** ${generatedAt}`,
+        `- **Platform:** ${session.platform}`,
+        `- **Session:** ${session.name}`,
+        `- **Started:** ${startedAt}`,
+        '',
+        '## Metrics',
+        '',
+        formatMetricsTable(metrics),
+        '',
+        '## Comparison',
+        '',
+        formatComparisonTable(comparison),
+        '',
+        '## Step History',
+        '',
+        formatStepHistory(history),
+        '',
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// 6. printDashboard
+// ---------------------------------------------------------------------------
+// Composes the full terminal dashboard as a string. Never prints — callers
+// decide whether to write it to the console.
+export function printDashboard(input) {
+    const { metrics, comparison, history, session, progress } = input;
+    const separator = paint('═'.repeat(60), CYAN);
+    const parts = [
+        separator,
+        paint('  SKILLSTATE DASHBOARD', BOLD),
+        separator,
+        '',
+        `Session: ${session.name} (${session.platform})`,
+        `Started: ${formatTimestamp(session.startedAt)}`,
+        '',
+        paint('── Metrics ' + '─'.repeat(47), DIM),
+        '',
+        formatMetricsTable(metrics),
+    ];
+    if (progress) {
+        parts.push('');
+        parts.push(`Budget: ${formatProgressBar(progress)} (${progress.used}/${progress.budget} chars)`);
+    }
+    parts.push('');
+    parts.push(paint('── Comparison ' + '─'.repeat(45), DIM));
+    parts.push('');
+    parts.push(formatComparisonTable(comparison));
+    parts.push('');
+    parts.push(paint('── Step History ' + '─'.repeat(43), DIM));
+    parts.push('');
+    parts.push(formatStepHistory(history));
+    parts.push('');
+    parts.push(separator);
+    return parts.join('\n');
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/dashboard.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './commands.js';
+export * from './dashboard.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// @skillstate/cli — skillstate CLI commands + dashboard.
+export * from './commands.js';
+export * from './dashboard.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@skillstate/cli",
+  "version": "2.0.0",
+  "description": "skillstate CLI — init | run | report.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "skillstate": "bin/skillstate.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "bin"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@skillstate/core": "^2.0.0"
+  }
+}