iterate-harness 1.12.8 → 1.12.9

package/README.md

@@ -44,6 +44,21 @@ If the install during `npm install` can't complete (no Python, no network, or
 the npm install, and `ih` still installs on its first run — a lazy fallback
 keeps the package usable either way.
 
+## Interactive experience
+
+`ih` greets you with a cyan **ITERATE** ASCII banner on every run (claude-code
+style), and the first install runs an **interactive wizard** like
+iterate-skill-installer:
+
+- It prints an "Installing" box with the pinned version and runtime location.
+- It asks `Install iterate-harness vX.Y.Z ...? [Y/n]` before downloading —
+  decline and it exits cleanly (code 0) instead of failing.
+- When done, it prints a "Done" box with getting-started tips (`ih --help`,
+  `ih status`, `ih iterate --help`).
+
+All UI output goes to **stderr**, so `ih --version | jq '...'` still gives you
+clean machine-readable stdout.
+
 The React TUI's frontend dependencies (`node_modules`) are installed
 automatically by the harness itself on first TUI launch — npm users always
 have Node, so the TUI always works.

package/README.zh-CN.md

@@ -37,6 +37,20 @@ harness 本身是**一个 Python 包**。这个 npm 包是一个薄分发包装
 `ITERATE_HARNESS_SKIP_INSTALL=1`），钩子只会打印提示而不让 npm 安装失败，
 `ih` 会在首次运行时补装——惰性兑底保证两种情况下包都可用。
 
+## 交互式体验
+
+每次运行 `ih`，都会出现青色 **ITERATE** ASCII 横幅（claude-code 风格）；首次安装
+会像 iterate-skill-installer 一样进入**交互式向导**：
+
+- 先打印 "Installing" 信息框，包含锁定的版本号与运行时目录。
+- 下载前询问 `Install iterate-harness vX.Y.Z ...? [Y/n]`——选否会以 0 退出码
+  干净退出而不是报错。
+- 装完打印 "Done" 信息框，附上快速上手提示（`ih --help`、`ih status`、
+  `ih iterate --help`）。
+
+所有交互输出都写到 **stderr**，所以 `ih --version | jq '...'` 得到的 stdout
+依旧干净、可机器解析。
+
 React TUI 的前端依赖（`node_modules`）会在首次启动 TUI 时由 harness 自动安装——
 npm 用户必然有 Node，所以 TUI 始终可用。
 

package/lib/bootstrap.js

@@ -36,6 +36,8 @@ const https = require("https");
 const os = require("os");
 const path = require("path");
 
+const ui = require("./ui");
+
 // ---------------------------------------------------------------------------
 // Constants (no magic strings below — everything is named here)
 // ---------------------------------------------------------------------------
@@ -72,6 +74,10 @@ const IS_WINDOWS = process.platform === "win32";
 
 class BootstrapError extends Error {}
 
+// Thrown when the user declines the interactive install wizard. Treated as a
+// graceful "nothing to do" exit (code 0), never as a failure.
+class CancelledError extends Error {}
+
 // ---------------------------------------------------------------------------
 // Pure helpers (unit-tested in test/bootstrap.test.js)
 // ---------------------------------------------------------------------------
@@ -467,13 +473,13 @@ async function bootstrap(homeDir, version, env) {
     fs.rmSync(venvDir, { recursive: true, force: true });
   }
   if (!fs.existsSync(activateMarker)) {
-    process.stderr.write(`[iterate-harness] creating virtualenv at ${venvDir} ...\n`);
+    ui.step(`Creating virtualenv at ${venvDir}`);
     runStep(interpreter.command, [...interpreter.preArgs, "-m", "venv", venvDir]);
   }
 
   const url = installUrl(version, env);
   const fallbackUrl = installFallbackUrl(version, env);
