@kinlab/kin 0.2.13 → 0.2.14

package/README.md

@@ -6,12 +6,14 @@ semantic system of record for software work.
 ```sh
 npm install -g @kinlab/kin
 kin --version
+kin setup --intent agent
 ```
 
 or zero-install:
 
 ```sh
 npx -y @kinlab/kin --version
+npx -y @kinlab/kin setup --intent agent --no-interactive
 ```
 
 ## What it does
@@ -29,6 +31,26 @@ The launcher and the shell installer (`scripts/install.sh`) share the same insta
 contract (`$KIN_HOME`, default `~/.kin`): either lane satisfies the other, and neither
 silently downgrades an install the other made.
 
+Run `kin setup --intent agent` after provisioning. Setup writes the Kin MCP server into
+detected AI clients with the `agent-default` tool profile, adds the managed bin directory
+to your shell profile, installs the shell/session hook, and records the install ledger used
+by `kin setup status`, `kin doctor --fix`, and `kin setup uninstall`.
+
+## Version pinning
+
+Every `@kinlab/kin` release pins one managed `kin` release — its own package version.
+Each run compares that pin against whatever is already installed at `$KIN_HOME`:
+
+- **installed is older than the pin** — upgrades it automatically (a one-line notice
+  on stderr, no prompt, no opt-in required).
+- **installed is newer than the pin** — refuses the downgrade and exits with an
+  actionable error instead of running anything; re-run with `KIN_LAUNCHER_ADOPT=1` to
+  force it on purpose (e.g. deliberately pinning to an older release).
+- **installed matches the pin** — runs it as-is.
+
+`KIN_LAUNCHER_ADOPT=1` always forces a fresh provision of the pinned release, even when
+the installed version already matches.
+
 ## Environment
 
 | Variable | Effect |
@@ -36,14 +58,21 @@ silently downgrades an install the other made.
 | `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. |
+| `KIN_LAUNCHER_ADOPT=1` | Force re-provisioning to the pinned release, including over a newer install that would otherwise be refused as a downgrade. |
 
 ## MCP setup
 
-Any MCP client can use the included server:
+`kin setup --intent agent` is the preferred MCP setup path. It writes an absolute path to
+the managed native `kin` binary, so agents do not depend on inheriting your shell `PATH`.
+
+Any MCP client can also use the included server manually:
 
 ```json
-{ "command": "npx", "args": ["-y", "@kinlab/kin", "mcp", "start"] }
+{
+  "command": "npx",
+  "args": ["-y", "@kinlab/kin", "mcp", "start"],
+  "env": { "KIN_MCP_TOOL_PROFILE": "agent-default" }
+}
 ```
 
 `@kinlab/kin-mcp` remains published for existing configurations; new setups should use

package/bin/kin-mcp.mjs

@@ -26,14 +26,22 @@ if (argv.includes('--version') || argv.includes('-V')) {
 }
 
 let binary = null;
+let provisionError = null;
 try {
   binary = await ensureProvisioned();
 } catch (error) {
-  process.stderr.write(`kin-mcp: provisioning failed: ${error.message}\n`);
+  provisionError = error;
 }
 
 if (!binary) {
-  process.stderr.write(`${notProvisionedMessage('kin')}\n`);
+  // The error message is already complete and actionable (e.g. a declined
+  // downgrade names the binary that IS present) — printing the generic
+  // not-provisioned message on top of it would contradict it.
+  if (provisionError) {
+    process.stderr.write(`kin-mcp: provisioning failed: ${provisionError.message}\n`);
+  } else {
+    process.stderr.write(`${notProvisionedMessage('kin')}\n`);
+  }
   process.exit(1);
 }
 

package/bin/kin.mjs

@@ -33,13 +33,20 @@ try {
 
 if (!binary) {
   if (provisionError) {
+    // The error message is already complete and actionable (e.g. a declined
+    // downgrade names the binary that IS present) — printing the generic
+    // not-provisioned message on top of it would contradict it.
     process.stderr.write(`kin: provisioning failed: ${provisionError.message}\n`);
+    if (wantsVersion) {
+      process.stdout.write(launcherVersionLine(', provisioning failed'));
+    }
+    process.exit(1);
   }
   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.stdout.write(launcherVersionLine(', not installed'));
+    process.exit(0);
   }
   process.stderr.write(`${notProvisionedMessage('kin')}\n`);
   process.exit(1);

package/lib/provision.mjs

@@ -20,6 +20,7 @@ import { spawnSync } from 'node:child_process';
 
 import {
   binaryName,
+  compareVersions,
   kinHome,
   managedBinaryPath,
   readLauncherStamp,
@@ -196,16 +197,26 @@ export function probeBinaryVersion(binary, spawnImpl = spawnSync) {
  * 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.
+ * Throws when an installed release outranks the pin and the caller has not
+ * opted into a downgrade — this function never returns a value while quietly
+ * declining to honor the pin.
  *
  * 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.
+ *   - $KIN_LAUNCHER_ADOPT=1: always (re-)provision the pinned release,
+ *     regardless of what is already installed.
+ *   - nothing installed yet: provision the pinned release.
+ *   - installed version is known — from the launcher stamp when this package
+ *     provisioned it (no probe needed), otherwise by probing a foreign
+ *     install's `--version` once:
+ *       - installed == pinned: reuse it (a foreign match adopts the stamp).
+ *       - installed < pinned: the pin is an upgrade — provision it
+ *         automatically with a one-line notice. Never a silent no-op.
+ *       - installed > pinned: the pin would downgrade a newer install — fail
+ *         loud with an actionable message instead of running anything.
+ *   - installed version unparseable (foreign binary that will not report a
+ *     version): can't prove direction, so respect it — notice and reuse.
  */
 export async function ensureProvisioned(opts = {}) {
   const {
@@ -229,29 +240,37 @@ export async function ensureProvisioned(opts = {}) {
 
   const doProvision = () => provision(target, { env, platform, arch, fetchImpl, log });
 
+  if (env.KIN_LAUNCHER_ADOPT === '1') {
+    return doProvision();
+  }
   if (!existing) {
     return doProvision();
   }
 
+  const installedPath = managedBinaryPath('kin', env, platform);
   const stamp = readLauncherStamp(env);
-  if (stamp === target) {
+  const installed = stamp ?? probeBinaryVersion(existing, spawnImpl);
+
+  if (installed === null) {
+    log(
+      `kin: using existing managed kin (version unknown) at ${installedPath} ` +
+        `(this @kinlab/kin pins ${target}; set KIN_LAUNCHER_ADOPT=1 to re-provision).`,
+    );
     return existing;
   }
-  if (stamp !== null) {
-    return doProvision();
-  }
 
-  const probed = probeBinaryVersion(existing, spawnImpl);
-  if (probed === target) {
-    writeLauncherStamp(target, env);
+  const cmp = compareVersions(target, installed);
+  if (cmp === 0) {
+    if (stamp === null) writeLauncherStamp(target, env);
     return existing;
   }
-  if (env.KIN_LAUNCHER_ADOPT === '1') {
+  if (cmp > 0) {
+    log(`kin: managed kin ${installed} is older than the pinned ${target}; upgrading automatically.`);
     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).`,
