@trazum/cli 1.50.1 → 1.50.3

package/src/index.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
-import { join, resolve as resolvePath } from 'node:path';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
 
 import {
@@ -37,6 +39,7 @@ import {
   DEFAULT_USAGE,
   budgetPositions,
   conform,
+  FAILURE_POLICIES,
   detectFromSource,
   matchLocale,
   parsePlanDocument,
@@ -131,6 +134,8 @@ import type {
 import type {
   BudgetReport,
   ContractName,
+  FailurePolicy,
+  GatewayStanding,
   UsageProfileReport,
   WaiverUse,
   InitDecline,
@@ -177,6 +182,12 @@ import { fetchProviderUsage, findCredential } from './connect.js';
 import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
 import { WAIVER_LOG, appendWaiverUse, readWaiverLog } from './waiver-log.js';
 import { DEFAULT_PORT, buildServer, listen } from './serve.js';
+import {
+  DEFAULT_GATEWAY_PORT,
+  UPSTREAMS,
+  buildGateway,
+  listenGateway,
+} from './gateway-server.js';
 import {
   WATCH_STATE_VERSION,
   checkWebhook,
@@ -231,6 +242,7 @@ interface Args {
 const VALUE_FLAGS = new Set([
   'against',
   'contract',
+  'on-cannot-tell',
   'from-log',
   'min-usd',
   'payload',
@@ -528,7 +540,7 @@ function disabledRules(args: Args, config: TrazumConfig): RuleId[] | undefined {
  * a threshold is set — `--max-growh 5` would have been ignored and the build
  * gone green. Silence is the wrong answer for a typo.
  */
-const GLOBAL_FLAGS = ['help', 'h', 'locale', 'json', 'config', 'pricing', 'pricing-live'];
+const GLOBAL_FLAGS = ['help', 'h', 'version', 'v', 'locale', 'json', 'config', 'pricing', 'pricing-live'];
 const COMMAND_FLAGS: Record<string, string[]> = {
   optimize: [
     'level', 'model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch',
@@ -554,6 +566,8 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   rank: ['level', 'model', 'calls', 'output-tokens', 'batch', 'disable', 'prompt', 'markdown-out'],
   init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
   conform: ['contract', 'json'],
+  feedback: [],
+  gateway: ['on-cannot-tell', 'port', 'socket', 'pricing', 'pricing-live'],
   where: [],
   rules: [],
   blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -1476,6 +1490,44 @@ const INIT_LOG_CANDIDATES = [
  * nobody has vouched for.
  */
 
+/**
+ * Where feedback goes. Compiled in, never configurable.
+ *
+ * A flag or a config key naming this host would let a fork — or anything that
+ * had rewritten a config on disk — point somebody's bug report, and the
+ * prefilled body with it, at a machine they did not choose. It is one string
+ * and it stays one string.
+ */
+/**
+ * Which Trazum this is.
+ *
+ * Read from the manifest beside the built entry point rather than baked in by
+ * a generator, so it cannot drift from what npm installed — the one number a
+ * bug report is useless without is the one that must not be a copy.
+ *
+ * `readFileSync` at module load, deliberately: every other read in this file
+ * is async and inside a command, but a version has to be available to
+ * `--version` before any command is chosen, and one small synchronous read at
+ * startup is cheaper than making the whole entry point await.
+ *
+ * A failure falls back to `unknown` rather than throwing. A tool that will not
+ * start because it cannot find its own manifest is worse than one that admits
+ * it does not know — and `unknown` in a bug report is itself a useful fact
+ * about how somebody installed it.
+ */
+const VERSION: string = (() => {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const manifest: unknown = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+    const found = (manifest as { version?: unknown }).version;
+    return typeof found === 'string' ? found : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+})();
+
+const FEEDBACK_REPO = 'https://github.com/Davmunrey/Trazum';
+
 /** Problems listed before the rest are counted. A wall of them helps nobody. */
 const MAX_CONFORM_PROBLEMS = 20;
 
@@ -1949,6 +2001,193 @@ async function commandConform(args: Args, t: CliMessages): Promise<void> {
   console.log();
 }
 
+/**
+ * `trazum feedback` — where to say it, and what to say.
+ *
+ * **This command sends nothing.** Trazum has no telemetry: the CLI makes no
+ * network call it was not explicitly asked to make, and there is no ping, no
+ * install hook and no anonymous counter anywhere in it. That is not an
+ * omission somebody has been meaning to fix — a tool whose entire argument is
+ * that it reads your bill without uploading it cannot also be quietly
+ * reporting on you, and the security suite fails the build if this command
+ * ever reaches the network.
+ *
+ * So the loop is closed the only honest way: the person decides to send
+ * something, and this makes that as cheap as possible. It prints the four
+ * places worth writing to, and a **prefilled link** carrying the facts a
+ * maintainer always has to ask for — version, runtime, platform — printed in
+ * full first, so nothing travels that the sender has not read.
+ *
+ * Nothing about *their work* is in it. Not the config, not a prompt, not a
+ * label, not a figure. Those are the things a bug report needs and the things
+ * only the reporter can decide to share, and a command that helpfully attached
+ * them would be the leak this product exists not to be.
+ */
+function commandFeedback(t: CliMessages): void {
+  const version = VERSION;
+  /**
+   * Facts about the machine, and nothing about the person.
+   *
+   * `process.platform` and the Node version are what every "cannot reproduce"
+   * thread eventually asks for. The locale is here because Trazum ships two
+   * languages and a report reading wrong in one of them is a real bug class.
+   */
+  const environment = [
+    `Trazum ${version}`,
+    `Node ${process.version}`,
+    `${process.platform} ${process.arch}`,
+    `locale ${t.locale}`,
+  ];
+
+  const body = [
+    '<!-- What happened, and what you expected instead. -->',
+    '',
+    '',
+    '---',
+    ...environment.map((line) => `- ${line}`),
+  ].join('\n');
+  const url =
+    `${FEEDBACK_REPO}/issues/new?body=${encodeURIComponent(body)}`;
+
+  console.log();
+  console.log(c.bold(t.feedback.heading()));
+  console.log(`  ${c.dim(wrap(t.feedback.sendsNothing(), 74, '    '))}`);
+  console.log();
+
+  console.log(c.bold(t.feedback.whereHeading()));
+  console.log(`  ${t.feedback.wrongOptimisation()}`);
+  console.log(`    ${c.dim(`${FEEDBACK_REPO}/issues/new?template=wrong_optimisation.yml`)}`);
+  console.log(`  ${t.feedback.bug()}`);
+  console.log(`    ${c.dim(`${FEEDBACK_REPO}/issues/new?template=bug_report.yml`)}`);
+  console.log(`  ${t.feedback.question()}`);
+  console.log(`    ${c.dim(`${FEEDBACK_REPO}/discussions`)}`);
+  console.log(`  ${t.feedback.security()}`);
+  console.log(`    ${c.dim(`${FEEDBACK_REPO}/security/advisories/new`)}`);
+  console.log();
+
+  console.log(c.bold(t.feedback.environmentHeading()));
+  for (const line of environment) console.log(`  ${line}`);
+  console.log(`  ${c.dim(wrap(t.feedback.environmentOnly(), 74, '    '))}`);
+  console.log();
+
+  console.log(c.bold(t.feedback.linkHeading()));
+  console.log(`  ${url}`);
+  console.log();
+}
+
+/**
+ * `trazum gateway <provider>` — in the path, and refusing rather than advising.
+ *
+ * The last thing this product could not do. `serve` answers a question an
+ * implementation may ignore; a connector reports the runaway after it ran.
+ * Standing between the caller and the provider fixes both — usage is measured
+ * from the provider's own response as it comes back, and a refusal is a
+ * refusal.
+ *
+ * **The failure policy is required.** `--on-cannot-tell fail-open` keeps the
+ * product working and lets the bill run; `fail-closed` stops the bill and takes
+ * the product down with it. Both are defensible and there is deliberately no
+ * default: a proxy that picks silently has made the most consequential decision
+ * in somebody's architecture on their behalf, at install time, without saying
+ * so.
+ *
+ * **Substitution is off unless it is written down.** `spend.substitute` in the
+ * config, with the operator's own reason, and every substituted call is marked
+ * so no later report treats it as the call the caller made.
+ */
+async function commandGateway(
+  args: Args,
+  config: TrazumConfig,
+  configDir: string,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const provider = args.positional[0];
+  if (provider === undefined || UPSTREAMS[provider] === undefined) {
+    throw new Error(t.gateway.badProvider(provider ?? '', Object.keys(UPSTREAMS).join(', ')));
+  }
+
+  /**
+   * No default, and the error says why rather than just what.
+   *
+   * The one flag in this product that refuses to guess on the reader's behalf,
+   * because the two answers differ in which failure they accept and nobody but
+   * the operator knows which their product can survive.
+   */
+  const policyFlag = stringFlag(args, 'on-cannot-tell');
+  if (policyFlag === undefined || !FAILURE_POLICIES.includes(policyFlag as FailurePolicy)) {
+    throw new Error(t.gateway.needsPolicy(FAILURE_POLICIES.join(', ')));
+  }
+
+  const { resolved } = await readStore(configDir);
+  const budget = budgetPositions(resolved.records, config.spend, { catalogue: pricing });
+  const position = budget.positions[0] ?? null;
+
+  /**
+   * Read once at start, like `serve`'s.
+   *
+   * A file read in the request path would put Trazum's own latency between a
+   * caller and their provider on every call, which is a cost this product
+   * would otherwise be reporting on somebody else. The staleness is real, so a
+   * refusal carries `asOfMs` and says what it rested on.
+   */
+  const standing: GatewayStanding | null =
+    position === null || position.coverage === 'none'
+      ? null
+      : {
+          limitUsd: position.limitUsd,
+          consumedUsd: position.consumedUsd,
+          provenance: 'measured',
+          asOfMs: Date.now(),
+        };
+
+  const measured: { calls: number; usd: number } = { calls: 0, usd: 0 };
+  const server = buildGateway({
+    provider,
+    catalogue: pricing,
+    policy: {
+      onCannotTell: policyFlag as FailurePolicy,
+      ...(config.spend?.substitute === undefined ? {} : { substitute: config.spend.substitute }),
+    },
+    standing: () => standing,
+    record: (call) => {
+      measured.calls += 1;
+      console.error(
+        c.dim(
+          t.gateway.measured(
+            call.model,
+            call.label,
+            call.inputTokens,
+            call.outputTokens,
+            call.substituted,
+          ),
+        ),
+      );
+    },
+    note: (line) => {
+      console.error(c.yellow(`  ${line}`));
+    },
+  });
+
+  const socket = stringFlag(args, 'socket');
+  const portRaw = stringFlag(args, 'port');
+  const port = portRaw === undefined ? DEFAULT_GATEWAY_PORT : Number(portRaw);
+  if (socket === undefined && (!Number.isInteger(port) || port < 0 || port > 65_535)) {
+    throw new Error(t.serve.badPort(String(portRaw)));
+  }
+
+  const where = await listenGateway(server, socket !== undefined ? { socket } : { port });
+  console.log(c.bold(t.gateway.listening(where, provider)));
+  console.log(`  ${c.dim(wrap(t.gateway.pointYourSdk(where), 74, '    '))}`);
+  console.log(`  ${c.dim(wrap(t.gateway.credential(), 74, '    '))}`);
+  console.log(`  ${c.dim(wrap(t.gateway.neverSubstitutes(), 74, '    '))}`);
+  console.log(
+    `  ${c.dim(wrap(standing === null ? t.gateway.noStanding() : t.gateway.standing(formatUsd(standing.consumedUsd), formatUsd(standing.limitUsd)), 74, '    '))}`,
+  );
+  console.log(`  ${c.dim(wrap(t.gateway.policy(policyFlag), 74, '    '))}`);
+  console.log();
+}
+
 function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const col = t.models.columns;
@@ -3525,6 +3764,7 @@ async function commandConnect(
 async function commandHistory(
   args: Args,
   config: TrazumConfig,
+  configDir: string,
   pricing: PricingCatalogue,
   t: CliMessages,
 ): Promise<void> {
@@ -3644,7 +3884,7 @@ async function commandHistory(
    * the waiver record belongs to the repository whose gates fired, and the
    * stored reports may have come from anywhere.
    */
-  const waivers = await readWaiverLog('.');
+  const waivers = await readWaiverLog(configDir);
   const waiverReport = waiverHistory(waivers.uses, config.waive ?? []);
 
   const stamped = { ...history, unrecognizedFiles: unrecognized, waivers: waiverReport };
@@ -4046,7 +4286,13 @@ async function commandPlan(
   if (outPath !== undefined) console.log(c.dim(wrap(t.plan.wrote(outPath), 74, '')));
 }
 
-async function commandProfile(args: Args, config: TrazumConfig, pricing: PricingCatalogue, t: CliMessages): Promise<void> {
+async function commandProfile(
+  args: Args,
+  config: TrazumConfig,
+  configDir: string,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
   const path = args.positional[0];
   if (path === undefined) {
     console.log();
@@ -4870,7 +5116,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   const recordWaiverUses = async (): Promise<void> => {
     if (waiverUses.length === 0) return;
     for (const use of waiverUses) {
-      const failed = await appendWaiverUse('.', use);
+      const failed = await appendWaiverUse(configDir, use);
       if (failed !== null) {
         console.error(c.dim(t.profile.waiveNotRecorded(WAIVER_LOG, failed)));
         return;
@@ -7835,6 +8081,20 @@ async function main(): Promise<void> {
     return;
   }
 
+  /**
+   * Before the help branch, and before the config loads.
+   *
+   * `trazum --version` on its own is how somebody answers "which one is
+   * installed", and it has to work when the config is broken — that is
+   * precisely the moment they are being asked. Placed above `!args.command`
+   * for the same reason `--clear-suggestion-cache` is: with nothing else on
+   * the line, the help branch would have swallowed it.
+   */
+  if (boolFlag(args, 'version') || boolFlag(args, 'v')) {
+    console.log(VERSION);
+    return;
+  }
+
   if (boolFlag(args, 'help') || boolFlag(args, 'h') || !args.command) {
     console.log(
       t.help(
@@ -7885,6 +8145,22 @@ async function main(): Promise<void> {
     };
   }
   const { config } = loaded;
+  /**
+   * Where the waiver record lives: **beside the config that declared it**.
+   *
+   * It used to be the process's working directory, which is a different place
+   * whenever somebody runs `trazum profile ../logs/x.jsonl --config ../repo/
+   * trazum.config.json` — and that is not hypothetical. This repository's own
+   * test suite did exactly that from `packages/cli`, so sixty records of a
+   * fixture's decisions accumulated in a package directory and one of them was
+   * committed to `main`, where it sat for two releases.
+   *
+   * A waiver is a decision a *repository* made. The record of using it belongs
+   * with the file that made it, not with wherever the terminal happened to be.
+   * No config means no waivers, so there is nothing to write and `.` is never
+   * reached.
+   */
+  const configDir = loaded.path === null ? '.' : dirname(loaded.path);
   const pricing = await pricingFor(args, loaded, t);
 
   // The config only gets to choose the locale when nothing more explicit did.
@@ -7904,7 +8180,7 @@ async function main(): Promise<void> {
       await commandBaseline(args, config, pricing, t, locale);
       break;
     case 'profile':
-      await commandProfile(args, config, pricing, t);
+      await commandProfile(args, config, configDir, pricing, t);
       break;
     case 'plan':
       await commandPlan(args, pricing, t);
@@ -7913,7 +8189,7 @@ async function main(): Promise<void> {
       await commandVerify(args, pricing, t);
       break;
     case 'history':
-      await commandHistory(args, config, pricing, t);
+      await commandHistory(args, config, configDir, pricing, t);
       break;
     case 'connect':
       await commandConnect(args, pricing, t);
@@ -7942,6 +8218,12 @@ async function main(): Promise<void> {
     case 'models':
       commandModels(t, pricing);
       break;
+    case 'gateway':
+      await commandGateway(args, config, configDir, pricing, t);
+      break;
+    case 'feedback':
+      commandFeedback(t);
+      break;
     case 'conform':
       await commandConform(args, t);
       break;