npm - @notionhq/custom-blocks-dev-shell - Versions diffs - 0.1.0 → 0.1.2 - Mend

@notionhq/custom-blocks-dev-shell 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.md +11 -0
package/bin/cli.js +12 -34
package/dist/assets/index-B1zP6MFl.js +9 -0
package/dist/index.html +1 -1
package/{cli/block-server.ts → dist-cli/block-server.js} +27 -54
package/dist-cli/data-sources.js +107 -0
package/dist-cli/main.js +247 -0
package/dist-cli/serve-ui.js +81 -0
package/dist-cli/worker-manifest.js +118 -0
package/docs/data-sources.md +72 -0
package/package.json +5 -4
package/cli/main.ts +0 -293
package/cli/serve-ui.ts +0 -100
package/cli/worker-manifest.ts +0 -196
package/dist/assets/index-BCi_w7Gk.js +0 -9

package/dist/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
 		<meta charset="UTF-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<title>Workers local shell</title>
-		<script type="module" crossorigin src="/assets/index-BCi_w7Gk.js"></script>
+		<script type="module" crossorigin src="/assets/index-B1zP6MFl.js"></script>
 		<link rel="stylesheet" crossorigin href="/assets/index-DvRqSoqY.css">
 	</head>
 	<body>

package/{cli/block-server.ts → dist-cli/block-server.js} RENAMED Viewed

@@ -2,42 +2,25 @@
  * Per-block Vite server plumbing shared by the repo dev script
  * (`scripts/dev.ts`) and the published dev-shell CLI (`cli/main.ts`).
  */
-import { existsSync, mkdirSync, writeFileSync } from "node:fs"
-import { relative, resolve } from "node:path"
-import type { WorkerBlockCapability } from "./worker-manifest"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
 /** First port handed to per-block Vite servers; blocks count up from here. */
-export const BLOCK_BASE_PORT = 9876
+export const BLOCK_BASE_PORT = 9876;
 /** Port the dev-shell-2 UI is served on. */
-export const SHELL_2_PORT = 9873
-/** One block entry handed to the dev-shell-2 UI. */
-export type BlockRegistryEntry = {
-	key: string
-	name: string
-	url: string
-}
+export const SHELL_2_PORT = 9873;
 /** The registry for a worker's blocks, assuming sequential port assignment. */
