@sequenceholdings/studio-cli 0.1.11 → 0.1.12

package/dist/bin.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 import { run } from './main.js';
+import { maybeNotifyUpdate } from './update-check.js';
 run()
-    .then((code) => process.exit(code))
     .catch((error) => {
     console.error(error instanceof Error ? error.message : error);
-    process.exit(1);
+    return 1;
+})
+    // The update notice runs after the command so it never delays real output,
+    // and it is best-effort (never throws, never changes the exit code).
+    .then(async (code) => {
+    await maybeNotifyUpdate();
+    process.exit(code);
 });

package/dist/main.js

@@ -30,6 +30,7 @@ const TOP_LEVEL_USAGE = `usage:
   seq-studio login                   authenticate in the browser
   seq-studio logout                  remove cached user tokens
   seq-studio doctor [-e <env>]       diagnose config, auth, and writer gate
+  seq-studio version                 print the installed version
   seq-studio help                    show this message
 
   Authenticate with: seq-studio login
@@ -92,6 +93,13 @@ export async function run(argv = process.argv.slice(2)) {
         case 'login':
         case 'logout':
             return runSessionCommand({ argument: sub, command: namespace });
+        case 'version':
+        case '--version':
+        case '-v': {
+            const { currentVersion } = await import('./update-check.js');
+            console.log(currentVersion());
+            return 0;
+        }
         case 'doctor':
             return doctorCommand(parseArgs([sub, ...rest].filter(Boolean)));
         default:

package/dist/update-check-refresh.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/update-check-refresh.js

@@ -0,0 +1,9 @@
+/**
+ * Detached background entry spawned by maybeNotifyUpdate() when the update
+ * cache is stale. Polls the npm registry once and persists the result so
+ * the *next* command can print the notice without any foreground network.
+ */
+import { refreshUpdateCache } from './update-check.js';
+refreshUpdateCache().catch(() => {
+    // Best-effort: nothing to report to — the parent process is long gone.
+});

package/dist/update-check.d.ts

@@ -0,0 +1,27 @@
+/** The version of this installed package (dist/../package.json). */
+export declare function currentVersion(): string;
+export declare function updateCheckCachePath(): string;
+/** Exclusive-create marker that makes "who spawns the refresh?" atomic. */
+export declare function updateCheckClaimPath(): string;
+/**
+ * True when `candidate` is a strictly newer semver than `current`.
+ * Prerelease suffixes are ignored — the published channel is plain
+ * major.minor.patch and this only drives a notice, not resolution.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/**
+ * Poll the registry and persist the result. Runs in the detached background
+ * process (see update-check-refresh.ts) — never on a command's exit path.
+ * Failed fetches still record `lastCheckedAt` (keeping any previously known
+ * version) so attempts are throttled to once per interval either way. The
+ * cache file is written *only* here, so a foreground path can never clobber
+ * a fresher result. Releases the spawn claim when done.
+ */
+export declare function refreshUpdateCache(): Promise<void>;
+/**
+ * Print a strong upgrade recommendation to stderr when the cached registry
+ * state says a newer version is published, and kick off a detached refresh
+ * when the cache is stale. Reads only local state — adds no network latency
+ * to the command. Never throws.
+ */
+export declare function maybeNotifyUpdate(): Promise<void>;

package/dist/update-check.js

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Update notice: tell interactive users when a newer version of the CLI is
+ * on npm, and strongly recommend upgrading.
+ *
+ * Zero foreground latency is the design constraint. The command path only
+ * ever *reads* the on-disk cache (~/.config/lattice/update-check.json) and
+ * prints; the registry poll runs in a detached background process spawned
+ * at most once per CHECK_INTERVAL_MS — including after failures, which
+ * record their attempt time so a downed registry doesn't retry on every
+ * command. An exclusive claim file elects a single refresher even across
+ * concurrent CLI invocations. The notice is therefore at most one
+ * invocation stale, which is the standard update-notifier trade-off.
+ *
+ * The notice goes to stderr and only when stderr is a TTY, so scripted /
+ * piped / CI invocations never see it. Opt out entirely with
+ * SEQ_STUDIO_NO_UPDATE_CHECK=1. Everything is best-effort: failures are
+ * silent and never affect the command's exit code.
+ */
+const PACKAGE_NAME = '@sequenceholdings/studio-cli';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+/** A claim older than this belongs to a refresher that died — take it over. */
+const CLAIM_TTL_MS = 10 * 60 * 1000;
+/** The version of this installed package (dist/../package.json). */
+export function currentVersion() {
+    const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    const version = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'version') : null;
+    return typeof version === 'string' ? version : '0.0.0';
+}
+export function updateCheckCachePath() {
+    return join(homedir(), '.config', 'lattice', 'update-check.json');
+}
+/** Exclusive-create marker that makes "who spawns the refresh?" atomic. */
+export function updateCheckClaimPath() {
+    return updateCheckCachePath() + '.claim';
+}
+/**
+ * True when `candidate` is a strictly newer semver than `current`.
+ * Prerelease suffixes are ignored — the published channel is plain
+ * major.minor.patch and this only drives a notice, not resolution.
+ */
+export function isNewerVersion(candidate, current) {
+    const parse = (v) => v
+        .replace(/^v/, '')
+        .split('-')[0]
+        .split('.')
+        .map((part) => Number.parseInt(part, 10) || 0);
+    const [a, b] = [parse(candidate), parse(current)];
+    for (let i = 0; i < 3; i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0;
+    }
+    return false;
+}
+async function readCache() {
+    try {
+        const parsed = JSON.parse(await readFile(updateCheckCachePath(), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const candidate = parsed;
+        if (typeof candidate.lastCheckedAt !== 'number')
+            return null;
+        if (typeof candidate.latestVersion !== 'string' && candidate.latestVersion !== null) {
+            return null;
+        }
+        return { lastCheckedAt: candidate.lastCheckedAt, latestVersion: candidate.latestVersion };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(cache) {
+    const path = updateCheckCachePath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(cache, null, 2) + '\n', 'utf8');
+}
+async function fetchLatestVersion() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, { signal: controller.signal });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Poll the registry and persist the result. Runs in the detached background
+ * process (see update-check-refresh.ts) — never on a command's exit path.
+ * Failed fetches still record `lastCheckedAt` (keeping any previously known
+ * version) so attempts are throttled to once per interval either way. The
+ * cache file is written *only* here, so a foreground path can never clobber
+ * a fresher result. Releases the spawn claim when done.
+ */
+export async function refreshUpdateCache() {
+    try {
+        const previous = await readCache();
+        const fetched = await fetchLatestVersion();
+        await writeCache({
+            lastCheckedAt: Date.now(),
+            latestVersion: fetched ?? previous?.latestVersion ?? null,
+        });
+    }
+    finally {
+        await rm(updateCheckClaimPath(), { force: true }).catch(() => { });
+    }
+}
+/**
+ * Atomically claim the right to spawn a refresh. The `wx` flag makes the
+ * create exclusive at the filesystem level, so concurrent CLI processes
+ * racing past a stale cache elect exactly one refresher. A claim whose
+ * mtime exceeds CLAIM_TTL_MS is from a refresher that died before releasing
+ * it — take it over so refreshes can't wedge forever.
+ */
+async function tryClaimRefresh() {
+    const path = updateCheckClaimPath();
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, String(process.pid), { flag: 'wx' });
+        return true;
+    }
+    catch {
+        try {
+            const { mtimeMs } = await stat(path);
+            if (Date.now() - mtimeMs < CLAIM_TTL_MS)
+                return false;
+            await rm(path, { force: true });
+            await writeFile(path, String(process.pid), { flag: 'wx' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** CI conventionally sets CI=true; some environments set CI=false to mean "not CI". */
+function isCiEnvironment() {
+    const value = process.env['CI']?.trim().toLowerCase();
+    return value !== undefined && value !== '' && value !== 'false' && value !== '0';
+}
+function spawnBackgroundRefresh() {
+    const script = join(dirname(fileURLToPath(import.meta.url)), 'update-check-refresh.js');
+    const child = spawn(process.execPath, [script], { detached: true, stdio: 'ignore' });
+    // Spawn failures surface as an async 'error' event; without a listener that
+    // becomes an unhandled event that could crash the CLI after its command
+    // already succeeded. The refresh is best-effort — swallow it.
+    child.on('error', () => { });
+    child.unref();
+}
+/**
+ * Print a strong upgrade recommendation to stderr when the cached registry
+ * state says a newer version is published, and kick off a detached refresh
+ * when the cache is stale. Reads only local state — adds no network latency
+ * to the command. Never throws.
+ */
+export async function maybeNotifyUpdate() {
+    try {
+        if (process.env['SEQ_STUDIO_NO_UPDATE_CHECK']?.trim())
+            return;
+        if (isCiEnvironment())
+            return;
+        if (!process.stderr.isTTY)
+            return;
+        const cache = await readCache();
+        if (!cache || Date.now() - cache.lastCheckedAt > CHECK_INTERVAL_MS) {
+            // Exactly one process refreshes: the exclusive claim file elects a
+            // single refresher even across concurrent CLI invocations, and the
+            // foreground never writes the cache itself (so it can't clobber a
+            // fresher background result).
+            if (await tryClaimRefresh())
+                spawnBackgroundRefresh();
+        }
+        const latest = cache?.latestVersion;
+        const current = currentVersion();
+        if (!latest || !isNewerVersion(latest, current))
+            return;
+        process.stderr.write('\n' +
+            `seq-studio ${current} is out of date — ${latest} is available.\n` +
+            'We highly recommend updating: fixes and environment changes land there first.\n' +
+            `  pnpm add -g ${PACKAGE_NAME}@latest   (or: npm install -g ${PACKAGE_NAME}@latest)\n`);
+    }
+    catch {
+        // Best-effort by design — an update notice must never break a command.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequenceholdings/studio-cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Unified Sequence Studio CLI — `seq-studio process` (Lattice), `seq-studio artifact` (Artifact Studio), `seq-studio functions` / `secrets`, `seq-studio repos` (platform git-service), and `seq-studio auth pat` (git-service PATs). Includes Auth0 browser login shared with seqapi.",
   "license": "UNLICENSED",
   "repository": {