copilot-usage-studio 0.1.0

package/lib/cli.mjs

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join, posix, resolve, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createLocalRuntime } from './local-runtime.mjs';
+import { scanVsCodeSessions, writeSessionData } from './scanner-api.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+
+export function defaultAppDataDir(environment = process.env, os = platform(), home = homedir()) {
+  if (os === 'win32') {
+    return win32.join(
+      environment.LOCALAPPDATA ?? win32.join(home, 'AppData', 'Local'),
+      'Copilot Usage Studio',
+    );
+  }
+  if (os === 'darwin') {
+    return posix.join(home, 'Library', 'Application Support', 'Copilot Usage Studio');
+  }
+  return posix.join(
+    environment.XDG_DATA_HOME ?? posix.join(home, '.local', 'share'),
+    'copilot-usage-studio',
+  );
+}
+
+export function parseCliArgs(args = process.argv.slice(2)) {
+  const command = args[0] && !args[0].startsWith('-') ? args[0] : 'serve';
+  const commandArgs = command === 'serve' && command !== args[0] ? args : args.slice(1);
+  const options = {
+    command,
+    host: process.env.COPILOT_USAGE_STUDIO_HOST ?? '127.0.0.1',
+    port: Number(process.env.COPILOT_USAGE_STUDIO_PORT ?? 4312),
+    output: '',
+    roots: [],
+    scanOnStart: true,
+  };
+
+  if (command === 'help' || command === 'version') {
+    return options;
+  }
+  if (!['serve', 'scan', 'status'].includes(command)) {
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  for (let index = 0; index < commandArgs.length; index += 1) {
+    const argument = commandArgs[index];
+    if (argument === '--help' || argument === '-h') {
+      options.command = 'help';
+      continue;
+    }
+    if (argument === '--version' || argument === '-v') {
+      options.command = 'version';
+      continue;
+    }
+    if (argument === '--no-startup-scan') {
+      options.scanOnStart = false;
+      continue;
+    }
+
+    const [flag, inlineValue] = argument.split('=', 2);
+    const value = inlineValue ?? commandArgs[index + 1];
+    if (['--host', '--port', '--output', '--root'].includes(flag) && !value) {
+      throw new Error(`${flag} requires a value.`);
+    }
+    if (['--host', '--port', '--output', '--root'].includes(flag) && inlineValue === undefined) {
+      index += 1;
+    }
+
+    if (flag === '--host') options.host = value;
+    else if (flag === '--port') options.port = Number(value);
+    else if (flag === '--output') options.output = value;
+    else if (flag === '--root') options.roots.push(value);
+    else if (!['--no-startup-scan', '--help', '-h', '--version', '-v'].includes(flag)) {
+      throw new Error(`Unknown option: ${argument}`);
+    }
+  }
+
+  if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65_535) {
+    throw new Error('--port must be an integer between 0 and 65535.');
+  }
+  return options;
+}
+
+export async function runCli(args = process.argv.slice(2), dependencies = {}) {
+  const options = parseCliArgs(args);
+  const logger = dependencies.logger ?? console;
+  const appDataDir = dependencies.appDataDir ?? defaultAppDataDir();
+
+  if (options.command === 'help') {
+    logger.log(helpText());
+    return null;
+  }
+  if (options.command === 'version') {
+    logger.log(packageJson.version);
+    return null;
+  }
+  if (options.command === 'status') {
+    const fetchStatus = dependencies.fetch ?? globalThis.fetch;
+    const response = await fetchStatus(`http://${options.host}:${options.port}/api/status`);
+    if (!response.ok) {
+      throw new Error(`Local runtime returned ${response.status}.`);
+    }
+    const status = await response.json();
+    logger.log(JSON.stringify(status, null, 2));
+    return status;
+  }
+
+  const scanOptions = options.roots.length ? { roots: options.roots } : {};
+  if (options.command === 'scan') {
+    const scanner = dependencies.scanner ?? scanVsCodeSessions;
+    const writer = dependencies.writer ?? writeSessionData;
+    const sessionData = await scanner(scanOptions);
+    const outputFile = resolve(options.output || join(appDataDir, 'sessions.json'));
+    writer(sessionData, outputFile);
+    logger.log(`Imported ${sessionData.sessions.length} sessions to ${outputFile}`);
+    return sessionData;
+  }
+
+  const staticDir = dependencies.staticDir ?? join(packageRoot, 'dist', 'copilot-usage-studio', 'browser');
+  const hasStaticAssets = dependencies.hasStaticAssets ?? existsSync;
+  if (!hasStaticAssets(join(staticDir, 'index.html'))) {
+    throw new Error('Packaged UI assets are missing. Run npm run build before serving from this checkout.');
+  }
+
+  const runtimeFactory = dependencies.runtimeFactory ?? createLocalRuntime;
+  const runtime = runtimeFactory({
+    host: options.host,
+    port: options.port,
+    dataFile: join(appDataDir, 'sessions.json'),
+    seedDataFile: null,
+    staticDir,
+    scanOnStart: options.scanOnStart,
+    scanOptions,
+    logger,
+  });
+  await runtime.listen();
+  installShutdownHandlers(runtime, dependencies.processObject ?? process);
+  return runtime;
+}
+
+export function helpText() {
+  return `Copilot Usage Studio ${packageJson.version}
+
+Usage:
+  copilot-usage-studio [serve] [options]
+  copilot-usage-studio scan [options]
+  copilot-usage-studio status [options]
+
+Commands:
+  serve    Scan local VS Code data and serve the local UI (default)
+  scan     Scan and write the normalized session-data JSON
+  status   Read status from a running local runtime
+
+Options:
+  --host <host>       Bind host (default: 127.0.0.1)
+  --port <port>       Runtime port (default: 4312)
+  --root <path>       Custom VS Code User or workspace-storage path; repeatable
+  --output <file>     Output file for the scan command
+  --no-startup-scan   Serve the last local cache without scanning on startup
+  -h, --help          Show help
+  -v, --version       Show version`;
+}
+
+function installShutdownHandlers(runtime, processObject) {
+  const close = async () => {
+    await runtime.close();
+    processObject.exit(0);
+  };
+  processObject.once('SIGINT', close);
+  processObject.once('SIGTERM', close);
+}