-  process.stderr.write(`[iterate-harness] installing iterate-harness ${version} ...\n`);
+  ui.step(`Installing iterate-harness ${version}`);
   await installHarness({
     python: executable.python,
     url,
@@ -487,10 +493,12 @@ async function bootstrap(homeDir, version, env) {
 
   const stampPath = path.join(homeDir, STAMP_FILE_NAME);
   fs.writeFileSync(stampPath, `${version}\n`, "utf8");
+  ui.success(`iterate-harness ${version} installed`);
 }
 
-async function ensureRuntime(env) {
+async function ensureRuntime(env, options) {
   const environment = env || process.env;
+  const opts = options || {};
   const version = packageVersion();
   const homeDir = runtimeHomeDir(environment);
   const venvDir = path.join(homeDir, VENV_DIR_NAME);
@@ -503,7 +511,30 @@ async function ensureRuntime(env) {
     : "";
 
   if (!skipInstall && needsBootstrap(stampContent, version)) {
+    if (opts.interactive) {
+      // Interactive install wizard: ask the user before downloading.
+      const confirmed = await ui.askYesNo(
+        `Install iterate-harness v${version} into ${homeDir}?`,
+        true
+      );
+      if (!confirmed) {
+        throw new CancelledError(
+          "Skipped installing iterate-harness. Re-run `ih` whenever you are ready."
+        );
+      }
+      ui.frameSection("Installing", [
+        `\x1b[36m◆\x1b[0m Version: v${version}`,
+        `\x1b[36m◆\x1b[0m Runtime:  ${homeDir}`,
+      ]);
+    }
     await bootstrap(homeDir, version, environment);
+    if (opts.interactive) {
+      ui.frameSection("Done", [
+        `\x1b[32m✓\x1b[0m iterate-harness v${version} installed`,
+        `  Run \x1b[36mih --help\x1b[0m to see all commands.`,
+        `  Try \x1b[36mih status\x1b[0m or \x1b[36mih iterate --help\x1b[0m to get started.`,
+      ]);
+    }
   }
 
   if (!fs.existsSync(executable.ih)) {
@@ -530,10 +561,19 @@ function reportBootstrapFailure(error) {
 }
 
 async function runHarness(args, env) {
+  // Print the banner on every run (claude-code style). Skipped automatically
+  // when stderr is not a TTY (e.g. piped output), so `ih --version | jq` stays clean.
+  ui.printBanner();
+
   let target;
   try {
-    target = await ensureRuntime(env);
+    target = await ensureRuntime(env, { interactive: true });
   } catch (error) {
+    if (error instanceof CancelledError) {
+      ui.info(error.message);
+      process.exit(0);
+      return;
+    }
     reportBootstrapFailure(error);
     process.exit(1);
     return;
@@ -567,6 +607,7 @@ async function runHarness(args, env) {
 
 module.exports = {
   BootstrapError,
+  CancelledError,
   DEFAULT_ARTIFACT_EXT,
   MAX_DOWNLOAD_REDIRECTS,
   MIN_PYTHON_MAJOR,

package/lib/ui.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/*
+ * Terminal UI helpers for the iterate-harness npm wrapper.
+ *
+ * Mirrors the style of iterate-skill-installer's interactive installer:
+ *   - ASCII banner (ITERATE brand)
+ *   - Colored step/success/warning/error/info prefixes
+ *   - Framed section box for summary
+ *   - Yes/no prompt for interactive choices
+ *
+ * Every function writes to stderr so piped stdout (e.g. `ih --version | jq`)
+ * is never polluted with UI noise. Non-TTY stderr silently skips the banner.
+ */
+
+const readline = require("node:readline");
+
+const ITERATE_BANNER = [
+  "██╗████████╗███████╗██████╗  █████╗ ████████╗███████╗",
+  "██║╚══██╔══╝██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝",
+  "██║   ██║   █████╗  ██████╔╝███████║   ██║   █████╗  ",
+  "██║   ██║   ██╔══╝  ██╔══██╗██╔══██║   ██║   ██╔══╝  ",
+  "██║   ██║   ███████╗██║  ██║██║  ██║   ██║   ███████╗",
+  "╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝",
+];
+
+function printBanner() {
+  if (!process.stderr.isTTY) return;
+  console.error();
+  for (const line of ITERATE_BANNER) {
+    console.error(`\x1b[36m${line}\x1b[0m`);
+  }
+  console.error(`\x1b[36m  iterate-harness\x1b[0m\x1b[2m · jingzhao-l/iterate-harness\x1b[0m`);
+  console.error();
+}
+
+function info(message) {
+  console.error(`\x1b[34mℹ\x1b[0m  ${message}`);
+}
+
+function success(message) {
+  console.error(`\x1b[32m✓\x1b[0m  ${message}`);
+}
+
+function warning(message) {
+  console.error(`\x1b[33m⚠\x1b[0m  ${message}`);
+}
+
+function error(message) {
+  console.error(`\x1b[31m✗\x1b[0m  ${message}`);
+}
+
+function step(message) {
+  console.error(`\x1b[36m◆\x1b[0m  ${message}`);
+}
+
+function hint(message) {
+  console.error(`\x1b[2m   ${message}\x1b[0m`);
+}
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function frameSection(title, lines) {
+  const maxLen = Math.max(
+    title.length,
+    ...lines.map((l) => stripAnsi(l).length),
+  );
+  const innerWidth = maxLen + 2;
+  const top = `┌─ ${title} ${"─".repeat(Math.max(0, innerWidth - title.length - 2))}┐`;
+  const bottom = `└${"─".repeat(innerWidth + 1)}┘`;
+  console.error(top);
+  for (const line of lines) {
+    const visibleLen = stripAnsi(line).length;
+    const padding = " ".repeat(Math.max(0, innerWidth - visibleLen));
+    console.error(`│ ${line}${padding}│`);
+  }
+  console.error(bottom);
+}
+
+function askYesNo(question, defaultNo = false) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    const hint = defaultNo ? "[y/N]" : "[Y/n]";
+    rl.question(`\x1b[36m◆\x1b[0m  ${question} ${hint} `, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      if (a === "y" || a === "yes") resolve(true);
+      else if (a === "n" || a === "no") resolve(false);
+      else resolve(defaultNo);
+    });
+  });
+}
+
+module.exports = {
+  ITERATE_BANNER,
+  printBanner,
+  info,
+  success,
+  warning,
+  error,
+  step,
+  hint,
+  stripAnsi,
+  frameSection,
+  askYesNo,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-harness",
-  "version": "1.12.8",
+  "version": "1.12.9",
   "description": "npm distribution wrapper for iterate-harness — installs the Python harness (ih CLI) into a managed venv on install and exposes it as a global command",
   "license": "MIT",
   "type": "commonjs",

package/scripts/postinstall.js

@@ -15,23 +15,21 @@
 "use strict";
 
 const { ensureRuntime, reportBootstrapFailure, SKIP_INSTALL_ENV_VAR } = require("../lib/bootstrap");
+const ui = require("../lib/ui");
 
 async function main() {
   if (process.env[SKIP_INSTALL_ENV_VAR] === "1") {
-    process.stderr.write(
-      `[iterate-harness] skipped install during npm install (${SKIP_INSTALL_ENV_VAR}=1); ` +
-        "the harness will be installed on the first `ih` run.\n"
-    );
+    ui.warning(`Skipped install during npm install (${SKIP_INSTALL_ENV_VAR}=1); harness installs on the first \`ih\` run.`);
     return;
   }
   try {
     await ensureRuntime();
-    process.stderr.write("[iterate-harness] harness installed during npm install.\n");
+    ui.success("iterate-harness installed during npm install — `ih` is ready to use.");
   } catch (error) {
     reportBootstrapFailure(error);
-    process.stderr.write(
-      "[iterate-harness] could not install the harness during npm install " +
-        "(see above). It will be retried automatically on the first `ih` run.\n"
+    ui.warning(
+      "Could not install the harness during npm install (see above). " +
+        "It will be retried automatically on the first `ih` run."
     );
   }
 }