storyshelf 0.3.2 → 0.5.4

package/README.md

@@ -99,7 +99,8 @@ jobs:
         with: { node-version: 20 }
       - run: nub install && nub run build
       - run: nubx storybook build -o storybook-static
-      - run: nubx storyshelf upload \
+      - run:
+          nubx storyshelf upload \
           --token "${{ secrets.STORYSHELF_TOKEN }}" \
           --sha "${{ github.sha }}" \
           --branch "${{ github.ref_name }}"

package/dist/client.js

@@ -3,6 +3,21 @@ import "node:path";
 import "node:url";
 import.meta.url;
 //#region src/client.ts
+/**
+* Create a typed API client for a StoryShelf server.
+*
+* Wraps `fetch` with bearer auth and JSON helpers so commands can call
+* `client.projects.builds.createJson(...)` without hand-rolling URLs or headers.
+*
+* @param baseUrl - Server origin, e.g. `https://shelf.example.com`
+* @param token - Optional bearer token (CI or admin token); sent as `Authorization: Bearer <token>`
+* @returns Namespaced client with `projects`, `builds`, `tokens`, and `admin` helpers
+*/
+function createClient(baseUrl, token) {
+	const authHeaders = buildAuthHeaders(token);
+	const requestHeaders = (contentType) => buildRequestHeaders(authHeaders, contentType);
+	return { projects: createProjectsApi(baseUrl, authHeaders, requestHeaders) };
+}
 function buildAuthHeaders(token) {
 	return token ? { Authorization: `Bearer ${token}` } : {};
 }
