feat(ms-ai-architect): add lib/cost-estimat heuristic for API-key budget [skip-docs]

Pure auth-mode-aware cost estimator for v1.12.0 cron pre-flight.

Heuristic: critical+high files only (medium/low excluded per brief);
3000 input + 1500 output tokens per file at Sonnet pricing
($3/M in, $15/M out).

Auth-mode behavior:
- api-key:   numeric usd, kvote_warn off  (subject to dollar-cap)
- long-oauth, subscription-browser-only:
             usd null, kvote_warn on      (quota, no dollar billing)
- unauthenticated/missing: best-effort api-key estimate

11/11 tests pass; covers both billing modes plus token-math
invariance across auth-mode (auth only affects dollar-field, not tokens).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

plugins/ms-ai-architect/tests/kb-update/test-cost-estimat.test.mjs

@@ -0,0 +1,82 @@
+// tests/kb-update/test-cost-estimat.test.mjs
+// Unit tests for scripts/kb-update/lib/cost-estimat.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { estimateCost } from '../../scripts/kb-update/lib/cost-estimat.mjs';
+
+test('estimateCost — api-key returns numeric usd, kvote_warn unset', () => {
+  const result = estimateCost({ critical: 3, high: 15 }, { authMode: 'api-key' });
+  assert.equal(typeof result.usd, 'number');
+  assert.equal(result.kvote_warn, false);
+  assert.ok(result.usd > 0);
+});
+
+test('estimateCost — api-key empty input returns 0 USD', () => {
+  const result = estimateCost({}, { authMode: 'api-key' });
+  assert.equal(result.usd, 0);
+  assert.equal(result.kvote_warn, false);
+  assert.equal(result.tokens_input, 0);
+  assert.equal(result.tokens_output, 0);
+});
+
+test('estimateCost — api-key tokens are integers', () => {
+  const result = estimateCost({ critical: 3, high: 15 }, { authMode: 'api-key' });
+  assert.equal(Number.isInteger(result.tokens_input), true);
+  assert.equal(Number.isInteger(result.tokens_output), true);
+});
+
+test('estimateCost — ignores medium and low (only critical+high counted)', () => {
+  const a = estimateCost({ critical: 1, high: 1 }, { authMode: 'api-key' });
+  const b = estimateCost({ critical: 1, high: 1, medium: 100, low: 100 }, { authMode: 'api-key' });
+  assert.equal(a.usd, b.usd);
+  assert.equal(a.tokens_input, b.tokens_input);
+});
+
+test('estimateCost — long-oauth returns null usd, kvote_warn flag set', () => {
+  const result = estimateCost({ critical: 3, high: 15 }, { authMode: 'long-oauth' });
+  assert.strictEqual(result.usd, null);
+  assert.strictEqual(result.kvote_warn, true);
+});
+
+test('estimateCost — subscription-browser-only returns null usd, kvote_warn flag set', () => {
+  const result = estimateCost({ critical: 3, high: 15 }, { authMode: 'subscription-browser-only' });
+  assert.strictEqual(result.usd, null);
+  assert.strictEqual(result.kvote_warn, true);
+});
+
+test('estimateCost — auth-mode does not affect token math', () => {
+  const apikey = estimateCost({ critical: 5, high: 10 }, { authMode: 'api-key' });
+  const oauth = estimateCost({ critical: 5, high: 10 }, { authMode: 'long-oauth' });
+  const sub = estimateCost({ critical: 5, high: 10 }, { authMode: 'subscription-browser-only' });
+  assert.equal(apikey.tokens_input, oauth.tokens_input);
+  assert.equal(apikey.tokens_input, sub.tokens_input);
+  assert.equal(apikey.tokens_output, oauth.tokens_output);
+  assert.equal(apikey.tokens_output, sub.tokens_output);
+});
+
+test('estimateCost — unauthenticated treated as best-effort api-key', () => {
+  const result = estimateCost({ critical: 3, high: 15 }, { authMode: 'unauthenticated' });
+  assert.equal(typeof result.usd, 'number');
+  assert.equal(result.kvote_warn, false);
+});
+
+test('estimateCost — missing authMode opt treated as best-effort api-key', () => {
+  const result = estimateCost({ critical: 3, high: 15 });
+  assert.equal(typeof result.usd, 'number');
+  assert.equal(result.kvote_warn, false);
+});
+
+test('estimateCost — unknown priority keys are ignored', () => {
+  const result = estimateCost({ critical: 1, high: 1, weird: 999 }, { authMode: 'api-key' });
+  // Should equal {critical:1, high:1} alone
+  const baseline = estimateCost({ critical: 1, high: 1 }, { authMode: 'api-key' });
+  assert.equal(result.usd, baseline.usd);
+});
+
+test('estimateCost — fixture {critical: 3, high: 15} produces expected order of magnitude', () => {
+  // 18 files * (3000 in + 1500 out) tokens = 54k in, 27k out
+  // api-key cost: 54k * $3/M + 27k * $15/M = $0.162 + $0.405 = $0.567
+  const result = estimateCost({ critical: 3, high: 15 }, { authMode: 'api-key' });
+  assert.ok(result.usd > 0.4 && result.usd < 0.8, `expected ~$0.567, got $${result.usd}`);
+});