@letterstory/cli 0.2.1 → 0.2.2

package/README.md

@@ -9,13 +9,38 @@ manifest an agent sees, so it never drifts from the API.
 The CLI is plain ESM with **zero dependencies** and needs no build step (Node ≥ 20).
 
 ```bash
-# from a checkout of this repo
+npm install -g @letterstory/cli   # puts `letterstory` (and `phantom`) on your PATH
+# …or run it without installing:
+npx @letterstory/cli --help
+```
+
+Contributing to the CLI itself? Run it straight from a checkout instead:
+
+```bash
 cd cli
-npm link          # puts `letterstory` (and `phantom`) on your PATH
+npm link          # puts `letterstory` (and `phantom`) on your PATH, pointing at this checkout
 # …or run it directly without linking:
 node cli/bin/letterstory.mjs --help
 ```
 
+## Updating
+
+The CLI checks npm for a newer published version at most once every 24 hours (cached
+alongside your config, so most runs make no extra network call) and prints a one-line
+nudge on stderr when one's available:
+
+```
+Update available: 0.2.1 → 0.3.0. Run `npm install -g @letterstory/cli@latest` to upgrade.
+```
+
+To upgrade immediately:
+
+```bash
+npm install -g @letterstory/cli@latest
+```
+
+Set `LETTERSTORY_NO_UPDATE_CHECK=1` to disable the check entirely (e.g. in CI).
+
 ## `phantom` — the same CLI, Phantomstory-branded
 
 `phantom` is a ghost-branded entry point for demos and presentations — same binary, same
@@ -32,6 +57,22 @@ otherwise runs the exact same code path as `letterstory`.
 
 ## Authenticate
 
+Two ways in — pick whichever fits how you're running the CLI.
+
+**Sign in via your browser** (the default — best for interactive use on your own machine):
+
+```bash
+letterstory login
+# opens your browser to https://app.letterstory.com, or override with --url
+```
+
+This runs a browser-based OAuth 2.1 flow (PKCE, loopback redirect — RFC 8252) against your
+account. It comes back with a full-access session and a refresh token, so there's no API key
+to mint or scope up front. Tokens are saved to `~/.letterstory/config.json` (mode 600) and
+refresh automatically. Run `letterstory logout` to revoke the session and forget it.
+
+**Or use a static API key** (for CI/automation, or when you want scoped-down access):
+
 You need a Letterstory API key (starts with `ls_`; legacy `lb_` keys still work) with the `deployment:read` and
 `deployment:write` capabilities — mint one in the app under **Settings → API keys**.
 Add `deployment:domain` too if you plan to buy custom domains.
@@ -44,8 +85,9 @@ letterstory login --key ls_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 Credentials resolve from `--key`/`--url` flags, then `LETTERSTORY_API_KEY` /
 `LETTERSTORY_API_URL`, then `~/.letterstory/config.json` (written by `login`, mode 600).
 
-Run `letterstory whoami` (alias `status`) any time to confirm which key/url resolved and
-see your company profile.
+Run `letterstory whoami` (alias `status`) any time to confirm which key/url (or OAuth session)
+resolved and see your company profile. Run `letterstory config` to see the resolved url and
+credential source without making a network call.
 
 ## Spin up a blog
 

package/lib/cli.mjs

@@ -3,6 +3,7 @@
 // never throws for user-facing problems (those become a printed CliError + code 1).
 
 import { LetterstoryClient, CliError, resolveConfig, readConfigFile, writeConfigFile } from "./client.mjs";
+import { checkForUpdate } from "./update-check.mjs";
 import {
 	cmdLogin,
 	cmdLogout,
@@ -27,7 +28,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.2.1";
+export const VERSION = "0.2.2";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -244,6 +245,9 @@ export function defaultIo() {
 		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 		pollIntervalMs: envInt("LETTERSTORY_POLL_INTERVAL_MS", 4000),
 		maxPolls: envInt("LETTERSTORY_MAX_POLLS", 90),
+		// Only a *real* CLI invocation (never a test, which always builds its own io)
+		// gets the background update-version check — see the `finally` block in run().
+		updateCheck: true,
 	};
 }
 
