storyshelf 0.3.2 → 0.5.3

package/dist/commands/upload.js

@@ -2,15 +2,49 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { createClient } from "../client.js";
 import { loadStorybookConfig } from "../config.js";
 import { createSpinner, printLine, spinnerFrames } from "../output.js";
-import { execSync } from "node:child_process";
-import { access, readdir } from "node:fs/promises";
+import { assertBuildOutput, ensureBuildDir } from "./storybook-build.js";
+import { createClient } from "../client.js";
 import { resolve } from "node:path";
+import { LOCAL_BRANCH, computeAffected, gitBranchName, gitHeadSha, localSha } from "@storyshelf/affected";
 import { ZipArchive } from "archiver";
 import * as picomatch from "picomatch";
 //#region src/commands/upload.ts
+/**
+* Upload a built Storybook and create a build record.
+*
+* @param options - Upload command options.
+*/
+async function runUpload(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const collected = collectUploadOptions(cwd, options, await loadStorybookConfig(cwd, options.config));
+	if (collected.synthesized) printLine(`No git checkout detected — using synthetic identity sha=${collected.sha} branch="${collected.branch}" (pass --sha/--branch to override)`);
+	if (shouldSkipUpload(collected.skip, collected.branch)) {
+		printLine(`Skipped per config skip="${collected.skip}" for branch "${collected.branch}"`);
+		return;
+	}
+	assertUploadOptions(collected);
+	await buildAndPost(cwd, collected, options.forceBuild, options.dryRun);
+}
+const defaultProbe = {
+	headSha: gitHeadSha,
+	branchName: gitBranchName
+};
+/**
+* Resolve sha/branch per field: flags > env > local git > synthesized local
+* identity. Synthesis always succeeds, so checkouts without git can upload
+* with zero identity flags.
+*/
+function resolveIdentity(cwd, options, probe = defaultProbe) {
+	const sha = options.sha ?? envOf("GITHUB_SHA", "VERCEL_GIT_COMMIT_SHA", "CI_COMMIT_SHA");
+	const branch = options.branch ?? envOf("GITHUB_REF_NAME", "VERCEL_GIT_COMMIT_REF", "CI_COMMIT_REF_NAME");
+	return {
+		sha: sha ?? probe.headSha(cwd) ?? localSha(),
+		branch: branch ?? probe.branchName(cwd) ?? LOCAL_BRANCH,
+		synthesized: sha === void 0 || branch === void 0
+	};
+}
 /** First set value among the given env var names. */
 function envOf(...names) {
 	for (const name of names) {
@@ -19,13 +53,15 @@ function envOf(...names) {
 	}
 }
 /** Layer explicit options over env and the client config file. */
-function collectUploadOptions(options, cfg) {
+function collectUploadOptions(cwd, options, cfg) {
+	const identity = resolveIdentity(cwd, options);
 	return {
 		url: options.url ?? cfg?.url ?? envOf("STORYSHELF_URL"),
 		slug: options.slug ?? cfg?.slug ?? envOf("STORYSHELF_SLUG"),
 		token: options.token ?? envOf("STORYSHELF_TOKEN", "SHELF_TOKEN"),
-		sha: options.sha ?? envOf("GITHUB_SHA", "VERCEL_GIT_COMMIT_SHA", "CI_COMMIT_SHA"),
-		branch: options.branch ?? envOf("GITHUB_REF_NAME", "VERCEL_GIT_COMMIT_REF", "CI_COMMIT_REF_NAME"),
+		sha: identity.sha,
+		branch: identity.branch,
+		synthesized: identity.synthesized,
 		buildDir: options.buildDir ?? cfg?.buildDir ?? "storybook-static",
 		buildCommand: options.buildCommand ?? cfg?.buildCommand,
 		buildScriptName: options.buildScriptName ?? cfg?.buildScriptName,
@@ -33,16 +69,26 @@ function collectUploadOptions(options, cfg) {
 		message: options.message,
 		authorEmail: options.authorEmail,
 		authorName: options.authorName,
-		label: options.label
+		label: options.label,
+		affectedOnly: resolveAffectedOnly(options, cfg),
+		untraced: mergeUntraced(cfg?.untraced, options.untraced),
+		statsFile: options.statsFile
 	};
 }
+/** Combine config-file and flag untraced globs, deduplicated in order. */
+function mergeUntraced(configured, flagged) {
+	return [.../* @__PURE__ */ new Set([...configured ?? [], ...flagged ?? []])];
+}
+/** Affected capture is on by default; `--full` (or `STORYSHELF_FULL=1`) opts out. */
+function resolveAffectedOnly(options, cfg) {
+	if (options.full === true || envOf("STORYSHELF_FULL") === "1") return false;
+	return options.affectedOnly ?? cfg?.affectedOnly ?? true;
+}
 /** Throw on the first missing required upload option. */
 function assertUploadOptions(collected) {
 	if (!collected.url) throw new Error("--url is required (or .storybook/storyshelf.json / STORYSHELF_URL)");
 	if (!collected.slug) throw new Error("--slug is required (or .storybook/storyshelf.json / STORYSHELF_SLUG)");
 	if (!collected.token) throw new Error("--token is required (or STORYSHELF_TOKEN env)");
-	if (!collected.sha) throw new Error("--sha is required (or GITHUB_SHA env)");
-	if (!collected.branch) throw new Error("--branch is required (or GITHUB_REF_NAME env)");
 }
 function shouldSkipUpload(skip, branch) {
 	return Boolean(skip && branch && picomatch.isMatch(branch, skip));
@@ -71,23 +117,8 @@ function zipBuildDirStream(cwd, buildDir) {
 	archive.finalize().catch(() => {});
 	return archive;
 }
-/**
-* Upload a built Storybook and create a build record.
-*
-* @param options - Upload command options.
-*/
-async function runUpload(options) {
-	const cwd = options.cwd ?? process.cwd();
-	const collected = collectUploadOptions(options, await loadStorybookConfig(cwd, options.config));
-	if (shouldSkipUpload(collected.skip, collected.branch)) {
-		printLine(`Skipped per config skip="${collected.skip}" for branch "${collected.branch}"`);
-		return;
-	}
-	assertUploadOptions(collected);
-	await buildAndPost(cwd, collected, options.forceBuild);
-}
 /** Ensure, create, and stream the build directory. */
-async function buildAndPost(cwd, collected, force) {
+async function buildAndPost(cwd, collected, force, dryRun) {
 	await ensureBuildDir({
 		cwd,
 		buildDir: collected.buildDir,
@@ -95,6 +126,11 @@ async function buildAndPost(cwd, collected, force) {
 		buildScriptName: collected.buildScriptName,
 		force
 	});
+	await assertBuildOutput(cwd, collected.buildDir);
+	if (dryRun) {
+		printLine(`Dry run: would upload ${collected.buildDir} as ${collected.sha} on ${collected.branch}`);
+		return;
+	}
 	const client = createClient(collected.url, collected.token);
 	const created = await client.projects.builds.createJson(collected.slug, {
 		gitSha: collected.sha,
@@ -102,11 +138,54 @@ async function buildAndPost(cwd, collected, force) {
 		message: collected.message,
 		authorEmail: collected.authorEmail,
 		authorName: collected.authorName,
+		affectedOnly: collected.affectedOnly,
 		labels: parseLabels(collected.label)
 	});
-	await putZipStream(client, created, cwd, collected.buildDir);
+	await reportAffectedCapture(client, created, cwd, collected);
+	if (!await tryDedupUpload(client, created, cwd, collected.buildDir)) await putZipStream(client, created, cwd, collected.buildDir);
 	printLine(`Build created: ${created.build.id}`);
 }
+/** Compute the affected set and post it, never failing the upload. */
+async function reportAffectedCapture(client, created, cwd, collected) {
+	if (!collected.affectedOnly) {
+		printLine("Full capture (--full): rendering all stories");
+		return;
+	}
+	if (!created.baselineSha) {
+		printLine("Full capture (no baseline build yet): rendering all stories");
+		return;
+	}
+	try {
+		const result = await computeAffected({
+			cwd,
+			buildDir: collected.buildDir,
+			baseSha: created.baselineSha,
+			headSha: collected.sha,
+			untraced: collected.untraced,
+			statsFile: collected.statsFile
+		});
+		await client.projects.builds.postAffected(collected.slug, created.build.id, {
+			baselineSha: result.baselineSha,
+			changedFiles: result.changedFiles,
+			affectedImportPaths: result.affectedImportPaths
+		});
+		printLine(describeAffected(result, created.baselineSha));
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		printLine(`Full capture (affected post failed: ${reason}): rendering all stories`);
+	}
+}
+/** Human-readable summary of an affected computation. */
+function describeAffected(result, baselineSha) {
+	if (result.affectedImportPaths === null) return `Full capture (${result.fullReason ?? "unknown reason"}): rendering all stories`;
+	const count = result.affectedImportPaths.length;
+	const short = baselineSha.slice(0, 7);
+	if (count === 0) return `Affected capture: no stories affected (baseline ${short})`;
+	return `Affected capture: rendering ${count} ${count === 1 ? "story" : "stories"} (baseline ${short})`;
+}
+async function tryDedupUpload(_client, _created, _cwd, _buildDir) {
+	return false;
+}
 /** PUT the streamed zip, then report the created build id. */
 async function putZipStream(client, created, cwd, buildDir) {
 	const spinner = createSpinner("Uploading...", spinnerFrames);
@@ -118,28 +197,5 @@ async function putZipStream(client, created, cwd, buildDir) {
 		throw error;
 	}
 }
-async function ensureBuildDir(opts) {
-	if (opts.buildCommand && opts.buildScriptName) throw new Error("buildCommand and buildScriptName are mutually exclusive");
-	const full = resolve(opts.cwd, opts.buildDir);
-	if (!(opts.force ?? await needsBuild(full))) return;
-	const command = opts.buildCommand ?? `npm run ${opts.buildScriptName ?? "build-storybook"} -- --output-dir ${opts.buildDir}`;
-	printLine(`Building Storybook: ${command}`);
-	execSync(command, {
-		stdio: "inherit",
-		env: {
-			...process.env,
-			STORYBOOK_BUILD_STORIES_JSON: "true"
-		}
-	});
-}
-/** True when the build directory is missing or empty. */
-async function needsBuild(full) {
-	try {
-		await access(full);
-		return (await readdir(full)).length === 0;
-	} catch {
-		return true;
-	}
-}
 //#endregion
-export { runUpload };
+export { resolveIdentity, runUpload };

package/dist/commands/whoami.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { printLine } from "../output.js";
+import { createClient } from "../client.js";
+import { resolveConnection } from "./connection.js";
+//#region src/commands/whoami.ts
+/**
+* Verify the token against the server and print the project it can read.
+*
+* @param options - Connection options (url/slug/token via flags, config, or env).
+*/
+async function runWhoami(options) {
+	const { url, slug, token } = await resolveConnection(options);
+	const project = await createClient(url, token).projects.get(slug);
+	const name = typeof project.name === "string" && project.name.length > 0 ? project.name : slug;
+	printLine(`Server: ${url}`);
+	printLine(`Project: ${name} (${slug})`);
+}
+//#endregion
+export { runWhoami };

package/dist/commands/worker/init.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { detectPackageRunner, installCommand } from "../../config.js";
+import { printError, printLine } from "../../output.js";
+import { detectInstalledAdapters } from "../shared/detect-adapters.js";
+import { generateDockerignore, generateWorkerDockerfile } from "../server/docker.js";
+import { PROJECT_PROMPTS, WORKER_INFRA_PROMPTS } from "../server/prompts.js";
+import { join, resolve } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import prompts from "prompts";
+//#region src/commands/worker/init.ts
+const DB_PACKAGE = {
+	sqlite: "@storyshelf/db-sqlite",
+	turso: "@storyshelf/db-sqlite",
+	"better-sqlite3": "@storyshelf/db-sqlite",
+	"bun-sqlite": "@storyshelf/db-sqlite",
+	d1: "@storyshelf/db-sqlite",
+	postgres: "@storyshelf/db-postgres",
+	pg: "@storyshelf/db-postgres",
+	neon: "@storyshelf/db-postgres",
+	"neon-http": "@storyshelf/db-postgres",
+	vercel: "@storyshelf/db-postgres",
+	pglite: "@storyshelf/db-postgres",
+	mysql: "@storyshelf/db-mysql",
+	planetscale: "@storyshelf/db-mysql",
+	tidb: "@storyshelf/db-mysql"
+};
+const STORAGE_PACKAGE = {
+	local: "@storyshelf/storage-local",
+	s3: "@storyshelf/storage-s3",
+	azure: "@storyshelf/storage-azure",
+	gcs: "@storyshelf/storage-gcs"
+};
+const QUEUE_PACKAGE = {
+	sqs: "@storyshelf/queue-sqs",
+	"azure-storage-queues": "@storyshelf/queue-azure",
+	"azure-service-bus": "@storyshelf/queue-azure",
+	"gcp-pubsub": "@storyshelf/queue-gcp",
+	memory: null
+};
+/** Azure SDK pins (must match @storyshelf/queue-azure peerDependencies). */
+const AZURE_STORAGE_QUEUE_SDK = "^12.31.0";
+const AZURE_SERVICE_BUS_SDK = "^7.9.5";
+/** Pub/Sub SDK pin (must match @storyshelf/queue-gcp peerDependencies). */
+const GCP_PUBSUB_SDK = "^6.1.0";
+/** DB peer SDK pins (must match db-* peerDependencies). */
+const LIBSQL_CLIENT_SDK = "^0.15.0";
+const BETTER_SQLITE3_SDK = "^12.0.0";
+const PG_SDK = "^8.0.0";
+const NEON_SDK = "^1.1.0";
+const VERCEL_POSTGRES_SDK = "^0.10.0";
+const PGLITE_SDK = "^0.5.8";
+const MYSQL2_SDK = "^3.9.0";
+const PLANETSCALE_SDK = "^1.19.0";
+const TIDBCLOUD_SDK = "^0.1.0";
+const DB_IMPORT = {
+	sqlite: `import { createSqliteDatabase } from "@storyshelf/db-sqlite";`,
+	turso: `import { createTursoDatabase } from "@storyshelf/db-sqlite/turso";`,
+	"better-sqlite3": `import { createBetterSqlite3Database } from "@storyshelf/db-sqlite/better-sqlite3";`,
+	"bun-sqlite": `import { createBunSqliteDatabase } from "@storyshelf/db-sqlite/bun-sqlite";`,
+	d1: `import { createD1Database } from "@storyshelf/db-sqlite/d1";`,
+	postgres: `import { createPostgresDatabase } from "@storyshelf/db-postgres";`,
+	pg: `import { createPgDatabase } from "@storyshelf/db-postgres/pg";`,
+	neon: `import { createNeonDatabase } from "@storyshelf/db-postgres/neon";`,
+	"neon-http": `import { createNeonHttpDatabase } from "@storyshelf/db-postgres/neon-http";`,
+	vercel: `import { createVercelDatabase } from "@storyshelf/db-postgres/vercel";`,
+	pglite: `import { createPgliteDatabase } from "@storyshelf/db-postgres/pglite";`,
+	mysql: `import { createMysqlDatabase } from "@storyshelf/db-mysql";`,
+	planetscale: `import { createPlanetscaleDatabase } from "@storyshelf/db-mysql/planetscale";`,
+	tidb: `import { createTidbDatabase } from "@storyshelf/db-mysql/tidb";`
+};
+const STORAGE_IMPORT = {
+	local: `import { createLocalStorage } from "@storyshelf/storage-local";`,
+	s3: `import { createS3Storage } from "@storyshelf/storage-s3";`,
+	azure: `import { createAzureStorage } from "@storyshelf/storage-azure";`,
+	gcs: `import { createGcsStorage } from "@storyshelf/storage-gcs";`
+};
+const DB_INIT = {
+	sqlite: `createSqliteDatabase(\`\${dataDir}/shelf.db\`)`,
+	turso: `createTursoDatabase({ url: process.env.TURSO_DATABASE_URL!, authToken: process.env.TURSO_AUTH_TOKEN })`,
+	"better-sqlite3": `createBetterSqlite3Database({ path: \`\${dataDir}/shelf.db\` })`,
+	"bun-sqlite": `createBunSqliteDatabase({ path: \`\${dataDir}/shelf.db\` })`,
+	d1: `createD1Database({ client: getD1Binding() })`,
+	postgres: `createPostgresDatabase({ url: process.env.DATABASE_URL! })`,
+	pg: `createPgDatabase({ url: process.env.DATABASE_URL! })`,
+	neon: `createNeonDatabase({ url: process.env.DATABASE_URL! })`,
+	"neon-http": `createNeonHttpDatabase({ url: process.env.DATABASE_URL! })`,
+	vercel: `createVercelDatabase()`,
+	pglite: `createPgliteDatabase()`,
+	mysql: `createMysqlDatabase({ url: process.env.DATABASE_URL! })`,
+	planetscale: `createPlanetscaleDatabase({ url: process.env.DATABASE_URL! })`,
+	tidb: `createTidbDatabase({ url: process.env.DATABASE_URL! })`
+};
+/** Extra scaffolding before `const database = ...` (D1 binding stub). */
+function dbPrelude(database) {
+	if (database !== "d1") return [];
+	return [
+		`// TODO: provide your D1 binding (Cloudflare Workers: env.DB).`,
+		`function getD1Binding(): never {`,
+		`  throw new Error("Provide your D1 database binding (env.DB).");`,
+		`}`
+	];
+}
+const STORAGE_INIT = {
+	local: `createLocalStorage(dataDir)`,
+	s3: `createS3Storage({ bucket: process.env.S3_BUCKET!, region: process.env.AWS_REGION })`,
+	azure: `createAzureStorage({ container: "storybook", connectionString: process.env.AZURE_STORAGE_CONNECTION! })`,
+	gcs: `createGcsStorage({ bucket: process.env.GCS_BUCKET! })`
+};
+function workerQueueImport(queue) {
+	if (queue === "azure-storage-queues") return `import { createAzureStorageQueuesQueue } from "@storyshelf/queue-azure/storage-queues";`;
+	if (queue === "azure-service-bus") return `import { createAzureServiceBusQueue } from "@storyshelf/queue-azure/service-bus";`;
+	if (queue === "gcp-pubsub") return `import { createGcpPubSubQueue } from "@storyshelf/queue-gcp";`;
+	if (queue === "sqs") return `import { createSqsCaptureQueue } from "@storyshelf/queue-sqs";`;
+	return `// In-memory queue is server-side only; worker uses a remote queue.`;
+}
+function workerQueueInit(queue) {
+	if (queue === "azure-storage-queues") return `const queue = createAzureStorageQueuesQueue({ queueName: "capture-jobs", connectionString: process.env.AZURE_STORAGE_CONNECTION! });`;
+	if (queue === "azure-service-bus") return `const queue = createAzureServiceBusQueue({ queueName: "capture-jobs", connectionString: process.env.AZURE_SERVICE_BUS_CONNECTION! });`;
+	if (queue === "gcp-pubsub") return `const queue = createGcpPubSubQueue({ topic: "capture-jobs", subscription: "capture-jobs-worker", projectId: process.env.GOOGLE_CLOUD_PROJECT! });`;
+	if (queue === "sqs") return `const queue = createSqsCaptureQueue({ queueUrl: process.env.QUEUE_URL! });`;
+	return `const queue = null as unknown as never; // replace with a remote queue`;
+}
+function generateWorker(answers) {
+	const queueLine = workerQueueImport(answers.queue);
+	const queueInit = workerQueueInit(answers.queue);
+	return [
+		queueLine,
+		`import { createCaptureWorker } from "@storyshelf/worker";`,
+		`import { createPlaywrightCaptureRunner } from "@storyshelf/runner-playwright";`,
+		DB_IMPORT[answers.database],
+		STORAGE_IMPORT[answers.storage],
+		``,
+		`const dataDir = process.env.DATA_DIR || "./data";`,
+		...dbPrelude(answers.database),
+		`const database = ${DB_INIT[answers.database]};`,
+		`const storage = ${STORAGE_INIT[answers.storage]};`,
+		queueInit,
+		`const runner = createPlaywrightCaptureRunner();`,
+		``,
+		`const worker = createCaptureWorker({`,
+		`  queue,`,
+		`  db: database,`,
+		`  storage,`,
+		`  runner,`,
+		`  scratchDir: dataDir,`,
+		`  config: { concurrency: Number(process.env.WORKER_CONCURRENCY) || 2 },`,
+		`});`,
+		``,
+		`await worker.start();`,
+		``,
+		`const shutdown = async () => { await worker.stop(); };`,
+		`process.on("SIGTERM", () => { shutdown().catch(() => {}); });`,
+		`process.on("SIGINT", () => { shutdown().catch(() => {}); });`,
+		``
+	].join("\n");
+}
+function buildDeps(answers) {
+	const deps = {
+		"@storyshelf/core": "0.5.3",
+		"@storyshelf/worker": "0.5.3",
+		"@storyshelf/runner-playwright": "0.5.3",
+		[DB_PACKAGE[answers.database]]: "0.5.3"
+	};
+	if (answers.database === "turso") deps["@libsql/client"] = LIBSQL_CLIENT_SDK;
+	if (answers.database === "better-sqlite3") deps["better-sqlite3"] = BETTER_SQLITE3_SDK;
+	if (answers.database === "pg") deps["pg"] = PG_SDK;
+	if (answers.database === "neon" || answers.database === "neon-http") deps["@neondatabase/serverless"] = NEON_SDK;
+	if (answers.database === "vercel") deps["@vercel/postgres"] = VERCEL_POSTGRES_SDK;
+	if (answers.database === "pglite") deps["@electric-sql/pglite"] = PGLITE_SDK;
+	if (answers.database === "mysql") deps["mysql2"] = MYSQL2_SDK;
+	if (answers.database === "planetscale") deps["@planetscale/database"] = PLANETSCALE_SDK;
+	if (answers.database === "tidb") deps["@tidbcloud/serverless"] = TIDBCLOUD_SDK;
+	if (answers.storage !== "local") deps[STORAGE_PACKAGE[answers.storage]] = "0.5.3";
+	const qp = QUEUE_PACKAGE[answers.queue];
+	if (qp) deps[qp] = "0.5.3";
+	if (answers.queue === "azure-storage-queues") deps["@azure/storage-queue"] = AZURE_STORAGE_QUEUE_SDK;
+	if (answers.queue === "azure-service-bus") deps["@azure/service-bus"] = AZURE_SERVICE_BUS_SDK;
+	if (answers.queue === "gcp-pubsub") deps["@google-cloud/pubsub"] = GCP_PUBSUB_SDK;
+	return deps;
+}
+function generatePackageJson(answers) {
+	const pkg = {
+		name: answers.name,
+		version: "0.1.0",
+		type: "module",
+		private: true,
+		description: "StoryShelf capture worker (remote queue).",
+		scripts: {
+			start: "node --experimental-transform-types worker.ts",
+			dev: "node --experimental-transform-types --watch worker.ts"
+		},
+		dependencies: buildDeps(answers),
+		devDependencies: { typescript: "^7.0.2" }
+	};
+	return JSON.stringify(pkg, null, 2);
+}
+async function writeFiles(outDir, answers) {
+	await writeFile(join(outDir, "worker.ts"), generateWorker(answers));
+	printLine(`Created worker.ts`);
+	await writeFile(join(outDir, "package.json"), generatePackageJson(answers));
+	printLine(`Created package.json`);
+	if (answers.docker) {
+		await writeFile(join(outDir, "Dockerfile"), generateWorkerDockerfile());
+		await writeFile(join(outDir, ".dockerignore"), generateDockerignore());
+		printLine(`Created Dockerfile, .dockerignore`);
+	}
+}
+function printNextSteps(answers, runner) {
+	printLine(`\nScaffolded ${answers.name} in ${resolve(answers.dir)}`);
+	printLine(`\nNext steps:`);
+	printLine(`  cd ${answers.dir}`);
+	if (answers.docker) {
+		printLine(`  docker build -t storyshelf-worker .`);
+		printLine(`  docker run --env-file .env storyshelf-worker`);
+	} else {
+		printLine(`  ${installCommand(runner)}`);
+		printLine(`  npx storyshelf worker serve --dir .`);
+	}
+}
+function promptInitial(choices, value) {
+	if (value === void 0 || value === "") return void 0;
+	const idx = choices.findIndex((c) => c.value === value);
+	if (idx === -1) return void 0;
+	return idx;
+}
+async function runWorkerInit(_options) {
+	const cwdPkg = detectInstalledAdapters(process.cwd());
+	const infraWithInitial = WORKER_INFRA_PROMPTS.map((prompt) => {
+		if (prompt.type !== "select") return prompt;
+		const detected = cwdPkg[prompt.name];
+		const initial = promptInitial(prompt.choices, detected);
+		if (initial !== void 0) return {
+			...prompt,
+			initial
+		};
+		return prompt;
+	});
+	const responses = await prompts([...PROJECT_PROMPTS, ...infraWithInitial]);
+	if (!responses["name"] || !responses["dir"]) {
+		printError("Cancelled.");
+		return;
+	}
+	const answers = responses;
+	if (!answers.queue) answers.queue = "sqs";
+	const outDir = resolve(answers.dir);
+	await mkdir(outDir, { recursive: true });
+	await writeFiles(outDir, answers);
+	printNextSteps(answers, await detectPackageRunner(process.cwd()));
+}
+//#endregion
+export { runWorkerInit };

package/dist/commands/worker/serve.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { detectPackageRunner, installCommand } from "../../config.js";
+import { printLine } from "../../output.js";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+//#region src/commands/worker/serve.ts
+const WORKER_CANDIDATES = [
+	"worker.ts",
+	"worker.js",
+	"worker.mjs",
+	"index.ts",
+	"index.js",
+	"index.mjs"
+];
+async function resolveWorkerFile(dir) {
+	for (const candidate of WORKER_CANDIDATES) {
+		const full = join(dir, candidate);
+		try {
+			await access(full);
+			return full;
+		} catch {
+			continue;
+		}
+	}
+	throw new Error(`No worker entry found in ${dir} (looked for ${WORKER_CANDIDATES.join(", ")}). Run "storyshelf worker init" first.`);
+}
+function nodeArgs(file) {
+	return file.endsWith(".ts") ? ["--experimental-transform-types", file] : [file];
+}
+function relaySignals(child) {
+	let relayed = false;
+	const relay = (signal) => {
+		relayed = true;
+		child.kill(signal);
+	};
+	const onSigint = () => {
+		relay("SIGINT");
+	};
+	const onSigterm = () => {
+		relay("SIGTERM");
+	};
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+	return {
+		stop: () => {
+			process.off("SIGINT", onSigint);
+			process.off("SIGTERM", onSigterm);
+		},
+		relayed: () => relayed
+	};
+}
+function waitForExit(child, relay) {
+	return new Promise((resolvePromise, rejectPromise) => {
+		child.on("error", rejectPromise);
+		child.on("exit", (code, signal) => {
+			if (signal && relay.relayed()) resolvePromise(0);
+			else resolvePromise(code ?? 1);
+		});
+	});
+}
+async function defaultSpawnProcess(command, args, options) {
+	const child = spawn(command, [...args], {
+		stdio: "inherit",
+		cwd: options.cwd,
+		env: options.env
+	});
+	const relay = relaySignals(child);
+	try {
+		return await waitForExit(child, relay);
+	} finally {
+		relay.stop();
+	}
+}
+async function warnIfUninstalled(dir) {
+	try {
+		await access(join(dir, "node_modules"));
+	} catch {
+		const runner = await detectPackageRunner(dir);
+		printLine(`Warning: no node_modules in ${dir} — run "${installCommand(runner)}" there first if the worker fails to start.`);
+	}
+}
+async function runWorkerServe(options, deps = {}) {
+	const dir = resolve(options.dir ?? process.cwd());
+	const file = await resolveWorkerFile(dir);
+	await warnIfUninstalled(dir);
+	printLine(`Starting worker: ${file}`);
+	const code = await (deps.spawnProcess ?? defaultSpawnProcess)(process.execPath, nodeArgs(file), {
+		cwd: dir,
+		env: childEnv(options)
+	});
+	if (code !== 0) throw new Error(`Worker exited with code ${code}`);
+}
+function childEnv(options) {
+	const env = { ...process.env };
+	if (options.port !== void 0) env["PORT"] = options.port;
+	if (options.queueUrl !== void 0) env["QUEUE_URL"] = options.queueUrl;
+	if (options.concurrency !== void 0) env["WORKER_CONCURRENCY"] = options.concurrency;
+	return env;
+}
+//#endregion
+export { resolveWorkerFile, runWorkerServe };