+  throw new Error(
+    `refusing to downgrade managed kin ${installed} to the pinned ${target} (at ${installedPath}). ` +
+      'This @kinlab/kin would replace a newer managed install with an older one; nothing was run. ' +
+      'Set KIN_LAUNCHER_ADOPT=1 to force it if the downgrade is intended.',
   );
-  return existing;
 }

package/lib/resolve.mjs

@@ -33,6 +33,73 @@ export function targetKinVersion() {
   return packageVersion();
 }
 
+/**
+ * Compare two dotted version strings by semver precedence: numeric release
+ * segments first, then any `-prerelease` suffix (a release outranks its own
+ * prerelease; prerelease identifiers compare numerically when both sides are
+ * numeric, else lexically; on an equal shared prefix, fewer identifiers ranks
+ * lower). Mirrors the precedence `kin update` applies on the native side
+ * (crates/kin-cli/src/commands/update.rs). Returns -1 when `a` is older than
+ * `b`, 0 when equal, 1 when `a` is newer than `b`. Non-numeric release
+ * segments parse as 0 rather than throwing, so a malformed string degrades to
+ * a comparison instead of crashing the launcher.
+ */
+export function compareVersions(a, b) {
+  const [aCore, aPre] = splitVersion(a);
+  const [bCore, bPre] = splitVersion(b);
+  const core = compareNumericParts(aCore, bCore);
+  return core !== 0 ? core : comparePrereleaseParts(aPre, bPre);
+}
+
+function splitVersion(version) {
+  const trimmed = String(version).trim().replace(/^v/, '');
+  const dash = trimmed.indexOf('-');
+  const core = dash === -1 ? trimmed : trimmed.slice(0, dash);
+  const pre = dash === -1 ? null : trimmed.slice(dash + 1).split('.');
+  const nums = core.split('.').map((part) => {
+    const n = Number.parseInt(part, 10);
+    return Number.isFinite(n) ? n : 0;
+  });
+  return [nums, pre];
+}
+
+function compareNumericParts(a, b) {
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i += 1) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function comparePrereleaseParts(a, b) {
+  if (a === null && b === null) return 0;
+  if (a === null) return 1; // a released version outranks its own prerelease
+  if (b === null) return -1;
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i += 1) {
+    if (i >= a.length) return -1; // shared prefix equal, fewer identifiers ranks lower
+    if (i >= b.length) return 1;
+    const cmp = comparePrereleaseIdentifier(a[i], b[i]);
+    if (cmp !== 0) return cmp;
+  }
+  return 0;
+}
+
+function comparePrereleaseIdentifier(a, b) {
+  const aNumeric = /^\d+$/.test(a);
+  const bNumeric = /^\d+$/.test(b);
+  if (aNumeric && bNumeric) {
+    const x = Number.parseInt(a, 10);
+    const y = Number.parseInt(b, 10);
+    return x === y ? 0 : x < y ? -1 : 1;
+  }
+  if (aNumeric) return -1; // numeric identifiers rank below alphanumeric
+  if (bNumeric) return 1;
+  return a === b ? 0 : a < b ? -1 : 1;
+}
+
 /**
  * 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "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).",
+  "version": "0.2.14",
+  "description": "Canonical installer and launcher for Kin, the semantic system of record for software work — provisions and runs the managed kin + kin-daemon release. MCP is one included mode (kin mcp start).",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {