@bluestep-systems/bspecs 0.11.1 → 0.12.0

package/README.md

@@ -46,11 +46,21 @@ devDependency; bare `npx b6p` resolves only inside a scaffolded project, where `
 From the parent directory where you want to create the project:
 
 ```sh
-bspecs
+bspecs new
 ```
 
 The interactive wizard asks for the project name, client, and an optional description. When done, it generates the project directory with the full structure and (unless you opt out) runs `git init`.
 
+### Add the tooling to an existing project
+
+Already have a project and just want the Claude Code tooling? From inside that project's directory:
+
+```sh
+bspecs init
+```
+
+`bspecs init` installs the full tooling tree **in place** and is strictly non-destructive: any file that already exists is left untouched. The one exception is `package.json` — the `@bluestep-systems/b6p-cli` devDependency (and the `b6p` script) are merged in, preserving everything else. It then writes the `bspecs.lock` so `bspecs sync` works going forward. At the end it prints a report of every file it skipped because the name already existed; to install the `bspecs` version of any of them, rename or move your local copy and run `bspecs init` again. The client-name prompt is optional — press Enter to default to `BlueStep Client`. (No `git init` — an existing project owns its own VCS.)
+
 ### Keep a project up to date
 
 When a new version of `bspecs` is published with improvements to skills, hooks, or instructions, update your global install and sync the project:

package/cli.js

@@ -3,8 +3,8 @@ import { intro, outro, cancel, log } from '@clack/prompts';
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { runPrompts } from './src/prompts.js';
-import { scaffold } from './src/scaffold.js';
+import { runPrompts, runInitPrompts } from './src/prompts.js';
+import { scaffold, init } from './src/scaffold.js';
 import { sync } from './src/sync.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -12,17 +12,22 @@ const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'));
 
 const HELP = `bspecs — spec-driven BlueStep development with AI agents
 
-Scaffold a new BlueStep project with Claude Code skills, hooks, and
+Scaffold and maintain BlueStep projects with Claude Code skills, hooks, and
 project conventions for spec-driven development.
 
 Usage:
-  bspecs           Run the interactive scaffolder in the current directory.
+  bspecs new       Scaffold a brand-new project in a new subdirectory.
+  bspecs init      Install the tooling into the current directory (non-destructive).
   bspecs sync      Sync infrastructure files in the current project.
   bspecs -v        Print version.
   bspecs -h        Print this help.
 
 Options for bspecs sync:
   --silent         Suppress all output (used by the SessionStart hook).
