@trazum/cli 1.50.1 → 1.50.3

package/dist/index.js

@@ -1,8 +1,10 @@
 #!/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 { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
+import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
 import { dayOf, formatGap, median, spanDays } from './time.js';
 // Everything that reads the filesystem, on its own entry point so the web
@@ -13,6 +15,7 @@ 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, postWebhook, readWatchState, writeWatchState, } from './watch-run.js';
 import { LOCALE_ENV_VARS, detectLocale, getCliMessages } from './i18n/index.js';
 import { MAX_SUMMARY_CHARS, fitWithin, renderBlameMarkdown, renderCheckMarkdown, renderDiffMarkdown, renderRankMarkdown, renderProfileMarkdown, } from './markdown.js';
@@ -31,6 +34,7 @@ const c = {
 const VALUE_FLAGS = new Set([
     'against',
     'contract',
+    'on-cannot-tell',
     'from-log',
     'min-usd',
     'payload',
@@ -287,7 +291,7 @@ function disabledRules(args, config) {
  * 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 = {
     optimize: [
         'level', 'model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch',
@@ -313,6 +317,8 @@ const COMMAND_FLAGS = {
     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'],
@@ -1039,6 +1045,43 @@ const INIT_LOG_CANDIDATES = [
  * answers for a file somebody named while this answers for a repository
  * 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 = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const manifest = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        const found = manifest.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;
 /** The contracts `--contract` accepts, so a typo is refused with the list. */
@@ -1467,6 +1510,161 @@ async function commandConform(args, t) {
     }
     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) {
+    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, config, configDir, pricing, t) {
+    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)) {
+        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 = position === null || position.coverage === 'none'
+        ? null
+        : {
+            limitUsd: position.limitUsd,
+            consumedUsd: position.consumedUsd,
+            provenance: 'measured',
+            asOfMs: Date.now(),
+        };
+    const measured = { calls: 0, usd: 0 };
+    const server = buildGateway({
+        provider,
+        catalogue: pricing,
+        policy: {
+            onCannotTell: policyFlag,
+            ...(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, pricing) {
     const n = (value) => value.toLocaleString(t.numberLocale);
     const col = t.models.columns;
@@ -2653,7 +2851,7 @@ async function commandConnect(args, pricing, t) {
  * same action planned twice — and no series, however long, becomes a
  * forecast.
  */
-async function commandHistory(args, config, pricing, t) {
+async function commandHistory(args, config, configDir, pricing, t) {
     /**
      * `--store` builds the series from measured spend already on disk.
      *
@@ -2765,7 +2963,7 @@ async function commandHistory(args, config, pricing, t) {
      * 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 };
     const n = (value) => value.toLocaleString(t.numberLocale);
@@ -3117,7 +3315,7 @@ async function commandPlan(args, pricing, t) {
     if (outPath !== undefined)
         console.log(c.dim(wrap(t.plan.wrote(outPath), 74, '')));
 }
-async function commandProfile(args, config, pricing, t) {
+async function commandProfile(args, config, configDir, pricing, t) {
     const path = args.positional[0];
     if (path === undefined) {
         console.log();
@@ -3876,7 +4074,7 @@ async function commandProfile(args, config, pricing, t) {
         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;
@@ -6265,6 +6463,19 @@ async function main() {
         console.log(t.cache.cleared(removed, before.bytes, dir));
         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({
             model: DEFAULT_USAGE.model,
@@ -6310,6 +6521,22 @@ async function main() {
         };
     }
     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.
     if (config.locale && !stringFlag(args, 'locale')) {
@@ -6327,7 +6554,7 @@ async function main() {
             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);
@@ -6336,7 +6563,7 @@ async function main() {
             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);
@@ -6365,6 +6592,12 @@ async function main() {
         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;