@@ -298,5 +302,18 @@ export async function run(argv, io = defaultIo()) {
 			return 1;
 		}
 		throw err;
+	} finally {
+		// Fire-and-await (bounded by checkForUpdate's own short fetch timeout) so the
+		// nudge, if any, is printed before the bin's process.exit() — but a warm cache
+		// (the common case) resolves with no network call at all, so this is normally
+		// instant. --json output stays machine-clean; real errors above already returned.
+		if (io.updateCheck && !flags.json) {
+			try {
+				const notice = await checkForUpdate({ currentVersion: VERSION });
+				if (notice) io.error(notice);
+			} catch {
+				// Never let the update nudge itself become the reason a command fails.
+			}
+		}
 	}
 }

package/lib/update-check.mjs

@@ -0,0 +1,94 @@
+// Best-effort "a newer version is out" nudge. Checks the npm registry at most once
+// every 24h and caches the result next to the config file, so a warm cache never
+// touches the network and a cold/offline check never slows or breaks a command —
+// every failure mode (no network, slow DNS, registry down, unwritable home) is
+// swallowed and just means no nudge gets printed.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+const REGISTRY_URL = "https://registry.npmjs.org/@letterstory/cli/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 500;
+
+function cachePath() {
+	const home = process.env.LETTERSTORY_CONFIG_HOME || homedir();
+	return join(home, ".letterstory", "update-check.json");
+}
+
+function readCache() {
+	try {
+		if (!existsSync(cachePath())) return null;
+		return JSON.parse(readFileSync(cachePath(), "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+function writeCache(data) {
+	try {
+		const path = cachePath();
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, JSON.stringify(data));
+	} catch {
+		// Read-only home, no disk space, etc. — caching is an optimization, not a requirement.
+	}
+}
+
+// Plain dotted-numeric semver compare — this CLI's versions are always X.Y.Z, no
+// prerelease/build metadata to worry about.
+function isNewer(latest, current) {
+	const a = String(latest).split(".").map(Number);
+	const b = String(current).split(".").map(Number);
+	for (let i = 0; i < Math.max(a.length, b.length); i++) {
+		const x = a[i] || 0;
+		const y = b[i] || 0;
+		if (x !== y) return x > y;
+	}
+	return false;
+}
+
+async function fetchLatestVersion(fetchImpl) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		const res = await fetchImpl(REGISTRY_URL, { signal: controller.signal });
+		if (!res.ok) return null;
+		const body = await res.json();
+		return typeof body.version === "string" ? body.version : null;
+	} catch {
+		return null; // offline, timed out, registry down, malformed response — no nudge, not an error
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Returns a one-line nudge string if a newer version is published on npm, else null.
+ * Never throws. `fetchImpl`/`now` are injectable for tests; real callers use the
+ * defaults (global fetch, current time).
+ *
+ * @param {{ currentVersion: string, fetchImpl?: (url: string, init?: { signal?: AbortSignal }) => Promise<{ ok: boolean, json: () => Promise<any> }>, now?: number }} opts
+ * @returns {Promise<string | null>}
+ */
+export async function checkForUpdate({ currentVersion, fetchImpl = globalThis.fetch, now = Date.now() }) {
+	if (process.env.LETTERSTORY_NO_UPDATE_CHECK) return null;
+
+	const cache = readCache();
+	let latest = cache?.latestVersion;
+	const stale = !cache || typeof cache.checkedAt !== "number" || now - cache.checkedAt > CHECK_INTERVAL_MS;
+
+	if (stale) {
+		const fetched = await fetchLatestVersion(fetchImpl);
+		if (fetched) {
+			latest = fetched;
+			writeCache({ checkedAt: now, latestVersion: fetched });
+		} else if (!cache) {
+			return null; // first-ever check failed (e.g. offline) — nothing to compare against yet
+		}
+	}
+
+	if (!latest || !isNewer(latest, currentVersion)) return null;
+	return `Update available: ${currentVersion} → ${latest}. Run \`npm install -g @letterstory/cli@latest\` to upgrade. (Set LETTERSTORY_NO_UPDATE_CHECK=1 to silence this.)`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.2.1",
+	"version": "0.2.2",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",