@primitive.ai/prim 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Primitive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @primitive.ai/prim
+
+The official CLI for [Primitive](https://getprimitive.ai). Manage specs, contexts, tasks, and git hooks from the command line.
+
+> [!WARNING]
+> This project is in **alpha**. Commands and APIs may change between releases.
+
+## Installation
+
+Requires Node.js 20+.
+
+```bash
+npm install -g @primitive.ai/prim
+```
+
+Or run directly without installing:
+
+```bash
+npx @primitive.ai/prim
+```
+
+## Quick Start
+
+```bash
+# Authenticate via browser (WorkOS OAuth)
+prim auth login
+
+# List your specs
+prim spec list
+
+# Install the pre-commit hook
+prim hooks install
+```
+
+## Commands
+
+### Auth
+
+```bash
+prim auth login              # Authenticate via browser
+prim auth set-token <token>  # Save a bearer token (e.g. for CI)
+prim auth clear              # Remove saved tokens
+prim auth status             # Check authentication status
+```
+
+### Specs
+
+Specs are documents that drive implementation. They can be synced to a task DAG and mapped to file patterns for automatic pre-commit hook integration.
+
+```bash
+prim spec list                        # List all specs
+prim spec list --task-id <id>         # Find spec for a root task
+prim spec get <id>                    # Show spec details
+prim spec get <id> --text-only        # Print raw spec text
+prim spec update <id> --file spec.md  # Update spec from file
+prim spec update <id> --name "New"    # Rename a spec
+prim spec sync <id>                   # Trigger spec-to-task sync
+prim spec map <id> -p "src/auth/**"   # Map file patterns to a spec
+prim spec unmap <id>                  # Clear all file patterns
+prim spec unmap <id> -p "src/auth/**" # Remove specific pattern
+prim spec auto-map <id>              # Auto-detect file patterns
+```
+
+### Contexts
+
+```bash
+prim context list                     # List all contexts
+prim context list --scope task        # Filter by scope
+prim context list --task-id <id>      # List contexts for a task
+prim context get <id>                 # Get context details
+prim context create -s task -n "Name" # Create a context
+prim context create -s task -n "Name" --file path/to/file
+prim context update <id> --name "New" # Update a context
+prim context delete <id>              # Delete a context
+prim context link <id> --task <tid>   # Link context to task
+prim context unlink <id> --task <tid> # Unlink context from task
+```
+
+### Tasks
+
+```bash
+prim task create -n "Task name"                    # Create a task
+prim task create -n "Task name" -d "Description"   # Create with description
+prim task create -n "Task name" --spec <contextId> # Create and link a spec
+```
+
+### Hooks
+
+```bash
+prim hooks install    # Install pre-commit hook
+prim hooks uninstall  # Remove pre-commit hook
+```
+
+The pre-commit hook automatically syncs specs when you commit changes to files matching a spec's file patterns (configured via `prim spec map`).
+
+Supports [Husky](https://typicode.github.io/husky/) — `prim hooks install` detects Husky and offers to install into `.husky/pre-commit`.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev          # Build in watch mode
+pnpm build        # Production build
+pnpm test         # Run tests
+pnpm typecheck    # Type-check
+pnpm lint         # Lint
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/chunk-3APLWTLB.js

@@ -0,0 +1,165 @@
+// src/client.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+function loadEnvFile() {
+  const envVars = {};
+  const candidates = [".env.local", ".env"];
+  for (const file of candidates) {
+    const filePath = resolve(process.cwd(), file);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, "utf-8");
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx === -1) continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const value = trimmed.slice(eqIdx + 1).trim();
+        envVars[key] = value;
+      }
+    }
+  }
+  return envVars;
+}
+var TOKEN_FILE_PATH = join(homedir(), ".config", "prim", "token");
+var REFRESH_TOKEN_PATH = TOKEN_FILE_PATH.replace("/token", "/refresh_token");
+var TOKEN_EXPIRES_PATH = join(homedir(), ".config", "prim", "token_expires_at");
+var REFRESH_THRESHOLD_MS = 6e4;
+function isTokenExpiringSoon() {
+  if (!existsSync(TOKEN_EXPIRES_PATH)) return false;
+  const expiresAt = Number(readFileSync(TOKEN_EXPIRES_PATH, "utf-8").trim());
+  return !Number.isNaN(expiresAt) && Date.now() >= expiresAt - REFRESH_THRESHOLD_MS;
+}
+function getJwtExpiry(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return void 0;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+    return payload.exp ? payload.exp * 1e3 : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function saveTokenExpiry(token, expiresIn) {
+  const expiresAt = expiresIn ? Date.now() + expiresIn * 1e3 : getJwtExpiry(token);
+  if (expiresAt) {
+    writeFileSync(TOKEN_EXPIRES_PATH, String(expiresAt), { mode: 384 });
+  }
+}
+function getTokenExpiresAt() {
+  if (!existsSync(TOKEN_EXPIRES_PATH)) return void 0;
+  const val = Number(readFileSync(TOKEN_EXPIRES_PATH, "utf-8").trim());
+  return Number.isNaN(val) ? void 0 : val;
+}
+function getAuthToken() {
+  if (process.env.PRIM_TOKEN) {
+    return process.env.PRIM_TOKEN;
+  }
+  if (existsSync(TOKEN_FILE_PATH)) {
+    const token = readFileSync(TOKEN_FILE_PATH, "utf-8").trim();
+    if (token) {
+      return token;
+    }
+  }
+  const envVars = loadEnvFile();
+  if (envVars.PRIM_TOKEN) {
+    return envVars.PRIM_TOKEN;
+  }
+  return void 0;
+}
+var API_URL = "https://api.getprimitive.ai";
+function getSiteUrl() {
+  return API_URL;
+}
+async function refreshToken() {
+  if (!existsSync(REFRESH_TOKEN_PATH)) {
+    return void 0;
+  }
+  const refreshTokenValue = readFileSync(REFRESH_TOKEN_PATH, "utf-8").trim();
+  if (!refreshTokenValue) {
+    return void 0;
+  }
+  const siteUrl = getSiteUrl();
+  const response = await fetch(`${siteUrl}/mcp/broker/refresh`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ refresh_token: refreshTokenValue })
+  });
+  if (!response.ok) {
+    return void 0;
+  }
+  const data = await response.json();
+  if (!data.access_token) {
+    return void 0;
+  }
+  writeFileSync(TOKEN_FILE_PATH, data.access_token, { mode: 384 });
+  if (data.refresh_token) {
+    writeFileSync(REFRESH_TOKEN_PATH, data.refresh_token, { mode: 384 });
+  }
+  saveTokenExpiry(data.access_token, data.expires_in);
+  return data.access_token;
+}
+var _cachedToken;
+async function request(method, path, body, options) {
+  const siteUrl = getSiteUrl();
+  const url = `${siteUrl}${path}`;
+  if (!_cachedToken) {
+    _cachedToken = getAuthToken();
+  }
+  if (_cachedToken && isTokenExpiringSoon()) {
+    const newToken = await refreshToken();
+    if (newToken) {
+      _cachedToken = newToken;
+    }
+  }
+  const doFetch = async (token) => {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+    return fetch(url, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal: options?.signal
+    });
+  };
+  let res = await doFetch(_cachedToken);
+  if (res.status === 401) {
+    const newToken = await refreshToken();
+    if (newToken) {
+      _cachedToken = newToken;
+      res = await doFetch(newToken);
+    }
+  }
+  if (!res.ok) {
+    if (res.status === 401) {
+      throw new Error("Authentication expired. Run `prim auth login` to re-authenticate.");
+    }
+    const errorBody = await res.json().catch(() => null);
+    throw new Error(errorBody?.error ?? `HTTP ${res.status}`);
+  }
+  return res.json();
+}
+function getClient() {
+  return {
+    get: (path, options) => request("GET", path, void 0, options),
+    post: (path, body, options) => request("POST", path, body, options),
+    patch: (path, body, options) => request("PATCH", path, body, options),
+    delete: (path, options) => request("DELETE", path, void 0, options)
+  };
+}
+
+export {
+  TOKEN_FILE_PATH,
+  REFRESH_TOKEN_PATH,
+  TOKEN_EXPIRES_PATH,
+  saveTokenExpiry,
+  getTokenExpiresAt,
+  getAuthToken,
+  getSiteUrl,
+  getClient
+};

