costlayers 0.8.15 → 0.8.17

package/README.md

@@ -2,29 +2,30 @@
 
 CostLayers helps coding-agent users stop paying for repeated repo context. API users can route model calls through the gateway for invoice savings. ChatGPT-login Codex users get a usage-stretch meter that shows how much repeated context was avoided.
 
-## Install
+## Quick Start
 
-One-command setup:
+Daily Codex use:
 
 ```bash
 cd your-repo
-npx -y costlayers@latest start --email you@example.com
+npx -y costlayers@latest codex --email you@example.com --chatgpt
 ```
 
-## Usage
+This default path preserves Codex's native ChatGPT-login/provider flow and shows a usage-stretch meter. CostLayers only routes billable API traffic when you explicitly pass `--api`.
 
-Inside a repo:
+Run a one-command API savings test:
 
 ```bash
-costlayers init
-costlayers scan
+export OPENAI_API_KEY=sk-proj-...
+npx -y costlayers@latest test --email you@example.com
 ```
 
-Launch Codex with CostLayers context:
+## Usage
+
+Inside a repo:
 
 ```bash
-cd your-repo
-npx -y costlayers@latest start --email you@example.com -- codex
+npx -y costlayers@latest codex --email you@example.com --chatgpt
 ```
 
 This gives Codex `.agentspend/repo-pack.md` and `.agentspend/runtime-plan.md`
