@graphorin/cli 0.5.0

package/dist/commands/migrate-export.d.ts

@@ -0,0 +1,26 @@
+import { CommonOutputOptions } from "../internal/output.js";
+
+//#region src/commands/migrate-export.d.ts
+
+/** @stable */
+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@0.5.0'`. */
+  readonly writer?: string;
+}
+/** @stable */
+interface MigrateExportResult {
+  readonly input: string;
+  readonly output: string;
+  readonly schemaIn: string;
+  readonly schemaOut: string;
+  readonly records: number;
+}
+/** @stable */
+declare function runMigrateExport(options: MigrateExportOptions): Promise<MigrateExportResult>;
+//#endregion
+export { MigrateExportOptions, MigrateExportResult, runMigrateExport };
+//# sourceMappingURL=migrate-export.d.ts.map

package/dist/commands/migrate-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-export.d.ts","names":[],"sources":["../../src/commands/migrate-export.ts"],"sourcesContent":[],"mappings":";;;;;UAwCiB,oBAAA,SAA6B;;;;;;;;;UAU7B,mBAAA;;;;;;;;iBASK,gBAAA,UACX,uBACR,QAAQ"}

package/dist/commands/migrate-export.js

@@ -0,0 +1,67 @@
+import { brand, defaultPrintSink, emitReport, statusMarker } from "../internal/output.js";
+import { EXIT_CODES } from "../internal/exit.js";
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import process from "node:process";
+import { SESSION_EXPORT_SCHEMA_CURRENT, createBufferSink, createSessionExportWriter, readSessionExport } from "@graphorin/sessions";
+
+//#region src/commands/migrate-export.ts
+/**
+* `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
+*/
+/** @stable */
+async function runMigrateExport(options) {
+	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) {
+		(options.print ?? defaultPrintSink)(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 parsed = readSessionExport(await readFile(inputPath, "utf8"));
+	const buffer = createBufferSink();
+	const writer = createSessionExportWriter(buffer.sink, {
+		writer: options.writer ?? "graphorin-cli@0.5.0",
+		...parsed.meta.embedderIds !== void 0 ? { embedderIds: parsed.meta.embedderIds } : {}
+	});
+	for (const record of parsed.records) {
+		if (record.kind === "unknown") continue;
+		await writer.writeRecord(record);
+	}
+	await writer.close();
+	await writeFile(outputPath, buffer.toString(), { mode: 384 });
+	const out = 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;
+}
+
+//#endregion
+export { runMigrateExport };
+//# sourceMappingURL=migrate-export.js.map

package/dist/commands/migrate-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-export.js","names":["out: MigrateExportResult"],"sources":["../../src/commands/migrate-export.ts"],"sourcesContent":["/**\n * `graphorin migrate-export <input> --to-schema <X.Y>` — schema-version\n * migration for `graphorin-session-export/N.N` JSONL files (DEC-155 /\n * ADR-042).\n *\n * The exporter ships schema 1.0 in v0.1; the migrator's main job today\n * is to validate that the supplied input file is a well-formed session\n * export with a schema in the framework's N-2 backwards-compat band\n * and to round-trip the records through the writer with the desired\n * target schema. When the runtime reaches MAJOR 2.x / 3.x the\n * migrator extends the per-record transforms in place.\n *\n * The output path is required (`--to <file>`); the helper never\n * overwrites the input.\n *\n * @packageDocumentation\n */\n\nimport { readFile, writeFile } from 'node:fs/promises';\nimport { isAbsolute, resolve } from 'node:path';\nimport process from 'node:process';\n\nimport {\n  createBufferSink,\n  createSessionExportWriter,\n  readSessionExport,\n  SESSION_EXPORT_SCHEMA_CURRENT,\n  type SessionExportRecord,\n} from '@graphorin/sessions';\n\nimport { EXIT_CODES } from '../internal/exit.js';\nimport {\n  brand,\n  type CommonOutputOptions,\n  defaultPrintSink,\n  emitReport,\n  statusMarker,\n} from '../internal/output.js';\n\n/** @stable */\nexport interface MigrateExportOptions extends CommonOutputOptions {\n  readonly input: string;\n  readonly to: string;\n  /** Defaults to the writer's current schema (e.g. `'1.0'`). */\n  readonly toSchema?: string;\n  /** Surfaced on the meta header. Defaults to `'graphorin-cli@0.5.0'`. */\n  readonly writer?: string;\n}\n\n/** @stable */\nexport interface MigrateExportResult {\n  readonly input: string;\n  readonly output: string;\n  readonly schemaIn: string;\n  readonly schemaOut: string;\n  readonly records: number;\n}\n\n/** @stable */\nexport async function runMigrateExport(\n  options: MigrateExportOptions,\n): Promise<MigrateExportResult> {\n  const cwd = process.cwd();\n  const inputPath = isAbsolute(options.input) ? options.input : resolve(cwd, options.input);\n  const outputPath = isAbsolute(options.to) ? options.to : resolve(cwd, options.to);\n  const targetSchema = options.toSchema ?? SESSION_EXPORT_SCHEMA_CURRENT;\n\n  if (inputPath === outputPath) {\n    throw new Error(\n      `[graphorin/cli] migrate-export refuses to overwrite the input file '${inputPath}'.`,\n    );\n  }\n  if (targetSchema !== SESSION_EXPORT_SCHEMA_CURRENT) {\n    const print = options.print ?? defaultPrintSink;\n    print(\n      brand(\n        `requested target schema '${targetSchema}' is not the writer's current schema (${SESSION_EXPORT_SCHEMA_CURRENT}); v0.1 supports the current schema only.`,\n      ),\n    );\n    process.exit(EXIT_CODES.UNSUPPORTED);\n  }\n\n  const raw = await readFile(inputPath, 'utf8');\n  const parsed = readSessionExport(raw);\n\n  const buffer = createBufferSink();\n  const writer = createSessionExportWriter(buffer.sink, {\n    writer: options.writer ?? 'graphorin-cli@0.5.0',\n    ...(parsed.meta.embedderIds !== undefined ? { embedderIds: parsed.meta.embedderIds } : {}),\n  });\n  for (const record of parsed.records) {\n    if (record.kind === 'unknown') continue;\n    await writer.writeRecord(record as SessionExportRecord);\n  }\n  await writer.close();\n  await writeFile(outputPath, buffer.toString(), { mode: 0o600 });\n\n  const out: MigrateExportResult = Object.freeze({\n    input: inputPath,\n    output: outputPath,\n    schemaIn: parsed.meta.version,\n    schemaOut: targetSchema,\n    records: parsed.records.length,\n  });\n  emitReport(options, out, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(\n      brand(\n        `${statusMarker('ok')} migrated ${out.records} record(s) from schema ${out.schemaIn} -> ${out.schemaOut}`,\n      ),\n    );\n    print(`  input:  ${out.input}`);\n    print(`  output: ${out.output}`);\n  });\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,eAAsB,iBACpB,SAC8B;CAC9B,MAAM,MAAM,QAAQ,KAAK;CACzB,MAAM,YAAY,WAAW,QAAQ,MAAM,GAAG,QAAQ,QAAQ,QAAQ,KAAK,QAAQ,MAAM;CACzF,MAAM,aAAa,WAAW,QAAQ,GAAG,GAAG,QAAQ,KAAK,QAAQ,KAAK,QAAQ,GAAG;CACjF,MAAM,eAAe,QAAQ,YAAY;AAEzC,KAAI,cAAc,WAChB,OAAM,IAAI,MACR,uEAAuE,UAAU,IAClF;AAEH,KAAI,iBAAiB,+BAA+B;AAElD,GADc,QAAQ,SAAS,kBAE7B,MACE,4BAA4B,aAAa,wCAAwC,8BAA8B,2CAChH,CACF;AACD,UAAQ,KAAK,WAAW,YAAY;;CAItC,MAAM,SAAS,kBADH,MAAM,SAAS,WAAW,OAAO,CACR;CAErC,MAAM,SAAS,kBAAkB;CACjC,MAAM,SAAS,0BAA0B,OAAO,MAAM;EACpD,QAAQ,QAAQ,UAAU;EAC1B,GAAI,OAAO,KAAK,gBAAgB,SAAY,EAAE,aAAa,OAAO,KAAK,aAAa,GAAG,EAAE;EAC1F,CAAC;AACF,MAAK,MAAM,UAAU,OAAO,SAAS;AACnC,MAAI,OAAO,SAAS,UAAW;AAC/B,QAAM,OAAO,YAAY,OAA8B;;AAEzD,OAAM,OAAO,OAAO;AACpB,OAAM,UAAU,YAAY,OAAO,UAAU,EAAE,EAAE,MAAM,KAAO,CAAC;CAE/D,MAAMA,MAA2B,OAAO,OAAO;EAC7C,OAAO;EACP,QAAQ;EACR,UAAU,OAAO,KAAK;EACtB,WAAW;EACX,SAAS,OAAO,QAAQ;EACzB,CAAC;AACF,YAAW,SAAS,WAAW;EAC7B,MAAM,QAAQ,QAAQ,SAAS;AAC/B,QACE,MACE,GAAG,aAAa,KAAK,CAAC,YAAY,IAAI,QAAQ,yBAAyB,IAAI,SAAS,MAAM,IAAI,YAC/F,CACF;AACD,QAAM,aAAa,IAAI,QAAQ;AAC/B,QAAM,aAAa,IAAI,SAAS;GAChC;AACF,QAAO"}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,31 @@
+//#region src/commands/migrate.d.ts
+/**
+ * `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
+ */
+/**
+ * @stable
+ */
+interface MigrateCommandOptions {
+  readonly config?: string;
+  readonly target?: string;
+  readonly print?: (line: string) => void;
+}
+/**
+ * @stable
+ */
+interface MigrateCommandResult {
+  readonly applied: ReadonlyArray<string>;
+}
+/**
+ * @stable
+ */
+declare function runMigrate(options?: MigrateCommandOptions): Promise<MigrateCommandResult>;
+//#endregion
+export { MigrateCommandOptions, MigrateCommandResult, runMigrate };
+//# sourceMappingURL=migrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","names":[],"sources":["../../src/commands/migrate.ts"],"sourcesContent":[],"mappings":";;AAoBA;AASA;AAOA;;;;;;;;;UAhBiB,qBAAA;;;;;;;;UASA,oBAAA;oBACG;;;;;iBAME,UAAA,WACX,wBACR,QAAQ"}

package/dist/commands/migrate.js

@@ -0,0 +1,59 @@
+import { loadConfig } from "../internal/load-config.js";
+import { applyHardeningEarly } from "./start.js";
+import process from "node:process";
+import { parseServerConfig } from "@graphorin/server";
+import { createSqliteStore } from "@graphorin/store-sqlite";
+
+//#region src/commands/migrate.ts
+/**
+* `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
+*/
+/**
+* @stable
+*/
+async function runMigrate(options = {}) {
+	applyHardeningEarly();
+	const print = options.print ?? ((line) => process.stderr.write(`${line}\n`));
+	let loaded;
+	try {
+		loaded = await loadConfig(options.config);
+	} catch (err) {
+		print(`[graphorin/cli] ${err.message}`);
+		process.exit(1);
+	}
+	print(`[graphorin/cli] resolved config: ${loaded.path}`);
+	let parsed;
+	try {
+		parsed = parseServerConfig(loaded.config);
+	} catch (err) {
+		print(`[graphorin/cli] ${err.message}`);
+		process.exit(1);
+	}
+	if (options.target !== void 0) 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.message}`);
+		process.exit(1);
+	} finally {
+		await store.close();
+	}
+}
+
+//#endregion
+export { runMigrate };
+//# sourceMappingURL=migrate.js.map

package/dist/commands/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","names":["loaded: Awaited<ReturnType<typeof loadConfig>>","parsed: ReturnType<typeof parseServerConfig>"],"sources":["../../src/commands/migrate.ts"],"sourcesContent":["/**\n * `graphorin migrate` — apply pending storage migrations.\n *\n * Idempotent: re-running the command after every migration has been\n * applied is a no-op + a successful exit. Failures bubble up with the\n * underlying SQLite error so operators can fix corrupted state.\n *\n * @packageDocumentation\n */\n\nimport process from 'node:process';\n\nimport { parseServerConfig } from '@graphorin/server';\nimport { createSqliteStore } from '@graphorin/store-sqlite';\nimport { loadConfig } from '../internal/load-config.js';\nimport { applyHardeningEarly } from './start.js';\n\n/**\n * @stable\n */\nexport interface MigrateCommandOptions {\n  readonly config?: string;\n  readonly target?: string;\n  readonly print?: (line: string) => void;\n}\n\n/**\n * @stable\n */\nexport interface MigrateCommandResult {\n  readonly applied: ReadonlyArray<string>;\n}\n\n/**\n * @stable\n */\nexport async function runMigrate(\n  options: MigrateCommandOptions = {},\n): Promise<MigrateCommandResult> {\n  applyHardeningEarly();\n  const print = options.print ?? ((line: string) => process.stderr.write(`${line}\\n`));\n  let loaded: Awaited<ReturnType<typeof loadConfig>>;\n  try {\n    loaded = await loadConfig(options.config);\n  } catch (err) {\n    print(`[graphorin/cli] ${(err as Error).message}`);\n    process.exit(1);\n  }\n  print(`[graphorin/cli] resolved config: ${loaded.path}`);\n\n  let parsed: ReturnType<typeof parseServerConfig>;\n  try {\n    parsed = parseServerConfig(loaded.config);\n  } catch (err) {\n    print(`[graphorin/cli] ${(err as Error).message}`);\n    process.exit(1);\n  }\n\n  if (options.target !== undefined) {\n    print(\n      `[graphorin/cli] --target is reserved for the Phase 15 migration runner; the v0.1 store applies every pending migration in order.`,\n    );\n  }\n\n  const store = await createSqliteStore({\n    path: parsed.storage.path,\n    mode: parsed.storage.mode,\n  });\n  try {\n    await store.init();\n    const ids = store.appliedMigrations.map((m) => `${m.version} (${m.name})`);\n    print(`[graphorin/cli] applied ${ids.length} migration(s):`);\n    for (const id of ids) {\n      print(`  - ${id}`);\n    }\n    return Object.freeze({ applied: Object.freeze(ids) });\n  } catch (err) {\n    print(`[graphorin/cli] migration failed: ${(err as Error).message}`);\n    process.exit(1);\n  } finally {\n    await store.close();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAoCA,eAAsB,WACpB,UAAiC,EAAE,EACJ;AAC/B,sBAAqB;CACrB,MAAM,QAAQ,QAAQ,WAAW,SAAiB,QAAQ,OAAO,MAAM,GAAG,KAAK,IAAI;CACnF,IAAIA;AACJ,KAAI;AACF,WAAS,MAAM,WAAW,QAAQ,OAAO;UAClC,KAAK;AACZ,QAAM,mBAAoB,IAAc,UAAU;AAClD,UAAQ,KAAK,EAAE;;AAEjB,OAAM,oCAAoC,OAAO,OAAO;CAExD,IAAIC;AACJ,KAAI;AACF,WAAS,kBAAkB,OAAO,OAAO;UAClC,KAAK;AACZ,QAAM,mBAAoB,IAAc,UAAU;AAClD,UAAQ,KAAK,EAAE;;AAGjB,KAAI,QAAQ,WAAW,OACrB,OACE,mIACD;CAGH,MAAM,QAAQ,MAAM,kBAAkB;EACpC,MAAM,OAAO,QAAQ;EACrB,MAAM,OAAO,QAAQ;EACtB,CAAC;AACF,KAAI;AACF,QAAM,MAAM,MAAM;EAClB,MAAM,MAAM,MAAM,kBAAkB,KAAK,MAAM,GAAG,EAAE,QAAQ,IAAI,EAAE,KAAK,GAAG;AAC1E,QAAM,2BAA2B,IAAI,OAAO,gBAAgB;AAC5D,OAAK,MAAM,MAAM,IACf,OAAM,OAAO,KAAK;AAEpB,SAAO,OAAO,OAAO,EAAE,SAAS,OAAO,OAAO,IAAI,EAAE,CAAC;UAC9C,KAAK;AACZ,QAAM,qCAAsC,IAAc,UAAU;AACpE,UAAQ,KAAK,EAAE;WACP;AACR,QAAM,MAAM,OAAO"}

package/dist/commands/pricing.d.ts

@@ -0,0 +1,66 @@
+import { CommonOutputOptions } from "../internal/output.js";
+import * as _graphorin_pricing0 from "@graphorin/pricing";
+import { PricingDiffEntry } from "@graphorin/pricing";
+
+//#region src/commands/pricing.d.ts
+
+/** @stable */
+interface PricingCommonOptions extends CommonOutputOptions {}
+/** @stable */
+interface PricingStatusResult {
+  readonly version: string;
+  readonly snapshotDate: string;
+  readonly entries: number;
+  readonly digest: string;
+}
+/** @stable */
+declare function runPricingStatus(options?: PricingCommonOptions): PricingStatusResult;
+/** @stable */
+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;
+  /** Test seam — inject a fetch implementation. */
+  readonly fetchImpl?: typeof fetch;
+}
+/** @stable */
+declare function runPricingRefresh(options: PricingRefreshOptions): Promise<{
+  readonly entries: number;
+  readonly version: string;
+  readonly out?: string;
+}>;
+/** @stable */
+interface PricingDiffOptions extends PricingCommonOptions {
+  /**
+   * Path to a JSON file containing a `PricingSnapshot`. The CLI diffs
+   * this against the bundled snapshot.
+   */
+  readonly snapshot: string;
+}
+/** @stable */
+declare function runPricingDiff(options: PricingDiffOptions): Promise<ReadonlyArray<PricingDiffEntry>>;
+/** @stable */
+interface PricingLookupOptions extends PricingCommonOptions {
+  readonly provider: string;
+  readonly model: string;
+  readonly region?: string;
+}
+/** @stable */
+declare function runPricingLookup(options: PricingLookupOptions): _graphorin_pricing0.LookupPriceResult | null;
+/** @stable */
+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 */
+declare function runPricingMissing(options: PricingMissingOptions): Promise<readonly _graphorin_pricing0.MissingModelEntry[]>;
+//#endregion
+export { PricingCommonOptions, PricingDiffOptions, PricingLookupOptions, PricingMissingOptions, PricingRefreshOptions, PricingStatusResult, runPricingDiff, runPricingLookup, runPricingMissing, runPricingRefresh, runPricingStatus };
+//# sourceMappingURL=pricing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","names":[],"sources":["../../src/commands/pricing.ts"],"sourcesContent":[],"mappings":";;;;;;AAyLA;AAAiD,UA5IhC,oBAAA,SAA6B,mBA4IG,CAAA;;AAAqB,UAzIrD,mBAAA,CAyIqD;;;;;;;iBAjItD,gBAAA,WAA0B,uBAA4B;;UAiBrD,qBAAA,SAA8B;;;;;;;;8BAQjB;;;iBAIR,iBAAA,UACX,wBACR;;;;;;UA6Bc,kBAAA,SAA2B;;;;;;;;iBAStB,cAAA,UACX,qBACR,QAAQ,cAAc;;UAkBR,oBAAA,SAA6B;;;;;;iBAO9B,gBAAA,UAA0B,uBAAoB,mBAAA,CAAA,iBAAA;;UAuB7C,qBAAA,SAA8B;;;;;;;;;iBAUzB,iBAAA,UAA2B,wBAAqB,iBAAA,mBAAA,CAAA,iBAAA"}

package/dist/commands/pricing.js

@@ -0,0 +1,128 @@
+import { brand, defaultPrintSink, emitReport, statusMarker } from "../internal/output.js";
+import { EXIT_CODES } from "../internal/exit.js";
+import { checkOfflineModeBlocked } from "../internal/offline.js";
+import { readFile, writeFile } from "node:fs/promises";
+import process from "node:process";
+import { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest, diffPricing, listMissingModels, lookupPrice, refreshPricing } from "@graphorin/pricing";
+
+//#region src/commands/pricing.ts
+/**
+* `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
+*/
+/** @stable */
+function runPricingStatus(options = {}) {
+	const out = 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 */
+async function runPricingRefresh(options) {
+	if (!checkOfflineModeBlocked("pricing refresh", { ...options.print !== void 0 ? { print: options.print } : {} })) process.exit(EXIT_CODES.RECOVERABLE_FAILURE);
+	const refreshed = await refreshPricing({
+		url: options.url,
+		...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {}
+	});
+	if (options.out !== void 0) await writeFile(options.out, JSON.stringify(refreshed, null, 2), { mode: 384 });
+	const result = {
+		entries: refreshed.entries.length,
+		version: refreshed.version,
+		...options.out !== void 0 ? { out: options.out } : {}
+	};
+	emitReport(options, result, () => {
+		const print = options.print ?? defaultPrintSink;
+		print(brand(`refreshed pricing snapshot v${result.version} (${result.entries} entries).`));
+		if (result.out !== void 0) print(brand(`written to ${result.out} (mode 0600).`));
+	});
+	return result;
+}
+/** @stable */
+async function runPricingDiff(options) {
+	const diff = diffPricing(BUNDLED_SNAPSHOT, await readSnapshot(options.snapshot));
+	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 */
+function runPricingLookup(options) {
+	const result = lookupPrice({
+		provider: options.provider,
+		model: options.model,
+		...options.region !== void 0 ? { region: options.region } : {}
+	});
+	emitReport(options, result, () => {
+		const print = options.print ?? defaultPrintSink;
+		if (result === null) {
+			print(brand(`no pricing entry for ${options.provider}/${options.model}.`));
+			process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+			return;
+		}
+		print(brand(`${options.provider}/${options.model}: input=${result.inputUsdPerToken} / output=${result.outputUsdPerToken} USD per token (source=${result.source}, snapshot=${result.snapshotDate})`));
+	});
+	return result;
+}
+/** @stable */
+async function runPricingMissing(options) {
+	const raw = await readFile(options.spans, "utf8");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`[graphorin/cli] '${options.spans}' is not valid JSON: ${err.message}`);
+	}
+	if (!Array.isArray(parsed)) throw new Error(`[graphorin/cli] '${options.spans}' must contain an array of trace spans.`);
+	const missing = listMissingModels(parsed);
+	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) {
+	const raw = await readFile(path, "utf8");
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`[graphorin/cli] '${path}' is not a valid pricing snapshot JSON: ${err.message}`);
+	}
+}
+
+//#endregion
+export { runPricingDiff, runPricingLookup, runPricingMissing, runPricingRefresh, runPricingStatus };
+//# sourceMappingURL=pricing.js.map

