@promptster/teams-cli 0.12.1 → 0.12.3

package/bin/promptster-teams.js

@@ -31,6 +31,41 @@ function usable(p) {
   }
 }
 
+// Converge the managed binary before choosing which one to run.
+//
+// npm is not a reliable place to hang this work any more: its install-script
+// approval gate can decline to run our postinstall while reporting a completely
+// successful install, so the managed binary — the one the daemon executes and
+// autostart points at — is never written and `autostart repair` never runs. The
+// engineer sees "added 2 packages" and a working CLI, and only the parts that
+// matter are missing. Doing it here means running the CLI at all converges the
+// machine, whatever npm decided about our scripts.
+//
+// Cost when there is nothing to do (the overwhelming case): one readFileSync of
+// a tiny marker file. No spawns, no stat of the bundled binary.
+//
+// `uninstall` is excluded — reinstalling the binary a person is in the middle of
+// removing is the one thing this must never do.
+try {
+  const {
+    installManagedBinary,
+    mayNeedInstall,
+    shouldConvergeOnInvocation,
+  } = require("../lib/install");
+  if (shouldConvergeOnInvocation(process.argv[2])) {
+    if (mayNeedInstall(require("../package.json").version)) {
+      // stderr, never stdout: this must not corrupt the output of the command
+      // the engineer actually ran (`version`, `status --json`, …).
+      const say = (msg) => console.error(`promptster-teams: ${msg}`);
+      installManagedBinary({ log: say, warn: say });
+    }
+  }
+} catch (err) {
+  // Never block the command. The worst case is the pre-existing behaviour: run
+  // the bundled binary and let npm's metadata drift.
+  console.error(`promptster-teams: could not check the managed install: ${err && err.message}`);
+}
+
 const bundled = bundledBinPath();
 
 // A project-local install runs ITS OWN binary, never the shared managed one.

package/lib/install.js

