shipper-town 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# shipper-town
 
-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.
+Join the [Shipper Town](https://shipper.town) leaderboard: a live board of people building with Claude Code.
+
+```bash
+npx shipper-town join     # sign in with GitHub and connect this machine
+npx shipper-town status   # show your connection and rank
+npx shipper-town leave    # disconnect this machine
+```
+
+## What `join` does
+
+It turns on Claude Code's built-in usage metrics (OpenTelemetry) and points them at Shipper Town, by adding
+these 7 entries to the `env` block of `~/.claude/settings.json`. It shows the exact changes and asks before writing,
+and it keeps a backup of the previous file.
+
+```
+CLAUDE_CODE_ENABLE_TELEMETRY=1
+OTEL_METRICS_EXPORTER=otlp
+OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://ingest.shipper.town/v1/metrics
+OTEL_EXPORTER_OTLP_METRICS_HEADERS=Authorization=Bearer <this machine's key>
+OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
+OTEL_METRIC_EXPORT_INTERVAL=600000
+```
+
+Restart Claude Code afterwards. Reports are sent every 10 minutes and when a session ends.
+
+## What is counted
+
+Only totals: active time, token counts, sessions, lines changed, commits and pull requests. No prompts, code,
+file names, email, model names or session IDs are stored. See [shipper.town/privacy](https://shipper.town/privacy).
+
+## Leaving
+
+`npx shipper-town leave` removes exactly the entries above (anything you customised stays) and revokes this
+machine's key. You can also revoke keys or delete your account at [shipper.town/settings](https://shipper.town/settings).
+
+If Claude Code already sends metrics to another tool, `join` stops and tells you, since Claude Code supports
+one metrics destination. `--force` replaces it.
+
+Independent fan project, not affiliated with Anthropic. MIT licensed.

package/dist/api.js

@@ -0,0 +1,72 @@
+export const CLIENT_ID = 'shipper-cli';
+const json = { 'content-type': 'application/json' };
+export function createApi(baseUrl, ingestUrl, fetchImpl = fetch, now = Date.now) {
+    const url = (p) => `${baseUrl}${p}`;
+    return {
+        async requestDeviceCode() {
+            const res = await fetchImpl(url('/api/auth/device/code'), { method: 'POST', headers: json, body: JSON.stringify({ client_id: CLIENT_ID }) });
+            if (!res.ok)
+                throw new Error(`Could not start sign-in (${res.status})`);
+            return (await res.json());
+        },
+        async pollToken(dc, sleep) {
+            let interval = dc.interval;
+            const deadline = now() + dc.expires_in * 1000;
+            while (now() < deadline) {
+                await sleep(interval * 1000);
+                const res = await fetchImpl(url('/api/auth/device/token'), {
+                    method: 'POST', headers: json,
+                    body: JSON.stringify({ grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: dc.device_code, client_id: CLIENT_ID }),
+                });
+                const body = (await res.json().catch(() => ({})));
+                if (res.ok && body.access_token)
+                    return body.access_token;
+                if (body.error === 'authorization_pending')
+                    continue;
+                if (body.error === 'slow_down') {
+                    interval += 5;
+                    continue;
+                }
+                if (body.error === 'access_denied')
+                    throw new Error('Sign-in was denied in the browser.');
+                if (body.error === 'expired_token')
+                    break;
+                throw new Error(`Sign-in failed (${body.error ?? res.status})`);
+            }
+            throw new Error('The code expired. Run the command again.');
+        },
+        async createKey(sessionToken, label) {
+            const res = await fetchImpl(url('/api/cli/keys'), {
+                method: 'POST', headers: { ...json, authorization: `Bearer ${sessionToken}` }, body: JSON.stringify({ label }),
+            });
+            if (res.status !== 201)
+                throw new Error(`Could not create a key (${res.status})`);
+            return (await res.json());
+        },
+        async signOut(sessionToken) {
+            try {
+                const res = await fetchImpl(url('/api/auth/sign-out'), {
+                    method: 'POST', headers: { ...json, authorization: `Bearer ${sessionToken}` }, body: '{}',
+                });
+                return res.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+        async revokeKey(key) {
+            const res = await fetchImpl(url('/api/cli/keys/revoke'), { method: 'POST', headers: { authorization: `Bearer ${key}` } });
+            return res.ok;
+        },
+        async status(key) {
+            const res = await fetchImpl(url('/api/cli/status'), { headers: { authorization: `Bearer ${key}` } });
+            return res.ok ? (await res.json()) : null;
+        },
+        async testExport(key) {
+            const res = await fetchImpl(`${ingestUrl}/v1/metrics`, {
+                method: 'POST', headers: { ...json, authorization: `Bearer ${key}` }, body: JSON.stringify({ resourceMetrics: [] }),
+            });
+            return res.ok;
+        },
+    };
+}

package/dist/browser.js

@@ -0,0 +1,13 @@
+/** Only https URLs (or http on localhost) are ever handed to the OS opener. */
+export function isSafeBrowserUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol === 'https:')
+        return true;
+    return u.protocol === 'http:' && (u.hostname === 'localhost' || u.hostname === '127.0.0.1');
+}

package/dist/commands.js

@@ -0,0 +1,154 @@
+import { existingShipperKey, maskKey, mergeSettings, removeShipperEnv, findConflicts } from './settings.js';
+import { InvalidSettingsError, readSettings, writeSettings } from './settings-file.js';
+export function prettyHostname(h) {
+    const s = h.replace(/\.local$/i, '').replace(/[-_]+/g, ' ').trim();
+    return s || 'My machine';
+}
+const formatCode = (c) => (c.length === 8 ? `${c.slice(0, 4)}-${c.slice(4)}` : c);
+async function load(io) {
+    try {
+        return await readSettings(io.settingsPath);
+    }
+    catch (e) {
+        io.log(e instanceof InvalidSettingsError ? e.message : `Could not read ${io.settingsPath}: ${e.message}`);
+        return null;
+    }
+}
+export async function join(api, io, ingestUrl, opts) {
+    const current = await load(io);
+    if (!current)
+        return 1;
+    const conflicts = findConflicts(current, ingestUrl);
+    if (conflicts.length && !opts.force) {
+        const r = mergeSettings(current, 'ship_x', ingestUrl, opts);
+        if (!r.ok)
+            io.log(r.reason);
+        return 1;
+    }
+    if (io.fileExists(io.managedPath)) {
+        io.log(`Note: your organization has managed settings at ${io.managedPath}. They may override these settings.`);
+    }
+    const dc = await api.requestDeviceCode();
+    io.log(`\nOpen ${dc.verification_uri} and enter: ${formatCode(dc.user_code)}\n`);
+    io.openBrowser(dc.verification_uri_complete);
+    io.log('Waiting for you to approve in the browser…');
+    let token;
+    try {
+        token = await api.pollToken(dc, io.sleep);
+    }
+    catch (e) {
+        io.log(e.message);
+        return 1;
+    }
+    let created;
+    try {
+        created = await api.createKey(token, prettyHostname(io.hostname));
+    }
+    catch (e) {
+        io.log(`Could not create a key: ${e.message}`);
+        return 1;
+    }
+    // The device-flow session has done its job; best-effort sign it out so no long-lived session lingers.
+    await api.signOut(token).catch(() => false);
+    const { key, handle } = created;
+    const revokeFresh = async () => {
+        try {
+            if (!(await api.revokeKey(key)))
+                io.log('Note: the new key could not be revoked on the server. Revoke it at https://shipper.town/settings.');
+        }
+        catch {
+            io.log('Note: the new key could not be revoked on the server. Revoke it at https://shipper.town/settings.');
+        }
+    };
+    let oldKey;
+    try {
+        const merged = mergeSettings(current, key, ingestUrl, opts);
+        if (!merged.ok) {
+            io.log(merged.reason);
+            await revokeFresh();
+            return 1;
+        }
+        oldKey = merged.oldKey;
+        io.log(`\nThis will update ${io.settingsPath}:`);
+        for (const c of merged.changes)
+            io.log(c.from ? `  ~ ${c.key}: ${c.from} → ${c.to}` : `  + ${c.key}=${c.to}`);
+        if (!opts.yes && !(await io.confirm('Apply these changes?'))) {
+            await revokeFresh();
+            io.log('Cancelled. Nothing was changed.');
+            return 1;
+        }
+        const backup = await writeSettings(io.settingsPath, merged.next, io.now());
+        if (backup)
+            io.log(`Backup saved to ${backup}`);
+    }
+    catch (e) {
+        io.log(`Could not update settings: ${e.message}. Nothing was changed.`);
+        await revokeFresh();
+        return 1;
+    }
+    if (oldKey && oldKey !== key) {
+        try {
+            if (!(await api.revokeKey(oldKey)))
+                io.log('Note: your previous key could not be revoked on the server. Revoke it at https://shipper.town/settings.');
+        }
+        catch {
+            io.log('Note: your previous key could not be revoked on the server. Revoke it at https://shipper.town/settings.');
+        }
+    }
+    let pinged = false;
+    try {
+        pinged = await api.testExport(key);
+    }
+    catch { }
+    if (!pinged) {
+        io.log("Settings written and this machine's key is active, but the test report failed. Check your connection and run `npx shipper-town status`.");
+        return 1;
+    }
+    io.log(`\nConnected as @${handle}. Restart open Claude Code sessions to start counting.`);
+    return 0;
+}
+export async function status(api, io, ingestUrl) {
+    const current = await load(io);
+    if (!current)
+        return 1;
+    const key = existingShipperKey(current);
+    if (!key) {
+        io.log('This machine is not connected. Run `npx shipper-town join`.');
+        return 1;
+    }
+    const s = await api.status(key);
+    if (!s) {
+        io.log(`Key ${maskKey(key)} is no longer valid. Run \`npx shipper-town join\` again.`);
+        return 1;
+    }
+    const merged = mergeSettings(current, key, ingestUrl, { force: false });
+    const settingsOk = merged.ok && merged.changes.length === 0;
+    io.log(`Connected as @${s.handle} (${s.label})`);
+    io.log(`Last active: ${s.lastSeenAt ? new Date(s.lastSeenAt * 1000).toLocaleString() : 'not yet'}`);
+    io.log(`Rank this week: ${s.weekRank ? `#${s.weekRank}` : 'not ranked yet'}`);
+    io.log(settingsOk ? 'Settings look correct.' : 'Settings differ from expected. Run `npx shipper-town join` to repair.');
+    return 0;
+}
+export async function leave(api, io, ingestUrl) {
+    const current = await load(io);
+    if (!current)
+        return 1;
+    const { next, removed, oldKey } = removeShipperEnv(current, ingestUrl);
+    if (removed.length === 0) {
+        io.log('Nothing to remove. This machine was not connected.');
+        return 0;
+    }
+    let revoked = false;
+    if (oldKey) {
+        try {
+            revoked = await api.revokeKey(oldKey);
+        }
+        catch { }
+    }
+    const backup = await writeSettings(io.settingsPath, next, io.now());
+    const done = `Removed ${removed.length} settings${backup ? ` (backup: ${backup})` : ''}.`;
+    io.log(!oldKey || revoked
+        ? `${done} This machine is disconnected.`
+        : `${done} Settings removed, but the key could not be revoked on the server. Revoke it at https://shipper.town/settings`);
+    return 0;
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+const HINTS = {
+    ENOTFOUND: 'the address could not be found (check your connection or DNS)',
+    ECONNREFUSED: 'the connection was refused',
+    ETIMEDOUT: 'the connection timed out',
+    ECONNRESET: 'the connection was reset',
+};
+/** Turns Node's bare "fetch failed" into something a person can act on. */
+export function describeError(e, base) {
+    if (!(e instanceof Error))
+        return String(e);
+    if (e.message !== 'fetch failed')
+        return e.message;
+    const code = e.cause?.code;
+    const why = (code && HINTS[code]) ?? (code ? code : 'a network error');
+    return `Could not reach ${base}: ${why}.`;
+}

package/dist/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir, hostname, platform } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { createApi } from './api.js';
+import { join, leave, status } from './commands.js';
+import { isSafeBrowserUrl } from './browser.js';
+import { managedSettingsPath, settingsPath } from './settings-file.js';
+import { describeError } from './errors.js';
+const BASE = (process.env.SHIPPER_TOWN_URL ?? 'https://shipper.town').replace(/\/$/, '');
+const INGEST = (process.env.SHIPPER_TOWN_INGEST_URL ?? 'https://ingest.shipper.town').replace(/\/$/, '');
+function openBrowser(url) {
+    if (!isSafeBrowserUrl(url))
+        return;
+    const win = platform() === 'win32';
+    const cmd = platform() === 'darwin' ? 'open' : win ? 'rundll32' : 'xdg-open';
+    const args = win ? ['url.dll,FileProtocolHandler', url] : [url];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
+    }
+    catch { }
+}
+const argv = new Set(process.argv.slice(3));
+const assumeYes = argv.has('--yes') || argv.has('-y');
+const io = {
+    log: (m) => console.log(m),
+    async confirm(q) {
+        if (!process.stdin.isTTY && !assumeYes)
+            return false;
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const closed = new Promise((r) => rl.once('close', () => r('')));
+        const a = await Promise.race([rl.question(`${q} [y/N] `), closed]);
+        rl.close();
+        return /^y(es)?$/i.test(a.trim());
+    },
+    openBrowser,
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Math.floor(Date.now() / 1000),
+    settingsPath: settingsPath(process.env, homedir()),
+    managedPath: managedSettingsPath(platform()),
+    hostname: hostname(),
+    fileExists: existsSync,
+};
+const [cmd, ...rest] = process.argv.slice(2);
+const flags = new Set(rest);
+const api = createApi(BASE, INGEST);
+const run = async () => {
+    switch (cmd) {
+        case 'join': return join(api, io, INGEST, { yes: flags.has('--yes') || flags.has('-y'), force: flags.has('--force') });
+        case 'status': return status(api, io, INGEST);
+        case 'leave': return leave(api, io, INGEST);
+        default:
+            console.log('Usage: npx shipper-town <join|status|leave> [--yes] [--force]');
+            return cmd ? 1 : 0;
+    }
+};
+run().then((code) => process.exit(code), (e) => { console.error(describeError(e, BASE)); process.exit(1); });

package/dist/settings-file.js

@@ -0,0 +1,48 @@
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export function settingsPath(env, home) {
+    return join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'settings.json');
+}
+export function managedSettingsPath(platform) {
+    if (platform === 'darwin')
+        return '/Library/Application Support/ClaudeCode/managed-settings.json';
+    if (platform === 'win32')
+        return 'C:\\Program Files\\ClaudeCode\\managed-settings.json';
+    return '/etc/claude-code/managed-settings.json';
+}
+export class InvalidSettingsError extends Error {
+}
+export async function readSettings(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return {};
+        throw e;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new InvalidSettingsError(`${path} is not valid JSON. Fix it by hand first; nothing was changed.`);
+    }
+}
+/** Writes settings, backing up any existing file first. Returns the backup path, or '' if there was no file. */
+export async function writeSettings(path, next, now) {
+    await mkdir(dirname(path), { recursive: true });
+    let backup = '';
+    try {
+        backup = `${path}.bak-${now}`;
+        await copyFile(path, backup);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+        backup = '';
+    }
+    // mode applies only when the file is created; existing files keep their mode.
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    return backup;
+}