package/dist/commands/pricing.js.map

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

package/dist/commands/secrets.d.ts

@@ -0,0 +1,96 @@
+import { CommonOutputOptions } from "../internal/output.js";
+import { SecretsStoreKind } from "@graphorin/security";
+import { SecretMetadata } from "@graphorin/core/contracts";
+
+//#region src/commands/secrets.d.ts
+
+/** @stable */
+interface SecretsCommonOptions extends CommonOutputOptions {
+  /** Mirrors `--secrets-source` per DEC-136. */
+  readonly secretsSource?: SecretsStoreKind;
+  /** Mirrors `--strict-secrets` per DEC-136. */
+  readonly strictSecrets?: boolean;
+}
+/** @stable */
+interface SecretsListOptions extends SecretsCommonOptions {}
+/** @stable */
+declare function runSecretsList(options?: SecretsListOptions): Promise<ReadonlyArray<SecretMetadata>>;
+/** @stable */
+interface SecretsGetOptions extends SecretsCommonOptions {
+  readonly key: string;
+  /**
+   * When `true`, print the raw value through the human report. The
+   * default is to print only structured metadata so the bytes do not
+   * surface in shell history.
+   */
+  readonly reveal?: boolean;
+}
+/** @stable */
+interface SecretsGetResult {
+  readonly key: string;
+  readonly found: boolean;
+  /** Only present when `reveal: true` AND the secret exists. */
+  readonly value?: string;
+}
+/** @stable */
+declare function runSecretsGet(options: SecretsGetOptions): Promise<SecretsGetResult>;
+/** @stable */
+interface SecretsSetOptions extends SecretsCommonOptions {
+  readonly key: string;
+  readonly value?: string;
+  /** When `true`, read the value from stdin. */
+  readonly fromStdin?: boolean;
+}
+/** @stable */
+declare function runSecretsSet(options: SecretsSetOptions): Promise<{
+  readonly ok: true;
+}>;
+/** @stable */
+interface SecretsDeleteOptions extends SecretsCommonOptions {
+  readonly key: string;
+}
+/** @stable */
+declare function runSecretsDelete(options: SecretsDeleteOptions): Promise<{
+  readonly ok: true;
+}>;
+/** @stable */
+interface SecretsRefOptions extends CommonOutputOptions {
+  readonly uri: string;
+  readonly reveal?: boolean;
+}
+/** @stable */
+interface SecretsRefResult {
+  readonly uri: string;
+  readonly scheme: string;
+  readonly resolved: boolean;
+  readonly length?: number;
+  readonly value?: string;
+}
+/**
+ * Test resolution of a `SecretRef` URI. The CLI parses the URI first
+ * (sanity check + scheme echo), then resolves through the registered
+ * resolver chain.
+ *
+ * @stable
+ */
+declare function runSecretsRef(options: SecretsRefOptions): Promise<SecretsRefResult>;
+/** @stable */
+interface SecretsRotateOptions extends SecretsCommonOptions {
+  readonly key: string;
+  readonly newValue?: string;
+  readonly fromStdin?: boolean;
+}
+/**
+ * `graphorin secrets rotate <key>` — overwrite the existing value
+ * with a fresh one. Functionally identical to `set` but the CLI
+ * surfaces the operation explicitly so audit logs can distinguish
+ * a rotation from an initial write.
+ *
+ * @stable
+ */
+declare function runSecretsRotate(options: SecretsRotateOptions): Promise<{
+  readonly ok: true;
+}>;
+//#endregion
+export { SecretsCommonOptions, SecretsDeleteOptions, SecretsGetOptions, SecretsGetResult, SecretsListOptions, SecretsRefOptions, SecretsRefResult, SecretsRotateOptions, SecretsSetOptions, runSecretsDelete, runSecretsGet, runSecretsList, runSecretsRef, runSecretsRotate, runSecretsSet };
+//# sourceMappingURL=secrets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","names":[],"sources":["../../src/commands/secrets.ts"],"sourcesContent":[],"mappings":";;;;;;AAqMA;AAA6C,UAvJ5B,oBAAA,SAA6B,mBAuJD,CAAA;EAA4B;EAAR,SAAA,aAAA,CAAA,EArJtC,gBAqJsC;EAAO;EAwCvD,SAAA,aAAA,CAAqB,EAAA,OAAA;AActC;;UArMiB,kBAAA,SAA2B;;iBAGtB,cAAA,WACX,qBACR,QAAQ,cAAc;;UAkBR,iBAAA,SAA0B;;;;;;;;;;UAW1B,gBAAA;;;;;;;iBAQK,aAAA,UAAuB,oBAAoB,QAAQ;;UA+BxD,iBAAA,SAA0B;;;;;;;iBAQrB,aAAA,UAAuB,oBAAoB;;;;UAuBhD,oBAAA,SAA6B;;;;iBAKxB,gBAAA,UACX,uBACR;;;;UAWc,iBAAA,SAA0B;;;;;UAM1B,gBAAA;;;;;;;;;;;;;;iBAeK,aAAA,UAAuB,oBAAoB,QAAQ;;UAwCxD,oBAAA,SAA6B;;;;;;;;;;;;;iBAcxB,gBAAA,UACX,uBACR"}