@@ -48,6 +63,11 @@ function createBuildsApi(baseUrl, authHeaders, requestHeaders) {
 			method: "POST",
 			headers: requestHeaders("application/json"),
 			body: JSON.stringify({})
+		}),
+		postAffected: async (slug, buildId, json) => await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds/${buildId}/affected`, {
+			method: "POST",
+			headers: requestHeaders("application/json"),
+			body: JSON.stringify(json)
 		})
 	};
 }
@@ -77,10 +97,5 @@ function createProjectsApi(baseUrl, authHeaders, requestHeaders) {
 		admin: createAdminApi(baseUrl, requestHeaders)
 	};
 }
-function createClient(baseUrl, token) {
-	const authHeaders = buildAuthHeaders(token);
-	const requestHeaders = (contentType) => buildRequestHeaders(authHeaders, contentType);
-	return { projects: createProjectsApi(baseUrl, authHeaders, requestHeaders) };
-}
 //#endregion
 export { createClient };

package/dist/commands/build.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { loadStorybookConfig } from "../config.js";
+import { printLine } from "../output.js";
+import { assertBuildOutput, ensureBuildDir } from "./storybook-build.js";
+import { resolve } from "node:path";
+//#region src/commands/build.ts
+/**
+* Build a Storybook directory without uploading, using the same
+* buildDir/buildCommand/buildScriptName resolution as `upload`.
+*
+* @param options - Build command options.
+*/
+async function runBuild(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const cfg = await loadStorybookConfig(cwd, options.config);
+	const buildDir = options.buildDir ?? cfg?.buildDir ?? "storybook-static";
+	await ensureBuildDir({
+		cwd,
+		buildDir,
+		buildCommand: options.buildCommand ?? cfg?.buildCommand,
+		buildScriptName: options.buildScriptName ?? cfg?.buildScriptName,
+		force: options.forceBuild
+	});
+	await assertBuildOutput(cwd, buildDir);
+	printLine(`Build ready: ${resolve(cwd, buildDir)}`);
+}
+//#endregion
+export { runBuild };

package/dist/commands/connection.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { loadStorybookConfig } from "../config.js";
+//#region src/commands/connection.ts
+/**
+* Resolve url/slug/token as flags > config file > env, throwing on the first
+* missing value (same messages as `upload`).
+*/
+async function resolveConnection(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const cfg = await loadStorybookConfig(cwd, options.config);
+	const fields = {
+		url: options.url ?? cfg?.url ?? process.env["STORYSHELF_URL"],
+		slug: options.slug ?? cfg?.slug ?? process.env["STORYSHELF_SLUG"],
+		token: options.token ?? process.env["STORYSHELF_TOKEN"] ?? process.env["SHELF_TOKEN"]
+	};
+	assertConnectionFields(fields);
+	return fields;
+}
+/** Throw on the first missing connection field. */
+function assertConnectionFields(fields) {
+	if (!fields.url) throw new Error("--url is required (or .storybook/storyshelf.json / STORYSHELF_URL)");
+	if (!fields.slug) throw new Error("--slug is required (or .storybook/storyshelf.json / STORYSHELF_SLUG)");
+	if (!fields.token) throw new Error("--token is required (or STORYSHELF_TOKEN env)");
+}
+//#endregion
+export { resolveConnection };

package/dist/commands/create.js

@@ -2,9 +2,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { createClient } from "../client.js";
 import { assertStorybookMain, detectGitDefaultBranch, detectGitRepository, detectPackageName, detectStorybookMeta, writeStorybookConfig } from "../config.js";
 import { printError, printLine } from "../output.js";
+import { createClient } from "../client.js";
 //#region src/commands/create.ts
 async function readCreateInputs(options, cwd) {
 	const name = (options.name === "" ? void 0 : options.name) ?? await detectPackageName(cwd);

package/dist/commands/doctor.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { findStorybookMain, loadStorybookConfig } from "../config.js";
+import { printLine } from "../output.js";
+import { needsBuild, resolveBuildCommand } from "./storybook-build.js";
+import { createClient } from "../client.js";
+import { resolveConnection } from "./connection.js";
+import { resolve } from "node:path";
+import { access, readdir } from "node:fs/promises";
+import { gitRepoStatus } from "@storyshelf/affected";
+//#region src/commands/doctor.ts
+function mark(status) {
+	if (status === "pass") return "✓";
+	return status === "warn" ? "!" : "✗";
+}
+async function checkSetup(cwd) {
+	const main = await findStorybookMain(cwd);
+	if (!main) return {
+		status: "fail",
+		message: "No .storybook/main.* found"
+	};
+	return {
+		status: "pass",
+		message: `Storybook setup found (${main})`
+	};
+}
+function checkConfigFile(cfg) {
+	if (!cfg) return {
+		status: "warn",
+		message: "No config file — url/slug/token must come from flags or env"
+	};
+	return {
+		status: "pass",
+		message: `Config loaded (slug "${cfg.slug}")`
+	};
+}
+function serverErrorMessage(error) {
+	if (error instanceof TypeError) return "cannot reach server — check --url and network";
+	const message = error instanceof Error ? error.message : String(error);
+	if (message.includes("(401)")) return "authentication failed (401) — check STORYSHELF_TOKEN";
+	if (message.includes("(403)")) return "forbidden (403) — token lacks access to this project";
+	if (message.includes("(404)")) return "project not found (404) — check --slug";
+	return message;
+}
+async function checkServer(connection) {
+	try {
+		const project = await createClient(connection.url, connection.token).projects.get(connection.slug);
+		return {
+			status: "pass",
+			message: `Server reachable, project "${typeof project.name === "string" && project.name.length > 0 ? project.name : connection.slug}" readable`
+		};
+	} catch (error) {
+		return {
+			status: "fail",
+			message: `Server check failed: ${serverErrorMessage(error)}`
+		};
+	}
+}
+async function checkBuildOutput(cwd, inputs) {
+	const full = resolve(cwd, inputs.buildDir);
+	if (await needsBuild(full)) return {
+		status: "warn",
+		message: `Build output missing — upload would run: ${await resolveBuildCommand(cwd, inputs.buildDir, inputs.buildCommand, inputs.buildScriptName)}`
+	};
+	try {
+		await access(resolve(full, "index.json"));
+	} catch {
+		return {
+			status: "fail",
+			message: `Build output incomplete: no index.json in ${inputs.buildDir} (upload would zip it as-is)`
+		};
+	}
+	const entries = await readdir(full);
+	return {
+		status: "pass",
+		message: `Build output ready: ${inputs.buildDir} (${entries.length} top-level entries)`
+	};
+}
+function resolveBuildInputs(options, cfg) {
+	return {
+		buildDir: options.buildDir ?? cfg?.buildDir ?? "storybook-static",
+		buildCommand: options.buildCommand ?? cfg?.buildCommand,
+		buildScriptName: options.buildScriptName ?? cfg?.buildScriptName
+	};
+}
+/**
+* Diagnose whether an upload would succeed, without uploading anything.
+* Prints one line per check; sets exit code 1 when any check fails.
+*
+* @param options - Connection and build options (flags, config, or env).
+*/
+async function runDoctor(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const cfg = await loadStorybookConfig(cwd, options.config);
+	const checks = [await checkSetup(cwd), checkConfigFile(cfg)];
+	const connection = await tryResolveConnection(options, checks);
+	if (connection) checks.push(await checkServer(connection));
+	checks.push(await checkBuildOutput(cwd, resolveBuildInputs(options, cfg)), await checkAffected(cwd, resolveBuildInputs(options, cfg).buildDir));
+	reportChecks(checks);
+}
+/** Warn when affected capture would silently fall back to a full render. */
+async function checkAffected(cwd, buildDir) {
+	const repo = gitRepoStatus(cwd);
+	if (repo === "no-git") return {
+		status: "warn",
+		message: "No git repository — upload uses a synthetic local identity and affected capture renders all stories"
+	};
+	if (repo === "shallow") return {
+		status: "warn",
+		message: "Shallow clone detected — affected capture renders all stories (use fetch-depth: 0)"
+	};
+	try {
+		await access(resolve(cwd, buildDir, "preview-stats.json"));
+	} catch {
+		return {
+			status: "warn",
+			message: `No preview-stats.json in ${buildDir} — affected capture renders all stories`
+		};
+	}
+	return {
+		status: "pass",
+		message: "Affected capture ready (history and stats available)"
+	};
+}
+/** Resolve the connection, recording success or failure as a check. */
+async function tryResolveConnection(options, checks) {
+	try {
+		const connection = await resolveConnection(options);
+		checks.push({
+			status: "pass",
+			message: `Connection: ${connection.url} / ${connection.slug} (token present)`
+		});
+		return connection;
+	} catch (error) {
+		checks.push({
+			status: "fail",
+			message: error instanceof Error ? error.message : String(error)
+		});
+		return null;
+	}
+}
+/** Print all checks; fail the process when any check failed. */
+function reportChecks(checks) {
+	for (const check of checks) printLine(`${mark(check.status)} ${check.message}`);
+	if (checks.some((check) => check.status === "fail")) process.exitCode = 1;
+}
+//#endregion
+export { runDoctor };

package/dist/commands/init.js

@@ -2,9 +2,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { createClient } from "../client.js";
 import { assertStorybookMain, detectStorybookMeta, loadStorybookConfig, writeStorybookConfig } from "../config.js";
 import { printError, printLine } from "../output.js";
+import { createClient } from "../client.js";
 import prompts from "prompts";
 //#region src/commands/init.ts
 /** Human description of the detected Storybook (framework, addons, path). */
@@ -96,7 +96,7 @@ function buildInitConfig(answers, slug) {
 /** Persist the resolved answers to .storybook/storyshelf.json. */
 async function persistInitConfig(answers, slug, cwd, configPath) {
 	try {
-		const written = await writeStorybookConfig(buildInitConfig(answers, slug), cwd, configPath);
+		const written = await writeStorybookConfig(buildInitConfig(answers, slug), cwd, configPath, { stampSchema: true });
 		printLine(`Wrote ${written}`);
 		if (answers.detected) printLine(`Detected ${answers.detected}`);
 	} catch (error) {

package/dist/commands/purge.js

@@ -2,8 +2,8 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { createClient } from "../client.js";
 import { printLine } from "../output.js";
+import { createClient } from "../client.js";
 //#region src/commands/purge.ts
 /**
 * Purge expired builds on a StoryShelf server.

package/dist/commands/retry.js

@@ -2,8 +2,8 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { createClient } from "../client.js";
 import { printLine } from "../output.js";
+import { createClient } from "../client.js";
 //#region src/commands/retry.ts
 /**
 * Retry a failed StoryShelf build.

package/dist/commands/server/docker.js

@@ -30,7 +30,7 @@ const DOCKERIGNORE_LINES = [
 	".env*",
 	"data/"
 ];
-const COMPOSE_LINES = [
+const COMPOSE_BASE_LINES = [
 	"services:",
 	"  storyshelf:",
 	"    build: .",
@@ -41,22 +41,87 @@ const COMPOSE_LINES = [
 	"    environment:",
 	"      - SECRET=change-me",
 	"      - PORT=3000",
-	"      - DATA_DIR=/data",
-	"      # Add your env vars here:",
-	"      # - AUTH_PASSWORD=your-password",
-	"      # - TURSO_DATABASE_URL=libsql://...",
-	"      # - TURSO_AUTH_TOKEN=...",
-	"volumes:",
-	"  storyshelf-data:"
+	"      - DATA_DIR=/data"
+];
+const COMPOSE_TURSO_LINES = ["      # - TURSO_DATABASE_URL=libsql://...", "      # - TURSO_AUTH_TOKEN=..."];
+const COMPOSE_POSTGRES_LINES = [
+	"      - DATABASE_URL=postgres://shelf:shelf@postgres:5432/shelf",
+	"    depends_on:",
+	"      postgres:",
+	"        condition: service_healthy",
+	"  postgres:",
+	"    image: postgres:16-alpine",
+	"    environment:",
+	"      - POSTGRES_DB=shelf",
+	"      - POSTGRES_USER=shelf",
+	"      - POSTGRES_PASSWORD=shelf",
+	"    volumes:",
+	"      - postgres-data:/var/lib/postgresql/data",
+	"    healthcheck:",
+	"      test: [\"CMD-SHELL\", \"pg_isready -U shelf -d shelf\"]",
+	"      interval: 5s",
+	"      timeout: 5s",
+	"      retries: 5"
 ];
+const COMPOSE_VOLUMES_LINES = ["volumes:", "  storyshelf-data:"];
+const COMPOSE_POSTGRES_VOLUMES_LINES = ["  postgres-data:"];
 function generateDockerfile() {
 	return DOCKERFILE_LINES.join("\n");
 }
 function generateDockerignore() {
 	return DOCKERIGNORE_LINES.join("\n");
 }
-function generateComposeYaml() {
-	return COMPOSE_LINES.join("\n");
+function generateComposeYaml(database = "sqlite") {
+	return [
+		...COMPOSE_BASE_LINES,
+		"      # Add your env vars here:",
+		"      # - AUTH_PASSWORD=your-password",
+		...database === "turso" ? COMPOSE_TURSO_LINES : [],
+		...database === "postgres" ? COMPOSE_POSTGRES_LINES : [],
+		...COMPOSE_VOLUMES_LINES,
+		...database === "postgres" ? COMPOSE_POSTGRES_VOLUMES_LINES : []
+	].join("\n");
+}
+const WORKER_DOCKERFILE_LINES = [
+	"FROM node:lts-alpine AS builder",
+	"WORKDIR /app",
+	"COPY package.json ./",
+	"RUN npm install",
+	"COPY worker.ts ./",
+	"RUN npx esbuild worker.ts --bundle --platform=node --format=esm \\",
+	"  --external:playwright-core \\",
+	"  --outfile=dist/worker.mjs",
+	"",
+	"FROM mcr.microsoft.com/playwright:v1.63.0-noble",
+	"WORKDIR /app",
+	"COPY --from=builder /app/dist/worker.mjs ./",
+	"COPY --from=builder /app/node_modules/playwright-core ./node_modules/playwright-core",
+	"ENV DATA_DIR=/data",
+	"CMD [\"node\", \"dist/worker.mjs\"]"
+];
+const WORKER_COMPOSE_LINES = [
+	"  worker:",
+	"    build:",
+	"      dockerfile: Dockerfile.worker",
+	"    volumes:",
+	"      - storyshelf-data:/data",
+	"    environment:",
+	"      - SECRET=change-me",
+	"      - DATA_DIR=/data",
+	"      - QUEUE_URL=${QUEUE_URL}",
+	"      - WORKER_CONCURRENCY=2",
+	"    depends_on:",
+	"      storyshelf:",
+	"        condition: service_started"
+];
+function generateWorkerDockerfile() {
+	return WORKER_DOCKERFILE_LINES.join("\n");
+}
+function generateWorkerComposeSnippet() {
+	return WORKER_COMPOSE_LINES.join("\n");
+}
+function generateComposeYamlWithWorker(database = "sqlite") {
+	return `${generateComposeYaml(database)}\n${generateWorkerComposeSnippet()}`;
 }
 //#endregion
-export { generateComposeYaml, generateDockerfile, generateDockerignore };
+export { generateComposeYaml, generateComposeYamlWithWorker, generateDockerfile, generateDockerignore, generateWorkerComposeSnippet, generateWorkerDockerfile };