-export function buildBlockRegistry(
-	blocks: readonly WorkerBlockCapability[],
-	basePort: number = BLOCK_BASE_PORT,
-): BlockRegistryEntry[] {
-	return blocks.map((capability, index) => ({
-		key: capability.key,
-		name: capability.key,
-		url: `http://localhost:${basePort + index}/`,
-	}))
+export function buildBlockRegistry(blocks, basePort = BLOCK_BASE_PORT) {
+    return blocks.map((capability, index) => ({
+        key: capability.key,
+        name: capability.key,
+        url: `http://localhost:${basePort + index}/`,
+    }));
 }
 /** Import specifier from `fromDir` to `toPath`, POSIX-style for ESM. */
-function relativeImport(fromDir: string, toPath: string): string {
-	const rel = relative(fromDir, toPath).split(/[\\/]/).join("/")
-	return rel.startsWith(".") ? rel : `./${rel}`
+function relativeImport(fromDir, toPath) {
+    const rel = relative(fromDir, toPath).split(/[\\/]/).join("/");
+    return rel.startsWith(".") ? rel : `./${rel}`;
 }
 /**
  * Write a per-block Vite config wrapper into the worker's `.dev-shell/` dir. It
  * re-exports the block's own config (keeping its plugins) but pins `root` to the
@@ -48,27 +31,18 @@ function relativeImport(fromDir: string, toPath: string): string {
  * plays the part production infra does and answers the SDK's manifest fetch
  * from the worker's declaration. Returns the wrapper path for `vite --config`.
  */
-export function writeBlockViteConfig(
-	workerDir: string,
-	blockDir: string,
-	capability: WorkerBlockCapability,
-): string {
-	const key = capability.key
-	const dir = resolve(workerDir, ".dev-shell")
-	mkdirSync(dir, { recursive: true })
-	const blockConfig = resolve(blockDir, "vite.config.ts")
-	const toRoot = relativeImport(dir, blockDir)
-	const toCache = relativeImport(
-		dir,
-		resolve(workerDir, "node_modules/.vite", key),
-	)
-	const baseImport = existsSync(blockConfig)
-		? `import base from "${relativeImport(dir, blockConfig)}"`
-		: `const base = {}`
-	const file = resolve(dir, `${key}.mjs`)
-	writeFileSync(
-		file,
-		`import { fileURLToPath } from "node:url"
+export function writeBlockViteConfig(workerDir, blockDir, capability) {
+    const key = capability.key;
+    const dir = resolve(workerDir, ".dev-shell");
+    mkdirSync(dir, { recursive: true });
+    const blockConfig = resolve(blockDir, "vite.config.ts");
+    const toRoot = relativeImport(dir, blockDir);
+    const toCache = relativeImport(dir, resolve(workerDir, "node_modules/.vite", key));
+    const baseImport = existsSync(blockConfig)
+        ? `import base from "${relativeImport(dir, blockConfig)}"`
+        : `const base = {}`;
+    const file = resolve(dir, `${key}.mjs`);
+    writeFileSync(file, `import { fileURLToPath } from "node:url"
 ${baseImport}
 const here = p => fileURLToPath(new URL(p, import.meta.url))
@@ -102,7 +76,6 @@ export default {
 	cacheDir: here("${toCache}"),
 	plugins: [serveWorkerManifest, ...(resolved.plugins ?? [])],
 }
-`,
-	)
-	return file
+`);
+    return file;
 }

package/dist-cli/data-sources.js ADDED Viewed

@@ -0,0 +1,107 @@
+/**
+ * Load a worker's dev-shell data sources from `<dataDir>/*.json` — one source
+ * per file, hand-authored (the scaffolded worker AGENTS.md documents the
+ * format). Every file is validated here, before it reaches the shell, so a
+ * malformed source fails spin-up naming the file and the problem instead of
+ * breaking the UI.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import * as v from "valibot";
+const DEV_SHELL_DATA_SOURCE_TYPES = [
+    "built-in",
+    "worker",
+    "manual",
+    "syncedFromProd",
+];
+// Local copy of the SDK's NOTION_PROPERTY_TYPES: the compiled CLI runs under
+// plain node, which can't import the SDK's published TS source at runtime.
+// The `satisfies` below plus the type-only import keep the two lists locked
+// together — a drift on either side fails typecheck.
+const NOTION_PROPERTY_TYPES = [
+    "title",
+    "rich_text",
+    "number",
+    "checkbox",
+    "url",
+    "email",
+    "phone_number",
+    "select",
+    "multi_select",
+    "status",
+    "date",
+    "people",
+    "files",
+    "unique_id",
+    "relation",
+    "place",
+    "formula",
+    "rollup",
+    "button",
+    "verification",
+    "last_visited_time",
+    "location",
+    "created_time",
+    "last_edited_time",
+    "created_by",
+    "last_edited_by",
+];
+const _allPropertyTypesListed = true;
+void _allPropertyTypesListed;
+export function readDataSources(dataDir) {
+    if (!existsSync(dataDir)) {
+        return [];
+    }
+    return readdirSync(dataDir)
+        .filter(name => name.endsWith(".json"))
+        .map(name => readSource(resolve(dataDir, name)))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+const nonEmptyString = v.pipe(v.string(), v.nonEmpty());
+const sourceFileSchema = v.object({
+    type: v.optional(v.literal("worker"), "worker"),
+    key: v.optional(nonEmptyString),
+    name: v.optional(nonEmptyString),
+    icon: v.optional(v.string()),
+    schema: v.optional(v.record(v.string(), v.object({
+        name: v.optional(v.string()),
+        type: v.picklist(NOTION_PROPERTY_TYPES),
+    })), {}),
+    rows: v.optional(v.array(v.looseObject({ id: nonEmptyString })), []),
+});
+/**
+ * Parse and validate one source file. Structural mistakes throw with the file
+ * and problem named; omitted `key`/`name` fall back to the filename, and
+ * omitted `schema`/`rows` to empty — so the minimal valid file is `{}`.
+ */
+function readSource(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch (error) {
+        throw new Error(`${file}: not valid JSON — ${error.message}`);
+    }
+    if (Array.isArray(parsed)) {
+        throw new Error(`${file}: must be a JSON object`);
+    }
+    const result = v.safeParse(sourceFileSchema, parsed);
+    if (!result.success) {
+        const issue = result.issues[0];
+        const path = v.getDotPath(issue);
+        throw new Error(`${file}: ${path ? `${path}: ` : ""}${issue.message}`);
+    }
+    const { type, icon, schema, rows } = result.output;
+    const key = result.output.key ?? basename(file, ".json");
+    return {
+        type,
+        key,
+        name: result.output.name ?? key,
+        ...(icon !== undefined ? { icon } : {}),
+        schema: Object.fromEntries(Object.entries(schema).map(([propertyKey, property]) => [
+            propertyKey,
+            { name: property.name ?? propertyKey, type: property.type },
+        ])),
+        rows,
+    };
+}

package/dist-cli/main.js ADDED Viewed

@@ -0,0 +1,247 @@
+/**
+ * Entry point for the published dev-shell CLI (`npx`-run from a worker
+ * project). Mirrors the worker mode of the repo's `scripts/dev.ts`: build the
+ * worker, extract its manifest, serve one Vite dev server per custom block
+ * (using the worker's own Vite install), and serve the prebuilt dev-shell-2 UI
+ * with the block registry injected at runtime.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BLOCK_BASE_PORT, buildBlockRegistry, SHELL_2_PORT, writeBlockViteConfig, } from "./block-server.js";
+import { readDataSources } from "./data-sources.js";
+import { serveUi } from "./serve-ui.js";
+import { blockCapabilities, findWorkerDir, generateWorkerManifest, } from "./worker-manifest.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const dim = "\x1b[2m";
+const bold = "\x1b[1m";
+const cyan = "\x1b[36m";
+const reset = "\x1b[0m";
+const label = (name) => `${cyan}[${name}]${reset}`;
+function parseCliArgs(argv) {
+    const args = {
+        worker: undefined,
+        shellPort: SHELL_2_PORT,
+        blockBasePort: BLOCK_BASE_PORT,
+    };
+    const takeValue = (name, index) => {
+        const value = argv[index];
+        if (value === undefined || value.startsWith("--")) {
+            throw new Error(`${name} requires a value.`);
+        }
+        return value;
+    };
+    const takePort = (name, raw) => {
+        const port = Number(raw);
+        if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+            throw new Error(`${name} requires a port number, got "${raw}".`);
+        }
+        return port;
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--worker") {
+            args.worker = takeValue("--worker", ++index);
+        }
+        else if (arg.startsWith("--worker=")) {
+            args.worker = arg.slice("--worker=".length);
+            if (args.worker.length === 0) {
+                throw new Error("--worker requires a path to a worker directory.");
+            }
+        }
+        else if (arg === "--port") {
+            args.shellPort = takePort("--port", takeValue("--port", ++index));
+        }
+        else if (arg.startsWith("--port=")) {
+            args.shellPort = takePort("--port", arg.slice("--port=".length));
+        }
+        else if (arg === "--block-base-port") {
+            args.blockBasePort = takePort("--block-base-port", takeValue("--block-base-port", ++index));
+        }
+        else if (arg.startsWith("--block-base-port=")) {
+            args.blockBasePort = takePort("--block-base-port", arg.slice("--block-base-port=".length));
+        }
+    }
+    return args;
+}
+function resolveWorkerDir(workerArg) {
+    if (workerArg !== undefined) {
+        return resolve(process.cwd(), workerArg);
+    }
+    const detected = findWorkerDir(process.cwd());
+    if (detected !== undefined) {
+        console.log(`Detected a worker at ${detected}.`);
+        return detected;
+    }
+    throw new Error("No worker found: run from inside a worker directory, or pass --worker <dir>.");
+}
+/**
+ * The worker's own Vite binary. Blocks are served with the worker's Vite (and
+ * plugins) rather than anything bundled here, matching how the block builds in
+ * production.
+ */
+function resolveViteBin(workerDir) {
+    let vitePkgPath;
+    try {
+        const workerRequire = createRequire(join(workerDir, "package.json"));
+        vitePkgPath = workerRequire.resolve("vite/package.json");
+    }
+    catch {
+        throw new Error(`Could not resolve "vite" from ${workerDir}. Add vite to the worker's ` +
+            `devDependencies and reinstall.`);
+    }
+    const vitePkg = JSON.parse(readFileSync(vitePkgPath, "utf-8"));
+    const bin = typeof vitePkg.bin === "string" ? vitePkg.bin : vitePkg.bin?.vite;
+    if (bin === undefined) {
+        throw new Error(`The vite package at ${vitePkgPath} exposes no bin.`);
+    }
+    return resolve(dirname(vitePkgPath), bin);
+}
+const procs = [];
+async function main() {
+    const cliArgs = parseCliArgs(process.argv.slice(2));
+    const workerDir = resolveWorkerDir(cliArgs.worker);
+    if (!existsSync(resolve(workerDir, "node_modules"))) {
+        throw new Error(`No node_modules in ${workerDir}. Install the worker's dependencies first ` +
+            `(e.g. \`npm install\`), then rerun.`);
+    }
+    console.log(`${label(basename(workerDir))} Extracting worker manifest...`);
+    const { manifest, manifestPath } = await generateWorkerManifest(workerDir);
+    console.log(`${label(basename(workerDir))} Wrote ${manifestPath}`);
+    const blocks = blockCapabilities(manifest);
+    if (blocks.length === 0) {
+        // Not an error — start the shell anyway; it shows "None" under Blocks.
+        console.log(`${label(basename(workerDir))} Worker declares no custom blocks.`);
+    }
+    // Hand-authored data sources under the worker's src/data — see the
+    // scaffolded AGENTS.md for the file format. Validated before injection; a
+    // malformed file fails spin-up with the problem named.
+    const dataSources = readDataSources(resolve(workerDir, "src/data"));
+    console.log(dataSources.length > 0
+        ? `${label(basename(workerDir))} Data sources from src/data: ${dataSources
+            .map(source => source.name)
+            .join(", ")}`
+        : `${label(basename(workerDir))} No data sources — create src/data/<key>.json files ` +
+            `(format: node_modules/@notionhq/custom-blocks-dev-shell/docs/data-sources.md).`);
+    if (blocks.length > 0 &&
+        cliArgs.shellPort >= cliArgs.blockBasePort &&
+        cliArgs.shellPort < cliArgs.blockBasePort + blocks.length) {
+        throw new Error(`--port ${cliArgs.shellPort} collides with the block server ports ` +
+            `(${cliArgs.blockBasePort}–${cliArgs.blockBasePort + blocks.length - 1}); ` +
+            `pick a port outside that range or move --block-base-port.`);
+    }
+    const viteBin = blocks.length > 0 ? resolveViteBin(workerDir) : undefined;
+    const registry = buildBlockRegistry(blocks, cliArgs.blockBasePort);
+    for (const [index, capability] of blocks.entries()) {
+        const blockDir = resolve(workerDir, capability.config.source.path);
+        const configFile = writeBlockViteConfig(workerDir, blockDir, capability);
+        const port = cliArgs.blockBasePort + index;
+        const proc = spawn(process.execPath, [
+            viteBin,
+            "--config",
+            configFile,
+            "--port",
+            String(port),
+            "--strictPort",
+        ], {
+            cwd: workerDir,
+            stdio: ["ignore", "ignore", "inherit"],
+            // Process groups (and negative-PID kills) are POSIX-only; on
+            // Windows children are killed individually in shutdown().
+            detached: process.platform !== "win32",
+        });
+        proc.on("exit", code => {
+            if (shuttingDown || code === 0 || code === null) {
+                return;
+            }
+            console.error(`${label(capability.key)} dev server exited with code ${code}`);
+            process.exitCode = code;
+            shutdown("SIGTERM");
+        });
+        procs.push(proc);
+    }
+    // The published layout is dist/ next to cli/; index.html must be prebuilt.
+    const distDir = resolve(__dirname, "..", "dist");
+    if (!existsSync(join(distDir, "index.html"))) {
+        throw new Error(`No prebuilt UI found at ${distDir}. This package was not assembled ` +
+            `correctly; reinstall it.`);
+    }
+    try {
+        await serveUi(distDir, cliArgs.shellPort, {
+            mode: "worker",
+            blocks: registry,
+            dataSources,
+        });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EADDRINUSE") {
+            throw new Error(`Port ${cliArgs.shellPort} is already in use. Stop whatever holds it ` +
+                `or rerun with --port <port> (and --block-base-port <port> for the ` +
+                `block servers).`);
+        }
+        throw error;
+    }
+    console.log("");
+    console.log(`${bold}Dev shell${reset}`);
+    console.log(`  ${label("dev-shell")} ${dim}http://localhost:${cliArgs.shellPort}${reset}`);
+    if (blocks.length > 0) {
+        console.log("");
+        console.log(`${bold}Blocks${reset}`);
+        for (const [index, entry] of registry.entries()) {
+            console.log(`  ${label(entry.key)} ${dim}http://localhost:${cliArgs.blockBasePort + index}${reset}`);
+        }
+    }
+    console.log("");
+}
+function killProc(p, signal) {
+    if (p.pid === undefined || p.killed) {
+        return;
+    }
+    try {
+        if (process.platform === "win32") {
+            p.kill(signal);
+        }
+        else {
+            process.kill(-p.pid, signal);
+        }
+    }
+    catch { }
+}
+let shuttingDown = false;
+function shutdown(signal) {
+    if (shuttingDown) {
+        return;
+    }
+    shuttingDown = true;
+    if (signal !== "exit") {
+        console.log(`\n${dim}Shutting down...${reset}`);
+    }
+    for (const p of procs) {
+        killProc(p, "SIGTERM");
+    }
+    setTimeout(() => {
+        for (const p of procs) {
+            killProc(p, "SIGKILL");
+        }
+        // Preserve a failure exit code set before shutdown (startup errors,
+        // crashed block servers); plain signal shutdowns still exit 0.
+        process.exit(process.exitCode ?? 0);
+    }, 1500).unref();
+}
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => shutdown(signal));
+}
+process.on("exit", () => shutdown("exit"));
+process.on("uncaughtException", err => {
+    console.error(err);
+    process.exitCode = 1;
+    shutdown("SIGTERM");
+});
+main().catch(err => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+    shutdown("SIGTERM");
+});

