@selvakumaresra/specship 0.1.0

package/scripts/local-install.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Build the current branch and link it as the global `specship` for
+# hands-on testing. Replaces any existing global install for as long
+# as the symlink is in place.
+#
+# Usage:
+#   ./scripts/local-install.sh           # build + link
+#   ./scripts/local-install.sh --undo    # unlink + restore the published version
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+PKG=$(node -p "require('./package.json').name")
+VERSION=$(node -p "require('./package.json').version")
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+if [ "${1:-}" = "--undo" ]; then
+  echo "→ unlinking ${PKG}"
+  npm unlink -g "${PKG}" >/dev/null 2>&1 || true
+  echo "→ reinstalling published ${PKG}"
+  npm install -g "${PKG}"
+  echo "done: global specship -> $(command -v specship)"
+  exit 0
+fi
+
+echo "→ building ${PKG} ${VERSION} (${BRANCH})"
+npm run build
+
+echo "→ linking globally"
+npm link
+
+LINKED=$(command -v specship || echo "(not on PATH)")
+echo
+echo "✓ global specship now points to this branch"
+echo "  binary:  ${LINKED}"
+echo "  branch:  ${BRANCH}"
+echo "  version: ${VERSION}"
+echo
+echo "To restore the published version:"
+echo "  ./scripts/local-install.sh --undo"

package/scripts/npm-sdk.js

@@ -0,0 +1,75 @@
+'use strict';
+//
+// Programmatic / embedded SDK entry for @selvakumaresra/specship (issue #354).
+//
+// The CLI/MCP `bin` (npm-shim.js) execs the per-platform bundle's OWN Node 24 so
+// the tool never depends on the user's runtime. Embedded library consumers are
+// the opposite case: they already run their own Node and just want the compiled
+// API — `require("@selvakumaresra/specship")` returning the SpecShip class et al.
+//
+// The compiled library + its production dependencies (web-tree-sitter,
+// tree-sitter-wasms, …) ship INSIDE the per-platform bundle, at
+//   @selvakumaresra/specship-<platform>-<arch>/lib/dist/index.js
+// (with the deps in the sibling lib/node_modules). Re-exporting that bundle keeps
+// the main package thin — no second 50 MB copy of the grammars — while making the
+// SDK work in the consumer's process. Types are a separate concern: the main
+// package ships its own dist/**/*.d.ts tree (pointed at by `types`), built from
+// the same release so it can never skew from the runtime it re-exports.
+//
+// node:sqlite (Node >= 22.5) is required to OPEN a graph, but only lazily inside
+// the SQLite adapter — so loading this module is safe on older Node, and the
+// node:sqlite requirement surfaces with an actionable error only when a DB is
+// actually opened. Heavy extraction additionally wants the bundled launcher's
+// --liftoff-only flag (the WASM Zone-OOM guard, issues #293/#298); an embedded
+// host that drives large indexing should pass that flag to its own Node.
+
+var path = require('path');
+var os = require('os');
+var fs = require('fs');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@selvakumaresra/specship-' + target;
+
+module.exports = require(resolveLibrary());
+
+// Locate the compiled library entry inside the installed per-platform bundle.
+// Throws an actionable error (rather than a bare MODULE_NOT_FOUND) when no bundle
+// is present, so an embedded consumer knows exactly what to install.
+function resolveLibrary() {
+  // 1) The npm-installed optional dependency — the normal case.
+  try {
+    return require.resolve(pkg + '/lib/dist/index.js');
+  } catch (e) {
+    /* fall through to the self-healed cache */
+  }
+
+  // 2) A bundle the CLI shim self-healed from GitHub Releases into the cache
+  //    (issue #303). Same node/lib/bin layout as the npm package. We only REUSE a
+  //    cached bundle here — unlike the CLI shim we never trigger a network
+  //    download from inside require(), which must stay synchronous and cheap.
+  var cached = cachedLibrary();
+  if (cached) return cached;
+
+  throw new Error(
+    'specship: the programmatic API is unavailable because the platform bundle\n' +
+    '(' + pkg + ') is not installed.\n' +
+    'The compiled library ships inside that per-platform optional dependency.\n' +
+    'Fixes:\n' +
+    '  - install from the official npm registry so the matching bundle is fetched:\n' +
+    '      npm i @selvakumaresra/specship --registry=https://registry.npmjs.org\n' +
+    '  - or run the CLI once (e.g. `npx @selvakumaresra/specship status`) to\n' +
+    '    self-heal the bundle into ~/.specship, then require() will find it.'
+  );
+}
+
+function cachedLibrary() {
+  try {
+    var version = require(path.join(__dirname, 'package.json')).version;
+    var base = process.env.SPECSHIP_INSTALL_DIR || path.join(os.homedir(), '.specship');
+    var lib = path.join(base, 'bundles', target + '-' + version, 'lib', 'dist', 'index.js');
+    if (fs.existsSync(lib)) return lib;
+  } catch (e) {
+    /* no readable cache → caller reports the install guidance */
+  }
+  return null;
+}

