devspend 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhx842htt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# devspend
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **One ledger for your AI dev spend. Tagged by project. Ready to bill.**
+
+Repo: <https://github.com/zhx842htt/devspend>
+
+If you deliver client work with Claude Code, API keys, and AI subscriptions, you're probably spending **$80–300/month on AI** — and you can't say which client it went to, let alone put it on an invoice.
+
+**devspend** reads your local agent logs and API usage, tags every dollar by project, and turns it into invoice-ready line items. 100% local. Zero cloud. Zero config.
+
+## Quickstart
+
+```bash
+npx devspend report      # spend by day (last 30d)
+npx devspend projects    # spend by project — the billing view
+npx devspend models      # spend by model
+```
+
+It reads Claude Code session logs from `~/.claude/projects` by default. Point it anywhere:
+
+```bash
+npx devspend projects --path /some/other/log/dir
+```
+
+## How billing-accurate pricing works
+
+Token costs include cache pricing (cache writes ≈ 1.25× input, cache reads ≈ 0.1× input), and prices are fully overridable at `~/.devspend/prices.json`:
+
+```json
+[{ "match": "claude-sonnet", "input": 3, "output": 15 }]
+```
+
+Default prices ship built-in as sane estimates — **calibrate them to your plan before invoicing** (subscription plans like Claude Max don't pay per-token rates).
+
+## Roadmap
+
+- **Phase 1** — API usage ingest (OpenRouter / OpenAI / Anthropic, read-only keys), subscription entries, project aliases, local web dashboard
+- **Phase 2 (Pro)** — client entities, invoice-grade exports (CSV/PDF), budget alerts, optional encrypted sync. One-time license, no subscription.
+
+## How is this different from ccusage?
+
+[ccusage](https://github.com/ryoppippi/ccusage) is an excellent free CLI for Claude Code usage stats — this project stands on its shoulders for the log format. devspend is built one layer up, for **billing**: multi-source ingest, project/client attribution, and invoice-ready exports. Use both if you like; devspend will always keep the CLI free.
+
+## Privacy
+
+Everything runs on your machine. No telemetry, no accounts, no cloud. Open core (MIT); Pro adds billing workflows, not locks on your data.
+
+## License
+
+MIT

package/bin/devspend.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// devspend — 你的 AI 开发开销账本
+// 用法:
+//   npx devspend report  [--path 日志目录] [--days 30]   按日汇总
+//   npx devspend projects [--path 日志目录]              按项目汇总(可计费归集的基础)
+//   npx devspend models   [--path 日志目录]              按模型汇总
+//   npx devspend prices                                  查看当前价格表
+import { defaultClaudeDir, collectUsage } from '../src/ingest/claude-code.mjs';
+import { loadPrices, DEFAULT_PRICES } from '../src/pricing.mjs';
+import { reportByDay, reportByProject, reportByModel } from '../src/report.mjs';
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--path') out.path = argv[++i];
+    else if (a === '--days') out.days = parseInt(argv[++i], 10);
+    else out._.push(a);
+  }
+  return out;
+}
+
+function help() {
+  console.log(`devspend — 你的 AI 开发开销账本
+
+命令:
+  report    [--path 目录] [--days N]  按日汇总 Claude Code 用量与成本
+  projects  [--path 目录]             按项目路径汇总(计费归集的基础)
+  models    [--path 目录]             按模型汇总
+  prices                                打印当前生效的价格表
+
+默认读取 ~/.claude/projects 下的会话日志,一切数据只在本机处理。`);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._[0] || 'report';
+
+if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  help();
+} else if (cmd === 'prices') {
+  console.log('当前价格表(USD / 百万 token,用户覆盖优先):');
+  for (const p of loadPrices().list) console.log(`  ${String(p.match)}  in=$${p.input}  out=$${p.output}`);
+  console.log(`\n内置默认 ${DEFAULT_PRICES.length} 条,可在 ~/.devspend/prices.json 覆盖。`);
+} else if (cmd === 'report' || cmd === 'projects' || cmd === 'models') {
+  const dir = args.path || defaultClaudeDir();
+  const prices = loadPrices();
+  const rows = collectUsage(dir);
+  if (cmd === 'report') reportByDay(rows, prices, args.days || 30);
+  if (cmd === 'projects') reportByProject(rows, prices);
+  if (cmd === 'models') reportByModel(rows, prices);
+} else {
+  console.error(`未知命令: ${cmd}`);
+  help();
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "devspend",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "One ledger for your AI dev spend — agent logs, API usage, subscriptions. Tagged by project, ready to bill.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhx842htt/devspend.git"
+  },
+  "homepage": "https://github.com/zhx842htt/devspend#readme",
+  "bugs": {
+    "url": "https://github.com/zhx842htt/devspend/issues"
+  },
+  "bin": {
+    "devspend": "bin/devspend.mjs"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "test": "node bin/devspend.mjs report --path test/fixtures && node bin/devspend.mjs projects --path test/fixtures"
+  },
+  "keywords": [
+    "ai",
+    "cost",
+    "spending",
+    "claude",
+    "claude-code",
+    "cursor",
+    "openai",
+    "openrouter",
+    "invoice",
+    "freelance"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ]
+}