@@ -44,7 +45,7 @@ API write permission:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-...
-npx -y costlayers@latest start --email you@example.com --codex-proxy -- codex
+npx -y costlayers@latest codex --email you@example.com --api
 ```
 
 ChatGPT-login Codex can be metered, but it does not create per-request OpenAI
@@ -52,8 +53,9 @@ Platform invoice savings because it is not billed through your Platform API key.
 
 ## Which Mode Should I Use?
 
-- ChatGPT-login Codex: use `start -- codex` to reduce repeated repo context and stretch usage limits.
-- OpenAI Platform API billing: use `--codex-proxy` with `OPENAI_API_KEY` for invoice-backed savings.
+- ChatGPT-login Codex: use `costlayers codex --email you@example.com --chatgpt` to reduce repeated repo context and stretch usage limits.
+- OpenAI Platform API billing: set `OPENAI_API_KEY`, then use `costlayers codex --email you@example.com --api` for invoice-backed savings.
+- Savings proof: set `OPENAI_API_KEY`, then run `costlayers test --email you@example.com`.
 - Other OpenAI-compatible clients: point the client at the CostLayers gateway URL and check `costlayers gateway report`.
 
 To install only the Codex profile after signup:

package/bin/agentspend.js

@@ -9,7 +9,7 @@ const https = require("https");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
-const VERSION = "0.8.15";
+const VERSION = "0.8.17";
 const INSTALL_SPEC = "costlayers@latest";
 const DEFAULT_RUNS_PER_WEEK = 20;
 const WEEKS_PER_MONTH = 4.33;
@@ -50,6 +50,8 @@ function usage(exitCode = 0) {
 CostLayers ${VERSION}
 
 Usage:
+  costlayers codex [--email <email>] [--chatgpt|--api] [-- <codex args>]
+  costlayers test [--email <email>] [--prompt <text>]
   costlayers init [--repo <path>]
   costlayers scan [--repo <path>] [--price-per-1m <usd>] [--tasks <n>] [--runs-per-week <n>]
   costlayers start [--email <email>] [--provider-url <url>] [--mode measure|reduce] [--runs-per-week <n>] [--codex-proxy] [-- <agent command>]
@@ -64,6 +66,8 @@ Usage:
   costlayers doctor
 
 Commands:
+  codex   Start Codex with CostLayers. Defaults to ChatGPT-login mode unless --api is passed.
+  test    Run a safe read-only API invoice-mode Codex task and print the CostLayers savings report.
   init    Create .agentspend config and agent instructions.
   scan    Build repo context pack and savings report.
   start   One-command setup, signup, gateway start, and optional agent run.
@@ -103,6 +107,14 @@ function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
 
+function chmodBestEffort(file, mode) {
+  try {
+    fs.chmodSync(file, mode);
+  } catch {
+    // Windows and some network filesystems may ignore POSIX modes.
+  }
+}
+
 function writeIfMissing(file, content) {
   if (!fs.existsSync(file)) fs.writeFileSync(file, content, "utf8");
 }
@@ -123,7 +135,7 @@ function guardRepoRoot(repo, args) {
     "",
     "Run it inside a project folder instead:",
     "  cd path/to/your-repo",
-    `  npx -y ${INSTALL_SPEC} start --email you@example.com`,
+    `  npx -y ${INSTALL_SPEC} codex --email you@example.com --chatgpt`,
     "",
     "Or pass --repo path/to/your-repo from anywhere.",
     "If you really intend to scan your whole home directory, add --allow-home.",
@@ -149,6 +161,101 @@ function normalizedEmail(value) {
   return String(value || "").trim().toLowerCase();
 }
 
+function configRoot() {
+  const base = process.env.XDG_CONFIG_HOME
+    ? path.join(process.env.XDG_CONFIG_HOME, "costlayers")
+    : path.join(os.homedir(), ".config", "costlayers");
+  ensureDir(base);
+  chmodBestEffort(base, 0o700);
+  return base;
+}
+
+function connectionsDir() {
+  const dir = path.join(configRoot(), "connections");
+  ensureDir(dir);
+  chmodBestEffort(dir, 0o700);
+  return dir;
+}
+
+function connectionSecretPath(connectionId) {
+  return path.join(connectionsDir(), `${connectionId}.json`);
+}
+
+function repoConnectionPath(repo) {
+  return path.join(repo, ".agentspend", "connection.json");
+}
+
+function ensureAgentSpendGitignore(outDir) {
+  ensureDir(outDir);
+  const file = path.join(outDir, ".gitignore");
+  const required = ["connection.json", "*.secret.json", "gateway-key.txt"];
+  let current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const lines = new Set(current.split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+  let changed = false;
+  for (const item of required) {
+    if (!lines.has(item)) {
+      current += `${current.endsWith("\n") || current.length === 0 ? "" : "\n"}${item}\n`;
+      changed = true;
+    }
+  }
+  if (changed || !fs.existsSync(file)) fs.writeFileSync(file, current, "utf8");
+}
+
+function connectionIdFor(repo, connection = {}) {
+  if (connection.connection_id) return String(connection.connection_id);
+  const seed = connection.api_key || `${path.resolve(repo)}\n${connection.engine_url || ""}\n${connection.email || ""}`;
+  return `cl_${sha256(seed).slice(0, 24)}`;
+}
+
+function publicConnectionMetadata(connection) {
+  return {
+    version: VERSION,
+    connection_id: connection.connection_id,
+    engine_url: connection.engine_url,
+    email: normalizedEmail(connection.email),
+    label: connection.label || "",
+    connected_utc: connection.connected_utc || new Date().toISOString(),
+    secret_store: "~/.config/costlayers/connections",
+    note: "Live CostLayers keys are stored outside the repo. Run `costlayers dashboard` to print your private dashboard URL."
+  };
+}
+
+function writePrivateJson(file, payload) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  chmodBestEffort(file, 0o600);
+}
+
+function saveConnection(repo, connection) {
+  const outDir = path.join(repo, ".agentspend");
+  ensureDir(outDir);
+  ensureAgentSpendGitignore(outDir);
+  const connectionId = connectionIdFor(repo, connection);
+  const full = {
+    ...connection,
+    connection_id: connectionId,
+    email: normalizedEmail(connection.email),
+    connected_utc: connection.connected_utc || new Date().toISOString()
+  };
+  writePrivateJson(connectionSecretPath(connectionId), full);
+  fs.writeFileSync(repoConnectionPath(repo), JSON.stringify(publicConnectionMetadata(full), null, 2) + "\n", "utf8");
+  return full;
+}
+
+function loadStoredConnection(repo) {
+  const saved = readJsonIfExists(repoConnectionPath(repo));
+  if (!saved) return null;
+  if (saved.api_key || saved.gateway_url) {
+    const migrated = saveConnection(repo, saved);
+    process.stdout.write(`CostLayers moved the live key out of .agentspend into ~/.config/costlayers.\n`);
+    return migrated;
+  }
+  const connectionId = saved.connection_id || connectionIdFor(repo, saved);
+  const secret = readJsonIfExists(connectionSecretPath(connectionId));
+  if (secret && secret.api_key) return { ...saved, ...secret, connection_id: connectionId };
+  return null;
+}
+
 function estimateTokens(text) {
   return Math.ceil(String(text || "").length / 4);
 }
@@ -403,9 +510,10 @@ This public scanner estimates repeated context waste. Real savings should be val
 `;
 }
 