package/dist/hooks/pre-commit.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import {
+  getClient
+} from "../chunk-3APLWTLB.js";
+
+// src/hooks/pre-commit.ts
+import { execSync } from "child_process";
+function getStagedFiles() {
+  const output = execSync("git diff --cached --name-only", {
+    encoding: "utf-8"
+  });
+  return output.trim().split("\n").filter((f) => f.length > 0);
+}
+function matchPattern(filePath, pattern) {
+  const regexStr = pattern.replaceAll("**", "\xA7GLOBSTAR\xA7").replaceAll("*", "[^/]*").replaceAll("\xA7GLOBSTAR\xA7", ".*");
+  const regex = new RegExp(`^${regexStr}$`);
+  return regex.test(filePath);
+}
+function findAffectedContexts(stagedFiles, specs) {
+  const affected = /* @__PURE__ */ new Map();
+  for (const file of stagedFiles) {
+    for (const spec of specs) {
+      for (const pattern of spec.filePatterns) {
+        if (matchPattern(file, pattern)) {
+          const existing = affected.get(spec._id);
+          if (existing) {
+            existing.matchedFiles.push(file);
+          } else {
+            affected.set(spec._id, {
+              contextId: spec._id,
+              matchedFiles: [file]
+            });
+          }
+          break;
+        }
+      }
+    }
+  }
+  return affected;
+}
+var HOOK_TIMEOUT_MS = 1e4;
+async function main() {
+  const stagedFiles = getStagedFiles();
+  if (stagedFiles.length === 0) {
+    process.exit(0);
+  }
+  const client = getClient();
+  let mappings = [];
+  try {
+    mappings = await client.get("/api/cli/specs/mappings", {
+      signal: AbortSignal.timeout(HOOK_TIMEOUT_MS)
+    });
+  } catch {
+    process.exit(0);
+  }
+  if (mappings.length === 0) {
+    process.exit(0);
+  }
+  const affectedContexts = findAffectedContexts(stagedFiles, mappings);
+  if (affectedContexts.size === 0) {
+    process.exit(0);
+  }
+  console.log(`[prim] ${String(affectedContexts.size)} spec(s) affected by staged changes:`);
+  for (const [contextId] of affectedContexts) {
+    try {
+      const ctx = await client.get(`/api/cli/contexts/${contextId}`, {
+        signal: AbortSignal.timeout(HOOK_TIMEOUT_MS)
+      });
+      if (!ctx._id) {
+        console.log(`  [skip] ${contextId} \u2014 not found`);
+        continue;
+      }
+      if (!ctx.isSpecDocument) {
+        console.log(`  [skip] ${contextId} \u2014 not a spec document`);
+        continue;
+      }
+      await client.post(`/api/cli/contexts/${contextId}/sync`, void 0, {
+        signal: AbortSignal.timeout(HOOK_TIMEOUT_MS)
+      });
+      console.log(`  [synced] ${contextId} \u2014 ${ctx.name ?? "(unnamed)"}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  [error] ${contextId} \u2014 ${message}`);
+    }
+  }
+  process.exit(0);
+}
+main().catch((error) => {
+  console.error("[prim] Pre-commit hook error:", error);
+  process.exit(0);
+});

