wood-fired-tasks 1.18.1 → 1.18.2

package/CHANGELOG.md

@@ -13,6 +13,38 @@ vulnerabilities, supply-chain pinning) are always called out under `Security`.
 
 _No changes yet._
 
+## [v1.18.2] - 2026-06-06
+
+A patch release: a Windows `self-update` fix plus two install-experience
+follow-ups.
+
+### Fixed
+- **`wood-fired-tasks self-update` no longer crashes on Windows** (#793). It
+  spawned `npm` (which is `npm.cmd`) without a shell; since the CVE-2024-27980
+  hardening, Node refuses to spawn a `.cmd`/`.bat` directly and threw
+  `spawn EINVAL` (errno -4071). The npm spawn now passes `shell: true` on
+  Windows only (its args are constant — no quoting/injection hazard), with a
+  win32 regression test. Workaround on 1.18.0/1.18.1: run
+  `npm i -g wood-fired-tasks@latest` directly.
+
+### Added
+- **PATH remediation hint after global install** (#792). A child process can't
+  change the parent shell's PATH, so a fresh `npm i -g` is sometimes not
+  resolvable until a new shell. `setup` and the postinstall notice now detect
+  this (npm global bin dir vs the process PATH — no `which`/`where` shell-out)
+  and print a copy-pasteable fix per platform/shell: `hash -r` (bash, dir on
+  PATH but stale cache), `export PATH=…` + persist (posix, dir off PATH), or the
+  PowerShell `$env:Path` refresh (Windows). The postinstall path is
+  try/catch-guarded so it can never fail an install.
+
+### Changed
+- **Documented the harmless npm deprecation warnings** (#789). `prebuild-install`
+  (via `better-sqlite3`, latest still uses it) and `lodash.get`/`lodash.isequal`
+  (via `umzug` → `@rushstack/ts-command-line` → `z-schema@5`) are upstream
+  transitives — install succeeds and `npm audit` is clean. Recorded in
+  `docs/SETUP.md` with the dependency chains; eliminating the lodash pair via a
+  `z-schema@12` override is deferred (it must not risk the migration path).
+
 ## [v1.18.1] - 2026-06-06
 
 A patch release fixing two regressions shipped in v1.18.0.

package/dist/cli/commands/self-update.js

@@ -64,6 +64,12 @@ function runNpmInstall(spawn) {
         let settled = false;
         const child = spawn(NPM_BIN, ['i', '-g', `${PACKAGE_NAME}@latest`], {
             stdio: ['ignore', 'inherit', 'pipe'],
+            // Windows: npm is `npm.cmd` (a batch file), and since the
+            // CVE-2024-27980 hardening Node refuses to spawn a `.cmd`/`.bat`
+            // directly without a shell (throws spawn EINVAL). Run through the shell
+            // on win32. Safe here: every arg is a constant with no spaces or shell
+            // metacharacters, so there is no quoting/injection hazard.
+            shell: process.platform === 'win32',
         });
         const settle = (code, error) => {
             if (settled)

package/dist/cli/commands/setup.js

@@ -6,6 +6,7 @@ import { execFileSync } from 'node:child_process';
 import { mergeClaudeJson } from '../../setup/claude-json.js';
 import { resolveAssetPath } from '../../assets/resolve.js';
 import { configDir as defaultConfigDir } from '../../config/paths.js';
+import { resolvePathHint } from '../util/path-hint.js';
 /**
  * `tasks setup` (task #737).
  *
@@ -292,6 +293,18 @@ export function runSetup(options = {}) {
             log,
         });
     }
+    // Task #792: best-effort PATH remediation hint. If the npm global bin dir is
+    // not resolvable on the current PATH (or a POSIX shell may have a stale
+    // command-hash cache), print the exact one-liner to fix it. Non-fatal: a
+    // child process cannot mutate the parent shell's PATH, so this is advice only.
+    try {
+        const hint = resolvePathHint();
+        if (hint !== null)
+            log(hint);
+    }
+    catch {
+        /* best-effort: never block setup on a hint failure */
+    }
     return {
         claudeJsonPath,
         claudeJsonChanged: !merge.unchanged,

package/dist/cli/util/path-hint.d.ts

@@ -0,0 +1,61 @@
+/**
+ * PATH remediation hint (task #792).
+ *
+ * After `npm i -g wood-fired-tasks`, the npm global bin directory may not be on
+ * the CURRENT shell's PATH (the user must open a new shell) or — even when it
+ * IS on PATH — a POSIX shell may have a stale command-hash cache that resolves
+ * the old absence. A child process cannot mutate the parent shell's PATH, but
+ * we CAN detect the condition and print the exact one-liner to fix it.
+ *
+ * The core {@link pathHint} is PURE: every input is injected, there is no I/O,
+ * no env reads, no process spawning. The {@link resolvePathHint} resolver
+ * gathers real inputs for production callers WITHOUT shelling out to
+ * `npm`/`which`/`where` (slow at postinstall time, and `which` would mask the
+ * hash-cache case).
+ */
+export interface PathHintInput {
+    /** Target platform (`process.platform`). */
+    platform: NodeJS.Platform;
+    /** Raw `PATH` env value (may be undefined). */
+    pathEnv: string | undefined;
+    /** Absolute npm global bin directory the CLI was installed into. */
+    npmBinDir: string;
+    /** Current shell (e.g. `process.env.SHELL`); used to pick an rc file. */
+    shell?: string | undefined;
+}
+/**
+ * Returns a remediation hint string when the npm global bin dir is NOT
+ * resolvable in the current PATH (or, on POSIX, when it IS present but a stale
+ * shell command-hash cache may hide it), else null (no message needed).
+ *
+ * PURE: no I/O, no env reads, no spawning — all inputs injected.
+ */
+export declare function pathHint(input: PathHintInput): string | null;
+/**
+ * Best-effort resolution of the npm global bin directory WITHOUT shelling out.
+ *
+ * Strategy (in order):
+ *   1. `process.env.npm_config_prefix` (set during npm lifecycle scripts and
+ *      when the user configured a prefix) → bin dir per platform convention.
+ *   2. The location of the running module: a global install lands under
+ *      `<prefix>/lib/node_modules/wood-fired-tasks` (POSIX) or
+ *      `<prefix>/node_modules/wood-fired-tasks` (win32). Walk up to recover
+ *      `<prefix>` and derive the bin dir.
+ *
+ * Returns null when it cannot resolve a prefix confidently (better to print no
+ * hint than a misleading one).
+ *
+ * On POSIX the bin dir is `<prefix>/bin`; on win32 the global bins live in the
+ * prefix directory itself.
+ */
+export declare function resolveNpmBinDir(opts?: {
+    platform?: NodeJS.Platform;
+    npmConfigPrefix?: string | undefined;
+    moduleDir?: string;
+}): string | null;
+/**
+ * Production convenience: resolve real inputs and return the hint (or null).
+ * Never throws — wraps resolution defensively so callers (setup, postinstall)
+ * can call it best-effort.
+ */
+export declare function resolvePathHint(): string | null;

package/dist/cli/util/path-hint.js

@@ -0,0 +1,173 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Path-list delimiter for the given platform. */
+function pathDelimiter(platform) {
+    return platform === 'win32' ? ';' : ':';
+}
+/**
+ * Normalize a single PATH entry for comparison. On win32 we compare
+ * case-insensitively and tolerate a trailing slash/backslash; on POSIX the
+ * comparison is exact (modulo a trailing-slash trim, which is always safe).
+ */
+function normalizeEntry(entry, platform) {
+    let e = entry.trim();
+    // Strip a single trailing path separator (both kinds, defensively).
+    e = e.replace(/[/\\]+$/, '');
+    if (platform === 'win32') {
+        e = e.toLowerCase();
+    }
+    return e;
+}
+/** True when `npmBinDir` is present in `pathEnv` after normalization. */
+function isOnPath(input) {
+    if (input.pathEnv === undefined || input.pathEnv.length === 0)
+        return false;
+    const delim = pathDelimiter(input.platform);
+    const target = normalizeEntry(input.npmBinDir, input.platform);
+    if (target.length === 0)
+        return false;
+    return input.pathEnv
+        .split(delim)
+        .map((p) => normalizeEntry(p, input.platform))
+        .some((p) => p.length > 0 && p === target);
+}
+/**
+ * Pick the shell rc file to mention for persistence on POSIX. zsh → ~/.zshrc;
+ * otherwise stay generic (~/.bashrc or ~/.profile) since we cannot be certain.
+ */
+function posixRcHint(shell) {
+    if (typeof shell === 'string' && /zsh/i.test(shell)) {
+        return '~/.zshrc';
+    }
+    return '~/.bashrc (or ~/.profile)';
+}
+/**
+ * Returns a remediation hint string when the npm global bin dir is NOT
+ * resolvable in the current PATH (or, on POSIX, when it IS present but a stale
+ * shell command-hash cache may hide it), else null (no message needed).
+ *
+ * PURE: no I/O, no env reads, no spawning — all inputs injected.
+ */
+export function pathHint(input) {
+    // Cannot resolve a confident hint without a bin dir.
+    if (typeof input.npmBinDir !== 'string' || input.npmBinDir.trim().length === 0) {
+        return null;
+    }
+    const onPath = isOnPath(input);
+    const isWin = input.platform === 'win32';
+    if (onPath) {
+        if (isWin) {
+            // PowerShell/cmd don't maintain a bash-style command-hash cache; a dir on
+            // PATH resolves. Nothing actionable to print.
+            return null;
+        }
+        // POSIX: dir is on PATH, but the running shell may have cached the command's
+        // absence (hash table). `hash -r` clears it.
+        return (`'${input.npmBinDir}' is on your PATH but your shell may have a stale ` +
+            `command cache.\n` +
+            `If 'wood-fired-tasks' / 'wft' / 'tasks' is "command not found", run:\n` +
+            `  hash -r\n` +
+            `(or open a new terminal).`);
+    }
+    // NOT on PATH.
+    if (isWin) {
+        return (`The install directory is not on this session's PATH:\n` +
+            `  ${input.npmBinDir}\n` +
+            `Refresh the current PowerShell session:\n` +
+            `  $env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + ` +
+            `[Environment]::GetEnvironmentVariable('Path','User')\n` +
+            `cmd.exe users: open a new terminal.`);
+    }
+    const rc = posixRcHint(input.shell);
+    return (`The npm global bin directory is not on your PATH:\n` +
+        `  ${input.npmBinDir}\n` +
+        `Add it for the current shell now:\n` +
+        `  export PATH="${input.npmBinDir}:$PATH"\n` +
+        `Persist it by adding that line to ${rc}, then 'source' it (or open a new terminal).`);
+}
+/**
+ * Best-effort resolution of the npm global bin directory WITHOUT shelling out.
+ *
+ * Strategy (in order):
+ *   1. `process.env.npm_config_prefix` (set during npm lifecycle scripts and
+ *      when the user configured a prefix) → bin dir per platform convention.
+ *   2. The location of the running module: a global install lands under
+ *      `<prefix>/lib/node_modules/wood-fired-tasks` (POSIX) or
+ *      `<prefix>/node_modules/wood-fired-tasks` (win32). Walk up to recover
+ *      `<prefix>` and derive the bin dir.
+ *
+ * Returns null when it cannot resolve a prefix confidently (better to print no
+ * hint than a misleading one).
+ *
+ * On POSIX the bin dir is `<prefix>/bin`; on win32 the global bins live in the
+ * prefix directory itself.
+ */
+export function resolveNpmBinDir(opts) {
+    const platform = opts?.platform ?? process.platform;
+    // Distinguish "caller injected a prefix (possibly undefined to mean none)"
+    // from "caller said nothing, read the env". `'npmConfigPrefix' in opts` is the
+    // discriminator so tests can inject `undefined` to exercise the fallback path
+    // without the ambient `npm_config_prefix` env leaking in.
+    const npmConfigPrefix = opts !== undefined && 'npmConfigPrefix' in opts
+        ? opts.npmConfigPrefix
+        : process.env['npm_config_prefix'];
+    const binFromPrefix = (prefix) => platform === 'win32' ? prefix : path.join(prefix, 'bin');
+    // 1) Explicit prefix from the npm environment.
+    if (typeof npmConfigPrefix === 'string' && npmConfigPrefix.trim().length > 0) {
+        return binFromPrefix(npmConfigPrefix.trim());
+    }
+    // 2) Derive from the running module's location.
+    let moduleDir = opts?.moduleDir;
+    if (moduleDir === undefined) {
+        try {
+            moduleDir = path.dirname(fileURLToPath(import.meta.url));
+        }
+        catch {
+            return null;
+        }
+    }
+    // Find a `node_modules` segment and treat its parent as the prefix root.
+    // POSIX: <prefix>/lib/node_modules/...  → parent of node_modules is `lib`,
+    //        whose parent is <prefix>.
+    // win32: <prefix>/node_modules/...      → parent of node_modules is <prefix>.
+    const segments = moduleDir.split(/[/\\]+/);
+    const nmIdx = segments.lastIndexOf('node_modules');
+    if (nmIdx <= 0)
+        return null;
+    const parentOfNm = segments.slice(0, nmIdx).join(path.sep);
+    if (parentOfNm.length === 0)
+        return null;
+    let prefix;
+    if (platform === 'win32') {
+        prefix = parentOfNm;
+    }
+    else {
+        // Expect the parent of node_modules to be `lib`; strip it to get <prefix>.
+        prefix = path.basename(parentOfNm) === 'lib' ? path.dirname(parentOfNm) : parentOfNm;
+    }
+    if (prefix.length === 0)
+        return null;
+    return binFromPrefix(prefix);
+}
+/**
+ * Production convenience: resolve real inputs and return the hint (or null).
+ * Never throws — wraps resolution defensively so callers (setup, postinstall)
+ * can call it best-effort.
+ */
+export function resolvePathHint() {
+    try {
+        const npmBinDir = resolveNpmBinDir();
+        if (npmBinDir === null)
+            return null;
+        return pathHint({
+            platform: process.platform,
+            pathEnv: process.env['PATH'],
+            npmBinDir,
+            shell: process.env['SHELL'],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=path-hint.js.map

package/docs/SETUP.md

@@ -58,6 +58,19 @@ npm i -g wood-fired-tasks
 After that, `npm i -g` and `wood-fired-tasks self-update` both work without sudo
 forever.
 
+### Deprecation warnings on install (harmless)
+
+`npm i -g wood-fired-tasks` prints a few `npm warn deprecated` lines. They are
+**expected, harmless, and come from upstream transitive dependencies** — not
+from wood-fired-tasks itself. The install succeeds and `npm audit` is clean.
+
+| Warning | Where it comes from | Status |
+| --- | --- | --- |
+| `prebuild-install@7.x` | `better-sqlite3` (the SQLite driver) still depends on it, including the latest release | Upstream-owned; nothing to do until better-sqlite3 drops it |
+| `lodash.get@4.x`, `lodash.isequal@4.x` | `umzug` (migrations) → `@rushstack/ts-command-line` → `z-schema@5` | Upstream-owned; `z-schema@12` dropped them but forcing that major override under rushstack is deferred (it must not risk the migration path) |
+
+You can safely ignore them. Tracking: project-37 #789.
+
 ### `wood-fired-tasks setup` — local Claude Code wiring
 
 `setup` does three things, all idempotent (re-runnable; a file is only rewritten

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wood-fired-tasks",
-  "version": "1.18.1",
+  "version": "1.18.2",
   "description": "Network-wide task tracking system for Wood Fired Games",
   "keywords": [
     "task-tracker",

package/scripts/postinstall.cjs

@@ -19,3 +19,111 @@ process.stdout.write(
   'wood-fired-tasks installed. Run `wood-fired-tasks setup` to register the ' +
     'MCP server and copy skills into ~/.claude.\n',
 );
+
+/**
+ * Task #792: PATH remediation hint.
+ *
+ * After `npm i -g`, the npm global bin dir may not be on the CURRENT shell's
+ * PATH (needs a new shell), or — on POSIX — may be on PATH but hidden by a
+ * stale command-hash cache. A child process can't mutate the parent shell's
+ * PATH, but we can DETECT and print the exact fix.
+ *
+ * This is a SELF-CONTAINED mirror of `src/cli/util/path-hint.ts` rather than an
+ * import of the ESM dist helper. postinstall.cjs is CommonJS and must (#752)
+ * stay self-contained + side-effect-free, and must run even if `dist/` is weird
+ * or absent — importing the built helper would couple this to a successful
+ * build and to ESM/CJS interop. The logic is short, so we inline it and keep
+ * the two copies in sync. Everything is wrapped in try/catch so a hint failure
+ * NEVER breaks `npm install` (postinstall must always exit 0).
+ */
+try {
+  const path = require('node:path');
+  const platform = process.platform;
+  const isWin = platform === 'win32';
+
+  /** Resolve the npm global bin dir without shelling out (no npm/which/where). */
+  function resolveNpmBinDir() {
+    const binFromPrefix = (prefix) => (isWin ? prefix : path.join(prefix, 'bin'));
+    const prefixEnv = process.env.npm_config_prefix;
+    if (typeof prefixEnv === 'string' && prefixEnv.trim().length > 0) {
+      return binFromPrefix(prefixEnv.trim());
+    }
+    // Derive from this module's location: a global install lands under
+    // <prefix>/lib/node_modules/wood-fired-tasks (POSIX) or
+    // <prefix>/node_modules/wood-fired-tasks (win32).
+    const segments = __dirname.split(/[/\\]+/);
+    const nmIdx = segments.lastIndexOf('node_modules');
+    if (nmIdx <= 0) return null;
+    const parentOfNm = segments.slice(0, nmIdx).join(path.sep);
+    if (parentOfNm.length === 0) return null;
+    let prefix;
+    if (isWin) {
+      prefix = parentOfNm;
+    } else {
+      prefix = path.basename(parentOfNm) === 'lib' ? path.dirname(parentOfNm) : parentOfNm;
+    }
+    if (prefix.length === 0) return null;
+    return binFromPrefix(prefix);
+  }
+
+  function normalizeEntry(entry) {
+    let e = entry.trim().replace(/[/\\]+$/, '');
+    if (isWin) e = e.toLowerCase();
+    return e;
+  }
+
+  function isOnPath(npmBinDir) {
+    const pathEnv = process.env.PATH;
+    if (typeof pathEnv !== 'string' || pathEnv.length === 0) return false;
+    const delim = isWin ? ';' : ':';
+    const target = normalizeEntry(npmBinDir);
+    if (target.length === 0) return false;
+    return pathEnv
+      .split(delim)
+      .map(normalizeEntry)
+      .some((p) => p.length > 0 && p === target);
+  }
+
+  function pathHint(npmBinDir) {
+    if (typeof npmBinDir !== 'string' || npmBinDir.trim().length === 0) return null;
+    const onPath = isOnPath(npmBinDir);
+    if (onPath) {
+      if (isWin) return null;
+      return (
+        `'${npmBinDir}' is on your PATH but your shell may have a stale ` +
+        `command cache.\n` +
+        `If 'wood-fired-tasks' / 'wft' / 'tasks' is "command not found", run:\n` +
+        `  hash -r\n` +
+        `(or open a new terminal).`
+      );
+    }
+    if (isWin) {
+      return (
+        `The install directory is not on this session's PATH:\n` +
+        `  ${npmBinDir}\n` +
+        `Refresh the current PowerShell session:\n` +
+        `  $env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + ` +
+        `[Environment]::GetEnvironmentVariable('Path','User')\n` +
+        `cmd.exe users: open a new terminal.`
+      );
+    }
+    const shell = process.env.SHELL;
+    const rc =
+      typeof shell === 'string' && /zsh/i.test(shell) ? '~/.zshrc' : '~/.bashrc (or ~/.profile)';
+    return (
+      `The npm global bin directory is not on your PATH:\n` +
+      `  ${npmBinDir}\n` +
+      `Add it for the current shell now:\n` +
+      `  export PATH="${npmBinDir}:$PATH"\n` +
+      `Persist it by adding that line to ${rc}, then 'source' it (or open a new terminal).`
+    );
+  }
+
+  const npmBinDir = resolveNpmBinDir();
+  if (npmBinDir !== null) {
+    const hint = pathHint(npmBinDir);
+    if (hint !== null) process.stdout.write(hint + '\n');
+  }
+} catch {
+  /* best-effort: a PATH hint must NEVER fail `npm install`. */
+}