amicus 1.9.0 → 2.0.0

package/src/utils/spend-ledger.js

@@ -0,0 +1,80 @@
+// src/utils/spend-ledger.js
+'use strict';
+
+/**
+ * @module spend-ledger
+ * Cross-run cost ledger (B24). One JSONL row per completed RUN, appended at
+ * the same points the per-run `usage` block is already resolved and written
+ * into that run's own `metadata.json` (src/utils/pricing.js resolveUsage):
+ * currently `start` (src/sidecar/start.js, mode headless|interactive) and
+ * each fanout leg (src/sidecar/fanout-leg.js, mode leg). `continue`/`resume`
+ * do NOT currently call resolveUsage at all — no usage block exists at their
+ * finalize points to append here either, a pre-existing gap outside this
+ * module's scope (see the B24 task report for the inventory).
+ * `amicus spend` (src/cli-handlers-spend.js) reads this file to build a
+ * cross-run rollup; nothing else consumes it.
+ *
+ * Precedent: src/council/ledger.js (council-ledger.jsonl). Same tradeoffs:
+ *   - plain fs.appendFileSync — a torn/lost row on a hard crash mid-write is
+ *     an acceptable loss for a ledger (best-effort spend visibility, not a
+ *     billing record of truth — the per-run metadata.json is that).
+ *   - corrupt/partial lines are skipped on read, never thrown.
+ * Departure from council/ledger.js: appendSpend() itself is wrapped so it
+ * NEVER throws — a run's usage must never fail the run it's recording. Every
+ * call site is expected to call this fire-and-forget with its own try/catch
+ * as a second belt (defense in depth), but the ledger guarantees it too.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config');
+const { logger } = require('./logger');
+
+const SPEND_LEDGER_SCHEMA_VERSION = 1;
+const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
+
+/**
+ * Append one row for a completed run. Best-effort: swallows any failure
+ * (unwritable config dir, disk full, etc.) and logs at debug — never throws,
+ * never rejects, never blocks/fails the run it's recording. A no-op when
+ * `usage` is null (nothing priced to record, e.g. an errored run that never
+ * reached resolveUsage).
+ *
+ * @param {object} opts
+ * @param {string} opts.taskId
+ * @param {string} [opts.waveId] present for a fanout leg
+ * @param {string} opts.model resolved model id (or alias, if that's all the caller has)
+ * @param {'headless'|'interactive'|'leg'} opts.mode
+ * @param {{tokens:object, cost:{amount:number|null,currency:string,source:string}}|null} opts.usage
+ * @param {{dir?:string}} [ctx] test seam — dir overrides getConfigDir()
+ */
+function appendSpend({ taskId, waveId, model, mode, usage }, ctx = {}) {
+  if (!usage) { return; }
+  try {
+    const dir = ctx.dir || getConfigDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const row = {
+      schemaVersion: SPEND_LEDGER_SCHEMA_VERSION,
+      ts: new Date().toISOString(),
+      taskId: taskId || null,
+      waveId: waveId || null,
+      model: model || null,
+      mode: mode || null,
+      tokens: usage.tokens || null,
+      cost: usage.cost || null,
+    };
+    fs.appendFileSync(path.join(dir, SPEND_LEDGER_FILE), JSON.stringify(row) + '\n');
+  } catch (e) {
+    logger.debug('spend-ledger append failed (best-effort, run unaffected)', { taskId, error: e.message });
+  }
+}
+
+/** @param {string} [dir] @returns {Array<object>} parsed rows; corrupt lines skipped */
+function readSpendRows(dir) {
+  const file = path.join(dir || getConfigDir(), SPEND_LEDGER_FILE);
+  if (!fs.existsSync(file)) { return []; }
+  return fs.readFileSync(file, 'utf-8').split('\n').map(l => l.trim()).filter(Boolean)
+    .map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+module.exports = { appendSpend, readSpendRows, SPEND_LEDGER_FILE, SPEND_LEDGER_SCHEMA_VERSION };

package/src/utils/updater.js

@@ -5,7 +5,7 @@
  * Checks for new versions via update-notifier and performs
  * updates via npm install -g.
  *
- * Supports AMICUS_MOCK_UPDATE (or legacy SIDECAR_MOCK_UPDATE) env var for testing:
+ * Supports AMICUS_MOCK_UPDATE env var for testing:
  *   "available" — getUpdateInfo returns fake update
  *   "updating"  — getUpdateInfo returns fake update
  *   "success"   — performUpdate resolves immediately
@@ -15,7 +15,6 @@
 const { spawn } = require('child_process');
 const path = require('path');
 const { logger } = require('./logger');
-const { getCompatEnv } = require('./env-compat');
 const { loadUpdateNotifier } = require('./update-notifier-loader');
 
 const pkg = require(path.join(__dirname, '..', '..', 'package.json'));
@@ -31,7 +30,7 @@ let notifier = null;
  * @returns {string|null} The mock mode or null
  */
 function getMockMode() {
-  const mode = getCompatEnv('MOCK_UPDATE');
+  const mode = process.env.AMICUS_MOCK_UPDATE;
   if (mode && MOCK_MODES.includes(mode)) {
     return mode;
   }

package/src/utils/env-compat.js

@@ -1,38 +0,0 @@
-/**
- * Environment-variable compatibility shim (Amicus rebrand).
- *
- * DEPRECATED(amicus-shim): the SIDECAR_* fallbacks exist only for backward
- * compatibility with pre-rebrand setups. Remove in a future revision once users
- * have migrated to the AMICUS_* names. See docs/SHIMS.md.
- */
-const { logger } = require('./logger');
-
-const warned = new Set();
-
-/**
- * Read an env var by its canonical AMICUS_<suffix> name, falling back to the
- * legacy SIDECAR_<suffix> name (with a one-time deprecation warning) if unset.
- *
- * @param {string} suffix - e.g. 'CONFIG_DIR' (no AMICUS_/SIDECAR_ prefix)
- * @returns {string|undefined}
- */
-function getCompatEnv(suffix) {
-  const amicusName = `AMICUS_${suffix}`;
-  if (process.env[amicusName] !== undefined) {
-    return process.env[amicusName];
-  }
-  const legacyName = `SIDECAR_${suffix}`;
-  if (process.env[legacyName] !== undefined) {
-    if (!warned.has(legacyName)) {
-      warned.add(legacyName);
-      logger.warn(
-        `${legacyName} is deprecated; use ${amicusName} instead. ` +
-        'Support will be removed in a future Amicus release.'
-      );
-    }
-    return process.env[legacyName];
-  }
-  return undefined;
-}
-
-module.exports = { getCompatEnv };