package/dist-cli/serve-ui.js ADDED Viewed

@@ -0,0 +1,81 @@
+/**
+ * Dependency-free static server for the prebuilt dev-shell-2 UI (`dist/`).
+ *
+ * The published UI is a plain Vite build, so the block registry can't ride in
+ * through build-time `import.meta.env` vars the way it does under
+ * `scripts/dev.ts`. Instead, this server injects a `window.__DEV_SHELL_2_CONFIG__`
+ * script into `index.html` as it is served; `src/helpers/templates.ts` prefers
+ * that global over the baked-in env values.
+ */
+import { readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join, normalize, resolve, sep } from "node:path";
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".map": "application/json; charset=utf-8",
+};
+/** `index.html` with the runtime config injected ahead of the bundle script. */
+function injectConfig(html, config) {
+    const tag = `<script>window.__DEV_SHELL_2_CONFIG__ = ${JSON.stringify(config)}</script>`;
+    if (html.includes("<head>")) {
+        return html.replace("<head>", `<head>\n\t\t${tag}`);
+    }
+    return `${tag}\n${html}`;
+}
+/**
+ * Serve `distDir` on `port`. Unknown extensionless paths fall back to
+ * `index.html`. Rejects on listen errors (e.g. the port is taken).
+ */
+export function serveUi(distDir, port, config) {
+    const dist = resolve(distDir);
+    const indexHtml = injectConfig(readFileSync(join(dist, "index.html"), "utf-8"), config);
+    const server = createServer((req, res) => {
+        let path;
+        try {
+            path = normalize(decodeURIComponent(req.url?.split("?", 1)[0] ?? "/"));
+        }
+        catch {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        const filePath = join(dist, path);
+        if (!filePath.startsWith(dist + sep) && filePath !== dist) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        const ext = extname(filePath);
+        if (path === "/" || path === `${sep}index.html` || ext === "") {
+            res.writeHead(200, { "Content-Type": CONTENT_TYPES[".html"] });
+            res.end(indexHtml);
+            return;
+        }
+        try {
+            const body = readFileSync(filePath);
+            res.writeHead(200, {
+                "Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream",
+            });
+            res.end(body);
+        }
+        catch {
+            res.writeHead(404);
+            res.end();
+        }
+    });
+    return new Promise((resolvePromise, reject) => {
+        server.once("error", reject);
+        // Loopback only: every response embeds the worker's block registry, and
+        // the per-block Vite servers are localhost-only too.
+        server.listen(port, "127.0.0.1", () => resolvePromise(server));
+    });
+}

package/dist-cli/worker-manifest.js ADDED Viewed

@@ -0,0 +1,118 @@
+/**
+ * Extract a worker's manifest without deploying it, following the localhost
+ * verification strategy: build the worker, then read the manifest off the
+ * built module's default export. This is the one prerequisite the dev shell
+ * needs before it can list a worker's blocks and data sources.
+ *
+ * The worker manifest is otherwise in-memory only (tied to `worker.ts` + cloud
+ * build), so we materialize it under the worker's git-ignored `.dev-shell/` dir
+ * (clearly a dev-shell artifact, not something the author maintains).
+ * Regenerated on every spin-up.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+export const WORKER_MANIFEST_FILENAME = "worker_manifest.json";
+/**
+ * Heuristic for the no-flag fallback: does `dir` look like a worker project?
+ * True if it carries a worker deploy binding (`worker.json`/`workers.json`) or
+ * depends on `@notionhq/workers`.
+ */
+export function looksLikeWorkerDir(dir) {
+    if (existsSync(resolve(dir, "worker.json")) ||
+        existsSync(resolve(dir, "workers.json"))) {
+        return true;
+    }
+    const pkgPath = resolve(dir, "package.json");
+    if (!existsSync(pkgPath)) {
+        return false;
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return Boolean(pkg.dependencies?.["@notionhq/workers"] ??
+            pkg.devDependencies?.["@notionhq/workers"]);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk up from `startDir` looking for a worker directory (see
+ * `looksLikeWorkerDir`), so the shell can be launched from anywhere inside a
+ * worker, not only its root. Stops once it reaches a git-repo boundary (a
+ * `.git` at the current level, checked after the worker test) or the filesystem
+ * root — it should never escape the project the user is in.
+ */
+export function findWorkerDir(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (looksLikeWorkerDir(current)) {
+            return current;
+        }
+        if (existsSync(resolve(current, ".git"))) {
+            return undefined;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+/** The custom-block capabilities in a manifest, narrowed by `_tag`. */
+export function blockCapabilities(manifest) {
+    return manifest.capabilities.filter((capability) => capability._tag === "custom_block");
+}
+function isManifestShape(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Array.isArray(value.capabilities));
+}
+/**
+ * Build the worker in `workerDir` and read its manifest off the built default
+ * export. Mirrors the deploy path (build → read the built module) rather than
+ * importing TypeScript source, so what the dev shell sees matches what a deploy
+ * would produce.
+ */
+export async function extractWorkerManifest(workerDir, options = {}) {
+    const root = resolve(workerDir);
+    if (!existsSync(resolve(root, "package.json"))) {
+        throw new Error(`No package.json found in worker directory: ${root}`);
+    }
+    if (options.build !== false) {
+        execSync("npm run build", { cwd: root, stdio: "inherit" });
+    }
+    const entry = resolve(root, "dist/index.js");
+    if (!existsSync(entry)) {
+        throw new Error(`Built worker entry not found at ${entry}. The worker's build must emit dist/index.js.`);
+    }
+    const mod = (await import(pathToFileURL(entry).href));
+    const worker = mod.default;
+    if (worker === undefined) {
+        throw new Error(`Built worker at ${entry} has no default export.`);
+    }
+    // Read the built worker's manifest, falling back to a bare capabilities array
+    // (per the localhost verification doc's `w.manifest || w.capabilities`).
+    const raw = worker.manifest ?? worker.capabilities;
+    if (isManifestShape(raw)) {
+        return raw;
+    }
+    if (Array.isArray(raw)) {
+        return { databases: [], pacers: [], capabilities: raw };
+    }
+    throw new Error(`Built worker at ${entry} exposed no usable manifest (expected .manifest or .capabilities).`);
+}
+/**
+ * Extract the worker manifest and write it to `.dev-shell/worker_manifest.json`
+ * inside the worker (a git-ignored dev-shell artifact dir). Returns the parsed
+ * manifest and the path written.
+ */
+export async function generateWorkerManifest(workerDir, options = {}) {
+    const manifest = await extractWorkerManifest(workerDir, options);
+    const dir = resolve(workerDir, ".dev-shell");
+    mkdirSync(dir, { recursive: true });
+    const manifestPath = resolve(dir, WORKER_MANIFEST_FILENAME);
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return { manifest, manifestPath };
+}