@bluestep-systems/bspecs 0.10.0 → 0.11.1

package/README.md

@@ -22,28 +22,22 @@ token or `~/.npmrc` setup — install in one command:
 npm install -g @bluestep-systems/bspecs
 ```
 
-This gives you the `bspecs` command for scaffolding projects. It does **not** put a `b6p` binary on
-your global `PATH` — a dependency's bin is never globally reachable. Instead, every project you
-scaffold declares `@bluestep-systems/b6p-cli` as a devDependency and the skills invoke it via
-`npx b6p`. The scaffolder runs `npm install` in the new project for you (best-effort) to fetch `b6p`;
-if it can't — e.g. you're offline — it prints the command to run by hand. That per-project install
-resolves `@bluestep-systems/b6p-cli` anonymously from public npm, no token needed.
-
-> **Not "zero setup."** Removing the npm token does **not** remove the one-time **BlueStep platform**
-> credential step. Before the `/b6p-pull`, `/b6p-push`, or `/b6p-audit` skills work in a scaffolded
-> project, run `npx b6p auth set` **once per machine** (credentials are stored globally in `~/.b6p`,
-> not per project). This is unrelated to the npm registry and is still required — see the scaffolded
-> project's own README.
-
-> **Migrating from the old GitHub Packages install?** If you previously installed `bspecs` you likely
-> have a line in `~/.npmrc` mapping the scope to GitHub Packages:
->
-> ```ini
-> @bluestep-systems:registry=https://npm.pkg.github.com
-> ```
->
-> Remove it (and the matching `//npm.pkg.github.com/:_authToken=...` line). Left in place it keeps
-> routing `@bluestep-systems/*` to GitHub Packages and the public install will 404.
+This installs the `bspecs` command. The `b6p` CLI is wired into each scaffolded project as a
+devDependency and invoked via `npx b6p` — the scaffolder installs it for you (re-run `npm install` in
+the project if you were offline).
+
+### Set your platform credentials (required, once per machine)
+
+The npm install needs no token, but the `/b6p-pull`, `/b6p-push`, and `/b6p-audit` skills will not
+work until you set your BlueStep platform credentials:
+
+```sh
+npx -p @bluestep-systems/b6p-cli b6p auth set
+```
+
+Run this **once per machine** — credentials are stored globally in `~/.b6p`, not per project. This is
+unrelated to the npm registry. (The `-p` form is required because `b6p` is a project-local
+devDependency; bare `npx b6p` resolves only inside a scaffolded project, where `npx b6p …` works.)
 
 ## Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluestep-systems/bspecs",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Spec-driven BlueStep development with AI agents — scaffolder and project conventions for Claude Code",
   "type": "module",
   "bin": {

package/src/scaffold.js

@@ -78,6 +78,19 @@ export async function scaffold(answers) {
       'Skipped git init. The implementer agent relies on `git diff` to summarize its work — run `git init` in the project before using /spec-execute.'
     );
   }
+
+  log.info(
+    [
+      'Next step — set your BlueStep platform credentials (required, once per machine):',
+      '',
+      '    npx -p @bluestep-systems/b6p-cli b6p auth set',
+      '',
+      'Run that from anywhere (it fetches the CLI on the fly). Inside this project after `npm',
+      'install`, plain `npx b6p ...` also works. Until credentials are set, the /b6p-pull,',
+      '/b6p-push, and /b6p-audit skills cannot run. Credentials are stored globally in ~/.b6p,',
+      'so you only do this once — not per project.',
+    ].join('\n')
+  );
 }
 
 // Detect whether the freshly created project directory sits inside an existing

package/templates/claude/skills/b6p-audit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: b6p-audit
 description: Compare a local component's state against what lives on the BlueStep platform, listing files that differ. Use when the user wants to know if they (or someone else) changed something on the platform side, or before a push to be sure nothing unexpected will be overwritten.
-allowed-tools: Bash(npx b6p *)
+allowed-tools: Bash(npx b6p *) Bash(test -f *)
 ---
 
 # /b6p-audit — Compare local vs. platform
@@ -26,6 +26,20 @@ Always pass `--yes` so b6p does not show interactive prompts that Claude cannot
 
 ## Steps
 
+### 0. Auth preflight (do this first, before any `b6p` call)
+
+`b6p` stores BlueStep platform credentials globally in `~/.b6p/`. On a machine that has never run `npx b6p auth set`, the first `audit` prompts for credentials **interactively** — a prompt you (Claude) cannot answer, so the call hangs silently. `--yes` does **not** save you here: it guards the *confirmation* prompt, not the *missing-credentials* one.
+
+Before running the audit, check that credentials exist:
+
+```
+test -f ~/.b6p/secrets.enc && echo OK
+```
+
+- If it prints `OK` → credentials are set, continue.
+- If it prints nothing (file absent) → STOP. Do **not** run the audit. Tell the user:
+  > `b6p` has no BlueStep platform credentials on this machine yet, so the audit would hang on an interactive prompt I can't answer. Run `npx b6p auth set` once (it stores credentials globally in `~/.b6p/`, so you only do this per machine), then retry `/b6p-audit <component>`.
+
 ### 1. Identify the component
 
 If `$ARGUMENTS` contains a component path (e.g. `U######/Combined Scheduler`), use it. If empty, ask the user which component to audit.

