specstocode 0.6.1 → 0.7.1

package/README.md

@@ -8,6 +8,8 @@ Write structured specs, map your user stories, and let your AI coding agent do t
 npm install -g specstocode
 ```
 
+Installs three aliases: **`stc`** (short, daily use), `specstocode`, and `productbuilders`.
+
 Or use without installing:
 
 ```bash
@@ -17,7 +19,7 @@ npx specstocode init
 ## How it works
 
 1. **Plan on the web** — create a project on [specstocode.com](https://specstocode.com), map your user stories, and write Gherkin specs for each one
-2. **Connect your codebase** — run `specstocode init` in your project directory
+2. **Connect your codebase** — run `npx specstocode init` in your project directory
 3. **Build with AI** — your AI coding agent reads `SPECSTOCODE.md` for full product context: stories, acceptance criteria, decisions, and notes
 
 ```
@@ -40,7 +42,7 @@ specstocode.com                        Your project
 ### 1. Log in
 
 ```bash
-specstocode login
+stc login
 ```
 
 Opens your browser to authenticate. One-time per machine.
@@ -50,7 +52,7 @@ Opens your browser to authenticate. One-time per machine.
 Run this inside your project directory after creating a project on [specstocode.com](https://specstocode.com):
 
 ```bash
-specstocode init
+npx specstocode init
 ```
 
 This creates:
@@ -60,7 +62,7 @@ This creates:
 ### 3. Set up your AI tool
 
 ```bash
-specstocode setup
+stc setup
 ```
 
 Configures [Claude Code](https://claude.com/claude-code) or [Cursor](https://cursor.com) with:
@@ -70,10 +72,10 @@ Configures [Claude Code](https://claude.com/claude-code) or [Cursor](https://cur
 ### 4. Build
 
 ```bash
-specstocode next          # What to build next (highest priority story + acceptance criteria)
-specstocode done <id>     # Mark a story complete
-specstocode stories       # List all stories
-specstocode status        # Progress dashboard
+stc next          # What to build next (highest priority story + acceptance criteria)
+stc done <id>     # Mark a story complete
+stc stories       # List all stories
+stc status        # Progress dashboard
 ```
 
 ---
@@ -84,29 +86,29 @@ specstocode status        # Progress dashboard
 
 | Command | Description |
 |---------|-------------|
-| `specstocode login` | Authenticate (opens browser) |
-| `specstocode logout` | Log out |
-| `specstocode init` | Connect project directory to a story map |
-| `specstocode sync` | Refresh `SPECSTOCODE.md` with latest from the web |
-| `specstocode setup` | Configure Claude Code / Cursor |
+| `stc login` | Authenticate (opens browser) |
+| `stc logout` | Log out |
+| `stc init` | Connect project directory to a story map |
+| `stc sync` | Refresh `SPECSTOCODE.md` with latest from the web |
+| `stc setup` | Configure Claude Code / Cursor |
 
 ### Story management
 
 | Command | Description |
 |---------|-------------|
-| `specstocode status` | Progress dashboard |
-| `specstocode stories [-f filter]` | List stories (filter: `todo` / `done` / keyword) |
-| `specstocode next` | Next priority story with acceptance criteria |
-| `specstocode done <id>` | Mark a story done (accepts ID prefix) |
-| `specstocode add <title>` | Create a new story |
-| `specstocode decide [title]` | Log an architectural decision |
-| `specstocode note <id> [text]` | Add implementation notes to a story |
+| `stc status` | Progress dashboard |
+| `stc stories [-f filter]` | List stories (filter: `todo` / `done` / keyword) |
+| `stc next` | Next priority story with acceptance criteria |
+| `stc done <id>` | Mark a story done (accepts ID prefix) |
+| `stc add <title>` | Create a new story |
+| `stc decide [title]` | Log an architectural decision |
+| `stc note <id> [text]` | Add implementation notes to a story |
 
 ### MCP server
 
 | Command | Description |
 |---------|-------------|
-| `specstocode mcp [--mode]` | Start MCP server (`core` / `standard` / `all`) |
+| `stc mcp [--mode]` | Start MCP server (`core` / `standard` / `all`) |
 
 ---
 
@@ -156,6 +158,31 @@ Control token usage with `--mode`:
 
 ---
 
+## AI Features & Pricing
+
+Most commands work on every plan. These three are AI-powered and gated:
+
+| Command | What it does |
+|---------|--------------|
+| `stc complexity` | AI complexity scoring — 1-10 score, risks, suggested effort per story |
+| `stc research` | AI research with your project context — findings, recommendations, next steps |
+| `stc import` | Parse a PRD or spec document into structured user stories |
+
+(The same applies to the matching MCP tools: `analyze_complexity`, `research`, `import_prd`.)
+
+You can unlock them two ways:
+
+1. **Upgrade your plan** — see [specstocode.com/pricing](https://specstocode.com/pricing)
+2. **Bring your own Anthropic key** — works on any plan, AI commands run on your key:
+
+```bash
+stc keys set       # add your Anthropic API key (encrypted at rest)
+stc keys status    # check whether a key is configured
+stc keys remove    # fall back to your plan's platform limits
+```
+
+---
+
 ## Links
 
 - [specstocode.com](https://specstocode.com) — web app

package/dist/chunk-XFT36SZE.js

@@ -0,0 +1,21 @@
+// src/lib/upgrade.ts
+import chalk from "chalk";
+function isPlanGated(status) {
+  return status === 402 || status === 403;
+}
+var UPGRADE_MESSAGE_PLAIN = "This feature requires a Pro plan or your own Anthropic key.\n  Upgrade: https://specstocode.com/pricing\n  Or add your key: stc keys set";
+function printUpgradeMessage() {
+  console.log();
+  console.log(
+    `  ${chalk.yellow("This feature requires a Pro plan or your own Anthropic key.")}`
+  );
+  console.log(`    Upgrade: ${chalk.cyan.underline("https://specstocode.com/pricing")}`);
+  console.log(`    Or add your key: ${chalk.cyan("stc keys set")}`);
+  console.log();
+}
+
+export {
+  isPlanGated,
+  UPGRADE_MESSAGE_PLAIN,
+  printUpgradeMessage
+};

package/dist/{complexity-27JMHAD2.js → complexity-MFKA2RFZ.js}

@@ -1,6 +1,10 @@
 import {
   listStories
 } from "./chunk-QKMZ2SBR.js";
+import {
+  isPlanGated,
+  printUpgradeMessage
+} from "./chunk-XFT36SZE.js";
 import {
   requireConfig
 } from "./chunk-ZLSV4CRF.js";
@@ -36,6 +40,11 @@ async function complexity(storyId) {
       }
     );
     if (!res.ok) {
+      if (isPlanGated(res.status)) {
+        spinner.fail("  Complexity analysis is not available on your plan");
+        printUpgradeMessage();
+        return;
+      }
       spinner.fail("  Complexity analysis failed");
       return;
     }

package/dist/{import-prd-IOV3SEQV.js → import-prd-SJWUNW5M.js}

@@ -2,6 +2,10 @@ import {
   closePrompt,
   confirm
 } from "./chunk-WPVDURTJ.js";
+import {
+  isPlanGated,
+  printUpgradeMessage
+} from "./chunk-XFT36SZE.js";
 import {
   requireConfig
 } from "./chunk-ZLSV4CRF.js";
@@ -47,6 +51,11 @@ async function importPrd(filePath) {
       }
     );
     if (!res.ok) {
+      if (isPlanGated(res.status)) {
+        spinner.fail("  PRD import is not available on your plan");
+        printUpgradeMessage();
+        return;
+      }
       spinner.fail("  Import failed");
       const errText = await res.text();
       console.error(`  ${errText.slice(0, 200)}`);

package/dist/index.js

@@ -27,6 +27,10 @@ import {
   confirm,
   pausePrompt
 } from "./chunk-WPVDURTJ.js";
+import {
+  UPGRADE_MESSAGE_PLAIN,
+  isPlanGated
+} from "./chunk-XFT36SZE.js";
 import {
   hasConfig,
   readConfig,
@@ -81,6 +85,9 @@ async function login() {
         saveAuth({ token: data.token, apiBase: API_BASE });
         console.log("\u2705 Logged in to specstocode!\n");
         console.log("You can now run: stc init");
+        console.log(
+          "Optional: add your Anthropic API key to unlock AI features on any plan \u2014 stc keys set"
+        );
         return;
       }
       if (data.status === "expired") {
@@ -210,7 +217,7 @@ Connecting to "${map.title}"...`);
 }
 async function initWithSyncToken(syncToken) {
   if (!syncToken.startsWith("pb_sync_") && !syncToken.startsWith("sc_sync_")) {
-    console.error("Invalid token. It should start with pb_sync_");
+    console.error("Invalid token. It should start with sc_sync_");
     process.exit(1);
   }
   console.log("\nConnecting to specstocode...");
@@ -1618,7 +1625,12 @@ async function startMcpServer(mode = "all") {
             body: JSON.stringify(body)
           }
         );
