@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vimoxshah/tokenflow",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Local-first, provider-agnostic analytics for the AI tokens you actually spend. Zero dependencies, nothing leaves your machine.",
   "type": "module",
   "license": "MIT",
@@ -18,16 +18,19 @@
   "files": [
     "bin",
     "src",
+    "design",
     "docs",
     "skills",
     "examples",
     "scripts",
+    "schemas",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
     "SECURITY.md",
     "CONTRIBUTING.md",
-    "Refresh & Open Dashboard.command"
+    "Refresh & Open Dashboard.command",
+    "Dockerfile.team"
   ],
   "scripts": {
     "setup": "node bin/tokenflow.js setup",
@@ -39,6 +42,8 @@
     "typecheck": "tsc --noEmit -p jsconfig.json",
     "typecheck:deps": "npm i --no-save --no-package-lock typescript@5 @types/node@22",
     "lint": "node scripts/lint.js",
+    "design": "node scripts/design-build.js",
+    "design:check": "node scripts/design-build.js --check",
     "validate": "node scripts/validate-install.js",
     "start": "node bin/tokenflow.js up",
     "up": "node bin/tokenflow.js up"

package/schemas/receipt.v0.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vimoxshah/tokenflow/schemas/receipt.v0.json",
+  "title": "TokenFlow branch receipt (v0)",
+  "description": "A portable, self-contained record of what one branch cost — designed to travel with the code as a git note (refs/notes/tokenflow) rather than live on a server. Every cost figure is estimated locally from token counts against a local price table, never measured billing, unless the underlying records say otherwise; see docs/receipt-schema.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "toolVersion",
+    "repo",
+    "branch",
+    "headSha",
+    "window",
+    "costUsd",
+    "contextShare",
+    "turns",
+    "sessions",
+    "subagentTurns",
+    "models",
+    "coverage",
+    "largestPromptTokens",
+    "changedLines",
+    "pr",
+    "longLived",
+    "costPer100Lines",
+    "notes"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 0,
+      "description": "Receipt schema version. This document describes version 0."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this receipt was computed, in UTC ISO-8601."
+    },
+    "toolVersion": {
+      "type": "string",
+      "description": "The TokenFlow package version that computed this receipt (package.json version)."
+    },
+    "repo": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The repository's name — the basename of its main checkout, resolved through git worktrees. Never a full path."
+    },
+    "branch": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The branch this receipt attributes spend to."
+    },
+    "headSha": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{7,40}$",
+      "description": "The commit sha this receipt is attached to (the local sha being pushed)."
+    },
+    "window": {
+      "description": "The first and last timestamp of a priced turn attributed to this branch, or null when there were none.",
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["first", "last"],
+          "properties": {
+            "first": { "type": ["string", "null"], "format": "date-time" },
+            "last": { "type": ["string", "null"], "format": "date-time" }
+          }
+        }
+      ]
+    },
+    "costUsd": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "description": "Estimated spend attributed to this branch, in US dollars. null when no turn on this branch had a priced model — never 0."
+    },
+    "contextShare": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Share of costUsd that paid to re-send prior context (cache reads + writes) rather than fresh input/output. A high share is the price of a long session, not necessarily waste."
+    },
+    "turns": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of primary-measurement turns attributed to this branch."
+    },
+    "sessions": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of distinct sessions that touched this branch."
+    },
+    "subagentTurns": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Of turns, how many ran as a subagent."
+    },
+    "models": {
+      "type": "array",
+      "description": "Spend broken down by model family, most expensive first.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["model", "costUsd", "share"],
+        "properties": {
+          "model": { "type": "string" },
+          "costUsd": { "type": ["number", "null"], "minimum": 0 },
+          "share": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }
+        }
+      }
+    },
+    "coverage": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Share of this branch's turns that used a model with a configured price. Turns outside this coverage are counted but excluded from costUsd."
+    },
+    "largestPromptTokens": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "description": "The largest single prompt (input + cache read + cache write tokens) seen on this branch."
+    },
+    "changedLines": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "description": "Additions + deletions of the matched pull request, when one was supplied. null with no matched PR."
+    },
+    "pr": {
+      "description": "The pull request this receipt's headline window is scoped to (turns up to its merge), or null when none was supplied/matched.",
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["number", "mergedAt"],
+          "properties": {
+            "number": { "type": "integer", "minimum": 1 },
+            "mergedAt": { "type": ["string", "null"], "format": "date-time" }
+          }
+        }
+      ]
+    },
+    "longLived": {
+      "type": "boolean",
+      "description": "True for a long-lived branch name (main, staging, …): this receipt is for a period of work on it, not one change."
+    },
+    "costPer100Lines": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "description": "costUsd divided by changedLines, scaled to 100 lines. null with no matched PR, no changed lines, or no priced turns."
+    },
+    "notes": {
+      "type": "array",
+      "description": "Honesty caveats in plain sentences: e.g. unpriced turns excluded from costUsd, a long-lived branch covering a period, work that predates the matched PR, that costs are estimated locally and no prompt or code content was read.",
+      "items": { "type": "string" }
+    }
+  }
+}

package/scripts/build-menubar-app.sh

@@ -106,9 +106,11 @@ if [ "$PORTABLE" != "1" ]; then
 fi
 
 echo "compiling with $(swiftc --version | head -1)"
+# DesignTokens.swift is generated from design/tokens.yaml (`npm run design`);
+# the app is compiled from both files so it cannot drift from the dashboard.
 swiftc -O -swift-version 5 \
   -o "$APP/Contents/MacOS/TokenFlow" \
-  "$SRC" 2>&1 | head -40
+  "$SRC" "$REPO/menubar/TokenFlow/DesignTokens.swift" 2>&1 | head -40
 
 codesign --force --sign - "$APP" >/dev/null 2>&1 || true