package/dist/settings.js

@@ -0,0 +1,97 @@
+/** The exact env block. Keep in sync with apps/web/src/setup-env.ts (both are tested). */
+export function telemetryEnv(key, ingestUrl) {
+    return {
+        CLAUDE_CODE_ENABLE_TELEMETRY: '1',
+        OTEL_METRICS_EXPORTER: 'otlp',
+        OTEL_EXPORTER_OTLP_METRICS_PROTOCOL: 'http/json',
+        OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: `${ingestUrl}/v1/metrics`,
+        OTEL_EXPORTER_OTLP_METRICS_HEADERS: `Authorization=Bearer ${key}`,
+        OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: 'delta',
+        OTEL_METRIC_EXPORT_INTERVAL: '600000',
+    };
+}
+export const SHIPPER_ENV_KEYS = Object.keys(telemetryEnv('k', 'b'));
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const KEY_RE = /Authorization=Bearer (ship_[0-9A-Za-z]+)/;
+function envOf(settings) {
+    if (!isObj(settings) || !isObj(settings.env))
+        return {};
+    return Object.fromEntries(Object.entries(settings.env).filter(([, v]) => typeof v === 'string'));
+}
+export function existingShipperKey(settings) {
+    return KEY_RE.exec(envOf(settings).OTEL_EXPORTER_OTLP_METRICS_HEADERS ?? '')?.[1] ?? null;
+}
+export function maskKey(key) {
+    return key.length <= 13 ? key : `${key.slice(0, 9)}…${key.slice(-4)}`;
+}
+/** Env vars already sending metrics somewhere other than Shipper Town. */
+export function findConflicts(settings, ingestUrl) {
+    const env = envOf(settings);
+    const ours = `${ingestUrl}/v1/metrics`;
+    const out = [];
+    if (env.OTEL_METRICS_EXPORTER && env.OTEL_METRICS_EXPORTER !== 'otlp')
+        out.push('OTEL_METRICS_EXPORTER');
+    if (env.OTEL_EXPORTER_OTLP_ENDPOINT)
+        out.push('OTEL_EXPORTER_OTLP_ENDPOINT');
+    // A ship_ key means a previous Shipper Town setup (another server, e.g. localhost or an old host): replace it freely.
+    const shipperSetup = KEY_RE.test(env.OTEL_EXPORTER_OTLP_METRICS_HEADERS ?? '');
+    if (env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT && env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT !== ours && !shipperSetup) {
+        out.push('OTEL_EXPORTER_OTLP_METRICS_ENDPOINT');
+    }
+    if (env.OTEL_EXPORTER_OTLP_METRICS_HEADERS && !KEY_RE.test(env.OTEL_EXPORTER_OTLP_METRICS_HEADERS))
+        out.push('OTEL_EXPORTER_OTLP_METRICS_HEADERS');
+    return out;
+}
+const display = (v) => v.replace(/ship_[0-9A-Za-z]+/, (k) => maskKey(k));
+/** Foreign header values may hold secrets, so never print them. */
+const shownFrom = (k, v) => k.endsWith('_HEADERS') && !KEY_RE.test(v) ? '[redacted]' : display(v);
+export function mergeSettings(settings, key, ingestUrl, opts) {
+    if (!isObj(settings))
+        return { ok: false, reason: 'settings.json is not a JSON object' };
+    if (settings.env !== undefined && !isObj(settings.env))
+        return { ok: false, reason: '"env" in settings.json is not an object' };
+    const conflicts = findConflicts(settings, ingestUrl);
+    if (conflicts.length && !opts.force) {
+        return {
+            ok: false,
+            reason: `Claude Code already sends metrics elsewhere (${conflicts.join(', ')}). ` +
+                'Claude Code supports one metrics destination, so joining would stop that. Re-run with --force to replace it.',
+        };
+    }
+    const current = envOf(settings);
+    const wanted = telemetryEnv(key, ingestUrl);
+    const changes = [];
+    for (const [k, v] of Object.entries(wanted)) {
+        if (current[k] === v)
+            continue;
+        changes.push(current[k] === undefined ? { key: k, to: display(v) } : { key: k, from: shownFrom(k, current[k]), to: display(v) });
+    }
+    return {
+        ok: true,
+        next: { ...settings, env: { ...settings.env, ...wanted } },
+        changes,
+        // Only a key from this same server can be revoked here; one from another server is just replaced.
+        oldKey: current.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT === `${ingestUrl}/v1/metrics` ? existingShipperKey(settings) : null,
+    };
+}
+/**
+ * Removes only the env vars Shipper Town wrote, and only when this is our setup
+ * (our endpoint plus a ship_ key). A key the user customised stays.
+ */
+export function removeShipperEnv(settings, ingestUrl) {
+    const base = isObj(settings) ? { ...settings } : {};
+    const oldKey = existingShipperKey(base);
+    const ours = oldKey !== null && envOf(base).OTEL_EXPORTER_OTLP_METRICS_ENDPOINT === `${ingestUrl}/v1/metrics`;
+    if (!ours || !isObj(base.env))
+        return { next: base, removed: [], oldKey };
+    const expected = telemetryEnv(oldKey, ingestUrl);
+    const env = { ...base.env };
+    const removed = SHIPPER_ENV_KEYS.filter((k) => k in env && env[k] === expected[k]);
+    for (const k of removed)
+        delete env[k];
+    if (Object.keys(env).length === 0)
+        delete base.env;
+    else
+        base.env = env;
+    return { next: base, removed, oldKey };
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "shipper-town",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Join the Shipper Town leaderboard: turns on Claude Code's built-in usage metrics for this machine.",
+  "license": "MIT",
+  "homepage": "https://shipper.town",
+  "keywords": [
+    "claude-code",
+    "leaderboard",
+    "opentelemetry",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "shipper-town": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "5.9.3",
+    "vitest": "5.0.5"
+  }
+}