@primitive.ai/prim 0.1.0-alpha.11 → 0.1.0-alpha.13

package/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: prim
+description: Use the prim CLI for managing Primitive specs, contexts, projects, and pre-commit hooks. TRIGGER when the user mentions Primitive, prim, "specs" (in the Primitive sense), or "contexts" (in the Primitive sense); when the repo's package.json depends on @primitive.ai/prim; when the user asks to sync, map, update, or auto-map a spec; when configuring Primitive pre-commit hooks. SKIP when "spec" means test specs (vitest, jest, rspec), when "context" means React context or LLM context window, or for unrelated CLIs.
+---
+
+# Working with the prim CLI
+
+`prim` is the official CLI for [Primitive](https://app.getprimitive.ai). Use it -- don't reach for shell or curl.
+
+## Mental model
+
+A **spec** captures intent for execution -- it defines what should be done, usually so other agents (or humans) can act on it. A **context** is everything else: supporting material that informs but doesn't define the work -- design docs, references, prior art, shared documentation, examples. When deciding which to create, ask: does this say *what to do*, or does it *inform* whoever's doing it? A project has at most one spec but can link many contexts.
+
+In Primitive, a markdown spec is associated with a **project**. The spec is the source of truth: `npx --yes @primitive.ai/prim spec sync` parses the spec, diffs it against the project, and **applies the diff** -- adding, updating, or **archiving** items in the project to match. Items removed from a spec are soft-archived (recoverable via the dashboard), not deleted -- but they leave the active view, so flag the user before large spec rewrites on projects with work in flight.
+
+A **spec is a kind of context** -- same IDs, same storage. The `npx --yes @primitive.ai/prim spec ...` commands are a focused view onto specs; `npx --yes @primitive.ai/prim context get <id>` works on a spec ID and vice versa. For structured metadata on a spec (review status, root project, sync version, scope, file patterns), use `npx --yes @primitive.ai/prim context get <specId>` -- it returns JSON.
+
+`npx --yes @primitive.ai/prim spec list` returns only spec-type contexts. `npx --yes @primitive.ai/prim context list` returns all contexts regardless of type.
+
+## Auth
+
+Run `npx --yes @primitive.ai/prim auth status` first. It exits **0 if authenticated, 1 if not** -- branch on the exit code, don't parse the message.
+
+Three ways to authenticate, in priority order:
+
+1. **`PRIM_TOKEN` environment variable** -- preferred for agents and CI. Set it before invoking prim and you're done; no interactive flow, no token files.
+2. **`npx --yes @primitive.ai/prim auth set-token <token>`** -- saves a bearer token to `~/.config/prim/token`. Use when the user has a long-lived token in hand.
+3. **`npx --yes @primitive.ai/prim auth login`** -- opens a browser via WorkOS OAuth. **An agent cannot complete this.** If `auth status` exits non-zero and `PRIM_TOKEN` is unset, **stop and ask the user** to run `npx --yes @primitive.ai/prim auth login` themselves.
+
+The CLI auto-refreshes expired tokens. On unrecoverable expiry it throws `Authentication expired. Run prim auth login to re-authenticate.` -- relay it.
+
+## Ground rules
+
+1. Don't guess IDs. Discover them with `npx --yes @primitive.ai/prim spec list`, `npx --yes @primitive.ai/prim spec list --project-id <pid>`, or `npx --yes @primitive.ai/prim context list`.
+2. Every command accepts `--help`. When unsure of flags, run `npx --yes @primitive.ai/prim <cmd> --help` rather than guessing.
+3. The CLI prints API errors as one-liners to stderr and exits non-zero. Treat any non-zero exit as actionable. If a command fails with an unrecognized error, re-run with `--help` to check your flags. If auth-related, re-check `auth status`.
+
+## Common workflows
+
+### Read a spec's current text (do this before any partial edit)
+```
+npx --yes @primitive.ai/prim spec get <id> --text-only > spec.md
+```
+`npx --yes @primitive.ai/prim spec update <id> --file <path>` replaces the entire body. Fetch first if you're only changing part of it.
+
+### Update a spec from a local file and apply to the project
+```
+npx --yes @primitive.ai/prim spec list --project-id <pid>     # find the spec for a project
+npx --yes @primitive.ai/prim spec update <id> --file spec.md  # replaces spec body
+npx --yes @primitive.ai/prim spec sync <id>                   # required -- update doesn't apply changes to the project
+```
+`npx --yes @primitive.ai/prim spec sync` is **async**: it returns immediately with `Triggered sync for spec`, then applies in the background. The project isn't updated when the command returns -- surface that to the user.
+
+Auto-map runs automatically on the server after every `spec update`. Call `npx --yes @primitive.ai/prim spec auto-map <id>` explicitly only to re-run mapping without changing the spec text.
+
+### Map files to a spec (so pre-commit auto-syncs all affected specs)
+```
+npx --yes @primitive.ai/prim spec map <id> -p "src/auth/**" "src/foo/**"   # multiple patterns at once
+npx --yes @primitive.ai/prim spec unmap <id> -p "src/auth/**"              # remove one
+npx --yes @primitive.ai/prim spec unmap <id>                               # clear all manual patterns
+```
+
+### Create or link a context
+```
+npx --yes @primitive.ai/prim context create -s project -n "<name>" --file <path> --project-id <pid>   # add --spec to make it a spec
+npx --yes @primitive.ai/prim context create -s global -n "<name>" --text "..."                        # filed in the global context pane, not linked to a specific project
+npx --yes @primitive.ai/prim context link <ctxId> --project <projectId>                                # works on any scope
+npx --yes @primitive.ai/prim context unlink <ctxId> --project <projectId>                              # remove a link
+```
+
+### Update or delete a context
+```
+npx --yes @primitive.ai/prim context update <id> -n "<new name>"           # rename
+npx --yes @primitive.ai/prim context update <id> --file <path>             # replace body
+npx --yes @primitive.ai/prim context delete <id>                           # permanent -- confirm with the user first
+```
+
+### Create a project (optionally with a linked spec)
+```
+npx --yes @primitive.ai/prim project create -n "<name>" -d "<desc>"
+npx --yes @primitive.ai/prim project create -n "<name>" --spec <contextId>     # value is a context ID
+```
+
+### Install the pre-commit hook
+```
+npx --yes @primitive.ai/prim hooks install     # auto-detects Husky and prompts
+npx --yes @primitive.ai/prim hooks uninstall
+```
+**Note:** `hooks uninstall` only removes `.git/hooks/pre-commit`. If the hook was installed into `.husky/pre-commit`, you must remove the prim block from that file manually.
+
+## How the pre-commit hook behaves
+
+`npx --yes @primitive.ai/prim hooks install` adds a hook that, on every commit:
+
+1. Fetches the org's spec-to-file-pattern mappings.
+2. Glob-matches staged files against each spec's patterns (`*` and `**` supported).
+3. For each affected spec, sends `git diff --cached` to `/api/cli/contexts/:id/sync-diff`. The backend runs an **LLM over (current spec + diff)** to produce edits, updates the spec text, then applies the new spec to the project.
+4. Prints `[synced] <id> -- <name>` or `[skip] <id> -- <reason>` per affected spec to stdout, and `[error]` lines to stderr.
+
+What that means:
+
+- **The hook is not `npx --yes @primitive.ai/prim spec sync`.** `npx --yes @primitive.ai/prim spec sync` re-applies the *existing* spec to the project. The hook calls `sync-diff` -- an LLM updates the spec from the code change, then applies the new spec to the project. The casual "just commit and the hook will sync" is ambiguous; when explaining to the user, specify which operation you mean.
+- **The hook never blocks the commit.** Failures (auth, network, backend) print `[error]` to stderr but exit 0, so a successful `git commit` doesn't prove the spec changed. Check the hook's `[synced]` / `[error]` / `[skip]` output, or verify with `npx --yes @primitive.ai/prim spec get <id>`.
+- **Diffs over 256 KiB are truncated.** The hook logs `(truncated: X KiB -> Y KiB analyzed)`. The LLM only sees the first 256 KiB of the diff.
+- **To suppress the hook for one commit** (e.g., when intentionally desyncing code from spec, or when committing unrelated changes), use `git commit --no-verify`.
+
+## Output formats
+
+| Command | Output | Where the ID is |
+|---|---|---|
+| `npx --yes @primitive.ai/prim context create` | `Created context: <id>` | Match `^Created context: (\S+)` |
+| `npx --yes @primitive.ai/prim project create` | `Created project: <id>` | Match `^Created project: (\S+)` |
+| `npx --yes @primitive.ai/prim spec update` | `Updated spec: <id>` | Match `^Updated spec: (\S+)` |
+| `npx --yes @primitive.ai/prim spec sync` | `Triggered sync for spec: <id>` | Match `^Triggered sync for spec: (\S+)` |
+| `npx --yes @primitive.ai/prim context list`, `npx --yes @primitive.ai/prim spec list` | Table with trailing count line | First token of each row (skip the final `N spec(s)` / `N context(s)` summary line) |
+| `npx --yes @primitive.ai/prim spec list --project-id <pid>` | Single-spec block (key:value) | `ID:` line |
+| `npx --yes @primitive.ai/prim context get <id>` | Pretty-printed JSON | `._id` field |
+| `npx --yes @primitive.ai/prim spec get <id>` | Human-readable key:value block | `ID:` line |
+| `npx --yes @primitive.ai/prim spec get <id> --text-only` | Raw spec markdown, nothing else | n/a |
+
+## Pitfalls
+
+- **`npx --yes @primitive.ai/prim spec sync` archives anything dropped from the spec.** Removed content is archived (recoverable), not deleted.
+- **`npx --yes @primitive.ai/prim spec update` doesn't apply changes to the project.** Always follow with `npx --yes @primitive.ai/prim spec sync <id>`.
+- **`npx --yes @primitive.ai/prim spec update --file` replaces the whole body.** Fetch with `npx --yes @primitive.ai/prim spec get <id> --text-only` before any partial edit.
+- **`npx --yes @primitive.ai/prim spec sync` rejects non-spec contexts** with "Context is not a spec document. Use `prim context` instead." Use `npx --yes @primitive.ai/prim spec list` to find spec IDs.
+- **`npx --yes @primitive.ai/prim context delete` is permanent.** Confirm with the user before deleting.
+- **Scope is set at creation.** To change it, delete and recreate the context.
+
+## After each task
+
+Report the names and IDs you touched (spec, context, project) so the user can verify in the dashboard. If you ran `npx --yes @primitive.ai/prim spec sync`, remind the user it's async -- the project settles in the background.

package/dist/index.js

@@ -11,10 +11,11 @@ import {
 } from "./chunk-3APLWTLB.js";
 
 // src/index.ts
-import { readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
-import { fileURLToPath } from "url";
+import { readFileSync as readFileSync6 } from "fs";
+import { dirname as dirname3, resolve as resolve3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
+import updateNotifier from "update-notifier";
 
 // src/commands/auth.ts
 import { exec } from "child_process";
@@ -103,10 +104,10 @@ function registerAuthCommands(program2) {
         process.exit(1);
       });
     });