package/lib/local-runtime.mjs

@@ -0,0 +1,231 @@
+import { createReadStream, existsSync, readFileSync, statSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+
+import { scanVsCodeSessions, writeSessionData } from './scanner-api.mjs';
+
+const contentTypes = new Map([
+  ['.css', 'text/css; charset=utf-8'],
+  ['.html', 'text/html; charset=utf-8'],
+  ['.ico', 'image/x-icon'],
+  ['.js', 'text/javascript; charset=utf-8'],
+  ['.json', 'application/json; charset=utf-8'],
+  ['.map', 'application/json; charset=utf-8'],
+  ['.png', 'image/png'],
+  ['.svg', 'image/svg+xml'],
+  ['.webp', 'image/webp'],
+  ['.woff', 'font/woff'],
+  ['.woff2', 'font/woff2'],
+]);
+
+export function createLocalRuntime(options = {}) {
+  const host = options.host ?? '127.0.0.1';
+  const port = Number(options.port ?? 4312);
+  const dataFile = resolve(options.dataFile ?? 'tmp/local-runtime/sessions.json');
+  const seedDataFile = options.seedDataFile === null
+    ? null
+    : resolve(options.seedDataFile ?? 'public/data/sessions.json');
+  const staticDir = resolve(options.staticDir ?? 'dist/copilot-usage-studio/browser');
+  const scanOptions = options.scanOptions ?? {};
+  const scanner = options.scanner ?? scanVsCodeSessions;
+  const writer = options.writer ?? writeSessionData;
+  const logger = options.logger ?? console;
+
+  let sessionData = readCachedSessionData(dataFile, logger)
+    ?? (seedDataFile ? readCachedSessionData(seedDataFile, logger) : null);
+  let phase = sessionData ? 'ready' : 'empty';
+  let lastError = '';
+  let lastScanStartedAt = '';
+  let lastScanCompletedAt = '';
+  let lastScanDurationMs = 0;
+  let activeScan = null;
+
+  function status() {
+    return {
+      phase,
+      scanning: Boolean(activeScan),
+      hasData: Boolean(sessionData),
+      sessionCount: sessionData?.sessions?.length ?? 0,
+      generatedAt: sessionData?.generatedAt ?? '',
+      lastScanStartedAt,
+      lastScanCompletedAt,
+      lastScanDurationMs,
+      lastError,
+    };
+  }
+
+  function refresh(reason = 'manual') {
+    if (activeScan) {
+      return activeScan;
+    }
+
+    const started = Date.now();
+    lastScanStartedAt = new Date(started).toISOString();
+    lastError = '';
+    phase = 'scanning';
+
+    activeScan = Promise.resolve()
+      .then(() => scanner(scanOptions))
+      .then((nextSessionData) => {
+        writer(nextSessionData, dataFile);
+        sessionData = nextSessionData;
+        phase = 'ready';
+        lastScanCompletedAt = new Date().toISOString();
+        lastScanDurationMs = Date.now() - started;
+        logger.log(
+          `Local data refresh (${reason}) imported ${nextSessionData.sessions.length} sessions in ${lastScanDurationMs}ms.`,
+        );
+        return nextSessionData;
+      })
+      .catch((error) => {
+        lastError = error instanceof Error ? error.message : String(error);
+        phase = sessionData ? 'ready' : 'error';
+        lastScanCompletedAt = new Date().toISOString();
+        lastScanDurationMs = Date.now() - started;
+        logger.error(`Local data refresh failed: ${lastError}`);
+        throw error;
+      })
+      .finally(() => {
+        activeScan = null;
+      });
+
+    return activeScan;
+  }
+
+  const server = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url ?? '/', `http://${request.headers.host ?? `${host}:${port}`}`);
+
+      if (request.method === 'GET' && url.pathname === '/api/status') {
+        return sendJson(response, 200, status());
+      }
+
+      if (request.method === 'GET' && url.pathname === '/api/sessions') {
+        await waitForFirstData();
+        return sessionData
+          ? sendJson(response, 200, sessionData)
+          : sendJson(response, 503, { error: 'No session data is available yet.', status: status() });
+      }
+
+      if (request.method === 'GET' && url.pathname === '/data/sessions.json') {
+        await waitForFirstData();
+        return sessionData
+          ? sendJson(response, 200, sessionData)
+          : sendJson(response, 503, { error: 'No session data is available yet.', status: status() });
+      }
+
+      if (request.method === 'POST' && url.pathname === '/api/scan') {
+        try {
+          const nextSessionData = await refresh('manual');
+          return sendJson(response, 200, { sessionData: nextSessionData, status: status() });
+        } catch {
+          return sendJson(response, 500, { error: lastError, status: status() });
+        }
+      }
+
+      if (request.method !== 'GET' && request.method !== 'HEAD') {
+        return sendJson(response, 405, { error: 'Method not allowed.' });
+      }
+
+      return serveStaticFile(request, response, staticDir, url.pathname);
+    } catch (error) {
+      logger.error(error);
+      return sendJson(response, 500, { error: 'Local runtime request failed.' });
+    }
+  });
+
+  return {
+    address: () => server.address(),
+    close: () => new Promise((resolveClose, rejectClose) => {
+      server.close((error) => (error ? rejectClose(error) : resolveClose()));
+    }),
+    listen: () => new Promise((resolveListen, rejectListen) => {
+      server.once('error', rejectListen);
+      server.listen(port, host, () => {
+        server.off('error', rejectListen);
+        const address = server.address();
+        logger.log(`Copilot Usage Studio local runtime: http://${host}:${address.port}/`);
+        resolveListen(address);
+
+        if (options.scanOnStart !== false) {
+          void refresh('startup').catch(() => {});
+        }
+      });
+    }),
+    refresh,
+    status,
+  };
+
+  async function waitForFirstData() {
+    if (!sessionData && activeScan) {
+      try {
+        await activeScan;
+      } catch {
+        // The response below reports the retained empty/error state.
+      }
+    }
+  }
+}
+
+function readCachedSessionData(dataFile, logger) {
+  if (!existsSync(dataFile)) {
+    return null;
+  }
+
+  try {
+    const value = JSON.parse(readFileSync(dataFile, 'utf8'));
+    return value && Array.isArray(value.sessions) ? value : null;
+  } catch (error) {
+    logger.warn(`Ignoring unreadable cached session data at ${dataFile}: ${error.message}`);
+    return null;
+  }
+}
+
+function sendJson(response, statusCode, body) {
+  const payload = JSON.stringify(body);
+  response.writeHead(statusCode, {
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(payload),
+    'content-type': 'application/json; charset=utf-8',
+  });
+  response.end(payload);
+}
+
+function serveStaticFile(request, response, staticDir, pathname) {
+  if (!existsSync(staticDir)) {
+    return sendJson(response, 404, {
+      error: 'The production UI has not been built. Run npm run build first.',
+    });
+  }
+
+  const decodedPath = decodeURIComponent(pathname);
+  const relativePath = decodedPath === '/' ? 'index.html' : decodedPath.replace(/^\/+/, '');
+  let file = safeStaticPath(staticDir, relativePath);
+
+  if (!file || !existsSync(file) || !statSync(file).isFile()) {
+    file = safeStaticPath(staticDir, 'index.html');
+  }
+
+  if (!file || !existsSync(file)) {
+    return sendJson(response, 404, { error: 'UI file not found.' });
+  }
+
+  const headers = {
+    'content-type': contentTypes.get(extname(file).toLowerCase()) ?? 'application/octet-stream',
+  };
+  if (file.endsWith('index.html')) {
+    headers['cache-control'] = 'no-store';
+  }
+  response.writeHead(200, headers);
+  if (request.method === 'HEAD') {
+    response.end();
+    return;
+  }
+  createReadStream(file).pipe(response);
+}
+
+function safeStaticPath(staticDir, relativePath) {
+  const root = `${resolve(staticDir)}${sep}`;
+  const candidate = resolve(join(staticDir, normalize(relativePath)));
+  return candidate.startsWith(root) ? candidate : null;
+}

