blodemd 0.0.14 → 0.1.0

package/README.md

@@ -9,7 +9,7 @@
 - **One-command deploy:** Push your entire docs folder to Blode.md with `blodemd push`.
 - **Scaffold in seconds:** Generate a ready-to-edit docs folder with `blodemd new`.
 - **Config validation:** Catch `docs.json` errors before deploying.
-- **Zero keys:** Sign in once with GitHub in your browser — the CLI handles the rest.
+- **Zero keys locally:** Sign in once with GitHub in your browser — no keys for local deploys. CI uses a project deploy key.
 
 ## Install
 
@@ -41,6 +41,30 @@ blodemd dev
 blodemd push
 ```
 
+## Deploy from CI
+
+The [GitHub App](#auto-deploy-without-the-cli) is the recommended zero-config path. To run the deploy yourself from GitHub Actions, use a project deploy key stored in the `BLODEMD_API_KEY` secret:
+
+```yaml
+name: Deploy docs
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+      - run: npx blodemd@latest push --project your-project-slug
+        env:
+          BLODEMD_API_KEY: ${{ secrets.BLODEMD_API_KEY }}
+```
+
+Create a deploy key in the dashboard under **Settings → Deploy keys**, or copy the `bmd_...` key that `blodemd push` prints the first time it auto-creates a project. Deploy keys are project-scoped and deploy-only — store them as CI secrets, never commit them.
+
 ## Commands
 
 ```bash