-function init(repo) {
+function init(repo, options = {}) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
+  ensureAgentSpendGitignore(outDir);
   writeIfMissing(path.join(outDir, "config.json"), JSON.stringify({
     version: VERSION,
     created_utc: new Date().toISOString(),
@@ -421,7 +529,7 @@ function init(repo) {
     process.stdout.write(`AGENTS.md already exists; snippet saved to ${path.join(outDir, "AGENTS_SNIPPET.md")}\n`);
   }
   process.stdout.write(`CostLayers initialized in ${outDir}\n`);
-  process.stdout.write("Next: costlayers scan\n");
+  if (!options.suppressNext) process.stdout.write("Next: costlayers scan\n");
 }
 
 function scan(repo, args) {
@@ -447,21 +555,30 @@ function connectEngine(repo, args) {
     api_key: args["api-key"] ? String(args["api-key"]) : null,
     connected_utc: new Date().toISOString()
   };
-  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(config, null, 2) + "\n", "utf8");
+  saveConnection(repo, config);
   process.stdout.write(`Connected CostLayers engine: ${config.engine_url}\n`);
 }
 
 function loadConnection(repo, args) {
-  const outDir = path.join(repo, ".agentspend");
-  const saved = readJsonIfExists(path.join(outDir, "connection.json")) || {};
+  const saved = loadStoredConnection(repo) || {};
   const engineUrl = String(args["engine-url"] || saved.engine_url || "").replace(/\/+$/, "");
   if (!engineUrl) {
-    process.stderr.write("Missing engine connection. Run `agentspend connect --engine-url <url>` first.\n");
+    process.stderr.write("Missing engine connection. Run `costlayers signup --email you@example.com` first.\n");
+    process.exit(2);
+  }
+  const apiKey = args["api-key"] ? String(args["api-key"]) : saved.api_key || null;
+  if (!apiKey) {
+    process.stderr.write([
+      "CostLayers cannot find the live key for this repo.",
+      "Keys are stored outside the repo in ~/.config/costlayers/connections.",
+      "Run `costlayers signup --email you@example.com` again from this repo to create a fresh key.",
+      ""
+    ].join("\n"));
     process.exit(2);
   }
   return {
     engine_url: engineUrl,
-    api_key: args["api-key"] ? String(args["api-key"]) : saved.api_key || null
+    api_key: apiKey
   };
 }
 
@@ -538,16 +655,37 @@ function codexProxyApiKeyEnv(args = {}) {
   return String(args["api-key-env"] || "OPENAI_API_KEY");
 }
 
-function assertCodexProxyApiKey(args = {}) {
+function apiInvoiceModeRequested(args = {}) {
+  return Boolean(args.api || args.invoice || args["api-mode"] || codexProxyEnabled(args));
+}
+
+function chatgptModeRequested(args = {}) {
+  return Boolean(args.chatgpt || args["no-api"]);
+}
+
+function codexArgsAfterDash(argv) {
+  const dash = argv.indexOf("--");
+  return dash >= 0 ? argv.slice(dash + 1) : [];
+}
+
+function withAutoCodexMode(args = {}, options = {}) {
+  const next = { ...args };
+  const wantsInvoice = apiInvoiceModeRequested(next) || Boolean(options.forceInvoice);
+  if (!chatgptModeRequested(next) && wantsInvoice) next["codex-proxy"] = true;
+  return next;
+}
+
+function assertCodexProxyApiKey(args = {}, rerunCommand = "") {
   if (!codexProxyEnabled(args)) return;
   const keyEnv = codexProxyApiKeyEnv(args);
   if (process.env[keyEnv]) return;
+  const command = rerunCommand || `npx -y ${INSTALL_SPEC} codex --email you@example.com --api`;
   process.stderr.write([
     `CostLayers invoice mode needs ${keyEnv} in this shell.`,
     "",
     "Set an OpenAI Platform API key with Responses API write permission, then rerun:",
     `  export ${keyEnv}=sk-proj-...`,
-    `  npx -y ${INSTALL_SPEC} start --email you@example.com --codex-proxy -- codex`,
+    `  ${command}`,
     "",
     "ChatGPT-login Codex can be metered, but it cannot produce provider invoice savings because there is no per-request Platform invoice to reduce.",
     ""
@@ -647,19 +785,11 @@ async function signupConnection(repo, args) {
     label: payload.label,
     connected_utc: new Date().toISOString()
   };
-  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(connection, null, 2) + "\n", "utf8");
-  return connection;
-}
-
-function saveConnection(repo, connection) {
-  const outDir = path.join(repo, ".agentspend");
-  ensureDir(outDir);
-  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(connection, null, 2) + "\n", "utf8");
+  return saveConnection(repo, connection);
 }
 
 async function ensureConnection(repo, args) {
-  const outDir = path.join(repo, ".agentspend");
-  const saved = readJsonIfExists(path.join(outDir, "connection.json"));
+  const saved = loadStoredConnection(repo);
   const requestedEmail = normalizedEmail(args.email);
   if (saved && saved.engine_url && saved.api_key) {
     if (!requestedEmail) return saved;
@@ -811,7 +941,7 @@ async function runAgent(repo, args, argv, options = {}) {
   }
   if (!options.skipSetup) init(repo);
   const { outDir, pack, report } = options.precomputed || scanToFiles(repo, args);
-  const connection = readJsonIfExists(path.join(outDir, "connection.json"));
+  const connection = loadStoredConnection(repo);
   let plan = buildLocalPlan(report);
   if (connection && connection.engine_url) {
     try {
@@ -845,7 +975,9 @@ async function runAgent(repo, args, argv, options = {}) {
     stdio: "inherit",
     shell: process.platform === "win32"
   });
-  process.exit(typeof result.status === "number" ? result.status : 1);
+  const status = typeof result.status === "number" ? result.status : 1;
+  if (options.returnStatus) return status;
+  process.exit(status);
 }
 
 async function gateway(repo, args) {
@@ -918,12 +1050,57 @@ async function dashboard(repo, args) {
   process.stdout.write(`claim: API invoice savings only count when provider API traffic is routed through CostLayers. ChatGPT-login Codex shows usage stretch, not invoice reduction.\n`);
 }
 
-async function start(repo, args, argv) {
+async function codexShortcut(repo, args, argv) {
+  const codexTail = codexArgsAfterDash(argv);
+  const command = codexTail.length > 0 ? codexTail : ["codex"];
+  const commandToRun = isCodexCommand(command) ? command : ["codex", ...command];
+  const nextArgs = withAutoCodexMode(args);
+  if (codexProxyEnabled(nextArgs)) {
+    process.stdout.write(`CostLayers Codex: API invoice mode explicitly enabled from ${codexProxyApiKeyEnv(nextArgs)}.\n`);
+  } else {
+    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Pass --api to route API-billed provider calls for invoice savings.\n`);
+  }
+  return start(repo, nextArgs, ["start", "--", ...commandToRun]);
+}
+
+async function savingsTest(repo, args) {
+  const nextArgs = withAutoCodexMode({ ...args, api: true }, { forceInvoice: true });
+  if (!codexProxyEnabled(nextArgs)) {
+    const keyEnv = codexProxyApiKeyEnv(nextArgs);
+    process.stderr.write([
+      `CostLayers test needs ${keyEnv} for real API invoice savings.`,
+      "",
+      "Set your OpenAI Platform API key, then rerun:",
+      `  export ${keyEnv}=sk-proj-...`,
+      `  npx -y ${INSTALL_SPEC} test --email you@example.com`,
+      "",
+      `For ChatGPT-login metering without invoice savings, run:`,
+      `  npx -y ${INSTALL_SPEC} codex --email you@example.com --chatgpt`,
+      ""
+    ].join("\n"));
+    process.exit(2);
+  }
+  const prompt = typeof args.prompt === "string"
+    ? args.prompt
+    : "Analyze this repository. Find the main entry points, data flow, and the 5 files most worth reading. Do not edit files.";
+  assertCodexProxyApiKey(nextArgs, `npx -y ${INSTALL_SPEC} test --email you@example.com`);
+  process.stdout.write("CostLayers savings test: running one safe read-only Codex task.\n");
+  const status = await start(repo, nextArgs, ["start", "--", "codex", "exec", "--sandbox", "read-only", prompt], { returnStatus: true });
+  process.stdout.write("\nCostLayers savings test report\n");
+  try {
+    await gateway(repo, { ...nextArgs, _: ["gateway", "report"] });
+  } catch (err) {
+    process.stderr.write(`Could not fetch savings report: ${err.message}\n`);
+  }
+  process.exit(status);
+}
+
+async function start(repo, args, argv, options = {}) {
   const dash = argv.indexOf("--");
   const command = dash >= 0 ? argv.slice(dash + 1) : [];
   const codexTelemetryRun = command.length > 0 && isCodexCommand(command) && !codexProxyEnabled(args);
   if (command.length > 0 && isCodexCommand(command)) assertCodexProxyApiKey(args);
-  init(repo);
+  init(repo, { suppressNext: true });
   process.stdout.write(`Scanning repo: ${repo}\n`);
   const precomputed = scanToFiles(repo, args);
   const { outDir, pack, report } = precomputed;
@@ -972,12 +1149,13 @@ async function start(repo, args, argv) {
   process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
   process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
   if (command.length > 0) {
-    return runAgent(repo, args, argv, { skipSetup: true, precomputed });
+    return runAgent(repo, args, argv, { skipSetup: true, precomputed, returnStatus: options.returnStatus });
   }
   process.stdout.write(`\nNext options:\n`);
-  process.stdout.write(`  Use gateway URL in your model client: ${gatewayBaseUrl}\n`);
-  process.stdout.write(`  Run Codex metered: npx -y ${INSTALL_SPEC} start --email you@example.com -- codex\n`);
-  process.stdout.write(`  Reduce an OpenAI API invoice: export OPENAI_API_KEY=sk-proj-... && npx -y ${INSTALL_SPEC} start --email you@example.com --codex-proxy -- codex\n`);
+  process.stdout.write(`  ChatGPT-login Codex: npx -y ${INSTALL_SPEC} codex --email you@example.com --chatgpt\n`);
+  process.stdout.write(`  API invoice Codex: export OPENAI_API_KEY=sk-proj-... && npx -y ${INSTALL_SPEC} codex --email you@example.com --api\n`);
+  process.stdout.write(`  Other OpenAI-compatible client base URL: ${gatewayBaseUrl}\n`);
+  process.stdout.write(`  Prove API savings: npx -y ${INSTALL_SPEC} test --email you@example.com\n`);
   process.stdout.write(`  Or run Codex directly: codex --profile costlayers\n`);
   process.stdout.write(`  View report: npx -y ${INSTALL_SPEC} gateway report\n`);
   process.stdout.write(`  Dashboard: npx -y ${INSTALL_SPEC} dashboard\n`);
@@ -995,8 +1173,10 @@ function main() {
   const cmd = args._[0];
   if (!cmd || args.help || args.h) usage(0);
   const repo = path.resolve(String(args.repo || process.cwd()));
-  if (["init", "scan", "start", "run", "codex-profile"].includes(cmd)) guardRepoRoot(repo, args);
+  if (["init", "scan", "start", "run", "codex-profile", "codex", "test"].includes(cmd)) guardRepoRoot(repo, args);
   if (cmd === "doctor") return doctor();
+  if (cmd === "codex") return codexShortcut(repo, args, rawArgv);
+  if (cmd === "test") return savingsTest(repo, args);
   if (cmd === "init") return init(repo);
   if (cmd === "scan") return scan(repo, args);
   if (cmd === "start") return start(repo, args, rawArgv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "costlayers",
-  "version": "0.8.15",
+  "version": "0.8.17",
   "description": "CostLayers cost control for AI coding agents. Build compact repo context packs, gateway reports, and savings dashboards.",
   "bin": {
     "agentspend": "bin/agentspend.js",
@@ -8,6 +8,10 @@
   },
   "type": "commonjs",
   "license": "UNLICENSED",
+  "homepage": "https://costlayers.com",
+  "bugs": {
+    "url": "mailto:rishabh@costlayers.com"
+  },
   "private": false,
   "engines": {
     "node": ">=18"