@primitive.ai/prim 0.1.0-alpha.15 → 0.1.0-alpha.17

package/SKILL.md

@@ -83,20 +83,60 @@ npx --yes @primitive.ai/prim project create -n "<name>" --spec <contextId>     #
 
 ### Link a spec to a branch (and an optional PR)
 
-A branch-linked spec only auto-syncs from commits on its branch — so per-branch work doesn't mutate specs that aren't relevant. The link is the contract the pre-commit hook checks before every `sync-diff`.
+Linking is **automatic** once the pre-commit hook is installed and a spec is bound to your branch — every commit refreshes the link's metadata, including the PR number (detected from `gh pr view` when `gh` is on `PATH`). When a spec was authored for the work on this branch, bind it at the right moment so the hook can take over — do this without waiting for the user to ask. When no spec exists for the work, **do not bind one** — see "Decide whether a spec exists for this branch" below.
 
-Two ways to bind a spec to a branch:
+**At the start of branch work, install the hook** (skip if `.git/hooks/pre-commit` or `.husky/pre-commit` already invokes `prim-pre-commit`):
+```
+npx --yes @primitive.ai/prim hooks install --yes
+```
 
+**When you create a spec for branch-scoped work, always pass `--branch`** (and `--pr` if a PR already exists):
 ```
-npx --yes @primitive.ai/prim spec create -s project -n "<name>" --file <path> --branch <branch> --pr <n>   # explicit at creation; --pr is optional
+br=$(git rev-parse --abbrev-ref HEAD)
+pr=$(gh pr view --json number -q .number 2>/dev/null)
+npx --yes @primitive.ai/prim spec create -s project -n "<name>" --file <path> --branch "$br" ${pr:+--pr "$pr"}
 ```
+`--branch` requires a GitHub origin; if `git remote get-url origin` isn't GitHub the link is silently dropped (stderr warning). There is no `prim spec link` subcommand in v1 — to rebind a spec to a different branch, edit it from the spec editor UI.
+
+**Decide whether a spec exists for this branch.** A spec is "for this branch" only if one of:
+- the user named a spec ID or title in conversation,
+- a spec was created with `--branch "$br"` (visible via `npx --yes @primitive.ai/prim spec list --json | jq --arg br "$br" '.[] | select(.linkedBranches[]?.branch == $br)'`, where `$br` is the same shell variable set in the recipe above).
+
+**Do not** browse `prim spec list` and pick the closest- or most-related-sounding spec. Topical proximity is not authorship — two specs that touch the same area of the codebase can describe entirely different intents. An irrelevant link pollutes drift signal and silently misattributes review findings; no link is strictly better than a wrong link.
+
+If neither signal applies, **stop and ask the user**:
+
+> "I couldn't find a spec associated with this branch. Is there one I should link, or should I draft one from the PR description and our conversation?"
 
-Or implicitly: the pre-commit hook **auto-links an unlinked spec to the current branch** the first time it sees a sync on that branch — no flag needed. The `[synced]` line on that first sync prints ` (auto-linking to <branch>)`; subsequent syncs print ` (linked to <branch> #<pr> <state>)` once the link sticks.
+Three legitimate answers:
+- **User names an existing spec** → proceed to "When the user has identified a spec for this branch" below.
+- **User declines a spec entirely** → leave the PR unlinked.
+- **User asks you to draft one** →
+  - Compose with these sections (drop any that would only restate the obvious): *Goal*, *Requirements / Behavior*, *Technical Approach*, *Key Decisions*, *Out of Scope*. Scope to what the PR actually changed; don't restate the unchanged system. Each fact appears in exactly one section.
+  - Voice: plain language; lead with the point; **intent before mechanism** ("users see each other's edits" before "we use WebSocket"); present tense, active voice; one idea per paragraph; cut sentences that don't earn their place.
+  - **Key Decisions** is a markdown table — columns *Decision | Rationale | Trade-offs*, one row per non-obvious choice.
+  - Title is just the feature name (no `Spec:` prefix); no numbered or parenthetical headers. Match length to PR complexity — a small fix is one screen; a substantial feature warrants the full shape.
+  - Do not paste the PR description verbatim — a spec captures *intent*, not a change log. If the rationale behind a non-obvious decision isn't in conversation, ask one or two targeted questions before drafting; do not invent rationale.
+  - Show the user the drafted text and wait for go-ahead before running `spec create`.
+  - Then create-and-link using the recipe above.
 