package/lib/scanner-api.mjs

@@ -0,0 +1,12 @@
+/**
+ * Stable Node-side scanner boundary for local hosts.
+ *
+ * Hosts should consume this module instead of importing parser internals from
+ * scripts/scan-vscode-sessions.mjs. The returned object is the same normalized
+ * SessionData document consumed by the Angular application.
+ */
+export {
+  defaultCodeUserDirs,
+  scanVsCodeSessions,
+  writeSessionData,
+} from '../scripts/scan-vscode-sessions.mjs';

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "copilot-usage-studio",
+  "version": "0.1.0",
+  "description": "Local VS Code GitHub Copilot usage, cost, and session insights.",
+  "type": "module",
+  "bin": {
+    "copilot-usage-studio": "bin/copilot-usage-studio.mjs"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "bin/",
+    "data/github-copilot-pricing.json",
+    "dist/copilot-usage-studio/browser/",
+    "docs/local-deployment.md",
+    "docs/pricing.md",
+    "docs/scanner-api.md",
+    "lib/",
+    "scripts/pricing-utils.mjs",
+    "scripts/scan-vscode-sessions.mjs"
+  ],
+  "scripts": {
+    "ng": "ng",
+    "start": "node scripts/start-local-dev.mjs",
+    "start:angular": "ng serve --proxy-config proxy.conf.json",
+    "start:clean": "npm run clean:ng-cache && node scripts/start-local-dev.mjs",
+    "runtime": "node scripts/local-runtime.mjs",
+    "preview:local": "npm run build && node scripts/local-runtime.mjs",
+    "cli": "node bin/copilot-usage-studio.mjs",
+    "prebuild": "node scripts/clean-dist.mjs",
+    "build": "ng build",
+    "watch": "ng build --watch --configuration development",
+    "test": "ng test",
+    "test:scripts": "node --test scripts/*.test.mjs",
+    "clean:ng-cache": "ng cache clean",
+    "refresh:data": "npm run scan && npm run verify:data",
+    "scan": "node scripts/scan-vscode-sessions.mjs",
+    "verify:data": "node scripts/verify-session-data.mjs",
+    "schema:audit": "node scripts/audit-vscode-schema.mjs",
+    "schema:accept": "node scripts/audit-vscode-schema.mjs --accept",
+    "verify:package": "node scripts/verify-package.mjs",
+    "release:check": "npm run test:scripts && npm test -- --watch=false && npm run build && npm run verify:package",
+    "prepack": "npm run build"
+  },
+  "exports": {
+    ".": "./lib/cli.mjs",
+    "./scanner": "./lib/scanner-api.mjs",
+    "./local-runtime": "./lib/local-runtime.mjs"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fortunes-guardian/copilot-usage-studio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fortunes-guardian/copilot-usage-studio/issues"
+  },
+  "homepage": "https://github.com/fortunes-guardian/copilot-usage-studio#readme",
+  "keywords": [
+    "github-copilot",
+    "vscode",
+    "ai-usage",
+    "token-cost",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "packageManager": "npm@11.11.0",
+  "devDependencies": {
+    "@angular/build": "^21.2.9",
+    "@angular/cli": "^21.2.9",
+    "@angular/common": "^21.2.0",
+    "@angular/compiler": "^21.2.0",
+    "@angular/compiler-cli": "^21.2.0",
+    "@angular/core": "^21.2.0",
+    "@angular/forms": "^21.2.0",
+    "@angular/platform-browser": "^21.2.0",
+    "@angular/router": "^21.2.0",
+    "jsdom": "^28.0.0",
+    "prettier": "^3.8.1",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0",
+    "typescript": "~5.9.2",
+    "vitest": "^4.0.8"
+  }
+}

