create-healix 1.1.6 → 1.3.0

package/README.md

@@ -0,0 +1,34 @@
+# create-healix
+
+Scaffold a [Healix](https://www.npmjs.com/package/wdio-healix-service) test-automation project in one command — a ready-to-run WebdriverIO setup wired for AI-assisted authoring and **self-healing, standalone** test suites.
+
+```bash
+npx create-healix my-app
+cd my-app
+```
+
+## What you get
+- **WebdriverIO + Healix service** preconfigured (`wdio.web.conf.ts`).
+- **`.mcp.json`** registering the [`healix-mcp`](https://www.npmjs.com/package/healix-mcp) server, so an AI agent (Claude Code, Cursor, Windsurf, …) can drive the live browser, observe the real DOM, and author specs/page objects for you.
+- **Two-file page-object model** + an example spec/POM to copy.
+- **Allure reporting** and a `reports/screenshots/` directory wired out of the box.
+- **`CLAUDE.md`** + a SessionStart hook so the agent always loads the framework guide.
+
+## Options
+| Flag | Effect |
+|------|--------|
+| `--yes`, `-y` | Accept all defaults |
+| `--platforms=web,android,ios` | Target platforms (default `web`) |
+| `--app-url=<url>` | Default app URL for the example spec |
+| `--mcp=cursor\|claude\|windsurf` | Which MCP client to configure |
+| `--skip-install` | Don't run `npm install` |
+
+## Run it
+```bash
+npm run session:web   # opens a live browser + the Healix API for the agent to drive
+npm test              # runs the suite standalone — no AI, no MCP
+```
+
+The deliverable is a normal WDIO suite: it runs in CI with `npx wdio run` and **no AI in the loop**.
+
+See [`wdio-healix-service`](https://www.npmjs.com/package/wdio-healix-service) (the framework) and [`healix-mcp`](https://www.npmjs.com/package/healix-mcp) (the agent server).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-healix",
-  "version": "1.1.6",
+  "version": "1.3.0",
   "description": "Scaffold a healix WDIO project with MCP integration ready out of the box",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   ],
   "scripts": {
     "build": "echo 'No build step required — source is plain ESM'",
-    "test": "node test/seed-parity.test.mjs && node bin/create-healix.js --help",
+    "test": "node test/seed-parity.test.mjs && node test/rehydrate-hooks.test.mjs && node bin/create-healix.js --help",
     "test:parity": "node test/seed-parity.test.mjs"
   },
   "dependencies": {

package/src/scaffold.js

@@ -4,7 +4,7 @@ import { execSync } from 'node:child_process';
 import {
   tsconfigJson, packageJson, wdioWebConf, mcpJson, healixAgentJson,
   exampleSpec, examplePage, exampleLocators, readme,
-  claudeSettings, claudeMd, claudeRehydrateScript,
+  claudeSettings, claudeMd, claudeRehydrateScript, cursorHooks,
 } from './templates.js';
 
 function write(filePath, content) {
@@ -54,9 +54,12 @@ export function scaffold(projectName, targetDir, options = {}) {
   write(path.join(projectDir, '.mcp.json'),          mcpJson(apiPort));
   write(path.join(projectDir, 'healix.agent.json'),  healixAgentJson());
   write(path.join(projectDir, 'README.md'),          readme(projectName));
-  // Durable knowledge delivery: compact-hook backstop + thin project-scope pointer.
+  // Durable knowledge delivery: re-hydration hook (fires at start + after compaction)
+  // wired for EVERY host — Spryv + Claude Code via .claude/settings.json, Cursor via
+  // .cursor/hooks.json — all running ONE shared script. Plus a thin project-scope pointer.
   write(path.join(projectDir, '.claude', 'settings.json'), claudeSettings());
   write(path.join(projectDir, '.claude', 'healix-rehydrate.mjs'), claudeRehydrateScript());
+  write(path.join(projectDir, '.cursor', 'hooks.json'),  cursorHooks());
   write(path.join(projectDir, 'CLAUDE.md'),          claudeMd(projectName));
 
   write(path.join(projectDir, 'test', 'specs', 'example.spec.ts'),              exampleSpec());

package/src/templates.js

@@ -1,7 +1,7 @@
 // Template generators for create-healix scaffold output.
 // Each function returns the file content as a string with all known fixes applied.
 
-const HEALIX_SERVICE_VERSION = '^0.2.0';
+const HEALIX_SERVICE_VERSION = '^0.3.0';
 
 export function tsconfigJson() {
   return JSON.stringify(
@@ -55,6 +55,7 @@ export function packageJson(projectName) {
         '@wdio/local-runner': '^9',
         '@wdio/mocha-framework': '^9',
         '@wdio/spec-reporter': '^9',
+        '@wdio/allure-reporter': '^9',
         'cross-env': '^7',
         'ts-node': '^10',
         typescript: '^5',
@@ -77,10 +78,14 @@ export function wdioWebConf(apiPort = 4000) {
   framework: 'mocha',
   mochaOpts: {
     ui: 'bdd',
-    timeout: 300000,
+    // Interactive/agent sessions are held open inside ONE long-lived mocha test; WDIO
+    // (@wdio/utils) would otherwise kill it at this timeout (default 5 min) and force a
+    // mid-run restart. Lift it for agent mode with a large FINITE value — NEVER 0, which
+    // in WDIO yields a negative (instant-firing) timeout, the opposite of mocha's "disable".
+    timeout: (process.env.HEALIX_AGENT === '1' || process.env.HEALIX_INTERACTIVE === 'true') ? 86400000 : 300000,
   },
 
-  reporters: ['spec'],
+  reporters: ['spec', ['allure', { outputDir: 'allure-results' }]],
 
   suites: {
     smoke:   ['./test/specs/smoke/**/*.spec.ts'],
@@ -116,7 +121,7 @@ export function wdioWebConf(apiPort = 4000) {
     },
   }]],
 
-  waitforTimeout: 10000,
+  waitforTimeout: 5000,
   connectionRetryTimeout: 120000,
   connectionRetryCount: 3,
 
@@ -149,11 +154,66 @@ const REHYDRATE_REMINDER =
   'the scaffold tools. If the Healix guide is not currently in your context, run ' +
   'healix_guide before any scaffold/heal/run step — do not operate from memory of it.';
 
-// Tiny script the hook runs. Living in a FILE (not an inline `node -e`) avoids
-// cross-shell quoting hell — the hook command is just `node <path>`.
+// The ONE script every host runs to re-anchor the agent. Living in a FILE (not an
+// inline `node -e`) avoids cross-shell quoting hell — the hook command is just
+// `node <path>`. It is host-agnostic: the SAME file is referenced by both
+//   • .claude/settings.json  (Spryv + Claude Code SessionStart)  → wants PLAIN TEXT stdout
+//   • .cursor/hooks.json      (Cursor sessionStart)              → wants JSON {additional_context}
+// We detect Cursor from its stdin payload (it sends composer_mode / is_background_agent)
+// and emit JSON for it; everyone else gets plain text, which both Spryv (captures hook
+// stdout) and Claude Code (adds SessionStart stdout to context) inject verbatim. Cursor
+// has no post-compaction inject event, so its sessionStart additional_context is seeded
+// into the persistent system context — where it survives compaction.
 export function claudeRehydrateScript() {
-  return `// Printed into the agent's context by the SessionStart hook (startup + after compaction).\n` +
-    `console.log(${JSON.stringify(REHYDRATE_REMINDER)});\n`;
+  return `// Re-anchors the agent on the Healix workflow at session start and after a context
+// compaction. Host-agnostic — referenced by .claude/settings.json (Spryv + Claude Code)
+// AND .cursor/hooks.json (Cursor). Cursor wants JSON; the others want plain text.
+const REMINDER = ${JSON.stringify(REHYDRATE_REMINDER)};
+
+let buf = '';
+let settled = false;
+function settle() {
+  if (settled) return;
+  settled = true;
+  let host = null;
+  try { host = buf.trim() ? JSON.parse(buf) : null; } catch { host = null; }
+  // composer_mode / is_background_agent are Cursor-only stdin keys.
+  const isCursor = !!host && ('composer_mode' in host || 'is_background_agent' in host);
+  if (isCursor) process.stdout.write(JSON.stringify({ additional_context: REMINDER }));
+  else process.stdout.write(REMINDER + '\\n');
+}
+try {
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (c) => { buf += c; });
+  process.stdin.on('end', settle);
+  process.stdin.on('error', settle);
+} catch { /* no stdin — the timer below settles it */ }
+// Hosts that ignore stdin (Spryv pipes /dev/null) may not emit 'end' reliably; a short
+// unref'd timer guarantees we print exactly once without keeping the process alive.
+const t = setTimeout(settle, 60);
+if (t && t.unref) t.unref();
+`;
+}
+
+// Cursor 1.7+ hook config — Cursor reads .cursor/hooks.json (NOT .claude/settings.json)
+// and its hooks speak a stdin-JSON → stdout-JSON contract. `sessionStart` returns
+// { additional_context } which Cursor injects into the agent's system context. (Cursor's
+// only compaction event, `preCompact`, is observational and cannot inject — so seeding at
+// sessionStart, which persists through compaction, is the correct re-hydration vehicle.)
+// The command runs the SAME shared script as the Claude/Spryv hook — one source of truth.
+export function cursorHooks() {
+  return JSON.stringify(
+    {
+      version: 1,
+      hooks: {
+        sessionStart: [
+          { command: 'node .claude/healix-rehydrate.mjs', type: 'command' },
+        ],
+      },
+    },
+    null,
+    2,
+  );
 }
 
 // Claude Code-format SessionStart hook (host-agnostic: read by any host that