-    const port = await new Promise((resolve3) => {
+    const port = await new Promise((resolve4) => {
       server.listen(CALLBACK_PORT, LOCALHOST, () => {
         const addr = server.address();
-        resolve3(typeof addr === "object" && addr ? addr.port : 0);
+        resolve4(typeof addr === "object" && addr ? addr.port : 0);
       });
     });
     const redirectUri = `http://${LOCALHOST}:${port}/callback`;
@@ -473,8 +474,156 @@ function registerProjectCommands(program2) {
   });
 }
 
+// src/commands/skill.ts
+import {
+  closeSync,
+  existsSync as existsSync3,
+  fsyncSync,
+  openSync,
+  readFileSync as readFileSync4,
+  renameSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+import { createPatch } from "diff";
+var __dirname = dirname2(fileURLToPath(import.meta.url));
+var SKILL_BEGIN = "<!-- BEGIN PRIM SKILL v1 -->";
+var SKILL_END = "<!-- END PRIM SKILL v1 -->";
+var TARGET_CANDIDATES = [
+  "CLAUDE.md",
+  ".cursor/rules",
+  ".windsurfrules",
+  ".github/instructions/primitive.md"
+];
+var DEFAULT_TARGET = "CLAUDE.md";
+function loadSkill() {
+  let dir = __dirname;
+  while (dir !== dirname2(dir)) {
+    const p = resolve2(dir, "SKILL.md");
+    if (existsSync3(p)) return readFileSync4(p, "utf-8");
+    dir = dirname2(dir);
+  }
+  throw new Error("SKILL.md not found in package");
+}
+function detectTargets(cwd) {
+  return TARGET_CANDIDATES.filter((p) => existsSync3(resolve2(cwd, p)));
+}
+function detectNewline(content) {
+  return content.includes("\r\n") ? "\r\n" : "\n";
+}
+function composeBlock(skill, eol) {
+  const body = skill.replace(/\r?\n/g, eol);
+  return `${SKILL_BEGIN}${eol}${body}${eol}${SKILL_END}`;
+}
+function applyBlock(existing, block, eol) {
+  const b = existing.indexOf(SKILL_BEGIN);
+  const e = existing.indexOf(SKILL_END);
+  if (b !== -1 && e !== -1) {
+    return existing.slice(0, b) + block + existing.slice(e + SKILL_END.length);
+  }
+  if (existing.length === 0) return `${block}${eol}`;
+  const sep = existing.endsWith(eol) ? "" : eol;
+  return `${existing}${sep}${block}${eol}`;
+}
+function removeBlock(existing) {
+  const b = existing.indexOf(SKILL_BEGIN);
+  const e = existing.indexOf(SKILL_END);
+  if (b === -1 || e === -1) return null;
+  const out = existing.slice(0, b) + existing.slice(e + SKILL_END.length);
+  return out.replace(/(\r?\n){2,}$/, "$1");
+}
+function atomicWrite(target, content) {
+  const tmp = `${target}.tmp`;
+  writeFileSync3(tmp, content);
+  const fd = openSync(tmp, "r+");
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, target);
+}
+function resolveTarget(cwd, override) {
+  if (override) return resolve2(cwd, override);
+  const matches = detectTargets(cwd);
+  if (matches.length === 0) return resolve2(cwd, DEFAULT_TARGET);
+  if (matches.length === 1) return resolve2(cwd, matches[0]);
+  console.error("Multiple rules files detected. Use --target to disambiguate:");
+  for (const m of matches) console.error(`  ${m}`);
+  return null;
+}
+function runInstall(cwd, opts) {
+  const target = resolveTarget(cwd, opts.target);
+  if (target === null) return 1;
+  const existing = existsSync3(target) ? readFileSync4(target, "utf-8") : "";
+  const eol = existing ? detectNewline(existing) : "\n";
+  const block = composeBlock(loadSkill(), eol);
+  const next = applyBlock(existing, block, eol);
+  if (next === existing) {
+    console.log("No changes \u2014 skill block already up to date.");
+    return 0;
+  }
+  if (opts.dryRun) {
+    process.stdout.write(createPatch(target, existing, next, "current", "proposed"));
+    return 0;
+  }
+  atomicWrite(target, next);
+  console.log(`Wrote ${Buffer.byteLength(next)} bytes to ${target}`);
+  return 0;
+}
+function runUninstall(cwd, opts) {
+  const target = resolveTarget(cwd, opts.target);
+  if (target === null) return 1;
+  if (!existsSync3(target)) {
+    console.log(`Skill block not present at ${target}`);
+    return 0;
+  }
+  const existing = readFileSync4(target, "utf-8");
+  const next = removeBlock(existing);
+  if (next === null) {
+    console.log(`Skill block not present at ${target}`);
+    return 0;
+  }
+  atomicWrite(target, next);
+  console.log(`Removed skill block from ${target}`);
+  return 0;
+}
+function runStatus(cwd, opts) {
+  const target = resolveTarget(cwd, opts.target);
+  if (target === null) return 1;
+  if (!existsSync3(target)) {
+    console.log(`No rules file at ${target}`);
+    return 1;
+  }
+  const content = readFileSync4(target, "utf-8");
+  if (content.includes(SKILL_BEGIN) && content.includes(SKILL_END)) {
+    console.log(`PRIM SKILL v1 installed at ${target}`);
+    return 0;
+  }
+  console.log(`No PRIM SKILL block at ${target}`);
+  return 1;
+}
+function registerSkillCommands(program2) {
+  const skill = program2.command("skill").description("Manage the prim skill in your project rules file");
+  skill.command("install").description("Install the prim skill block into your project rules file").option("--target <path>", "Path to the rules file (overrides auto-detection)").option("--dry-run", "Print a unified diff without writing").action((opts) => {
+    try {
+      process.exit(runInstall(process.cwd(), opts));
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(2);
+    }
+  });
+  skill.command("uninstall").description("Remove the prim skill block from your project rules file").option("--target <path>", "Path to the rules file (overrides auto-detection)").action((opts) => {
+    process.exit(runUninstall(process.cwd(), opts));
+  });
+  skill.command("status").description("Report whether the prim skill block is installed").option("--target <path>", "Path to the rules file (overrides auto-detection)").action((opts) => {
+    process.exit(runStatus(process.cwd(), opts));
+  });
+}
+
 // src/commands/spec.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 function registerSpecCommands(program2) {
   const spec = program2.command("spec").description("Manage spec documents");
   spec.command("list").description("List spec documents").option("-t, --project-id <projectId>", "List spec for a specific root project").action(async (opts) => {
@@ -515,7 +664,7 @@ ${contexts.length} spec(s)`);
     const client = getClient();
     let text = opts.text;
     if (opts.file) {
-      text = readFileSync4(opts.file, "utf-8");
+      text = readFileSync5(opts.file, "utf-8");
     }
     if (!(text || opts.name)) {
       console.error("Provide --text, --file, or --name to update.");
@@ -599,8 +748,9 @@ ${preview}`);
 }
 
 // src/index.ts
-var __dirname = dirname2(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync5(resolve2(__dirname, "../package.json"), "utf-8"));
+var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
+var pkg = JSON.parse(readFileSync6(resolve3(__dirname2, "../package.json"), "utf-8"));
+updateNotifier({ pkg }).notify();
 var program = new Command();
 program.name("prim").description("CLI for managing Primitive specs and contexts").version(pkg.version);
 registerAuthCommands(program);
@@ -608,6 +758,7 @@ registerContextCommands(program);
 registerSpecCommands(program);
 registerProjectCommands(program);
 registerHooksCommands(program);
+registerSkillCommands(program);
 process.on("unhandledRejection", (err) => {
   const msg = err instanceof Error ? err.message : String(err);
   console.error(msg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitive.ai/prim",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "description": "CLI for managing Primitive specs, contexts, and git hooks",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,8 @@
   "files": [
     "dist",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "SKILL.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/hooks/pre-commit.ts --format esm --clean",
@@ -51,11 +52,15 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "diff": "^5.2.0",
+    "update-notifier": "^7.3.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
+    "@types/diff": "^5.2.0",
     "@types/node": "^25.5.0",
+    "@types/update-notifier": "^6.0.8",
     "@vitest/coverage-v8": "^3.1.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",