@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/scripts/context-meter/count-tokens-client.test.js

@@ -0,0 +1,308 @@
+"use strict";
+
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const http = require("http");
+
+const { countTokens } = require("./count-tokens-client");
+
+/* ----------------------------- stub server helpers ----------------------------- */
+
+/**
+ * Start a stub HTTP server bound to 127.0.0.1:0 (OS-assigned port).
+ *
+ * @param {(req, res, body) => void} handler
+ *   Called on every incoming request. `body` is the full request body as string.
+ *   The handler is responsible for writing the response (unless it intentionally
+ *   hangs — see the timeout test).
+ * @returns {Promise<{server: http.Server, baseUrl: string, lastBody: {value: string|null}}>}
+ */
+function startStub(handler) {
+  return new Promise((resolve, reject) => {
+    const lastBody = { value: null };
+    const server = http.createServer((req, res) => {
+      const chunks = [];
+      req.on("data", (c) => chunks.push(c));
+      req.on("end", () => {
+        const body = Buffer.concat(chunks).toString("utf8");
+        lastBody.value = body;
+        try {
+          handler(req, res, body);
+        } catch (err) {
+          try {
+            res.statusCode = 500;
+            res.end(String(err && err.message));
+          } catch (_) {
+            /* ignore */
+          }
+        }
+      });
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      resolve({ server, baseUrl: `http://127.0.0.1:${addr.port}`, lastBody });
+    });
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolve) => {
+    if (!server) {
+      resolve();
+      return;
+    }
+    // Destroy any lingering sockets so hung handlers don't keep the event loop alive.
+    try {
+      server.closeAllConnections && server.closeAllConnections();
+    } catch (_) {
+      /* ignore */
+    }
+    server.close(() => resolve());
+  });
+}
+
+/* ---------------------------------- tests ---------------------------------- */
+
+test("happy path → returns { inputTokens }", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 12345 }));
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "you are helpful",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.deepEqual(got, { inputTokens: 12345 });
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("401 → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 401;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ error: { type: "authentication_error", message: "bad key" } }));
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-bad",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("429 → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 429;
+    res.end("rate limited");
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("500 → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 500;
+    res.end("internal");
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("timeout → returns null", async () => {
+  // Handler never responds — the client's timeoutMs should fire first.
+  const { server, baseUrl } = await startStub(() => {
+    /* never calls res.end() */
+  });
+  try {
+    const t0 = Date.now();
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 500,
+      _baseUrl: baseUrl,
+    });
+    const elapsed = Date.now() - t0;
+    assert.equal(got, null);
+    // Should resolve shortly after the 500ms timeout, well under the 5s test budget.
+    assert.ok(elapsed < 3000, `timeout path took too long: ${elapsed}ms`);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("malformed response JSON → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end('not json{');
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("missing input_tokens field → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ other_field: 99 }));
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test('empty system string → request body OMITS "system" key', async () => {
+  const { server, baseUrl, lastBody } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 1 }));
+  });
+  try {
+    await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.ok(lastBody.value, "stub did not receive a body");
+    const parsed = JSON.parse(lastBody.value);
+    assert.equal(Object.prototype.hasOwnProperty.call(parsed, "system"), false);
+    assert.equal(parsed.model, "claude-opus-4-6");
+    assert.ok(Array.isArray(parsed.messages));
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test('non-empty system → request body INCLUDES "system"', async () => {
+  const { server, baseUrl, lastBody } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 2 }));
+  });
+  try {
+    await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "some text",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.ok(lastBody.value, "stub did not receive a body");
+    const parsed = JSON.parse(lastBody.value);
+    assert.equal(parsed.system, "some text");
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("sends required Anthropic headers", async () => {
+  let seenHeaders = null;
+  const { server, baseUrl } = await startStub((req, res) => {
+    seenHeaders = req.headers;
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 3 }));
+  });
+  try {
+    await countTokens({
+      apiKey: "sk-abc-123",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.ok(seenHeaders, "stub did not receive headers");
+    assert.equal(seenHeaders["x-api-key"], "sk-abc-123");
+    assert.equal(seenHeaders["anthropic-version"], "2023-06-01");
+    assert.equal(seenHeaders["content-type"], "application/json");
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("invalid opts → returns null without throwing", async () => {
+  assert.equal(await countTokens(null), null);
+  assert.equal(await countTokens({}), null);
+  assert.equal(
+    await countTokens({ apiKey: "", model: "m", messages: [], timeoutMs: 100 }),
+    null
+  );
+  assert.equal(
+    await countTokens({ apiKey: "k", model: "", messages: [], timeoutMs: 100 }),
+    null
+  );
+  assert.equal(
+    await countTokens({ apiKey: "k", model: "m", messages: "no", timeoutMs: 100 }),
+    null
+  );
+  assert.equal(
+    await countTokens({ apiKey: "k", model: "m", messages: [], timeoutMs: 0 }),
+    null
+  );
+});

package/scripts/context-meter/test-injector.js

@@ -0,0 +1,55 @@
+/**
+ * test-injector.js — TEST-ONLY INFRASTRUCTURE. DO NOT REQUIRE FROM PRODUCTION CODE.
+ *
+ * Loaded into the child process via NODE_OPTIONS=--require when running the
+ * E2E test at `scripts/gsd-t-context-meter.e2e.test.js`. Its job is to monkey-
+ * patch `count-tokens-client.countTokens` so the real child-process hook (which
+ * normally calls https://api.anthropic.com) is redirected to a local stub HTTP
+ * server bound on 127.0.0.1:{random-port}.
+ *
+ * Production NEVER loads this file:
+ *   - The hook script (`scripts/gsd-t-context-meter.js`) does not require it.
+ *   - The npm installer does not ship `NODE_OPTIONS` anywhere near it.
+ *   - The file lives under `scripts/context-meter/` only so the E2E test can
+ *     point `--require` at a stable absolute path; nothing in the runtime
+ *     require graph pulls it in on its own.
+ *
+ * Activation:
+ *   - Reads `process.env.GSD_T_CONTEXT_METER_TEST_BASE_URL`. If unset, the file
+ *     is a no-op (and `NODE_OPTIONS=--require` with this path on a production
+ *     invocation would still be a harmless no-op).
+ *   - When set, resolves and requires `./count-tokens-client`, wraps its
+ *     `countTokens` export to inject `_baseUrl` before every call, and
+ *     reassigns the property on the same module.exports object — so any later
+ *     `require('./count-tokens-client')` from the hook sees the patched fn.
+ *
+ * Why this exists:
+ *   Tasks 1–4 tested `runMeter()` via dependency injection. Task 5 tests the
+ *   real child-process hook as Claude Code would invoke it, which means no DI
+ *   seams are available — only stdin, stdout, and env. The hook's CLI shim does
+ *   not accept `_baseUrl` as a config param (by design: production must never
+ *   be routable to a non-Anthropic host). So the only honest way to redirect
+ *   HTTP in a black-box test is to monkey-patch the HTTP client *inside* the
+ *   child process, gated on a test-only env var. That is what this file does.
+ *
+ * @module scripts/context-meter/test-injector
+ */
+
+"use strict";
+
+const baseUrl = process.env.GSD_T_CONTEXT_METER_TEST_BASE_URL;
+if (baseUrl && typeof baseUrl === "string" && baseUrl.length > 0) {
+  try {
+    const clientPath = require.resolve("./count-tokens-client");
+    const client = require(clientPath);
+    const original = client.countTokens;
+    if (typeof original === "function") {
+      client.countTokens = function patchedCountTokens(opts) {
+        const merged = Object.assign({}, opts || {}, { _baseUrl: baseUrl });
+        return original(merged);
+      };
+    }
+  } catch (_) {
+    // Silent — an injector failure must never break the child process.
+  }
+}

package/scripts/context-meter/threshold.js

@@ -0,0 +1,88 @@
+/**
+ * scripts/context-meter/threshold.js
+ *
+ * Pure-function module for the context-meter PostToolUse hook.
+ *
+ * Responsibilities:
+ *   1. Compute the context-window percentage from a token count + window size.
+ *   2. Map that percentage to a token-budget band (normal / warn / stop).
+ *      Boundaries mirror bin/token-budget.js v3.0.0 exactly so the
+ *      `threshold` field in the state file is consistent across consumers.
+ *   3. Build the exact `additionalContext` string the hook emits when the
+ *      measured percentage meets or exceeds the configured thresholdPct.
+ *
+ * v3.0.0 (M35): The `downgrade` and `conserve` bands were REMOVED. The
+ * three-band model is: normal < 70 ≤ warn < 85 ≤ stop. Silent model
+ * degradation and silent phase-skipping violate GSD-T's quality principles.
+ *
+ * Zero side effects. Zero dependencies. CommonJS.
+ */
+
+// ── Band boundaries (must match bin/token-budget.js THRESHOLDS exactly) ──────
+// Lower bound inclusive, upper bound exclusive.
+const BANDS = Object.freeze({
+  warn: 70,
+  stop: 85,
+});
+
+/**
+ * Compute context-window percentage (0–100+).
+ *
+ * Fail-safe: any non-finite, negative, or zero-window input returns 0 — the
+ * caller should treat 0 as "normal/safe, no action needed".
+ *
+ * Does NOT clamp above 100. If real usage reports 102.3%, return 102.3; the
+ * band mapping handles it (>= 95 → stop).
+ *
+ * @param {{ inputTokens: number, modelWindowSize: number }} args
+ * @returns {number}
+ */
+function computePct({ inputTokens, modelWindowSize } = {}) {
+  if (!Number.isFinite(inputTokens) || !Number.isFinite(modelWindowSize)) {
+    return 0;
+  }
+  if (inputTokens < 0 || modelWindowSize <= 0) {
+    return 0;
+  }
+  return (inputTokens / modelWindowSize) * 100;
+}
+
+/**
+ * Map a percentage to a token-budget band (v3.0.0 three-band model).
+ *
+ * Boundaries (inclusive on the lower edge):
+ *   pct <  70 → "normal"
+ *   pct <  85 → "warn"
+ *   pct >= 85 → "stop"
+ *
+ * Non-finite input → "normal" (fail-safe — never escalate on garbage).
+ *
+ * @param {number} pct
+ * @returns {"normal"|"warn"|"stop"}
+ */
+function bandFor(pct) {
+  if (!Number.isFinite(pct)) return "normal";
+  if (pct >= BANDS.stop) return "stop";
+  if (pct >= BANDS.warn) return "warn";
+  return "normal";
+}
+
+/**
+ * Build the `additionalContext` string the hook emits, or null if the
+ * measured percentage is below the configured thresholdPct.
+ *
+ * Exact format (from .gsd-t/contracts/context-meter-contract.md line 139):
+ *   ⚠️ Context window at {pct.toFixed(1)}% of {modelWindowSize}. Run /user:gsd-t-pause to checkpoint and clear before continuing.
+ *
+ * `modelWindowSize` is emitted as the raw integer — no commas, no "K" suffix.
+ *
+ * @param {{ pct: number, modelWindowSize: number, thresholdPct: number }} args
+ * @returns {string|null}
+ */
+function buildAdditionalContext({ pct, modelWindowSize, thresholdPct } = {}) {
+  if (!Number.isFinite(pct) || !Number.isFinite(thresholdPct)) return null;
+  if (pct < thresholdPct) return null;
+  return `⚠️ Context window at ${pct.toFixed(1)}% of ${modelWindowSize}. Run /user:gsd-t-pause to checkpoint and clear before continuing.`;
+}
+
+module.exports = { computePct, bandFor, buildAdditionalContext, BANDS };

package/scripts/context-meter/threshold.test.js

@@ -0,0 +1,255 @@
+/**
+ * scripts/context-meter/threshold.test.js
+ *
+ * Tests for threshold.js — context-meter's pure-function band/emit module.
+ * Run: node --test scripts/context-meter/threshold.test.js
+ */
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const {
+  computePct,
+  bandFor,
+  buildAdditionalContext,
+  BANDS,
+} = require("./threshold");
+
+// ── computePct ───────────────────────────────────────────────────────────────
+
+test("computePct — happy path 50%", () => {
+  assert.equal(
+    computePct({ inputTokens: 100000, modelWindowSize: 200000 }),
+    50
+  );
+});
+
+test("computePct — zero window returns 0", () => {
+  assert.equal(
+    computePct({ inputTokens: 100000, modelWindowSize: 0 }),
+    0
+  );
+});
+
+test("computePct — negative window returns 0", () => {
+  assert.equal(
+    computePct({ inputTokens: 100000, modelWindowSize: -1 }),
+    0
+  );
+});
+
+test("computePct — negative input returns 0", () => {
+  assert.equal(
+    computePct({ inputTokens: -5, modelWindowSize: 200000 }),
+    0
+  );
+});
+
+test("computePct — NaN input returns 0", () => {
+  assert.equal(
+    computePct({ inputTokens: NaN, modelWindowSize: 200000 }),
+    0
+  );
+});
+
+test("computePct — NaN window returns 0", () => {
+  assert.equal(
+    computePct({ inputTokens: 100000, modelWindowSize: NaN }),
+    0
+  );
+});
+
+test("computePct — Infinity returns 0", () => {
+  assert.equal(
+    computePct({ inputTokens: Infinity, modelWindowSize: 200000 }),
+    0
+  );
+});
+
+test("computePct — missing args returns 0", () => {
+  assert.equal(computePct({}), 0);
+  assert.equal(computePct(), 0);
+});
+
+test("computePct — does NOT clamp above 100", () => {
+  assert.equal(
+    computePct({ inputTokens: 250000, modelWindowSize: 200000 }),
+    125
+  );
+});
+
+test("computePct — small fraction", () => {
+  const result = computePct({ inputTokens: 1, modelWindowSize: 200000 });
+  assert.ok(result > 0 && result < 0.001);
+});
+
+// ── bandFor — boundary sweep (v3.0.0 three-band: normal/warn/stop) ───────────
+
+test("bandFor — 0 → normal", () => {
+  assert.equal(bandFor(0), "normal");
+});
+
+test("bandFor — 69 → normal", () => {
+  assert.equal(bandFor(69), "normal");
+});
+
+test("bandFor — 69.9 → normal", () => {
+  assert.equal(bandFor(69.9), "normal");
+});
+
+test("bandFor — 70 → warn (inclusive lower)", () => {
+  assert.equal(bandFor(70), "warn");
+});
+
+test("bandFor — 71 → warn", () => {
+  assert.equal(bandFor(71), "warn");
+});
+
+test("bandFor — 84 → warn", () => {
+  assert.equal(bandFor(84), "warn");
+});
+
+test("bandFor — 84.9 → warn", () => {
+  assert.equal(bandFor(84.9), "warn");
+});
+
+test("bandFor — 85 → stop (inclusive lower)", () => {
+  assert.equal(bandFor(85), "stop");
+});
+
+test("bandFor — 86 → stop", () => {
+  assert.equal(bandFor(86), "stop");
+});
+
+test("bandFor — 95 → stop", () => {
+  assert.equal(bandFor(95), "stop");
+});
+
+test("bandFor — 150 → stop (no upper clamp)", () => {
+  assert.equal(bandFor(150), "stop");
+});
+
+test("bandFor — NaN → normal (fail-safe)", () => {
+  assert.equal(bandFor(NaN), "normal");
+});
+
+test("bandFor — Infinity → normal (fail-safe: Infinity is NOT finite)", () => {
+  assert.equal(bandFor(Infinity), "normal");
+});
+
+test("bandFor — undefined → normal", () => {
+  assert.equal(bandFor(undefined), "normal");
+});
+
+test("BANDS constant mirrors bin/token-budget.js v3.0.0 three-band model", () => {
+  // Guard against accidental drift from the token-budget boundaries.
+  assert.deepEqual(BANDS, { warn: 70, stop: 85 });
+});
+
+// ── buildAdditionalContext ───────────────────────────────────────────────────
+
+test("buildAdditionalContext — below threshold returns null", () => {
+  assert.equal(
+    buildAdditionalContext({ pct: 50, modelWindowSize: 200000, thresholdPct: 75 }),
+    null
+  );
+});
+
+test("buildAdditionalContext — at threshold returns string", () => {
+  const result = buildAdditionalContext({
+    pct: 75,
+    modelWindowSize: 200000,
+    thresholdPct: 75,
+  });
+  assert.ok(typeof result === "string");
+  assert.ok(result.includes("75.0%"));
+});
+
+test("buildAdditionalContext — above threshold exact contract string", () => {
+  const result = buildAdditionalContext({
+    pct: 76.2,
+    modelWindowSize: 200000,
+    thresholdPct: 75,
+  });
+  assert.equal(
+    result,
+    "⚠️ Context window at 76.2% of 200000. Run /user:gsd-t-pause to checkpoint and clear before continuing."
+  );
+});
+
+test("buildAdditionalContext — decimal formatting rounds via toFixed(1)", () => {
+  const result = buildAdditionalContext({
+    pct: 76.25,
+    modelWindowSize: 200000,
+    thresholdPct: 75,
+  });
+  // toFixed(1) on 76.25 → "76.3" (banker rounds vary but V8 gives "76.3" here)
+  assert.ok(result.includes("76.3%") || result.includes("76.2%"));
+  // Either rounding is acceptable — what matters is one decimal place.
+  const match = result.match(/at (\d+\.\d)% of/);
+  assert.ok(match, "must have exactly one decimal place");
+});
+
+test("buildAdditionalContext — modelWindowSize emitted raw (no commas)", () => {
+  const result = buildAdditionalContext({
+    pct: 80,
+    modelWindowSize: 200000,
+    thresholdPct: 75,
+  });
+  assert.ok(result.includes("of 200000."));
+  assert.ok(!result.includes("200,000"));
+  assert.ok(!result.includes("200K"));
+});
+
+test("buildAdditionalContext — NaN pct returns null", () => {
+  assert.equal(
+    buildAdditionalContext({ pct: NaN, modelWindowSize: 200000, thresholdPct: 75 }),
+    null
+  );
+});
+
+test("buildAdditionalContext — NaN thresholdPct returns null", () => {
+  assert.equal(
+    buildAdditionalContext({ pct: 80, modelWindowSize: 200000, thresholdPct: NaN }),
+    null
+  );
+});
+
+test("buildAdditionalContext — missing args returns null", () => {
+  assert.equal(buildAdditionalContext({}), null);
+  assert.equal(buildAdditionalContext(), null);
+});
+
+test("buildAdditionalContext — zero pct vs zero threshold emits", () => {
+  // 0 >= 0 is true — edge case: if thresholdPct is 0, every call emits.
+  const result = buildAdditionalContext({
+    pct: 0,
+    modelWindowSize: 200000,
+    thresholdPct: 0,
+  });
+  assert.ok(typeof result === "string");
+  assert.ok(result.includes("0.0%"));
+});
+
+test("buildAdditionalContext — pct over 100% still formats correctly", () => {
+  const result = buildAdditionalContext({
+    pct: 102.3,
+    modelWindowSize: 200000,
+    thresholdPct: 75,
+  });
+  assert.equal(
+    result,
+    "⚠️ Context window at 102.3% of 200000. Run /user:gsd-t-pause to checkpoint and clear before continuing."
+  );
+});
+
+test("buildAdditionalContext — different modelWindowSize (1M)", () => {
+  const result = buildAdditionalContext({
+    pct: 80,
+    modelWindowSize: 1000000,
+    thresholdPct: 75,
+  });
+  assert.equal(
+    result,
+    "⚠️ Context window at 80.0% of 1000000. Run /user:gsd-t-pause to checkpoint and clear before continuing."
+  );
+});