@lanes-sh/link 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A self-hostable MCP gateway for all your connections, memory, skills, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",

package/src/cli/commands/operate/inspect.ts

@@ -10,6 +10,7 @@ import {
   toPolicyDocument,
 } from '#registry';
 import { announce, emit, fail, ok, print, warn } from '../../output.ts';
+import { staleNudge } from '../../release.ts';
 import { capabilityDiff, discoveryProbe } from '../../runtime/discovery.ts';
 import { openRuntime, resolveProfile, type GlobalFlags } from '../../runtime.ts';
 
@@ -189,6 +190,12 @@ export async function doctor(flags: DoctorFlags): Promise<void> {
       });
     }
 
+    // Every finding above is about this profile; this one is about the binary
+    // reading it. Silent when the registry cannot be reached — `doctor` is
+    // expected to work on a plane, and "could not check" is not a finding.
+    const stale = await staleNudge();
+    if (stale !== null) warnings.push({ kind: 'stale_release', message: stale });
+
     await reportCapabilityDrift(runtime, (message) =>
       warnings.push({ kind: 'capability_drift', message }),
     );

package/src/cli/commands/operate/serve.ts

@@ -1,6 +1,7 @@
 import { startEndpoint } from '#server/endpoint.ts';
 import { streamLogger } from '#server/logging.ts';
 import { announce, ok, print, style, warn } from '../../output.ts';
+import { staleNudge } from '../../release.ts';
 import { resolveProfile, type GlobalFlags } from '../../runtime.ts';
 
 /** `lanes link start` — reconcile, then serve every profile on one endpoint. */
