entropy-machines 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # entropy-machines
 
-Escape the terminal. Enter your proto factory.
+Escape the terminal. Enter your factory floor.
 
 You create PRDs, design with agents, and once your decisions are complete,
 issues are generated from those PRDs. Worker agents execute each issue in
@@ -24,7 +24,7 @@ the decisions only you can make. Everything downstream follows from your answers
 ## Get started
 
 ```sh
-npx entropy start
+npx entropy-machines start
 ```
 
 This vendors the harness into your git repo (if it hasn't been already) and

package/bin/entropy-machines-init

@@ -47,6 +47,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);
@@ -55,8 +64,8 @@ function die(lines) {
 function usage() {
   console.log(`entropy-machines ${PKG.version}
 
-  npx entropy start                     # init (if needed) + open the PRD
-  npx entropy init [--dir <path>]       # vendor the harness only
+  npx entropy-machines start                     # init (if needed) + open the PRD
+  npx entropy-machines init [--dir <path>]       # vendor the harness only
 
 start: vendors the harness if config.json is absent, then launches
 bin/serve — which opens your first PRD in a browser.
@@ -196,31 +205,31 @@ function init(argv) {
   }
 
   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 +240,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) {
@@ -262,7 +274,7 @@ function start(argv) {
   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.1",
+  "version": "0.1.3",
   "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": {
@@ -12,7 +12,6 @@
     "url": "https://github.com/modern-sapien/entropy-machines/issues"
   },
   "bin": {
-    "entropy": "bin/entropy-machines-init",
     "entropy-machines": "bin/entropy-machines-init"
   },
   "files": [