loop-engineering-harness 1.0.0 → 1.0.1

package/README.md

@@ -17,17 +17,45 @@ commands — plus **graphify** (deterministic code knowledge graph) and **Langfu
 
 ## Install
 
+Published on npm as [`loop-engineering-harness`](https://www.npmjs.com/package/loop-engineering-harness).
+Zero runtime dependencies — just Node ≥ 16.
+
+**Run without installing (recommended):**
+
 ```bash
 npx loop-engineering-harness detect .      # dry run — show exactly what will change
 npx loop-engineering-harness init .        # install (prints a plan, asks to confirm)
 npx loop-engineering-harness uninstall .   # remove everything; keeps your specs/
 ```
 
-> **Note:** You can also install directly from GitHub without publishing:
+**Or install globally** to get the `loop-engineering-harness` / `agent-harness` commands on your PATH:
+
+```bash
+npm install -g loop-engineering-harness
+
+loop-engineering-harness detect .
+loop-engineering-harness init .
+```
+
+> **No npm needed?** Install straight from GitHub:
 > ```bash
 > npx github:AakashRajendran0926/Loop-Engineering init .
 > ```
 
+### After install — build the knowledge base
+
+`init` installs **graphify** (PyPI `graphifyy`, via uv/pipx/pip) because retrieval
+is graph-first. Then, inside Claude Code, build the graph for your **existing**
+codebase once:
+
+```
+/graphify .          # indexes this repo into graphify-out/ (the knowledge base)
+/feature <description>   # /feature also auto-builds the graph on first run if you skip the step above
+```
+
+Skip the graphify install with `init . --no-graphify` (the `/graphify` skill
+self-installs on first use either way).
+
 Brownfield-safe by construction:
 
 - **`CLAUDE.md`** gains a delimited `<!-- harness:begin -->…<!-- harness:end -->`
@@ -140,6 +168,10 @@ Escalations **park** (with a question for a human) instead of stalling the queue
 a parked feature resumes from artifacts in a brand-new session — recover-from-
 compaction and resume-from-parking are the same mechanism.
 
+> Commands below assume a global install (`npm install -g loop-engineering-harness`).
+> Without one, prefix each with `npx loop-engineering-harness …`. The
+> `loop-engineering-harness` and `agent-harness` commands are interchangeable.
+
 ```bash
 agent-harness queue add "add order cancellation with refunds"
 agent-harness queue add "nightly CSV export" --auto-approve   # headless self-approve
@@ -252,7 +284,7 @@ npm test        # node tests/run.js — 84 checks across extract-deps determinis
 
 - **Node ≥ 16** (installer + loop driver; zero runtime dependencies)
 - **Python 3.8+** on PATH (`python`, `python3`, or `py`) for hooks/scripts
-- **graphify** for graph-first retrieval — `/graphify` self-installs it on first run
+- **graphify** for graph-first retrieval — `init` installs it (PyPI `graphifyy`); `/graphify` also self-installs it on first run
 - **Claude Code** (for the `claude -p` headless loop) and, optionally, **Langfuse**
 
 ## Reversibility

package/bin/cli.js

@@ -10,17 +10,19 @@ const readline = require('readline');
 const { detect, formatReport } = require('../src/detect');
 const { install } = require('../src/install');
 const { uninstall } = require('../src/uninstall');
+const { ensureGraphify } = require('../src/graphify');
 const loop = require('../src/loop');
 const { computeMetrics, formatMetrics } = require('../src/metrics');
 
 function parseArgs(argv) {
-  const out = { _: [], yes: false, python: null, dryRun: false, once: false, autoApprove: false };
+  const out = { _: [], yes: false, python: null, dryRun: false, once: false, autoApprove: false, graphify: true };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--yes' || a === '-y') out.yes = true;
     else if (a === '--dry-run') out.dryRun = true;
     else if (a === '--once') out.once = true;
     else if (a === '--auto-approve') out.autoApprove = true;
+    else if (a === '--no-graphify') out.graphify = false;
     else if (a === '--python') out.python = argv[++i];
     else if (a.startsWith('--python=')) out.python = a.slice(9);
     else out._.push(a);
@@ -57,6 +59,7 @@ async function main() {
       '  agent-harness metrics              Per-feature burndown + tokens-per-task',
       '',
       'Flags:  --yes | -y   skip confirmation      --python <cmd>   force interpreter',
+      '        --no-graphify  skip installing graphify at init',
       '        --once       one feature then stop   --auto-approve  headless self-approval',
       '        --dry-run    plan the loop, run nothing',
     ].join('\n'));
@@ -140,7 +143,21 @@ async function main() {
     console.log(`Installed. CLAUDE.md: ${manifest.claudeMd}; ` +
       `${manifest.filesAdded.length} files added` +
       (manifest.filesRenamed.length ? `, ${manifest.filesRenamed.length} collision(s) renamed to *.harness.*` : '') +
-      `. Next: /feature <description>`);
+      `.`);
+
+    // Retrieval is graph-first — install graphify now (best-effort; the
+    // /graphify skill self-installs on first use if this is skipped or fails).
+    if (args.graphify) {
+      console.log('\nInstalling graphify (graph-first retrieval)...');
+      const g = ensureGraphify({ python: args.python });
+      console.log('  ' + g.message);
+    }
+
+    console.log('\nNext steps:');
+    console.log('  1. Build the knowledge base for this project:  /graphify .');
+    console.log('     (existing/brownfield repos: this indexes your codebase into graphify-out/;');
+    console.log('      /feature also auto-builds it on first run if you skip this)');
+    console.log('  2. Start a feature:  /feature <description>');
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loop-engineering-harness",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Loop Engineering — a reversible, observable multi-agent Claude Code harness for brownfield codebases. Policy lives in exit codes and artifacts on disk, not in prompts.",
   "keywords": [
     "claude-code",
@@ -13,6 +13,7 @@
   "license": "MIT",
   "type": "commonjs",
   "bin": {
+    "loop-engineering-harness": "bin/cli.js",
     "agent-harness": "bin/cli.js",
     "loop-engineering": "bin/cli.js"
   },

package/src/graphify.js

@@ -0,0 +1,55 @@
+'use strict';
+// Best-effort installer for graphify (PyPI package `graphifyy`, imported as
+// `graphify`). Retrieval in the harness is graph-first, so we install the CLI at
+// `init` time rather than waiting for the first `/graphify` to self-install it.
+// Non-fatal by design: a failure here never blocks the harness install — the
+// `/graphify` skill still self-installs on first use.
+
+const { spawnSync } = require('child_process');
+const m = require('./merge');
+
+const PKG = 'graphifyy';
+
+function has(cmd) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const r = spawnSync(probe, [cmd], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+function importable(python) {
+  const r = spawnSync(python, ['-c', 'import graphify'], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+// Returns { status, via, message }.
+//   status: 'already' | 'installed' | 'failed' | 'skipped'
+function ensureGraphify(opts) {
+  opts = opts || {};
+  const python = opts.python || m.detectPython();
+  const run = opts.run || ((cmd, cmdArgs) => spawnSync(cmd, cmdArgs, { stdio: 'inherit' }));
+
+  if (python && importable(python)) {
+    return { status: 'already', via: python, message: 'graphify already installed' };
+  }
+
+  // Prefer isolated tool installs (uv → pipx), fall back to pip into the
+  // detected interpreter — mirrors what the /graphify skill does on first run.
+  const attempts = [];
+  if (has('uv')) attempts.push({ via: 'uv', cmd: 'uv', args: ['tool', 'install', '--upgrade', PKG] });
+  if (has('pipx')) attempts.push({ via: 'pipx', cmd: 'pipx', args: ['install', PKG] });
+  if (python) attempts.push({ via: 'pip', cmd: python, args: ['-m', 'pip', 'install', '--upgrade', PKG] });
+
+  if (attempts.length === 0) {
+    return { status: 'skipped', via: null, message: 'no uv/pipx/python found — skipped graphify install' };
+  }
+
+  for (const a of attempts) {
+    const r = run(a.cmd, a.args);
+    if (r && r.status === 0) {
+      return { status: 'installed', via: a.via, message: `graphify installed via ${a.via}` };
+    }
+  }
+  return { status: 'failed', via: null, message: 'graphify install failed — /graphify will self-install on first use' };
+}
+
+module.exports = { ensureGraphify, PKG };