@kinlab/kin 0.2.13

package/README.md

@@ -0,0 +1,50 @@
+# @kinlab/kin
+
+The canonical npm install surface for [Kin](https://github.com/firelock-ai/kin), the
+semantic system of record for software work.
+
+```sh
+npm install -g @kinlab/kin
+kin --version
+```
+
+or zero-install:
+
+```sh
+npx -y @kinlab/kin --version
+```
+
+## What it does
+
+`@kinlab/kin` ships two thin launchers, not a JavaScript reimplementation:
+
+- **`kin`** — provisions the managed native `kin` + `kin-daemon` release for your
+  platform on first run (downloaded from the matching GitHub release, verified against
+  its published SHA-256), installs it under `~/.kin/bin`, then passes every invocation
+  straight through to the real binary and mirrors its exit.
+- **`kin-mcp`** — compatibility entrypoint that starts Kin's MCP server
+  (`kin mcp start`). MCP is one included mode of Kin, not a separate product.
+
+The launcher and the shell installer (`scripts/install.sh`) share the same install
+contract (`$KIN_HOME`, default `~/.kin`): either lane satisfies the other, and neither
+silently downgrades an install the other made.
+
+## Environment
+
+| Variable | Effect |
+| --- | --- |
+| `KIN_HOME` | Root of the managed install (default `~/.kin`). |
+| `KIN_MANAGED_BIN` | Explicit path to a `kin` binary; disables provisioning entirely. |
+| `KIN_NO_PROVISION=1` | Never touch the network; fail loud if no binary is present. |
+| `KIN_LAUNCHER_ADOPT=1` | Allow re-provisioning over a version-skewed non-npm install. |
+
+## MCP setup
+
+Any MCP client can use the included server:
+
+```json
+{ "command": "npx", "args": ["-y", "@kinlab/kin", "mcp", "start"] }
+```
+
+`@kinlab/kin-mcp` remains published for existing configurations; new setups should use
+this package.

package/bin/kin-mcp.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Firelock, LLC
+
+// `kin-mcp` — compatibility launcher for Kin's MCP server.
+//
+// MCP is one included mode of Kin, not a separate product. This bin exists so
+// existing `@kinlab/kin-mcp` users keep a working `kin-mcp` entrypoint; it
+// provisions the managed release like the `kin` launcher and starts
+// `kin mcp start`, forwarding any extra argv. Progress and failures go to
+// stderr only — stdout belongs to the MCP stdio protocol.
+
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+import { packageVersion, targetKinVersion, notProvisionedMessage } from '../lib/resolve.mjs';
+import { ensureProvisioned } from '../lib/provision.mjs';
+
+const argv = process.argv.slice(2);
+
+if (argv.includes('--version') || argv.includes('-V')) {
+  process.stdout.write(
+    `@kinlab/kin ${packageVersion()} (kin-mcp compatibility launcher; provisions kin ${targetKinVersion()})\n`,
+  );
+  process.exit(0);
+}
+
+let binary = null;
+try {
+  binary = await ensureProvisioned();
+} catch (error) {
+  process.stderr.write(`kin-mcp: provisioning failed: ${error.message}\n`);
+}
+
+if (!binary) {
+  process.stderr.write(`${notProvisionedMessage('kin')}\n`);
+  process.exit(1);
+}
+
+const result = spawnSync(binary, ['mcp', 'start', ...argv], { stdio: 'inherit' });
+if (result.error) {
+  process.stderr.write(`kin-mcp: failed to launch managed binary: ${result.error.message}\n`);
+  process.exit(1);
+}
+if (result.signal) {
+  process.exit(128 + (os.constants.signals[result.signal] ?? 0));
+}
+process.exit(result.status ?? 0);

package/bin/kin.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Firelock, LLC
+
+// `kin` — canonical launcher/passthrough for the Kin CLI.
+//
+// Provisions the managed native `kin` (+ `kin-daemon`) release on first run,
+// then forwards argv straight to it and mirrors its exit. `--version` therefore
+// proves provisioning end-to-end: it answers with the real binary's version.
+// When provisioning is unavailable (offline, disabled), it fails loud with an
+// actionable message — it never pretends to run.
+
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+import { packageVersion, targetKinVersion, notProvisionedMessage } from '../lib/resolve.mjs';
+import { ensureProvisioned } from '../lib/provision.mjs';
+
+const argv = process.argv.slice(2);
+const wantsVersion = argv.includes('--version') || argv.includes('-V');
+
+function launcherVersionLine(note) {
+  return `@kinlab/kin ${packageVersion()} (launcher; provisions kin ${targetKinVersion()}${note})\n`;
+}
+
+let binary = null;
+let provisionError = null;
+try {
+  binary = await ensureProvisioned();
+} catch (error) {
+  provisionError = error;
+}
+
+if (!binary) {
+  if (provisionError) {
+    process.stderr.write(`kin: provisioning failed: ${provisionError.message}\n`);
+  }
+  if (wantsVersion) {
+    // Honest launcher identity; success only when provisioning was explicitly
+    // disabled rather than broken.
+    process.stdout.write(launcherVersionLine(provisionError ? ', provisioning failed' : ', not installed'));
+    process.exit(provisionError ? 1 : 0);
+  }
+  process.stderr.write(`${notProvisionedMessage('kin')}\n`);
+  process.exit(1);
+}
+
+const result = spawnSync(binary, argv, { stdio: 'inherit' });
+if (result.error) {
+  process.stderr.write(`kin: failed to launch managed binary: ${result.error.message}\n`);
+  process.exit(1);
+}
+if (result.signal) {
+  // Mirror signal deaths honestly instead of reporting success.
+  process.exit(128 + (os.constants.signals[result.signal] ?? 0));
+}
+process.exit(result.status ?? 0);

package/lib/provision.mjs

@@ -0,0 +1,257 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Firelock, LLC
+
+// Binary provisioning for the @kinlab/kin launcher.
+//
+// Downloads the platform archive of the pinned Kin release from GitHub
+// Releases, verifies it against the per-artifact SHA-256 published next to it,
+// and installs the binaries into <kinHome>/bin — the same directory and the
+// same refusal semantics as scripts/install.sh, so the two install lanes are
+// interchangeable. kin-daemon is mandatory (status/search/MCP require it): a
+// daemon-less archive aborts before anything is moved rather than leaving a
+// half-installed environment. Network, spawning, and the environment are all
+// injectable so every decision here is unit testable offline.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import {
+  binaryName,
+  kinHome,
+  managedBinaryPath,
+  readLauncherStamp,
+  resolveManagedBinary,
+  targetKinVersion,
+  writeLauncherStamp,
+} from './resolve.mjs';
+
+/**
+ * Release-artifact file name for a host. Follows the release workflow's
+ * naming (kin-{macos|linux|windows}-{x86_64|aarch64}); Windows ships as .zip.
+ * There is no native windows-aarch64 artifact — fail honestly rather than
+ * fabricate a URL (Windows-on-ARM can run the x64 build under emulation).
+ */
+export function artifactName(platform = process.platform, arch = process.arch) {
+  const artifacts = {
+    'darwin:arm64': 'kin-macos-aarch64.tar.gz',
+    'darwin:x64': 'kin-macos-x86_64.tar.gz',
+    'linux:arm64': 'kin-linux-aarch64.tar.gz',
+    'linux:x64': 'kin-linux-x86_64.tar.gz',
+    'win32:x64': 'kin-windows-x86_64.zip',
+  };
+  const key = `${platform}:${arch}`;
+  const file = artifacts[key];
+  if (!file) {
+    const supported = Object.keys(artifacts).join(', ');
+    throw new Error(
+      key === 'win32:arm64'
+        ? 'no native windows-aarch64 Kin release artifact exists; use an x64 Node ' +
+          'under emulation (the x86_64 build runs on Windows-on-ARM), or build from source.'
+        : `no Kin release artifact for "${key}"; supported: ${supported}`,
+    );
+  }
+  return file;
+}
+
+/** Download URL of a file attached to the v<version> GitHub release. */
+export function releaseDownloadUrl(version, file) {
+  return `https://github.com/firelock-ai/kin/releases/download/v${version}/${file}`;
+}
+
+/**
+ * Extract the hex digest from a `shasum -a 256` style checksum file
+ * ("<hex>  <name>"). Refuses anything that does not look like SHA-256.
+ */
+export function parseSha256File(text) {
+  const token = String(text).trim().split(/\s+/)[0] ?? '';
+  if (!/^[0-9a-f]{64}$/i.test(token)) {
+    throw new Error(`malformed .sha256 file (expected a 64-hex digest, got "${token.slice(0, 80)}")`);
+  }
+  return token.toLowerCase();
+}
+
+/** SHA-256 hex digest of a buffer. */
+export function sha256Hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+async function fetchBuffer(url, fetchImpl) {
+  const res = await fetchImpl(url);
+  if (!res.ok) {
+    throw new Error(`download failed (${res.status}) for ${url}`);
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Locate the extraction root: release archives contain a kin-* subdirectory;
+ * tolerate a flat archive the way install.sh does.
+ */
+function extractionRoot(tmp) {
+  const sub = fs
+    .readdirSync(tmp, { withFileTypes: true })
+    .find((e) => e.isDirectory() && e.name.startsWith('kin-'));
+  return sub ? path.join(tmp, sub.name) : tmp;
+}
+
+/** Replace-then-move a binary into place (never overwrite in place: replacing
+ * a running executable's inode causes launch deadlocks on macOS). */
+function installFile(src, dest, mode) {
+  fs.rmSync(dest, { force: true });
+  fs.copyFileSync(src, dest);
+  fs.chmodSync(dest, mode);
+}
+
+/**
+ * Download, verify, and install the pinned Kin release. Returns the installed
+ * managed `kin` path. Mirrors scripts/install.sh: kin + kin-daemon are
+ * mandatory, kin-vfs and the projection shim library are optional extras.
+ */
+export async function provision(version, opts = {}) {
+  const {
+    env = process.env,
+    platform = process.platform,
+    arch = process.arch,
+    fetchImpl = fetch,
+    log = (line) => process.stderr.write(`${line}\n`),
+  } = opts;
+
+  const file = artifactName(platform, arch);
+  const url = releaseDownloadUrl(version, file);
+  log(`kin: provisioning managed kin ${version} (${file})...`);
+
+  const [archive, shaText] = await Promise.all([
+    fetchBuffer(url, fetchImpl),
+    fetchBuffer(`${url}.sha256`, fetchImpl),
+  ]);
+  const expected = parseSha256File(shaText.toString('utf8'));
+  const actual = sha256Hex(archive);
+  if (actual !== expected) {
+    throw new Error(
+      `SHA-256 mismatch for ${file}: expected ${expected}, got ${actual}. ` +
+        'The download may be corrupted or tampered with; refusing to install.',
+    );
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'kinlab-kin-'));
+  try {
+    const archivePath = path.join(tmp, file);
+    fs.writeFileSync(archivePath, archive);
+    // bsdtar reads both .tar.gz and .zip with -xf, on macOS, Linux, and
+    // Windows 10+ (tar.exe ships in System32).
+    const tar = spawnSync('tar', ['-xf', archivePath, '-C', tmp], { encoding: 'utf8' });
+    if (tar.status !== 0) {
+      throw new Error(`archive extraction failed: ${tar.stderr || tar.error?.message || 'tar exited non-zero'}`);
+    }
+
+    const root = extractionRoot(tmp);
+    const kinSrc = path.join(root, binaryName('kin', platform));
+    const daemonSrc = path.join(root, binaryName('kin-daemon', platform));
+    if (!fs.existsSync(kinSrc) || !fs.existsSync(daemonSrc)) {
+      throw new Error(
+        'kin-daemon (or kin) missing from the downloaded archive. kin status/search and ' +
+          'the MCP server require the daemon; refusing a daemon-less install.',
+      );
+    }
+
+    const binDir = path.join(kinHome(env), 'bin');
+    const libDir = path.join(kinHome(env), 'lib');
+    fs.mkdirSync(binDir, { recursive: true });
+
+    installFile(kinSrc, path.join(binDir, binaryName('kin', platform)), 0o755);
+    installFile(daemonSrc, path.join(binDir, binaryName('kin-daemon', platform)), 0o755);
+
+    const vfsSrc = path.join(root, binaryName('kin-vfs', platform));
+    if (fs.existsSync(vfsSrc)) {
+      installFile(vfsSrc, path.join(binDir, binaryName('kin-vfs', platform)), 0o755);
+    }
+    for (const lib of ['libkin_vfs_shim.so', 'libkin_vfs_shim.dylib']) {
+      const libSrc = path.join(root, lib);
+      if (fs.existsSync(libSrc)) {
+        fs.mkdirSync(libDir, { recursive: true });
+        installFile(libSrc, path.join(libDir, lib), 0o644);
+      }
+    }
+
+    writeLauncherStamp(version, env);
+    log(`kin: managed kin ${version} installed at ${binDir}`);
+    return path.join(binDir, binaryName('kin', platform));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** First line of `<binary> --version`, or null if it cannot be run. */
+export function probeBinaryVersion(binary, spawnImpl = spawnSync) {
+  const res = spawnImpl(binary, ['--version'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) return null;
+  const m = String(res.stdout).match(/^kin\s+(\S+)/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Ensure the managed `kin` binary matching this launcher's pinned release is
+ * present, provisioning (or re-provisioning) when needed. Returns the binary
+ * path, or null when nothing usable exists and provisioning is unavailable.
+ *
+ * Policy, in order:
+ *   - $KIN_MANAGED_BIN is an explicit user pin: use it as-is, never provision.
+ *   - $KIN_NO_PROVISION=1: resolve-only, no network.
+ *   - launcher stamp == target and the binary exists: run it (no probe cost).
+ *   - stamp differs or binary missing: provision the pinned release.
+ *   - no stamp but a binary exists (foreign install, e.g. install.sh): probe
+ *     its version; adopt on match. On mismatch respect the foreign install —
+ *     run it with a one-line notice — unless $KIN_LAUNCHER_ADOPT=1 opts into
+ *     re-provisioning. Never silently downgrade someone else's install.
+ */
+export async function ensureProvisioned(opts = {}) {
+  const {
+    env = process.env,
+    platform = process.platform,
+    arch = process.arch,
+    fetchImpl = fetch,
+    log = (line) => process.stderr.write(`${line}\n`),
+    spawnImpl = spawnSync,
+  } = opts;
+
+  const target = targetKinVersion();
+
+  if (env.KIN_MANAGED_BIN && env.KIN_MANAGED_BIN.trim()) {
+    return resolveManagedBinary('kin', env, platform);
+  }
+  const existing = resolveManagedBinary('kin', env, platform);
+  if (env.KIN_NO_PROVISION === '1') {
+    return existing;
+  }
+
+  const doProvision = () => provision(target, { env, platform, arch, fetchImpl, log });
+
+  if (!existing) {
+    return doProvision();
+  }
+
+  const stamp = readLauncherStamp(env);
+  if (stamp === target) {
+    return existing;
+  }
+  if (stamp !== null) {
+    return doProvision();
+  }
+
+  const probed = probeBinaryVersion(existing, spawnImpl);
+  if (probed === target) {
+    writeLauncherStamp(target, env);
+    return existing;
+  }
+  if (env.KIN_LAUNCHER_ADOPT === '1') {
+    return doProvision();
+  }
+  log(
+    `kin: using existing managed kin ${probed ?? 'unknown'} at ${managedBinaryPath('kin', env, platform)} ` +
+      `(this @kinlab/kin pins ${target}; set KIN_LAUNCHER_ADOPT=1 to re-provision).`,
+  );
+  return existing;
+}

package/lib/resolve.mjs

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Firelock, LLC
+
+// Managed-binary resolution for the @kinlab/kin launcher.
+//
+// This package is the canonical install surface for Kin: `npm i -g @kinlab/kin`
+// gives you the `kin` and `kin-mcp` bins. The bins are thin launchers over a
+// *managed* native binary (the real `kin` + `kin-daemon` release). This module
+// owns the pure, side-effect-free part of that story — computing the platform
+// target, where the managed binary is expected to live, and which release the
+// launcher pins — so it is unit testable without spawning or touching the
+// network. Downloading and installing live in ./provision.mjs.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** This package's own version, read from its package.json (single source). */
+export function packageVersion() {
+  const manifest = JSON.parse(fs.readFileSync(path.join(HERE, '..', 'package.json'), 'utf8'));
+  return manifest.version;
+}
+
+/**
+ * The Kin release this launcher provisions. It tracks the package version: the
+ * canonical package is versioned in lockstep with the `kin` + `kin-daemon`
+ * release it installs (the release workflow asserts package version == tag).
+ */
+export function targetKinVersion() {
+  return packageVersion();
+}
+
+/**
+ * Map a Node platform+arch pair to the Rust target triple of the managed
+ * binary. Pure and injectable so it is testable for every supported host.
+ */
+export function platformTarget(platform = process.platform, arch = process.arch) {
+  const targets = {
+    'darwin:arm64': 'aarch64-apple-darwin',
+    'darwin:x64': 'x86_64-apple-darwin',
+    'linux:arm64': 'aarch64-unknown-linux-gnu',
+    'linux:x64': 'x86_64-unknown-linux-gnu',
+    'win32:x64': 'x86_64-pc-windows-msvc',
+    'win32:arm64': 'aarch64-pc-windows-msvc',
+  };
+  const key = `${platform}:${arch}`;
+  const triple = targets[key];
+  if (!triple) {
+    throw new Error(
+      `unsupported platform "${key}" for @kinlab/kin; supported: ${Object.keys(targets).join(', ')}`,
+    );
+  }
+  return triple;
+}
+
+/** Executable file name for a bin on the host platform (adds .exe on Windows). */
+export function binaryName(name, platform = process.platform) {
+  return platform === 'win32' ? `${name}.exe` : name;
+}
+
+/** Root of Kin's managed install, honoring $KIN_HOME (default ~/.kin). */
+export function kinHome(env = process.env, home = os.homedir()) {
+  return env.KIN_HOME && env.KIN_HOME.trim() ? env.KIN_HOME : path.join(home, '.kin');
+}
+
+/**
+ * Absolute path where the managed `name` binary is expected. An explicit
+ * $KIN_MANAGED_BIN overrides the whole computation (an explicit user pin;
+ * provisioning never writes through it); otherwise it is
+ * <kinHome>/bin/<name>[.exe] — the same directory the shell installer
+ * (scripts/install.sh) populates, so either lane satisfies the other.
+ */
+export function managedBinaryPath(name = 'kin', env = process.env, platform = process.platform) {
+  if (env.KIN_MANAGED_BIN && env.KIN_MANAGED_BIN.trim()) {
+    return env.KIN_MANAGED_BIN;
+  }
+  return path.join(kinHome(env), 'bin', binaryName(name, platform));
+}
+
+/**
+ * Resolve the managed `name` binary to an absolute path if it exists on disk,
+ * else null. Never fabricates a path that is not really present.
+ */
+export function resolveManagedBinary(name = 'kin', env = process.env, platform = process.platform) {
+  const candidate = managedBinaryPath(name, env, platform);
+  try {
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Path of the launcher's version stamp: which Kin release this launcher last
+ * provisioned into <kinHome>/bin. Lets the normal launch path skip a
+ * `kin --version` probe; a binary installed by other means (install.sh) has no
+ * stamp and is probed instead of being silently trusted or clobbered.
+ */
+export function launcherStampPath(env = process.env) {
+  return path.join(kinHome(env), 'bin', '.kinlab-kin-version');
+}
+
+/** The stamped provisioned version, or null when absent/unreadable. */
+export function readLauncherStamp(env = process.env) {
+  try {
+    const text = fs.readFileSync(launcherStampPath(env), 'utf8').trim();
+    return text.length ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Record `version` as the provisioned release (directory must exist). */
+export function writeLauncherStamp(version, env = process.env) {
+  fs.writeFileSync(launcherStampPath(env), `${version}\n`);
+}
+
+/** Human-readable, honest explanation for when the managed binary is absent. */
+export function notProvisionedMessage(name = 'kin', env = process.env, platform = process.platform) {
+  const expected = managedBinaryPath(name, env, platform);
+  const triple = (() => {
+    try {
+      return platformTarget();
+    } catch {
+      return 'unknown-target';
+    }
+  })();
+  return [
+    `kin: managed "${name}" binary not found (expected at ${expected}).`,
+    `Host target: ${triple}. @kinlab/kin ${packageVersion()} provisions the managed Kin`,
+    'release on first run; if you are seeing this, provisioning failed or was disabled',
+    '(KIN_NO_PROVISION=1). Re-run with network access, set KIN_MANAGED_BIN to an existing',
+    'kin binary, or install via https://github.com/firelock-ai/kin (scripts/install.sh).',
+  ].join('\n');
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@kinlab/kin",
+  "version": "0.2.13",
+  "description": "Canonical installer and launcher for Kin — provisions and runs the managed kin + kin-daemon release. MCP is one included mode (kin mcp start).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "kin": "bin/kin.mjs",
+    "kin-mcp": "bin/kin-mcp.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/firelock-ai/kin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firelock-ai/kin.git",
+    "directory": "packages/kin"
+  },
+  "bugs": {
+    "url": "https://github.com/firelock-ai/kin/issues"
+  },
+  "keywords": [
+    "kin",
+    "kinlab",
+    "cli",
+    "mcp",
+    "semantic"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "node --check ./bin/kin.mjs && node --check ./bin/kin-mcp.mjs && node --check ./lib/resolve.mjs && node --check ./lib/provision.mjs",
+    "smoke": "node bin/kin.mjs --version"
+  }
+}