@graphorin/cli 0.6.1 → 0.7.0

package/src/commands/migrate-config.ts

@@ -0,0 +1,77 @@
+/**
+ * `graphorin migrate-config <input>` - config-schema migration helper.
+ *
+ * v0.1 ships exactly one config schema; the migrator is therefore a
+ * compatibility shell that round-trips the operator's config through
+ * `parseServerConfig(...)` and writes the canonical-shape JSON back to
+ * disk. Future MAJOR bumps replace this body with the rewriter that
+ * upgrades old field shapes; the CLI surface stays the same.
+ *
+ * The output path is always derived from the input - `migrate-config`
+ * writes `<input>.migrated` next to the source unless `--out` is
+ * supplied. The original is never modified.
+ *
+ * @packageDocumentation
+ */
+
+import { writeFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import process from 'node:process';
+
+import { parseServerConfig } from '@graphorin/server';
+
+import { loadConfig } from '../internal/load-config.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+
+/** @stable */
+export interface MigrateConfigOptions extends CommonOutputOptions {
+  readonly input: string;
+  readonly out?: string;
+}
+
+/** @stable */
+export interface MigrateConfigResult {
+  readonly input: string;
+  readonly output: string;
+  readonly schemaVersion: '0.1';
+}
+
+/** @stable */
+export async function runMigrateConfig(
+  options: MigrateConfigOptions,
+): Promise<MigrateConfigResult> {
+  const cwd = process.cwd();
+  const inputPath = isAbsolute(options.input) ? options.input : resolve(cwd, options.input);
+  const outputPath =
+    options.out !== undefined
+      ? isAbsolute(options.out)
+        ? options.out
+        : resolve(cwd, options.out)
+      : `${inputPath}.migrated.json`;
+  if (inputPath === outputPath) {
+    throw new Error(
+      `[graphorin/cli] migrate-config refuses to overwrite the input file '${inputPath}'.`,
+    );
+  }
+  const loaded = await loadConfig(inputPath);
+  const parsed = parseServerConfig(loaded.config);
+  await writeFile(outputPath, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+  const out: MigrateConfigResult = Object.freeze({
+    input: inputPath,
+    output: outputPath,
+    schemaVersion: '0.1',
+  });
+  emitReport(options, out, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand(`${statusMarker('ok')} migrated config v${out.schemaVersion}`));
+    print(`  input:  ${out.input}`);
+    print(`  output: ${out.output}`);
+  });
+  return out;
+}

package/src/commands/migrate-export.ts