package/templates/claude/skills/b6p-pull/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: b6p-pull
 description: Pull a B6P component from the BlueStep platform into the local workspace using its DAV URL, and scaffold draft/README.md if missing. Use when the user wants to bring a component down for the first time or re-sync after platform edits.
-allowed-tools: Bash(npx b6p *)
+allowed-tools: Bash(npx b6p *) Bash(test -f *)
 ---
 
 # /b6p-pull — Pull a component from BlueStep
@@ -30,6 +30,20 @@ If `node_modules` is missing, the user has not run `npm install` yet (see the "I
 
 ## Steps
 
+### 0. Auth preflight (do this first, before any `b6p` call)
+
+`b6p` stores BlueStep platform credentials globally in `~/.b6p/`. On a machine that has never run `npx b6p auth set`, the first `pull` prompts for credentials **interactively** — a prompt you (Claude) cannot answer, so the call hangs silently. `--yes` does **not** save you here: it guards the *confirmation* prompt, not the *missing-credentials* one.
+
+Before running the pull, check that credentials exist:
+
+```
+test -f ~/.b6p/secrets.enc && echo OK
+```
+
+- If it prints `OK` → credentials are set, continue.
+- If it prints nothing (file absent) → STOP. Do **not** run the pull. Tell the user:
+  > `b6p` has no BlueStep platform credentials on this machine yet, so the pull would hang on an interactive prompt I can't answer. Run `npx b6p auth set` once (it stores credentials globally in `~/.b6p/`, so you only do this per machine), then retry `/b6p-pull <DAV URL>`.
+
 ### 1. Get the DAV URL
 
 - If `$ARGUMENTS` looks like a URL (starts with `http://` or `https://`), use it.

package/templates/claude/skills/b6p-push/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: b6p-push
 description: Push local changes for a component back to the BlueStep platform. Use when the user is ready to deploy local edits.
-allowed-tools: Bash(npx b6p *) Bash(git*)
+allowed-tools: Bash(npx b6p *) Bash(git*) Bash(test -f *)
 ---
 
 # /b6p-push — Push a component to BlueStep
@@ -22,6 +22,20 @@ Any file inside the component works as the `--file` argument; the CLI walks up t
 
 ## Steps
 
+### 0. Auth preflight (do this first, before any `b6p` call)
+
+`b6p` stores BlueStep platform credentials globally in `~/.b6p/`. On a machine that has never run `npx b6p auth set`, the first `push` prompts for credentials **interactively** — a prompt you (Claude) cannot answer, so the call hangs silently. `--yes` does **not** save you here: it guards the *confirmation* prompt, not the *missing-credentials* one.
+
+Before running the push, check that credentials exist:
+
+```
+test -f ~/.b6p/secrets.enc && echo OK
+```
+
+- If it prints `OK` → credentials are set, continue.
+- If it prints nothing (file absent) → STOP. Do **not** run the push. Tell the user:
+  > `b6p` has no BlueStep platform credentials on this machine yet, so the push would hang on an interactive prompt I can't answer. Run `npx b6p auth set` once (it stores credentials globally in `~/.b6p/`, so you only do this per machine), then retry `/b6p-push <component>`.
+
 ### 1. Identify the component
 
 If `$ARGUMENTS` contains a component path (relative to the project root), use it. Otherwise ask the user which component to push.

package/templates/root/CLAUDE.md.template

@@ -123,6 +123,8 @@ The skills above wrap these commands. You can run them directly if you need to,
 
 `b6p` ships as a devDependency of this project (`@bluestep-systems/b6p-cli`). Invoke it with `npx b6p`, which resolves `node_modules/.bin/b6p` cross-platform — no global install, no shell or PATH detection. Run `npm install` once if `node_modules` is missing.
 
+**One-time platform auth (required before any pull/push/audit).** `b6p` needs BlueStep platform credentials, stored globally in `~/.b6p/` (once per machine — not per project). On a machine that has never run it, the **first** `b6p` command prompts for credentials interactively, which hangs Claude (`--yes` does not cover the credentials prompt). Before the first sync command, verify credentials exist with `test -f ~/.b6p/secrets.enc`; if absent, run `npx b6p auth set` once, then retry. The `/b6p-*` skills do this preflight automatically.
+
 - **Pull (DAV URL required):** `npx b6p --yes pull "<DAV URL>"`. The DAV URL is copied from the component's page in the BlueStep platform UI — `b6p pull` does not accept display names. First pull creates the `U######/` folder and the component skeleton.
 - **Push (file-driven):** `npx b6p --yes push --file "U######/<Component>/draft/scripts/app.ts"`. `--file` lets the CLI derive the destination from local metadata.
 - **Audit (read-only):** `npx b6p --yes --json audit --file "U######/<Component>/draft/scripts/app.ts"`. Lists files that differ between local and platform.