package/src/ingest/claude-code.mjs

@@ -0,0 +1,74 @@
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// Claude Code 的本地会话日志: ~/.claude/projects/<project-slug>/<sessionId>.jsonl
+// 已知格式(以 ccusage 等工具的解析口径为准):
+//   每行一个 JSON,assistant 消息形如
+//   { type:"assistant", timestamp, sessionId, cwd,
+//     message:{ id, model, usage:{ input_tokens, output_tokens,
+//       cache_creation_input_tokens, cache_read_input_tokens } } }
+// 字段在不同版本间有改名(cache_creation -> cache_creation_input_tokens),此处两个口径都收。
+
+export function defaultClaudeDir() {
+  return join(homedir(), '.claude', 'projects');
+}
+
+export function* jsonlEntries(dir) {
+  if (!existsSync(dir)) return;
+  const jsonlFiles = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      // Claude Code 原生布局: <dir>/<project-slug>/<sessionId>.jsonl
+      for (const f of readdirSync(join(dir, entry.name))) {
+        if (f.endsWith('.jsonl')) jsonlFiles.push(join(dir, entry.name, f));
+      }
+    } else if (entry.name.endsWith('.jsonl')) {
+      // 平铺布局: <dir>/*.jsonl(方便用户直接指定任意目录)
+      jsonlFiles.push(join(dir, entry.name));
+    }
+  }
+  for (const full of jsonlFiles) {
+    const text = readFileSync(full, 'utf8');
+    for (const line of text.split('\n')) {
+      const t = line.trim();
+      if (!t) continue;
+      let entry;
+      try {
+        entry = JSON.parse(t);
+      } catch {
+        continue; // 跳过截断/损坏行
+      }
+      yield entry;
+    }
+  }
+}
+
+// 汇总成统一的 usage 行;按 message id + 时间戳去重(流式写入可能产生重复行)
+export function collectUsage(dir) {
+  const rows = [];
+  const seen = new Set();
+  for (const e of jsonlEntries(dir)) {
+    const u = e && e.message && e.message.usage;
+    if (!u || !e.timestamp) continue;
+    // message.id 全局唯一,以它为主键去重(流式/重放会产生重复行);
+    // 没有 id 的旧格式行退回到"时间戳+会话+用量指纹"去重
+    const fingerprint = `${u.input_tokens}|${u.output_tokens}|${u.cache_creation_input_tokens || 0}|${u.cache_read_input_tokens || 0}`;
+    const key = e.message.id || `${e.timestamp}|${e.sessionId || ''}|${fingerprint}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const usage = u || {};
+    const cacheObj = usage.cache_creation || {};
+    rows.push({
+      ts: new Date(e.timestamp),
+      sessionId: e.sessionId || 'unknown',
+      project: e.cwd || '(未知项目)',
+      model: (e.message && e.message.model) || 'unknown',
+      input: usage.input_tokens || 0,
+      output: usage.output_tokens || 0,
+      cacheWrite: usage.cache_creation_input_tokens ?? cacheObj.input_tokens ?? 0,
+      cacheRead: usage.cache_read_input_tokens ?? (usage.cache_read || {}).input_tokens ?? 0,
+    });
+  }
+  return rows;
+}

package/src/pricing.mjs

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// 出厂默认价(USD / 每百万 token)。各家调价频繁,用户务必用 ~/.devspend/prices.json 覆盖校准。
+// 覆盖格式:[{ "match": "claude-sonnet", "input": 3, "output": 15 }]
+export const DEFAULT_PRICES = [
+  { match: /claude.*opus/i, input: 15, output: 75 },
+  { match: /claude.*(sonnet|4-5)/i, input: 3, output: 15 },
+  { match: /claude.*haiku/i, input: 0.8, output: 4 },
+  { match: /gpt-5/i, input: 1.25, output: 10 },
+  { match: /gpt-4o-mini/i, input: 0.15, output: 0.6 },
+  { match: /gpt-4o/i, input: 2.5, output: 10 },
+  { match: /gpt-4\.1/i, input: 2.5, output: 10 },
+];
+
+const CACHE_READ_MULTIPLIER = 0.1;   // 缓存读约为输入价 1 折
+const CACHE_WRITE_MULTIPLIER = 1.25; // 缓存写约为输入价 1.25 倍
+
+export function loadPrices() {
+  const overrides = [];
+  const overridePath = join(homedir(), '.devspend', 'prices.json');
+  if (existsSync(overridePath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(overridePath, 'utf8'));
+      for (const o of parsed) {
+        overrides.push({ match: new RegExp(o.match, 'i'), input: o.input, output: o.output });
+      }
+    } catch {
+      console.error(`[devspend] 警告: ${overridePath} 解析失败,已忽略,使用默认价格表`);
+    }
+  }
+  // 用户覆盖优先于默认
+  return { list: [...overrides, ...DEFAULT_PRICES] };
+}
+
+export function costOf(model, usage, prices) {
+  const rule = prices.list.find((p) => p.match.test(model));
+  if (!rule) return { cost: 0, unknown: true };
+  const cacheWrite = usage.cacheWrite || 0;
+  const cacheRead = usage.cacheRead || 0;
+  const billableInput =
+    (usage.input || 0) +
+    cacheWrite * CACHE_WRITE_MULTIPLIER +
+    cacheRead * CACHE_READ_MULTIPLIER;
+  const billableOutput = usage.output || 0;
+  return {
+    cost: (billableInput * rule.input + billableOutput * rule.output) / 1e6,
+    unknown: false,
+  };
+}

package/src/report.mjs

@@ -0,0 +1,82 @@
+import { costOf } from './pricing.mjs';
+
+function fmtUSD(n) {
+  if (n === 0) return '$0';
+  if (n < 0.01) return '$' + n.toFixed(4);
+  if (n < 1) return '$' + n.toFixed(3);
+  return '$' + n.toFixed(2);
+}
+
+function sumBy(rows, keyFn, prices) {
+  const map = new Map();
+  const unknownModels = new Set();
+  for (const r of rows) {
+    const { cost, unknown } = costOf(r.model, r, prices);
+    if (unknown) unknownModels.add(r.model);
+    const key = keyFn(r);
+    const cur = map.get(key) || { cost: 0, rows: 0, tokensIn: 0, tokensOut: 0 };
+    cur.cost += cost;
+    cur.rows += 1;
+    cur.tokensIn += r.input + r.cacheWrite + r.cacheRead;
+    cur.tokensOut += r.output;
+    map.set(key, cur);
+  }
+  return { map, unknownModels };
+}
+
+function printTable(title, entries, unit) {
+  console.log(`\n${title}`);
+  const w = [28, 12, 14, 16];
+  console.log(
+    [unit.padEnd(w[0]), '花费'.padStart(w[1]), '输入tok'.padStart(w[2]), '输出tok'.padStart(w[3])].join('')
+  );
+  let total = 0;
+  for (const [key, v] of entries) {
+    total += v.cost;
+    console.log(
+      [
+        key.slice(0, w[0]).padEnd(w[0]),
+        fmtUSD(v.cost).padStart(w[1]),
+        (v.tokensIn >= 1e6 ? (v.tokensIn / 1e6).toFixed(1) + 'M' : Math.round(v.tokensIn / 1e3) + 'K').padStart(w[2]),
+        (v.tokensOut >= 1e6 ? (v.tokensOut / 1e6).toFixed(1) + 'M' : Math.round(v.tokensOut / 1e3) + 'K').padStart(w[3]),
+      ].join('')
+    );
+  }
+  console.log('─'.repeat(w[0] + w[1] + w[2] + w[3]));
+  console.log(`${'合计'.padEnd(w[0])}${fmtUSD(total).padStart(w[1])}`);
+  return total;
+}
+
+export function reportByDay(rows, prices, days) {
+  const cutoff = Date.now() - days * 86400 * 1000;
+  const recent = rows.filter((r) => r.ts.getTime() >= cutoff);
+  if (recent.length === 0) {
+    console.log(`近 ${days} 天没有找到任何用量记录。`);
+    console.log('提示: 用 --path 指定日志目录,或先运行 Claude Code 产生本地日志。');
+    return;
+  }
+  const { map, unknownModels } = sumBy(recent, (r) => r.ts.toISOString().slice(0, 10), prices);
+  const total = printTable(`devspend · 近 ${days} 天按日汇总`, [...map.entries()].sort(), '日期');
+  printModelWarning(unknownModels);
+  console.log(`\n(价格为出厂估算,可在 ~/.devspend/prices.json 覆盖;本期合计 ${fmtUSD(total)})`);
+}
+
+export function reportByProject(rows, prices) {
+  const { map, unknownModels } = sumBy(rows, (r) => r.project, prices);
+  const entries = [...map.entries()].sort((a, b) => b[1].cost - a[1].cost);
+  printTable('devspend · 按项目汇总(全量)', entries, '项目路径');
+  printModelWarning(unknownModels);
+}
+
+export function reportByModel(rows, prices) {
+  const { map } = sumBy(rows, (r) => r.model, prices);
+  const entries = [...map.entries()].sort((a, b) => b[1].cost - a[1].cost);
+  printTable('devspend · 按模型汇总(全量)', entries, '模型');
+}
+
+function printModelWarning(unknownModels) {
+  if (unknownModels.size > 0) {
+    console.log(`\n⚠ 未知价格模型的 token 未计价: ${[...unknownModels].join(', ')}`);
+    console.log('  请在 ~/.devspend/prices.json 里为它们添加价格规则。');
+  }
+}