package/scripts/npm-shim.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+'use strict';
+//
+// npm thin-installer launcher for SpecShip.
+//
+// The heavy artifact (a vendored Node runtime + the app) ships as a per-platform
+// optionalDependency: @selvakumaresra/specship-<platform>-<arch>. npm installs
+// only the one matching the host, via each package's `os`/`cpu` fields (the
+// esbuild pattern). This shim — run by the user's OWN Node — locates that bundle
+// and execs its launcher, so the real work always runs on the bundled Node 24
+// (with node:sqlite), regardless of the user's Node version. The user's Node is
+// only ever a launcher; even an ancient version can run this file.
+//
+// Self-heal (issue #303): some registries — notably the npmmirror/cnpm mirrors,
+// and some corporate proxies — don't reliably mirror the per-platform
+// optionalDependencies. npm treats an unfetchable optional dep as success and
+// silently skips it, so the bundle goes missing and every command fails. When
+// the installed bundle can't be resolved, this shim falls back to downloading
+// the matching bundle straight from GitHub Releases — the very archive
+// install.sh uses — into a cache dir, then runs that. Knobs:
+//   SPECSHIP_NO_DOWNLOAD=1     disable the network fallback (print guidance)
+//   SPECSHIP_INSTALL_DIR=DIR   cache location (default: ~/.specship)
+//   SPECSHIP_DOWNLOAD_BASE=URL release-download base (for mirrors/air-gapped)
+//
+// Wired up at release time as the main package's `bin`:
+//   "bin": { "specship": "npm-shim.js" }
+// with the platform packages listed in `optionalDependencies`.
+
+var childProcess = require('child_process');
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@selvakumaresra/specship-' + target;
+var isWindows = process.platform === 'win32';
+var REPO = 'selvakumarEsra/specship';
+
+main().catch(function (e) {
+  process.stderr.write('specship: ' + (e && e.message ? e.message : String(e)) + '\n');
+  process.exit(1);
+});
+
+async function main() {
+  // Happy path: the npm-installed optional dependency. Fall back to a download
+  // when the registry didn't deliver it.
+  var resolved = resolveInstalledBundle() || (await selfHealBundle());
+  var res = childProcess.spawnSync(resolved.command, resolved.args, { stdio: 'inherit' });
+  if (res.error) {
+    process.stderr.write('specship: ' + res.error.message + '\n');
+    process.exit(1);
+  }
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+// Resolve the launcher from the installed per-platform optionalDependency.
+// Returns {command, args} or null if the package isn't installed.
+function resolveInstalledBundle() {
+  try {
+    if (isWindows) {
+      // Modern Node refuses to spawn the bundle's .cmd directly (EINVAL, the
+      // CVE-2024-27980 hardening on Node 24), so invoke the bundled node.exe
+      // against the app entry point and pass --liftoff-only here.
+      var nodeExe = require.resolve(pkg + '/node.exe');
+      var entry = require.resolve(pkg + '/lib/dist/bin/specship.js');
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+    return { command: require.resolve(pkg + '/bin/specship'), args: process.argv.slice(2) };
+  } catch (e) {
+    return null;
+  }
+}
+
+// Locate the launcher inside an extracted GitHub bundle directory (same
+// node/lib/bin layout as the npm platform package). Returns {command, args} or
+// null when the directory doesn't hold a usable bundle yet.
+function launcherIn(dir) {
+  if (isWindows) {
+    var nodeExe = path.join(dir, 'node.exe');
+    var entry = path.join(dir, 'lib', 'dist', 'bin', 'specship.js');
+    if (fs.existsSync(nodeExe) && fs.existsSync(entry)) {
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+  } else {
+    var launcher = path.join(dir, 'bin', 'specship');
+    if (fs.existsSync(launcher)) return { command: launcher, args: process.argv.slice(2) };
+  }
+  return null;
+}
+
+// --liftoff-only keeps tree-sitter's WASM grammars off V8's turboshaft tier to
+// avoid the Zone OOM on Node >= 22 (issues #293/#298). The unix bin/specship
+// launcher already passes it; on Windows we invoke node.exe directly so add it.
+function liftoff(entry) {
+  return ['--liftoff-only', entry].concat(process.argv.slice(2));
+}
+
+// Download + cache the platform bundle from GitHub Releases. Returns
+// {command, args}; exits the process with guidance if it can't.
+async function selfHealBundle() {
+  var version = readVersion();
+  var bundlesDir = path.join(process.env.SPECSHIP_INSTALL_DIR || path.join(os.homedir(), '.specship'), 'bundles');
+  var dest = path.join(bundlesDir, target + '-' + version);
+
+  // Already downloaded by a previous run? Use it even when downloads are
+  // disabled — SPECSHIP_NO_DOWNLOAD blocks fetching, not a cached bundle.
+  var cached = launcherIn(dest);
+  if (cached) return cached;
+
+  if (process.env.SPECSHIP_NO_DOWNLOAD) {
+    fail('the network fallback is disabled (SPECSHIP_NO_DOWNLOAD is set).');
+  }
+
+  var asset = 'specship-' + target + (isWindows ? '.zip' : '.tar.gz');
+  var base = process.env.SPECSHIP_DOWNLOAD_BASE || ('https://github.com/' + REPO + '/releases/download');
+  var url = base + '/v' + version + '/' + asset;
+
+  process.stderr.write(
+    'specship: platform bundle missing (registry did not provide ' + pkg + ').\n' +
+    'specship: downloading ' + asset + ' from GitHub Releases (' + version + ')...\n'
+  );
+
+  // Stage inside bundlesDir so the final rename is on the same filesystem (atomic,
+  // no EXDEV across tmpfs). Strip the archive's top-level specship-<target>/ dir.
+  fs.mkdirSync(bundlesDir, { recursive: true });
+  var stage = fs.mkdtempSync(path.join(bundlesDir, '.dl-'));
+  try {
+    var archivePath = path.join(stage, asset);
+    await download(url, archivePath, 6);
+    await verifyChecksum(archivePath, asset, base, version);
+    var extracted = path.join(stage, 'bundle');
+    fs.mkdirSync(extracted);
+    extract(archivePath, extracted);
+
+    var raced = launcherIn(dest); // another process may have finished meanwhile
+    if (raced) { rmrf(stage); return raced; }
+    try {
+      fs.renameSync(extracted, dest);
+    } catch (e) {
+      var other = launcherIn(dest); // lost the race but theirs is valid
+      if (other) { rmrf(stage); return other; }
+      throw e;
+    }
+  } catch (e) {
+    rmrf(stage);
+    fail('download failed (' + e.message + ').\n  URL: ' + url);
+  }
+  rmrf(stage);
+
+  var ready = launcherIn(dest);
+  if (!ready) fail('downloaded bundle is missing its launcher under ' + dest + '.');
+  process.stderr.write('specship: bundle ready.\n');
+  return ready;
+}
+
+function readVersion() {
+  try {
+    return require(path.join(__dirname, 'package.json')).version;
+  } catch (e) {
+    fail('could not read this package\'s version to locate a matching release.');
+  }
+}
+
+// GET with manual redirect following (GitHub release URLs redirect to a CDN).
+function download(url, dest, redirectsLeft) {
+  return new Promise(function (resolve, reject) {
+    var https = require('https');
+    // timeout is an idle/inactivity timeout — it won't kill a slow-but-progressing
+    // download, only a stalled connection (so a blocked mirror fails fast with
+    // guidance instead of hanging the user's command forever).
+    var req = https.get(url, { headers: { 'User-Agent': 'specship-npm-shim' }, timeout: 30000 }, function (res) {
+      var status = res.statusCode;
+      if (status >= 300 && status < 400 && res.headers.location) {
+        res.resume();
+        if (redirectsLeft <= 0) { reject(new Error('too many redirects')); return; }
+        download(new URL(res.headers.location, url).toString(), dest, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) { res.resume(); reject(new Error('HTTP ' + status)); return; }
+      var file = fs.createWriteStream(dest);
+      res.on('error', reject);
+      res.pipe(file);
+      file.on('error', reject);
+      file.on('finish', function () { file.close(function () { resolve(); }); });
+    });
+    req.on('timeout', function () { req.destroy(new Error('connection timed out')); });
+    req.on('error', reject);
+  });
+}
+
+// Best-effort integrity check. When the release publishes a SHA256SUMS file, the
+// downloaded archive MUST match its listed hash or we abort. When that file is
+// absent (older releases) or simply unreachable, we proceed — the archive still
+// arrived from GitHub over TLS. So tampering/corruption is caught, while a
+// missing checksum never breaks an install.
+async function verifyChecksum(archivePath, asset, base, version) {
+  var sumsPath = archivePath + '.SHA256SUMS';
+  try {
+    await download(base + '/v' + version + '/SHA256SUMS', sumsPath, 6);
+  } catch (e) {
+    return; // not published / unreachable → skip
+  }
+  var expected = null;
+  var lines = fs.readFileSync(sumsPath, 'utf8').split('\n');
+  for (var i = 0; i < lines.length; i++) {
+    var m = lines[i].trim().match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
+    if (m && path.basename(m[2].trim()) === asset) { expected = m[1].toLowerCase(); break; }
+  }
+  if (!expected) return; // asset not listed → nothing to check
+  var actual = require('crypto').createHash('sha256').update(fs.readFileSync(archivePath)).digest('hex');
+  if (actual !== expected) {
+    throw new Error('checksum mismatch for ' + asset +
+      ' (expected ' + expected.slice(0, 12) + '…, got ' + actual.slice(0, 12) + '…)');
+  }
+  process.stderr.write('specship: checksum verified.\n');
+}
+
+// Extract via the system tar — present on macOS, Linux, and Windows 10+
+// (bsdtar reads .zip too). No third-party dependency in the shim.
+function extract(archive, destDir) {
+  var args = isWindows
+    ? ['-xf', archive, '-C', destDir, '--strip-components=1']
+    : ['-xzf', archive, '-C', destDir, '--strip-components=1'];
+  var res = childProcess.spawnSync('tar', args, { stdio: 'ignore' });
+  if (res.error) throw new Error('tar unavailable: ' + res.error.message);
+  if (res.status !== 0) throw new Error('tar exited ' + res.status);
+}
+
+function rmrf(p) {
+  try { fs.rmSync(p, { recursive: true, force: true }); } catch (e) { /* best effort */ }
+}
+
+function fail(reason) {
+  process.stderr.write(
+    'specship: no prebuilt bundle for ' + target + '.\n' +
+    (reason ? 'specship: ' + reason + '\n' : '') +
+    'Expected the optional package ' + pkg + ' to be installed.\n' +
+    'A registry mirror (e.g. npmmirror/cnpm) that did not mirror the per-platform\n' +
+    'package is the usual cause. Fixes:\n' +
+    '  - install from the official registry:\n' +
+    '      npm i -g @selvakumaresra/specship --registry=https://registry.npmjs.org\n' +
+    '  - or use the standalone installer (no Node required):\n' +
+    '      curl -fsSL https://raw.githubusercontent.com/' + REPO + '/main/install.sh | sh\n'
+  );
+  process.exit(1);
+}

package/scripts/offline-install.ps1

@@ -0,0 +1,148 @@
+<#
+.SYNOPSIS
+  Offline / air-gapped install of SpecShip from this source folder (Windows).
+
+.DESCRIPTION
+  Assumes the client workstation has:
+    - Node.js (>=18 <25) and npm on PATH
+    - npm configured against a registry it CAN reach (e.g. a private mirror)
+    - No git, no public GitHub access required
+
+  Does NOT call git, does NOT download anything from github.com. Dependencies
+  are pulled from whatever registry npm is already pointed at.
+
+.PARAMETER SkipClaude
+  Skip wiring Claude Code at the end.
+
+.PARAMETER Undo
+  Unlink the global `specship` symlink and exit.
+
+.EXAMPLE
+  .\scripts\offline-install.ps1
+  .\scripts\offline-install.ps1 -SkipClaude
+  .\scripts\offline-install.ps1 -Undo
+#>
+[CmdletBinding()]
+param(
+  [switch]$SkipClaude,
+  [switch]$Undo
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Resolve repo root from this script's location (no git).
+$Repo = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+Set-Location $Repo
+
+$Pkg     = node -p "require('./package.json').name"
+$Version = node -p "require('./package.json').version"
+
+if ($Undo) {
+  Write-Host "[offline-install] unlinking $Pkg"
+  & npm unlink -g $Pkg 2>$null
+  Write-Host "[offline-install] done"
+  exit 0
+}
+
+# --- Node version gate ---------------------------------------------------
+# Tighter than package.json engines (>=18 <25): the runtime needs node:sqlite
+# (Node 22.5+) AND that SQLite must have FTS5 compiled in. SpecShip's own
+# release bundle pins v24.16.0 for that reason; older Node builds either lack
+# node:sqlite entirely or ship SQLite without FTS5.
+$NodeMajor = [int](node -p "process.versions.node.split('.')[0]")
+$NodeMinor = [int](node -p "process.versions.node.split('.')[1]")
+if ($NodeMajor -lt 22 -or
+    ($NodeMajor -eq 22 -and $NodeMinor -lt 5) -or
+    $NodeMajor -ge 25) {
+  $nv = node --version
+  Write-Error "[offline-install] Node $nv is unsupported. Requires >=22.5 <25 (Node 24.x recommended)."
+  exit 1
+}
+
+# --- FTS5 capability probe ---------------------------------------------
+# Fail fast with a clear remediation message instead of letting `specship init`
+# die with a cryptic "no such module: fts5" deep inside indexing. node:sqlite
+# is present from 22.5+, but FTS5 is only enabled in newer Node builds —
+# Node 22.x typically ships SQLite without it.
+$probeScript = @'
+try {
+  const { DatabaseSync } = require('node:sqlite');
+  const db = new DatabaseSync(':memory:');
+  db.exec("CREATE VIRTUAL TABLE t USING fts5(x)");
+  console.log('OK');
+} catch (e) {
+  console.log('FAIL:' + e.message);
+}
+'@
+$probe = (node -e $probeScript 2>$null)
+if ($probe -eq 'OK') {
+  # FTS5 ok
+} elseif ($probe -like 'FAIL:*') {
+  $msg = $probe.Substring(5)
+  $nv  = node --version
+  Write-Error @"
+[offline-install] SQLite probe failed: $msg
+
+SpecShip requires Node.js whose bundled SQLite has FTS5 enabled. Your Node
+($nv) does not. Install Node 24.x and re-run this script. SpecShip's
+release bundle pins v24.16.0 as the known-good version.
+"@
+  exit 1
+} else {
+  Write-Error "[offline-install] unable to probe node:sqlite. Need Node >=22.5 (24.x recommended)."
+  exit 1
+}
+
+$Registry = npm config get registry
+Write-Host "[offline-install] repo:     $Repo"
+Write-Host "[offline-install] package:  $Pkg@$Version"
+Write-Host "[offline-install] node:     $(node --version)"
+Write-Host "[offline-install] registry: $Registry"
+
+# --- install deps --------------------------------------------------------
+if (Test-Path 'package-lock.json') {
+  Write-Host "[offline-install] npm ci"
+  & npm ci
+} else {
+  Write-Host "[offline-install] npm install"
+  & npm install
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# --- build ---------------------------------------------------------------
+Write-Host "[offline-install] npm run build"
+& npm run build
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# --- link as global specship -------------------------------------------
+Write-Host "[offline-install] npm link"
+& npm link
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# Avoid PS 7+ null-conditional (?.) — locked-down Windows clients often ship
+# only Windows PowerShell 5.1, where ?. fails to parse.
+$cmd    = Get-Command specship -ErrorAction SilentlyContinue
+$Linked = if ($cmd) { $cmd.Source } else { '(not on PATH)' }
+Write-Host "[offline-install] specship -> $Linked"
+
+# --- wire Claude Code (non-interactive) ---------------------------------
+# Invoke the just-built binary directly instead of relying on `specship` being
+# visible on PATH in this PowerShell session — `npm link`'s shim may not be
+# picked up until the user opens a new shell.
+if (-not $SkipClaude) {
+  Write-Host "[offline-install] wiring Claude Code"
+  & node (Join-Path $Repo 'dist/bin/specship.js') install --target claude -y
+  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
+Write-Host ""
+Write-Host "[OK] SpecShip $Version installed offline from source."
+Write-Host "  binary: $Linked"
+Write-Host "  source: $Repo"
+Write-Host ""
+Write-Host "Next:"
+Write-Host "  specship --version"
+Write-Host "  cd <your-project>; specship init; specship index"
+Write-Host ""
+Write-Host "To uninstall:"
+Write-Host "  .\scripts\offline-install.ps1 -Undo"

package/scripts/offline-install.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+#
+# Offline / air-gapped install of SpecShip from this source folder.
+#
+# Assumes the client workstation has:
+#   - Node.js (>=18 <25) and npm on PATH
+#   - npm configured against a registry it CAN reach (e.g. a private mirror)
+#   - No git, no public GitHub access required
+#
+# Does NOT call git, does NOT download anything from github.com. Dependencies
+# are pulled from whatever registry npm is already pointed at.
+#
+# Usage:
+#   ./scripts/offline-install.sh                    # build, link, wire Claude Code
+#   ./scripts/offline-install.sh --skip-claude      # build + link only
+#   ./scripts/offline-install.sh --undo             # unlink the global symlink
+#
+# After install:  `specship --version` should print the package.json version.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+REPO="$(pwd)"
+
+PKG=$(node -p "require('./package.json').name")
+VERSION=$(node -p "require('./package.json').version")
+
+# --- undo path ---------------------------------------------------------------
+if [ "${1:-}" = "--undo" ]; then
+  echo "[offline-install] unlinking ${PKG}"
+  npm unlink -g "${PKG}" >/dev/null 2>&1 || true
+  echo "[offline-install] done"
+  exit 0
+fi
+
+SKIP_CLAUDE=0
+[ "${1:-}" = "--skip-claude" ] && SKIP_CLAUDE=1
+
+# --- Node version gate -------------------------------------------------------
+# Tighter than package.json engines (>=18 <25): the runtime needs node:sqlite
+# (Node 22.5+) AND that SQLite must have FTS5 compiled in. SpecShip's own
+# release bundle pins v24.16.0 for that reason; older Node builds either lack
+# node:sqlite entirely or ship SQLite without FTS5.
+NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]")
+NODE_MINOR=$(node -p "process.versions.node.split('.')[1]")
+if [ "$NODE_MAJOR" -lt 22 ] \
+  || { [ "$NODE_MAJOR" -eq 22 ] && [ "$NODE_MINOR" -lt 5 ]; } \
+  || [ "$NODE_MAJOR" -ge 25 ]; then
+  echo "[offline-install] error: Node $(node --version) is unsupported. Requires >=22.5 <25 (Node 24.x recommended)." >&2
+  exit 1
+fi
+
+# --- FTS5 capability probe ---------------------------------------------------
+# Fail fast with a clear remediation message instead of letting `specship init`
+# die with a cryptic "no such module: fts5" deep inside indexing. node:sqlite
+# is present from 22.5+, but FTS5 is only enabled in newer Node builds —
+# Node 22.x typically ships SQLite without it.
+PROBE=$(node -e "
+  try {
+    const { DatabaseSync } = require('node:sqlite');
+    const db = new DatabaseSync(':memory:');
+    db.exec('CREATE VIRTUAL TABLE t USING fts5(x)');
+    console.log('OK');
+  } catch (e) {
+    console.log('FAIL:' + e.message);
+  }
+" 2>/dev/null)
+case "$PROBE" in
+  OK) ;;
+  FAIL:*)
+    cat >&2 <<EOF
+[offline-install] error: SQLite probe failed: ${PROBE#FAIL:}
+
+SpecShip requires Node.js whose bundled SQLite has FTS5 enabled. Your Node
+($(node --version)) does not. Install Node 24.x and re-run:
+
+  nvm install 24 && nvm use 24
+  ./scripts/offline-install.sh
+
+(SpecShip's release bundle pins v24.16.0 as the known-good version.)
+EOF
+    exit 1
+    ;;
+  *)
+    echo "[offline-install] error: unable to probe node:sqlite. Need Node >=22.5 (24.x recommended)." >&2
+    exit 1
+    ;;
+esac
+
+echo "[offline-install] repo:    ${REPO}"
+echo "[offline-install] package: ${PKG}@${VERSION}"
+echo "[offline-install] node:    $(node --version)"
+echo "[offline-install] registry: $(npm config get registry)"
+
+# --- install deps (offline-friendly: respects whatever registry npm is on) ---
+if [ -f package-lock.json ]; then
+  echo "[offline-install] npm ci"
+  npm ci
+else
+  echo "[offline-install] npm install"
+  npm install
+fi
+
+# --- build -------------------------------------------------------------------
+echo "[offline-install] npm run build"
+npm run build
+
+# --- link as global specship ------------------------------------------------
+echo "[offline-install] npm link"
+npm link
+
+LINKED=$(command -v specship || echo "(not on PATH)")
+echo "[offline-install] specship -> ${LINKED}"
+
+# --- wire Claude Code (non-interactive) --------------------------------------
+# Invoke the just-built binary directly instead of relying on `specship` being
+# visible on PATH in this shell session — `npm link`'s shim may not be picked
+# up until the user opens a new shell.
+if [ "$SKIP_CLAUDE" -eq 0 ]; then
+  echo "[offline-install] wiring Claude Code"
+  node "$REPO/dist/bin/specship.js" install --target claude -y
+fi
+
+cat <<EOF
+
+✓ SpecShip ${VERSION} installed offline from source.
+  binary:    ${LINKED}
+  source:    ${REPO}
+
+Next:
+  specship --version
+  cd <your-project> && specship init && specship index
+
+To uninstall:
+  ./scripts/offline-install.sh --undo
+EOF