@@ -57,6 +81,7 @@ blodemd dev [dir]         Start the local docs preview server
 
 ```
 --project <slug>    Project slug (env: BLODEMD_PROJECT)
+--api-key <token>   API key (env: BLODEMD_API_KEY)
 --api-url <url>     API URL (env: BLODEMD_API_URL)
 --branch <name>     Git branch (env: BLODEMD_BRANCH)
 --message <msg>     Deploy message (env: BLODEMD_COMMIT_MESSAGE)

package/dist/cli.mjs

@@ -20,6 +20,7 @@ import { watch } from "chokidar";
 import { readFileSync } from "node:fs";
 //#region src/constants.ts
 const CLI_NAME = "blodemd";
+const BLODE_API_KEY_ENV = "BLODEMD_API_KEY";
 const BLODE_PROJECT_ENV = "BLODEMD_PROJECT";
 const OAUTH_CLIENT_ID = "6b5f9860-fe96-4a83-b1ad-266260523c91";
 const DEFAULT_OAUTH_CALLBACK_PORT = 8787;
@@ -55,6 +56,7 @@ const toCliError = (error) => {
 	if (error instanceof Error) {
 		if (error instanceof TypeError && error.message.includes("fetch")) return new CliError("Cannot connect to Blode.md API.", EXIT_CODES.NETWORK, "Check your internet connection and API URL configuration.");
 		if (error.name === "TimeoutError" || error.name === "AbortError") return new CliError("Request timed out.", EXIT_CODES.NETWORK, "The API may be unavailable. Try again later.");
+		if (/\b401\b/.test(error.message)) return new CliError(error.message, EXIT_CODES.AUTH_REQUIRED, "Check your API key or run \"blodemd login\".");
 		return new CliError(error.message, EXIT_CODES.ERROR);
 	}
 	return new CliError("Unknown error", EXIT_CODES.ERROR);
@@ -1220,6 +1222,67 @@ const registerAnalyticsCommand = (program) => {
 	});
 };
 //#endregion
+//#region src/output.ts
+const isInteractive = (json = false) => !json && Boolean(process.stdout.isTTY) && !process.env.CI;
+const writeLine = (message) => {
+	process.stderr.write(`${message}\n`);
+};
+const createReporter = ({ json = false } = {}) => {
+	const interactive = isInteractive(json);
+	if (!interactive) return {
+		info: writeLine,
+		interactive,
+		json: (payload) => {
+			process.stdout.write(`${JSON.stringify(payload)}\n`);
+		},
+		step: writeLine,
+		stop: (message) => {
+			if (message) writeLine(message);
+		},
+		success: writeLine,
+		warn: writeLine
+	};
+	const s = spinner();
+	let active = false;
+	return {
+		info(message) {
+			if (active) {
+				s.stop();
+				active = false;
+			}
+			log.info(message);
+		},
+		interactive,
+		json() {},
+		step(message) {
+			if (active) s.message(message);
+			else {
+				s.start(message);
+				active = true;
+			}
+		},
+		stop(message) {
+			if (active) {
+				s.stop(message);
+				active = false;
+			}
+		},
+		success(message) {
+			if (active) {
+				s.stop(message);
+				active = false;
+			} else log.success(message);
+		},
+		warn(message) {
+			if (active) {
+				s.stop();
+				active = false;
+			}
+			log.warn(message);
+		}
+	};
+};
+//#endregion
 //#region src/scaffold.ts
 const SCAFFOLD_TEMPLATES = ["minimal", "starter"];
 const DEFAULT_SCAFFOLD_DIRECTORY = "docs";
@@ -1617,11 +1680,16 @@ const collectFiles = async (root, directory = root) => {
 	}
 	return files.toSorted((left, right) => left.localeCompare(right));
 };
-const reportCommandError = (prefix, error) => {
+const reportCommandError = (prefix, error, options) => {
 	const cliError = toCliError(error);
-	log.error(`${prefix}: ${cliError.message}`);
-	if (cliError.hint) log.info(cliError.hint);
-	log.info("Failed");
+	if (isInteractive(options?.json)) {
+		log.error(`${prefix}: ${cliError.message}`);
+		if (cliError.hint) log.info(cliError.hint);
+		log.info("Failed");
+	} else {
+		process.stderr.write(`${prefix}: ${cliError.message}\n`);
+		if (cliError.hint) process.stderr.write(`${cliError.hint}\n`);
+	}
 	process.exitCode = cliError.exitCode;
 };
 const parseScaffoldTemplate = (value) => {
@@ -1827,6 +1895,7 @@ const registerAuthCommands = (program) => {
 			const resolved = await resolveAuthToken();
 			if (!resolved) {
 				log.warn("Not logged in. Run \"blodemd login\" to authenticate.");
+				process.exitCode = EXIT_CODES.AUTH_REQUIRED;
 				return;
 			}
 			const status = resolveTokenStatus(resolved);
@@ -2513,6 +2582,31 @@ const registerNewCommand = (program) => {
 	});
 };
 //#endregion
+//#region src/commands/projects.ts
+const registerProjectsCommand = (program) => {
+	program.command("projects").description("List your projects").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--json", "output machine-readable JSON (implies non-interactive)").action(async (options) => {
+		const reporter = createReporter({ json: options.json });
+		if (reporter.interactive) intro(chalk.bold("blodemd projects"));
+		try {
+			const resolved = await resolveAuthToken();
+			if (!resolved?.token) throw new CliError("Run \"blodemd login\" to list your projects. API keys cannot list projects.", EXIT_CODES.AUTH_REQUIRED, "Run \"blodemd login\" to authenticate.");
+			const apiUrl = options.apiUrl ?? process.env["BLODEMD_API_URL"] ?? "https://api.blode.md";
+			const projects = await requestJson(new URL("/projects", apiUrl).toString(), { headers: { Authorization: `Bearer ${resolved.token}` } }, "Failed to list projects");
+			reporter.json(projects);
+			if (projects.length === 0) {
+				reporter.info("No projects yet.");
+				return;
+			}
+			for (const project of projects) {
+				const label = project.name ? `${chalk.cyan(project.slug)} — ${project.name}` : chalk.cyan(project.slug);
+				reporter.info(label);
+			}
+		} catch (error) {
+			reportCommandError("Projects failed", error, { json: options.json });
+		}
+	});
+};
+//#endregion
 //#region src/upload.ts
 const TEXT_CONTENT_TYPES = {
 	".css": "text/css; charset=utf-8",
@@ -2556,6 +2650,19 @@ const createUploadBatches = async function* createUploadBatchesGenerator({ files
 };
 //#endregion
 //#region src/commands/push.ts
+const resolveAuthHeaders = async (apiKeyOption) => {
+	const apiKey = (apiKeyOption ?? process.env["BLODEMD_API_KEY"])?.trim();
+	if (apiKey) return {
+		canAutoCreate: false,
+		headers: { Authorization: `Bearer ${apiKey}` }
+	};
+	const resolved = await resolveAuthToken();
+	if (!resolved?.token) throw new Error("Not logged in. Run \"blodemd login\" to authenticate, pass --api-key, or set BLODEMD_API_KEY (see https://blode.md/docs/deployment/ci).");
+	return {
+		canAutoCreate: true,
+		headers: { Authorization: `Bearer ${resolved.token}` }
+	};
+};
 const resolvePushConfig = async (config, options) => {
 	const { project, usedLegacyNameFallback } = resolveProjectTarget({
 		cliProject: options.project,
@@ -2563,7 +2670,6 @@ const resolvePushConfig = async (config, options) => {
 		envProject: process.env[BLODE_PROJECT_ENV]
 	});
 	const apiUrl = options.apiUrl ?? process.env["BLODEMD_API_URL"] ?? "https://api.blode.md";
-	const authToken = (await resolveAuthToken())?.token;
 	const branch = options.branch ?? process.env["BLODEMD_BRANCH"] ?? process.env.GITHUB_REF_NAME ?? readGitValue([
 		"rev-parse",
 		"--abbrev-ref",
@@ -2580,19 +2686,21 @@ const resolvePushConfig = async (config, options) => {
 		if (usedLegacyNameFallback) throw new Error(`docs.json.name is not a valid deployment slug. Add "slug" to docs.json, pass --project, or set BLODEMD_PROJECT. ${projectSlugError}`);
 		throw new Error(`Invalid project slug "${project}". ${projectSlugError}`);
 	}
-	if (!authToken) throw new Error("Not logged in. Run \"blodemd login\" to authenticate.");
+	const { headers: authHeaders, canAutoCreate } = await resolveAuthHeaders(options.apiKey);
 	return {
 		apiUrl,
-		authToken,
+		authHeaders,
 		branch,
+		canAutoCreate,
 		commitMessage,
 		project,
 		projectDisplayName: config.name?.trim() || project,
 		usedLegacyNameFallback
 	};
 };
-const autoCreateProject = async (project, projectDisplayName, apiUrl, headers) => {
-	if (!(await readAuthFile())?.session) throw new Error(`Project "${project}" not found. Create it at blode.md or login with "blodemd login" to auto-create.`);
+const autoCreateProject = async (project, projectDisplayName, apiUrl, headers, canAutoCreate, reporter) => {
+	if (!canAutoCreate) throw new Error(`Project "${project}" not found. Create it at blode.md or login with "blodemd login" to auto-create.`);
+	if (!reporter.interactive) throw new Error(`Project "${project}" not found. Create it in the dashboard or run \`blodemd push\` in an interactive terminal to auto-create it.`);
 	const shouldCreate = await confirm({ message: `Project "${project}" doesn't exist. Create it?` });
 	if (isCancel(shouldCreate) || !shouldCreate) return false;
 	const createResult = await requestJson(new URL("/projects", apiUrl).toString(), {
@@ -2603,12 +2711,18 @@ const autoCreateProject = async (project, projectDisplayName, apiUrl, headers) =
 		headers,
 		method: "POST"
 	}, "Failed to create project");