package/dist/index.js

@@ -0,0 +1,611 @@
+#!/usr/bin/env node
+import {
+  REFRESH_TOKEN_PATH,
+  TOKEN_EXPIRES_PATH,
+  TOKEN_FILE_PATH,
+  getAuthToken,
+  getClient,
+  getSiteUrl,
+  getTokenExpiresAt,
+  saveTokenExpiry
+} from "./chunk-3APLWTLB.js";
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/auth.ts
+import { exec } from "child_process";
+import { createHash, randomBytes } from "crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { createServer } from "http";
+import { platform } from "os";
+import { dirname } from "path";
+var FILE_MODE = 384;
+var LOCALHOST = "127.0.0.1";
+var CALLBACK_PORT = 19876;
+var CALLBACK_TIMEOUT_MS = 12e4;
+var BASE64_PLUS_RE = /\+/g;
+var BASE64_SLASH_RE = /\//g;
+var BASE64_PAD_RE = /=+$/;
+function base64url(buffer) {
+  return buffer.toString("base64").replace(BASE64_PLUS_RE, "-").replace(BASE64_SLASH_RE, "_").replace(BASE64_PAD_RE, "");
+}
+function generatePkce() {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+function openBrowser(url) {
+  const os = platform();
+  const cmd = os === "darwin" ? "open" : os === "win32" ? "start" : "xdg-open";
+  exec(`${cmd} "${url}"`);
+}
+function saveToken(token) {
+  const dir = dirname(TOKEN_FILE_PATH);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(TOKEN_FILE_PATH, token, { mode: FILE_MODE });
+}
+function registerAuthCommands(program2) {
+  const auth = program2.command("auth").description("Manage CLI authentication");
+  auth.command("login").description("Authenticate via browser (WorkOS OAuth)").action(async () => {
+    const siteUrl = getSiteUrl();
+    let config;
+    try {
+      const res = await fetch(`${siteUrl}/mcp/config`);
+      config = await res.json();
+    } catch {
+      console.error("Failed to fetch MCP config. Is the Convex backend running?");
+      process.exit(1);
+    }
+    if (!config.authorization_server || !config.client_id) {
+      console.error("MCP broker is not configured on the server.");
+      process.exit(1);
+    }
+    const { verifier, challenge } = generatePkce();
+    const state = base64url(randomBytes(16));
+    const server = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://${LOCALHOST}`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const returnedState = url.searchParams.get("state");
+      if (returnedState !== state) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end("<h1>State mismatch. Authentication failed.</h1>");
+        server.close();
+        process.exit(1);
+      }
+      if (!code) {
+        const error = url.searchParams.get("error_description") ?? "No authorization code received";
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(`<h1>Authentication failed: ${error}</h1>`);
+        server.close();
+        process.exit(1);
+      }
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end("<h1>Authentication successful!</h1><p>You can close this tab.</p>");
+      exchangeCode(siteUrl, code, verifier, `http://${LOCALHOST}:${port}/callback`).then((token) => {
+        saveToken(token);
+        console.log(`Authenticated! Token saved to ${TOKEN_FILE_PATH}`);
+        server.close();
+        process.exit(0);
+      }).catch((err) => {
+        console.error("Token exchange failed:", err);
+        server.close();
+        process.exit(1);
+      });
+    });
+    const port = await new Promise((resolve2) => {
+      server.listen(CALLBACK_PORT, LOCALHOST, () => {
+        const addr = server.address();
+        resolve2(typeof addr === "object" && addr ? addr.port : 0);
+      });
+    });
+    const redirectUri = `http://${LOCALHOST}:${port}/callback`;
+    const authorizeUrl = config.authorization_endpoint ?? "https://api.workos.com/user_management/authorize";
+    const authUrl = new URL(authorizeUrl);
+    authUrl.searchParams.set("client_id", config.client_id);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("provider", "authkit");
+    authUrl.searchParams.set("scope", config.default_scopes.join(" "));
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    console.log("Opening browser for authentication...");
+    openBrowser(authUrl.toString());
+    console.log(`If the browser doesn't open, visit:
+${authUrl.toString()}
+`);
+    console.log("Waiting for callback...");
+    setTimeout(() => {
+      console.error("Authentication timed out.");
+      server.close();
+      process.exit(1);
+    }, CALLBACK_TIMEOUT_MS);
+  });
+  auth.command("set-token <token>").description("Save a bearer token for authenticated CLI calls").action((token) => {
+    saveToken(token);
+    console.log(`Token saved to ${TOKEN_FILE_PATH}`);
+  });
+  auth.command("clear").description("Remove the saved authentication token").action(async () => {
+    if (existsSync(REFRESH_TOKEN_PATH)) {
+      const refreshTokenValue = readFileSync(REFRESH_TOKEN_PATH, "utf-8").trim();
+      if (refreshTokenValue) {
+        try {
+          const siteUrl = getSiteUrl();
+          const res = await fetch(`${siteUrl}/mcp/broker/revoke`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ refresh_token: refreshTokenValue })
+          });
+          if (res.ok) {
+            console.log("Server token revoked.");
+          } else {
+            console.warn(
+              "Server revocation failed (status %d) \u2014 clearing local files anyway.",
+              res.status
+            );
+          }
+        } catch {
+          console.warn("Could not reach server for revocation \u2014 clearing local files anyway.");
+        }
+      }
+    }
+    let removed = false;
+    for (const filePath of [TOKEN_FILE_PATH, REFRESH_TOKEN_PATH, TOKEN_EXPIRES_PATH]) {
+      if (existsSync(filePath)) {
+        rmSync(filePath);
+        removed = true;
+      }
+    }
+    if (removed) {
+      console.log("Local tokens removed.");
+    } else {
+      console.log("No saved tokens found.");
+    }
+  });
+  auth.command("status").description("Check authentication status and token expiry").action(() => {
+    const token = getAuthToken();
+    if (!token) {
+      console.log("Not authenticated. Run `prim auth login` to authenticate.");
+      process.exit(1);
+    }
+    console.log("Authenticated.");
+    console.log(`Token file: ${TOKEN_FILE_PATH}`);
+    const expiresAt = getTokenExpiresAt();
+    if (expiresAt) {
+      const remaining = expiresAt - Date.now();
+      if (remaining <= 0) {
+        console.log("Access token: expired");
+      } else {
+        const minutes = Math.floor(remaining / 6e4);
+        const seconds = Math.floor(remaining % 6e4 / 1e3);
+        console.log(`Access token expires in: ${minutes}m ${seconds}s`);
+      }
+    } else {
+      console.log("Access token expiry: unknown (no metadata)");
+    }
+    const hasRefresh = existsSync(REFRESH_TOKEN_PATH);
+    console.log(`Refresh token: ${hasRefresh ? "present" : "missing"}`);
+    if (!hasRefresh) {
+      console.log(
+        "Warning: No refresh token. Re-run `prim auth login` when access token expires."
+      );
+    }
+  });
+}
+async function exchangeCode(siteUrl, code, codeVerifier, redirectUri) {
+  const response = await fetch(`${siteUrl}/mcp/broker/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      code,
+      code_verifier: codeVerifier,
+      redirect_uri: redirectUri
+    })
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Token exchange failed (${response.status}): ${body}`);
+  }
+  const data = await response.json();
+  if (!data.access_token) {
+    throw new Error("No access token in response");
+  }
+  if (data.refresh_token) {
+    const refreshPath = TOKEN_FILE_PATH.replace("/token", "/refresh_token");
+    const dir = dirname(refreshPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(refreshPath, data.refresh_token, { mode: FILE_MODE });
+  }
+  saveTokenExpiry(data.access_token, data.expires_in);
+  return data.access_token;
+}
+
+// src/commands/context.ts
+import { readFileSync as readFileSync2 } from "fs";
+function registerContextCommands(program2) {
+  const context = program2.command("context").description("Manage contexts");
+  context.command("list").description("List contexts").option("-s, --scope <scope>", "Filter by scope: task, global, external").option("-t, --task-id <taskId>", "List contexts linked to a specific task").action(async (opts) => {
+    const client = getClient();
+    const params = new URLSearchParams();
+    if (opts.taskId) {
+      params.set("taskId", opts.taskId);
+    }
+    if (opts.scope) {
+      params.set("scope", opts.scope);
+    }
+    const contexts = await client.get(`/api/cli/contexts?${params.toString()}`);
+    printContextList(contexts);
+  });
+  context.command("get <contextId>").description("Get a context by ID").action(async (contextId) => {
+    const client = getClient();
+    const ctx = await client.get(`/api/cli/contexts/${contextId}`);
+    console.log(JSON.stringify(ctx, null, 2));
+  });
+  context.command("create").description("Create a new context").requiredOption("-s, --scope <scope>", "Scope: task, global, external").requiredOption("-n, --name <name>", "Context name").option("-t, --text <text>", "Context text content").option("-f, --file <path>", "Read text content from file").option("--task-id <taskId>", "Link to task(s), comma-separated").option("--spec", "Mark as a spec document").action(
+    async (opts) => {
+      const client = getClient();
+      let text = opts.text;
+      if (opts.file) {
+        text = readFileSync2(opts.file, "utf-8");
+      }
+      const taskIds = opts.taskId ? opts.taskId.split(",").map((id) => id.trim()) : void 0;
+      const result = await client.post("/api/cli/contexts", {
+        scope: opts.scope,
+        name: opts.name,
+        text,
+        taskIds,
+        isSpecDocument: opts.spec ?? false
+      });
+      console.log(`Created context: ${result._id}`);
+    }
+  );
+  context.command("update <contextId>").description("Update a context").option("-n, --name <name>", "New name").option("-t, --text <text>", "New text content").option("-f, --file <path>", "Read text content from file").action(async (contextId, opts) => {
+    const client = getClient();
+    let text = opts.text;
+    if (opts.file) {
+      text = readFileSync2(opts.file, "utf-8");
+    }
+    await client.patch(`/api/cli/contexts/${contextId}`, {
+      name: opts.name,
+      text
+    });
+    console.log(`Updated context: ${contextId}`);
+  });
+  context.command("delete <contextId>").description("Delete a context").action(async (contextId) => {
+    const client = getClient();
+    await client.delete(`/api/cli/contexts/${contextId}`);
+    console.log(`Deleted context: ${contextId}`);
+  });
+  context.command("link <contextId>").description("Link a context to a task").requiredOption("--task <taskId>", "Task ID to link to").action(async (contextId, opts) => {
+    const client = getClient();
+    await client.post(`/api/cli/contexts/${contextId}/link`, {
+      taskId: opts.task
+    });
+    console.log(`Linked context ${contextId} to task ${opts.task}`);
+  });
+  context.command("unlink <contextId>").description("Unlink a context from a task").requiredOption("--task <taskId>", "Task ID to unlink from").action(async (contextId, opts) => {
+    const client = getClient();
+    await client.post(`/api/cli/contexts/${contextId}/unlink`, {
+      taskId: opts.task
+    });
+    console.log(`Unlinked context ${contextId} from task ${opts.task}`);
+  });
+}
+function printContextList(contexts) {
+  if (contexts.length === 0) {
+    console.log("No contexts found.");
+    return;
+  }
+  for (const ctx of contexts) {
+    const scope = ctx.scope ?? "task";
+    const spec = ctx.isSpecDocument ? " [SPEC]" : "";
+    const name = ctx.name ?? ctx.title ?? "(unnamed)";
+    console.log(`${ctx._id}  ${scope.padEnd(8)} ${name}${spec}`);
+  }
+  console.log(`
+${contexts.length} context(s)`);
+}
+
+// src/commands/hooks.ts
+import { execSync } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import { resolve } from "path";
+var HOOK_SCRIPT = `#!/bin/sh
+# prim pre-commit hook \u2014 auto-syncs affected specs on commit
+# Installed by: prim hooks install
+
+# Find the nearest node_modules/.bin with prim, or use npx
+if command -v prim-pre-commit >/dev/null 2>&1; then
+  prim-pre-commit
+elif [ -f "./node_modules/.bin/prim-pre-commit" ]; then
+  ./node_modules/.bin/prim-pre-commit
+else
+  npx --yes @primitive.ai/prim pre-commit-hook 2>/dev/null || true
+fi
+`;
+var PRIM_BLOCK_START = "# >>> prim pre-commit hook >>>";
+var PRIM_BLOCK_END = "# <<< prim pre-commit hook <<<";
+var PRIM_HUSKY_BLOCK = `${PRIM_BLOCK_START}
+if command -v prim-pre-commit >/dev/null 2>&1; then
+  prim-pre-commit
+elif [ -f "./node_modules/.bin/prim-pre-commit" ]; then
+  ./node_modules/.bin/prim-pre-commit
+else
+  npx --yes @primitive.ai/prim pre-commit-hook 2>/dev/null || true
+fi
+${PRIM_BLOCK_END}`;
+function getGitRoot() {
+  return execSync("git rev-parse --show-toplevel", {
+    encoding: "utf-8"
+  }).trim();
+}
+function detectHusky(gitRoot) {
+  const huskyDir = resolve(gitRoot, ".husky");
+  if (!existsSync2(huskyDir)) return false;
+  if (existsSync2(resolve(huskyDir, "_"))) return true;
+  if (existsSync2(resolve(huskyDir, "pre-commit"))) return true;
+  const pkgPath = resolve(gitRoot, "package.json");
+  if (existsSync2(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+      const scripts = pkg.scripts ?? {};
+      if (/husky/i.test(scripts.prepare ?? "") || /husky/i.test(scripts.postinstall ?? "")) {
+        return true;
+      }
+    } catch {
+    }
+  }
+  return false;
+}
+function containsPrimHook(content) {
+  return content.includes("prim-pre-commit");
+}
+async function askConfirmation(question) {
+  if (!process.stdin.isTTY) return false;
+  const { createInterface } = await import("readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question} [y/N] `);
+    const normalized = answer.trim().toLowerCase();
+    return normalized === "y" || normalized === "yes";
+  } finally {
+    rl.close();
+  }
+}
+function installToHusky(gitRoot) {
+  const hookPath = resolve(gitRoot, ".husky", "pre-commit");
+  if (existsSync2(hookPath)) {
+    const existing = readFileSync3(hookPath, "utf-8");
+    if (containsPrimHook(existing)) {
+      console.log("Prim pre-commit hook is already installed in .husky/pre-commit.");
+      return;
+    }
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    writeFileSync2(hookPath, `${existing}${separator}${PRIM_HUSKY_BLOCK}
+`, {
+      mode: 493
+    });
+    console.log("Appended prim hook block to .husky/pre-commit.");
+  } else {
+    writeFileSync2(hookPath, `#!/bin/sh
+
+${PRIM_HUSKY_BLOCK}
+`, {
+      mode: 493
+    });
+    console.log("Created .husky/pre-commit with prim hook block.");
+  }
+}
+function installToDotGit(gitRoot) {
+  const hooksDir = resolve(gitRoot, ".git", "hooks");
+  const hookPath = resolve(hooksDir, "pre-commit");
+  if (!existsSync2(hooksDir)) {
+    mkdirSync2(hooksDir, { recursive: true });
+  }
+  if (existsSync2(hookPath)) {
+    const existing = readFileSync3(hookPath, "utf-8");
+    if (containsPrimHook(existing)) {
+      console.log("Prim pre-commit hook is already installed at .git/hooks/pre-commit.");
+      return;
+    }
+    console.log(`A pre-commit hook already exists at ${hookPath}.`);
+    console.log("To replace it, run: prim hooks uninstall && prim hooks install");
+    return;
+  }
+  writeFileSync2(hookPath, HOOK_SCRIPT, { mode: 493 });
+  console.log(`Installed pre-commit hook at ${hookPath}`);
+}
+function registerHooksCommands(program2) {
+  const hooks = program2.command("hooks").description("Manage git hooks");
+  hooks.command("install").description("Install the prim pre-commit hook").action(async () => {
+    const gitRoot = getGitRoot();
+    if (detectHusky(gitRoot)) {
+      const confirmed = await askConfirmation(
+        "Husky detected. Install prim hook into .husky/pre-commit instead of .git/hooks/pre-commit?"
+      );
+      if (confirmed) {
+        installToHusky(gitRoot);
+        return;
+      }
+      console.log("Falling back to .git/hooks/pre-commit install.");
+    }
+    installToDotGit(gitRoot);
+  });
+  hooks.command("uninstall").description("Remove the prim pre-commit hook").action(() => {
+    const gitRoot = getGitRoot();
+    const hookPath = resolve(gitRoot, ".git", "hooks", "pre-commit");
+    if (!existsSync2(hookPath)) {
+      console.log("No pre-commit hook found.");
+      return;
+    }
+    unlinkSync(hookPath);
+    console.log(`Removed pre-commit hook at ${hookPath}`);
+  });
+}
+
+// src/commands/spec.ts
+import { readFileSync as readFileSync4 } from "fs";
+function registerSpecCommands(program2) {
+  const spec = program2.command("spec").description("Manage spec documents");
+  spec.command("list").description("List spec documents").option("-t, --task-id <taskId>", "List spec for a specific root task").action(async (opts) => {
+    const client = getClient();
+    if (opts.taskId) {
+      const specs = await client.get(`/api/cli/specs?rootTaskId=${opts.taskId}`);
+      if (specs.length === 0) {
+        console.log("No spec document found for this task.");
+        return;
+      }
+      printSpec(specs[0]);
+      return;
+    }
+    const contexts = await client.get("/api/cli/specs");
+    if (contexts.length === 0) {
+      console.log("No spec documents found.");
+      return;
+    }
+    for (const ctx of contexts) {
+      const scope = ctx.scope ?? "task";
+      const review = ctx.specReviewStatus ?? "\u2014";
+      const name = ctx.name ?? "(unnamed)";
+      console.log(`${ctx._id}  ${scope.padEnd(8)} ${String(review).padEnd(10)} ${name}`);
+    }
+    console.log(`
+${contexts.length} spec(s)`);
+  });
+  spec.command("get <contextId>").description("Get a spec document by ID").option("--text-only", "Print only the text content (no metadata)").action(async (contextId, opts) => {
+    const client = getClient();
+    const ctx = await client.get(`/api/cli/contexts/${contextId}`);
+    if (opts.textOnly) {
+      console.log(ctx.text ?? "");
+      return;
+    }
+    printSpec(ctx);
+  });
+  spec.command("update <contextId>").description("Update a spec document's text content").option("-t, --text <text>", "New text content").option("-f, --file <path>", "Read text content from file").option("-n, --name <name>", "New name").action(async (contextId, opts) => {
+    const client = getClient();
+    let text = opts.text;
+    if (opts.file) {
+      text = readFileSync4(opts.file, "utf-8");
+    }
+    if (!(text || opts.name)) {
+      console.error("Provide --text, --file, or --name to update.");
+      process.exit(1);
+    }
+    await client.patch(`/api/cli/contexts/${contextId}`, {
+      name: opts.name,
+      text,
+      skipTiptapLifecycle: !!text
+    });
+    if (text) {
+      await client.post(`/api/cli/contexts/${contextId}/inject`);
+    }
+    console.log(`Updated spec: ${contextId}`);
+  });
+  spec.command("sync <contextId>").description("Trigger spec \u2194 task DAG synchronization").action(async (contextId) => {
+    const client = getClient();
+    const ctx = await client.get(`/api/cli/contexts/${contextId}`);
+    if (!ctx.isSpecDocument) {
+      console.error("Context is not a spec document. Use `prim context` instead.");
+      process.exit(1);
+    }
+    await client.post(`/api/cli/contexts/${contextId}/sync`);
+    console.log(`Triggered sync for spec: ${contextId}`);
+    if (ctx.specRootTaskId) {
+      console.log(`Root task: ${ctx.specRootTaskId}`);
+    }
+  });
+  spec.command("map <contextId>").description("Map file patterns to a spec (used by pre-commit hook to detect affected specs)").requiredOption(
+    "-p, --pattern <patterns...>",
+    'Glob pattern(s) to associate, e.g. "src/auth/**"'
+  ).action(async (contextId, opts) => {
+    const client = getClient();
+    const result = await client.post(`/api/cli/contexts/${contextId}/map`, {
+      patterns: opts.pattern
+    });
+    console.log(`Mapped patterns to spec ${contextId}:`);
+    for (const p of result.filePatterns) {
+      console.log(`  ${p}`);
+    }
+  });
+  spec.command("unmap <contextId>").description("Remove file pattern mappings from a spec (omit --pattern to clear all)").option("-p, --pattern <patterns...>", "Specific pattern(s) to remove (omit to clear all)").action(async (contextId, opts) => {
+    const client = getClient();
+    const result = await client.post(`/api/cli/contexts/${contextId}/unmap`, {
+      patterns: opts.pattern
+    });
+    if (result.filePatterns.length === 0) {
+      console.log(`Cleared all file patterns from spec ${contextId}`);
+    } else {
+      console.log(`Updated patterns for spec ${contextId}:`);
+      for (const p of result.filePatterns) {
+        console.log(`  ${p}`);
+      }
+    }
+  });
+  spec.command("auto-map <contextId>").description("Trigger auto-mapping of file patterns for a spec").action(async (contextId) => {
+    const client = getClient();
+    await client.post(`/api/cli/contexts/${contextId}/auto-map`);
+    console.log(`Auto-mapping triggered for spec: ${contextId}`);
+  });
+}
+function printSpec(ctx) {
+  const name = ctx.name ?? ctx.title ?? "(unnamed)";
+  const review = ctx.specReviewStatus ?? "\u2014";
+  const patterns = ctx.filePatterns;
+  console.log(`ID:              ${ctx._id}`);
+  console.log(`Name:            ${name}`);
+  console.log(`Scope:           ${ctx.scope ?? "task"}`);
+  console.log(`Review Status:   ${review}`);
+  console.log(`Root Task:       ${ctx.specRootTaskId ?? "\u2014"}`);
+  console.log(`Sync Version:    ${ctx.syncVersion ?? 0}`);
+  console.log(`Index Status:    ${ctx.indexStatus ?? "\u2014"}`);
+  console.log(`File Patterns:   ${patterns?.length ? patterns.join(", ") : "\u2014"}`);
+  if (ctx.text) {
+    const text = ctx.text;
+    const preview = text.length > 500 ? `${text.slice(0, 500)}\u2026` : text;
+    console.log(`
+--- Text ---
+${preview}`);
+  }
+}
+
+// src/commands/task.ts
+function registerTaskCommands(program2) {
+  const task = program2.command("task").description("Manage tasks");
+  task.command("create").description("Create a new task").requiredOption("-n, --name <name>", "Task name").option("-d, --description <description>", "Task description").option("--spec <contextId>", "Link an existing spec as this task's spec").action(async (opts) => {
+    const client = getClient();
+    const result = await client.post("/api/cli/tasks", {
+      name: opts.name,
+      description: opts.description,
+      specContextId: opts.spec
+    });
+    console.log(`Created task: ${result._id}`);
+    if (opts.spec) {
+      console.log(`Linked spec: ${opts.spec}`);
+    }
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("prim").description("CLI for managing Primitive specs and contexts").version("0.1.0-alpha.1");
+registerAuthCommands(program);
+registerContextCommands(program);
+registerSpecCommands(program);
+registerTaskCommands(program);
+registerHooksCommands(program);
+process.on("unhandledRejection", (err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(msg);
+  process.exit(1);
+});
+program.parse();

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@primitive.ai/prim",
+  "version": "0.1.0-alpha.1",
+  "description": "CLI for managing Primitive specs, contexts, and git hooks",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/campus-ai/prim.git"
+  },
+  "homepage": "https://github.com/campus-ai/prim#readme",
+  "bugs": {
+    "url": "https://github.com/campus-ai/prim/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "primitive",
+    "prim",
+    "cli",
+    "specs",
+    "contexts",
+    "pre-commit"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "prim": "./dist/index.js",
+    "prim-pre-commit": "./dist/hooks/pre-commit.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^3.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/hooks/pre-commit.ts --format esm --clean",
+    "postbuild": "chmod +x ./dist/index.js ./dist/hooks/pre-commit.js",
+    "dev": "tsup src/index.ts src/hooks/pre-commit.ts --format esm --watch --clean",
+    "clean": "rm -rf dist coverage",
+    "lint": "biome check src/",
+    "format": "biome check --fix src/",
+    "format:check": "biome check src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}