entropy-machines 0.1.2 → 0.1.4

package/bin/entropy-machines-init

@@ -21,9 +21,15 @@
 // against a clone does).
 //
 // Deliberately NOT here, because the owner deleted a 1072-line installer to
-// get rid of them: managed blocks, hash fences, install receipts, staleness
-// or version checking, an uninstall path, and any write into the user's
-// .claude/ or CLAUDE.md. Undoing this is `rm -rf` of one directory.
+// get rid of them: managed blocks, hash fences, install receipts, an
+// uninstall path, and any write into the user's .claude/ or CLAUDE.md.
+// Undoing this is `rm -rf` of one directory.
+//
+// VERSION STAMPING is the one piece that came back: a .version file in the
+// vendored directory lets `start` detect a stale copy and auto-update the
+// harness code (bin/, lib/, etc.) without re-running bin/init or touching
+// config.json. Without it, `npx entropy-machines start` after a version bump
+// silently ran the old code and the user had to know to delete and re-vendor.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -47,6 +53,15 @@ const NPM_ENTRY = path.basename(__filename);
 
 const DEFAULT_DIR = 'entropy-machines';
 
+// ANSI color, gated on tty + NO_COLOR (https://no-color.org/).
+const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const BOLD  = USE_COLOR ? '\x1b[1m'  : '';
+const DIM   = USE_COLOR ? '\x1b[2m'  : '';
+const GREEN = USE_COLOR ? '\x1b[32m' : '';
+const YELLOW = USE_COLOR ? '\x1b[33m' : '';
+const CYAN  = USE_COLOR ? '\x1b[36m' : '';
+const RESET = USE_COLOR ? '\x1b[0m'  : '';
+
 function die(lines) {
   for (const line of [].concat(lines)) console.error(line);
   process.exit(2);
@@ -195,32 +210,35 @@ function init(argv) {
     fs.copyFileSync(path.join(PKG_ROOT, 'LICENSE'), licenseDst);
   }
 
+  // Stamp the version so `start` can detect a stale vendored copy.
+  fs.writeFileSync(path.join(dest, '.version'), PKG.version + '\n');
+
   const shown = path.relative(root, dest) || '.';
-  console.log(`entropy-machines ${PKG.version}: vendored into ${dest}`);
-  for (const d of HARNESS_DIRS) console.log(`  ${path.join(shown, d)}/`);
-  console.log(`  ${path.join(shown, 'LICENSE')}${licenseNote}`);
+  console.log(`${GREEN}entropy-machines ${PKG.version}: vendored into ${dest}${RESET}`);
+  for (const d of HARNESS_DIRS) console.log(`  ${DIM}${path.join(shown, d)}/${RESET}`);
+  console.log(`  ${DIM}${path.join(shown, 'LICENSE')}${licenseNote}${RESET}`);
   console.log('');
 
   // ---- Hand over to the harness. Everything past here is shell + Python. ----
 
   const vendoredInit = path.join(dest, 'bin', 'init');
-  console.log(`entropy-machines: running ${path.join(shown, 'bin', 'init')}`);
+  console.log(`entropy-machines: running ${DIM}${path.join(shown, 'bin', 'init')}${RESET}`);
   const r = spawnSync(vendoredInit, [], { cwd: root, stdio: 'inherit' });
   if (r.error) {
-    console.error(`entropy-machines: could not run ${vendoredInit}: ${r.error.message}`);
-    console.error('  The files ARE vendored. Run it yourself from the repo root.');
+    console.error(`${YELLOW}entropy-machines: could not run ${vendoredInit}: ${r.error.message}${RESET}`);
+    console.error(`  The files ARE vendored. Run it yourself from the repo root.`);
     process.exit(2);
   }
   if (r.status !== 0) {
     console.error('');
-    console.error('entropy-machines: the files are vendored, but bin/init did not');
+    console.error(`${YELLOW}entropy-machines: the files are vendored, but bin/init did not${RESET}`);
     console.error('  finish. Fix what it named above and re-run it from the repo');
-    console.error(`  root:  ${path.join(shown, 'bin', 'init')}`);
+    console.error(`  root:  ${CYAN}${path.join(shown, 'bin', 'init')}${RESET}`);
     process.exit(r.status === null ? 2 : r.status);
   }
 
   console.log('');
-  console.log('entropy-machines: done. Next —');
+  console.log(`${BOLD}entropy-machines: done. Next —${RESET}`);
   // Named paths only, never a guessed docs directory — that one is config
   // (docs.dir), and CONFIG.md rule 1 makes a hardcoded path in bin/ a bug.
   // NEVER `git add .` for the root layout. This command is reached over npm,
@@ -231,9 +249,12 @@ function init(argv) {
     shown === '.'
       ? `${HARNESS_DIRS.join(' ')} LICENSE .gitignore`
       : `${shown} .gitignore`;
-  console.log(`  1. commit what init just wrote:  git add ${addPaths}`);
-  console.log(`  2. point your coding agent at ${path.join(shown, 'docs', 'AGENT-QUICKSTART.md')}`);
-  console.log(`  3. ${path.join(shown, 'bin', 'serve')}  — answer the PRD it opens`);
+  // Step 1: agent context (most important — the agent needs this first)
+  console.log(`  ${BOLD}1. point your coding agent at ${CYAN}${path.join(shown, 'docs', 'AGENT-QUICKSTART.md')}${RESET}`);
+  // Step 2: run serve to get the PRD
+  console.log(`  2. ${CYAN}${path.join(shown, 'bin', 'serve')}${RESET}  — answer the PRD it opens (creates issues)`);
+  // Step 3: commit (least urgent)
+  console.log(`  ${DIM}3. commit what init wrote:  git add ${addPaths}${RESET}`);
 }
 
 function findHarness(root) {
@@ -245,6 +266,22 @@ function findHarness(root) {
   return null;
 }
 
+// Re-copy harness code (bin/, lib/, etc.) without re-running bin/init or
+// touching config.json. Called by start() when the vendored .version is older
+// than the running package.
+function updateHarness(loc) {
+  const dest = loc.dir;
+  for (const d of HARNESS_DIRS) {
+    fs.cpSync(path.join(PKG_ROOT, d), path.join(dest, d), {
+      recursive: true,
+      filter: copyFilter,
+    });
+  }
+  // LICENSE: overwrite — it's ours, not user-edited.
+  fs.copyFileSync(path.join(PKG_ROOT, 'LICENSE'), path.join(dest, 'LICENSE'));
+  fs.writeFileSync(path.join(dest, '.version'), PKG.version + '\n');
+}
+
 function start(argv) {
   const root = repoRoot();
   if (!root) die(['entropy-machines: not inside a git repository.']);
@@ -258,11 +295,24 @@ function start(argv) {
   if (!loc) {
     die(['entropy-machines: config.json not found at root or in ' + DEFAULT_DIR + '/.']);
   }
+
+  // AUTO-UPDATE: if the vendored copy is older than this package, re-copy
+  // the harness code. config.json and the docs directory are untouched.
+  const versionFile = path.join(loc.dir, '.version');
+  let vendored = '';
+  try { vendored = fs.readFileSync(versionFile, 'utf8').trim(); } catch {}
+  if (vendored !== PKG.version) {
+    const from = vendored || 'unknown';
+    console.log(`${GREEN}entropy-machines: updating ${loc.shown}/ from ${from} → ${PKG.version}${RESET}`);
+    updateHarness(loc);
+    console.log(`${DIM}  (config.json and docs left alone)${RESET}\n`);
+  }
+
   const serve = path.join(loc.dir, 'bin', 'serve');
   if (!fs.existsSync(serve)) {
     die([`entropy-machines: ${path.join(loc.shown, 'bin', 'serve')} not found.`]);
   }
-  console.log(`\nentropy-machines: starting serve from ${loc.shown}/\n`);
+  console.log(`\n${BOLD}entropy-machines: starting serve from ${loc.shown}/${RESET}\n`);
   const r = spawnSync('sh', [serve], { cwd: loc.dir, stdio: 'inherit' });
   process.exit(r.status ?? 1);
 }

package/bin/init

@@ -18,6 +18,13 @@
 #   --force     overwrite an existing config.json.
 set -e
 
+# ---- ANSI color, gated on tty + NO_COLOR (https://no-color.org/) ----
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+  BOLD='\033[1m'  DIM='\033[2m'  GREEN='\033[32m'  YELLOW='\033[33m'  CYAN='\033[36m'  RESET='\033[0m'
+else
+  BOLD='' DIM='' GREEN='' YELLOW='' CYAN='' RESET=''
+fi
+
 usage() {
   cat >&2 <<'EOF'
 usage: bin/init [--force]
@@ -195,18 +202,18 @@ fi
 # in fact everything was — and a plain re-run then died on "config.json
 # already exists" with no repair path named.
 if ! (cd "$project" && "$ENTROPY_MACHINES_HOME/bin/tracker" ready >/dev/null 2>&1); then
-  echo "init: WARNING — $target was WRITTEN, but bin/tracker could not read the" >&2
+  printf "${YELLOW}init: WARNING — $target was WRITTEN, but bin/tracker could not read the${RESET}\n" >&2
   echo "  tracker back afterward. This is not a refusal: everything above" >&2
   echo "  really was written, and the project is half-initialised." >&2
-  echo "  Check $project/.entropy-machines/ and $target by hand." >&2
+  printf "  Check ${DIM}$project/.entropy-machines/${RESET} and ${DIM}$target${RESET} by hand.\n" >&2
   echo "  To re-run once you have fixed it (a plain re-run will refuse," >&2
   echo "  because config.json now exists):" >&2
-  echo "      $ENTROPY_MACHINES_HOME/bin/init --force" >&2
+  printf "      ${CYAN}$ENTROPY_MACHINES_HOME/bin/init --force${RESET}\n" >&2
   exit 2
 fi
 
-echo "init: wrote $target"
-echo "$prd_note"
+printf "${GREEN}init: wrote $target${RESET}\n"
+printf "${GREEN}$prd_note${RESET}\n"
 if [ -n "$prd_written" ]; then
   echo "      questions in it are the ones only you can answer."
 fi
@@ -225,8 +232,8 @@ esac
 # the first document the harness hands them would otherwise hit a 404 — which
 # is exactly the bug that made this necessary.
 "$ENTROPY_MACHINES_HOME/bin/tracker" render >/dev/null 2>&1 || \
-  echo "init: warning — could not render TRACKER.html; run \`$cmd_prefix/tracker render\`" >&2
+  printf "${YELLOW}init: warning — could not render TRACKER.html; run \`${CYAN}$cmd_prefix/tracker render${YELLOW}\`${RESET}\n" >&2
 
-echo "init: tracker is live and empty — \`$cmd_prefix/tracker ready\` answers."
-echo "init: next — run \`$cmd_prefix/serve\` and answer the PRD it opens."
+printf "${GREEN}init: tracker is live and empty${RESET} — \`${CYAN}$cmd_prefix/tracker ready${RESET}\` answers.\n"
+printf "${BOLD}init: next — run \`${CYAN}$cmd_prefix/serve${RESET}${BOLD}\` and answer the PRD it opens.${RESET}\n"
 echo "      Filing the issues it produces is step one."

package/bin/serve

@@ -690,18 +690,31 @@ class Handler(BaseHTTPRequestHandler):
 
 
 def main():
-    try:
-        server = ThreadingHTTPServer(("127.0.0.1", PORT), Handler)
-    except OSError as exc:
-        if exc.errno == 48 or "Address already in use" in str(exc):  # EADDRINUSE
-            print(
-                "serve: REFUSED — port %d is already in use.\n"
-                "  Another server (maybe a previous `bin/serve`) already holds it.\n"
-                "  Try a different port:  bin/serve %d" % (PORT, PORT + 1),
-                file=sys.stderr,
-            )
+    # TRY THE REQUESTED PORT, THEN SCAN UPWARD. A user running `npx
+    # entropy-machines start` for the first time should not be stopped by a
+    # stale process on 8787 — the server picks the next open port and says
+    # which one it got. Cap at 20 attempts so a misconfigured machine gets a
+    # clear error, not an infinite loop.
+    MAX_ATTEMPTS = 20
+    port = PORT
+    server = None
+    for attempt in range(MAX_ATTEMPTS):
+        try:
+            server = ThreadingHTTPServer(("127.0.0.1", port), Handler)
+            break
+        except OSError as exc:
+            if exc.errno == 48 or "Address already in use" in str(exc):
+                if attempt == 0 and port == PORT:
+                    print("serve: port %d busy, scanning for an open port…" % port,
+                          file=sys.stderr, flush=True)
+                port += 1
+                continue
+            print("serve: REFUSED — could not bind 127.0.0.1:%d (%s)." % (port, exc),
+                  file=sys.stderr)
             sys.exit(1)
-        print("serve: REFUSED — could not bind 127.0.0.1:%d (%s)." % (PORT, exc), file=sys.stderr)
+    if server is None:
+        print("serve: REFUSED — ports %d–%d all busy." % (PORT, PORT + MAX_ATTEMPTS - 1),
+              file=sys.stderr)
         sys.exit(1)
     # flush=True IS THE POINT OF THESE TWO LINES. Python block-buffers stdout
     # when it is not a tty — which is exactly the case a bootstrapping agent
@@ -710,7 +723,7 @@ def main():
     # never drained, because the very next statement blocks in serve_forever()
     # forever; the log stays 0 bytes while the server runs and 0 bytes after
     # it is killed. The URL is the one thing this command exists to produce.
-    print("serving %s on http://localhost:%d" % (ENTROPY_MACHINES_ROOT, PORT), flush=True)
+    print("serving %s on http://localhost:%d" % (ENTROPY_MACHINES_ROOT, port), flush=True)
     print("  docs: %s (%s)" % (DOCS_PATH, DOCS_DIR), flush=True)
     print("  theme: %s (%s)" % (THEME_NAME, THEME_FILE), flush=True)
     try:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entropy-machines",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Vendors the entropy-machines agent-orchestration harness into your git repository as plain tracked files. A delivery mechanism, not a runtime — the harness is POSIX shell and Python 3 and needs no Node once the files have landed.",
   "license": "Elastic-2.0",
   "repository": {