buildwright 0.0.13 → 0.0.15

package/README.md

@@ -82,6 +82,25 @@ Then open your AI editor and run:
 /bw-work "your task"
 ```
 
+### Update
+
+```bash
+npm install -g buildwright@latest
+cd your-project
+buildwright update
+```
+
+`buildwright update` refreshes Buildwright commands, agents, default steering,
+and Buildwright-owned support scripts. It also removes paths from the old
+pre-`/bw-work` model so generated tool configs do not contain both old and new
+workflows.
+
+Steering is only touched if Buildwright ships the file. The default
+`philosophy.md` is refreshed in place only when it is unmodified (a known shipped
+version); a customized `philosophy.md` is preserved. Any steering file Buildwright
+does not ship — your `tech.md`, `product.md`, or org-injected docs such as
+`quality-gates.md` — is never deleted or overwritten.
+
 ### From Source
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildwright",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Lightweight engineering workflow for agent-led development.",
   "license": "MIT",
   "engines": {
@@ -15,6 +15,7 @@
     "templates/"
   ],
   "scripts": {
+    "test": "node --test",
     "prepack": "node scripts/prepack.js",
     "postpack": "node scripts/postpack.js"
   },

package/src/commands/update.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const https = require('https');
 const { execSync } = require('child_process');
 const { isBuildwrightInstalled } = require('../utils/detect');
@@ -17,6 +18,104 @@ const RESET = '\x1b[0m';
 
 const GITHUB_REPO = 'raunakkathuria/buildwright';
 const UPDATE_DIRS = ['commands', 'agents', 'steering'];
+const SUPPORT_FILES = [
+  'scripts/sync-agents.sh',
+  'scripts/validate-docs.sh',
+  'scripts/validate-skill.sh',
+  'scripts/install-hooks.sh',
+  'scripts/hooks/pre-commit',
+  'scripts/hooks/post-merge',
+  'scripts/hooks/post-checkout',
+];
+const REMOVED_PATHS = [
+  '.buildwright/commands/bw-new-feature.md',
+  '.buildwright/commands/bw-quick.md',
+  '.buildwright/commands/bw-claw.md',
+  '.buildwright/commands/bw-help.md',
+  '.buildwright/agents/architect.md',
+  '.buildwright/claws',
+  '.buildwright/skills',
+  '.buildwright/tasks/TEMPLATE.md',
+  'docs/requirements/TEMPLATE.md',
+  '.claude/commands/bw-new-feature.md',
+  '.claude/commands/bw-quick.md',
+  '.claude/commands/bw-claw.md',
+  '.claude/commands/bw-help.md',
+  '.claude/agents/architect.md',
+  '.claude/claws',
+  '.claude/tasks',
+  '.opencode/commands/bw-new-feature.md',
+  '.opencode/commands/bw-quick.md',
+  '.opencode/commands/bw-claw.md',
+  '.opencode/commands/bw-help.md',
+  '.opencode/agents/architect.md',
+  '.opencode/claws',
+  '.opencode/skills',
+  '.cursor/rules/commands/bw-new-feature.mdc',
+  '.cursor/rules/commands/bw-quick.mdc',
+  '.cursor/rules/commands/bw-claw.mdc',
+  '.cursor/rules/commands/bw-help.mdc',
+  '.cursor/rules/agents/architect.mdc',
+  '.cursor/rules/claws',
+  'skills/bw-new-feature',
+  'skills/bw-quick',
+  'skills/bw-claw',
+  'skills/bw-help',
+];
+
+// Steering files Buildwright ships and may update in place. Keyed by filename,
+// each value is the set of SHA-256 hashes of every version Buildwright has ever
+// shipped for that file. An existing steering file is overwritten on update ONLY
+// when its hash is in this set (i.e. it is an unmodified, previously-shipped
+// copy); a customized file (hash absent) is preserved. Files Buildwright does not
+// ship at all are never touched.
+//
+// RELEASE STEP: whenever a managed steering file changes, append the superseded
+// version's SHA-256 here so unmodified installs keep auto-updating.
+const MANAGED_STEERING_HASHES = {
+  'philosophy.md': new Set([
+    '476fe491e139a211d9483942bd60435513813227c589ae0c29ba1e082672757a',
+  ]),
+};
+
+function sha256(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+/**
+ * Copy shipped steering files into dest. New shipped files are added. An existing
+ * file is overwritten only when its content matches a known shipped hash (i.e. the
+ * user has not customized it); customized or unmanaged files are preserved. Files
+ * not shipped by Buildwright are never touched. Steering is a flat dir of .md files.
+ * @param {object} [managedHashes] - filename -> Set of known shipped hashes
+ * @returns {{updated: string[], preserved: string[]}}
+ */
+function updateSteering(src, dest, managedHashes = MANAGED_STEERING_HASHES) {
+  fs.mkdirSync(dest, { recursive: true });
+  const updated = [];
+  const preserved = [];
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const realSrc = fs.realpathSync(path.join(src, entry.name));
+    const destPath = path.join(dest, entry.name);
+    if (!fs.existsSync(destPath)) {
+      fs.copyFileSync(realSrc, destPath);
+      updated.push(entry.name);
+      continue;
+    }
+    const known = managedHashes[entry.name];
+    const localHash = sha256(destPath);
+    if (known && known.has(localHash)) {
+      if (sha256(realSrc) !== localHash) {
+        fs.copyFileSync(realSrc, destPath);
+        updated.push(entry.name);
+      }
+    } else {
+      preserved.push(entry.name);
+    }
+  }
+  return { updated, preserved };
+}
 
 /**
  * Download a URL following redirects. Returns a Buffer.
@@ -73,7 +172,7 @@ async function update() {
 
   console.log(`${BOLD}Updating Buildwright in ${cwd}...${RESET}\n`);
   console.log(`Updating: ${UPDATE_DIRS.map(d => `.buildwright/${d}/`).join(', ')}`);
-  console.log(`Preserving: project-created steering files such as tech.md and product.md\n`);
+  console.log(`Preserving: customized and org-injected steering files (only an unmodified philosophy.md is refreshed)\n`);
 
   let tmpDir;
   try {
@@ -86,8 +185,27 @@ async function update() {
       throw new Error('Downloaded archive is missing .buildwright/ directory');
     }
 
-    // This version is not backward compatible with the older command model.
-    // Update only adds current files; users should re-run init for a clean tree.
+    const removed = [];
+    for (const relativePath of REMOVED_PATHS) {
+      const target = path.join(cwd, relativePath);
+      if (!fs.existsSync(target)) continue;
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(relativePath);
+    }
+    for (const relativePath of ['.buildwright/tasks', 'docs/requirements']) {
+      const target = path.join(cwd, relativePath);
+      if (!fs.existsSync(target)) continue;
+      if (fs.statSync(target).isDirectory() && fs.readdirSync(target).length === 0) {
+        fs.rmdirSync(target);
+      }
+    }
+    if (removed.length > 0) {
+      console.log(`  Removed old Buildwright paths:`);
+      for (const relativePath of removed) {
+        console.log(`    - ${relativePath}`);
+      }
+    }
+
     for (const dir of UPDATE_DIRS) {
       const src = path.join(srcBuildwright, dir);
       const dest = path.join(cwd, '.buildwright', dir);
@@ -97,8 +215,24 @@ async function update() {
       }
       console.log(`  Updating .buildwright/${dir}/`);
       fs.mkdirSync(dest, { recursive: true });
-      copyDir(src, dest, { skipExisting: dir === 'steering' });
+      if (dir === 'steering') {
+        const { preserved } = updateSteering(src, dest);
+        if (preserved.length > 0) {
+          console.log(`    Preserved customized steering files: ${preserved.join(', ')}`);
+        }
+      } else {
+        copyDir(src, dest);
+      }
+    }
+
+    for (const file of SUPPORT_FILES) {
+      const src = path.join(extractedRoot, file);
+      const dest = path.join(cwd, file);
+      if (!fs.existsSync(src)) continue;
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
     }
+    console.log(`  Updated Buildwright support scripts`);
 
     // Also add CLAUDE.md if it doesn't already exist locally
     const srcClaude = path.join(extractedRoot, 'CLAUDE.md');
@@ -119,7 +253,7 @@ async function update() {
 
     console.log('');
     console.log(`${GREEN}${BOLD}Update complete!${RESET}`);
-    console.log('commands, agents, and default steering: new files added. Existing files unchanged.');
+    console.log('commands, agents, and default steering updated.');
     console.log('Your custom files are unchanged.\n');
 
   } catch (err) {
@@ -133,4 +267,4 @@ async function update() {
   }
 }
 
-module.exports = { update };
+module.exports = { update, updateSteering, REMOVED_PATHS, MANAGED_STEERING_HASHES };

package/src/commands/update.test.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const { updateSteering, REMOVED_PATHS, MANAGED_STEERING_HASHES } = require('./update');
+
+const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+function tmpProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bw-update-test-'));
+  const src = path.join(root, 'src');
+  const dest = path.join(root, 'dest');
+  fs.mkdirSync(src, { recursive: true });
+  fs.mkdirSync(dest, { recursive: true });
+  return { root, src, dest };
+}
+
+test('copies a shipped steering file that is absent locally', () => {
+  const { src, dest } = tmpProject();
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+
+  const { updated, preserved } = updateSteering(src, dest, {});
+
+  assert.deepStrictEqual(updated, ['philosophy.md']);
+  assert.deepStrictEqual(preserved, []);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'philosophy.md'), 'utf8'), 'NEW philosophy');
+});
+
+test('overwrites an unmodified shipped file (hash match) with the latest', () => {
+  const { src, dest } = tmpProject();
+  const oldContent = 'OLD philosophy';
+  fs.writeFileSync(path.join(dest, 'philosophy.md'), oldContent);
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+
+  const managed = { 'philosophy.md': new Set([sha256(oldContent)]) };
+  const { updated, preserved } = updateSteering(src, dest, managed);
+
+  assert.deepStrictEqual(updated, ['philosophy.md']);
+  assert.deepStrictEqual(preserved, []);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'philosophy.md'), 'utf8'), 'NEW philosophy');
+});
+
+test('preserves a customized steering file (hash not in the managed set)', () => {
+  const { src, dest } = tmpProject();
+  const customContent = 'CUSTOM org philosophy';
+  fs.writeFileSync(path.join(dest, 'philosophy.md'), customContent);
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+
+  // managed set only knows some other (shipped) hash, not the custom content
+  const managed = { 'philosophy.md': new Set([sha256('some shipped version')]) };
+  const { updated, preserved } = updateSteering(src, dest, managed);
+
+  assert.deepStrictEqual(updated, []);
+  assert.deepStrictEqual(preserved, ['philosophy.md']);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'philosophy.md'), 'utf8'), customContent);
+});
+
+test('never touches an org steering file that Buildwright does not ship', () => {
+  const { src, dest } = tmpProject();
+  // Buildwright ships only philosophy.md
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+  // org injected its own doc at a colliding-style path
+  const orgDoc = 'org quality gates';
+  fs.writeFileSync(path.join(dest, 'quality-gates.md'), orgDoc);
+
+  updateSteering(src, dest, MANAGED_STEERING_HASHES);
+
+  assert.strictEqual(fs.existsSync(path.join(dest, 'quality-gates.md')), true);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'quality-gates.md'), 'utf8'), orgDoc);
+});
+
+test('REMOVED_PATHS no longer deletes org-injected steering docs', () => {
+  assert.ok(!REMOVED_PATHS.includes('.buildwright/steering/quality-gates.md'));
+  assert.ok(!REMOVED_PATHS.includes('.buildwright/steering/naming-conventions.md'));
+  assert.ok(!REMOVED_PATHS.includes('.buildwright/steering/engineering-philosophy.md'));
+});
+
+test('REMOVED_PATHS still cleans up non-steering legacy paths', () => {
+  assert.ok(REMOVED_PATHS.includes('.buildwright/commands/bw-quick.md'));
+  assert.ok(REMOVED_PATHS.includes('.buildwright/agents/architect.md'));
+});

package/templates/scripts/sync-agents.sh

@@ -33,6 +33,17 @@ cd "$ROOT_DIR"
 # Helpers
 # ============================================================================
 
+sed_inplace() {
+  local expression="$1"
+  local file="$2"
+
+  if sed --version >/dev/null 2>&1; then
+    sed -i -e "$expression" "$file"
+  else
+    sed -i '' -e "$expression" "$file"
+  fi
+}
+
 # sync_dir SRC DST [REWRITE_FROM REWRITE_TO]
 # Copies directory, optionally rewriting path references in .md files
 sync_dir() {
@@ -58,9 +69,9 @@ sync_dir() {
     if [ -n "$rewrite_from" ] && [ -n "$rewrite_to" ]; then
       # Only rewrite @@.buildwright/ (read instructions) → tool-specific path
       # Bare .buildwright/ (write/canonical instructions) stays untouched
-      find "$tmpdir" -name "*.md" -exec sed -i '' \
-        -e "s|@@${rewrite_from}|${rewrite_to}|g" \
-        {} + 2>/dev/null || true
+      while IFS= read -r file; do
+        sed_inplace "s|@@${rewrite_from}|${rewrite_to}|g" "$file"
+      done < <(find "$tmpdir" -name "*.md" -type f)
     fi
     if ! diff -rq "$tmpdir" "$dst" > /dev/null 2>&1; then
       echo "OUT OF SYNC: $dst differs from $src"
@@ -74,9 +85,9 @@ sync_dir() {
     # @@.buildwright/ = "resolve to tool-specific dir" → gets rewritten
     # Bare .buildwright/ = "canonical path" → stays untouched
     if [ -n "$rewrite_from" ] && [ -n "$rewrite_to" ]; then
-      find "$dst" -name "*.md" -exec sed -i '' \
-        -e "s|@@${rewrite_from}|${rewrite_to}|g" \
-        {} + 2>/dev/null || true
+      while IFS= read -r file; do
+        sed_inplace "s|@@${rewrite_from}|${rewrite_to}|g" "$file"
+      done < <(find "$dst" -name "*.md" -type f)
     fi
     echo "  synced $src → $dst"
   fi