@stetcms/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,12 @@
 # @stetcms/cli
 
-Stet from the command line, for scripting, seeding, and CI.
+[![CI](https://github.com/jamiedavenport/stet/actions/workflows/ci.yml/badge.svg)](https://github.com/jamiedavenport/stet/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-stetcms.com-black.svg)](https://docs.stetcms.com/reference/cli)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+
+[Stet](https://stetcms.com) from the command line, for scripting, seeding, and CI.
+
+Stet is the CMS where marketing owns the content model and engineering gets a typed client generated from it.
 
 ## Install
 
@@ -12,9 +18,31 @@ npx @stetcms/cli login
 
 ## Usage
 
+### `stet init`
+
+Write a `stet.config.ts` to start from, with the analytics block present but commented out. No network calls, so it works before you have a key.
+
+```bash
+npx stet init
+```
+
+| Flag              | Description                                                            |
+| ----------------- | ---------------------------------------------------------------------- |
+| `--config <path>` | Where to write the config. Defaults to `./stet.config.ts`.             |
+| `--output <path>` | Where the generated content client should go. Written into the config. |
+| `--force`         | Overwrite an existing config.                                          |
+
+`--output` defaults to `src/stet.gen.ts` when the project has a `src` directory and `stet.gen.ts` when it does not.
+
+Without `--force`, an existing config is never replaced. Detection looks in every place [`@stetcms/vite`](https://docs.stetcms.com/reference/codegen) and this CLI look, so writing to the default location cannot shadow the config your project already loads: with `--force` and no `--config`, it overwrites the file it found rather than adding one at the root. An explicit `--config` is honoured as given, and if that path is somewhere the resolver will not look, the command says so rather than leaving you a config nothing reads.
+
+The next steps it prints depend on the project. A project that builds with Vite is told to install the plugin and add `stet()` to `vite.config.ts`; anywhere else — Next.js, another bundler, a CI checkout — is told to install [`@stetcms/client`](https://docs.stetcms.com/reference/client) and run `stet generate`. The install line follows whichever package manager the project uses.
+
+The config carries no `apiKey`. Export `STET_API_KEY` instead, so the file stays safe to commit. `init` does not edit your `package.json`.
+
 ### `stet generate`
 
-Generate the typed content client from your organization's content model, exactly as [`@stetcms/vite`](https://github.com/jamiedavenport/stet/tree/main/published/vite) does at build time. Use it where there is no Vite: Next.js apps, other bundlers, or CI.
+Generate the typed content client from your organization's content model, exactly as [`@stetcms/vite`](https://docs.stetcms.com/reference/codegen) does at build time. Use it where there is no Vite: Next.js apps, other bundlers, or CI.
 
 ```bash
 STET_API_KEY=stet_... stet generate
@@ -27,14 +55,17 @@ stet generate --key stet_... --url https://stet.example.com --output lib/stet.ge
 | `--key <api-key>` | Organization API key. Defaults to `$STET_API_KEY`.                   |
 | `--output <path>` | Where the generated module goes. Defaults to `src/stet.gen.ts`.      |
 | `--config <path>` | Path to `stet.config.ts`. Auto-detected by default.                  |
+| `--if-key`        | Succeed without generating when no API key is set.                   |
+
+`--url`, `--key` and `--output` each override the matching key in `stet.config.ts`; `--config` chooses which file that is. Both this CLI and the Vite plugin read it (see [`@stetcms/config`](https://docs.stetcms.com/reference/configuration)).
 
-Every flag overrides the same key in `stet.config.ts`, which both this CLI and the Vite plugin read (see [`@stetcms/config`](https://github.com/jamiedavenport/stet/tree/main/published/config)).
+`--if-key` exists for build scripts, so `stet generate --if-key && next build` can run in environments that have no `STET_API_KEY`, such as a CI job building against a committed generated client. It is the same behaviour [`@stetcms/vite`](https://docs.stetcms.com/reference/codegen) has without a key: say so, keep the file on disk, and carry on. Only the missing key is forgiven; with a key set, an unreachable server or a rejected key still fails the command.
 
-The generated file imports [`@stetcms/client`](https://github.com/jamiedavenport/stet/tree/main/published/client), so add that to your app's dependencies. It never contains the key: at runtime the client reads `STET_API_KEY` from the environment again, so the file is safe to commit. It reads `STET_ORIGIN` at runtime too, falling back to the origin it was generated against.
+The generated file imports [`@stetcms/client`](https://docs.stetcms.com/reference/client), so add that to your app's dependencies. It never contains the key: at runtime the client reads `STET_API_KEY` from the environment again, so the file is safe to commit. It reads `STET_ORIGIN` at runtime too, falling back to the origin it was generated against.
 
 ### `stet sync`
 
-Publish your analytics tracking plan, so Stet can chart events your code declares before anyone has fired one. The same job [`@stetcms/vite`](https://github.com/jamiedavenport/stet/tree/main/published/vite) does on dev-server and build start; use this where there is no Vite, or in CI.
+Publish your analytics tracking plan, so Stet can chart events your code declares before anyone has fired one. The same job [`@stetcms/vite`](https://docs.stetcms.com/reference/codegen) does on dev-server and build start; use this where there is no Vite, or in CI.
 
 ```bash
 STET_API_KEY=stet_... stet sync
@@ -72,6 +103,14 @@ stet whoami --json
 
 `--json` prints the user, session, and active organization as JSON for scripting. The session token is never included in the output.
 
+### `stet logout`
+
+Clear the session stored on this machine. Running the command when already logged out also succeeds.
+
+```bash
+stet logout
+```
+
 ### `stet org`
 
 Show the organization an API key is scoped to, including its billing plan.
@@ -81,20 +120,33 @@ stet org --api-key stet_...   # or set STET_API_KEY
 stet org --json
 ```
 
+| Flag              | Description                                                           |
+| ----------------- | --------------------------------------------------------------------- |
+| `--api-key <key>` | Organization API key. Defaults to `$STET_API_KEY`.                    |
+| `--url <origin>`  | Stet server origin. Defaults to `$STET_API_URL`, then the hosted app. |
+| `--json`          | Print the organization as JSON.                                       |
+
 ## Configuration
 
-- `STET_API_URL`: default server origin for `stet login`.
-- The session token is stored at `~/.config/stet/auth.json` (`$XDG_CONFIG_HOME/stet/auth.json` when set) with `0600` permissions. Delete the file to log out.
+- `STET_API_URL`: default server origin for the account commands (`login`,
+  `whoami`, `org`). `generate` and `sync` resolve theirs through
+  `stet.config.ts` and `STET_ORIGIN` instead.
+- The session token is stored at `~/.config/stet/auth.json` (`$XDG_CONFIG_HOME/stet/auth.json` when set) with `0600` permissions. Run `stet logout` to remove it.
 
 ## Development
 
-This package lives in the [Stet](https://github.com/jamiedavenport/stet) monorepo under `published/cli` and is built with `vp pack` (Vite+). Releases are versioned with Changesets and published from CI.
+This package lives in the [Stet monorepo](https://github.com/jamiedavenport/stet) under `published/cli` and is built with `vp pack` (Vite+). Releases are versioned with Changesets and published from CI.
 
 ```bash
 vp install
-vp run build --filter @stetcms/cli
+vp run cli#build
 ```
 
+The `stet` bin is `bin/stet.mjs`, a committed launcher that defers to the
+bundled `dist/index.mjs`. It exists so pnpm can link the bin at install time
+inside the monorepo, where `dist` is gitignored and only exists after the
+build above; before that build it exits with a message saying to run it.
+
 ## License
 
 Apache-2.0

package/bin/stet.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// The CLI itself is bundled into dist/ by `vp pack` and ships in the npm
+// package. This launcher is committed because pnpm links a bin only when its
+// target exists at install time: in the monorepo dist/ is gitignored and
+// built after install, so pointing the bin straight at it would leave every
+// fresh checkout without a `stet` command.
+import { access } from 'node:fs/promises';
+
+const entry = new URL('../dist/index.mjs', import.meta.url);
+
+try {
+  await access(entry);
+} catch {
+  console.error('stet: the CLI is not built yet. Run `vp run cli#build` from the repository root.');
+  process.exit(1);
+}
+
+await import(entry.href);

package/dist/index.mjs

@@ -1,22 +1,23 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { mkdir, writeFile } from "node:fs/promises";
-import path, { dirname, resolve } from "node:path";
+import path, { dirname, relative, resolve } from "node:path";
 import { fetchContentModel, renderContentModule } from "@stetcms/client/codegen";
 import { resolveStetConfig } from "@stetcms/config";
 import { findStetConfig, loadStetConfig, trackingPlanEvents } from "@stetcms/vite/config";
 import { intro, log, note, outro, spinner } from "@clack/prompts";
 import pc from "picocolors";
+import fs, { existsSync, readFileSync } from "node:fs";
+import { resolveCommand } from "package-manager-detector/commands";
+import { detect } from "package-manager-detector/detect";
 import open from "open";
 import { createAuthClient } from "better-auth/client";
 import { deviceAuthorizationClient, organizationClient } from "better-auth/client/plugins";
-import fs from "node:fs";
 import { homedir } from "node:os";
 import Conf from "conf";
-import { createStetClient, safe } from "@stetcms/client";
 import { syncTrackingPlan } from "@stetcms/analytics/sync";
 //#region package.json
-var version = "0.1.0";
+var version = "0.2.0";
 //#endregion
 //#region src/config.ts
 /**
@@ -52,8 +53,16 @@ function fail(message) {
 	outro(pc.red("Something went wrong."));
 	process.exit(1);
 }
+/** A boxed, titled aside: several lines the reader is meant to act on. */
+function note$1(message, title) {
+	note(message, title);
+}
+/** Something worth knowing that is not a failure, so the command carries on. */
+function warn(message) {
+	log.warn(pc.yellow(message));
+}
 function showVerification(verificationUri, userCode) {
-	note([`${pc.dim("Visit")} ${verificationUri}`, `${pc.dim("Code")}  ${pc.bold(userCode)}`].join("\n"), "Confirm this device");
+	note$1([`${pc.dim("Visit")} ${verificationUri}`, `${pc.dim("Code")}  ${pc.bold(userCode)}`].join("\n"), "Confirm this device");
 }
 function progress() {
 	if (process.stdout.isTTY) {
@@ -74,10 +83,16 @@ function keyValueRows(rows) {
 }
 //#endregion
 //#region src/commands/generate.ts
-const generateCommand = new Command("generate").description("Generate the typed content client from your content model").option("--url <origin>", "Stet server origin (defaults to $STET_ORIGIN or the hosted app)").option("--key <api-key>", "Organization API key (defaults to $STET_API_KEY)").option("--output <path>", "Where the generated module goes").option("--config <path>", "Path to stet.config.ts (auto-detected by default)").action(async (options) => {
-	begin("stet generate");
+/** The command's whole body, extracted so tests can drive it without a process. */
+async function runGenerate(options) {
 	const { origin, apiKey, output } = await settleOptions(options);
-	if (apiKey === void 0) fail("No API key. Pass --key or set STET_API_KEY.");
+	if (apiKey === void 0 || apiKey === "") {
+		if (options.ifKey === true) {
+			done("No API key set; kept the generated client already on disk.");
+			return;
+		}
+		fail("No API key. Pass --key or set STET_API_KEY.");
+	}
 	const fetching = progress();
 	fetching.start(`Fetching the content model from ${origin}…`);
 	let code;
@@ -94,6 +109,137 @@ const generateCommand = new Command("generate").description("Generate the typed
 	await mkdir(dirname(target), { recursive: true });
 	await writeFile(target, code, "utf8");
 	done(`Generated ${output}`);
+}
+const generateCommand = new Command("generate").description("Generate the typed content client from your content model").option("--url <origin>", "Stet server origin (defaults to $STET_ORIGIN or the hosted app)").option("--key <api-key>", "Organization API key (defaults to $STET_API_KEY)").option("--output <path>", "Where the generated module goes").option("--config <path>", "Path to stet.config.ts (auto-detected by default)").option("--if-key", "Succeed without generating when no API key is set").action(async (options) => {
+	begin("stet generate");
+	await runGenerate(options);
+});
+//#endregion
+//#region src/commands/init.ts
+/**
+* The default `output`, which is where a developer would have put it anyway:
+* projects with a `src/` keep generated code inside it, and flatter ones do
+* not have the directory to write into.
+*/
+function defaultOutput(root) {
+	if (existsSync(resolve(root, "src"))) return "src/stet.gen.ts";
+	return "stet.gen.ts";
+}
+/**
+* Decides which file to write, and reports what the project already has.
+*
+* Detection runs through {@link findStetConfig}, the resolver `generate` and
+* `sync` settle their options against, so writing to the default location can
+* never shadow the config the project loads. An explicit `--config` is honoured
+* as given and can land somewhere that resolver will not look, which is why
+* `detected` is reported separately for the caller to warn about.
+*/
+function resolveTarget(root, options) {
+	const detected = findStetConfig(root);
+	if (options.config !== void 0) {
+		const path = resolve(root, options.config);
+		if (existsSync(path)) return {
+			path,
+			existing: path,
+			detected
+		};
+		return {
+			path,
+			existing: void 0,
+			detected
+		};
+	}
+	if (detected !== void 0) return {
+		path: detected,
+		existing: detected,
+		detected
+	};
+	return {
+		path: resolve(root, "stet.config.ts"),
+		existing: void 0,
+		detected
+	};
+}
+/** The `stet.config.ts` init writes. */
+function renderStetConfig(output) {
+	return `import { defineStet } from '@stetcms/config';
+// import { defineAnalytics, event } from '@stetcms/analytics';
+// import { z } from 'zod';
+
+export default defineStet({
+  output: '${output}',
+
+  // A typed tracking plan, published with \`stet sync\`.
+  // analytics: defineAnalytics({
+  //   events: { signup: event({ plan: z.enum(['free', 'paid']) }) },
+  // }),
+});
+`;
+}
+const VITE_CONFIGS = [
+	"vite.config.ts",
+	"vite.config.js",
+	"vite.config.mjs",
+	"vite.config.mts",
+	"vite.config.cjs"
+];
+/**
+* Whether the plugin is any use here. Next.js, Astro's own config, and a bare
+* CI checkout all run codegen through `stet generate` instead, so telling them
+* to install `@stetcms/vite` would be telling them to install nothing.
+*/
+function usesVite(root) {
+	if (VITE_CONFIGS.some((candidate) => existsSync(resolve(root, candidate)))) return true;
+	const manifest = resolve(root, "package.json");
+	if (!existsSync(manifest)) return false;
+	const { dependencies, devDependencies } = JSON.parse(readFileSync(manifest, "utf8"));
+	return "vite" in {
+		...dependencies,
+		...devDependencies
+	};
+}
+/**
+* The install line for whichever package manager the project uses, resolved by
+* `package-manager-detector`: it reads the `packageManager` field and walks up
+* to the workspace root, so a package inside a monorepo is told the truth.
+*/
+async function installCommand(root, packages) {
+	const resolved = resolveCommand((await detect({ cwd: root }))?.agent ?? "npm", "add", packages);
+	if (resolved === null) return `npm install ${packages.join(" ")}`;
+	return `${resolved.command} ${resolved.args.join(" ")}`;
+}
+/**
+* What to do once the config exists. `@stetcms/client` is what the generated
+* module imports and so is always needed; the plugin only earns its place in a
+* project that builds with Vite, and codegen without one is `stet generate`.
+*/
+async function nextSteps(root) {
+	const key = "export STET_API_KEY=\"...\"";
+	if (usesVite(root)) return [
+		key,
+		await installCommand(root, ["@stetcms/vite", "@stetcms/client"]),
+		"Add stet() to vite.config.ts"
+	].join("\n");
+	return [
+		key,
+		await installCommand(root, ["@stetcms/client"]),
+		"npx stet generate"
+	].join("\n");
+}
+/** The command's whole body, taking the project root so tests need no `chdir`. */
+async function runInit(root, options) {
+	const { path, existing, detected } = resolveTarget(root, options);
+	if (existing !== void 0 && options.force !== true) fail(`${relative(root, existing)} already exists. Pass --force to overwrite it.`);
+	const output = options.output ?? defaultOutput(root);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, renderStetConfig(output), "utf8");
+	if (detected !== void 0 && detected !== path) warn(`${relative(root, detected)} is the config Stet loads. Pass --config to point the CLI and the plugin at ${relative(root, path)}, or this file goes unread.`);
+	note$1(await nextSteps(root), "Next");
+	done(`Wrote ${relative(root, path)}`);
+}
+const initCommand = new Command("init").description("Write a stet.config.ts to start from").option("--config <path>", "Where to write the config (defaults to ./stet.config.ts)").option("--output <path>", "Where the generated content client should go").option("--force", "Overwrite an existing config").action(async (options) => {
+	begin("stet init");
+	await runInit(process.cwd(), options);
 });
 //#endregion
 //#region src/client.ts
@@ -134,6 +280,10 @@ function saveAuth(auth) {
 	createStore().set(auth);
 	fs.chmodSync(configDir(), 448);
 }
+function clearAuth() {
+	const store = createStore();
+	fs.rmSync(store.path, { force: true });
+}
 function loadAuth() {
 	const store = createStore();
 	const origin = store.get("origin");
@@ -203,27 +353,31 @@ const loginCommand = new Command("login").description("Log in to Stet from this
 	done(`Logged in as ${session?.user.email ?? "your account"}`);
 });
 //#endregion
+//#region src/commands/logout.ts
+const logoutCommand = new Command("logout").description("Log out of Stet on this machine").action(() => {
+	begin("stet logout");
+	const stored = loadAuth();
+	clearAuth();
+	if (stored === null) {
+		done("Already logged out.");
+		return;
+	}
+	done("Logged out.");
+});
+//#endregion
 //#region src/commands/org.ts
 const orgCommand = new Command("org").description("Show the organization your API key is scoped to").option("--api-key <key>", "Organization API key (defaults to STET_API_KEY)").option("--url <url>", "Origin of the Stet deployment").option("--json", "Print the organization as JSON").action(async (options) => {
+	const { createStetClient, safe } = await import("@stetcms/client");
 	const apiKey = options.apiKey ?? process.env.STET_API_KEY;
-	if (apiKey === void 0 || apiKey === "") {
-		console.error("No API key. Pass --api-key or set STET_API_KEY.");
-		process.exit(1);
-	}
+	if (apiKey === void 0 || apiKey === "") fail("No API key. Pass --api-key or set STET_API_KEY.");
 	const origin = resolveOrigin(options.url);
 	const client = createStetClient({
 		origin,
 		apiKey
 	});
 	const { data, error, isDefined } = await safe(client.org.current());
-	if (isDefined && error.code === "UNAUTHORIZED") {
-		console.error("Invalid or revoked API key.");
-		process.exit(1);
-	}
-	if (error !== null) {
-		console.error(error.message !== "" ? error.message : `Could not reach ${origin}.`);
-		process.exit(1);
-	}
+	if (isDefined && error.code === "UNAUTHORIZED") fail("Invalid or revoked API key.");
+	if (error !== null) fail(error.message !== "" ? error.message : `Could not reach ${origin}.`);
 	if (options.json === true) {
 		console.log(JSON.stringify(data, null, 2));
 		return;
@@ -267,21 +421,12 @@ const syncCommand = new Command("sync").description("Publish your analytics trac
 //#region src/commands/whoami.ts
 const whoamiCommand = new Command("whoami").description("Show the account you are logged in as").option("--json", "Print the session as JSON").action(async (options) => {
 	const stored = loadAuth();
-	if (stored === null) {
-		console.error("Not logged in. Run `stet login` first.");
-		process.exit(1);
-	}
+	if (stored === null) fail("Not logged in. Run `stet login` first.");
 	const client = createClient(stored.origin);
 	const fetchOptions = { headers: { Authorization: `Bearer ${stored.token}` } };
 	const { data: session, error } = await client.getSession({ fetchOptions });
-	if (error !== null) {
-		console.error(error.message ?? `Could not reach ${stored.origin}.`);
-		process.exit(1);
-	}
-	if (session === null) {
-		console.error("Your session has expired. Run `stet login` again.");
-		process.exit(1);
-	}
+	if (error !== null) fail(error.message ?? `Could not reach ${stored.origin}.`);
+	if (session === null) fail("Your session has expired. Run `stet login` again.");
 	const { data: organizations } = await client.organization.list({ fetchOptions });
 	const activeOrganization = organizations?.find((organization) => organization.id === session.session.activeOrganizationId);
 	if (options.json === true) {
@@ -304,7 +449,9 @@ const whoamiCommand = new Command("whoami").description("Show the account you ar
 const program = new Command();
 program.name("stet").description("Stet from the command line").version(version);
 program.addCommand(generateCommand);
+program.addCommand(initCommand);
 program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
 program.addCommand(orgCommand);
 program.addCommand(syncCommand);
 program.addCommand(whoamiCommand);

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@stetcms/cli",
-  "version": "0.1.0",
-  "description": "Command line interface for Stet.",
+  "version": "0.2.0",
+  "description": "Command line interface for Stet, the CMS for marketing and engineering: generate a typed content client and publish your tracking plan.",
   "keywords": [
-    "auth",
     "cli",
-    "device-flow",
-    "stet"
+    "cms",
+    "codegen",
+    "content",
+    "headless-cms",
+    "stet",
+    "stetcms",
+    "typescript"
   ],
-  "homepage": "https://github.com/jamiedavenport/stet/tree/main/published/cli#readme",
+  "homepage": "https://docs.stetcms.com/reference/cli",
   "bugs": "https://github.com/jamiedavenport/stet/issues",
   "license": "Apache-2.0",
   "author": "Jamie Davenport (https://jxd.dev)",
@@ -18,9 +22,10 @@
     "directory": "published/cli"
   },
   "bin": {
-    "stet": "./dist/index.mjs"
+    "stet": "./bin/stet.mjs"
   },
   "files": [
+    "bin",
     "dist"
   ],
   "type": "module",
@@ -33,11 +38,12 @@
     "commander": "^15.0.0",
     "conf": "^15.1.0",
     "open": "^11.0.0",
+    "package-manager-detector": "^1.8.0",
     "picocolors": "^1.1.1",
-    "@stetcms/analytics": "0.1.0",
-    "@stetcms/client": "0.1.0",
-    "@stetcms/config": "0.1.0",
-    "@stetcms/vite": "0.1.0"
+    "@stetcms/analytics": "0.2.0",
+    "@stetcms/client": "0.2.0",
+    "@stetcms/vite": "0.2.0",
+    "@stetcms/config": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
@@ -50,6 +56,7 @@
   },
   "scripts": {
     "build": "vp pack",
-    "tc": "tsc --noEmit"
+    "tc": "tsc --noEmit",
+    "test": "vp test run"
   }
 }