@bigstrider/transcodes-cli 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# @bigstrider/transcodes-cli
+
+Token manager for the **ai-action-tracker** plugins (Claude Code / Codex / Cursor / Antigravity).
+
+The plugins and their hooks authenticate to the Transcodes backend with a member MCP JWT. This CLI is the safe way to store that token: you paste it into your terminal, **never into the agent chat** (which would leak it into the transcript).
+
+## Install
+
+```bash
+# no install needed
+npx @bigstrider/transcodes-cli login <token>
+
+# or global
+npm install -g @bigstrider/transcodes-cli
+transcodes login <token>
+```
+
+Works the same on macOS, Linux, and Windows (Node ≥ 20).
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `transcodes login <token>` | Validates the JWT and saves it to `~/.transcodes/config.json` (dir `0700`, file `0600`). |
+| `transcodes logout` | Deletes the saved token. |
+| `transcodes status` | Shows the active token source (env vs file) and its expiry. |
+| `transcodes help` | Usage. |
+
+## Token precedence
+
+The plugins resolve the token in this order (see `@ai-action-tracker/stepup-core` `resolveToken()`):
+
+1. `TRANSCODES_TOKEN` environment variable — overrides everything (CI / power users)
+2. `~/.transcodes/config.json` — written by this CLI
+3. none → the hook fail-safes (blocks danger commands, cannot start step-up)
+
+## Notes
+
+- **Windows security**: the `0600` mode is a POSIX concept and is largely ignored on Windows. The file still lives under your user profile (`C:\Users\<you>\.transcodes\`) and is user-scoped by default. A hardware-backed OS keychain is tracked in `docs/prd/0005-token-auth-device-flow.md`.
+- The token never passes through the agent chat — this CLI writes the file directly.

package/dist/index.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+
+// ../stepup-core/dist/jwt.js
+var REQUIRED_AUDIENCE = "transcodes-mcp";
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function tryDecodeBase64UrlJson(segment) {
+  if (!segment)
+    return void 0;
+  try {
+    const json = Buffer.from(segment, "base64url").toString("utf8");
+    const parsed = JSON.parse(json);
+    return isPlainObject(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readString(rec, key) {
+  const v = rec[key];
+  if (typeof v !== "string")
+    return void 0;
+  const t = v.trim();
+  return t || void 0;
+}
+function readNumericDate(rec, key) {
+  const v = rec[key];
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() ? Number(v) : Number.NaN;
+  return Number.isFinite(n) ? Math.floor(n) : void 0;
+}
+function readAudience(rec) {
+  const aud = rec["aud"];
+  if (typeof aud === "string") {
+    const t = aud.trim();
+    return t ? [t] : void 0;
+  }
+  if (Array.isArray(aud)) {
+    const list = aud.filter((x) => typeof x === "string").map((x) => x.trim()).filter((x) => x.length > 0);
+    return list.length > 0 ? list : void 0;
+  }
+  return void 0;
+}
+function parseMemberAccessToken(rawToken) {
+  if (typeof rawToken !== "string") {
+    throw new Error("token must be a string");
+  }
+  const raw = rawToken.trim();
+  if (!raw) {
+    throw new Error("token is empty");
+  }
+  const warnings = [];
+  const parts = raw.split(".");
+  if (parts.length !== 3 || parts.some((p) => !p)) {
+    warnings.push(`token does not look like a JWT (expected 3 non-empty segments, got ${parts.length})`);
+  }
+  const payloadSegment = parts.length === 3 ? parts[1] : raw;
+  const payload = tryDecodeBase64UrlJson(payloadSegment);
+  if (!payload) {
+    throw new Error("token payload could not be decoded as base64url JSON object");
+  }
+  const organizationId = readString(payload, "oid");
+  const projectId = readString(payload, "pid");
+  const memberId = readString(payload, "mid");
+  if (!organizationId || !projectId || !memberId) {
+    throw new Error("token payload must include oid, pid, and mid claims");
+  }
+  const aud = readAudience(payload);
+  if (!aud) {
+    warnings.push("aud claim is missing");
+  } else if (!aud.includes(REQUIRED_AUDIENCE)) {
+    warnings.push(`aud does not include "${REQUIRED_AUDIENCE}" (got ${JSON.stringify(aud)})`);
+  }
+  const exp = readNumericDate(payload, "exp");
+  if (exp === void 0) {
+    throw new Error("token must include exp claim (NumericDate, integer seconds)");
+  }
+  const nowSec = Math.floor(Date.now() / 1e3);
+  if (nowSec >= exp) {
+    throw new Error("token has expired");
+  }
+  return {
+    raw,
+    claims: {
+      organizationId,
+      projectId,
+      memberId,
+      aud,
+      exp,
+      iss: readString(payload, "iss"),
+      jti: readString(payload, "jti"),
+      iat: readNumericDate(payload, "iat")
+    },
+    warnings
+  };
+}
+
+// ../stepup-core/dist/token-store.js
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import os from "os";
+import path from "path";
+var CONFIG_DIR_NAME = ".transcodes";
+var CONFIG_FILE_NAME = "config.json";
+function transcodesConfigDir() {
+  return path.join(os.homedir(), CONFIG_DIR_NAME);
+}
+function transcodesConfigFile() {
+  return path.join(transcodesConfigDir(), CONFIG_FILE_NAME);
+}
+function readTokenFromFile() {
+  let raw;
+  try {
+    raw = readFileSync(transcodesConfigFile(), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+  const token = parsed.token;
+  if (typeof token !== "string")
+    return null;
+  const trimmed = token.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function writeTokenToFile(token) {
+  const trimmed = token.trim();
+  if (!trimmed) {
+    throw new Error("token is empty");
+  }
+  const dir = transcodesConfigDir();
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  writeFileSync(transcodesConfigFile(), JSON.stringify({ token: trimmed }), {
+    mode: 384
+  });
+}
+function clearTokenFile() {
+  try {
+    rmSync(transcodesConfigFile(), { force: true });
+  } catch {
+  }
+}
+function resolveToken() {
+  const envToken = process.env.TRANSCODES_TOKEN?.trim();
+  if (envToken) {
+    return { token: envToken, source: "env" };
+  }
+  const fileToken = readTokenFromFile();
+  if (fileToken) {
+    return { token: fileToken, source: "file" };
+  }
+  return { token: null, source: "none" };
+}
+
+// src/index.ts
+var USAGE = `transcodes \u2014 ai-action-tracker token manager
+
+Usage:
+  transcodes login <token>   Save your Transcodes member token to ${transcodesConfigFile()}
+  transcodes logout          Remove the saved token
+  transcodes status          Show where the active token comes from
+  transcodes help            Show this message
+
+The token is read by the ai-action-tracker plugins/hooks with precedence:
+  1. TRANSCODES_TOKEN environment variable (overrides everything)
+  2. ${transcodesConfigFile()}
+`;
+function fail(message) {
+  process.stderr.write(`transcodes: ${message}
+`);
+  process.exit(1);
+}
+function expiryLine(token) {
+  try {
+    const parsed = parseMemberAccessToken(token);
+    const exp = new Date(parsed.claims.exp * 1e3).toISOString();
+    const warn = parsed.warnings.length > 0 ? `  (warnings: ${parsed.warnings.join("; ")})` : "";
+    return `member=${parsed.claims.memberId} project=${parsed.claims.projectId} expires=${exp}${warn}`;
+  } catch (err) {
+    return `unable to decode token: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}
+function cmdLogin(token) {
+  if (!token || !token.trim()) {
+    fail("missing token. Usage: transcodes login <token>");
+  }
+  const trimmed = token.trim();
+  try {
+    parseMemberAccessToken(trimmed);
+  } catch (err) {
+    fail(
+      `token rejected: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  try {
+    writeTokenToFile(trimmed);
+  } catch (err) {
+    fail(
+      `could not write token file: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  process.stdout.write(
+    `Saved to ${transcodesConfigFile()}
+  ${expiryLine(trimmed)}
+`
+  );
+}
+function cmdLogout() {
+  clearTokenFile();
+  process.stdout.write(`Removed ${transcodesConfigFile()}
+`);
+}
+function cmdStatus() {
+  const { token, source } = resolveToken();
+  if (source === "none" || !token) {
+    process.stdout.write(
+      "No token configured. Run `transcodes login <token>` to set one.\n"
+    );
+    return;
+  }
+  const where = source === "env" ? "TRANSCODES_TOKEN environment variable" : transcodesConfigFile();
+  process.stdout.write(`Active token source: ${where}
+  ${expiryLine(token)}
+`);
+}
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "login":
+      cmdLogin(rest[0]);
+      break;
+    case "logout":
+      cmdLogout();
+      break;
+    case "status":
+      cmdStatus();
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case void 0:
+      process.stdout.write(USAGE);
+      break;
+    default:
+      fail(`unknown command "${command}". Run \`transcodes help\`.`);
+  }
+}
+main();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@bigstrider/transcodes-cli",
+  "version": "0.1.0",
+  "description": "Transcodes CLI — manage the ai-action-tracker member token (login/logout/status).",
+  "type": "module",
+  "bin": {
+    "transcodes": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup && chmod 755 dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@ai-action-tracker/stepup-core": "*",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}