@haus-tech/haus-workflow 3.1.2 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [4.0.0](https://github.com/WeAreHausTech/haus-workflow/compare/v3.1.2...v4.0.0) (2026-08-20)
+
+### ⚠ BREAKING CHANGES
+
+- **init:** stdout is `{ scan, recommendation, hooks,
+repoName, warnings }`, not scan-then-recommend documents plus
+  human doctor lines. Callers that parsed the first document as
+  the scan must read `envelope.scan`.
+
+### Bug Fixes
+
+- **init:** emit one JSON envelope on --json ([#318](https://github.com/WeAreHausTech/haus-workflow/issues/318)) ([2657428](https://github.com/WeAreHausTech/haus-workflow/commit/2657428a47a2459d3a1ccdc3a9137f9553ccb3d7)), closes [#306](https://github.com/WeAreHausTech/haus-workflow/issues/306)
+- surface worktree hydrate install failure diagnostics ([#319](https://github.com/WeAreHausTech/haus-workflow/issues/319)) ([3fb6a53](https://github.com/WeAreHausTech/haus-workflow/commit/3fb6a53c00471e5b4c9aa0658cd19806785db717))
+
 ## [3.1.2](https://github.com/WeAreHausTech/haus-workflow/compare/v3.1.1...v3.1.2) (2026-08-20)
 
 ### Bug Fixes

package/dist/cli.js

@@ -10014,6 +10014,9 @@ async function hasMultipleSiblingRepos(root) {
 init_fs();
 init_logger();
 init_paths();
+function emitJsonEnvelope(json, quiet, envelope) {
+  if (json && !quiet) log(JSON.stringify(envelope, null, 2));
+}
 async function readPriorManualIncludes(root) {
   const prior = await readJson(hausPath(root, "recommendation.json"));
   if (!prior?.recommended) return [];
@@ -10021,16 +10024,12 @@ async function readPriorManualIncludes(root) {
 }
 async function runSetupCore(root, opts) {
   const { json, apply, dryRun, quiet, confirm: confirm2, force } = opts;
-  const say = quiet ? () => {
+  const say = quiet || json ? () => {
   } : log;
   const scanResult = await scanProject(root);
-  if (json) {
-    say(JSON.stringify(scanResult, null, 2));
-  } else {
-    say("Haus scan complete");
-    say(`Roles: ${scanResult.repoRoles.join(", ") || "unknown"}`);
-    say(`Package manager: ${scanResult.packageManager}`);
-  }
+  say("Haus scan complete");
+  say(`Roles: ${scanResult.repoRoles.join(", ") || "unknown"}`);
+  say(`Package manager: ${scanResult.packageManager}`);
   const siblingWarning = await hasMultipleSiblingRepos(root) ? [SIBLING_REPO_WARNING] : [];
   const context = await readContextOrScan(root);
   const priorManualIncludes = await readPriorManualIncludes(root);
@@ -10043,39 +10042,39 @@ async function runSetupCore(root, opts) {
     const warningLines2 = [
       .../* @__PURE__ */ new Set([...context.warnings, ...recommendation.warnings ?? [], ...siblingWarning])
     ];
-    if (json) {
-      say(JSON.stringify(recommendation, null, 2));
-    } else {
-      say("Haus recommendation ready");
-      say("Recommended: 0");
-      say(`Skipped: ${recommendation.skipped.length}`);
-      say(`Repo: ${context.repoName}`);
-      for (const warning of warningLines2) say(`- WARN: ${warning}`);
-    }
+    say("Haus recommendation ready");
+    say("Recommended: 0");
+    say(`Skipped: ${recommendation.skipped.length}`);
+    say(`Repo: ${context.repoName}`);
+    for (const warning of warningLines2) say(`- WARN: ${warning}`);
     const supersededCount = recommendation.skipped.filter(
       (s) => s.skipReasons?.some((r) => r.code === "superseded-by-global-plugin")
     ).length;
     const message2 = supersededCount > 0 ? `No catalog items matched this project after ${supersededCount} item(s) were gated as already provided by an installed global plugin \u2014 refusing to write recommendation.json/haus.lock.json. Those skills are available globally; re-run with \`haus init --force\` to write anyway.` : "No catalog items matched this project at all (zero signal) \u2014 refusing to write recommendation.json/haus.lock.json. Re-run with `haus init --force` to write anyway.";
     warn(message2);
     process.exitCode = 1;
+    const warnings = [...warningLines2, message2];
+    emitJsonEnvelope(json, quiet, {
+      scan: scanResult,
+      recommendation,
+      hooks: null,
+      repoName: context.repoName,
+      warnings
+    });
     return {
       root,
       repoName: context.repoName,
       roles: scanResult.repoRoles,
       recommendedCount: 0,
-      warnings: [...warningLines2, message2],
+      warnings,
       hooksOk: false,
       written: []
     };
   }
   await writeJson(hausPath(root, "recommendation.json"), recommendation);
-  if (json) {
-    say(JSON.stringify(recommendation, null, 2));
-  } else {
-    say("Haus recommendation ready");
-    say(`Recommended: ${recommendation.recommended.length}`);
-    say(`Skipped: ${recommendation.skipped.length}`);
-  }
+  say("Haus recommendation ready");
+  say(`Recommended: ${recommendation.recommended.length}`);
+  say(`Skipped: ${recommendation.skipped.length}`);
   const hooks = await verifyProjectSettingsHooksContract(root);
   const warningLines = [
     .../* @__PURE__ */ new Set([...context.warnings, ...recommendation.warnings ?? [], ...siblingWarning])
@@ -10100,12 +10099,23 @@ async function runSetupCore(root, opts) {
     hooksOk,
     written: []
   };
-  if (!apply) return baseResult;
+  const envelope = (hooksResult) => ({
+    scan: scanResult,
+    recommendation,
+    hooks: hooksResult,
+    repoName: context.repoName,
+    warnings: warningLines
+  });
+  if (!apply) {
+    emitJsonEnvelope(json, quiet, envelope(hooks));
+    return baseResult;
+  }
   if (confirm2) {
     const approved = await confirm2();
     if (!approved) {
       say("Setup reviewed. No files written.");
       say("Next step: run `haus apply --write` when ready.");
+      emitJsonEnvelope(json, quiet, envelope(hooks));
       return baseResult;
     }
   }
@@ -10115,6 +10125,7 @@ async function runSetupCore(root, opts) {
     if (sync.formatRefusal) {
       error(sync.formatRefusal);
       process.exitCode = 1;
+      emitJsonEnvelope(json, quiet, envelope(hooks));
       return baseResult;
     }
     if (sync.newItems.length > 0) {
@@ -10142,6 +10153,7 @@ async function runSetupCore(root, opts) {
   } else {
     say(`- HOOKS OK: ${hooksAfter.message}`);
   }
+  emitJsonEnvelope(json, quiet, envelope(hooksAfter));
   return { ...baseResult, hooksOk: hooksOkAfter, written: files };
 }
 
@@ -11926,9 +11938,72 @@ async function computeLockfileSignals(dir) {
     hasDotnetProject
   };
 }
+var INSTALL_OUTPUT_CAP = 8192;
+var INSTALL_TAIL_LINES = 8;
+function capTail(text, max = INSTALL_OUTPUT_CAP) {
+  return text.length <= max ? text : text.slice(-max);
+}
+function nonemptyLines(text) {
+  return text.split(/\r?\n/).filter((line2) => line2.trim().length > 0);
+}
+function findRequiredYarnrcEnvVars(content2) {
+  const required = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+  const names = /* @__PURE__ */ new Set();
+  for (const line2 of content2.split(/\r?\n/)) {
+    if (line2.trimStart().startsWith("#")) continue;
+    required.lastIndex = 0;
+    let match;
+    while ((match = required.exec(line2)) !== null) {
+      const name = match[1];
+      if (name !== void 0) names.add(name);
+    }
+  }
+  return [...names];
+}
+function missingYarnrcEnvVars(content2, env) {
+  return findRequiredYarnrcEnvVars(content2).filter((name) => env[name] === void 0);
+}
+function missingYarnrcEnvVarsInDir(dir, env) {
+  const yarnrcPath = path59.join(dir, ".yarnrc.yml");
+  if (!existsSync3(yarnrcPath)) return [];
+  try {
+    return missingYarnrcEnvVars(readFileSync3(yarnrcPath, "utf8"), env);
+  } catch {
+    return [];
+  }
+}
+function tailInstallOutput(stdout2, stderr) {
+  const errLines = nonemptyLines(stderr).slice(-INSTALL_TAIL_LINES);
+  const remaining = INSTALL_TAIL_LINES - errLines.length;
+  const outLines = remaining > 0 ? nonemptyLines(stdout2).slice(-remaining) : [];
+  return [...errLines, ...outLines].join("\n");
+}
+function summarizeInstall(install) {
+  if (install.plan.manager === "none") return "no install step (no recognized lockfile)";
+  const envNotes = (install.missingEnvVars ?? []).map(
+    (name) => `${name} not set in environment \u2014 yarn install will fail`
+  );
+  if (!install.ran) {
+    const skip = `install skipped (${install.skippedReason ?? "unavailable"})`;
+    return envNotes.length > 0 ? [skip, ...envNotes].join("\n    ") : skip;
+  }
+  if (install.ok) return `hydrated via ${install.plan.manager}`;
+  const head = `install FAILED via ${install.plan.manager}`;
+  const tail = tailInstallOutput(install.stdout ?? "", install.stderr ?? "");
+  const details = [...envNotes, ...tail.length > 0 ? tail.split("\n") : []];
+  return details.length > 0 ? [head, ...details].join("\n    ") : head;
+}
+function withMissingEnv(result, missingEnvVars) {
+  return missingEnvVars.length > 0 ? { ...result, missingEnvVars } : result;
+}
 async function runInstallPlan(dir, plan, deps = {}) {
+  const env = deps.env ?? process.env;
+  const missingEnvVars = plan.manager === "yarn" ? missingYarnrcEnvVarsInDir(dir, env) : [];
   if (plan.manager === "none") {
-    return { plan, ran: false, ok: true, skippedReason: "no recognized lockfile" };
+    return withMissingEnv(
+      { plan, ran: false, ok: true, skippedReason: "no recognized lockfile" },
+      missingEnvVars
+    );
   }
   const probe = deps.probe ?? probeCommand;
   const probed = await probe(plan.command);
@@ -11936,25 +12011,41 @@ async function runInstallPlan(dir, plan, deps = {}) {
     case "available":
       break;
     case "absent":
-      return { plan, ran: false, ok: true, skippedReason: `${plan.command} not found on PATH` };
+      return withMissingEnv(
+        { plan, ran: false, ok: true, skippedReason: `${plan.command} not found on PATH` },
+        missingEnvVars
+      );
     case "inconclusive":
-      return {
-        plan,
-        ran: false,
-        ok: true,
-        skippedReason: `could not determine whether ${plan.command} is on PATH (${probed.reason})`
-      };
+      return withMissingEnv(
+        {
+          plan,
+          ran: false,
+          ok: true,
+          skippedReason: `could not determine whether ${plan.command} is on PATH (${probed.reason})`
+        },
+        missingEnvVars
+      );
     default:
       return assertNeverCommandProbe(probed);
   }
-  const result = await runCommand(plan.command, plan.args, { cwd: dir });
-  return {
-    plan,
-    ran: true,
-    ok: result.exitCode === 0,
-    exitCode: result.exitCode,
-    stderr: result.exitCode === 0 ? void 0 : result.stderr
-  };
+  const run = deps.run ?? runCommand;
+  const result = await run(plan.command, plan.args, { cwd: dir });
+  if (result.exitCode === 0) {
+    return withMissingEnv({ plan, ran: true, ok: true, exitCode: 0 }, missingEnvVars);
+  }
+  const stdout2 = capTail(result.stdout);
+  const stderr = capTail(result.stderr);
+  return withMissingEnv(
+    {
+      plan,
+      ran: true,
+      ok: false,
+      exitCode: result.exitCode,
+      stdout: stdout2.length > 0 ? stdout2 : void 0,
+      stderr: stderr.length > 0 ? stderr : void 0
+    },
+    missingEnvVars
+  );
 }
 
 // src/workspace/worktree/hydrate.ts
@@ -12629,10 +12720,11 @@ function emitJson(result) {
   log(JSON.stringify(result, null, 2));
 }
 function describeInstall(hydration) {
-  if (hydration.install.plan.manager === "none") return "no install step (no recognized lockfile)";
-  if (!hydration.install.ran)
-    return `install skipped (${hydration.install.skippedReason ?? "unavailable"})`;
-  return hydration.install.ok ? `hydrated via ${hydration.install.plan.manager}` : `install FAILED via ${hydration.install.plan.manager}`;
+  return summarizeInstall(hydration.install);
+}
+function emitMemberLine(hydration, line2) {
+  if (hydration?.install.ran && !hydration.install.ok) warn(line2);
+  else log(line2);
 }
 async function handleAdd(opts) {
   if (!opts.slug) {
@@ -12677,7 +12769,10 @@ async function handleAdd(opts) {
   for (const m of result.members) {
     if (m.status === "ok") {
       const hydrationNote = m.hydration ? describeInstall(m.hydration) : "not hydrated (--no-hydrate)";
-      log(`  ${m.member}: ${m.branchAction} "${m.branch}" \u2014 ${hydrationNote} (${m.durationMs}ms)`);
+      emitMemberLine(
+        m.hydration,
+        `  ${m.member}: ${m.branchAction} "${m.branch}" \u2014 ${hydrationNote} (${m.durationMs}ms)`
+      );
     } else {
       warn(`  ${m.member}: FAILED \u2014 ${m.error}`);
     }
@@ -12721,7 +12816,10 @@ async function handleHydrate(opts) {
   for (const r of result.results) {
     if (r.status === "ok" && r.hydration) {
       const materializedNote = r.branchAction ? `materialized (${r.branchAction}), ` : "";
-      log(`  ${r.member}: ${materializedNote}${describeInstall(r.hydration)}`);
+      emitMemberLine(
+        r.hydration,
+        `  ${r.member}: ${materializedNote}${describeInstall(r.hydration)}`
+      );
     } else {
       warn(`  ${r.member}: ${r.status}${r.error ? ` \u2014 ${r.error}` : ""}`);
     }
@@ -14058,7 +14156,7 @@ backups.command("prune").description("Delete old backups by age and/or count (re
   })
 );
 program.command("explain-recommendation").description("Print a per-item breakdown of the current recommendation, with skip reasons").option("--json").action(runExplainRecommendation);
-program.command("init").description("Full setup: scan, recommend, and optionally apply Claude files (safe to re-run)").option("--dry-run", "Preview the `.claude/` write; scan artifacts are still written").option("--json", "Machine-readable scan + recommendation documents (requires --dry-run)").option(
+program.command("init").description("Full setup: scan, recommend, and optionally apply Claude files (safe to re-run)").option("--dry-run", "Preview the `.claude/` write; scan artifacts are still written").option("--json", "Emit one JSON envelope on stdout (requires --dry-run)").option(
   "--force",
   "Write recommendation.json/haus.lock.json even when zero catalog items matched at all"
 ).action(runInit);

package/library/global/skills/haus-workflow/references/init.md

@@ -7,11 +7,11 @@ commands; they read plain language and approve.
 Do this in order:
 
 1. **Detect.** Run `haus init --json --dry-run`. Read the JSON yourself —
-   do not show it. Translate what was detected into one or two plain sentences,
-   e.g. "This looks like a Next.js website using Yarn. I found unit tests but no
-   end-to-end tests." If the detection status is `unknown` or `partial`, say so
-   honestly ("I couldn't fully recognise this stack, so I'll apply the general
-   workflow and security guidance").
+   do not show it. Stdout is one envelope: `{ scan, recommendation, hooks, repoName, warnings }`.
+   Translate `scan` into one or two plain sentences, e.g. "This looks like a Next.js
+   website using Yarn. I found unit tests but no end-to-end tests." If
+   `scan.detectionStatus` is `unknown` or `partial`, say so honestly ("I couldn't fully
+   recognise this stack, so I'll apply the general workflow and security guidance").
 
 2. **Apply the basics.** Run `haus apply --write`. Read the result. This installs
    the core guardrails and helpers — including the documentation skill haus uses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haus-tech/haus-workflow",
-  "version": "3.1.2",
+  "version": "4.0.0",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {