storyshelf 0.6.2 → 0.8.0

package/README.md

@@ -82,6 +82,13 @@ storyshelf purge --url <url> [--token <admin-token>]
 storyshelf retry --url <url> --slug <slug> --build-id <id> [--token <token>]
 ```
 
+`storyshelf protect` — print, validate and (only with `--apply`) write the branch rule that requires StoryShelf's gate status. Dry run by default; needs an admin token for the git host (`--token`, `GITHUB_TOKEN` or `GITLAB_TOKEN`), and talks to the host directly, not to the StoryShelf server. Exits `1` when the rule is missing the check and nothing was written.
+
+```sh
+storyshelf protect --provider github --repo <owner/repo> [--branch main] [--prefix storyshelf] [--gate testing|review] [--apply]
+storyshelf protect --provider gitlab --repo <group/project> [--host <url>] [--apply]
+```
+
 ### Example CI snippet
 
 ```yaml

package/dist/client.js

@@ -2,7 +2,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/client.ts
+// src/client.ts
 /**
 * Create a typed API client for a StoryShelf server.
 *
@@ -18,6 +18,15 @@ function createClient(baseUrl, token) {
 	const requestHeaders = (contentType) => buildRequestHeaders(authHeaders, contentType);
 	return { projects: createProjectsApi(baseUrl, authHeaders, requestHeaders) };
 }
+/** A non-2xx answer from the server; `status` is the HTTP status. */
+var RequestError = class extends Error {
+	name = "RequestError";
+	status;
+	constructor(status, body) {
+		super(`Request failed (${status}): ${body}`);
+		this.status = status;
+	}
+};
 function buildAuthHeaders(token) {
 	return token ? { Authorization: `Bearer ${token}` } : {};
 }
@@ -28,7 +37,7 @@ function buildRequestHeaders(authHeaders, contentType) {
 }
 async function fetchJson(url, options) {
 	const res = await fetch(url, options);
-	if (!res.ok) throw new Error(`Request failed (${res.status}): ${await res.text()}`);
+	if (!res.ok) throw new RequestError(res.status, await res.text());
 	return res.json();
 }
 function createTokensApi(baseUrl, requestHeaders) {
@@ -38,8 +47,35 @@ function createTokensApi(baseUrl, requestHeaders) {
 		body: JSON.stringify(json)
 	}) };
 }
+/** The three calls of a file-by-file upload. */
+function createFileUploadApi(baseUrl, requestHeaders) {
+	return {
+		dedup: async (slug, buildId, hashes) => {
+			return (await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds/${buildId}/dedup`, {
+				method: "POST",
+				headers: requestHeaders("application/json"),
+				body: JSON.stringify({ hashes })
+			})).needed;
+		},
+		uploadContent: async (slug, buildId, files) => {
+			const form = new FormData();
+			for (const file of files) form.set(file.hash, new File([new Uint8Array(file.data)], file.hash));
+			return await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds/${buildId}/content`, {
+				method: "POST",
+				headers: requestHeaders(),
+				body: form
+			});
+		},
+		postManifest: async (slug, buildId, files) => await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds/${buildId}/manifest`, {
+			method: "POST",
+			headers: requestHeaders("application/json"),
+			body: JSON.stringify({ files })
+		})
+	};
+}
 function createBuildsApi(baseUrl, authHeaders, requestHeaders) {
 	return {
+		...createFileUploadApi(baseUrl, requestHeaders),
 		createJson: async (slug, json) => await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds`, {
 			method: "POST",
 			headers: requestHeaders("application/json"),
@@ -56,7 +92,7 @@ function createBuildsApi(baseUrl, authHeaders, requestHeaders) {
 				duplex: "half"
 			};
 			const res = await fetch(`${baseUrl}${uploadUrl}`, init);
-			if (!res.ok) throw new Error(`Request failed (${res.status}): ${await res.text()}`);
+			if (!res.ok) throw new RequestError(res.status, await res.text());
 			return res.json();
 		},
 		retry: async (slug, buildId) => await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds/${buildId}/retry`, {
@@ -64,6 +100,11 @@ function createBuildsApi(baseUrl, authHeaders, requestHeaders) {
 			headers: requestHeaders("application/json"),
 			body: JSON.stringify({})
 		}),
+		postUsage: async (slug, buildId, usage) => await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds/${buildId}/usage`, {
+			method: "POST",
+			headers: requestHeaders("application/json"),
+			body: JSON.stringify({ usage })
+		}),
 		postAffected: async (slug, buildId, json) => await fetchJson(`${baseUrl}/api/v1/projects/${slug}/builds/${buildId}/affected`, {
 			method: "POST",
 			headers: requestHeaders("application/json"),
@@ -97,5 +138,4 @@ function createProjectsApi(baseUrl, authHeaders, requestHeaders) {
 		admin: createAdminApi(baseUrl, requestHeaders)
 	};
 }
-//#endregion
-export { createClient };
+export { RequestError, createClient };

package/dist/commands/build.js

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
-import "node:path";
+import { resolve } from "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
+// src/commands/build.ts
 /**
 * Build a Storybook directory without uploading, using the same
 * buildDir/buildCommand/buildScriptName resolution as `upload`.
@@ -27,5 +26,4 @@ async function runBuild(options) {
 	await assertBuildOutput(cwd, buildDir);
 	printLine(`Build ready: ${resolve(cwd, buildDir)}`);
 }
-//#endregion
 export { runBuild };

package/dist/commands/connection.js

@@ -3,7 +3,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { loadStorybookConfig } from "../config.js";
-//#region src/commands/connection.ts
+// src/commands/connection.ts
 /**
 * Resolve url/slug/token as flags > config file > env, throwing on the first
 * missing value (same messages as `upload`).
@@ -25,5 +25,4 @@ function assertConnectionFields(fields) {
 	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

@@ -5,7 +5,7 @@ import.meta.url;
 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
+// src/commands/create.ts
 async function readCreateInputs(options, cwd) {
 	const name = (options.name === "" ? void 0 : options.name) ?? await detectPackageName(cwd);
 	return {
@@ -61,5 +61,4 @@ async function runCreate(options) {
 	}
 	await executeCreate(inputs.url, inputs.token, buildCreatePayload(inputs.name, inputs), cwd);
 }
-//#endregion
 export { runCreate };

package/dist/commands/dedup.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { join, relative, resolve } from "node:path";
+import "node:url";
+import.meta.url;
+import { readFile, readdir, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+// src/commands/dedup.ts
+async function walkFiles(cwd, buildDir) {
+	const root = resolve(cwd, buildDir);
+	const files = [];
+	async function walk(dir) {
+		const entries = await readdir(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) await walk(full);
+			else files.push(relative(root, full));
+		}
+	}
+	await walk(root);
+	return files;
+}
+async function hashFiles(cwd, buildDir, files) {
+	const root = resolve(cwd, buildDir);
+	const results = [];
+	for (const rel of files) {
+		const full = join(root, rel);
+		const buffer = await readFile(full);
+		const hash = createHash("sha256").update(buffer).digest("hex");
+		const { size } = await stat(full);
+		results.push({
+			rel,
+			hash,
+			size
+		});
+	}
+	return results;
+}
+export { hashFiles, walkFiles };

package/dist/commands/default.js

@@ -5,7 +5,7 @@ import.meta.url;
 import { loadStorybookConfig } from "../config.js";
 import { printError } from "../output.js";
 import { runUpload } from "./upload.js";
-//#region src/commands/default.ts
+// src/commands/default.ts
 /** Print an error and mark the process as failed. */
 function handleError(error) {
 	printError(error instanceof Error ? error.message : String(error));
@@ -46,5 +46,4 @@ async function runDefaultCommand(program) {
 	}
 	await runUpload(options).catch(handleError);
 }
-//#endregion
 export { handleError, runDefaultCommand };

package/dist/commands/doctor.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import "node:path";
+import { resolve } from "node:path";
 import "node:url";
 import.meta.url;
 import { findStorybookMain, loadStorybookConfig } from "../config.js";
@@ -8,9 +8,8 @@ import { needsBuild, resolveBuildCommand } from "./storybook-build.js";
 import { createClient } from "../client.js";
 import { resolveConnection } from "./connection.js";
 import { access, readdir } from "node:fs/promises";
-import { resolve } from "node:path";
 import { gitRepoStatus } from "@storyshelf/affected";
-//#region src/commands/doctor.ts
+// src/commands/doctor.ts
 function mark(status) {
 	if (status === "pass") return "✓";
 	return status === "warn" ? "!" : "✗";
@@ -146,5 +145,4 @@ 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/file-by-file.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { join, resolve } from "node:path";
+import "node:url";
+import.meta.url;
+import { RequestError } from "../client.js";
+import { hashFiles, walkFiles } from "./dedup.js";
+import { readFile } from "node:fs/promises";
+// src/commands/file-by-file.ts
+/**
+* File-by-file upload (`/dedup`, `/content`, `/manifest`): stores a build's files content-addressed
+* and needs no zip extraction on the server, so it publishes on any host, serverless included.
+* `upload` falls back to it when the server refuses a zip over its inline limit.
+*/
+/** Files sent in one `/content` request. */
+const BATCH_FILES = 50;
+/** Bytes sent in one `/content` request (a single larger file goes alone). */
+const BATCH_BYTES = 16777216;
+/** Hashes asked about in one `/dedup` request. */
+const DEDUP_CHUNK = 5e3;
+/** What the server answers a zip it cannot extract inline and cannot hand to a job. */
+function isOverInlineLimit(error) {
+	return error instanceof RequestError && error.status === 413 && error.message.includes("/dedup");
+}
+/** Upload every file of the build directory the server lacks, then post the manifest. */
+async function uploadFileByFile(client, target, log) {
+	const files = await hashFiles(target.cwd, target.buildDir, await walkFiles(target.cwd, target.buildDir));
+	const toSend = firstFileOfEach(files, await neededHashes(client, target, files));
+	log(`Uploading ${toSend.length} of ${files.length} files (the server has the rest)`);
+	for (const batch of batches(toSend)) await sendBatch(client, target, batch);
+	await client.projects.builds.postManifest(target.slug, target.buildId, files);
+}
+async function neededHashes(client, target, files) {
+	const unique = [...new Set(files.map((file) => file.hash))];
+	const needed = /* @__PURE__ */ new Set();
+	for (let at = 0; at < unique.length; at += DEDUP_CHUNK) {
+		const answer = await client.projects.builds.dedup(target.slug, target.buildId, unique.slice(at, at + DEDUP_CHUNK));
+		for (const hash of answer) needed.add(hash);
+	}
+	return needed;
+}
+/** One file per needed hash (identical files are sent once). */
+function firstFileOfEach(files, needed) {
+	const seen = /* @__PURE__ */ new Set();
+	return files.filter((file) => {
+		if (!needed.has(file.hash) || seen.has(file.hash)) return false;
+		seen.add(file.hash);
+		return true;
+	});
+}
+/** Split into requests of at most {@link BATCH_FILES} files and {@link BATCH_BYTES} bytes (one big file goes alone). */
+function batches(files) {
+	const out = [];
+	for (const file of files) {
+		const last = out.at(-1);
+		if (last && fitsBatch(last, file)) last.push(file);
+		else out.push([file]);
+	}
+	return out;
+}
+function fitsBatch(batch, file) {
+	const bytes = batch.reduce((sum, member) => sum + member.size, 0);
+	return batch.length < BATCH_FILES && bytes + file.size <= BATCH_BYTES;
+}
+async function sendBatch(client, target, batch) {
+	const root = resolve(target.cwd, target.buildDir);
+	const files = await Promise.all(batch.map(async (file) => ({
+		hash: file.hash,
+		data: await readFile(join(root, file.rel))
+	})));
+	await client.projects.builds.uploadContent(target.slug, target.buildId, files);
+}
+export { isOverInlineLimit, uploadFileByFile };

package/dist/commands/init.js

@@ -6,7 +6,7 @@ import { assertStorybookMain, detectStorybookMeta, loadStorybookConfig, writeSto
 import { printError, printLine } from "../output.js";
 import { createClient } from "../client.js";
 import prompts from "prompts";
-//#region src/commands/init.ts
+// src/commands/init.ts
 /** Human description of the detected Storybook (framework, addons, path). */
 function describeMeta(meta) {
 	const hintParts = [];
@@ -193,5 +193,4 @@ async function runInit(options) {
 	if (!answers) return;
 	await finalizeInit(answers, cwd, options);
 }
-//#endregion
 export { runInit };

package/dist/commands/mcp/init.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { join, resolve } from "node:path";
+import "node:url";
+import.meta.url;
+import { detectPackageRunner, installCommand } from "../../config.js";
+import { printError, printLine } from "../../output.js";
+import { PROJECT_PROMPTS } from "../server/prompts.js";
+import { SCAFFOLD_DEV_DEPENDENCIES, generateTsconfig, writeScaffoldFile } from "../shared/scaffold.js";
+import { MCP_ENTRY, generateMcpClientConfig, generateMcpDockerfile, generateMcpEntry, generateMcpEnvExample, generateMcpPackageJson } from "./scaffold.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import prompts from "prompts";
+// src/commands/mcp/init.ts
+const MCP_PROMPTS = [
+	{
+		type: "select",
+		name: "transport",
+		message: "How will agents connect?",
+		choices: [{
+			title: "stdio (local agents: Claude Code, Cursor)",
+			value: "stdio"
+		}, {
+			title: "HTTP (remote or shared agents)",
+			value: "http"
+		}]
+	},
+	{
+		type: "text",
+		name: "url",
+		message: "StoryShelf server URL?",
+		initial: process.env["STORYSHELF_URL"] ?? "https://shelf.example.com"
+	},
+	{
+		type: "text",
+		name: "slug",
+		message: "Default project slug?",
+		initial: process.env["STORYSHELF_SLUG"] ?? ""
+	},
+	{
+		type: "confirm",
+		name: "docker",
+		message: "Add a Dockerfile (HTTP transport)?",
+		initial: false
+	}
+];
+/** Scaffold a StoryShelf MCP server project (`storyshelf mcp init`). */
+async function runMcpInit(options) {
+	const responses = await prompts([...PROJECT_PROMPTS, ...MCP_PROMPTS]);
+	if (!responses.name || !responses.dir) {
+		printError("Cancelled.");
+		return;
+	}
+	const answers = {
+		...responses,
+		dir: options.dir ?? responses.dir
+	};
+	const outDir = resolve(answers.dir);
+	await mkdir(outDir, { recursive: true });
+	await writeFiles(outDir, answers);
+	const runner = await detectPackageRunner(process.cwd());
+	printNextSteps(answers, outDir, installCommand(runner));
+}
+async function writeFiles(outDir, answers) {
+	await writeScaffoldFile(outDir, MCP_ENTRY, generateMcpEntry(answers.transport));
+	await writeFile(join(outDir, "package.json"), generateMcpPackageJson(answers, SCAFFOLD_DEV_DEPENDENCIES));
+	await writeFile(join(outDir, "tsconfig.json"), generateTsconfig());
+	await writeFile(join(outDir, ".env.example"), generateMcpEnvExample(answers));
+	await writeFile(join(outDir, ".mcp.json"), `${generateMcpClientConfig(answers)}\n`);
+	printLine(`Created ${MCP_ENTRY}, package.json, tsconfig.json, .env.example, .mcp.json`);
+	if (answers.docker) {
+		await writeFile(join(outDir, "Dockerfile"), generateMcpDockerfile());
+		printLine(`Created Dockerfile`);
+	}
+}
+function printNextSteps(answers, outDir, install) {
+	printLine(`\nScaffolded ${answers.name} in ${outDir}`);
+	printLine(`\nNext steps:`);
+	printLine(`  cd ${answers.dir}`);
+	printLine(`  ${install}`);
+	printLine(`  cp .env.example .env   # add STORYSHELF_TOKEN (never commit it)`);
+	printLine(`  npx storyshelf mcp serve --dir .`);
+	printLine(`\n.mcp.json is a ready client config for Claude Code (copy to your repo root).`);
+}
+export { runMcpInit };

package/dist/commands/mcp/scaffold.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/commands/mcp/scaffold.ts
+/** Entry file of a scaffolded MCP project. */
+const MCP_ENTRY = "src/index.ts";
+/** `src/index.ts`: stdio runs the package bin on import; http mounts the handler on `/mcp`. */
+function generateMcpEntry(transport) {
+	if (transport === "stdio") return [
+		`// Serves MCP over stdio. Configuration comes from STORYSHELF_URL / STORYSHELF_TOKEN / STORYSHELF_SLUG.`,
+		`import "@storyshelf/mcp";`,
+		``
+	].join("\n");
+	return [
+		`import { serveHttp } from "@storyshelf/mcp/http";`,
+		``,
+		`// Each MCP client sends its own "Authorization: Bearer <StoryShelf token>"; it is forwarded to /api/v1.`,
+		`await serveHttp({`,
+		`  url: process.env.STORYSHELF_URL!,`,
+		`  slug: process.env.STORYSHELF_SLUG,`,
+		`  port: Number(process.env.PORT) || 3333,`,
+		`  host: process.env.HOST || "127.0.0.1",`,
+		`});`,
+		`console.error("storyshelf-mcp listening on /mcp");`,
+		``
+	].join("\n");
+}
+/** `package.json` of the scaffolded project. */
+function generateMcpPackageJson(answers, devDependencies) {
+	return JSON.stringify({
+		name: answers.name,
+		version: "0.1.0",
+		type: "module",
+		private: true,
+		description: "StoryShelf MCP server.",
+		engines: { node: ">=24" },
+		scripts: {
+			start: `node ${MCP_ENTRY}`,
+			typecheck: "tsc"
+		},
+		dependencies: { "@storyshelf/mcp": "0.8.0" },
+		devDependencies
+	}, null, 2);
+}
+/** `.env.example`: never commit a real token. */
+function generateMcpEnvExample(answers) {
+	const transportLines = answers.transport === "stdio" ? ["# A project token with at least the viewer role (developer to post comments)", "STORYSHELF_TOKEN="] : [
+		"# HTTP clients send their own Bearer token; no token is stored on this server",
+		"PORT=3333",
+		"HOST=0.0.0.0"
+	];
+	return `${[
+		`STORYSHELF_URL=${answers.url}`,
+		`STORYSHELF_SLUG=${answers.slug}`,
+		...transportLines
+	].join("\n")}\n`;
+}
+const TOKEN_REF = "${STORYSHELF_TOKEN}";
+/** Client config for Claude Code (`.mcp.json`) and Cursor (`.cursor/mcp.json`). */
+function generateMcpClientConfig(answers) {
+	const server = answers.transport === "stdio" ? {
+		command: "npx",
+		args: ["-y", "@storyshelf/mcp"],
+		env: {
+			STORYSHELF_URL: answers.url,
+			STORYSHELF_SLUG: answers.slug,
+			STORYSHELF_TOKEN: TOKEN_REF
+		}
+	} : {
+		type: "http",
+		url: "http://127.0.0.1:3333/mcp",
+		headers: { Authorization: `Bearer ${TOKEN_REF}` }
+	};
+	return JSON.stringify({ mcpServers: { storyshelf: server } }, null, 2);
+}
+/** Small Node image for the HTTP transport (no browser needed). */
+function generateMcpDockerfile() {
+	return [
+		"FROM node:24-slim",
+		"WORKDIR /app",
+		"COPY package.json ./",
+		"RUN npm install --omit=dev",
+		"COPY src ./src",
+		"ENV HOST=0.0.0.0 PORT=3333",
+		"EXPOSE 3333",
+		`CMD ["node", "${MCP_ENTRY}"]`,
+		""
+	].join("\n");
+}
+export { MCP_ENTRY, generateMcpClientConfig, generateMcpDockerfile, generateMcpEntry, generateMcpEnvExample, generateMcpPackageJson };

package/dist/commands/mcp/serve.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { join, resolve } from "node:path";
+import "node:url";
+import.meta.url;
+import { detectPackageRunner, installCommand } from "../../config.js";
+import { printError } from "../../output.js";
+import { defaultSpawnProcess } from "../server/serve.js";
+import { access } from "node:fs/promises";
+// src/commands/mcp/serve.ts
+const MCP_CANDIDATES = [
+	"src/index.ts",
+	"src/index.js",
+	"src/index.mjs",
+	"index.ts",
+	"index.js",
+	"index.mjs"
+];
+/** Find the entry of a scaffolded MCP project. */
+async function resolveMcpFile(dir) {
+	for (const candidate of MCP_CANDIDATES) {
+		const full = join(dir, candidate);
+		try {
+			await access(full);
+			return full;
+		} catch {
+			continue;
+		}
+	}
+	throw new Error(`No MCP entry found in ${dir} (looked for ${MCP_CANDIDATES.join(", ")}). Run "storyshelf mcp init" first.`);
+}
+/** Run a scaffolded MCP project (`storyshelf mcp serve`). Flags map to STORYSHELF_* env. */
+async function runMcpServe(options, deps = {}) {
+	const dir = resolve(options.dir ?? process.cwd());
+	const file = await resolveMcpFile(dir);
+	await warnIfUninstalled(dir);
+	printError(`Starting MCP server: ${file}`);
+	const code = await (deps.spawnProcess ?? defaultSpawnProcess)(process.execPath, [file], {
+		cwd: dir,
+		env: childEnv(options)
+	});
+	if (code !== 0) throw new Error(`MCP server exited with code ${code}`);
+}
+function childEnv(options) {
+	const env = { ...process.env };
+	if (options.url !== void 0) env["STORYSHELF_URL"] = options.url;
+	if (options.slug !== void 0) env["STORYSHELF_SLUG"] = options.slug;
+	if (options.token !== void 0) env["STORYSHELF_TOKEN"] = options.token;
+	if (options.port !== void 0) env["PORT"] = options.port;
+	return env;
+}
+async function warnIfUninstalled(dir) {
+	try {
+		await access(join(dir, "node_modules"));
+	} catch {
+		const runner = await detectPackageRunner(dir);
+		printError(`Warning: no node_modules in ${dir} — run "${installCommand(runner)}" there first.`);
+	}
+}
+export { resolveMcpFile, runMcpServe };

package/dist/commands/package-usage.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { dirname, join, relative, resolve, sep } from "node:path";
+import "node:url";
+import.meta.url;
+import { existsSync } from "node:fs";
+import { readFile, realpath } from "node:fs/promises";
+import { extractPackageUsage, loadDepGraph, loadStoryImportPaths, statsPathFor } from "@storyshelf/affected";
+// src/commands/package-usage.ts
+/** Dependency sections of `package.json` whose packages are tracked. */
+const DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies"
+];
+/** Names declared in the project's `package.json`, or none when unreadable. */
+async function declaredPackages(cwd) {
+	try {
+		const manifest = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+		const names = DEPENDENCY_FIELDS.flatMap((field) => {
+			const section = manifest[field];
+			return typeof section === "object" && section !== null ? Object.keys(section) : [];
+		});
+		return [...new Set(names)];
+	} catch {
+		return [];
+	}
+}
+/** Nearest `node_modules/<name>` directory walking up from `cwd` (hoisted installs), if any. */
+function installedDir(cwd, name) {
+	for (let dir = resolve(cwd);; dir = dirname(dir)) {
+		const candidate = join(dir, "node_modules", name);
+		if (existsSync(join(candidate, "package.json"))) return candidate;
+		if (dirname(dir) === dir) return null;
+	}
+}
+/** Parse an installed `package.json`; null when unreadable or corrupt (never throws). */
+async function readManifest(path) {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/** Installed version and, for workspace links, the real source directory. */
+async function resolvePackage(cwd, name) {
+	const dir = installedDir(cwd, name);
+	if (dir === null) return {
+		tracked: {},
+		version: null
+	};
+	const manifest = await readManifest(join(dir, "package.json"));
+	if (manifest === null) return {
+		tracked: {},
+		version: null
+	};
+	const version = typeof manifest.version === "string" ? manifest.version : null;
+	const real = relative(await realpath(cwd), await realpath(dir));
+	return {
+		tracked: !real.startsWith("..") && !real.split(sep).includes("node_modules") ? { root: real.split(sep).join("/") } : {},
+		version
+	};
+}
+/**
+* Collect which declared dependency packages each story reaches, with the
+* installed version. Resolves `[]` (never throws) when the build has no usable
+* stats or the project declares no dependencies.
+*/
+async function collectPackageUsage(options) {
+	const names = await declaredPackages(options.cwd);
+	if (names.length === 0) return [];
+	const graph = await loadDepGraph(statsPathFor(options.cwd, options.buildDir, options.statsFile));
+	const stories = await loadStoryImportPaths(options.cwd, options.buildDir).catch(() => []);
+	if (!graph || stories.length === 0) return [];
+	const resolved = new Map(await Promise.all(names.map(async (name) => [name, await resolvePackage(options.cwd, name)])));
+	const tracked = Object.fromEntries([...resolved].map(([name, pkg]) => [name, pkg.tracked]));
+	return extractPackageUsage(graph, stories, tracked).map((usage) => ({
+		storyImportPath: usage.storyFile,
+		packageName: usage.packageName,
+		modulePath: usage.modulePath,
+		version: resolved.get(usage.packageName)?.version ?? null
+	}));
+}
+export { collectPackageUsage };