segreant 0.0.0-stage → 0.2.0

package/dist/cli/ui.js

@@ -0,0 +1,128 @@
+/**
+ * Shared CLI presentation helpers — ANSI palette, money/number/percent
+ * formatting, and the small disclosure lines every command reuses. Extracted
+ * verbatim from cli.ts in the per-command-module split; the dispatcher and
+ * every command module import from here so the CLI speaks with one voice.
+ */
+import { stringifyJson } from '../util/json.js';
+// Night Vault brand colors on terminals that declare 24-bit support (molten
+// gold for value, sage for pass, signal red for alerts); the plain ANSI-16
+// equivalents everywhere else so older terminals never see garbage escapes.
+const truecolor = process.env.COLORTERM === 'truecolor' || process.env.COLORTERM === '24bit' || Boolean(process.env.WT_SESSION);
+export const C = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    cyan: '\x1b[36m',
+    green: truecolor ? '\x1b[38;2;99;197;147m' : '\x1b[32m',
+    yellow: truecolor ? '\x1b[38;2;232;179;60m' : '\x1b[33m',
+    red: truecolor ? '\x1b[38;2;226;93;74m' : '\x1b[31m',
+    gray: '\x1b[90m',
+};
+export function color(on, code, s) {
+    return on ? `${code}${s}${C.reset}` : s;
+}
+export function usd(n) {
+    // Sign outside the symbol, and the same precision either side of zero: a
+    // credit of 5 dollars used to fall through every branch to "$-5.000000".
+    const sign = n < 0 ? '-' : '';
+    const a = Math.abs(n);
+    if (a === 0)
+        return '$0.00';
+    if (a >= 1)
+        return `${sign}$${a.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+    if (a >= 0.01)
+        return `${sign}$${a.toFixed(4)}`;
+    return `${sign}$${a.toFixed(6)}`;
+}
+export function num(n) {
+    return n.toLocaleString('en-US');
+}
+export function pct(n) {
+    return `${(n * 100).toFixed(0)}%`;
+}
+/** CLI response version, separate from database and exported artifact schemas. */
+export const CLI_JSON_SCHEMA_VERSION = 1;
+export function cliJsonResponse(value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        // A document that already names its own schema version keeps it: that
+        // number describes the document, and the CLI must not relabel it.
+        if (Object.hasOwn(value, 'schemaVersion'))
+            return value;
+        return { ...value, schemaVersion: CLI_JSON_SCHEMA_VERSION };
+    }
+    return { schemaVersion: CLI_JSON_SCHEMA_VERSION, data: value };
+}
+/** Emit one versioned response with stable six-decimal USD fields. */
+export function printJson(value, space = 2) {
+    process.stdout.write(stringifyJson(cliJsonResponse(value), space) + '\n');
+}
+/** Actionable not-a-git-repo message: tell the user what to do, not just what's wrong. */
+export function printNotAGitRepo(repo) {
+    console.error(`  Not a git repository: ${repo}`);
+    console.error('  Run this from inside your repo, or pass --repo <path>. Session-scored usage needs no git: segreant usage');
+}
+/**
+ * One-line honesty notes about where the realized-value figures came from: a
+ * stored snapshot vs a live repo, and — for a live repo — whether the dollars were
+ * scoped to THIS project's own spend (the ledger is characterized by project:
+ * native imports or tagged traffic) or fell back to the project-blind window sum
+ * (untagged proxy). Discloses the basis so the number is never silently mixed.
+ */
+export function noteSource(tty, source, projectScoped, costStaleUnits = 0, 
+/** Mature units whose spend window lost rows to retention (D-176). */
+spendWindowTruncatedUnits = 0, 
+/** Mature units persisted before that coverage was recorded: unknown, not intact. */
+spendWindowUnknownUnits = 0) {
+    if (spendWindowTruncatedUnits > 0) {
+        // The cost totals below are DENOMINATORS. A commit whose attribution
+        // window retention emptied contributes $0.00 and still counts as a
+        // unit, so every ratio built on them is inflated by an unknown amount.
+        // Reported rather than corrected: nothing surviving records what was
+        // deleted, so a repaired total would be invented.
+        console.log(color(tty, C.yellow, `  ● ${spendWindowTruncatedUnits} unit(s) had spend deleted by retention inside their attribution window — their cost reads lower than it was, so ratios below are flattering by an unknown amount.`));
+    }
+    if (spendWindowUnknownUnits > 0) {
+        // Distinct from zero truncated units on purpose: a snapshot written
+        // before the coverage was recorded cannot say, and reading that as
+        // intact is the inference this line exists to refuse.
+        console.log(color(tty, C.gray, `  ● ${spendWindowUnknownUnits} unit(s) predate the retention-coverage record, so whether their spend window lost rows is unknown. Recompute with: segreant realize`));
+    }
+    if (costStaleUnits > 0) {
+        // A reprice re-costed the request ledger. These units predate the recorded
+        // cost basis, so they could not be re-attributed without guessing which basis
+        // produced them — they still carry the old dollars, and this view and
+        // `segreant spend` will not agree until they are recomputed.
+        console.log(color(tty, C.yellow, `  ● ${costStaleUnits} unit(s) carry pre-reprice costs — excluded from model comparison. Recompute with: segreant realize`));
+    }
+    if (source === 'store') {
+        console.log(color(tty, C.gray, '  ● stored realization snapshot — no live repo attached; figures are as of the last realize run.'));
+        return;
+    }
+    if (projectScoped === true) {
+        console.log(color(tty, C.gray, "  ● scoped to this project's own spend — ledger characterized by project (imports / tagged traffic)."));
+    }
+    else if (projectScoped === false) {
+        console.log(color(tty, C.gray, '  ● project-blind window attribution — no project-tagged spend here. Import or tag sources to scope value per project.'));
+    }
+}
+export function glyph(tty, v) {
+    if (v === 'pass')
+        return color(tty, C.green, '✓');
+    if (v === 'fail')
+        return color(tty, C.red, '✗');
+    return color(tty, C.gray, '·');
+}
+/**
+ * A gate's glyph from its four-valued polarity (AII-003, WP-B03).
+ *
+ * A conflicted gate projects to `fail`, so rendering the verdict alone showed
+ * an operator a red ✗ — "the tests failed" — when what actually happened is
+ * that two runs disagreed and neither has been adjudicated. Those call for
+ * different actions, so they get different glyphs.
+ */
+export function gateGlyph(tty, result) {
+    if (result.polarity === 'conflicted')
+        return color(tty, C.yellow, '!');
+    return glyph(tty, result.verdict);
+}