-	log.success(`Project ${chalk.cyan(createResult.slug)} created`);
+	reporter.success(`Project ${chalk.cyan(createResult.slug)} created`);
+	const keyResult = await requestJson(new URL(`/projects/${createResult.id}/keys`, apiUrl).toString(), {
+		body: JSON.stringify({ name: "CI deploy key" }),
+		headers,
+		method: "POST"
+	}, "Failed to create deploy key");
+	reporter.info(`Deploy key created (save this — shown once, use as ${BLODE_API_KEY_ENV} in CI): ${chalk.cyan(keyResult.key)}`);
 	return true;
 };
 const MAX_BATCH_BYTES = 4 * 1024 * 1024;
-const uploadFiles = async (files, root, apiPath, deploymentId, headers, s) => {
-	s.start(`Uploading ${files.length} files`);
+const uploadFiles = async (files, root, apiPath, deploymentId, headers, reporter) => {
+	reporter.step(`Uploading ${files.length} files`);
 	let uploaded = 0;
 	for await (const batch of createUploadBatches({
 		files,
@@ -2621,28 +2735,28 @@ const uploadFiles = async (files, root, apiPath, deploymentId, headers, s) => {
 			method: "POST"
 		}, "Failed to upload files");
 		uploaded += batch.length;
-		s.message(`Uploading files (${uploaded}/${files.length})`);
+		reporter.step(`Uploading files (${uploaded}/${files.length})`);
 	}
-	s.stop(`Uploaded ${chalk.cyan(String(files.length))} files`);
+	reporter.success(`Uploaded ${chalk.cyan(String(files.length))} files`);
 };
 const registerPushCommand = (program) => {
-	program.command("push").description("Deploy docs").argument("[dir]", "docs directory").option("--project <slug>", "project slug (env: BLODEMD_PROJECT)").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--branch <name>", "git branch (env: BLODEMD_BRANCH)").option("--message <msg>", "deploy message (env: BLODEMD_COMMIT_MESSAGE)").action(async (dir, options) => {
-		intro(chalk.bold("blodemd push"));
-		const s = spinner();
+	program.command("push").description("Deploy docs").argument("[dir]", "docs directory").option("--project <slug>", "project slug (env: BLODEMD_PROJECT)").option("--api-key <token>", "API key (env: BLODEMD_API_KEY)").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--branch <name>", "git branch (env: BLODEMD_BRANCH)").option("--message <msg>", "deploy message (env: BLODEMD_COMMIT_MESSAGE)").option("--json", "output machine-readable JSON (implies non-interactive)").action(async (dir, options) => {
+		const reporter = createReporter({ json: options.json });
+		if (reporter.interactive) intro(chalk.bold("blodemd push"));
 		try {
 			const root = await resolveDocsRoot(dir);
-			s.start("Validating configuration");
+			reporter.step("Validating configuration");
 			const { config, warnings } = await loadValidatedSiteConfig(root);
-			s.stop("Configuration valid");
-			for (const warning of warnings) log.warn(warning);
-			const { project, projectDisplayName, apiUrl, authToken, branch, commitMessage, usedLegacyNameFallback } = await resolvePushConfig(config, options);
-			if (usedLegacyNameFallback) log.warn(LEGACY_PROJECT_NAME_FALLBACK_WARNING);
-			s.start("Collecting files");
+			reporter.success("Configuration valid");
+			for (const warning of warnings) reporter.warn(warning);
+			const { project, projectDisplayName, apiUrl, authHeaders, canAutoCreate, branch, commitMessage, usedLegacyNameFallback } = await resolvePushConfig(config, options);
+			if (usedLegacyNameFallback) reporter.warn(LEGACY_PROJECT_NAME_FALLBACK_WARNING);
+			reporter.step("Collecting files");
 			const files = await collectFiles(root);
 			if (files.length === 0) throw new Error("No files found to deploy.");
-			s.stop(`Found ${chalk.cyan(String(files.length))} files`);
+			reporter.success(`Found ${chalk.cyan(String(files.length))} files`);
 			const headers = {
-				Authorization: `Bearer ${authToken}`,
+				...authHeaders,
 				"Content-Type": "application/json"
 			};
 			const apiPath = (suffix) => new URL(`/projects/slug/${project}/deployments${suffix}`, apiUrl).toString();
@@ -2650,7 +2764,7 @@ const registerPushCommand = (program) => {
 				branch,
 				commitMessage
 			});
-			s.start("Creating deployment");
+			reporter.step("Creating deployment");
 			let deployment;
 			try {
 				deployment = await requestJson(apiPath(""), {
@@ -2660,34 +2774,39 @@ const registerPushCommand = (program) => {
 				}, "Failed to create deployment");
 			} catch (error) {
 				if (!(error instanceof Error ? error.message : "").includes("404")) throw error;
-				s.stop("Project not found");
-				if (!await autoCreateProject(project, projectDisplayName, apiUrl, headers)) {
-					log.info("Cancelled");
+				reporter.stop("Project not found");
+				if (!await autoCreateProject(project, projectDisplayName, apiUrl, headers, canAutoCreate, reporter)) {
+					reporter.info("Cancelled");
 					return;
 				}
-				s.start("Creating deployment");
+				reporter.step("Creating deployment");
 				deployment = await requestJson(apiPath(""), {
 					body: createDeploymentBody,
 					headers,
 					method: "POST"
 				}, "Failed to create deployment");
 			}
-			s.stop(`Deployment ${chalk.cyan(deployment.id)} created`);
-			await uploadFiles(files, root, apiPath, deployment.id, headers, s);
-			s.start("Finalizing deployment");
+			reporter.success(`Deployment ${chalk.cyan(deployment.id)} created`);
+			await uploadFiles(files, root, apiPath, deployment.id, headers, reporter);
+			reporter.step("Finalizing deployment");
 			const finalized = await requestJson(apiPath(`/${deployment.id}/finalize`), {
 				body: JSON.stringify({ promote: true }),
 				headers,
 				method: "POST"
 			}, "Failed to finalize deployment");
-			s.stop("Deployment finalized");
-			log.success(`Published ${chalk.cyan(finalized.id)}`);
-			if (finalized.manifestUrl) log.info(`Manifest: ${finalized.manifestUrl}`);
-			if (typeof finalized.fileCount === "number") log.info(`Files: ${finalized.fileCount}`);
-			log.info("Done");
+			reporter.success("Deployment finalized");
+			reporter.success(`Published ${chalk.cyan(finalized.id)}`);
+			if (finalized.manifestUrl) reporter.info(`Manifest: ${finalized.manifestUrl}`);
+			if (typeof finalized.fileCount === "number") reporter.info(`Files: ${finalized.fileCount}`);
+			reporter.info("Done");
+			reporter.json({
+				deploymentId: finalized.id,
+				fileCount: finalized.fileCount ?? files.length,
+				manifestUrl: finalized.manifestUrl ?? null
+			});
 		} catch (error) {
-			s.stop("Failed");
-			reportCommandError("Push failed", error);
+			reporter.stop("Failed");
+			reportCommandError("Push failed", error, { json: options.json });
 		}
 	});
 };
@@ -2695,15 +2814,24 @@ const registerPushCommand = (program) => {
 //#region src/commands/validate.ts
 const CONFIG_FILE = "docs.json";
 const registerValidateCommand = (program) => {
-	program.command("validate").description("Validate docs.json").argument("[dir]", "docs directory").action(async (dir) => {
-		intro(chalk.bold("blodemd validate"));
+	program.command("validate").description("Validate docs.json").argument("[dir]", "docs directory").option("--json", "output machine-readable JSON (implies non-interactive)").action(async (dir, options) => {
+		const reporter = createReporter({ json: options.json });
+		if (reporter.interactive) intro(chalk.bold("blodemd validate"));
 		try {
 			const { warnings } = await loadValidatedSiteConfig(await resolveDocsRoot(dir));
-			for (const warning of warnings) log.warn(warning);
-			log.success(`${chalk.cyan(CONFIG_FILE)} is valid.`);
-			log.info("Done");
+			for (const warning of warnings) reporter.warn(warning);
+			reporter.success(`${chalk.cyan(CONFIG_FILE)} is valid.`);
+			reporter.info("Done");
+			reporter.json({
+				valid: true,
+				warnings
+			});
 		} catch (error) {
-			reportCommandError("Validation failed", error);
+			if (options.json && error instanceof CliError && error.exitCode === EXIT_CODES.VALIDATION) reporter.json({
+				errors: error.message.split("\n"),
+				valid: false
+			});
+			reportCommandError("Validation failed", error, { json: options.json });
 		}
 	});
 };
@@ -2757,9 +2885,18 @@ registerAuthCommands(program);
 registerNewCommand(program);
 registerValidateCommand(program);
 registerPushCommand(program);
+registerProjectsCommand(program);
 registerDevCommand(program);
 registerAnalyticsCommand(program);
-program.parse();
+program.addHelpText("after", "\nExample:\n  $ blodemd push ./docs --project my-docs\n");
+try {
+	await program.parseAsync();
+} catch (error) {
+	const cliError = toCliError(error);
+	console.error(cliError.message);
+	if (cliError.hint) console.error(cliError.hint);
+	process.exitCode = cliError.exitCode;
+}
 //#endregion
 export {};