@@ -0,0 +1,272 @@
+"use strict";
+
+// Installing the managed binary, shared by postinstall AND the launcher.
+//
+// WHY THE LAUNCHER ALSO DOES THIS
+// -------------------------------
+// postinstall used to be the only path, and postinstall is not guaranteed to
+// run. npm gained an install-script approval gate, and a machine that has not
+// approved ours reports a completely successful `npm i -g` while doing none of
+// the work this package exists to do:
+//
+//   npm warn allow-scripts 1 package has install scripts not yet covered by allowScripts
+//
+// Nothing about that is loud. The engineer sees "added 2 packages", the CLI
+// still runs (the launcher falls back to the bundled copy), and the two things
+// that silently do not happen are the two that matter: the managed binary — the
+// one the daemon runs, autostart points at, and self-update owns — is never
+// written, and `autostart repair` never re-points a unit at it. Observed in the
+// field on npm's newer gate, where `npm approve-scripts --allow-scripts-pending`
+// answered "No packages with unreviewed install scripts" and the next install
+// warned again.
+//
+// So the install is idempotent and reachable from the launcher too. Running the
+// CLI at all is now enough to converge the machine, whatever the package manager
+// decided about our scripts. --ignore-scripts lands in the same place.
+//
+// Everything here is best-effort by contract. It runs inside `npm install`,
+// where a throw aborts the install and leaves the engineer with no CLI at all,
+// and on the hot path of every CLI invocation, where a throw breaks a command
+// that had nothing to do with installing. Every path returns a result; none
+// throw.
+
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const {
+  PLATFORMS,
+  bundledBinPath,
+  managedBinPath,
+  isGlobalInstall,
+  isNewer,
+  platformKey,
+  platformPackage,
+} = require("./resolve");
+
+// markerPath records the BUNDLED version last evaluated against the managed
+// binary. It exists purely to keep the launcher's check cheap: without it every
+// invocation would spawn two `--version` probes (~20ms) to answer "nothing to
+// do", which is the answer approximately always.
+//
+// It is a HINT, never the decision. The real guard still compares binary to
+// binary — see installManagedBinary.
+function markerPath() {
+  const managed = managedBinPath();
+  return managed ? path.join(path.dirname(managed), ".npm-installed") : null;
+}
+
+function readMarker() {
+  try {
+    const p = markerPath();
+    return p ? fs.readFileSync(p, "utf8").trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeMarker(version) {
+  try {
+    const p = markerPath();
+    if (!p) return;
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${version}\n`, { mode: 0o600 });
+  } catch {
+    // A missing marker costs two spawns on the next run, nothing more.
+  }
+}
+
+// mayNeedInstall is the cheap gate the launcher consults on every invocation:
+// one readFileSync of a ~7-byte file, no spawns.
+//
+// It answers true when the managed binary is absent, or when the marker is older
+// than the version npm has on disk (or missing entirely — an install whose
+// postinstall never ran leaves no marker). A false answer must be conclusive;
+// a true answer only buys the right to look properly.
+function mayNeedInstall(bundledPkgVersion) {
+  const managed = managedBinPath();
+  if (!managed) return false;
+  if (!fs.existsSync(managed)) return true;
+  const marker = readMarker();
+  if (!marker) return true;
+  return isNewer(bundledPkgVersion, marker);
+}
+
+// binVersion asks a binary what it is. One that cannot answer (missing, corrupt,
+// wrong arch, not executable) reports null.
+//
+// Both sides of the downgrade guard go through this deliberately. The obvious
+// shortcut is to compare package.json's version against the managed binary — but
+// that trusts package.json to describe the bytes actually shipped, and when those
+// two disagree the guard decides on a fiction (and the success log prints a
+// version that was never installed). Comparing the actual binary to the actual
+// binary means the guard cannot be wrong even if the pipeline's package.json gate
+// is ever lost. It costs one ~10ms spawn.
+function binVersion(bin) {
+  if (!bin || !fs.existsSync(bin)) return null;
+  try {
+    const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 10_000 });
+    if (r.status !== 0 || !r.stdout) return null;
+    return r.stdout.trim().split("\n")[0].trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// repairAutostart re-points an ALREADY-ENABLED launchd/systemd/schtasks unit at
+// the managed binary.
+//
+// THIS IS A MIGRATION, and without it this package is a silent regression for
+// every engineer who has run `autostart enable`. The unit bakes an ABSOLUTE path
+// at enable time. Installs predating the managed-binary layout baked
+// <pkg>/binaries/promptster-teams-<platform> — a path that no longer exists in
+// the package, because the binary moved to a per-platform dependency and the
+// wrapper stopped shipping binaries/ entirely. So `npm i -g` deletes the exact
+// file the supervisor is pointed at.
+//
+// Nothing about that fails loudly. The running daemon holds its inode and keeps
+// capturing, so the upgrade looks clean; the unit only breaks at the NEXT LOGIN,
+// when launchd runs a path that is gone. Capture never comes back — the precise
+// failure autostart exists to prevent.
+//
+// Delegated to the Go binary (`autostart repair`) rather than reimplemented here:
+// this must not grow a plist writer, a systemd unit writer and a schtasks caller
+// in Node, three platforms out of sync with the Go ones. `repair` is a no-op when
+// autostart was never enabled and never exits non-zero.
+function repairAutostart(managed, log) {
+  try {
+    const r = spawnSync(managed, ["autostart", "repair"], {
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    const out = `${r.stdout || ""}${r.stderr || ""}`.trim();
+    if (out) log(out);
+  } catch {
+    // Best-effort: a failed repair leaves autostart pointing at the old path,
+    // which the engineer can fix with `promptster-teams autostart enable`.
+  }
+}
+
+// installManagedBinary copies the bundled binary to the managed path when that
+// is an upgrade, then repairs autostart. Returns a short status string for the
+// caller's own reporting; never throws.
+//
+// log/warn are injected because the two callers need different streams:
+// postinstall talks on stdout inside an npm install, while the launcher must
+// stay on stderr so it cannot corrupt the output of the command being run.
+// bundledOverride exists so the test suite can supply a real fixture binary:
+// the actual bundled path resolves through an optionalDependency that is not
+// installed in a source checkout, which would make every test take the
+// "no binary to install" branch and prove nothing about the install itself.
+function installManagedBinary({ log, warn, bundled: bundledOverride }) {
+  // A project-local install must not touch the shared managed binary. The
+  // lockfile is a per-PROJECT pin; the managed binary is per-USER. Letting a
+  // local install write it means two repos pinning different versions fight over
+  // one file and neither gets what its lockfile selected — a worse bug than the
+  // npm-ls drift this whole design removes.
+  if (!isGlobalInstall()) return "project-local";
+
+  const bundled = bundledOverride || bundledBinPath();
+  if (!bundled) {
+    // Either an unsupported platform, or the optionalDependency carrying the
+    // binary is absent. npm treats a missing optional dep as SUCCESS and says
+    // nothing, so this warning is the only signal the engineer will ever get
+    // that they have a CLI with no binary behind it. Say which package.
+    if (!PLATFORMS.includes(platformKey())) {
+      warn(`unsupported platform ${platformKey()} — no binary to install`);
+      return "unsupported";
+    }
+    warn(`${platformPackage()} is not installed, so there is no binary to install.`);
+    warn("If you used --omit=optional or --no-optional, reinstall without it.");
+    return "no-bundled-binary";
+  }
+  const managed = managedBinPath();
+  if (!managed) {
+    warn("could not resolve home directory — skipping binary install");
+    return "no-home";
+  }
+
+  const incoming = binVersion(bundled);
+  const current = binVersion(managed);
+
+  if (!incoming) {
+    warn(`bundled binary at ${bundled} did not report a version — skipping`);
+    return "unreadable-bundled";
+  }
+
+  // Never downgrade. The managed binary self-updates forward on its own, so it is
+  // routinely NEWER than whatever version npm is installing (that is the normal
+  // steady state, not an error). Clobbering it would hand the daemon an older
+  // build that immediately re-updates — churn, plus a window on a version the
+  // engineer already moved past. Mirrors the Go updater's isNewer gate.
+  //
+  // A managed binary that cannot report a version (current === null) is treated
+  // as absent and overwritten: a corrupt or half-written file should be replaced,
+  // not preserved by a guard meant to protect a GOOD newer build.
+  if (current && !isNewer(incoming, current)) {
+    // Record what we evaluated even though nothing was written, or the launcher's
+    // cheap gate stays open and re-probes on every single invocation.
+    writeMarker(incoming);
+    return "already-current";
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(managed), { recursive: true });
+    // Write to a temp file in the SAME directory, then rename: rename is atomic
+    // on POSIX, so a concurrent `promptster-teams` exec sees either the whole old
+    // binary or the whole new one, never a half-written file. Copying straight
+    // onto `managed` would also fail with ETXTBSY on Linux if the daemon is
+    // running. The pid in the name keeps two concurrent launchers apart.
+    const tmp = `${managed}.tmp-${process.pid}`;
+    fs.copyFileSync(bundled, tmp);
+    fs.chmodSync(tmp, 0o755);
+
+    // Re-check immediately before the swap. The guard above and this rename are
+    // not atomic with respect to the Go self-updater, which renames onto this
+    // same path from a live daemon: read 1.0.0 -> daemon installs 1.2.0 -> rename
+    // 1.1.0 over it, and the guard has been defeated.
+    //
+    // This narrows the window from "the whole copy" to the microseconds around
+    // the rename rather than closing it. Closing it needs a lock protocol shared
+    // by a Node script and a Go daemon, which is a lot of machinery for this
+    // failure: rename is atomic so the file is always ONE whole valid binary
+    // (never corrupt), the only cost is running an older version, and the daemon
+    // re-updates forward within one check interval (<=30m). Deliberate tradeoff,
+    // not an oversight — see CLAUDE.md.
+    const stillCurrent = binVersion(managed);
+    if (stillCurrent && !isNewer(incoming, stillCurrent)) {
+      fs.unlinkSync(tmp);
+      writeMarker(incoming);
+      log(`${managed} changed to ${stillCurrent} mid-install; leaving it`);
+      return "raced";
+    }
+    fs.renameSync(tmp, managed);
+    writeMarker(incoming);
+    log(`installed ${incoming} to ${managed}${current ? ` (was ${current})` : ""}`);
+    repairAutostart(managed, log);
+    return "installed";
+  } catch (err) {
+    // Falls back to the bundled binary via bin/promptster-teams.js.
+    warn(`could not install to ${managed}: ${err.message}`);
+    warn("falling back to the bundled binary (npm ls may report a stale version)");
+    return "failed";
+  }
+}
+
+// shouldConvergeOnInvocation gates the launcher's self-heal.
+//
+// `uninstall` is the one command that must never trigger it: reinstalling the
+// binary a person is in the middle of removing would leave them with a CLI they
+// asked us to delete, and `uninstall` is already the ONLY working uninstall path
+// (npm runs no uninstall lifecycle script — see CLAUDE.md), so undermining it
+// leaves no other lever.
+function shouldConvergeOnInvocation(subcommand) {
+  return isGlobalInstall() && subcommand !== "uninstall";
+}
+
+module.exports = {
+  installManagedBinary,
+  mayNeedInstall,
+  binVersion,
+  shouldConvergeOnInvocation,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptster/teams-cli",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "On-device, auditable AI-coding capture for internal engineering teams",
   "keywords": [
     "promptster",
@@ -37,11 +37,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@promptster/teams-cli-linux-x64": "0.12.1",
-    "@promptster/teams-cli-linux-arm64": "0.12.1",
-    "@promptster/teams-cli-darwin-x64": "0.12.1",
-    "@promptster/teams-cli-darwin-arm64": "0.12.1",
-    "@promptster/teams-cli-win32-x64": "0.12.1",
-    "@promptster/teams-cli-win32-arm64": "0.12.1"
+    "@promptster/teams-cli-linux-x64": "0.12.3",
+    "@promptster/teams-cli-linux-arm64": "0.12.3",
+    "@promptster/teams-cli-darwin-x64": "0.12.3",
+    "@promptster/teams-cli-darwin-arm64": "0.12.3",
+    "@promptster/teams-cli-win32-x64": "0.12.3",
+    "@promptster/teams-cli-win32-arm64": "0.12.3"
   }
 }

package/scripts/postinstall.js

@@ -4,198 +4,37 @@
 // Installs the platform binary from node_modules to the MANAGED path
 // (~/.promptster-teams/bin/promptster-teams), which is what actually runs and
 // what self-update owns. See lib/resolve.js for why the binary must not run
-// from inside node_modules.
+// from inside node_modules, and lib/install.js for the install itself.
 //
-// Contract: this script must NEVER fail an npm install. A postinstall that
-// exits non-zero aborts `npm i -g` and leaves the engineer with no CLI at all —
-// far worse than the drift it exists to fix. Every failure path warns and exits
-// 0; bin/promptster-teams.js then falls back to the bundled binary, which works
-// exactly as it did before this file existed.
-
-const { spawnSync } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-
-const {
-  PLATFORMS,
-  bundledBinPath,
-  managedBinPath,
-  isGlobalInstall,
-  isNewer,
-  platformKey,
-  platformPackage,
-} = require("../lib/resolve");
-
-function warn(msg) {
-  console.warn(`promptster-teams: ${msg}`);
-}
-
-// binVersion asks a binary what it is. One that cannot answer (missing,
-// corrupt, wrong arch, not executable) reports null.
+// This is no longer the ONLY path to that install: npm can decline to run
+// install scripts at all (its allow-scripts approval gate, and --ignore-scripts),
+// and it says so in a warning that reads like housekeeping while the install
+// silently does nothing. So bin/promptster-teams.js performs the same converge
+// on invocation. This file stays because running it at install time is still
+// strictly better — the binary is in place before the engineer's first command,
+// and `autostart repair` lands during the upgrade rather than after it.
 //
-// Both sides of the downgrade guard go through this deliberately. The obvious
-// shortcut is to compare package.json's version against the managed binary —
-// but that trusts package.json to describe the bytes sitting in binaries/, and
-// when those two disagree the guard makes its decision on a fiction (and the
-// success log prints a version that was never installed). The pipeline does gate
-// package.json against the tag, so they agree today; comparing the actual binary
-// to the actual binary means the guard cannot be wrong even if that gate is ever
-// lost. It costs one ~10ms spawn on install.
-function binVersion(bin) {
-  if (!bin || !fs.existsSync(bin)) return null;
-  try {
-    const r = spawnSync(bin, ["--version"], {
-      encoding: "utf8",
-      timeout: 10_000,
-    });
-    if (r.status !== 0 || !r.stdout) return null;
-    return r.stdout.trim().split("\n")[0].trim() || null;
-  } catch {
-    return null;
-  }
-}
+// Contract: this script must NEVER fail an npm install. A postinstall that exits
+// non-zero aborts `npm i -g` and leaves the engineer with no CLI at all — far
+// worse than the drift it exists to fix. Every failure path warns and exits 0;
+// the launcher then falls back to the bundled binary, which works exactly as it
+// did before this file existed.
 
-// repairAutostart re-points an existing launchd/systemd/schtasks unit at the
-// managed binary.
-//
-// THIS IS A MIGRATION, and without it this package is a silent regression for
-// every engineer who has run `autostart enable`. The unit bakes an ABSOLUTE
-// path at enable time. Installs predating the managed-binary layout baked
-// <pkg>/binaries/promptster-teams-<platform> — a path that no longer exists in
-// the package, because the binary moved to a per-platform dependency and the
-// wrapper stopped shipping binaries/ entirely. So `npm i -g` deletes the exact
-// file the supervisor is pointed at.
-//
-// Nothing about that fails loudly. The running daemon holds its inode and keeps
-// capturing, so the upgrade looks clean; the unit only breaks at the NEXT LOGIN,
-// when launchd runs a path that is gone. Capture never comes back — the precise
-// failure autostart exists to prevent.
-//
-// Delegated to the Go binary (`autostart repair`) rather than reimplemented
-// here: this must not grow a plist writer, a systemd unit writer and a schtasks
-// caller in Node, three platforms out of sync with the Go ones. `repair` is a
-// no-op when autostart was never enabled and never exits non-zero.
-function repairAutostart(managed) {
-  try {
-    const r = spawnSync(managed, ["autostart", "repair"], {
-      encoding: "utf8",
-      timeout: 30_000,
-    });
-    const out = `${r.stdout || ""}${r.stderr || ""}`.trim();
-    if (out) console.log(out);
-  } catch {
-    // Best-effort: a failed repair leaves autostart pointing at the old path,
-    // which the engineer can fix with `promptster-teams autostart enable`.
-    // Aborting the install over it would be strictly worse.
-  }
-}
+const { installManagedBinary } = require("../lib/install");
+const { isGlobalInstall } = require("../lib/resolve");
 
-function main() {
-  // A project-local install must not touch the shared managed binary. The
-  // lockfile is a per-PROJECT pin; the managed binary is per-USER. Letting a
-  // local install write it means two repos pinning different versions fight
-  // over one file and neither gets what its lockfile selected — a worse bug
-  // than the npm-ls drift this whole design removes. Local installs keep
-  // running out of their own node_modules, exactly as before.
+const log = (msg) => console.log(`promptster-teams: ${msg}`);
+const warn = (msg) => console.warn(`promptster-teams: ${msg}`);
+
+try {
   if (!isGlobalInstall()) {
-    console.log(
-      "promptster-teams: project-local install — leaving ~/.promptster-teams/bin alone " +
+    log(
+      "project-local install — leaving ~/.promptster-teams/bin alone " +
         "and running the version your lockfile pins"
     );
-    return;
-  }
-
-  const bundled = bundledBinPath();
-  if (!bundled) {
-    // Either an unsupported platform, or the optionalDependency carrying the
-    // binary is absent. npm treats a missing optional dep as SUCCESS and says
-    // nothing, so this warning is the only signal the engineer will ever get
-    // that they have a CLI with no binary behind it. Say which package.
-    if (!PLATFORMS.includes(platformKey())) {
-      warn(`unsupported platform ${platformKey()} — no binary to install`);
-      return;
-    }
-    warn(`${platformPackage()} is not installed, so there is no binary to install.`);
-    warn("If you used --omit=optional or --no-optional, reinstall without it.");
-    return;
-  }
-  const managed = managedBinPath();
-  if (!managed) {
-    warn("could not resolve home directory — skipping binary install");
-    return;
-  }
-
-  const incoming = binVersion(bundled);
-  const current = binVersion(managed);
-
-  if (!incoming) {
-    warn(`bundled binary at ${bundled} did not report a version — skipping`);
-    return;
-  }
-
-  // Never downgrade. The managed binary self-updates forward on its own, so it
-  // is routinely NEWER than whatever version npm is installing (that is the
-  // normal steady state, not an error). Clobbering it would hand the daemon an
-  // older build that immediately re-updates — churn, plus a window on a version
-  // the engineer already moved past. Mirrors the Go updater's isNewer gate.
-  //
-  // A managed binary that cannot report a version (current === null) is treated
-  // as absent and overwritten: a corrupt or half-written file should be
-  // replaced, not preserved by a guard meant to protect a GOOD newer build.
-  if (current && !isNewer(incoming, current)) {
-    console.log(
-      `promptster-teams: ${managed} is ${current}; not replacing it with ${incoming}`
-    );
-    return;
+  } else {
+    installManagedBinary({ log, warn });
   }
-
-  try {
-    fs.mkdirSync(path.dirname(managed), { recursive: true });
-    // Write to a temp file in the SAME directory, then rename: rename is atomic
-    // on POSIX, so a concurrent `promptster-teams` exec sees either the whole
-    // old binary or the whole new one, never a half-written file. Copying
-    // straight onto `managed` would also fail with ETXTBSY on Linux if the
-    // daemon is running.
-    const tmp = `${managed}.tmp-${process.pid}`;
-    fs.copyFileSync(bundled, tmp);
-    fs.chmodSync(tmp, 0o755);
-
-    // Re-check immediately before the swap. The guard above and this rename are
-    // not atomic with respect to the Go self-updater, which renames onto this
-    // same path from a live daemon: read 1.0.0 -> daemon installs 1.2.0 ->
-    // rename 1.1.0 over it, and the guard has been defeated.
-    //
-    // This narrows the window from "the whole copy" to the microseconds around
-    // the rename rather than closing it. Closing it needs a lock protocol shared
-    // by a Node script and a Go daemon, which is a lot of machinery for this
-    // failure: rename is atomic so the file is always ONE whole valid binary
-    // (never corrupt), the only cost is running an older version, and the daemon
-    // re-updates forward within one check interval (<=30m). Deliberate tradeoff,
-    // not an oversight — see CLAUDE.md.
-    const stillCurrent = binVersion(managed);
-    if (stillCurrent && !isNewer(incoming, stillCurrent)) {
-      fs.unlinkSync(tmp);
-      console.log(
-        `promptster-teams: ${managed} changed to ${stillCurrent} mid-install; leaving it`
-      );
-      return;
-    }
-    fs.renameSync(tmp, managed);
-    console.log(
-      `promptster-teams: installed ${incoming} to ${managed}${
-        current ? ` (was ${current})` : ""
-      }`
-    );
-    repairAutostart(managed);
-  } catch (err) {
-    // Falls back to the bundled binary via bin/promptster-teams.js.
-    warn(`could not install to ${managed}: ${err.message}`);
-    warn("falling back to the bundled binary (npm ls may report a stale version)");
-  }
-}
-
-try {
-  main();
 } catch (err) {
   // Belt and braces: nothing here may abort an npm install.
   warn(`postinstall skipped: ${err && err.message}`);