@vimoxshah/tokenflow 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vimoxshah/tokenflow",
-  "version": "1.1.1",
+  "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-dmg.sh

@@ -15,8 +15,17 @@ DIST="$REPO/dist"
 APP="$DIST/TokenFlow.app"
 DMG="$DIST/TokenFlow-$VERSION.dmg"
 
-"$REPO/scripts/build-menubar-app.sh" "$DIST" "$VERSION" >/dev/null
-echo "built TokenFlow.app"
+# A DMG is for other people's machines, so it must carry no path from this one.
+TOKENFLOW_PORTABLE=1 "$REPO/scripts/build-menubar-app.sh" "$DIST" "$VERSION" >/dev/null
+echo "built TokenFlow.app (portable)"
+
+# Fail here rather than shipping an app that points at the build host.
+for KEY in TokenFlowCLIPath TokenFlowNodePath; do
+  if /usr/libexec/PlistBuddy -c "Print :$KEY" "$APP/Contents/Info.plist" >/dev/null 2>&1; then
+    echo "error: $KEY is embedded in a distributable build" >&2
+    exit 1
+  fi
+done
 
 STAGING="$(mktemp -d)"
 trap 'rm -rf "$STAGING"' EXIT

package/scripts/build-menubar-app.sh

@@ -4,8 +4,24 @@
 #   scripts/build-menubar-app.sh [output-dir]
 #
 # Compiles menubar/TokenFlow/main.swift with swiftc (Xcode Command Line Tools)
-# into a minimal .app bundle, embedding the absolute paths of this clone's
-# node binary and CLI so the app can drive refresh/watch actions.
+# into a minimal .app bundle.
+#
+# The CLI is ALWAYS bundled into Contents/Resources/cli, packed with `npm pack`
+# so the copy inside the app is byte-for-byte the published package rather than
+# a hand-picked subset of the working tree. The app drives that copy, which is
+# the only one guaranteed to match the binary it ships beside: the app and the
+# CLI share a contract (the status file, the watcher lock format, /api/ping),
+# and an unrelated CLI version next door is a mismatch nobody can reason about.
+#
+# Two build flavours:
+#
+#   local (default)      also embeds this clone's absolute node + CLI paths, so
+#                        a developer's installed app drives the checkout they
+#                        are editing.
+#   TOKENFLOW_PORTABLE=1 embeds NO absolute paths. Anything built for
+#                        distribution must use this: a release built on CI
+#                        otherwise ships /Users/runner/... in its Info.plist,
+#                        which exists on no user's machine.
 set -euo pipefail
 
 REPO="$(cd "$(dirname "$0")/.." && pwd)"
@@ -25,14 +41,40 @@ command -v swiftc >/dev/null 2>&1 || {
 NODE_BIN="$(command -v node)"
 CLI_JS="$REPO/bin/tokenflow.js"
 [ -f "$CLI_JS" ] || { echo "error: $CLI_JS missing" >&2; exit 1; }
+PORTABLE="${TOKENFLOW_PORTABLE:-0}"
 
 TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT
 
+rm -rf "$APP"
 mkdir -p "$APP/Contents/MacOS"
 mkdir -p "$APP/Contents/Resources"
 cp "$REPO/menubar/TokenFlow/AppIcon.icns" "$APP/Contents/Resources/AppIcon.icns"
 
+# ---- bundle the CLI ---------------------------------------------------------
+# `npm pack` rather than copying bin/ and src/: the tarball is what npm
+# publishes, filtered by package.json "files", so the app can never ship a file
+# the package does not.
+echo "packing the CLI into the bundle"
+( cd "$REPO" && npm pack --silent --pack-destination "$TMP" >/dev/null )
+TGZ="$(ls "$TMP"/*.tgz | head -1)"
+[ -f "$TGZ" ] || { echo "error: npm pack produced no tarball" >&2; exit 1; }
+mkdir -p "$APP/Contents/Resources/cli"
+tar -xzf "$TGZ" -C "$APP/Contents/Resources/cli"
+BUNDLED_CLI="$APP/Contents/Resources/cli/package/bin/tokenflow.js"
+[ -f "$BUNDLED_CLI" ] || { echo "error: bundled CLI missing at $BUNDLED_CLI" >&2; exit 1; }
+
+# Keep only what the CLI actually executes. docs/, skills/, examples/ and
+# scripts/ are never read at runtime — they appear in printed hints and nothing
+# opens them — and they are four fifths of the tarball. Whatever remains still
+# came from `npm pack`, so the bundle is a subset of the published package and
+# never a file npm does not ship.
+( cd "$APP/Contents/Resources/cli/package" \
+  && rm -rf docs skills examples scripts \
+     README.md CONTRIBUTING.md SECURITY.md CHANGELOG.md "Refresh & Open Dashboard.command" )
+[ -f "$BUNDLED_CLI" ] || { echo "error: pruning removed the CLI" >&2; exit 1; }
+[ -d "$APP/Contents/Resources/cli/package/src" ] || { echo "error: pruning removed src/" >&2; exit 1; }
+
 cat > "$APP/Contents/Info.plist" <<PLIST
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -50,18 +92,27 @@ cat > "$APP/Contents/Info.plist" <<PLIST
     <key>LSUIElement</key>                  <true/>
     <key>NSHighResolutionCapable</key>      <true/>
     <key>NSHumanReadableCopyright</key>     <string>MIT — local-first, nothing leaves your machine.</string>
-    <key>TokenFlowNodePath</key>            <string>$NODE_BIN</string>
-    <key>TokenFlowCLIPath</key>             <string>$CLI_JS</string>
 </dict>
 </plist>
 PLIST
 
+# A distributable build embeds no machine-specific path. A local one does, so
+# the developer's installed app drives the clone they are working in.
+if [ "$PORTABLE" != "1" ]; then
+  /usr/libexec/PlistBuddy \
+    -c "Add :TokenFlowNodePath string $NODE_BIN" \
+    -c "Add :TokenFlowCLIPath string $CLI_JS" \
+    "$APP/Contents/Info.plist" >/dev/null
+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
 
-SIZE=$(du -h "$APP" | cut -f1 | tr -d ' ')
-echo "built: $APP ($SIZE)"
+SIZE=$(du -sh "$APP" | cut -f1 | tr -d ' ')
+echo "built: $APP ($SIZE)$([ "$PORTABLE" = "1" ] && echo ' · portable, no embedded paths')"