package/scripts/pricing-utils.mjs

@@ -0,0 +1,71 @@
+export function modelKey(model) {
+  return String(model ?? '')
+    .replace(/^copilot\//i, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+}
+
+export function normalizeModel(model, pricing) {
+  const raw = String(model ?? '')
+    .replace(/^copilot\//i, '')
+    .trim();
+  const key = modelKey(raw);
+  const knownModels = Object.keys(pricing);
+
+  return (
+    knownModels.find((name) => modelKey(name) === key) ??
+    knownModels.find((name) => key.includes(modelKey(name))) ??
+    (raw || 'Unknown model')
+  );
+}
+
+export function pricingModelForModel(model, pricing, fallbackPricingModel) {
+  const normalized = normalizeModel(model, pricing);
+
+  return pricing[normalized] ? normalized : fallbackPricingModel;
+}
+
+export function priceForPricingModel(pricingModel, pricing, fallbackPricingModel) {
+  return pricing[pricingModel || ''] ?? pricing[fallbackPricingModel];
+}
+
+export function priceForTokens(pricingModel, tokens, pricing, fallbackPricingModel) {
+  const basePrice = priceForPricingModel(pricingModel, pricing, fallbackPricingModel);
+  const rawInputTokens =
+    Math.max(0, Number(tokens?.input ?? 0)) + Math.max(0, Number(tokens?.cachedInput ?? 0));
+  const tier = [...(basePrice.tiers ?? [])]
+    .sort((a, b) => b.thresholdInputTokensExclusive - a.thresholdInputTokensExclusive)
+    .find((candidate) => rawInputTokens > candidate.thresholdInputTokensExclusive);
+
+  return tier ? { ...basePrice, ...tier, tiers: basePrice.tiers } : basePrice;
+}
+
+export function costBreakdownUsdForTokens(pricingModel, tokens, pricing, fallbackPricingModel) {
+  const price = priceForTokens(pricingModel, tokens, pricing, fallbackPricingModel);
+  const input = (tokens.input / 1_000_000) * price.input;
+  const cachedInput = (tokens.cachedInput / 1_000_000) * price.cachedInput;
+  const cacheWrite = (tokens.cacheWrite / 1_000_000) * (price.cacheWrite ?? 0);
+  const output = (tokens.output / 1_000_000) * price.output;
+
+  return {
+    input,
+    cachedInput,
+    cacheWrite,
+    output,
+    total: input + cachedInput + cacheWrite + output,
+    tier: price.label ?? price.tierLabel ?? 'Default',
+  };
+}
+
+export function modelUsesPricingFallback(model, pricingModel, pricing, fallbackPricingModel) {
+  const normalized = normalizeModel(model, pricing);
+  const priceRow = pricingModel || pricingModelForModel(normalized, pricing, fallbackPricingModel);
+
+  return priceRow !== normalized || !pricing[normalized];
+}
+
+export function costUsdForTokens(pricingModel, tokens, pricing, fallbackPricingModel) {
+  return costBreakdownUsdForTokens(pricingModel, tokens, pricing, fallbackPricingModel).total;
+}