-        if (!res.ok) return { content: [{ type: "text", text: "Complexity analysis failed" }] };
+        if (!res.ok) {
+          if (isPlanGated(res.status)) {
+            return { content: [{ type: "text", text: UPGRADE_MESSAGE_PLAIN }] };
+          }
+          return { content: [{ type: "text", text: "Complexity analysis failed" }] };
+        }
         const result = await res.json();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
@@ -1633,7 +1645,12 @@ async function startMcpServer(mode = "all") {
             body: JSON.stringify({ query })
           }
         );
-        if (!res.ok) return { content: [{ type: "text", text: "Research failed" }] };
+        if (!res.ok) {
+          if (isPlanGated(res.status)) {
+            return { content: [{ type: "text", text: UPGRADE_MESSAGE_PLAIN }] };
+          }
+          return { content: [{ type: "text", text: "Research failed" }] };
+        }
         const result = await res.json();
         return { content: [{ type: "text", text: result.research }] };
       }
@@ -1648,7 +1665,12 @@ async function startMcpServer(mode = "all") {
             body: JSON.stringify({ prd, format: args?.format ?? "PRD" })
           }
         );
-        if (!res.ok) return { content: [{ type: "text", text: "PRD import failed" }] };
+        if (!res.ok) {
+          if (isPlanGated(res.status)) {
+            return { content: [{ type: "text", text: UPGRADE_MESSAGE_PLAIN }] };
+          }
+          return { content: [{ type: "text", text: "PRD import failed" }] };
+        }
         const result = await res.json();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
