cli-jaw 2.2.14 → 2.2.16

package/dist/src/core/install-integrity.js

@@ -0,0 +1,176 @@
+/**
+ * install-integrity — is THIS installation complete?
+ *
+ * npm >= 12 blocks dependency lifecycle scripts by default, so a global
+ * install can succeed while our postinstall never ran. The install-state
+ * receipt written by scripts/postinstall-guard.cjs (or the sidecar bundler)
+ * is the signal; everything else here turns that signal into a command the
+ * user can actually paste.
+ *
+ * Two deliberately different files, two deliberately different schemas:
+ *  - <installRoot>/.jaw-install-state.json — what the install's lifecycle
+ *    script did (writers: postinstall-guard.cjs, bundle-sidecar.sh)
+ *  - JAW_HOME/.setup-state.json — whether the user finished setup via
+ *    `jaw init` (writer: bin/commands/init.ts). Lives in the user's home so
+ *    a read-only global tree can still clear the warning.
+ *
+ * Both carry packageVersion: a receipt from a previous version never hides a
+ * blocked upgrade (it degrades to `stale`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+export const SCRIPT_DEPENDENT_PACKAGES = ['cli-jaw'];
+export const INSTALL_STATE_FILE = '.jaw-install-state.json';
+export const SETUP_STATE_FILE = '.setup-state.json';
+function readJson(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readInstallState(installRoot) {
+    const raw = readJson(path.join(installRoot, INSTALL_STATE_FILE));
+    if (!raw || typeof raw["state"] !== 'string')
+        return null;
+    return raw;
+}
+export function readSetupState(jawHome) {
+    const raw = readJson(path.join(jawHome, SETUP_STATE_FILE));
+    if (!raw || typeof raw["schema"] !== 'number')
+        return null;
+    return raw;
+}
+export function writeSetupState(jawHome, packageVersion) {
+    fs.mkdirSync(jawHome, { recursive: true });
+    fs.writeFileSync(path.join(jawHome, SETUP_STATE_FILE), JSON.stringify({
+        schema: 1,
+        packageVersion,
+        doneAt: new Date().toISOString(),
+    }, null, 2));
+}
+export function readPackageVersion(installRoot) {
+    const raw = readJson(path.join(installRoot, 'package.json'));
+    return raw && typeof raw["version"] === 'string' ? raw["version"] : null;
+}
+/**
+ * Which package manager owns this installation?
+ * npm_config_user_agent is only present while the manager itself runs us, so
+ * the install-root path is the durable signal for an installed CLI.
+ */
+export function detectPackageManager(installRoot, env = process.env) {
+    const agent = env["npm_config_user_agent"] || '';
+    if (agent.startsWith('pnpm/'))
+        return 'pnpm';
+    if (agent.startsWith('bun'))
+        return 'bun';
+    if (agent.startsWith('npm/'))
+        return 'npm';
+    if (/[\\/]\.bun[\\/]/.test(installRoot))
+        return 'bun';
+    if (/[\\/]pnpm[\\/]|[\\/]\.pnpm[\\/]/.test(installRoot))
+        return 'pnpm';
+    if (installRoot)
+        return 'npm';
+    return 'unknown';
+}
+function canWriteInstallTree(installRoot) {
+    try {
+        fs.accessSync(path.join(installRoot, 'node_modules'), fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function inspectInstallIntegrity(installRoot, jawHome) {
+    const pkgVersion = readPackageVersion(installRoot);
+    const receipt = readInstallState(installRoot);
+    const setup = readSetupState(jawHome);
+    let installScriptState;
+    if (!receipt) {
+        installScriptState = 'blocked';
+    }
+    else if (pkgVersion && receipt.packageVersion !== pkgVersion) {
+        installScriptState = 'stale';
+    }
+    else if (receipt.state === 'completed' || receipt.state === 'safe-mode' || receipt.state === 'failed') {
+        installScriptState = receipt.state;
+    }
+    else {
+        installScriptState = 'blocked';
+    }
+    const userSetupDone = Boolean(setup && pkgVersion && setup.packageVersion === pkgVersion);
+    let nativeLoadable = true;
+    try {
+        const require_ = createRequire(path.join(installRoot, 'package.json'));
+        const Database = require_('better-sqlite3');
+        new Database(':memory:').close();
+    }
+    catch {
+        nativeLoadable = false;
+    }
+    return {
+        installScriptState,
+        userSetupDone,
+        nativeLoadable,
+        packageManager: detectPackageManager(installRoot),
+        installRoot,
+        writableInstallTree: canWriteInstallTree(installRoot),
+        scriptDependents: SCRIPT_DEPENDENT_PACKAGES,
+    };
+}
+/**
+ * Exact, working recovery commands. npm's own printed remediation omits the
+ * package argument and fails with ENOENT (npm/cli#9835); never echo that form.
+ * `--dangerously-allow-all-scripts` is deliberately never suggested.
+ */
+export function formatRecoveryCommands(integrity) {
+    const allow = integrity.scriptDependents.join(',');
+    switch (integrity.packageManager) {
+        case 'bun':
+            return ['bun add -g --trust cli-jaw'];
+        case 'pnpm':
+            return [
+                `pnpm add -g --allow-build=${allow} cli-jaw`,
+                'pnpm approve-builds -g   # pnpm <= 10',
+            ];
+        case 'npm':
+            return [
+                `npm install -g cli-jaw --allow-scripts=${allow}`,
+                `npm config set allow-scripts=${allow} --location=user`,
+            ];
+        default:
+            return [
+                `npm install -g cli-jaw --allow-scripts=${allow}`,
+                `pnpm add -g --allow-build=${allow} cli-jaw`,
+                'bun add -g --trust cli-jaw',
+            ];
+    }
+}
+/** Problem → cause → command, Puppeteer-style. Plain text, pipe-safe. */
+export function formatIntegrityReport(integrity) {
+    const lines = [];
+    if (integrity.installScriptState === 'failed') {
+        lines.push('[jaw:install] the postinstall step ran but failed — run `jaw doctor` for details.');
+    }
+    else if (integrity.installScriptState === 'safe-mode') {
+        lines.push('[jaw:install] this install used safe mode, so setup was skipped on purpose.');
+        lines.push('[jaw:install] finish it with: jaw init');
+        return lines.join('\n');
+    }
+    else {
+        lines.push('[jaw:install] this installation is incomplete: the postinstall step never ran.');
+        lines.push('[jaw:install] npm >= 12 blocks dependency install scripts unless allowed.');
+    }
+    lines.push('[jaw:install] fix it with one of:');
+    for (const cmd of formatRecoveryCommands(integrity)) {
+        lines.push(`[jaw:install]   ${cmd}`);
+    }
+    lines.push('[jaw:install] then re-run: jaw doctor');
+    return lines.join('\n');
+}
+//# sourceMappingURL=install-integrity.js.map

package/dist/src/core/install-integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-integrity.js","sourceRoot":"","sources":["../../../src/core/install-integrity.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-jaw",
-  "version": "2.2.14",
+  "version": "2.2.16",
   "description": "Personal AI assistant powered by Pi, Antigravity, AI-E, Claude, Claude E, Codex, Codex App, Cursor, Grok, Kiro, OpenCode, and Copilot — Web, Terminal, Telegram, and Discord interfaces with 107 built-in skills",
   "type": "module",
   "keywords": [
@@ -34,6 +34,9 @@
   "engines": {
     "node": ">=22.4.0"
   },
+  "allowScripts": {
+    "better-sqlite3": false
+  },
   "bin": {
     "cli-jaw": "dist/bin/cli-jaw.js",
     "jaw": "dist/bin/cli-jaw.js"
@@ -114,6 +117,7 @@
     "gate:sidecar-prune-safety": "node scripts/release-gates.mjs sidecar-prune-safety",
     "gate:native-load": "node scripts/release-gates.mjs native-load",
     "gate:sidecar-smoke": "node scripts/release-gates.mjs sidecar-smoke",
+    "gate:install-integrity": "node scripts/release-gates.mjs install-integrity",
     "check:sidecar-prune-safety": "node scripts/check-sidecar-prune-safety.mjs",
     "sync:electron-version": "node scripts/sync-electron-version.cjs",
     "gate:all": "node scripts/release-gates.mjs",
@@ -150,7 +154,7 @@
     "@uiw/react-codemirror": "^4.25.9",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
-    "better-sqlite3": "^12.8.0",
+    "better-sqlite3": "^13.0.2",
     "d3": "^7.9.0",
     "discord.js": "^14.25.1",
     "dompurify": "^3.3.3",
@@ -183,9 +187,6 @@
     "ws": "^8.18.0",
     "yaml": "^2.8.4"
   },
-  "optionalDependencies": {
-    "claude-e": "latest"
-  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/d3": "^7.4.3",

package/scripts/bundle-sidecar.sh

@@ -111,6 +111,16 @@ fi
 echo "Rebuilding better-sqlite3 for bundled Node $NODE_VERSION..."
 while IFS= read -r pkg_json; do
   pkg_dir="$(dirname "$pkg_json")"
+  # better-sqlite3 >= 13 is Node-API: it ships prebuilds/ inside the package,
+  # has NO scripts.install (`npm run install` dies with "Missing script"), and
+  # the prebuild is ABI-independent, so no per-Node rebuild is needed at all.
+  # v12 keeps the old install script ("prebuild-install || node-gyp rebuild").
+  # The verification step below opens the DB with the bundled Node either way.
+  has_install_script="$("$NODE_BIN" -e 'const p=require(process.argv[1]);process.stdout.write(p.scripts&&p.scripts.install?"yes":"no")' "$pkg_json")"
+  if [ "$has_install_script" = "no" ]; then
+    echo "  skip rebuild (v13+ bundled prebuilds): ${pkg_dir#$SIDECAR_DIR/}"
+    continue
+  fi
   echo "  rebuild: ${pkg_dir#$SIDECAR_DIR/}"
   (
     cd "$pkg_dir"
@@ -126,8 +136,23 @@ done < <(find "$SIDECAR_DIR/node_modules" -path '*/better-sqlite3/package.json'
 
 echo "Verifying better-sqlite3 opens with bundled Node..."
 "$NODE_BIN" -e "const Database = require('better-sqlite3'); new Database(':memory:').close()" && echo "  better-sqlite3 OK" || {
-  echo "ERROR: better-sqlite3 failed to open with bundled Node"
-  exit 1
+  echo "  bundled prebuild failed to load — building from source (v13 build-release)..."
+  sidecar_bsql_dir="$SIDECAR_DIR/node_modules/better-sqlite3"
+  if [ -d "$sidecar_bsql_dir" ]; then
+    (
+      cd "$sidecar_bsql_dir"
+      PYTHON="$PYTHON_BIN" \
+      npm_config_python="$PYTHON_BIN" \
+      npm_config_runtime=node \
+      npm_config_target="$NODE_VERSION" \
+      npm_config_disturl="https://nodejs.org/dist" \
+        npm run build-release --foreground-scripts
+    )
+  fi
+  "$NODE_BIN" -e "const Database = require('better-sqlite3'); new Database(':memory:').close()" && echo "  better-sqlite3 OK (source build)" || {
+    echo "ERROR: better-sqlite3 failed to open with bundled Node"
+    exit 1
+  }
 }
 
 echo "Cleaning up Node extract..."
@@ -173,5 +198,28 @@ node "$PROJECT_ROOT/scripts/check-electron-sidecar-no-jwc.cjs" --server-root "$S
 # Telegram bot could load.
 node "$PROJECT_ROOT/scripts/check-sidecar-smoke.mjs" --server-root "$SIDECAR_DIR"
 
+# Sidecar install-state receipt. The sidecar is deliberately built with
+# --ignore-scripts, so postinstall-guard never runs here and its receipt would
+# be absent — which the runtime integrity check would misread as a blocked
+# install and nag every desktop user. This is a controlled build: writing the
+# receipt ourselves, with the sidecar's own package version, is the honest
+# record of what happened.
+echo "Writing sidecar install-state receipt..."
+"$NODE_BIN" -e '
+const fs = require("fs"), path = require("path");
+const root = process.argv[1];
+const packageVersion = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+fs.writeFileSync(path.join(root, ".jaw-install-state.json"), JSON.stringify({
+  schema: 1,
+  state: "completed",
+  sidecar: true,
+  packageVersion,
+  ranAt: new Date().toISOString(),
+  node: process.version,
+  platform: process.platform,
+  arch: process.arch,
+}, null, 2));
+' "$SIDECAR_DIR"
+
 echo "=== Sidecar ready ==="
 du -sh "$SIDECAR_DIR"

package/scripts/ensure-native-modules.cjs

@@ -7,7 +7,7 @@
  * rebuild it in-place before build/test steps continue.
  */
 const { execFileSync } = require('child_process');
-const { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } = require('fs');
+const { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } = require('fs');
 const { delimiter, dirname, join } = require('path');
 const { createRequire } = require('module');
 const { createHash } = require('crypto');
@@ -58,7 +58,13 @@ function rebuildBetterSqlite3() {
     const betterSqliteDir = join(root, 'node_modules', 'better-sqlite3');
     if (existsSync(join(betterSqliteDir, 'package.json'))) {
         rmSync(join(betterSqliteDir, 'build'), { recursive: true, force: true });
-        runNpm(['run', 'install', '--foreground-scripts'], {
+        // v12 has scripts.install ("prebuild-install || node-gyp rebuild").
+        // v13+ removed it (prebuilds ship in the package), and `npm rebuild`
+        // returns a no-op success there, so the real source-build script is
+        // build-release. Pick by reading the installed package's manifest.
+        const manifest = JSON.parse(readFileSync(join(betterSqliteDir, 'package.json'), 'utf8'));
+        const script = manifest.scripts && manifest.scripts.install ? 'install' : 'build-release';
+        runNpm(['run', script, '--foreground-scripts'], {
             stdio: 'inherit',
             cwd: betterSqliteDir,
             env: nativeBuildEnv(),
@@ -239,10 +245,51 @@ function releaseRepairLock() {
     try { rmSync(LOCK_DIR, { recursive: true, force: true }); } catch { /* best effort */ }
 }
 
+/**
+ * Can this process write into the install tree at all? A global npm prefix is
+ * often root-owned; telling that user to "rebuild" is advice that cannot work.
+ */
+function canWriteInstallTree() {
+    try {
+        accessSync(join(root, 'node_modules'), constants.W_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Package-manager-aware recovery commands. npm >= 12 blocks unreviewed
+ * dependency install scripts, which is the likeliest reason a fresh global
+ * install is missing its native addon. npm's own printed remediation omits
+ * the package argument (npm/cli#9835), so we print the working form.
+ */
+function recoveryHints() {
+    const lines = [];
+    if (/[\\/]\.bun[\\/]/.test(root)) {
+        lines.push('[jaw:native]    reinstall with lifecycle scripts trusted (bun):');
+        lines.push('[jaw:native]      bun add -g --trust cli-jaw');
+    } else if (/[\\/]pnpm[\\/]|[\\/]\.pnpm[\\/]/.test(root)) {
+        lines.push('[jaw:native]    reinstall with build scripts allowed (pnpm 11+):');
+        lines.push('[jaw:native]      pnpm add -g --allow-build=cli-jaw cli-jaw');
+        lines.push('[jaw:native]      (pnpm <= 10: pnpm approve-builds -g)');
+    } else {
+        lines.push('[jaw:native]    reinstall with install scripts allowed (npm >= 11.16):');
+        lines.push('[jaw:native]      npm install -g cli-jaw --allow-scripts=cli-jaw');
+        lines.push('[jaw:native]      npm config set allow-scripts=cli-jaw --location=user');
+    }
+    return lines;
+}
+
 function reportMissing() {
     console.error('[jaw:native] ❌ dependencies are not installed (cannot resolve better-sqlite3).');
     console.error(`[jaw:native]    install root: ${root}`);
-    console.error('[jaw:native]    run: npm install');
+    if (!canWriteInstallTree()) {
+        console.error('[jaw:native]    install tree is not writable — a rebuild cannot help here.');
+        for (const line of recoveryHints()) console.error(line);
+    } else {
+        console.error('[jaw:native]    run: npm install');
+    }
 }
 
 module.exports = {

package/scripts/install-risk-gate.mjs

@@ -67,6 +67,7 @@ function runPackageContentsCheck() {
   const required = [
     'scripts/install.sh',
     'scripts/install-wsl.sh',
+    'scripts/install.ps1',
     'scripts/verify-fresh-install.sh',
     'scripts/collect-fresh-install-evidence.sh',
     'scripts/audit-fresh-install-evidence.mjs',
@@ -94,6 +95,13 @@ function runPackageContentsCheck() {
     return false;
   }
 
+  // The install-state receipt is written at install time; if it ever ships in
+  // the tarball it always exists, which makes blocked-install detection blind.
+  if ([...files].some((file) => file.endsWith('.jaw-install-state.json'))) {
+    console.error(`[install-risk] FAIL ${label}: .jaw-install-state.json must never ship in the package`);
+    return false;
+  }
+
   console.log(`[install-risk] PASS ${label}`);
   return true;
 }

package/scripts/install-wsl.sh

@@ -37,6 +37,29 @@ HAS_SUDO=false
 NPM_PREFIX="$HOME/.local"
 NPM_PATH_LINE='export PATH="$HOME/.local/bin:$PATH"'
 
+# npm >= 11.16 understands --allow-scripts; npm 12 blocks unreviewed dependency
+# lifecycle scripts by default, so without this flag a global install can
+# succeed while cli-jaw's postinstall silently never runs. Older npm rejects
+# unknown config, so the flag is attached conditionally. (Duplicated from
+# install.sh — both files are standalone curl-run scripts.)
+JAW_ALLOW_SCRIPTS="cli-jaw"
+
+jaw_npm_supports_allow_scripts() {
+  local npm_version major minor
+  npm_version="$(npm --version 2>/dev/null || true)"
+  major="$(printf '%s' "$npm_version" | cut -d. -f1)"
+  minor="$(printf '%s' "$npm_version" | cut -d. -f2)"
+  case "$major" in (''|*[!0-9]*) return 1 ;; esac
+  case "$minor" in (''|*[!0-9]*) minor=0 ;; esac
+  [ "$major" -gt 11 ] || { [ "$major" -eq 11 ] && [ "$minor" -ge 16 ]; }
+}
+
+jaw_allow_scripts_flag() {
+  if jaw_npm_supports_allow_scripts; then
+    printf '%s' "--allow-scripts=${JAW_ALLOW_SCRIPTS}"
+  fi
+}
+
 # Guard: reject Windows HOME (e.g. /mnt/c/Users/...)
 case "$HOME" in
   /mnt/*) fail "HOME points to Windows path: $HOME — launch a proper WSL shell (wsl.exe -d Ubuntu)" ;;
@@ -315,15 +338,17 @@ verify_jaw_command() {
 #  Step 3: Install cli-jaw
 # ═══════════════════════════════════════
 install_jaw() {
+  local allow_flag
+  allow_flag="$(jaw_allow_scripts_flag)"
   if command -v jaw &>/dev/null; then
     ok "cli-jaw already installed ($(jaw --version 2>/dev/null || echo 'unknown version'))"
     info "Updating to latest..."
     CLI_JAW_INSTALL_CLI_TOOLS=1 \
-      npm install -g cli-jaw@latest
+      npm install -g cli-jaw@latest ${allow_flag:+$allow_flag}
   else
     info "Installing cli-jaw globally..."
     CLI_JAW_INSTALL_CLI_TOOLS=1 \
-      npm install -g cli-jaw
+      npm install -g cli-jaw ${allow_flag:+$allow_flag}
   fi
 
   verify_jaw_command

package/scripts/install.ps1

@@ -0,0 +1,121 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  CLI-JAW one-click installer for native Windows (beta).
+
+.DESCRIPTION
+  Installs cli-jaw globally with npm, attaching --allow-scripts when the npm
+  version supports it (npm >= 11.16; npm 12 blocks unreviewed dependency
+  lifecycle scripts by default). Verifies PATH and the installed binary, and
+  prints exact fixes instead of mutating user PATH or system policy.
+
+  This script never changes the PowerShell execution policy, never requires
+  elevation, and never edits the user PATH — it prints the command instead.
+
+.PARAMETER TarballPath
+  Install from a local .tgz produced by `npm pack` instead of the registry.
+  Used by CI to validate the exact artifact that will ship.
+
+.PARAMETER Prefix
+  Use an isolated npm prefix instead of the default global prefix. Used by CI
+  to avoid mutating the runner's real global tree.
+
+.PARAMETER IgnoreScripts
+  Pass --ignore-scripts to npm install. Used by CI to reproduce the
+  blocked-postinstall scenario deliberately.
+
+.EXAMPLE
+  irm https://raw.githubusercontent.com/lidge-jun/cli-jaw/main/scripts/install.ps1 | iex
+#>
+[CmdletBinding()]
+param(
+    [string]$TarballPath = '',
+    [string]$Prefix = '',
+    [switch]$IgnoreScripts
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$JawAllowScripts = 'cli-jaw'
+
+function Write-Info([string]$Message) { Write-Host "  $Message" -ForegroundColor Cyan }
+function Write-Ok([string]$Message) { Write-Host "  $Message" -ForegroundColor Green }
+function Write-Warn2([string]$Message) { Write-Host "  $Message" -ForegroundColor Yellow }
+
+Write-Host ''
+Write-Host '  CLI-JAW Windows Installer (beta)' -ForegroundColor Cyan
+Write-Host ''
+
+# --- 1. Node.js >= 22 ---------------------------------------------------
+$nodeCmd = Get-Command node -ErrorAction SilentlyContinue
+if (-not $nodeCmd) {
+    Write-Warn2 'Node.js not found on PATH.'
+    Write-Warn2 'Install it first, then re-run this script:'
+    Write-Warn2 '  winget install OpenJS.NodeJS.LTS'
+    exit 1
+}
+$nodeVersion = (& node --version) -replace '^v', ''
+$nodeMajor = [int]($nodeVersion.Split('.')[0])
+if ($nodeMajor -lt 22) {
+    Write-Warn2 "Node.js >= 22 required (current: v$nodeVersion)."
+    Write-Warn2 '  winget install OpenJS.NodeJS.LTS'
+    exit 1
+}
+Write-Ok "Node.js v$nodeVersion"
+
+# --- 2. npm allow-scripts support ---------------------------------------
+# npm >= 11.16 understands --allow-scripts; npm 12 blocks unreviewed
+# dependency lifecycle scripts by default. Older npm rejects unknown config,
+# so the flag is attached conditionally.
+$npmVersion = (& npm --version).Trim()
+$npmParts = $npmVersion.Split('.')
+$npmMajor = [int]$npmParts[0]
+$npmMinor = [int]$npmParts[1]
+$supportsAllowScripts = ($npmMajor -gt 11) -or (($npmMajor -eq 11) -and ($npmMinor -ge 16))
+Write-Ok "npm $npmVersion (allow-scripts: $supportsAllowScripts)"
+
+# --- 3. Install ----------------------------------------------------------
+$packageSpec = if ($TarballPath) { $TarballPath } else { 'cli-jaw' }
+$npmArgs = @('install', '-g', $packageSpec)
+if ($supportsAllowScripts -and -not $IgnoreScripts) {
+    $npmArgs += "--allow-scripts=$JawAllowScripts"
+}
+if ($IgnoreScripts) { $npmArgs += '--ignore-scripts' }
+if ($Prefix) { $npmArgs += @('--prefix', $Prefix) }
+
+Write-Info "npm $($npmArgs -join ' ')"
+& npm @npmArgs
+if ($LASTEXITCODE -ne 0) {
+    Write-Warn2 "npm install failed (exit $LASTEXITCODE)."
+    Write-Warn2 'If the error mentions blocked install scripts, run:'
+    Write-Warn2 "  npm install -g cli-jaw --allow-scripts=$JawAllowScripts"
+    exit 1
+}
+
+# --- 4. PATH check --------------------------------------------------------
+$globalBin = if ($Prefix) { $Prefix } else { (& npm prefix -g).Trim() }
+$pathEntries = $env:Path -split ';'
+$onPath = $pathEntries -contains $globalBin
+if (-not $onPath -and -not $Prefix) {
+    Write-Warn2 "npm global bin dir is not on PATH: $globalBin"
+    Write-Warn2 'Add it for the current user (then open a new terminal):'
+    Write-Warn2 "  [Environment]::SetEnvironmentVariable('Path', `$env:Path + ';$globalBin', 'User')"
+}
+
+# --- 5. Verify ------------------------------------------------------------
+$jawCmd = Join-Path $globalBin 'jaw.cmd'
+if (-not (Test-Path $jawCmd)) {
+    # default-prefix installs may resolve via PATH instead
+    $resolved = Get-Command jaw -ErrorAction SilentlyContinue
+    if ($resolved) { $jawCmd = $resolved.Source }
+}
+if (Test-Path $jawCmd) {
+    $jawVersion = (& $jawCmd --version)
+    Write-Ok "cli-jaw installed: $jawVersion"
+    Write-Info 'Next: jaw doctor  (diagnose)  |  jaw init  (finish setup)'
+} else {
+    Write-Warn2 'Install finished but the jaw command was not found.'
+    Write-Warn2 'Diagnose with: npm ls -g cli-jaw ; then check the PATH note above.'
+    exit 1
+}

package/scripts/install.sh

@@ -39,6 +39,28 @@ extract_semver() {
   printf '%s' "${1:-}" | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+' | head -n1 || true
 }
 
+# npm >= 11.16 understands --allow-scripts; npm 12 blocks unreviewed dependency
+# lifecycle scripts by default, so without this flag a global install can
+# succeed while cli-jaw's postinstall silently never runs. Older npm rejects
+# unknown config, so the flag is attached conditionally.
+JAW_ALLOW_SCRIPTS="cli-jaw"
+
+jaw_npm_supports_allow_scripts() {
+  local npm_version major minor
+  npm_version="$(npm --version 2>/dev/null || true)"
+  major="$(printf '%s' "$npm_version" | cut -d. -f1)"
+  minor="$(printf '%s' "$npm_version" | cut -d. -f2)"
+  case "$major" in (''|*[!0-9]*) return 1 ;; esac
+  case "$minor" in (''|*[!0-9]*) minor=0 ;; esac
+  [ "$major" -gt 11 ] || { [ "$major" -eq 11 ] && [ "$minor" -ge 16 ]; }
+}
+
+jaw_allow_scripts_flag() {
+  if jaw_npm_supports_allow_scripts; then
+    printf '%s' "--allow-scripts=${JAW_ALLOW_SCRIPTS}"
+  fi
+}
+
 resolve_cmd() {
   command -v "$1" 2>/dev/null || true
 }
@@ -433,11 +455,15 @@ install_cli_jaw() {
   fi
 
   # Detect package manager from existing install path to avoid shared-path contamination
-  local pkg_cmd="npm install -g cli-jaw"
+  local allow_flag pkg_cmd
+  allow_flag="$(jaw_allow_scripts_flag)"
+  pkg_cmd="npm install -g cli-jaw${allow_flag:+ $allow_flag}"
   if [ -n "$installed_bin" ]; then
     case "$installed_bin" in
       *"/.bun/bin/"*)
-        pkg_cmd="bun add -g cli-jaw"
+        # bun skips lifecycle scripts for untrusted packages; --trust is the
+        # only surface that runs them for a global add.
+        pkg_cmd="bun add -g --trust cli-jaw"
         info "Detected bun-managed install — using bun"
         ;;
       *)