buildwright 0.0.14 → 0.0.15

package/README.md

@@ -95,6 +95,12 @@ 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.14",
+  "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');
@@ -35,9 +36,6 @@ const REMOVED_PATHS = [
   '.buildwright/claws',
   '.buildwright/skills',
   '.buildwright/tasks/TEMPLATE.md',
-  '.buildwright/steering/quality-gates.md',
-  '.buildwright/steering/naming-conventions.md',
-  '.buildwright/steering/engineering-philosophy.md',
   'docs/requirements/TEMPLATE.md',
   '.claude/commands/bw-new-feature.md',
   '.claude/commands/bw-quick.md',
@@ -65,6 +63,60 @@ const REMOVED_PATHS = [
   '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.
  */
@@ -120,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 {
@@ -163,7 +215,14 @@ 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) {
@@ -208,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'));
+});