wkappbot-code 0.3.10 → 0.3.11

package/bin/postinstall.js

@@ -2,71 +2,86 @@
 // wkappbot-code postinstall -- npm runs this after `npm install wkappbot-code` (local or -g).
 // Owner order 2026-11-06: the Default cloud environment's setup script is `npm install wkappbot-code`, and new cloud
 // ROOTs still started with no hooks, because the package had no install script and npm only copied files.
+// Owner order 2026-11-08: "npm install wkappbot-code should do the initial setup and the tests automatically" -- on
+// Windows, macOS and Linux alike, not only on a cloud VM.
 // CONTRACT: (a) ALWAYS exits 0 and returns within a moment -- the real work runs DETACHED and logs to
-// ~/.wkappbot-code/postinstall.log, then writes ~/.wkappbot-code/postinstall.done; (b) on a Claude Code cloud VM
-// (CLAUDE_CODE_REMOTE set, or a Linux HOME of /root that holds .claude) it runs `wkappbot-code install --no-npm`,
-// which lays the web harness, wires ~/.claude/settings.json (PreToolUse, Stop, UserPromptSubmit, SessionStart through
-// the lite harness), the global git hooks, the wkskill/wk-verify shims and the public skills, keeping every user
-// setting; idempotent: a done marker of the same version skips it; (c) on any other machine it only prints the one
-// command to run. WKAPPBOT_CODE_NO_POSTINSTALL=1 skips it (the selftest sets it so npm-installs in its cases never
-// touch the machine running it). WKAPPBOT_CODE_DEV_SEAT=1 adds --dev-seat (the full pwsh harness instead of lite);
-// WKAPPBOT_CODE_INSTALL_ARGS adds install flags. A user install takes the lite harness: on a stranger's cloud VM the
-// owner's full fleet harness (busy-fleet, letter gates, emergency-edit) would be the wrong default.
+// ~/.wkappbot-code/postinstall.log; (b) the worker runs `wkappbot-code install --no-npm` (lays the web harness, wires
+// ~/.claude/settings.json through the lite harness -- PreToolUse, Stop, UserPromptSubmit, SessionStart -- the global git
+// hooks, the wkskill/wk-verify shims and the public skills, keeping every user setting), then `wkappbot-code doctor`,
+// then a short self-test (lib/setup-run.js: core --version, skill read on-load, one hook allow, one hook refuse), and
+// writes ~/.wkappbot-code/postinstall.done {version, installRc, doctor:{pass,warn,fail,skip}, selftest:{n,m}, ...};
+// postinstall.running exists while the worker lives; (c) the first `wkappbot-code` run afterwards prints ONE summary
+// line (lib/setup-run.js printBanner) and opens OpenCode; (d) idempotent: a done file of the same version with
+// installRc 0 skips the rerun. WKAPPBOT_CODE_NO_POSTINSTALL=1 skips everything (the selftest sets it so npm-installs
+// in its cases never touch the machine running it). WKAPPBOT_CODE_DEV_SEAT=1 adds --dev-seat (the full pwsh harness
+// instead of lite); WKAPPBOT_CODE_INSTALL_ARGS adds install flags. A user install takes the lite harness: on a
+// stranger's machine the owner's full fleet harness (busy-fleet, letter gates, emergency-edit) would be the wrong default.
 // Spec: wkappbot skill read agent-harness-landscape-2026-howto
-import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { buildDone, files, markRunning, parseDoctor, platformOf, selfTest, writeDone } from "../lib/setup-run.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const CLI = join(HERE, "wkappbot-code.js");
-const STATE = join(homedir(), ".wkappbot-code");
-const LOG = join(STATE, "postinstall.log");
-const DONE = join(STATE, "postinstall.done");
+const F = files(homedir());
+const STATE = F.dir, LOG = F.log, DONE = F.done;
 
 function version() {
   try { return JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version || "?"; } catch { return "?"; }
 }
