@letterstory/cli 0.1.0 → 0.2.0

package/lib/commands.mjs

@@ -1,325 +1,15 @@
-// Command handlers. Each takes a ctx { client, positionals, flags, io } and returns
-// a process exit code. Handlers do their own printing through io (so poll progress
-// streams live), and throw CliError for anything the user needs to fix.
-
-import { LetterstoryClient, CliError, resolveConfig, writeConfigFile, clearConfigFile, configPath } from "./client.mjs";
-
-// --- small helpers ----------------------------------------------------------
-
-// A flag with no value parses to `true`; coerce that back to undefined so a bare
-// `--name` reads as "missing", not the string "true".
-function flagStr(v) {
-	return typeof v === "string" ? v : undefined;
-}
-
-function flagNum(v) {
-	const s = flagStr(v);
-	if (s === undefined) return undefined;
-	const n = Number(s);
-	if (!Number.isFinite(n)) throw new CliError(`Expected a number, got "${s}"`);
-	return n;
-}
-
-function requireFlag(flags, name) {
-	const v = flagStr(flags[name]);
-	if (v === undefined) throw new CliError(`Missing required --${name}`);
-	return v;
-}
-
-function requirePositional(positionals, index, label) {
-	const v = positionals[index];
-	if (v === undefined) throw new CliError(`Missing required <${label}>`);
-	return v;
-}
-
-function printResult(io, flags, value, formatter) {
-	if (flags.json || !formatter) {
-		io.log(JSON.stringify(value, null, 2));
-	} else {
-		io.log(formatter(value));
-	}
-}
-
-function formatDeployment(d) {
-	const lines = [
-		`${d.name}  [${d.deployment_id}]`,
-		`  status:     ${d.status}${d.phase ? ` · ${d.phase}` : ""}`,
-		`  theme:      ${d.theme}`,
-		`  collection: ${d.collection_id ?? "(none)"}`,
-	];
-	if (d.url) lines.push(`  url:        ${d.url}`);
-	if (d.domain) lines.push(`  domain:     ${d.domain}`);
-	if (d.last_error) lines.push(`  error:      ${d.last_error}`);
-	return lines.join("\n");
-}
-
-// Poll get_deployment until the blog reaches a terminal state. Emits a line only
-// when status/phase changes so the output reads as progress, not a firehose.
-async function pollUntilTerminal(client, id, io) {
-	const maxPolls = io.maxPolls ?? 90;
-	const interval = io.pollIntervalMs ?? 4000;
-	let last = "";
-	for (let i = 0; i < maxPolls; i++) {
-		const d = await client.callTool("get_deployment", { deployment_id: id });
-		if (d.status === "live" || d.status === "error") return d;
-		const line = `${d.status}${d.phase ? ` · ${d.phase}` : ""}`;
-		if (line !== last) {
-			io.log(`  … ${line}`);
-			last = line;
-		}
-		await io.sleep(interval);
-	}
-	return {
-		status: "error",
-		last_error: `Timed out waiting for it to go live. Check: letterstory deploy get ${id}`,
-		url: null,
-	};
-}
-
-// --- auth / config ----------------------------------------------------------
-
-export async function cmdLogin(ctx) {
-	const { flags, io } = ctx;
-	const key = requireFlag(flags, "key");
-	const url = flagStr(flags.url);
-	if (!key.startsWith("lb_")) {
-		io.error("Warning: Letterstory API keys usually start with 'lb_'. Saving anyway.");
-	}
-	const saved = { key, ...(url ? { url } : {}) };
-	const path = writeConfigFile(saved);
-	io.log(`Saved credentials to ${path}`);
-
-	// Verify the key works (and report the tool count) without failing the save if
-	// the network is down — a saved-but-unverified key is still usable later.
-	try {
-		const resolved = resolveConfig({ url, key });
-		const client = new LetterstoryClient({ url: resolved.url, key: resolved.key });
-		const tools = await client.listTools();
-		io.log(`Authenticated to ${resolved.url} — ${tools.length} tools available.`);
-		return 0;
-	} catch (err) {
-		io.error(`Saved, but could not verify the key: ${err.message}`);
-		return 0;
-	}
-}
-
-export function cmdLogout(ctx) {
-	const path = clearConfigFile();
-	ctx.io.log(`Cleared credentials at ${path}`);
-	return 0;
-}
-
-export function cmdConfig(ctx) {
-	const { config, io, flags } = ctx;
-	const masked = config.key ? `${config.key.slice(0, 6)}…${config.key.slice(-4)}` : "(none)";
-	const value = {
-		url: config.url,
-		key: masked,
-		key_source: config.keySource,
-		config_file: configPath(),
-	};
-	if (flags.json) {
-		io.log(JSON.stringify(value, null, 2));
-	} else {
-		io.log(`url:         ${value.url}`);
-		io.log(`key:         ${value.key} (from ${value.key_source})`);
-		io.log(`config file: ${value.config_file}`);
-	}
-	return 0;
-}
-
-// --- discovery / generic passthrough ----------------------------------------
-
-export async function cmdTools(ctx) {
-	const { client, io, flags } = ctx;
-	const doc = await client.discover();
-	const tools = doc.tools ?? [];
-	if (flags.json) {
-		io.log(JSON.stringify(tools, null, 2));
-		return 0;
-	}
-	io.log(`${tools.length} tools available at ${client.url}:\n`);
-	for (const t of tools) io.log(`  ${t.name} — ${t.description ?? ""}`);
-	return 0;
-}
-
-// Escape hatch: call any tool by name. Args come from --args '<json>', or from
-// individual string flags (everything after the tool name). Keeps the whole
-// manifest reachable without a bespoke subcommand per tool.
-export async function cmdCall(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const name = requirePositional(positionals, 0, "tool");
-	let args = {};
-	if (flags.args !== undefined) {
-		try {
-			args = JSON.parse(flagStr(flags.args) ?? "");
-		} catch {
-			throw new CliError(`--args must be a JSON object, e.g. --args '{"name":"My Blog"}'`);
-		}
-	} else {
-		for (const [k, v] of Object.entries(flags)) {
-			if (k === "json" || k === "url" || k === "key") continue;
-			args[k] = v;
-		}
-	}
-	const result = await client.callTool(name, args);
-	io.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
-	return 0;
-}
-
-// --- deployments (phantom blogs) --------------------------------------------
-
-export async function cmdDeploy(ctx) {
-	const sub = ctx.positionals[0];
-	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
-	switch (sub) {
-		case "create":
-			return deployCreate(rest);
-		case "list":
-			return deployList(rest);
-		case "get":
-		case "status":
-			return deployGet(rest);
-		case "rebuild":
-			return deployRebuild(rest);
-		case "diagnostics":
-			return deployDiagnostics(rest);
-		case "delete":
-			return deployDelete(rest);
-		default:
-			throw new CliError(
-				`Unknown deploy subcommand: ${sub ?? "(none)"}. Try: create, list, get, rebuild, diagnostics, delete`
-			);
-	}
-}
-
-async function deployCreate(ctx) {
-	const { client, flags, io } = ctx;
-	const name = requireFlag(flags, "name");
-	const args = { name };
-	const description = flagStr(flags.description);
-	const theme = flagStr(flags.theme);
-	const collection = flagStr(flags.collection);
-	if (description !== undefined) args.description = description;
-	if (theme !== undefined) args.theme = theme;
-	if (collection !== undefined) args.collection_id = collection;
-
-	const created = await client.callTool("create_deployment", args);
-	io.log(`Created deployment ${created.deployment_id} (${created.status})`);
-
-	if (flags["no-wait"]) {
-		io.log(`Provisioning in the background. Poll with: letterstory deploy get ${created.deployment_id}`);
-		return 0;
-	}
-
-	const final = await pollUntilTerminal(client, created.deployment_id, io);
-	if (final.status === "live") {
-		io.log(`\n✓ Live at ${final.url}`);
-		return 0;
-	}
-	io.error(`\n✗ Deployment ${final.status}: ${final.last_error ?? "unknown error"}`);
-	return 1;
-}
-
-async function deployList(ctx) {
-	const { client, flags, io } = ctx;
-	const limit = flagNum(flags.limit);
-	const result = await client.callTool("list_deployments", limit !== undefined ? { limit } : {});
-	const items = result.items ?? [];
-	if (flags.json) {
-		io.log(JSON.stringify(result, null, 2));
-		return 0;
-	}
-	if (items.length === 0) {
-		io.log("No deployments yet. Create one with: letterstory deploy create --name <name>");
-		return 0;
-	}
-	for (const d of items) {
-		io.log(`${d.status.padEnd(13)} ${d.deployment_id}  ${d.name}${d.url ? `  ${d.url}` : ""}`);
-	}
-	return 0;
-}
-
-async function deployGet(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const id = requirePositional(positionals, 0, "deployment-id");
-	const d = await client.callTool("get_deployment", { deployment_id: id });
-	printResult(io, flags, d, formatDeployment);
-	return 0;
-}
-
-async function deployRebuild(ctx) {
-	const { client, positionals, io } = ctx;
-	const id = requirePositional(positionals, 0, "deployment-id");
-	await client.callTool("rebuild_deployment", { deployment_id: id });
-	io.log(`Rebuild started for ${id}. New published content will appear once the build finishes.`);
-	return 0;
-}
-
-async function deployDiagnostics(ctx) {
-	const { client, positionals, io } = ctx;
-	const id = requirePositional(positionals, 0, "deployment-id");
-	const diag = await client.callTool("get_deployment_diagnostics", { deployment_id: id });
-	io.log(JSON.stringify(diag, null, 2));
-	return 0;
-}
-
-async function deployDelete(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const id = requirePositional(positionals, 0, "deployment-id");
-	if (!flags.yes) {
-		io.error(`This tears down the blog's site and revokes its content key (the collection is kept).`);
-		io.error(`Re-run with --yes to confirm: letterstory deploy delete ${id} --yes`);
-		return 1;
-	}
-	await client.callTool("delete_deployment", { deployment_id: id });
-	io.log(`Deleted deployment ${id}.`);
-	return 0;
-}
-
-// --- custom domains ---------------------------------------------------------
-
-export async function cmdDomain(ctx) {
-	const sub = ctx.positionals[0];
-	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
-	switch (sub) {
-		case "check":
-			return domainCheck(rest);
-		case "buy":
-			return domainBuy(rest);
-		default:
-			throw new CliError(`Unknown domain subcommand: ${sub ?? "(none)"}. Try: check, buy`);
-	}
-}
-
-async function domainCheck(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const domain = requirePositional(positionals, 0, "domain");
-	const quote = await client.callTool("check_domain", { domain });
-	if (flags.json) {
-		io.log(JSON.stringify(quote, null, 2));
-		return 0;
-	}
-	io.log(`${domain}`);
-	io.log(`  available:   ${quote.available}`);
-	if (quote.price !== undefined) io.log(`  price:       $${quote.price}`);
-	io.log(`  purchasable: ${quote.purchasable}`);
-	return 0;
-}
-
-async function domainBuy(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const id = requirePositional(positionals, 0, "deployment-id");
-	const domain = requirePositional(positionals, 1, "domain");
-	if (!flags.yes) {
-		io.error(`Buying ${domain} SPENDS money (registered under Letterstory, auto-renewing yearly).`);
-		io.error(`Price it first with: letterstory domain check ${domain}`);
-		io.error(`Then confirm with:   letterstory domain buy ${id} ${domain} --yes`);
-		return 1;
-	}
-	const result = await client.callTool("buy_domain", { deployment_id: id, domain });
-	io.log(`Purchase started for ${domain}. Attach + DNS run in the background.`);
-	io.log(`Poll with: letterstory deploy get ${id}`);
-	if (flags.json) io.log(JSON.stringify(result, null, 2));
-	return 0;
-}
+// Command handlers, split into focused modules under ./commands/*.mjs as the surface
+// grew past a single-file's worth of clarity (auth, discovery, deploy/domain, posts,
+// collections, flows, connectors, strategy, insights). This file re-exports
+// everything so `cli.mjs` — and any test importing straight from "commands.mjs" —
+// keep a single, stable import path regardless of how the implementation is split.
+
+export * from "./commands/auth.mjs";
+export * from "./commands/discovery.mjs";
+export * from "./commands/deploy.mjs";
+export * from "./commands/posts.mjs";
+export * from "./commands/collections.mjs";
+export * from "./commands/flows.mjs";
+export * from "./commands/connectors.mjs";
+export * from "./commands/strategy.mjs";
+export * from "./commands/insights.mjs";

