@ijfw/install 1.5.3 → 1.5.4

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.5.4] -- 2026-05-26
+
+**Wayland Hub Extension pack pipeline.** Adds `pack-hub-extension` -- a new CLI subcommand that produces the three distributable artifacts Wayland's prebuild sync script needs to bundle IJFW as a native Hub Extension without committing binaries to the Wayland repo.
+
+### Added
+
+- `ijfw pack-hub-extension [--output <dir>]` produces three artifacts in one shot:
+  - `ijfw-<version>.zip` -- the installable Hub Extension bundle (manifest + lifecycle hooks + assets)
+  - `ijfw-<version>.sha512` -- SHA-512 SRI checksum for Wayland's integrity verifier
+  - `hub-index-snippet.json` -- drop-in entry for Wayland's Hub Index, ready to merge at build time
+- `--output <dir>` flag lets callers stage artifacts anywhere (defaults to `dist/`); the flag is forwarded verbatim to `scripts/pack-hub-extension.js`.
+- `scripts/pack-hub-extension.js` + `scripts/hub-extension/**` now ship inside the npm tarball, so Wayland's prebuild script can invoke the packer directly via `npx -y @ijfw/install@<version> pack-hub-extension --output <stage-dir>` with no local clone required.
+- Hub Extension bundle includes `scripts/install.js` (runs `npx -y @ijfw/install@latest` non-interactively) and `scripts/uninstall.js` with split timeouts -- 100s for install, 30s for uninstall -- so Wayland's sandboxed fork never hangs the boot sequence.
+- Manifest template (`aion-extension.json.tmpl`) declares all 15 `acpAdapters` so Wayland's existing verifier checks every supported CLI on PATH post-install. If any are missing, install fails with a clear error rather than silently succeeding.
+- Wayland integration: their `scripts/sync-hub-extensions.ts` prebuild step invokes `pack-hub-extension` at every build so each Wayland release snapshots the latest published IJFW without storing binaries in the repo.
+
+### Internal
+
+- `@ijfw/memory-server@1.5.4` republishes alongside with no functional changes vs 1.5.3 -- preserves the version-lockstep invariant between the two packages.
+- Test coverage: `installer/test/test-pack-hub-extension.js` verifies artifact production, SHA-512 stability across runs on identical content, and manifest shape conformance.
+
 ## [1.3.2] -- 2026-05-15
 
 **Project-agnostic swarm orchestration + live visual workflow + richer Codex native surface.** Adds first-class Team Assembly, blackboard coordination, swarm task lifecycle, conservative git worktrees, recovery checkpoints, Superpowers-style live design previews, and Claude-parity Codex command aliases.

package/dist/hub-index-snippet.json

@@ -0,0 +1,49 @@
+{
+  "name": "ijfw",
+  "displayName": "IJFW — AI Efficiency Layer",
+  "version": "1.5.4",
+  "description": "One install, every AI coding agent, zero config. Unifies 15 CLIs under a shared MCP memory layer so context follows you across Claude, Codex, Gemini, Cursor, Windsurf, and 10 more.",
+  "author": "Sean Donahoe",
+  "icon": "assets/ijfw-logo.svg",
+  "dist": {
+    "tarball": "extensions/ijfw-1.5.4.zip",
+    "integrity": "sha512-VzLLJg/kN1vP4kp6uSe26PJi92JoxT0rgLyulG7JLFuqr9AetZKIQBSBD/d4qWMP5q0k7Mn0J4eI7uZl27pfFw==",
+    "unpackedSize": 3205
+  },
+  "engines": {
+    "wayland": ">=0.6.0"
+  },
+  "hubs": [
+    "acpAdapters",
+    "mcpServers"
+  ],
+  "contributes": {
+    "acpAdapters": [
+      "claude",
+      "codex",
+      "gemini",
+      "cursor",
+      "windsurf",
+      "copilot",
+      "hermes",
+      "wayland",
+      "aider",
+      "opencode",
+      "qwencode",
+      "cline",
+      "kimicode",
+      "openclaw",
+      "antigravity"
+    ],
+    "mcpServers": [
+      "ijfw-memory"
+    ]
+  },
+  "tags": [
+    "ai",
+    "coding",
+    "mcp",
+    "memory",
+    "multi-agent"
+  ]
+}

package/dist/ijfw.js