@@ -0,0 +1,117 @@
+import pkg from '../../package.json' with { type: 'json' };
+/**
+ * `graphorin migrate-export <input> --to-schema <X.Y>` - schema-version
+ * migration for `graphorin-session-export/N.N` JSONL files (DEC-155 /
+ * ADR-042).
+ *
+ * The exporter ships schema 1.0 in v0.1; the migrator's main job today
+ * is to validate that the supplied input file is a well-formed session
+ * export with a schema in the framework's N-2 backwards-compat band
+ * and to round-trip the records through the writer with the desired
+ * target schema. When the runtime reaches MAJOR 2.x / 3.x the
+ * migrator extends the per-record transforms in place.
+ *
+ * The output path is required (`--to <file>`); the helper never
+ * overwrites the input.
+ *
+ * @packageDocumentation
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import process from 'node:process';
+
+import {
+  createBufferSink,
+  createSessionExportWriter,
+  readSessionExport,
+  SESSION_EXPORT_SCHEMA_CURRENT,
+  type SessionExportRecord,
+} from '@graphorin/sessions';
+
+import { EXIT_CODES } from '../internal/exit.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+
+/** @stable */
+export interface MigrateExportOptions extends CommonOutputOptions {
+  readonly input: string;
+  readonly to: string;
+  /** Defaults to the writer's current schema (e.g. `'1.0'`). */
+  readonly toSchema?: string;
+  /** Surfaced on the meta header. Defaults to `graphorin-cli@<version>` (the current package version). */
+  readonly writer?: string;
+}
+
+/** @stable */
+export interface MigrateExportResult {
+  readonly input: string;
+  readonly output: string;
+  readonly schemaIn: string;
+  readonly schemaOut: string;
+  readonly records: number;
+}
+
+/** @stable */
+export async function runMigrateExport(
+  options: MigrateExportOptions,
+): Promise<MigrateExportResult> {
+  const cwd = process.cwd();
+  const inputPath = isAbsolute(options.input) ? options.input : resolve(cwd, options.input);
+  const outputPath = isAbsolute(options.to) ? options.to : resolve(cwd, options.to);
+  const targetSchema = options.toSchema ?? SESSION_EXPORT_SCHEMA_CURRENT;
+
+  if (inputPath === outputPath) {
+    throw new Error(
+      `[graphorin/cli] migrate-export refuses to overwrite the input file '${inputPath}'.`,
+    );
+  }
+  if (targetSchema !== SESSION_EXPORT_SCHEMA_CURRENT) {
+    const print = options.print ?? defaultPrintSink;
+    print(
+      brand(
+        `requested target schema '${targetSchema}' is not the writer's current schema (${SESSION_EXPORT_SCHEMA_CURRENT}); v0.1 supports the current schema only.`,
+      ),
+    );
+    process.exit(EXIT_CODES.UNSUPPORTED);
+  }
+
+  const raw = await readFile(inputPath, 'utf8');
+  const parsed = readSessionExport(raw);
+
+  const buffer = createBufferSink();
+  const writer = createSessionExportWriter(buffer.sink, {
+    writer: options.writer ?? `graphorin-cli@${pkg.version}`,
+    ...(parsed.meta.embedderIds !== undefined ? { embedderIds: parsed.meta.embedderIds } : {}),
+  });
+  for (const record of parsed.records) {
+    if (record.kind === 'unknown') continue;
+    await writer.writeRecord(record as SessionExportRecord);
+  }
+  await writer.close();
+  await writeFile(outputPath, buffer.toString(), { mode: 0o600 });
+
+  const out: MigrateExportResult = Object.freeze({
+    input: inputPath,
+    output: outputPath,
+    schemaIn: parsed.meta.version,
+    schemaOut: targetSchema,
+    records: parsed.records.length,
+  });
+  emitReport(options, out, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(
+      brand(
+        `${statusMarker('ok')} migrated ${out.records} record(s) from schema ${out.schemaIn} -> ${out.schemaOut}`,
+      ),
+    );
+    print(`  input:  ${out.input}`);
+    print(`  output: ${out.output}`);
+  });
+  return out;
+}

package/src/commands/migrate.ts

@@ -0,0 +1,83 @@
+/**
+ * `graphorin migrate` - apply pending storage migrations.
+ *
+ * Idempotent: re-running the command after every migration has been
+ * applied is a no-op + a successful exit. Failures bubble up with the
+ * underlying SQLite error so operators can fix corrupted state.
+ *
+ * @packageDocumentation
+ */
+
+import process from 'node:process';
+
+import { parseServerConfig } from '@graphorin/server';
+import { createSqliteStore } from '@graphorin/store-sqlite';
+import { loadConfig } from '../internal/load-config.js';
+import { applyHardeningEarly } from './start.js';
+
+/**
+ * @stable
+ */
+export interface MigrateCommandOptions {
+  readonly config?: string;
+  readonly target?: string;
+  readonly print?: (line: string) => void;
+}
+
+/**
+ * @stable
+ */
+export interface MigrateCommandResult {
+  readonly applied: ReadonlyArray<string>;
+}
+
+/**
+ * @stable
+ */
+export async function runMigrate(
+  options: MigrateCommandOptions = {},
+): Promise<MigrateCommandResult> {
+  applyHardeningEarly();
+  const print = options.print ?? ((line: string) => process.stderr.write(`${line}\n`));
+  let loaded: Awaited<ReturnType<typeof loadConfig>>;
+  try {
+    loaded = await loadConfig(options.config);
+  } catch (err) {
+    print(`[graphorin/cli] ${(err as Error).message}`);
+    process.exit(1);
+  }
+  print(`[graphorin/cli] resolved config: ${loaded.path}`);
+
+  let parsed: ReturnType<typeof parseServerConfig>;
+  try {
+    parsed = parseServerConfig(loaded.config);
+  } catch (err) {
+    print(`[graphorin/cli] ${(err as Error).message}`);
+    process.exit(1);
+  }
+
+  if (options.target !== undefined) {
+    print(
+      `[graphorin/cli] --target is reserved for the Phase 15 migration runner; the v0.1 store applies every pending migration in order.`,
+    );
+  }
+
+  const store = await createSqliteStore({
+    path: parsed.storage.path,
+    mode: parsed.storage.mode,
+  });
+  try {
+    await store.init();
+    const ids = store.appliedMigrations.map((m) => `${m.version} (${m.name})`);
+    print(`[graphorin/cli] applied ${ids.length} migration(s):`);
+    for (const id of ids) {
+      print(`  - ${id}`);
+    }
+    return Object.freeze({ applied: Object.freeze(ids) });
+  } catch (err) {
+    print(`[graphorin/cli] migration failed: ${(err as Error).message}`);
+    process.exit(1);
+  } finally {
+    await store.close();
+  }
+}