package/lib/oauth.mjs

@@ -0,0 +1,204 @@
+// Browser-based OAuth 2.1 login (RFC 8252 loopback redirect + PKCE) for the
+// Letterstory CLI. This talks to the app's own /api/oauth/* endpoints — see
+// src/lib/oauth/core.ts on the server side for the matching implementation.
+
+import { randomBytes, createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { CliError } from "./client.mjs";
+
+export const CLIENT_ID = "letterstory_cli";
+const CALLBACK_TIMEOUT_MS = 180_000;
+
+function generatePkce() {
+	const verifier = randomBytes(32).toString("base64url");
+	const challenge = createHash("sha256").update(verifier).digest("base64url");
+	return { verifier, challenge };
+}
+
+function openBrowser(url) {
+	let cmd, args;
+	if (process.platform === "darwin") {
+		cmd = "open";
+		args = [url];
+	} else if (process.platform === "win32") {
+		cmd = "cmd";
+		args = ["/c", "start", '""', url];
+	} else {
+		cmd = "xdg-open";
+		args = [url];
+	}
+	try {
+		const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+const CALLBACK_HTML_OK = `<!doctype html><html><head><title>Letterstory CLI</title></head>
+<body style="font-family: system-ui, sans-serif; max-width: 28rem; margin: 4rem auto; text-align: center;">
+<h2>You're signed in.</h2><p>You can close this tab and return to your terminal.</p>
+</body></html>`;
+
+const CALLBACK_HTML_ERROR = `<!doctype html><html><head><title>Letterstory CLI</title></head>
+<body style="font-family: system-ui, sans-serif; max-width: 28rem; margin: 4rem auto; text-align: center;">
+<h2>Sign-in failed.</h2><p>Return to your terminal for details.</p>
+</body></html>`;
+
+// RFC 8252 §7.3: bind to loopback only, let the OS pick an ephemeral port,
+// and use whatever the OS gave us as part of the registered-but-portless
+// redirect_uri sent to /authorize.
+function startLoopbackServer() {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		let settled = false;
+
+		const resultPromise = new Promise((resolveResult) => {
+			server.on("request", (req, res) => {
+				const url = new URL(req.url, "http://127.0.0.1");
+				if (url.pathname !== "/callback") {
+					res.writeHead(404).end();
+					return;
+				}
+				const code = url.searchParams.get("code");
+				const state = url.searchParams.get("state");
+				const error = url.searchParams.get("error");
+				const errorDescription = url.searchParams.get("error_description");
+				res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+				res.end(error ? CALLBACK_HTML_ERROR : CALLBACK_HTML_OK);
+				if (!settled) {
+					settled = true;
+					resolveResult(error ? { error, errorDescription } : { code, state });
+				}
+			});
+			server.on("error", (err) => {
+				if (!settled) {
+					settled = true;
+					reject(err);
+				}
+			});
+		});
+
+		server.listen(0, "127.0.0.1", () => {
+			const { port } = server.address();
+			resolve({
+				port,
+				redirectUri: `http://127.0.0.1:${port}/callback`,
+				waitForCallback: () => resultPromise,
+				close: () => new Promise((r) => server.close(r)),
+			});
+		});
+	});
+}
+
+async function withTimeout(promise, ms, message) {
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(new CliError(message)), ms);
+	});
+	try {
+		return await Promise.race([promise, timeout]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function tokenRequest(url, body, fetchImpl) {
+	const endpoint = `${url.replace(/\/+$/, "")}/api/oauth/token`;
+	let res;
+	try {
+		res = await fetchImpl(endpoint, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams(body).toString(),
+		});
+	} catch (err) {
+		throw new CliError(`Could not reach ${endpoint}: ${err.message}`);
+	}
+	const json = await res.json().catch(() => null);
+	if (!res.ok || !json?.access_token) {
+		const detail = json?.error_description || json?.error || `HTTP ${res.status}`;
+		throw new CliError(`Login failed: ${detail}`);
+	}
+	return json;
+}
+
+// Opens the system browser, runs a one-shot loopback server, and exchanges
+// the resulting code for a token pair. Scope is left to the server's
+// default (the CLI client's full registered scope, including offline_access)
+// so a plain `letterstory login` always comes back with a refresh token.
+export async function browserLogin({ url, io, fetchImpl = globalThis.fetch }) {
+	const { verifier, challenge } = generatePkce();
+	const state = randomBytes(16).toString("hex");
+	const server = await startLoopbackServer();
+
+	const authUrl = new URL(`${url.replace(/\/+$/, "")}/api/oauth/authorize`);
+	authUrl.searchParams.set("response_type", "code");
+	authUrl.searchParams.set("client_id", CLIENT_ID);
+	authUrl.searchParams.set("redirect_uri", server.redirectUri);
+	authUrl.searchParams.set("state", state);
+	authUrl.searchParams.set("code_challenge", challenge);
+	authUrl.searchParams.set("code_challenge_method", "S256");
+
+	io.log(`Opening your browser to sign in…`);
+	io.log(`If it doesn't open automatically, visit:\n  ${authUrl.toString()}\n`);
+	openBrowser(authUrl.toString());
+
+	try {
+		const result = await withTimeout(
+			server.waitForCallback(),
+			CALLBACK_TIMEOUT_MS,
+			"Timed out waiting for the browser sign-in. Please try again."
+		);
+		if (result.error) {
+			throw new CliError(`Sign-in was not completed: ${result.errorDescription || result.error}`);
+		}
+		if (result.state !== state) {
+			throw new CliError("Sign-in response failed a security check (state mismatch). Please try again.");
+		}
+		if (!result.code) {
+			throw new CliError("Sign-in did not return an authorization code. Please try again.");
+		}
+
+		const tokens = await tokenRequest(
+			url,
+			{
+				grant_type: "authorization_code",
+				client_id: CLIENT_ID,
+				code: result.code,
+				redirect_uri: server.redirectUri,
+				code_verifier: verifier,
+			},
+			fetchImpl
+		);
+		return tokens;
+	} finally {
+		await server.close();
+	}
+}
+
+export async function refreshAccessToken({ url, refreshToken, fetchImpl = globalThis.fetch }) {
+	return tokenRequest(
+		url,
+		{ grant_type: "refresh_token", client_id: CLIENT_ID, refresh_token: refreshToken },
+		fetchImpl
+	);
+}
+
+// Best-effort: RFC 7009 revocation always "succeeds" server-side, and a
+// network failure here shouldn't block a local logout.
+export async function revokeToken({ url, token, fetchImpl = globalThis.fetch }) {
+	const endpoint = `${url.replace(/\/+$/, "")}/api/oauth/revoke`;
+	try {
+		await fetchImpl(endpoint, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({ token, client_id: CLIENT_ID }).toString(),
+		});
+	} catch {
+		// ignore — logout still clears local state
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -23,7 +23,8 @@
 		"mcp"
 	],
 	"bin": {
-		"letterstory": "bin/letterstory.mjs"
+		"letterstory": "bin/letterstory.mjs",
+		"phantom": "bin/phantom.mjs"
 	},
 	"engines": {
 		"node": ">=20"