+
+bspecs init never overwrites an existing file (package.json has the b6p-cli
+devDependency merged in) and reports what it skipped so you can rename/move and
+re-run. Its client-name prompt is optional — press Enter for "BlueStep Client".
 `;
 
 function parseArgs(argv) {
@@ -31,7 +36,9 @@ function parseArgs(argv) {
   if (flags.has('-v') || flags.has('--version')) return { mode: 'version' };
   if (flags.has('-h') || flags.has('--help'))    return { mode: 'help' };
   if (positional[0] === 'sync') return { mode: 'sync', silent: flags.has('--silent') };
-  return { mode: 'interactive' };
+  if (positional[0] === 'new')  return { mode: 'new' };
+  if (positional[0] === 'init') return { mode: 'init' };
+  return { mode: 'help' };
 }
 
 async function main() {
@@ -52,6 +59,25 @@ async function main() {
 
   intro('bspecs — spec-driven BlueStep development with AI agents');
 
+  if (mode === 'init') {
+    const answers = await runInitPrompts();
+    if (!answers) {
+      cancel('Cancelled.');
+      process.exit(0);
+    }
+
+    await init(answers);
+
+    outro(
+      `bspecs tooling installed in ${process.cwd()}\n` +
+      `  Next steps:\n` +
+      `    npm install   (if it did not run automatically)\n` +
+      `    npx -p @bluestep-systems/b6p-cli b6p auth set   (platform credentials, once per machine)`
+    );
+    return;
+  }
+
+  // mode === 'new'
   const answers = await runPrompts();
   if (!answers) {
     cancel('Cancelled.');

package/package.json

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

package/src/prompts.js

@@ -1,6 +1,6 @@
 import { text, confirm, isCancel, cancel } from '@clack/prompts';
 import { existsSync } from 'fs';
-import { join } from 'path';
+import { basename, join } from 'path';
 
 function titleCase(s) {
   return s
@@ -72,3 +72,39 @@ export async function runPrompts() {
     initGit,
   };
 }
+
+// Prompts for `bspecs init` (install into the current directory). No folder-name
+// question — the project name defaults to the cwd basename — and no git prompt.
+// Client name is optional, falling back to 'BlueStep Client' on an empty Enter.
+export async function runInitPrompts() {
+  const cwd = process.cwd();
+
+  const clientName = bail(
+    await text({
+      message: 'Client name (optional — press Enter for "BlueStep Client")',
+      placeholder: 'BlueStep Client',
+    })
+  );
+
+  const projectDescription = bail(
+    await text({
+      message: 'Project description (optional — gives Claude project context)',
+      placeholder: 'What does this project do? Press Enter to skip.',
+    })
+  );
+
+  const proceed = bail(
+    await confirm({
+      message: `Install bspecs tooling into ${cwd}?`,
+      initialValue: true,
+    })
+  );
+
+  if (!proceed) return null;
+
+  return {
+    projectName: basename(cwd),
+    clientName: (clientName && clientName.trim()) || 'BlueStep Client',
+    projectDescription: projectDescription || '',
+  };
+}

package/src/scaffold.js

@@ -1,9 +1,9 @@
 import { execSync } from 'child_process';
-import { join, dirname } from 'path';
+import { join, dirname, basename, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { log } from '@clack/prompts';
-import { ensureDir, copyTemplateTree, applyTemplate, TEMPLATES_DIR, sha256 } from './utils.js';
+import { ensureDir, copyTemplateTree, applyTemplate, writeFile, mergePackageJson, TEMPLATES_DIR, sha256 } from './utils.js';
 import { SYNC_TARGETS } from './sync.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -79,6 +79,11 @@ export async function scaffold(answers) {
     );
   }
 
+  printAuthReminder();
+}
+
+// One-time-per-machine BlueStep credential reminder, shared by `scaffold` and `init`.
+function printAuthReminder() {
   log.info(
     [
       'Next step — set your BlueStep platform credentials (required, once per machine):',
@@ -93,6 +98,102 @@ export async function scaffold(answers) {
   );
 }
 
+// `bspecs init`: install the template tree into the current directory without
+// overwriting anything that already exists (package.json is the one exception —
+// its devDependencies are merged). Writes the lock so `bspecs sync` works after.
+export async function init(answers) {
+  const projectDir = process.cwd();
+
+  const vars = {
+    PROJECT_NAME: answers.projectName,
+    CLIENT_NAME: answers.clientName,
+    PROJECT_DESCRIPTION: answers.projectDescription,
+    SCAFFOLD_DATE: new Date().toISOString().split('T')[0],
+  };
+
+  const collect = { written: [], skipped: [] };
+
+  copyTemplateTree('root', projectDir, vars, {
+    skipExisting: true,
+    collect,
+    exclude: ['package.json.template'],
+  });
+  copyTemplateTree('claude', join(projectDir, '.claude'), vars, {
+    skipExisting: true,
+    collect,
+    makeExecutable: true,
+  });
+  copyTemplateTree('module', join(projectDir, '.claude', 'templates'), vars, {
+    skipExisting: true,
+    collect,
+  });
+
+  const pkgStatus = handlePackageJson(projectDir, vars, collect);
+
+  writeBspecsLock(projectDir, vars);
+
+  log.success('Tooling installed.');
+
+  checkPrettierOnPath();
+  installDependencies(basename(projectDir), projectDir);
+  printAuthReminder();
+
+  reportInstall(projectDir, collect, pkgStatus);
+
+  return { collect, pkgStatus };
+}
+
+// End-of-`init` summary. Lists every file left untouched because it already
+// existed, with guidance to rename/move and re-run for the pristine version.
+function reportInstall(projectDir, collect, pkgStatus) {
+  const parts = [`${collect.written.length} added`];
+  if (pkgStatus === 'merged') parts.push('1 merged (package.json)');
+  parts.push(`${collect.skipped.length} skipped`);
+  log.info(`Install summary: ${parts.join(', ')}.`);
+
+  if (collect.skipped.length > 0) {
+    const list = collect.skipped.map((p) => '  ' + relative(projectDir, p)).join('\n');
+    log.warn(
+      'These files already existed and were left untouched:\n' +
+        list +
+        '\n\nTo install the bspecs version of any of them, rename or move your local copy and run `bspecs init` again.'
+    );
+  }
+}
+
+// package.json is the one file `init` may modify: if absent we write the template;
+// if present we merge in the missing b6p-cli devDependency (mergePackageJson fails
+// soft on malformed JSON). Returns 'written' | 'merged' | 'unchanged' | 'merge-failed'.
+function handlePackageJson(projectDir, vars, collect) {
+  const dest = join(projectDir, 'package.json');
+  const rendered = applyTemplate(
+    readFileSync(join(TEMPLATES_DIR, 'root', 'package.json.template'), 'utf8'),
+    vars
+  );
+
+  if (!existsSync(dest)) {
+    writeFile(dest, rendered);
+    collect.written.push(dest);
+    return 'written';
+  }
+
+  const existing = readFileSync(dest, 'utf8');
+  const merged = mergePackageJson(existing, rendered);
+  if (merged === null) {
+    log.warn(
+      'Existing package.json is not valid JSON — left untouched. Add the b6p CLI by hand:\n' +
+        '    "devDependencies": { "@bluestep-systems/b6p-cli": "^0.1.0" }'
+    );
+    collect.skipped.push(dest);
+    return 'merge-failed';
+  }
+  if (merged !== existing) {
+    writeFile(dest, merged);
+    return 'merged';
+  }
+  return 'unchanged';
+}
+
 // Detect whether the freshly created project directory sits inside an existing
 // git repository (a parent has a .git). Running `git init` here would nest a
 // repo inside another, which surprises users and breaks the implementer agent's

package/src/utils.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, readdirSync, statSync } from 'fs';
 import { createHash } from 'node:crypto';
-import { dirname, join } from 'path';
+import { dirname, join, relative } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -25,11 +25,22 @@ export function readTemplate(relativePath) {
   return readFileSync(join(TEMPLATES_DIR, relativePath), 'utf8');
 }
 
+// Extra opts (all default off, so plain calls overwrite everything as before):
+// skipExisting leaves existing dest files untouched (bspecs init); collect is a
+// { written, skipped } accumulator of absolute paths; exclude lists source-relative
+// paths (forward-slashed) to omit so the caller can handle them separately.
 export function copyTemplateTree(srcRel, destAbs, vars, opts = {}) {
-  const { makeExecutable = false, stripTemplateExt = true } = opts;
+  const {
+    makeExecutable = false,
+    stripTemplateExt = true,
+    skipExisting = false,
+    collect = null,
+    exclude = [],
+  } = opts;
   const srcAbs = join(TEMPLATES_DIR, srcRel);
   if (!existsSync(srcAbs)) return;
-  walk(srcAbs, srcAbs, destAbs, vars, { makeExecutable, stripTemplateExt });
+  const skip = new Set(exclude);
+  walk(srcAbs, srcAbs, destAbs, vars, { makeExecutable, stripTemplateExt, skipExisting, collect, skip });
 }
 
 function walk(rootSrc, src, dest, vars, opts) {
@@ -39,16 +50,26 @@ function walk(rootSrc, src, dest, vars, opts) {
     if (stats.isDirectory()) {
       walk(rootSrc, srcEntry, join(dest, entry), vars, opts);
     } else {
+      const srcRelPath = relative(rootSrc, srcEntry).split('\\').join('/');
+      if (opts.skip.has(srcRelPath)) continue;
+
       const targetName = opts.stripTemplateExt && entry.endsWith('.template')
         ? entry.slice(0, -'.template'.length)
         : entry;
       const destFile = join(dest, targetName);
+
+      if (opts.skipExisting && existsSync(destFile)) {
+        if (opts.collect) opts.collect.skipped.push(destFile);
+        continue;
+      }
+
       const raw = readFileSync(srcEntry, 'utf8');
       const rendered = applyTemplate(raw, vars);
       writeFile(destFile, rendered);
       if (opts.makeExecutable && destFile.endsWith('.sh')) {
         try { chmodSync(destFile, 0o755); } catch { /* Windows can't chmod, ignore */ }
       }
+      if (opts.collect) opts.collect.written.push(destFile);
     }
   }
 }
@@ -93,3 +114,32 @@ export function exists(path) {
 export function sha256(str) {
   return createHash('sha256').update(str, 'utf8').digest('hex');
 }
+
+// Add only-missing template devDependencies and the `b6p` script into an existing
+// package.json (bspecs init); existing values are never changed. Returns merged
+// JSON text, or null if the existing content isn't valid JSON (caller fails soft).
+export function mergePackageJson(existingContent, templateContent) {
+  let existing;
+  try {
+    existing = JSON.parse(existingContent);
+  } catch {
+    return null;
+  }
+  const template = JSON.parse(templateContent);
+
+  const tplDeps = template.devDependencies || {};
+  if (Object.keys(tplDeps).length > 0) {
+    existing.devDependencies = existing.devDependencies || {};
+    for (const [name, version] of Object.entries(tplDeps)) {
+      if (!(name in existing.devDependencies)) existing.devDependencies[name] = version;
+    }
+  }
+
+  const tplScripts = template.scripts || {};
+  if ('b6p' in tplScripts) {
+    existing.scripts = existing.scripts || {};
+    if (!('b6p' in existing.scripts)) existing.scripts.b6p = tplScripts.b6p;
+  }
+
+  return JSON.stringify(existing, null, 2) + '\n';
+}