-export function isCloudVm(env = process.env, home = homedir(), platform = process.platform) {
+export function isCloudVm(env = process.env, home = homedir(), platform = platformOf(env)) {
   if (env.CLAUDE_CODE_REMOTE) return true;
   return platform === "linux" && home === "/root" && existsSync(join(home, ".claude"));
 }
-function stamp(msg) { try { mkdirSync(STATE, { recursive: true }); writeFileSync(LOG, new Date().toISOString() + " " + msg + "\n", { flag: "a" }); } catch {} }
+function stamp(msg) { try { mkdirSync(STATE, { recursive: true }); appendFileSync(LOG, new Date().toISOString() + " " + msg + "\n"); } catch {} }
 
-// --run: the detached worker. Runs the installer to the end, then records the done marker with its exit code.
+// --run: the detached worker. install, then doctor, then the self-test, then the done file.
 async function runWorker() {
   const args = [CLI, "install", "--no-npm"];
   if (process.env.WKAPPBOT_CODE_DEV_SEAT === "1") args.push("--dev-seat");
   // extra install flags, e.g. "--no-bin --no-skills" (the selftest; a seat without the SDK release assets)
   args.push(...String(process.env.WKAPPBOT_CODE_INSTALL_ARGS || "").split(/\s+/).filter((a) => /^--[a-z-]+$/.test(a)));
+  // the children are the worker's own: they must not print the first-run banner (it is for the user's next command)
+  const env = { ...process.env, WKAPPBOT_CODE_NO_UPDATE_CHECK: "1", WKAPPBOT_CODE_SETUP_WORKER: "1" };
   stamp("worker start: node " + args.join(" "));
   const out = openSync(LOG, "a");
-  const rc = await new Promise((res) => {
-    const c = spawn(process.execPath, args, { stdio: ["ignore", out, out], env: { ...process.env, WKAPPBOT_CODE_NO_UPDATE_CHECK: "1" } });
+  const installRc = await new Promise((res) => {
+    const c = spawn(process.execPath, args, { stdio: ["ignore", out, out], env });
     c.on("error", () => res(-1));
     c.on("close", (code) => res(code ?? -1));
   });
-  try { writeFileSync(DONE, JSON.stringify({ version: version(), rc, at: new Date().toISOString() }) + "\n"); } catch {}
-  stamp("worker done rc " + rc);
+  stamp("install rc " + installRc + "; doctor");
+  const dr = spawnSync(process.execPath, [CLI, "doctor"], { encoding: "utf8", env, timeout: 300000 });
+  const dtext = (dr.stdout || "") + (dr.stderr || "");
+  try { appendFileSync(LOG, dtext); } catch {}
+  const doctor = parseDoctor(dtext);
+  stamp("doctor pass " + doctor.pass + " warn " + doctor.warn + " fail " + doctor.fail + " skip " + doctor.skip + "; self-test");
+  let st = { n: 0, m: 4, items: [{ ok: false, name: "self-test", detail: "did not run" }] };
+  try { st = selfTest({ env, home: homedir() }); } catch (e) { st.items[0].detail = String(e); }
+  for (const i of st.items) stamp("selftest " + (i.ok ? "PASS " : "FAIL ") + i.name + (i.ok ? "" : " -- " + i.detail));
+  try { writeDone(homedir(), buildDone({ version: version(), installRc, doctor, selftest: st, env: process.env })); } catch (e) { stamp("done file error: " + e); }
+  stamp("worker done: install rc " + installRc + ", doctor " + doctor.pass + "/" + (doctor.pass + doctor.warn + doctor.fail) + ", selftest " + st.n + "/" + st.m);
 }
 
 function main() {
   if (process.argv[2] === "--run") return runWorker().catch(() => {}).finally(() => process.exit(0));
   if (process.env.WKAPPBOT_CODE_NO_POSTINSTALL === "1") return;
-  if (!isCloudVm()) {
-    console.log("[wkappbot-code] installed. To wire the harness and OpenCode on this machine run: npx wkappbot-code install   (then: wkappbot-code doctor)");
-    return;
-  }
+  const cloud = isCloudVm();
   try {
     const d = JSON.parse(readFileSync(DONE, "utf8"));
-    if (d.version === version() && d.rc === 0) { console.log("[wkappbot-code] cloud VM: harness already wired by " + d.version + " (" + DONE + ")"); return; }
+    if (d.version === version() && (d.installRc ?? d.rc) === 0) { console.log("[wkappbot-code] already set up by " + d.version + " (" + DONE + ")"); return; }
   } catch {}
   mkdirSync(STATE, { recursive: true });
+  markRunning(homedir(), version());
   const out = openSync(LOG, "a");
-  const c = spawn(process.execPath, [fileURLToPath(import.meta.url), "--run"], { detached: true, stdio: ["ignore", out, out], env: process.env });
+  const c = spawn(process.execPath, [fileURLToPath(import.meta.url), "--run"], { detached: true, stdio: ["ignore", out, out], env: process.env, windowsHide: true });
   c.unref();
-  console.log("[wkappbot-code] cloud VM detected: wiring the Claude Code harness in the background (log: " + LOG + ", done marker: " + DONE + ")");
+  console.log("[wkappbot-code] " + (cloud ? "cloud VM detected: wiring the Claude Code harness in the background" : "setting up in the background (install, doctor, self-test)") +
+    " (log: " + LOG + ", result: " + DONE + "); the first `wkappbot-code` run prints the summary");
 }
 
 try { main(); } catch (e) { try { stamp("postinstall error: " + e); } catch {} }

package/bin/wkappbot-code.js

@@ -40,6 +40,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { quietCheck, runUpdate, updateRow } from "../lib/update.js"; import { rmTreeHard } from "../lib/rmtree.js"; import { plainFileUrl } from "../lib/fileurl.js";
 import { applySets, askEach, buildConfig, configRow, detect, lineDiff, printDetected } from "../lib/config.js";
+import { launchOpenCode, printBanner } from "../lib/setup-run.js";
 
 const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf8"));
@@ -616,6 +617,10 @@ if (["install", "doctor", "config"].includes(o.cmd) && !o.update) {
   const nv = quietCheck(PKG.version, console.log);
   if (nv && (o.autoUpdate || process.env.WKAPPBOT_CODE_AUTO_UPDATE === "1")) upd();
 }
+// The one-line result of the automatic post-install setup (lib/setup-run.js), once; not for the worker's own children.
+if (!["--version", "-v", "version", "uninstall"].includes(o.cmd) && process.env.WKAPPBOT_CODE_SETUP_WORKER !== "1") { try { printBanner(); } catch {} }
+// Bare `wkappbot-code`: open OpenCode (its start screen); no opencode on PATH falls through to the usage below.
+if (process.argv.length <= 2 && o.cmd === "help") { const rc = launchOpenCode(); if (rc !== null) process.exit(rc); }
 switch (o.cmd) {
   case "--version": case "-v": case "version":
     console.log("wkappbot-code " + PKG.version + " (opencode-ai " + OPENCODE_VERSION + ")"); process.exit(0);

package/lib/setup-run.js

@@ -0,0 +1,135 @@
+// wkappbot-code lib/setup-run.js -- what `npm install wkappbot-code` does after the files land, and what the first
+// `wkappbot-code` run says about it (owner order 2026-11-08: "npm install wkappbot-code should do the initial setup and
+// the tests automatically", "typing wkappbot-code should show the OpenCode start screen").
+//   worker  bin/postinstall.js --run: install --no-npm, then doctor, then selfTest() below, then ONE postinstall.done
+//           JSON {version, installRc, rc, doctor:{pass,warn,fail,skip}, selftest:{n,m}, platform, at, items}.
+//   banner  bannerFor() / printBanner(): the one line the first run prints ("setup ok, doctor 9/9, selftest 4/4", the
+//           failing item with the log path, or "setup still running"), shown ONCE per done file (postinstall.seen).
+// Files in ~/.wkappbot-code: postinstall.log, postinstall.running (worker alive), postinstall.done, postinstall.seen.
+// A user's own settings.json entries are the installer's job to keep (wkappbot-code.js install); this module only reads.
+// Spec: wkappbot skill read agent-harness-landscape-2026-howto
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNNING_STALE_MS = 30 * 60 * 1000;   // a worker that left no done file for 30 minutes is dead, not "still running"
+const IS_WIN = process.platform === "win32";
+
+// WKAPPBOT_CODE_FAKE_PLATFORM is the selftest's way to run the non-cloud road "as win32 / darwin" on one machine.
+export const platformOf = (env = process.env) => env.WKAPPBOT_CODE_FAKE_PLATFORM || process.platform;
+export const stateDir = (home = homedir()) => join(home, ".wkappbot-code");
+export const files = (home = homedir()) => {
+  const d = stateDir(home);
+  return { dir: d, log: join(d, "postinstall.log"), running: join(d, "postinstall.running"), done: join(d, "postinstall.done"), seen: join(d, "postinstall.seen") };
+};
+const readJson = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
+// Same MSYS rule as wkappbot-code.js shPath: the sh Git for Windows starts reads "D:\a\x" as host D.
+const shPath = (p) => (IS_WIN && /^[A-Za-z]:[\\/]/.test(p) ? "/" + p[0].toLowerCase() + p.slice(2).replace(/\\/g, "/") : p);
+
+// ---- doctor ---------------------------------------------------------------------------------------
+// doctor prints one `PASS|WARN|FAIL|SKIP name  detail` row per part; SKIP rows are not counted in the n/m.
+export function parseDoctor(text) {
+  const c = { pass: 0, warn: 0, fail: 0, skip: 0, failed: [] };
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const m = /^(PASS|WARN|FAIL|SKIP) (\S+)/.exec(line);
+    if (!m) continue;
+    c[m[1].toLowerCase()]++;
+    if (m[1] === "FAIL") c.failed.push(m[2]);
+  }
+  return c;
+}
+
+// ---- self-test ------------------------------------------------------------------------------------
+function installState(env, home) {
+  const cfg = env.OPENCODE_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(home, ".config"), "opencode");
+  return readJson(join(cfg, "wkappbot-code", "install-state.json")) || {};
+}
+const hookPayload = (cmd) => JSON.stringify({ hook_event_name: "PreToolUse", session_id: "wkappbot-code-selftest", cwd: tmpdir(), tool_name: "Bash", tool_input: { command: cmd } });
+
+// Four items: the core answers --version, the core prints skill on-load, the lite hook ALLOWS a plain command (rc 0) and
+// REFUSES git --no-verify (rc 2). Returns {n, m, items:[{name, ok, detail}]}.
+export function selfTest({ env = process.env, home = homedir() } = {}) {
+  const st = installState(env, home);
+  const dest = (st.bin && st.bin.dest) || env.WK_BIN_DEST || join(home, ".local", "share", "wkappbot", IS_WIN ? "wkappbot.exe" : "wkappbot");
+  const kih = st.kihDir || env.WK_HARNESS_DIR || join(home, ".wk-harness");
+  const lite = join(kih, "tools", "wkharness-lite.sh");
+  const items = [];
+  const add = (name, ok, detail) => items.push({ name, ok: !!ok, detail: String(detail || "").replace(/\s+/g, " ").slice(0, 200) });
+  const scratch = mkdtempSync(join(tmpdir(), "wk-appbot-selftest-"));
+  const shell = IS_WIN && /\.(cmd|bat)$/i.test(dest);   // node refuses to start a .cmd without a shell
+  try {
+    const core = (args) => (existsSync(dest) ? spawnSync(dest, args, { encoding: "utf8", timeout: 120000, cwd: scratch, shell, env: { ...env, WKAPPBOT_NO_REMOTE_CHECK: "1" } }) : null);
+    let r = core(["--version"]);
+    add("core --version", r && r.status === 0 && (r.stdout || "").trim(), r ? "rc " + r.status + " " + (r.stdout || r.stderr) : dest + " absent");
+    r = core(["skill", "read", "on-load"]);
+    add("skill read on-load", r && /\bID\s*:\s*on-load\b/.test(r.stdout || ""), r ? "rc " + r.status : dest + " absent");
+    const hook = (cmd) => (existsSync(lite)
+      ? spawnSync("sh", [shPath(lite), "pre"], { encoding: "utf8", timeout: 60000, input: hookPayload(cmd), env: { ...env, WKHARNESS_LITE_DIR: shPath(join(scratch, "lite")) } }) : null);
+    r = hook("ls /");
+    add("hook allow", r && r.status === 0, r ? "rc " + r.status + " " + (r.stderr || "") : lite + " absent");
+    r = hook("git commit --no-verify -m selftest");
+    add("hook refuse", r && r.status === 2, r ? "rc " + r.status + " " + (r.stderr || "") : lite + " absent");
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+  return { n: items.filter((i) => i.ok).length, m: items.length, items };
+}
+
+// ---- done / running -------------------------------------------------------------------------------
+export function markRunning(home, version) {
+  const f = files(home);
+  mkdirSync(f.dir, { recursive: true });
+  rmSync(f.done, { force: true });   // the old verdict belongs to the old install
+  writeFileSync(f.running, JSON.stringify({ version, at: new Date().toISOString(), pid: process.pid }) + "\n");
+}
+export function writeDone(home, rec) {
+  const f = files(home);
+  const tmp = f.done + ".tmp";
+  writeFileSync(tmp, JSON.stringify(rec) + "\n");
+  renameSync(tmp, f.done);   // the done file appears whole or not at all (the selftest polls for it)
+  rmSync(f.running, { force: true });
+}
+export function buildDone({ version, installRc, doctor, selftest, env = process.env }) {
+  return { version, installRc, rc: installRc, doctor: { pass: doctor.pass, warn: doctor.warn, fail: doctor.fail, skip: doctor.skip },
+    selftest: { n: selftest.n, m: selftest.m }, platform: platformOf(env), at: new Date().toISOString(),
+    items: selftest.items.filter((i) => !i.ok).map((i) => i.name + ": " + i.detail), doctorFailed: doctor.failed };
+}
+
+// ---- banner ---------------------------------------------------------------------------------------
+// Pure: the line to print for a state ("" = nothing to say) and whether it counts as seen. `now` is a ms clock.
+export function bannerFor({ done, running, seen, logPath, now = Date.now() }) {
+  if (running && !done) {
+    const age = now - Date.parse(running.at || 0);
+    if (age >= 0 && age < RUNNING_STALE_MS) return { line: "[wkappbot-code] setup still running (log: " + logPath + ") -- opening OpenCode anyway", mark: false };
+    return { line: "[wkappbot-code] setup did not finish (worker started " + (running.at || "?") + ", no result); log: " + logPath + " -- rerun: wkappbot-code install", mark: false };
+  }
+  if (!done || (seen && seen === done.at)) return { line: "", mark: false };
+  const d = done.doctor || {}, s = done.selftest || {};
+  const total = (d.pass || 0) + (d.warn || 0) + (d.fail || 0);
+  const tail = "doctor " + (d.pass || 0) + "/" + total + (d.warn ? " (" + d.warn + " warn)" : "") + ", selftest " + (s.n || 0) + "/" + (s.m || 0);
+  const installRc = done.installRc ?? done.rc;
+  if (installRc === 0 && !d.fail && s.n === s.m && s.m > 0) return { line: "[wkappbot-code] setup ok, " + tail, mark: true };
+  const bad = [];
+  if (installRc !== 0) bad.push("install rc " + installRc);
+  for (const f of done.doctorFailed || []) bad.push("doctor " + f + " FAIL");
+  for (const i of done.items || []) bad.push("selftest " + i);
+  if (!bad.length) bad.push(d.fail ? "doctor " + d.fail + " FAIL" : "selftest " + (s.n || 0) + "/" + (s.m || 0));
+  return { line: "[wkappbot-code] setup needs attention: " + bad.slice(0, 3).join("; ") + " (" + tail + "); log: " + logPath, mark: true };
+}
+export function printBanner({ home = homedir(), out = console.log, now = Date.now() } = {}) {
+  const f = files(home);
+  const done = readJson(f.done), running = readJson(f.running);
+  let seen = ""; try { seen = readFileSync(f.seen, "utf8").trim(); } catch {}
+  const b = bannerFor({ done, running, seen, logPath: f.log, now });
+  if (b.line) out(b.line);
+  if (b.mark && done) { try { writeFileSync(f.seen, done.at + "\n"); } catch {} }
+  return b.line;
+}
+
+// ---- bare launch ----------------------------------------------------------------------------------
+// `wkappbot-code` with no arguments opens OpenCode (its start screen). Returns the exit code, or null when opencode
+// cannot be started (not on PATH): the caller then prints the usage as before.
+export function launchOpenCode(env = process.env) {
+  const r = spawnSync("opencode", [], { stdio: "inherit", shell: IS_WIN, env });
+  if (r.error) return null;
+  return r.status ?? 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wkappbot-code",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "wkappbot-code -- Wisdom Kernel: the pinned OpenCode bridge plus the reflex harness plugin, the wkappbot core, the web harness and the latest public skills in one install",
   "type": "module",
   "scripts": {