-Inspect a spec's bindings via `npx --yes @primitive.ai/prim context get <id>`. The `linkedBranches[]` field lists every `(branch, prNumber, prState, prReviewDecision)` the spec is bound to. The editor UI surfaces the same data as a status pill.
+**When the user has identified a spec for this branch, check whether it's bound to your branch** before committing:
+```
+npx --yes @primitive.ai/prim context get <specId> --json | jq '.linkedBranches[]?.branch'
+```
+- Your branch appears → done; the hook keeps it fresh.
+- Empty or branch absent → the first commit's hook auto-binds it; no CLI step needed.
+- Bound only to another branch → the hook silently excludes it from your branch's syncs; rebind via the editor UI before committing.
+
+**After `gh pr create`**, no CLI step is required: the next commit's hook patches `linkedBranches[].prNumber` via `gh pr view`, and GitHub's webhook to Primitive sets the same field server-side within seconds. Confirm with:
+```
+npx --yes @primitive.ai/prim context get <specId> --json | jq .linkedBranches
+```
 
-- **`--branch` requires a GitHub origin.** With `--branch`, the CLI reads `repoFullName` from `git remote get-url origin`. If origin isn't GitHub, the link is silently dropped with a warning on stderr — the spec is still created, just unlinked — fix it later from the editor UI.
-- **There is no `prim spec link` subcommand in v1.** To re-link a spec to a different branch, edit it from the spec editor. The CLI only ever auto-links on first sync or accepts `--branch` at creation.
+**On every commit, read the `[synced]` line to verify link state** — it piggybacks the suffix:
+- `(auto-linking to <branch>)` — first sync; server is binding now.
+- `(linked to <branch> #<n> <state>)` — link is sticky.
+- `[skip] <id> — not linked to <branch>` — the spec is bound elsewhere; investigate before continuing.
 
 ### Trigger PR Intent Review or dispatch drift-fix against a linked PR
 

package/dist/{chunk-SHLF6OL2.js → chunk-6SIEWWUL.js}

@@ -68,9 +68,16 @@ function getAuthToken() {
   }
   return void 0;
 }
-var API_URL = "https://api.getprimitive.ai";
+var DEFAULT_API_URL = "https://api.getprimitive.ai";
 function getSiteUrl() {
-  return API_URL;
+  if (process.env.PRIM_API_URL) {
+    return process.env.PRIM_API_URL;
+  }
+  const envVars = loadEnvFile();
+  if (envVars.PRIM_API_URL) {
+    return envVars.PRIM_API_URL;
+  }
+  return DEFAULT_API_URL;
 }
 async function refreshToken() {
   if (!existsSync(REFRESH_TOKEN_PATH)) {
@@ -87,6 +94,11 @@ async function refreshToken() {
     body: JSON.stringify({ refresh_token: refreshTokenValue })
   });
   if (!response.ok) {
+    const detail = (await response.text().catch(() => "")).slice(0, 200);
+    process.stderr.write(
+      `[prim] token refresh rejected by broker: ${response.status} ${response.statusText}${detail ? ` \u2014 ${detail}` : ""}
+`
+    );
     return void 0;
   }
   const data = await response.json();
@@ -100,6 +112,14 @@ async function refreshToken() {
   saveTokenExpiry(data.access_token, data.expires_in);
   return data.access_token;
 }
+var HttpError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+  }
+};
 var _cachedToken;
 async function request(method, path, body, options) {
   const siteUrl = getSiteUrl();
@@ -137,10 +157,10 @@ async function request(method, path, body, options) {
   }
   if (!res.ok) {
     if (res.status === 401) {
-      throw new Error("Authentication expired. Run `prim auth login` to re-authenticate.");
+      throw new HttpError(401, "Authentication expired. Run `prim auth login` to re-authenticate.");
     }
     const errorBody = await res.json().catch(() => null);
-    throw new Error(errorBody?.error ?? `HTTP ${res.status}`);
+    throw new HttpError(res.status, errorBody?.error ?? `HTTP ${res.status}`);
   }
   return res.json();
 }
@@ -153,34 +173,6 @@ function getClient() {
   };
 }
 