@@ -41,6 +42,12 @@ export async function start(
 
   print(ok(`serving ${style.bold(endpoint.url)}`));
   print(style.dim(`      profiles: ${endpoint.profiles.join(', ')}`));
+
+  // Last, not first: the endpoint is what someone ran this for, and a version
+  // note in front of it would be the first thing they read and the least useful.
+  const stale = await staleNudge();
+  if (stale !== null) print(warn(stale));
+
   print(style.dim('Ctrl-C to stop.'));
 
   const shutdown = async (): Promise<void> => {

package/src/cli/commands/update.ts

@@ -0,0 +1,255 @@
+import { homedir } from 'node:os';
+import { join, sep } from 'node:path';
+import { installRoot } from '#profile';
+import { emit, fail, ok, print, printErr, progress, style, warn } from '../output.ts';
+import { PACKAGE, release, type ReleaseState } from '../release.ts';
+import { version } from '../version.ts';
+
+/**
+ * `lanes link update` — install the newer release, or say why it will not.
+ *
+ * There is no build step and no compiled artifact, so updating means exactly
+ * one thing: replace the installed package directory with a newer tarball from
+ * the registry. `bin/lanes` resolves its own symlink chain and execs Bun on the
+ * `src/` inside that directory, so the shipped source *is* the running code and
+ * the symlink on the PATH never has to move.
+ *
+ * Bun is the only installer this drives. `bun install -g @lanes-sh/link` is the
+ * only install documented, `engines.bun` requires it, and the shim refuses to
+ * run without it — so inferring a package manager would be machinery serving a
+ * case nobody is told to create. The case that does exist is handled below
+ * rather than ignored: an `npm i -g` install updated with Bun gets a second
+ * copy somewhere else on the PATH, which this detects and reports instead of
+ * doing quietly.
+ *
+ * Nothing here is control plane — it touches the install, not a profile — so it
+ * resolves no profile and no target, and is the second command after `version`
+ * that prints no `announce` line.
+ */
+
+export interface UpdateFlags {
+  /** Report and exit without installing anything. */
+  readonly check?: boolean | undefined;
+  readonly json?: boolean | undefined;
+}
+
+/**
+ * What `update` would do, and why.
+ *
+ * `'checkout'` is a refusal: `bun link` puts a checkout on the same PATH entry
+ * a published install would occupy, so installing from the registry there would
+ * leave two copies of this CLI and no indication of which one answers. `git
+ * pull` is the update in a checkout, and saying so is more useful than doing
+ * something surprising.
+ */
+export type UpdateAction = 'install' | 'current' | 'ahead' | 'checkout' | 'unknown';
+
+export interface UpdateDecision {
+  readonly action: UpdateAction;
+  /** The argv to run, or `null` when nothing should be run. */
+  readonly install: readonly string[] | null;
+  readonly message: string;
+  /** Something true and unwelcome about this install, if there is anything. */
+  readonly warning: string | null;
+}
+
+export interface UpdateInput {
+  readonly installed: string;
+  readonly latest: string | null;
+  readonly state: ReleaseState;
+  /** Where this CLI is installed — `installRoot()`, not the workspace. */
+  readonly root: string;
+  /** Where Bun keeps global installs, so a copy landing elsewhere is visible. */
+  readonly bunGlobal: string;
+}
+
+/**
+ * The whole decision, as a function of five strings.
+ *
+ * Split from the spawn because the alternative is a command whose only test is
+ * one that replaces the copy of this CLI on the machine running the suite. Every
+ * branch below is reachable from `update.test.ts` with no network and no
+ * subprocess — including the stale branch, which the checkout this is written in
+ * can never reach on its own, being by definition the newest thing there is.
+ */
+export function updatePlan(input: UpdateInput): UpdateDecision {
+  const { installed, latest, state, root, bunGlobal } = input;
+
+  // A published install lives under `node_modules`; a checkout does not. Cheaper
+  // and steadier than looking for `.git`, which a tarball could carry and a
+  // shallow export could lack.
+  const published = root.split(sep).includes('node_modules');
+
+  if (!published) {
+    return {
+      action: 'checkout',
+      install: null,
+      message: `${root} is a checkout, not an install — git pull is the update here`,
+      warning: null,
+    };
+  }
+
+  if (state === 'unknown') {
+    return {
+      action: 'unknown',
+      install: null,
+      message:
+        latest === null
+          ? `could not reach the registry — ${installed} is installed`
+          : `cannot compare ${installed} against ${latest}`,
+      warning: null,
+    };
+  }
+
+  if (state === 'ahead') {
+    return {
+      action: 'ahead',
+      install: null,
+      message: `${installed} is installed, ahead of the published ${latest ?? 'release'}`,
+      warning: null,
+    };
+  }
+
+  if (state === 'current') {
+    return { action: 'current', install: null, message: `${installed} is current`, warning: null };
+  }
+
+  // Installed by npm, updated by Bun: `bun install -g` writes into its own
+  // global prefix and leaves the npm copy where it is, so both are on the PATH
+  // and its order decides which one answers. Worth saying before, not after.
+  const elsewhere = !root.startsWith(bunGlobal + sep);
+
+  return {
+    action: 'install',
+    install: ['install', '-g', PACKAGE],
+    message: `${installed} installed, ${latest} available`,
+    warning: elsewhere
+      ? `this copy is at ${root}, which is not under ${bunGlobal} — ` +
+        'Bun will install a second copy there rather than replace this one, ' +
+        'and your PATH order decides which one answers'
+      : null,
+  };
+}
+
+/** Where Bun keeps global installs, honouring `BUN_INSTALL`. */
+export function bunGlobalRoot(env: Record<string, string | undefined> = process.env): string {
+  return join(env['BUN_INSTALL'] ?? join(homedir(), '.bun'), 'install', 'global');
+}
+
+export async function update(flags: UpdateFlags): Promise<void> {
+  const current = await release();
+  const root = installRoot(import.meta.dir);
+  const decision = updatePlan({
+    installed: current.installed,
+    latest: current.latest,
+    state: current.state,
+    root,
+    bunGlobal: bunGlobalRoot(),
+  });
+
+  // A gate wants a non-zero exit for the one state that needs action. An
+  // unreachable registry is not that state — failing a build because a network
+  // was down would make this the flakiest check in it.
+  if (flags.check === true && decision.action === 'install') process.exitCode = 1;
+
+  const report = {
+    installed: current.installed,
+    latest: current.latest,
+    state: current.state,
+    action: decision.action,
+    root,
+    ...(decision.install !== null ? { install: `bun ${decision.install.join(' ')}` } : {}),
+    ...(decision.warning !== null ? { warning: decision.warning } : {}),
+  };
+
+  if (flags.check === true || decision.action !== 'install') {
+    return emit(flags.json, report, () => {
+      if (decision.action === 'install') {
+        print(warn(decision.message));
+        if (decision.warning !== null) print(style.dim(`      ${decision.warning}`));
+        print(style.dim('      run: lanes link update'));
+        return;
+      }
+
+      // Green for the two states that need nothing. A refusal and an
+      // unreachable registry are neither wrong nor fine, and `ok` would claim
+      // the second of those.
+      if (decision.action === 'current' || decision.action === 'ahead') {
+        print(ok(decision.message));
+        return;
+      }
+
+      print(style.dim(decision.message));
+    });
+  }
+
+  // Stderr, both of them. What this command produces is the version change, and
+  // with `--json` that is a document — a line of prose in front of it corrupts
+  // it for whatever is parsing, which is the whole reason `emit` exists.
+  if (decision.warning !== null) progress(warn(decision.warning));
+  progress(style.dim(`bun ${decision.install!.join(' ')}`));
+
+  const installed = await runInstall(decision.install!, flags.json === true);
+  if (!installed) {
+    printErr(fail('the install did not complete — nothing was changed'));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Read the version back off disk rather than trusting the exit code. `version()`
+  // reads `package.json` from the install root at call time, so this is the one
+  // question worth asking after a successful install: did *this* copy change?
+  // Unchanged after a clean install is the second-copy case above, seen from the
+  // other side.
+  const landed = version();
+
+  return emit(
+    flags.json,
+    {
+      ...report,
+      // The action was `install`; this is what came of it. Inventing a third
+      // action value would describe an outcome as a decision.
+      result: landed === current.installed ? 'unchanged' : 'installed',
+      installed: landed,
+      previous: current.installed,
+    },
+    () => {
+      if (landed === current.installed) {
+        print(warn(`bun reported success, but ${root} is still ${landed}`));
+        print(style.dim('      the copy it installed is somewhere else on your PATH'));
+        print(style.dim('      check with: which -a lanes'));
+        return;
+      }
+
+      print(ok(`${current.installed} → ${style.bold(landed)}`));
+      print(style.dim('      a running endpoint serves the old code until it is restarted'));
+    },
+  );
+}
+
+/**
+ * Hand the install to Bun and let it own the terminal.
+ *
+ * `process.execPath` rather than `Bun.which('bun')`: this process is already
+ * running under the Bun that should do the installing, and a PATH lookup can
+ * find a different one — which would resolve the dependency set with a
+ * different resolver than the one that will run the result.
+ *
+ * Output is inherited rather than captured. Bun prints its own progress and its
+ * own errors, and paraphrasing a package manager's failure is how a report ends
+ * up less useful than the thing it replaced. Its stdout is dropped under
+ * `--json` for the same reason the lines above go to stderr: the document on
+ * stdout has to be the only thing on stdout. Its stderr is kept either way,
+ * because a failure is worth reading in both modes.
+ */
+async function runInstall(argv: readonly string[], json: boolean): Promise<boolean> {
+  try {
+    const child = Bun.spawn([process.execPath, ...argv], {
+      stdout: json ? 'ignore' : 'inherit',
+      stderr: 'inherit',
+    });
+    return (await child.exited) === 0;
+  } catch {
+    return false;
+  }
+}

package/src/cli/main.ts

@@ -38,6 +38,7 @@ import {
   vaultRemove,
   vaultSet,
 } from './commands/owner.ts';
+import { update } from './commands/update.ts';
 import { globalFlags, ownerFlags, parseArgv, text } from './argv.ts';
 import { PROGRAM, USAGE } from './usage.ts';
 import { version } from './version.ts';
@@ -335,6 +336,9 @@ export async function run(argv: readonly string[]): Promise<void> {
       print(version());
       return;
 
+    case 'update':
+      return update({ check: flags['check'] === true, json });
+
     default:
       throw new Error(`Unknown command "${first}". Run: ${PROGRAM} help`);
   }

package/src/cli/release.ts

@@ -0,0 +1,111 @@
+import { version } from './version.ts';
+
+/**
+ * Whether a newer release than this one has been published.
+ *
+ * `version.ts` answers which release is installed, which stopped being the
+ * whole question when this started shipping from npm: two machines can now sit
+ * a release apart with nothing on either to say so, and the only upgrade
+ * affordance in the tree was a `contract` mismatch telling someone to "Upgrade
+ * lanes-link" without naming a command.
+ *
+ * Every function here degrades to `null` or `'unknown'` rather than throwing. A
+ * version check is never the reason a command fails — `doctor`, `start`, and
+ * `deploy` each print one line from this and must all work on a plane.
+ */
+
+/** The npm package this CLI ships as, and the only thing `update` will install. */
+export const PACKAGE = '@lanes-sh/link';
+
+/**
+ * The dist-tags document, not the packument.
+ *
+ * `registry.npmjs.org/<name>` carries every version ever published with its
+ * full manifest — hundreds of kilobytes to answer a question whose answer is
+ * eighteen bytes. This endpoint returns `{"latest":"0.2.0"}` and nothing else.
+ */
+const DIST_TAGS = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE)}/dist-tags`;
+
+/**
+ * The same budget `endpointHealth` gives its probe.
+ *
+ * Long enough for a warm connection, short enough that a command which only
+ * mentions staleness in passing does not appear to hang on a captive-portal
+ * network that accepts the connection and then says nothing.
+ */
+const PROBE_TIMEOUT_MS = 700;
+
+export type ReleaseState = 'current' | 'stale' | 'ahead' | 'unknown';
+
+export interface Release {
+  readonly installed: string;
+  /** `null` when the registry could not be reached, or answered something else. */
+  readonly latest: string | null;
+  readonly state: ReleaseState;
+}
+
+/**
+ * How the installed version stands against the published one.
+ *
+ * `'ahead'` is not a mistake: a contributor running from a checkout is usually
+ * a version ahead of the registry, and telling them they are behind would be
+ * both wrong and the thing they see most often.
+ *
+ * Pure, and separate from the fetch, so every branch is testable without a
+ * network — which is the only way the stale path gets covered at all, given the
+ * checkout this is written in is by definition current.
+ */
+export function releaseState(installed: string, latest: string | null): ReleaseState {
+  if (latest === null) return 'unknown';
+
+  try {
+    const order = Bun.semver.order(installed, latest);
+    return order === 0 ? 'current' : order < 0 ? 'stale' : 'ahead';
+  } catch {
+    // `Bun.semver.order` throws on anything it cannot parse rather than
+    // ordering it arbitrarily. A registry that answers with something other
+    // than a version, or a hand-edited `package.json`, is an unknown state and
+    // not a reason to claim either answer.
+    return 'unknown';
+  }
+}
+
+/** What the registry calls `latest`, or `null` if it did not say. */
+export async function latestRelease(): Promise<string | null> {
+  try {
+    const response = await fetch(DIST_TAGS, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    if (!response.ok) return null;
+
+    const body = (await response.json()) as { latest?: unknown };
+    return typeof body.latest === 'string' ? body.latest : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The installed version, the published one, and how they stand. */
+export async function release(): Promise<Release> {
+  const installed = version();
+  const latest = await latestRelease();
+
+  return { installed, latest, state: releaseState(installed, latest) };
+}
+
+/**
+ * The one line `doctor`, `start`, and `deploy` print when this install is behind.
+ *
+ * One string in one place, because three commands saying it three ways is how
+ * two of them end up naming a command that has been renamed. `null` for every
+ * state but `'stale'`: nothing is worth saying about an install that is current,
+ * and an unreachable registry is not news.
+ */
+export function staleLine(current: Release): string | null {
+  if (current.state !== 'stale') return null;
+
+  return `${current.installed} is installed, ${current.latest} is out — run: lanes link update`;
+}
+
+/** `staleLine` over a fresh probe, for a caller that has no `Release` in hand. */
+export async function staleNudge(): Promise<string | null> {
+  return staleLine(await release());
+}

package/src/cli/usage.ts

@@ -90,6 +90,7 @@ ${style.bold('Inspection')}
   ${PROGRAM} audit verify           has anything in the log been altered or removed
   ${PROGRAM} config show
   ${PROGRAM} version                    which release this is — same as lanes --version
+  ${PROGRAM} update [--check] [--json]  install the newer release, or say what is available
 
 ${style.bold('Attachments')}
   ${PROGRAM} attach <file> --connection <provider>.<account>

package/src/deployments/deploy.ts

@@ -1,5 +1,6 @@
 import { ConfigError, resolveDeployTarget, type DeployConfig } from '#profile';
 import { announce, fail, heading, ok, print, style, warn } from '#cli/output.ts';
+import { staleNudge } from '#cli/release.ts';
 import { confirm, isInteractive } from '#cli/prompt.ts';
 import { openSecretStoreFor, resolveProfile, type GlobalFlags } from '#cli/runtime.ts';
 import { resolveTarget, vaultEnv } from './bootstrap.ts';
@@ -57,6 +58,12 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   // rejected on boot should be rejected here, not after a five-minute build.
   print(ok(`${resolution.profilePath} is valid`));
 
+  // The CLI planning this rollout, not the image it will build. An old one
+  // plans an old rollout, and a build is the most expensive place to find that
+  // out.
+  const stale = await staleNudge();
+  if (stale !== null) print(warn(stale));
+
   const declared = await resolveTarget({
     config,
     profilePath: resolution.profilePath,