@@ -1706,6 +1728,16 @@ var program = new Command();
 program.name("stc").description("Write specs, map stories, ship with AI \u2014 from your terminal").version(version);
 program.command("login").description("Log in to specstocode (opens browser)").action(() => void login());
 program.command("logout").description("Log out of specstocode").action(() => void logout());
+var keys = program.command("keys").description("Manage your Anthropic API key \u2014 unlock AI features on any plan");
+keys.command("set [key]").description("Save your Anthropic API key (prompts if omitted)").action((key) => {
+  import("./keys-3F2YZCL2.js").then((m) => void m.keysSet(key));
+});
+keys.command("status").description("Show whether a key is set (masked)").action(() => {
+  import("./keys-3F2YZCL2.js").then((m) => void m.keysStatus());
+});
+keys.command("remove").description("Remove your stored key").action(() => {
+  import("./keys-3F2YZCL2.js").then((m) => void m.keysRemove());
+});
 program.command("start").description("Start a new project \u2014 guided flow from problem to pitch").action(() => void start());
 program.command("scope [projectId]").description("Scope a project \u2014 generate blueprint, story map, and mockup").action((id) => void scope(id));
 program.command("setup").description("Configure your AI tool (Claude Code / Cursor) with specstocode agent workflows").action(() => void setup());
@@ -1750,13 +1782,13 @@ program.command("note <storyId> [note]").description("Add implementation notes t
   import("./log-4OBVVVVF.js").then((m) => void m.logNote(storyId, note));
 });
 program.command("complexity [storyId]").description("Analyze story complexity with AI \u2014 scores, risks, effort estimates").action((id) => {
-  import("./complexity-27JMHAD2.js").then((m) => void m.complexity(id));
+  import("./complexity-MFKA2RFZ.js").then((m) => void m.complexity(id));
 });
 program.command("research [query]").description("Research a topic with AI using your project context").action((query) => {
-  import("./research-NRHBPB5Q.js").then((m) => void m.research(query));
+  import("./research-FKISZ323.js").then((m) => void m.research(query));
 });
 program.command("import [file]").description("Import a PRD or spec into your story map as stories").action((file) => {
-  import("./import-prd-IOV3SEQV.js").then((m) => void m.importPrd(file));
+  import("./import-prd-SJWUNW5M.js").then((m) => void m.importPrd(file));
 });
 program.command("mcp").description("Start MCP server for Claude Code / Cursor integration").option("-m, --mode <mode>", "Tool mode: core, standard, all", "all").action((opts) => void startMcpServer(opts.mode));
 program.command("openclaw-register").description("Register this project with OpenClaw MCP \u2014 gives spawned coding agents access to your story map").action(() => void openclawRegister());

package/dist/keys-3F2YZCL2.js

@@ -0,0 +1,90 @@
+import {
+  requireAuth
+} from "./chunk-WJOIFYIA.js";
+import {
+  ask,
+  closePrompt
+} from "./chunk-WPVDURTJ.js";
+
+// src/commands/keys.ts
+var KEYS_DOC_URL = "https://console.anthropic.com/settings/keys";
+async function byokRequest(method, body) {
+  const auth = requireAuth();
+  const res = await fetch(`${auth.apiBase}/api/settings/byok`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${auth.token}`,
+      ...body ? { "Content-Type": "application/json" } : {}
+    },
+    ...body ? { body: JSON.stringify(body) } : {}
+  });
+  const data = await res.json().catch(() => null);
+  return { ok: res.ok, status: res.status, data };
+}
+async function keysSet(key) {
+  let value = key?.trim();
+  if (!value) {
+    console.log("\n  Optionally add your Anthropic API key to unlock AI features on any plan.");
+    console.log("  Your key is encrypted at rest and only used for your AI operations.");
+    console.log(`  Get one at: ${KEYS_DOC_URL}
+`);
+    value = (await ask("  Anthropic API key (sk-ant-...): ")).trim();
+    closePrompt();
+  }
+  if (!value) {
+    console.error("  No key provided. Run `stc keys set` to try again.");
+    process.exit(1);
+  }
+  try {
+    const { ok, data } = await byokRequest("POST", { key: value });
+    if (!ok) {
+      console.error(`
+  \u2717 ${data?.message ?? "Failed to save your key. Try again."}`);
+      process.exit(1);
+    }
+    console.log(`
+  \u2705 Key saved: ${data?.maskedKey}`);
+    console.log("  AI commands (complexity, research, import) now run on your key.\n");
+  } catch {
+    console.error("\n  \u2717 Could not reach specstocode. Check your connection and try again.");
+    process.exit(1);
+  }
+}
+async function keysStatus() {
+  try {
+    const { ok, data } = await byokRequest("GET");
+    if (!ok) {
+      console.error("  \u2717 Failed to fetch key status.");
+      process.exit(1);
+    }
+    if (data?.enabled) {
+      console.log(`
+  Anthropic API key: ${data.maskedKey ?? "(stored but unreadable \u2014 re-run `stc keys set`)"}`);
+      console.log("  AI features run on your key.\n");
+    } else {
+      console.log("\n  No Anthropic API key set.");
+      console.log("  Add one with `stc keys set` to unlock AI features on any plan.\n");
+    }
+  } catch {
+    console.error("  \u2717 Could not reach specstocode. Check your connection and try again.");
+    process.exit(1);
+  }
+}
+async function keysRemove() {
+  try {
+    const { ok } = await byokRequest("DELETE");
+    if (!ok) {
+      console.error("  \u2717 Failed to remove your key.");
+      process.exit(1);
+    }
+    console.log("\n  Key removed. AI features fall back to your plan's platform limits.\n");
+  } catch {
+    console.error("  \u2717 Could not reach specstocode. Check your connection and try again.");
+    process.exit(1);
+  }
+}
+export {
+  keysRemove,
+  keysSet,
+  keysStatus
+};

package/dist/{research-NRHBPB5Q.js → research-FKISZ323.js}

@@ -2,6 +2,10 @@ import {
   ask,
   closePrompt
 } from "./chunk-WPVDURTJ.js";
+import {
+  isPlanGated,
+  printUpgradeMessage
+} from "./chunk-XFT36SZE.js";
 import {
   requireConfig
 } from "./chunk-ZLSV4CRF.js";
@@ -30,6 +34,11 @@ async function research(query) {
       }
     );
     if (!res.ok) {
+      if (isPlanGated(res.status)) {
+        spinner.fail("  Research is not available on your plan");
+        printUpgradeMessage();
+        return;
+      }
       spinner.fail("  Research failed");
       return;
     }

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "specstocode",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "CLI for specstocode.com — connect your codebase to your product story map",
   "bin": {
     "specstocode": "bin/specstocode.js",
-    "productbuilders": "bin/productbuilders.js",
     "stc": "bin/stc.js"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --clean && chmod +x dist/index.js && chmod +x bin/specstocode.js && chmod +x bin/productbuilders.js && chmod +x bin/stc.js",
+    "build": "tsup src/index.ts --format esm --clean && chmod +x dist/index.js && chmod +x bin/specstocode.js && chmod +x bin/stc.js",
     "dev": "tsup src/index.ts --format esm --watch",
     "test": "vitest run",
     "prepublishOnly": "npm run build"

package/bin/productbuilders.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import "../dist/index.js";