-// src/utils/git.ts
-import { execSync } from "child_process";
-function safeExec(cmd) {
-  try {
-    return execSync(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-  } catch {
-    return null;
-  }
-}
-function parseRepoFullName(remoteUrl) {
-  const match = remoteUrl.match(/(?:github\.com[:/])([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
-  return match ? `${match[1]}/${match[2]}` : null;
-}
-function getGitContext() {
-  const branchRaw = safeExec("git rev-parse --abbrev-ref HEAD");
-  const branch = branchRaw && branchRaw !== "HEAD" ? branchRaw : null;
-  const sha = safeExec("git rev-parse HEAD");
-  const remoteUrl = safeExec("git remote get-url origin");
-  const repoFullName = remoteUrl ? parseRepoFullName(remoteUrl) : null;
-  let prNumber = null;
-  if (safeExec("command -v gh")) {
-    const raw = safeExec("gh pr view --json number -q .number");
-    const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
-    if (Number.isFinite(n)) prNumber = n;
-  }
-  return { branch, sha, repoFullName, prNumber };
-}
-
 export {
   TOKEN_FILE_PATH,
   REFRESH_TOKEN_PATH,
@@ -189,6 +181,7 @@ export {
   getTokenExpiresAt,
   getAuthToken,
   getSiteUrl,
-  getClient,
-  getGitContext
+  refreshToken,
+  HttpError,
+  getClient
 };

package/dist/chunk-7YRBACIE.js

@@ -0,0 +1,9 @@
+// src/hooks/agent.ts
+function parseAgent(argv) {
+  const i = argv.indexOf("--agent");
+  return i !== -1 && argv[i + 1] === "codex" ? "codex" : "claude_code";
+}
+
+export {
+  parseAgent
+};

package/dist/chunk-BEEGFDGU.js

@@ -0,0 +1,59 @@
+// src/lib/ansi.ts
+var ANSI_CODES = {
+  yellow: "\x1B[33m",
+  magenta: "\x1B[35m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  // 256-color approximation of the orange trigger marker (xterm 208).
+  orange: "\x1B[38;5;208m",
+  gray: "\x1B[90m"
+};
+var ANSI_RESET = "\x1B[0m";
+var ANSI_BOLD = "\x1B[1m";
+function supportsColor() {
+  if (process.env.NO_COLOR !== void 0 && process.env.NO_COLOR !== "") {
+    return false;
+  }
+  return process.stderr.isTTY === true;
+}
+function color(text, c) {
+  if (!supportsColor()) {
+    return text;
+  }
+  return `${ANSI_CODES[c]}${text}${ANSI_RESET}`;
+}
+function bold(text) {
+  if (!supportsColor()) {
+    return text;
+  }
+  return `${ANSI_BOLD}${text}${ANSI_RESET}`;
+}
+var AREA_COLORS = {
+  auth: "yellow",
+  data: "magenta",
+  mobile: "blue",
+  infra: "cyan",
+  ui: "green",
+  billing: "orange",
+  api: "blue",
+  docs: "gray",
+  testing: "gray"
+};
+function colorForArea(area) {
+  if (!area) {
+    return "gray";
+  }
+  return AREA_COLORS[area] ?? "gray";
+}
+function stripAnsi(text) {
+  return text.replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+export {
+  color,
+  bold,
+  colorForArea,
+  stripAnsi
+};

package/dist/chunk-JZGWQDM5.js

@@ -0,0 +1,199 @@
+// src/journal.ts
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync
+} from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var JOURNAL_DIR = join(homedir(), ".config", "prim", "moves");
+var LEGACY_JOURNAL_PATH = join(JOURNAL_DIR, "journal.ndjson");
+var UNBOUND_BUCKET = "_unbound";
+var JOURNAL_BASENAME = "journal.ndjson";
+var DIR_MODE = 448;
+var FILE_MODE = 384;
+var SAFE_BUCKET = /^[A-Za-z0-9_-]+$/;
+var RESERVED_BUCKETS = /* @__PURE__ */ new Set([UNBOUND_BUCKET, "_legacy"]);
+function appendMoveToPath(path, move) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+  }
+  appendFileSync(path, `${JSON.stringify(move)}
+`, { mode: FILE_MODE });
+}
+function bucketDir(orgId) {
+  const safe = orgId !== void 0 && SAFE_BUCKET.test(orgId) && !RESERVED_BUCKETS.has(orgId);
+  return join(JOURNAL_DIR, safe ? orgId : UNBOUND_BUCKET);
+}
+function journalPath(orgId) {
+  return join(bucketDir(orgId), JOURNAL_BASENAME);
+}
+function appendMove(move, orgId) {
+  appendMoveToPath(journalPath(orgId), move);
+}
+function readMovesFromPath(path) {
+  if (!existsSync(path)) {
+    return [];
+  }
+  const content = readFileSync(path, "utf-8");
+  const moves = [];
+  for (const line of content.split("\n")) {
+    if (line.length === 0) {
+      continue;
+    }
+    try {
+      moves.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return moves;
+}
+function listBuckets() {
+  const out = [];
+  if (existsSync(LEGACY_JOURNAL_PATH)) {
+    out.push({ bucket: "_legacy", path: LEGACY_JOURNAL_PATH });
+  }
+  if (!existsSync(JOURNAL_DIR)) {
+    return out;
+  }
+  for (const entry of readdirSync(JOURNAL_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const path = join(JOURNAL_DIR, entry.name, JOURNAL_BASENAME);
+    if (existsSync(path)) {
+      out.push({ bucket: entry.name, path });
+    }
+  }
+  return out;
+}
+function bucketStats() {
+  return listBuckets().map(({ bucket, path }) => {
+    const stat = statSync(path);
+    const content = readFileSync(path, "utf-8");
+    const lineCount = content.split("\n").filter((l) => l.length > 0).length;
+    return {
+      bucket,
+      path,
+      sizeBytes: stat.size,
+      mtimeMs: stat.mtimeMs,
+      lineCount
+    };
+  });
+}
+
+// src/binding.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+var PRIM_CONFIG_DIR = join2(homedir2(), ".config", "prim");
+var TOKEN_PATH = join2(PRIM_CONFIG_DIR, "token");
+var SESSIONS_DIR = join2(PRIM_CONFIG_DIR, "sessions");
+var WORKSPACE_FILE = ".prim/workspace.json";
+var JWT_PARTS = 3;
+var BASE64_PAD_4 = 4;
+var ENV_TOKEN_LINE = /^\s*PRIM_TOKEN\s*=\s*(.*)$/m;
+var SURROUNDING_QUOTES = /^["']|["']$/g;
+var BASE64URL_MINUS = /-/g;
+var BASE64URL_UNDERSCORE = /_/g;
+function readJsonSafe(path) {
+  if (!existsSync2(path)) {
+    return;
+  }
+  try {
+    return JSON.parse(readFileSync2(path, "utf-8"));
+  } catch {
+    return;
+  }
+}
+function fromSessionMarker(sessionId) {
+  if (!sessionId) {
+    return;
+  }
+  const marker = readJsonSafe(join2(SESSIONS_DIR, `${sessionId}.json`));
+  return marker?.orgId;
+}
+function fromWorkspaceFile(startDir) {
+  let dir = startDir;
+  while (true) {
+    const config = readJsonSafe(join2(dir, WORKSPACE_FILE));
+    if (config?.orgId) {
+      return config.orgId;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) {
+      return;
+    }
+    dir = parent;
+  }
+}
+function readToken(cwd) {
+  const fromEnv = process.env.PRIM_TOKEN;
+  if (fromEnv) {
+    return fromEnv.trim();
+  }
+  if (existsSync2(TOKEN_PATH)) {
+    return readFileSync2(TOKEN_PATH, "utf-8").trim();
+  }
+  const envLocal = join2(cwd, ".env.local");
+  if (existsSync2(envLocal)) {
+    const match = readFileSync2(envLocal, "utf-8").match(ENV_TOKEN_LINE);
+    if (match) {
+      return match[1].trim().replace(SURROUNDING_QUOTES, "");
+    }
+  }
+  return;
+}
+function base64UrlDecode(s) {
+  const padded = s.padEnd(
+    s.length + (BASE64_PAD_4 - s.length % BASE64_PAD_4) % BASE64_PAD_4,
+    "="
+  );
+  const normalized = padded.replace(BASE64URL_MINUS, "+").replace(BASE64URL_UNDERSCORE, "/");
+  return Buffer.from(normalized, "base64").toString("utf-8");
+}
+function fromDefaultOrg(cwd) {
+  const token = readToken(cwd);
+  if (!token) {
+    return;
+  }
+  const parts = token.split(".");
+  if (parts.length !== JWT_PARTS) {
+    return;
+  }
+  try {
+    const claims = JSON.parse(base64UrlDecode(parts[1]));
+    return claims.org_id;
+  } catch {
+    return;
+  }
+}
+function resolveOrg(args) {
+  const fromSession = fromSessionMarker(args.sessionId);
+  if (fromSession) {
+    return { orgId: fromSession, source: "session" };
+  }
+  const fromWorkspace = fromWorkspaceFile(args.cwd);
+  if (fromWorkspace) {
+    return { orgId: fromWorkspace, source: "workspace" };
+  }
+  const fromDefault = fromDefaultOrg(args.cwd);
+  if (fromDefault) {
+    return { orgId: fromDefault, source: "defaultOrg" };
+  }
+  return { orgId: void 0, source: "unbound" };
+}
+
+export {
+  JOURNAL_DIR,
+  appendMove,
+  readMovesFromPath,
+  listBuckets,
+  bucketStats,
+  SESSIONS_DIR,
+  resolveOrg
+};

package/dist/chunk-LCC66K45.js

@@ -0,0 +1,115 @@
+// src/hooks/prim-hook-core.ts
+import { randomUUID } from "crypto";
+import { platform } from "os";
+
+// src/protocol/move.ts
+var ENVELOPE_VERSION = 1;
+
+// src/hooks/prim-hook-core.ts
+function toMove(parsed, cliVersion, agent = "claude_code") {
+  return {
+    moveId: randomUUID(),
+    capturedAt: Date.now(),
+    sessionId: parsed.session_id ?? "",
+    eventType: parsed.hook_event_name ?? "unknown",
+    payload: parsed,
+    env: {
+      cwd: parsed.cwd ?? process.cwd(),
+      cliVersion,
+      osPlatform: platform()
+    },
+    envelopeVersion: ENVELOPE_VERSION,
+    // Stamp the producer only for Codex; Claude Code moves omit it (the
+    // backend defaults an absent value to "claude_code"), keeping the
+    // Claude wire shape byte-identical.
+    ...agent === "codex" ? { producer: "codex" } : {}
+  };
+}
+function shouldFlushAfter(eventType) {
+  return eventType === "SessionEnd";
+}
+
+// src/hooks/redact.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var DEFAULT_RULES = [
+  { pattern: /Bearer\s+[A-Za-z0-9._\-]+/g, reason: "bearer-token" },
+  { pattern: /sk-[A-Za-z0-9]{32,}/g, reason: "sk-api-key" },
+  {
+    pattern: /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]+?-----END [A-Z ]+PRIVATE KEY-----/g,
+    reason: "private-key"
+  },
+  { pattern: /xox[abprs]-[A-Za-z0-9-]{10,}/g, reason: "slack-token" },
+  { pattern: /ghp_[A-Za-z0-9]{36,}/g, reason: "github-pat" }
+];
+var MAX_SCRUB_LEN = 256e3;
+var WORKSPACE_FILE = ".prim/redaction.json";
+function debugRedaction(message, err) {
+  if (!process.env.PRIM_HOOK_DEBUG) {
+    return;
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[prim-hook] redaction: ${message}: ${detail}
+`);
+}
+function loadWorkspaceRules(cwd) {
+  const path = join(cwd, WORKSPACE_FILE);
+  if (!existsSync(path)) {
+    return [];
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    debugRedaction(`ignoring unparseable ${WORKSPACE_FILE}`, err);
+    return [];
+  }
+  if (!cfg.rules) {
+    return [];
+  }
+  const compiled = [];
+  for (const r of cfg.rules) {
+    try {
+      compiled.push({ pattern: new RegExp(r.pattern, r.flags ?? "g"), reason: r.reason });
+    } catch (err) {
+      debugRedaction(`skipping invalid redaction rule "${r.reason}"`, err);
+    }
+  }
+  return compiled;
+}
+function applyRules(input, rules) {
+  if (input.length > MAX_SCRUB_LEN) {
+    return "<REDACTED:oversized>";
+  }
+  let out = input;
+  for (const rule of rules) {
+    out = out.replace(rule.pattern, `<REDACTED:${rule.reason}>`);
+  }
+  return out;
+}
+function scrub(value, rules = DEFAULT_RULES) {
+  if (typeof value === "string") {
+    return applyRules(value, rules);
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => scrub(v, rules));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = scrub(v, rules);
+    }
+    return out;
+  }
+  return value;
+}
+function scrubFromCwd(value, cwd) {
+  const rules = [...DEFAULT_RULES, ...loadWorkspaceRules(cwd)];
+  return scrub(value, rules);
+}
+
+export {
+  toMove,
+  shouldFlushAfter,
+  scrubFromCwd
+};