package/src/commands/pricing.ts

@@ -0,0 +1,244 @@
+/**
+ * `graphorin pricing` - operate on the bundled LLM pricing snapshot.
+ *
+ * Surface (per Phase 15 § Pricing):
+ *
+ *  - `graphorin pricing status` - bundled snapshot version + entry
+ *    count + canonical digest.
+ *  - `graphorin pricing refresh --url <url>` - opt-in network call
+ *    that fetches a fresh snapshot. Honours `GRAPHORIN_OFFLINE=1`.
+ *  - `graphorin pricing diff` - row-by-row delta vs the bundled
+ *    snapshot.
+ *  - `graphorin pricing lookup --provider <name> --model <id>` - print
+ *    the per-token price for a single (provider, model) pair.
+ *  - `graphorin pricing missing` - read trace spans from a JSON file
+ *    and report unknown (provider, model) pairs.
+ *
+ * @packageDocumentation
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+
+import {
+  BUNDLED_SNAPSHOT,
+  computeEntriesDigest,
+  diffPricing,
+  listMissingModels,
+  lookupPrice,
+  type PricingDiffEntry,
+  type PricingSnapshot,
+  refreshPricing,
+  SNAPSHOT_DATE,
+} from '@graphorin/pricing';
+
+import { EXIT_CODES } from '../internal/exit.js';
+import { checkOfflineModeBlocked } from '../internal/offline.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+
+/** @stable */
+export interface PricingCommonOptions extends CommonOutputOptions {}
+
+/** @stable */
+export interface PricingStatusResult {
+  readonly version: string;
+  readonly snapshotDate: string;
+  readonly entries: number;
+  readonly digest: string;
+}
+
+/** @stable */
+export function runPricingStatus(options: PricingCommonOptions = {}): PricingStatusResult {
+  const out: PricingStatusResult = Object.freeze({
+    version: BUNDLED_SNAPSHOT.version,
+    snapshotDate: SNAPSHOT_DATE,
+    entries: BUNDLED_SNAPSHOT.entries.length,
+    digest: computeEntriesDigest(BUNDLED_SNAPSHOT.entries),
+  });
+  emitReport(options, out, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand(`pricing snapshot v${out.version} (${out.snapshotDate})`));
+    print(`  entries: ${out.entries}`);
+    print(`  digest:  ${out.digest}`);
+  });
+  return out;
+}
+
+/** @stable */
+export interface PricingRefreshOptions extends PricingCommonOptions {
+  readonly url: string;
+  /**
+   * Optional path to write the refreshed snapshot to. When omitted the
+   * CLI prints a status summary only; `--out` triggers a JSON write.
+   */
+  readonly out?: string;
+  /**
+   * W-097: accepted body format - `auto` (default) tries the native
+   * shape then auto-detects the `@pydantic/genai-prices` dataset.
+   */
+  readonly format?: 'auto' | 'graphorin' | 'genai-prices';
+  /** Test seam - inject a fetch implementation. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+/** @stable */
+export async function runPricingRefresh(options: PricingRefreshOptions): Promise<{
+  readonly entries: number;
+  readonly version: string;
+  readonly out?: string;
+  readonly skipped?: number;
+}> {
+  if (
+    !checkOfflineModeBlocked('pricing refresh', {
+      ...(options.print !== undefined ? { print: options.print } : {}),
+    })
+  ) {
+    process.exit(EXIT_CODES.RECOVERABLE_FAILURE);
+  }
+  const refreshed = await refreshPricing({
+    url: options.url,
+    ...(options.format !== undefined ? { format: options.format } : {}),
+    ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+  });
+  if (options.out !== undefined) {
+    await writeFile(options.out, JSON.stringify(refreshed, null, 2), { mode: 0o600 });
+  }
+  const result: { entries: number; version: string; out?: string; skipped?: number } = {
+    entries: refreshed.entries.length,
+    version: refreshed.version,
+    ...(options.out !== undefined ? { out: options.out } : {}),
+    ...(refreshed.conversion !== undefined ? { skipped: refreshed.conversion.skipped } : {}),
+  };
+  emitReport(options, result, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand(`refreshed pricing snapshot v${result.version} (${result.entries} entries).`));
+    if (result.skipped !== undefined) {
+      print(
+        brand(
+          `converted from genai-prices; ${result.skipped} entr${result.skipped === 1 ? 'y' : 'ies'} skipped (tiered/conditional pricing).`,
+        ),
+      );
+    }
+    if (result.out !== undefined) print(brand(`written to ${result.out} (mode 0600).`));
+  });
+  return result;
+}
+
+/** @stable */
+export interface PricingDiffOptions extends PricingCommonOptions {
+  /**
+   * Path to a JSON file containing a `PricingSnapshot`. The CLI diffs
+   * this against the bundled snapshot.
+   */
+  readonly snapshot: string;
+}
+
+/** @stable */
+export async function runPricingDiff(
+  options: PricingDiffOptions,
+): Promise<ReadonlyArray<PricingDiffEntry>> {
+  const right = await readSnapshot(options.snapshot);
+  const diff = diffPricing(BUNDLED_SNAPSHOT, right);
+  emitReport(options, diff, () => {
+    const print = options.print ?? defaultPrintSink;
+    if (diff.length === 0) {
+      print(brand('no diff between bundled snapshot and supplied snapshot.'));
+      return;
+    }
+    print(brand(`${diff.length} pricing diff row(s):`));
+    for (const row of diff) {
+      print(`  ${statusMarker('warn')} ${row.kind} ${row.provider}/${row.model}`);
+    }
+  });
+  return diff;
+}
+
+/** @stable */
+export interface PricingLookupOptions extends PricingCommonOptions {
+  readonly provider: string;
+  readonly model: string;
+  readonly region?: string;
+}
+
+/** @stable */
+export function runPricingLookup(options: PricingLookupOptions) {
+  const result = lookupPrice({
+    provider: options.provider,
+    model: options.model,
+    ...(options.region !== undefined ? { region: options.region } : {}),
+  });
+  emitReport(options, result, () => {
+    const print = options.print ?? defaultPrintSink;
+    if (result === null) {
+      print(brand(`no pricing entry for ${options.provider}/${options.model}.`));
+      return;
+    }
+    print(
+      brand(
+        `${options.provider}/${options.model}: input=${result.inputUsdPerToken} / output=${result.outputUsdPerToken} USD per token (source=${result.source}, snapshot=${result.snapshotDate})`,
+      ),
+    );
+  });
+  // W-002: exit code independent of --json (see runAuditVerify).
+  if (result === null) process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+  return result;
+}
+
+/** @stable */
+export interface PricingMissingOptions extends PricingCommonOptions {
+  /**
+   * Path to a JSON file containing an array of trace spans (each with
+   * an `attributes` map). Output of `graphorin traces export` (Phase
+   * 15) is the canonical source.
+   */
+  readonly spans: string;
+}
+
+/** @stable */
+export async function runPricingMissing(options: PricingMissingOptions) {
+  const raw = await readFile(options.spans, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `[graphorin/cli] '${options.spans}' is not valid JSON: ${(err as Error).message}`,
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`[graphorin/cli] '${options.spans}' must contain an array of trace spans.`);
+  }
+  // The pricing helper trusts the shape; we cast through unknown.
+  const missing = listMissingModels(
+    parsed as ReadonlyArray<{ readonly attributes: Record<string, unknown> }>,
+  );
+  emitReport(options, missing, () => {
+    const print = options.print ?? defaultPrintSink;
+    if (missing.length === 0) {
+      print(brand('every (provider, model) pair in the spans is present in the bundled snapshot.'));
+      return;
+    }
+    print(brand(`${missing.length} unknown (provider, model) pair(s):`));
+    for (const m of missing) {
+      print(`  ${statusMarker('warn')} ${m.provider}/${m.model} (${m.count} span(s))`);
+    }
+  });
+  return missing;
+}
+
+async function readSnapshot(path: string): Promise<PricingSnapshot> {
+  const raw = await readFile(path, 'utf8');
+  try {
+    return JSON.parse(raw) as PricingSnapshot;
+  } catch (err) {
+    throw new Error(
+      `[graphorin/cli] '${path}' is not a valid pricing snapshot JSON: ${(err as Error).message}`,
+    );
+  }
+}