@@ -3782,6 +3782,16 @@ var COMMAND_REGISTRY = Object.freeze([
     helpGroup: "EXPLORE"
   },
   // ---------- TIER 2: COORDINATION (shown in `ijfw commands`) ----------
+  {
+    name: "pack-hub-extension",
+    tier: "coordination",
+    owner: "installer-direct",
+    description: "Pack the Wayland Hub Extension (zip + SHA-512 + manifest snippet). Used by Wayland's prebuild sync.",
+    aliases: [],
+    since: "1.5.4",
+    status: "active",
+    helpGroup: "BUILD"
+  },
   {
     name: "status",
     tier: "coordination",
@@ -4246,6 +4256,12 @@ async function main() {
       process.exit(r.status ?? 1);
       break;
     }
+    case "pack-hub-extension": {
+      const packScript = resolve4(__dirname2, "..", "scripts", "pack-hub-extension.js");
+      const r = spawnSync12("node", [packScript, ...argv.slice(3)], { stdio: "inherit" });
+      process.exit(r.status ?? 1);
+      break;
+    }
     case "uninstall": {
       const uninstallBin = resolve4(__dirname2, "..", "dist", "uninstall.js");
       const r = spawnSync12("node", [uninstallBin, ...argv.slice(3)], { stdio: "inherit" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/install",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "One-command installer for IJFW -- the AI efficiency layer. One install, every AI coding agent, zero config.",
   "type": "module",
   "bin": {
@@ -13,6 +13,8 @@
     "src/install.ps1",
     "docs/GUIDE.md",
     "docs/guide/assets",
+    "scripts/pack-hub-extension.js",
+    "scripts/hub-extension/**",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -20,9 +22,12 @@
   "scripts": {
     "build": "node scripts/build.js",
     "test": "node --test test.js",
+    "test:hub-extension": "node --test test/test-pack-hub-extension.js",
     "preflight": "node dist/ijfw.js preflight",
     "pack:check": "npm pack --dry-run",
-    "prepublishOnly": "npm run build && npm run preflight"
+    "pack:hub-extension": "node scripts/pack-hub-extension.js",
+    "prepack": "node -e \"const fs=require('fs'),path=require('path');const d='dist';if(fs.existsSync(d)){for(const f of fs.readdirSync(d)){if(/^ijfw-\\d+\\.\\d+\\.\\d+\\.(zip|sha512)$/.test(f)){fs.rmSync(path.join(d,f))}}}\"",
+    "prepublishOnly": "npm run build && npm run preflight && npm run pack:check"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",

package/scripts/hub-extension/aion-extension.json.tmpl

@@ -0,0 +1,156 @@
+{
+  "name": "ijfw",
+  "displayName": "IJFW — AI Efficiency Layer",
+  "version": "{{VERSION}}",
+  "description": "One install, every AI coding agent, zero config. Unifies 15 CLIs under a shared MCP memory layer so context follows you across Claude, Codex, Gemini, Cursor, Windsurf, and 10 more.",
+  "author": "Sean Donahoe",
+  "icon": "assets/ijfw-logo.svg",
+  "engines": {
+    "wayland": ">=0.6.0"
+  },
+  "hubs": ["acpAdapters", "mcpServers"],
+  "lifecycle": {
+    "onInstall": "scripts/install.js",
+    "onUninstall": "scripts/uninstall.js"
+  },
+  "contributes": {
+    "acpAdapters": [
+      {
+        "id": "claude",
+        "name": "Claude Code",
+        "description": "Anthropic's Claude Code agentic coding CLI with IJFW memory + plugin layer",
+        "connectionType": "cli",
+        "cliCommand": "claude",
+        "defaultCliPath": "npx @anthropic-ai/claude-code",
+        "supportsStreaming": true
+      },
+      {
+        "id": "codex",
+        "name": "OpenAI Codex CLI",
+        "description": "OpenAI Codex CLI with IJFW MCP memory, hooks, skills, and command aliases",
+        "connectionType": "cli",
+        "cliCommand": "codex",
+        "defaultCliPath": "npx @openai/codex",
+        "supportsStreaming": true
+      },
+      {
+        "id": "gemini",
+        "name": "Gemini CLI",
+        "description": "Google Gemini CLI with IJFW MCP memory, extension bundle, and hooks",
+        "connectionType": "cli",
+        "cliCommand": "gemini",
+        "defaultCliPath": "npx @google/gemini-cli",
+        "supportsStreaming": true
+      },
+      {
+        "id": "cursor",
+        "name": "Cursor",
+        "description": "Cursor AI editor with IJFW MCP memory and project rules",
+        "connectionType": "cli",
+        "cliCommand": "cursor",
+        "defaultCliPath": "cursor",
+        "supportsStreaming": false
+      },
+      {
+        "id": "windsurf",
+        "name": "Windsurf",
+        "description": "Windsurf AI editor with IJFW MCP memory and project rules",
+        "connectionType": "cli",
+        "cliCommand": "windsurf",
+        "defaultCliPath": "windsurf",
+        "supportsStreaming": false
+      },
+      {
+        "id": "copilot",
+        "name": "GitHub Copilot",
+        "description": "GitHub Copilot (VS Code) with IJFW MCP memory and copilot-instructions",
+        "connectionType": "cli",
+        "cliCommand": "code",
+        "defaultCliPath": "code",
+        "supportsStreaming": false
+      },
+      {
+        "id": "hermes",
+        "name": "Hermes CLI",
+        "description": "Hermes CLI with IJFW MCP memory, skills, plugin, and tier-2 hook",
+        "connectionType": "cli",
+        "cliCommand": "hermes",
+        "defaultCliPath": "npx @hermes-ai/cli",
+        "supportsStreaming": true
+      },
+      {
+        "id": "wayland",
+        "name": "Wayland CLI",
+        "description": "Wayland CLI with IJFW MCP memory, skills, plugin, and tier-2 hook",
+        "connectionType": "cli",
+        "cliCommand": "wayland",
+        "defaultCliPath": "npx @wayland-ai/cli",
+        "supportsStreaming": true
+      },
+      {
+        "id": "aider",
+        "name": "Aider",
+        "description": "Aider AI pair programmer with IJFW rules (aider.conf.yml + CONVENTIONS.md)",
+        "connectionType": "cli",
+        "cliCommand": "aider",
+        "defaultCliPath": "npx aider-chat",
+        "supportsStreaming": false
+      },
+      {
+        "id": "opencode",
+        "name": "OpenCode",
+        "description": "OpenCode CLI with IJFW MCP memory (opencode mcp.local schema)",
+        "connectionType": "cli",
+        "cliCommand": "opencode",
+        "defaultCliPath": "npx opencode-ai",
+        "supportsStreaming": true
+      },
+      {
+        "id": "qwencode",
+        "name": "Qwen Code",
+        "description": "Alibaba Qwen Code CLI with IJFW MCP memory",
+        "connectionType": "cli",
+        "cliCommand": "qwen",
+        "defaultCliPath": "npx @qwen-ai/qwen-code",
+        "supportsStreaming": true
+      },
+      {
+        "id": "cline",
+        "name": "Cline",
+        "description": "Cline VS Code extension with IJFW MCP memory (globalStorage schema)",
+        "connectionType": "cli",
+        "cliCommand": "cline",
+        "defaultCliPath": "cline",
+        "supportsStreaming": false
+      },
+      {
+        "id": "kimicode",
+        "name": "Kimi Code",
+        "description": "Moonshot Kimi Code CLI with IJFW MCP memory",
+        "connectionType": "cli",
+        "cliCommand": "kimi",
+        "defaultCliPath": "npx @moonshot-ai/kimi-code",
+        "supportsStreaming": true
+      },
+      {
+        "id": "openclaw",
+        "name": "OpenClaw",
+        "description": "OpenClaw CLI with IJFW MCP memory (mcp.servers schema)",
+        "connectionType": "cli",
+        "cliCommand": "openclaw",
+        "defaultCliPath": "npx @openclaw-ai/cli",
+        "supportsStreaming": true
+      },
+      {
+        "id": "antigravity",
+        "name": "Antigravity",
+        "description": "Antigravity AI IDE (ex-Windsurf team) with IJFW MCP memory (IDE + CLI paths)",
+        "connectionType": "cli",
+        "cliCommand": "agy",
+        "defaultCliPath": "npx @antigravity-ai/cli",
+        "supportsStreaming": true
+      }
+    ],
+    "mcpServers": ["ijfw-memory"]
+  }
+}

package/scripts/hub-extension/assets/ijfw-logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32">
+  <circle cx="16" cy="16" r="16" fill="#ff6b35"/>
+  <text x="16" y="21" font-family="sans-serif" font-size="10" font-weight="bold" fill="white" text-anchor="middle">IJFW</text>
+</svg>

package/scripts/hub-extension/install.js.tmpl

@@ -0,0 +1,41 @@
+// IJFW Hub Extension — onInstall lifecycle hook.
+// Runs in a sandboxed forked process via require() (NOT ESM).
+// Wayland forks this script with a 120s timeout; we set our own inner
+// timeouts split across two phases so we surface a clean error before
+// Wayland's hard kill.
+//
+// Phase 1 (pre-fetch): 60s — network round-trip to npm registry.
+// Phase 2 (execute):   40s — local install from cached tarball.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+// Phase 1: pre-fetch (network) — pull package into npm cache.
+const fetchResult = spawnSync(
+  'npm',
+  ['pack', '@ijfw/install@{{VERSION}}', '--silent', '--prefer-offline', '--pack-destination', '/tmp'],
+  { stdio: 'pipe', timeout: 60_000 },
+);
+if (fetchResult.status !== 0) {
+  console.error('[ijfw] pre-fetch failed');
+  process.exit(1);
+}
+
+// Phase 2: execute install (local) — npx honours cached tarball.
+const result = spawnSync(
+  'npx',
+  ['-y', '--prefer-offline', '@ijfw/install@{{VERSION}}'],
+  {
+    stdio: 'inherit',
+    timeout: 40_000,
+    env: { ...process.env, IJFW_NONINTERACTIVE: '1' },
+  },
+);
+
+if (result.status !== 0) {
+  console.error(`[ijfw] install failed (exit ${result.status})`);
+  process.exit(result.status || 1);
+}
+
+console.log('[ijfw] 15 AI coding CLIs unified');

package/scripts/hub-extension/uninstall.js.tmpl

@@ -0,0 +1,42 @@
+// IJFW Hub Extension — onUninstall lifecycle hook.
+// Runs in a sandboxed forked process via require() (NOT ESM).
+// Wayland forks this script with a 120s timeout; we set our own inner
+// timeouts split across two phases so we surface a clean error before
+// Wayland's hard kill.
+//
+// Phase 1 (pre-fetch): 60s — network round-trip to npm registry.
+// Phase 2 (execute):   40s — local uninstall from cached tarball.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+// Phase 1: pre-fetch (network) — pull package into npm cache.
+const fetchResult = spawnSync(
+  'npm',
+  ['pack', '@ijfw/install@{{VERSION}}', '--silent', '--prefer-offline', '--pack-destination', '/tmp'],
+  { stdio: 'pipe', timeout: 60_000 },
+);
+if (fetchResult.status !== 0) {
+  console.error('[ijfw] pre-fetch failed');
+  process.exit(1);
+}
+
+// Phase 2: execute uninstall (local) — positional subcommand, no '--' prefix.
+// '--uninstall' routes to "Unknown subcommand" (exit 1); 'uninstall' is correct.
+const result = spawnSync(
+  'npx',
+  ['-y', '--prefer-offline', '@ijfw/install@{{VERSION}}', 'uninstall'],
+  {
+    stdio: 'inherit',
+    timeout: 40_000,
+    env: { ...process.env, IJFW_NONINTERACTIVE: '1' },
+  },
+);
+
+if (result.status !== 0) {
+  console.error(`[ijfw] uninstall failed (exit ${result.status})`);
+  process.exit(result.status || 1);
+}
+
+console.log('[ijfw] IJFW uninstalled');

package/scripts/pack-hub-extension.js

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+// installer/scripts/pack-hub-extension.js
+//
+// Packs the IJFW Wayland Hub Extension into a distributable zip artifact.
+//
+// Outputs (all under installer/dist/ by default, or --output <dir>):
+//   ijfw-<version>.zip         — archive containing manifest + scripts dir + assets
+//   ijfw-<version>.sha512      — SRI integrity string: "sha512-<base64>"
+//   hub-index-snippet.json     — IHubExtension-shaped JSON for Wayland's Hub Index
+//
+// Usage:
+//   node scripts/pack-hub-extension.js [--output <dir>]
+//   npm run pack:hub-extension
+//   node scripts/pack-hub-extension.js --help
+//
+// Requirements: Node.js >=18. Uses only Node builtins — no external deps.
+// Deterministic: all zip entries use fixed epoch timestamp (1980-01-01 00:00:00)
+// so SHA-512 is stable across runs on identical content.
+
+import { createHash } from 'node:crypto';
+import { deflateRawSync, crc32 } from 'node:zlib';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir as osTmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// --help / -h short-circuit (L3-06)
+// Must happen before any side-effectful code runs.
+// ---------------------------------------------------------------------------
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+Usage: node scripts/pack-hub-extension.js [--output <dir>]
+
+Options:
+  --output <dir>   Write zip, sha512, and snippet into <dir> instead of the
+                   default installer/dist/ (or process.cwd() when invoked from
+                   inside node_modules).
+  --help, -h       Print this help and exit.
+
+Outputs written:
+  ijfw-<version>.zip          Distributable extension archive
+  ijfw-<version>.sha512       SRI integrity string (sha512-<base64>)
+  hub-index-snippet.json      IHubExtension entry for Wayland's Hub Index
+`.trim());
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const INSTALLER_DIR = resolve(__dirname, '..');
+const PKG_PATH = join(INSTALLER_DIR, 'package.json');
+const TMPL_PATH = join(__dirname, 'hub-extension', 'aion-extension.json.tmpl');
+const HUB_EXT_DIR = join(__dirname, 'hub-extension');
+
+// Output directory: defaults to installer/dist/. Override via `--output <dir>`
+// so consumers like Wayland's prebuild sync script can stage artifacts directly
+// into their own resources/hub/ dir without an intermediate copy step.
+//
+// The CLI flag is parsed at the script-arg level so all three invocations work:
+//   node scripts/pack-hub-extension.js                       (default dist/)
+//   node scripts/pack-hub-extension.js --output /tmp/stage    (custom dir)
+//   npx -y @ijfw/install --pack-hub-extension --output /tmp   (via ijfw CLI)
+
+// ---------------------------------------------------------------------------
+// System-path blocklist for --output validation (L1-02, L1-06)
+// ---------------------------------------------------------------------------
+
+const POSIX_SYSTEM_DIRS = [
+  '/etc', '/usr', '/bin', '/sbin', '/var',
+  '/System', '/Library', '/private',
+];
+
+const WINDOWS_SYSTEM_DIRS = [
+  'C:\\Windows', 'C:\\Program Files', 'C:\\Program Files (x86)',
+  'C:\\System Volume Information',
+];
+
+/**
+ * Returns true if the resolved path is the filesystem root or a known system
+ * directory (or a child of one).
+ *
+ * Whitelist exception: paths inside the OS temp dir (os.tmpdir()) are always
+ * allowed even when they fall under a blocked system prefix. This matters on
+ * macOS where os.tmpdir() returns `/var/folders/.../T/` — a legitimate
+ * user-writable temp space whose parent `/var` is in the blocklist. Without
+ * this exception, every Wayland prebuild that stages into a temp dir on
+ * macOS would be rejected, breaking the documented sync pipeline.
+ *
+ * @param {string} absPath  Already-resolved absolute path.
+ * @returns {boolean}
+ */
+function isSystemPath(absPath) {
+  // Reject bare filesystem roots: '/', 'C:\', 'D:\', etc.
+  if (/^[A-Za-z]:\\?$/.test(absPath) || absPath === '/') return true;
+
+  // OS temp-dir whitelist — overrides the system-prefix blocklist.
+  // Resolve both sides so macOS /var → /private/var symlinks compare cleanly.
+  try {
+    const tmp = osTmpdir();
+    const tmpReal = realpathSync(tmp);
+    const absReal = (() => { try { return realpathSync(absPath); } catch { return absPath; } })();
+    if (absReal === tmpReal || absReal.startsWith(tmpReal + '/') || absReal.startsWith(tmpReal + '\\')
+        || absPath === tmp || absPath.startsWith(tmp + '/') || absPath.startsWith(tmp + '\\')) {
+      return false;
+    }
+  } catch { /* fall through to blocklist */ }
+
+  const lc = absPath.toLowerCase();
+  const allBlocked = [...POSIX_SYSTEM_DIRS, ...WINDOWS_SYSTEM_DIRS];
+  for (const blocked of allBlocked) {
+    const bl = blocked.toLowerCase();
+    if (lc === bl || lc.startsWith(bl + '/') || lc.startsWith(bl + '\\')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Parse --output from argv. Last occurrence wins (L2-02 last-wins convention).
+ * Validates non-empty, non-flag-shaped, non-system-path (L2-01, L1-02, L1-06).
+ * Returns the resolved absolute path, or null if --output was not present.
+ * @param {string[]} argv  process.argv.slice(2)
+ * @returns {string|null}
+ */
+function parseOutputArg(argv) {
+  let dir = null;
+
+  // Iterate all positions so last --output wins (L2-02).
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--output') {
+      if (i + 1 >= argv.length) {
+        console.error('[pack-hub-extension] ERROR: --output requires a directory argument');
+        process.exit(2);
+      }
+      dir = argv[i + 1];
+      i++; // skip value on next iteration
+    }
+  }
+
+  if (dir === null) return null; // flag not present — caller uses default
+
+  // L2-01: reject whitespace-only or flag-shaped values.
+  if (!dir || dir.trim() === '' || dir.startsWith('-')) {
+    console.error('[pack-hub-extension] ERROR: --output requires a non-empty directory argument');
+    process.exit(2);
+  }
+
+  const abs = resolve(process.cwd(), dir.trim());
+
+  // L1-02, L1-06: reject filesystem root and system directories.
+  if (isSystemPath(abs)) {
+    console.error(
+      `[pack-hub-extension] ERROR: --output "${abs}" is a system path. ` +
+      'Choose a user-writable directory.'
+    );
+    process.exit(2);
+  }
+
+  return abs;
+}
+
+/**
+ * Return the default output directory.
+ * When invoked from inside node_modules (npm-global install), default to
+ * process.cwd() so we don't pollute the package installation directory (L3-07).
+ * @returns {string}
+ */
+function defaultOutputDir() {
+  return __dirname.includes('node_modules')
+    ? process.cwd()
+    : join(INSTALLER_DIR, 'dist');
+}
+
+const _explicitOutput = parseOutputArg(process.argv.slice(2));
+const DIST_DIR = _explicitOutput !== null ? _explicitOutput : defaultOutputDir();
+
+// L3-07: always announce where output will land so the caller knows.
+console.log(
+  `[pack-hub-extension] NOTE: writing artifacts to ${resolve(DIST_DIR)}` +
+  (_explicitOutput === null ? '. Use --output <dir> to redirect.' : '.')
+);
+
+// ---------------------------------------------------------------------------
+// Safe write helper — wraps writeFileSync with a clean error UX (L2-09)
+// ---------------------------------------------------------------------------
+
+/**
+ * Write `content` to `filePath`, exiting with a clean error message on failure.
+ * @param {string} filePath
+ * @param {Buffer|string} content
+ * @param {string} [encoding]
+ */
+function safeWrite(filePath, content, encoding) {
+  try {
+    if (encoding !== undefined) {
+      writeFileSync(filePath, content, encoding);
+    } else {
+      writeFileSync(filePath, content);
+    }
+  } catch (err) {
+    console.error(`[pack-hub-extension] ERROR: cannot write to ${filePath}: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// L2-06: verify hub-extension/ source tree exists before any read/zip work.
+// Without this guard, a malformed install (e.g., scripts/hub-extension/ pruned
+// from a custom build) produces a raw Node ENOENT stack trace mid-banner with
+// no [pack-hub-extension] prefix — confusing for Wayland's sync script
+// consumers. Fail-fast with a clean, actionable error instead.
+// ---------------------------------------------------------------------------
+
+if (!existsSync(HUB_EXT_DIR)) {
+  console.error(
+    `[pack-hub-extension] ERROR: hub-extension source dir missing: ${HUB_EXT_DIR}\n` +
+    '[pack-hub-extension] Ensure scripts/hub-extension/ ships alongside this script.\n' +
+    '[pack-hub-extension] If invoked via npx, your @ijfw/install tarball may be incomplete.'
+  );
+  process.exit(1);
+}
+if (!existsSync(TMPL_PATH)) {
+  console.error(
+    `[pack-hub-extension] ERROR: hub-extension manifest template missing: ${TMPL_PATH}`
+  );
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Read version from package.json
+// ---------------------------------------------------------------------------
+
+const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'));
+const VERSION = pkg.version;
+if (!VERSION) {
+  console.error('[pack-hub-extension] ERROR: could not read version from package.json');
+  process.exit(1);
+}
+
+console.log(`[pack-hub-extension] packaging IJFW Hub Extension v${VERSION}`);
+
+// ---------------------------------------------------------------------------
+// Render manifest template
+// ---------------------------------------------------------------------------
+
+const tmpl = readFileSync(TMPL_PATH, 'utf8');
+const manifest = tmpl.replaceAll('{{VERSION}}', VERSION);
+
+let manifestObj;
+try {
+  manifestObj = JSON.parse(manifest);
+} catch (err) {
+  console.error('[pack-hub-extension] ERROR: rendered manifest is not valid JSON:', err.message);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Collect files to pack (deterministic: sorted by zip entry path)
+// ---------------------------------------------------------------------------
+// Layout inside zip:
+//   aion-extension.json
+//   scripts/install.js
+//   scripts/uninstall.js
+//   assets/ijfw-logo.svg   (if present)
+
+/** @type {Array<{zipPath: string, content: Buffer}>} */
+const entries = [];
+
+// Manifest (rendered in memory — no temp file needed)
+entries.push({
+  zipPath: 'aion-extension.json',
+  content: Buffer.from(manifest + '\n', 'utf8'),
+});
+
+// scripts/ — render .tmpl files with {{VERSION}} substitution at pack time so
+// the bundled hooks reference the exact pinned version rather than @latest.
+// Backward-compat: if no .tmpl exists but the plain .js does, zip it as-is.
+for (const name of ['install.js', 'uninstall.js']) {
+  const tmplSrc = join(HUB_EXT_DIR, `${name}.tmpl`);
+  const jsSrc = join(HUB_EXT_DIR, name);
+  let content;
+  if (existsSync(tmplSrc)) {
+    const raw = readFileSync(tmplSrc, 'utf8');
+    content = Buffer.from(raw.replaceAll('{{VERSION}}', VERSION), 'utf8');
+  } else if (existsSync(jsSrc)) {
+    content = readFileSync(jsSrc);
+  } else {
+    console.error(`[pack-hub-extension] ERROR: neither ${name}.tmpl nor ${name} found in hub-extension/scripts`);
+    process.exit(1);
+  }
+  entries.push({ zipPath: `scripts/${name}`, content });
+}
+
+// assets/ (walk directory, sorted)
+const assetsDir = join(HUB_EXT_DIR, 'assets');
+if (existsSync(assetsDir)) {
+  const assetFiles = readdirSync(assetsDir).sort();
+  for (const name of assetFiles) {
+    const full = join(assetsDir, name);
+    if (statSync(full).isFile()) {
+      entries.push({
+        zipPath: `assets/${name}`,
+        content: readFileSync(full),
+      });
+    } else if (statSync(full).isDirectory()) {
+      // L2-08: future-proof warning; current placeholder SVG is single-file.
+      console.warn(`[pack-hub-extension] WARNING: assets subdir ignored: ${name}/`);
+    }
+  }
+}
+
+// Sort entries for fully deterministic output regardless of fs ordering.
+entries.sort((a, b) => a.zipPath < b.zipPath ? -1 : a.zipPath > b.zipPath ? 1 : 0);
+
+// ---------------------------------------------------------------------------
+// Build deterministic ZIP (PKZIP format, all entries stored with deflate)
+//
+// Fixed MS-DOS timestamp: 1980-01-01 00:00:00
+//   date word: year-1980=0, month=1, day=1  → 0x0021
+//   time word: hour=0, min=0, sec/2=0       → 0x0000
+// ---------------------------------------------------------------------------
+
+const DOS_DATE = 0x0021; // 1980-01-01
+const DOS_TIME = 0x0000; // 00:00:00
+
+/**
+ * Write a little-endian uint16 into buf at offset.
+ * @param {Buffer} buf
+ * @param {number} offset
+ * @param {number} value
+ */
+function writeU16LE(buf, offset, value) {
+  buf[offset] = value & 0xff;
+  buf[offset + 1] = (value >> 8) & 0xff;
+}
+
+/**
+ * Write a little-endian uint32 into buf at offset.
+ * @param {Buffer} buf
+ * @param {number} offset
+ * @param {number} value
+ */
+function writeU32LE(buf, offset, value) {
+  buf.writeUInt32LE(value >>> 0, offset);
+}
+
+const ZIP_PARTS = []; // array of Buffers forming the zip stream
+
+/** @type {Array<{zipPath: string, crc: number, compSize: number, uncompSize: number, offset: number}>} */
+const centralDirEntries = [];
+
+let offset = 0;
+
+for (const { zipPath, content } of entries) {
+  const nameBytes = Buffer.from(zipPath, 'utf8');
+  const uncompSize = content.length;
+  const crc = crc32(content) >>> 0;
+
+  // Deflate the content.
+  const compressed = deflateRawSync(content, { level: 9 });
+  // Use stored (method=0) if deflate is bigger or equal — keeps zip valid.
+  const useDeflate = compressed.length < uncompSize;
+  const compMethod = useDeflate ? 8 : 0;
+  const compData = useDeflate ? compressed : content;
+  const compSize = compData.length;
+
+  // Local file header: signature + 26 bytes fixed + filename.
+  const localHeader = Buffer.alloc(30 + nameBytes.length);
+  writeU32LE(localHeader, 0, 0x04034b50);  // local file header sig
+  writeU16LE(localHeader, 4, 20);           // version needed: 2.0
+  writeU16LE(localHeader, 6, 0);            // general purpose bit flag
+  writeU16LE(localHeader, 8, compMethod);   // compression method
+  writeU16LE(localHeader, 10, DOS_TIME);    // last mod time
+  writeU16LE(localHeader, 12, DOS_DATE);    // last mod date
+  writeU32LE(localHeader, 14, crc);         // crc-32
+  writeU32LE(localHeader, 18, compSize);    // compressed size
+  writeU32LE(localHeader, 22, uncompSize);  // uncompressed size
+  writeU16LE(localHeader, 26, nameBytes.length); // file name length
+  writeU16LE(localHeader, 28, 0);           // extra field length
+  nameBytes.copy(localHeader, 30);
+
+  centralDirEntries.push({
+    zipPath,
+    nameBytes,
+    crc,
+    compSize,
+    uncompSize,
+    compMethod,
+    offset,
+  });
+
+  ZIP_PARTS.push(localHeader, compData);
+  offset += localHeader.length + compData.length;
+}
+
+// Central directory.
+const centralDirStart = offset;
+for (const e of centralDirEntries) {
+  const cdEntry = Buffer.alloc(46 + e.nameBytes.length);
+  writeU32LE(cdEntry, 0, 0x02014b50);       // central dir sig
+  writeU16LE(cdEntry, 4, 20);               // version made by: 2.0
+  writeU16LE(cdEntry, 6, 20);               // version needed: 2.0
+  writeU16LE(cdEntry, 8, 0);                // general purpose bit flag
+  writeU16LE(cdEntry, 10, e.compMethod);    // compression method
+  writeU16LE(cdEntry, 12, DOS_TIME);        // last mod time
+  writeU16LE(cdEntry, 14, DOS_DATE);        // last mod date
+  writeU32LE(cdEntry, 16, e.crc);           // crc-32
+  writeU32LE(cdEntry, 20, e.compSize);      // compressed size
+  writeU32LE(cdEntry, 24, e.uncompSize);    // uncompressed size
+  writeU16LE(cdEntry, 28, e.nameBytes.length); // file name length
+  writeU16LE(cdEntry, 30, 0);               // extra field length
+  writeU16LE(cdEntry, 32, 0);               // file comment length
+  writeU16LE(cdEntry, 34, 0);               // disk number start
+  writeU16LE(cdEntry, 36, 0);               // internal file attributes
+  writeU32LE(cdEntry, 38, 0);               // external file attributes
+  writeU32LE(cdEntry, 42, e.offset);        // relative offset of local header
+  e.nameBytes.copy(cdEntry, 46);
+  ZIP_PARTS.push(cdEntry);
+  offset += cdEntry.length;
+}
+
+const centralDirSize = offset - centralDirStart;
+
+// End of central directory record.
+const eocd = Buffer.alloc(22);
+writeU32LE(eocd, 0, 0x06054b50);           // EOCD signature
+writeU16LE(eocd, 4, 0);                    // disk number
+writeU16LE(eocd, 6, 0);                    // disk with central dir
+writeU16LE(eocd, 8, centralDirEntries.length);  // entries on this disk
+writeU16LE(eocd, 10, centralDirEntries.length); // total entries
+writeU32LE(eocd, 12, centralDirSize);      // size of central directory
+writeU32LE(eocd, 16, centralDirStart);     // offset of central directory
+writeU16LE(eocd, 20, 0);                   // comment length
+ZIP_PARTS.push(eocd);
+
+const zipBuffer = Buffer.concat(ZIP_PARTS);
+
+// ---------------------------------------------------------------------------
+// Write zip
+// ---------------------------------------------------------------------------
+
+mkdirSync(DIST_DIR, { recursive: true });
+
+const ZIP_NAME = `ijfw-${VERSION}.zip`;
+const ZIP_PATH = join(DIST_DIR, ZIP_NAME);
+safeWrite(ZIP_PATH, zipBuffer);
+
+const zipSize = zipBuffer.length;
+console.log(`[pack-hub-extension] zip: ${ZIP_PATH} (${zipSize} bytes)`);
+
+// ---------------------------------------------------------------------------
+// Compute SHA-512 SRI (sync — buffer already in memory)
+// ---------------------------------------------------------------------------
+
+const hashHex = createHash('sha512').update(zipBuffer).digest('hex');
+const sri = `sha512-${Buffer.from(hashHex, 'hex').toString('base64')}`;
+
+const SHA_PATH = join(DIST_DIR, `ijfw-${VERSION}.sha512`);
+safeWrite(SHA_PATH, sri, 'utf8');
+console.log(`[pack-hub-extension] sha512: ${SHA_PATH}`);
+console.log(`[pack-hub-extension] SRI: ${sri}`);
+
+// ---------------------------------------------------------------------------
+// Write hub-index-snippet.json (IHubExtension shape for Wayland's Hub Index)
+// ---------------------------------------------------------------------------
+
+// HubContributes in the index uses string ID arrays (not full adapter objects).
+const adapterIds = manifestObj.contributes.acpAdapters.map((a) => a.id);
+
+const hubIndexSnippet = {
+  name: manifestObj.name,
+  displayName: manifestObj.displayName,
+  version: VERSION,
+  description: manifestObj.description,
+  author: manifestObj.author,
+  icon: manifestObj.icon,
+  dist: {
+    tarball: `extensions/${ZIP_NAME}`,
+    integrity: sri,
+    unpackedSize: zipSize,
+  },
+  engines: manifestObj.engines,
+  hubs: manifestObj.hubs,
+  contributes: {
+    acpAdapters: adapterIds,
+    mcpServers: manifestObj.contributes.mcpServers,
+  },
+  tags: ['ai', 'coding', 'mcp', 'memory', 'multi-agent'],
+};
+
+const SNIPPET_PATH = join(DIST_DIR, 'hub-index-snippet.json');
+safeWrite(SNIPPET_PATH, JSON.stringify(hubIndexSnippet, null, 2) + '\n', 'utf8');
+console.log(`[pack-hub-extension] hub index snippet: ${SNIPPET_PATH}`);
+
+// ---------------------------------------------------------------------------
+// Done
+// ---------------------------------------------------------------------------
+
+console.log(`[pack-hub-extension] DONE — ${ZIP_NAME} ready for Wayland bundling`);