@trazum/cli 1.53.4 → 1.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
4
4
  import { dirname, join, resolve as resolvePath } from 'node:path';
5
5
  import { fileURLToPath } from 'node:url';
6
6
  import { gunzipSync } from 'node:zlib';
7
- import { CONTRACT_NAMES, 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, bandGoverns, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, annualRecord, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, 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';
7
+ import { CONTRACT_NAMES, 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, bandGoverns, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, annualRecord, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, rollUp, 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';
8
8
  import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
9
9
  import { dayOf, formatGap, median, spanDays } from './time.js';
10
10
  // Everything that reads the filesystem, on its own entry point so the web
@@ -325,6 +325,7 @@ const COMMAND_FLAGS = {
325
325
  rank: ['level', 'model', 'calls', 'output-tokens', 'batch', 'disable', 'prompt', 'markdown-out'],
326
326
  init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
327
327
  conform: ['contract', 'json'],
328
+ rollup: ['json'],
328
329
  feedback: [],
329
330
  gateway: ['on-cannot-tell', 'port', 'socket', 'pricing', 'pricing-live'],
330
331
  ladder: ['pricing', 'pricing-live', 'since', 'until', 'label'],
@@ -1527,6 +1528,191 @@ async function commandConform(args, t) {
1527
1528
  }
1528
1529
  console.log();
1529
1530
  }
1531
+ /**
1532
+ * `trazum rollup <document...>` — several people's bills, one roll-up.
1533
+ *
1534
+ * The first command here that reads *documents* rather than logs. Everything
1535
+ * else assumes one operator with the files on disk; this assumes four people
1536
+ * who each already ran `trazum profile --json` where their traffic is, and one
1537
+ * of them wants the total.
1538
+ *
1539
+ * **A format and a merge, not a service.** There is no upload, no account and
1540
+ * no server: the documents arrive however the team already moves files, and
1541
+ * this reads them off the filesystem. That is the whole design — a tool whose
1542
+ * argument is that it reads your bill without uploading it cannot also be the
1543
+ * place everybody's bill is uploaded.
1544
+ *
1545
+ * A directory argument is expanded to the `.json` files directly inside it, so
1546
+ * a shared folder people drop a document into is a roll-up without anybody
1547
+ * writing a shell loop.
1548
+ *
1549
+ * The rendering leads with the total and then spends most of its lines on what
1550
+ * the merge could **not** do: the contributors' own gaps, the findings that do
1551
+ * not roll up, and the overlap between contributors that nothing here can see.
1552
+ * A roll-up is the document most likely to be pasted into a slide, and a total
1553
+ * with its caveats one screen away is a total that will be quoted alone.
1554
+ */
1555
+ async function commandRollup(args, t) {
1556
+ if (args.positional.length === 0)
1557
+ throw new Error(t.rollup.noTargets());
1558
+ /** Every document to merge, in the order the caller named them. */
1559
+ const inputs = [];
1560
+ /** What a failed filesystem call was refusing, when it said. */
1561
+ const codeOf = (error) => typeof error === 'object' && error !== null ? error.code : undefined;
1562
+ for (const target of args.positional) {
1563
+ /**
1564
+ * Attempted, not checked first.
1565
+ *
1566
+ * The obvious shape is `stat` and then branch on `isDirectory()`, and it
1567
+ * is a check-then-act: between the answer and the read the path can become
1568
+ * something else, and CodeQL flagged exactly that on the pull request that
1569
+ * introduced this command. Reading the error code has no window between
1570
+ * the two operations, because there is only one operation — and it is the
1571
+ * same reasoning the gateway applies to a budget decision, which happens
1572
+ * before the upstream is opened rather than between two things.
1573
+ *
1574
+ * `ENOTDIR` is an answer — this is a file — and every other failure is a
1575
+ * failure.
1576
+ */
1577
+ const listing = await readdir(target, { withFileTypes: true }).catch((error) => {
1578
+ const code = codeOf(error);
1579
+ if (code === 'ENOTDIR')
1580
+ return null;
1581
+ if (code === 'ENOENT')
1582
+ throw new Error(t.rollup.noSuchTarget(target));
1583
+ throw error;
1584
+ });
1585
+ if (listing !== null) {
1586
+ const found = listing
1587
+ .filter((child) => child.isFile() && child.name.endsWith('.json'))
1588
+ .map((child) => join(target, child.name))
1589
+ .sort((a, b) => a.localeCompare(b));
1590
+ // An empty directory is named rather than quietly contributing nothing:
1591
+ // a roll-up of a folder somebody spelled wrong would otherwise report a
1592
+ // total of zero and look like a team that spent nothing.
1593
+ if (found.length === 0)
1594
+ throw new Error(t.rollup.emptyDirectory(target));
1595
+ for (const file of found)
1596
+ inputs.push({ name: file, text: await readFile(file, 'utf8') });
1597
+ continue;
1598
+ }
1599
+ const text = await readFile(target, 'utf8').catch((error) => {
1600
+ // Gone between the two calls, which is the race the shape above avoids
1601
+ // deciding on: the read is what says so, and it says so by name.
1602
+ if (codeOf(error) === 'ENOENT')
1603
+ throw new Error(t.rollup.noSuchTarget(target));
1604
+ throw error;
1605
+ });
1606
+ inputs.push({ name: target, text });
1607
+ }
1608
+ const document = rollUp(inputs);
1609
+ if (boolFlag(args, 'json')) {
1610
+ console.log(JSON.stringify(document, null, 2));
1611
+ // A rejected contribution is a machine missing from the total, so it gates
1612
+ // — the same reason `conform` exits 1 on a problem. Every other caveat is
1613
+ // a property of merging summaries and would gate on every honest roll-up.
1614
+ if (document.rejected.length > 0)
1615
+ process.exitCode = 1;
1616
+ return;
1617
+ }
1618
+ const day = (ms) => new Date(ms).toISOString().slice(0, 10);
1619
+ console.log();
1620
+ console.log(c.bold(t.rollup.heading(document.contributors.length, formatUsd(document.total.totalUsd), document.total.calls)));
1621
+ console.log(` ${c.dim(document.span === null
1622
+ ? t.rollup.noSpan()
1623
+ : t.rollup.span(day(document.span.fromMs), day(document.span.toMs)))}`);
1624
+ if (document.claimedSpan !== null) {
1625
+ console.log(` ${c.dim(wrap(t.rollup.claimedSpan(day(document.claimedSpan.fromMs), day(document.claimedSpan.toMs - 1), document.claimedSpan.contributors), 72, ' '))}`);
1626
+ }
1627
+ console.log();
1628
+ console.log(c.bold(t.rollup.contributorsHeading()));
1629
+ for (const contributor of document.contributors) {
1630
+ console.log(` ${t.rollup.contributor(contributor.name, formatUsd(contributor.totalUsd), contributor.calls, contributor.spanDays === null ? null : Math.round(contributor.spanDays))}${contributor.via === null ? '' : ` ${c.dim(t.rollup.via(contributor.via))}`}`);
1631
+ /**
1632
+ * What this contributor asked for, before what it found.
1633
+ *
1634
+ * A span is not a period: a log whose latest record is the 5th may be a
1635
+ * log of a quiet week or a log that stopped being written on the 5th, and
1636
+ * only a claim tells those apart. Printed above the gaps because the
1637
+ * silence below is measured against it.
1638
+ */
1639
+ if (contributor.claimed !== null) {
1640
+ const { sinceMs, untilMs } = contributor.claimed;
1641
+ if (sinceMs !== null && untilMs !== null) {
1642
+ // The window is half-open, so the last claimed day is the one before
1643
+ // `until` — printed as the reader would say it, not as the filter
1644
+ // stores it.
1645
+ console.log(` ${c.dim(t.rollup.claimedRow(day(sinceMs), day(untilMs - 1)))}`);
1646
+ }
1647
+ if (contributor.undatedExcluded !== null && contributor.undatedExcluded > 0) {
1648
+ console.log(` ${c.yellow(wrap(t.rollup.undated(contributor.undatedExcluded), 70, ' '))}`);
1649
+ }
1650
+ }
1651
+ // Every gap under the contributor that has it, never summed into one
1652
+ // figure: "one of your four machines is 90% unpriced" is the finding, and
1653
+ // an average is what hides it.
1654
+ for (const gap of contributor.gaps) {
1655
+ console.log(` ${c.yellow(wrap(gap.detail, 70, ' '))}`);
1656
+ }
1657
+ // The silent stretches by name, under the gap that counted them: "eight
1658
+ // days recorded nothing" is a number, and which eight is the finding.
1659
+ if (contributor.silence !== null && contributor.silence.runs.length > 0) {
1660
+ const runs = contributor.silence.runs
1661
+ .map((run) => (run.from === run.to ? run.from : `${run.from} to ${run.to}`))
1662
+ .join(', ');
1663
+ console.log(` ${c.dim(wrap(t.rollup.silentRuns(runs), 68, ' '))}`);
1664
+ }
1665
+ }
1666
+ if (document.rejected.length > 0) {
1667
+ console.log();
1668
+ console.log(c.bold(t.rollup.rejectedHeading()));
1669
+ for (const rejection of document.rejected) {
1670
+ // The roll-up it arrived through, when it came through one: a rejection
1671
+ // whose origin got lost is a machine nobody knows to go and fix.
1672
+ const line = rejection.via === null
1673
+ ? t.rollup.rejected(rejection.name, rejection.because)
1674
+ : t.rollup.rejectedVia(rejection.name, rejection.via, rejection.because);
1675
+ console.log(` ${c.red(wrap(line, 72, ' '))}`);
1676
+ }
1677
+ process.exitCode = 1;
1678
+ }
1679
+ if (document.identicalContributions.groups.length > 0) {
1680
+ console.log();
1681
+ for (const group of document.identicalContributions.groups) {
1682
+ console.log(` ${c.yellow(wrap(t.rollup.identical(group.join(', ')), 72, ' '))}`);
1683
+ }
1684
+ console.log(` ${c.dim(t.rollup.identicalUsd(formatUsd(document.identicalContributions.usd)))}`);
1685
+ }
1686
+ if (document.repeatedContributors.length > 0) {
1687
+ console.log();
1688
+ console.log(` ${c.yellow(wrap(t.rollup.repeated(document.repeatedContributors.join(', ')), 72, ' '))}`);
1689
+ }
1690
+ if (document.byLabel.length > 0) {
1691
+ console.log();
1692
+ console.log(c.bold(t.rollup.byLabelHeading()));
1693
+ for (const row of document.byLabel.slice(0, 8)) {
1694
+ console.log(` ${t.rollup.labelRow(row.label, formatUsd(row.breakdown.totalUsd), row.breakdown.calls)}`);
1695
+ }
1696
+ }
1697
+ if (document.notMerged.length > 0) {
1698
+ console.log();
1699
+ console.log(c.bold(t.rollup.notMergedHeading()));
1700
+ for (const finding of document.notMerged) {
1701
+ console.log(` ${wrap(t.rollup.notMerged(finding.finding, finding.because), 72, ' ')}`);
1702
+ if (finding.presentIn.length > 0) {
1703
+ console.log(` ${c.dim(t.rollup.presentIn(finding.presentIn.join(', ')))}`);
1704
+ }
1705
+ }
1706
+ }
1707
+ if (document.cannotSay.length > 0) {
1708
+ console.log();
1709
+ console.log(c.bold(t.rollup.cannotSayHeading()));
1710
+ for (const caveat of document.cannotSay) {
1711
+ console.log(` ${c.dim(wrap(t.rollup.caveat(caveat), 72, ' '))}`);
1712
+ }
1713
+ }
1714
+ console.log();
1715
+ }
1530
1716
  /**
1531
1717
  * `trazum feedback` — where to say it, and what to say.
1532
1718
  *
@@ -7405,6 +7591,7 @@ async function main() {
7405
7591
  avgOutputTokens: DEFAULT_USAGE.avgOutputTokens,
7406
7592
  cacheHitRate: DEFAULT_USAGE.cacheHitRate,
7407
7593
  locales: LOCALES,
7594
+ contracts: CONTRACT_NAMES,
7408
7595
  }, c.bold));
7409
7596
  return;
7410
7597
  }
@@ -7544,6 +7731,9 @@ async function main() {
7544
7731
  case 'conform':
7545
7732
  await commandConform(args, t);
7546
7733
  break;
7734
+ case 'rollup':
7735
+ await commandRollup(args, t);
7736
+ break;
7547
7737
  case 'init':
7548
7738
  await commandInit(args, config, pricing, t);
7549
7739
  break;