bosia 0.1.5 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bosia",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "type": "module",
   "description": "A fast, batteries-included fullstack framework — SSR · Svelte 5 Runes · Bun · ElysiaJS. File-based routing inspired by SvelteKit. No Node.js, no Vite, no adapters.",
   "keywords": [

package/src/cli/add.ts

@@ -1,7 +1,15 @@
 import { join, dirname } from "path";
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from "fs";
-import { spawn } from "bun";
 import * as p from "@clack/prompts";
+import {
+    type InstallOptions,
+    REGISTRY_URL,
+    resolveLocalRegistryOrExit,
+    readRegistryJSON,
+    readRegistryFile,
+    mergePkgJson,
+    bunAdd,
+} from "./registry.ts";
 
 // ─── bosia add <component> ────────────────────────────────
 // Fetches a component from the GitHub registry (or local registry
@@ -11,8 +19,6 @@ import * as p from "@clack/prompts";
 //   bosia add button       → src/lib/components/ui/button/
 //   bosia add shop/cart    → src/lib/components/shop/cart/
 
-const REMOTE_BASE = "https://raw.githubusercontent.com/bosapi/bosia/main/registry";
-
 interface ComponentMeta {
     name: string;
     description: string;
@@ -46,8 +52,7 @@ export async function runAdd(name: string | undefined, flags: string[] = []) {
     }
 
     if (flags.includes("--local")) {
-        // Walk up from this file to find the repo's registry/ directory
-        registryRoot = resolveLocalRegistry();
+        registryRoot = resolveLocalRegistryOrExit();
         console.log(`⬡ Using local registry: ${registryRoot}\n`);
     }
 
@@ -88,31 +93,35 @@ async function loadIndex(): Promise<RegistryIndex | null> {
             if (existsSync(path)) return JSON.parse(readFileSync(path, "utf-8"));
             return null;
         }
-        return await fetchJSON<RegistryIndex>(`${REMOTE_BASE}/index.json`);
+        const res = await fetch(`${REGISTRY_URL}/index.json`);
+        if (!res.ok) return null;
+        return await res.json() as RegistryIndex;
     } catch {
         return null;
     }
 }
 
-export async function addComponent(name: string, root = false) {
+export async function addComponent(name: string, root = false, options?: InstallOptions) {
     // Resolve the full path (e.g. "button" → "ui/button", "shop/cart" stays "shop/cart")
     const fullPath = resolveDestPath(name);
 
     if (installed.has(fullPath)) return;
     installed.add(fullPath);
 
+    const cwd = options?.cwd ?? process.cwd();
+
     console.log(root ? `⬡ Installing component: ${name}\n` : `   📦 Dependency: ${name}`);
 
-    const meta = await readMeta(fullPath);
+    const meta = await readRegistryJSON<ComponentMeta>(registryRoot, "components", fullPath, "meta.json");
 
     // Install component dependencies first (recursive)
     for (const dep of meta.dependencies) {
-        await addComponent(dep, false);
+        await addComponent(dep, false, options);
     }
 
-    // Check if component already exists
-    const destDir = join(process.cwd(), "src", "lib", "components", fullPath);
-    if (existsSync(destDir)) {
+    // Check if component already exists (skip check entirely in non-interactive mode)
+    const destDir = join(cwd, "src", "lib", "components", fullPath);
+    if (!options?.skipPrompts && existsSync(destDir)) {
         const replace = await p.confirm({
             message: `Component "${name}" already exists at src/lib/components/${fullPath}/. Replace it?`,
         });
@@ -126,25 +135,20 @@ export async function addComponent(name: string, root = false) {
     mkdirSync(destDir, { recursive: true });
 
     for (const file of meta.files) {
-        const content = await readFile(fullPath, file);
+        const content = await readRegistryFile(registryRoot, "components", fullPath, file);
         const dest = join(destDir, file);
-        mkdirSync(dirname(dest), { recursive: true });
+        if (file.includes("/")) mkdirSync(dirname(dest), { recursive: true });
         writeFileSync(dest, content, "utf-8");
         console.log(`   ✍️  src/lib/components/${fullPath}/${file}`);
     }
 
     // Install npm dependencies
-    const npmEntries = Object.entries(meta.npmDeps);
-    if (npmEntries.length > 0) {
-        const packages = npmEntries.map(([pkg, ver]) => (ver ? `${pkg}@${ver}` : pkg));
-        console.log(`   📥 npm: ${packages.join(", ")}`);
-        const proc = spawn(["bun", "add", ...packages], {
-            stdout: "inherit",
-            stderr: "inherit",
-            cwd: process.cwd(),
-        });
-        if ((await proc.exited) !== 0) {
-            console.warn(`   ⚠️  bun add failed for: ${packages.join(", ")}`);
+    if (Object.keys(meta.npmDeps).length > 0) {
+        if (options?.skipInstall) {
+            const { addedDeps } = mergePkgJson(cwd, { deps: meta.npmDeps });
+            if (addedDeps.length > 0) console.log(`   📥 Added to package.json: ${addedDeps.join(", ")}`);
+        } else {
+            await bunAdd(cwd, meta.npmDeps);
         }
     }
 
@@ -169,53 +173,3 @@ function ensureUtils() {
         console.log("   ✍️  src/lib/utils.ts (cn utility)\n");
     }
 }
-
-// ─── Registry resolvers ──────────────────────────────────────
-
-function resolveLocalRegistry(): string {
-    // Walk up from this file's directory to find registry/
-    let dir = dirname(new URL(import.meta.url).pathname);
-    for (let i = 0; i < 10; i++) {
-        const candidate = join(dir, "registry");
-        if (existsSync(join(candidate, "index.json"))) return candidate;
-        const parent = dirname(dir);
-        if (parent === dir) break;
-        dir = parent;
-    }
-    console.error("❌ Could not find local registry/ directory.");
-    process.exit(1);
-}
-
-async function readMeta(name: string): Promise<ComponentMeta> {
-    if (registryRoot) {
-        const path = join(registryRoot, "components", name, "meta.json");
-        if (!existsSync(path)) {
-            throw new Error(`Component "${name}" not found in local registry`);
-        }
-        return JSON.parse(readFileSync(path, "utf-8"));
-    }
-    return fetchJSON<ComponentMeta>(`${REMOTE_BASE}/components/${name}/meta.json`);
-}
-
-async function readFile(name: string, file: string): Promise<string> {
-    if (registryRoot) {
-        const path = join(registryRoot, "components", name, file);
-        if (!existsSync(path)) {
-            throw new Error(`File "${file}" not found for component "${name}" in local registry`);
-        }
-        return readFileSync(path, "utf-8");
-    }
-    return fetchText(`${REMOTE_BASE}/components/${name}/${file}`);
-}
-
-async function fetchJSON<T>(url: string): Promise<T> {
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`Failed to fetch ${url} (${res.status})`);
-    return res.json() as Promise<T>;
-}
-
-async function fetchText(url: string): Promise<string> {
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`Failed to fetch ${url} (${res.status})`);
-    return res.text();
-}

package/src/cli/create.ts

@@ -2,6 +2,8 @@ import { resolve, join, basename, relative } from "path";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
 import { spawn } from "bun";
 import * as p from "@clack/prompts";
+import { installFeature, initFeatRegistry, resolveLocalRegistry } from "./feat.ts";
+import { initAddRegistry } from "./add.ts";
 
 // ─── bosia create <name> [--template <name>] ──────────────
 
@@ -59,7 +61,32 @@ export async function runCreate(name: string | undefined, args: string[] = []) {
         writeFileSync(join(targetDir, ".env"), readFileSync(join(targetDir, ".env.example"), "utf-8"));
     }
 
-    console.log(`✅ Project created at ${targetDir}\n`);
+    // Install template features from registry
+    const templateConfigPath = join(templateDir, "template.json");
+    if (existsSync(templateConfigPath)) {
+        const config = JSON.parse(readFileSync(templateConfigPath, "utf-8"));
+        if (config.features?.length) {
+            let localRegistry: string | null = null;
+            try {
+                localRegistry = resolveLocalRegistry();
+            } catch {
+                // Local registry not found — will use remote
+            }
+
+            await initAddRegistry(localRegistry);
+            initFeatRegistry(localRegistry);
+
+            for (const feat of config.features) {
+                await installFeature(feat, true, {
+                    skipInstall: true,
+                    skipPrompts: true,
+                    cwd: targetDir,
+                });
+            }
+        }
+    }
+
+    console.log(`\n✅ Project created at ${targetDir}\n`);
 
     console.log("Installing dependencies...");
     const proc = spawn(["bun", "install"], {
@@ -72,7 +99,7 @@ export async function runCreate(name: string | undefined, args: string[] = []) {
         console.warn("⚠️  bun install failed — run it manually.");
     } else {
         console.log(`\n🎉 Ready!\n\ncd ${name}`);
-        
+
         const instPath = join(templateDir, "instructions.txt");
         if (existsSync(instPath)) {
             const instructions = readFileSync(instPath, "utf-8").trimEnd();
@@ -117,9 +144,9 @@ function copyDir(src: string, dest: string, projectName: string, isLocal: boolea
     for (const entry of readdirSync(src, { withFileTypes: true })) {
         const srcPath = join(src, entry.name);
         const destPath = join(dest, entry.name);
-        
-        // Do not copy instructions.txt to the final project
-        if (entry.name === "instructions.txt") continue;
+
+        // Do not copy instructions.txt or template.json to the final project
+        if (entry.name === "instructions.txt" || entry.name === "template.json") continue;
 
         if (entry.isDirectory()) {
             copyDir(srcPath, destPath, projectName, isLocal);

package/src/cli/feat.ts

@@ -1,16 +1,21 @@
 import { join, dirname } from "path";
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from "fs";
-import { spawn } from "bun";
 import * as p from "@clack/prompts";
 import { addComponent, initAddRegistry } from "./add.ts";
+import {
+    type InstallOptions,
+    resolveLocalRegistryOrExit,
+    readRegistryJSON,
+    readRegistryFile,
+    mergePkgJson,
+    bunAdd,
+} from "./registry.ts";
 
 // ─── bosia feat <feature> [--local] ──────────────────────
 // Fetches a feature scaffold from the GitHub registry (or local
 // registry with --local) and copies route/lib files, installs npm deps.
 // Supports nested feature dependencies (e.g. todo → drizzle).
 
-const REGISTRY_BASE = "https://raw.githubusercontent.com/bosapi/bosia/main/registry";
-
 interface FeatureMeta {
     name: string;
     description: string;
@@ -19,6 +24,7 @@ interface FeatureMeta {
     files: string[];                   // source filenames in the registry feature dir
     targets: string[];                 // destination paths relative to project root
     npmDeps: Record<string, string>;
+    npmDevDeps?: Record<string, string>;
     scripts?: Record<string, string>;  // package.json scripts to add
     envVars?: Record<string, string>;  // env vars to append to .env if missing
 }
@@ -35,7 +41,7 @@ export async function runFeat(name: string | undefined, flags: string[] = []) {
     }
 
     if (flags.includes("--local")) {
-        registryRoot = resolveLocalRegistry();
+        registryRoot = resolveLocalRegistryOrExit();
         console.log(`⬡ Using local registry: ${registryRoot}\n`);
     }
 
@@ -45,18 +51,25 @@ export async function runFeat(name: string | undefined, flags: string[] = []) {
     await installFeature(name, true);
 }
 
-async function installFeature(name: string, isRoot: boolean) {
+/** Set the registry root for feature resolution. Called by create.ts for template features. */
+export function initFeatRegistry(root: string | null) {
+    registryRoot = root;
+}
+
+export async function installFeature(name: string, isRoot: boolean, options?: InstallOptions) {
     if (installedFeats.has(name)) return;
     installedFeats.add(name);
 
+    const cwd = options?.cwd ?? process.cwd();
+
     console.log(isRoot ? `⬡ Installing feature: ${name}\n` : `\n⬡ Installing dependency feature: ${name}\n`);
 
-    const meta = await readMeta(name);
+    const meta = await readRegistryJSON<FeatureMeta>(registryRoot, "features", name, "meta.json");
 
     // Install required feature dependencies first (recursive)
     if (meta.features && meta.features.length > 0) {
         for (const feat of meta.features) {
-            await installFeature(feat, false);
+            await installFeature(feat, false, options);
         }
     }
 
@@ -64,19 +77,20 @@ async function installFeature(name: string, isRoot: boolean) {
     if (meta.components.length > 0) {
         console.log("📦 Installing required components...");
         for (const comp of meta.components) {
-            await addComponent(comp, false);
+            await addComponent(comp, false, options);
         }
         console.log("");
     }
 
     // Copy feature files to their target paths
+    const createdDirs = new Set<string>();
     for (let i = 0; i < meta.files.length; i++) {
         const file = meta.files[i]!;
         const target = meta.targets[i] ?? file;
-        const dest = join(process.cwd(), target);
+        const dest = join(cwd, target);
 
-        // Prompt before overwriting existing files
-        if (existsSync(dest)) {
+        // Prompt before overwriting existing files (skip check entirely in non-interactive mode)
+        if (!options?.skipPrompts && existsSync(dest)) {
             const replace = await p.confirm({
                 message: `File "${target}" already exists. Replace it?`,
             });
@@ -86,52 +100,46 @@ async function installFeature(name: string, isRoot: boolean) {
             }
         }
 
-        const content = await readFile(name, file);
-        mkdirSync(dirname(dest), { recursive: true });
+        const content = await readRegistryFile(registryRoot, "features", name, file);
+        const dir = dirname(dest);
+        if (!createdDirs.has(dir)) {
+            mkdirSync(dir, { recursive: true });
+            createdDirs.add(dir);
+        }
         writeFileSync(dest, content, "utf-8");
         console.log(`   ✍️  ${target}`);
     }
 
     // Install npm dependencies
-    const npmEntries = Object.entries(meta.npmDeps);
-    if (npmEntries.length > 0) {
-        const packages = npmEntries.map(([pkg, ver]) => (ver ? `${pkg}@${ver}` : pkg));
-        console.log(`\n📥 npm: ${packages.join(", ")}`);
-        const proc = spawn(["bun", "add", ...packages], {
-            stdout: "inherit",
-            stderr: "inherit",
-            cwd: process.cwd(),
-        });
-        if ((await proc.exited) !== 0) {
-            console.warn(`⚠️  bun add failed for: ${packages.join(", ")}`);
-        }
-    }
-
-    // Add package.json scripts
-    const scriptEntries = Object.entries(meta.scripts ?? {});
-    if (scriptEntries.length > 0) {
-        const pkgPath = join(process.cwd(), "package.json");
-        if (existsSync(pkgPath)) {
-            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-            pkg.scripts = pkg.scripts ?? {};
-            const added: string[] = [];
-            for (const [key, val] of scriptEntries) {
-                if (!pkg.scripts[key]) {
-                    pkg.scripts[key] = val;
-                    added.push(key);
-                }
-            }
-            if (added.length > 0) {
-                writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
-                console.log(`\n📜 Added scripts: ${added.join(", ")}`);
+    const hasDeps = Object.keys(meta.npmDeps).length > 0;
+    const hasDevDeps = Object.keys(meta.npmDevDeps ?? {}).length > 0;
+    const hasScripts = Object.keys(meta.scripts ?? {}).length > 0;
+
+    if (hasDeps || hasDevDeps) {
+        if (options?.skipInstall) {
+            const { addedDeps, addedScripts } = mergePkgJson(cwd, {
+                deps: meta.npmDeps,
+                devDeps: meta.npmDevDeps,
+                scripts: meta.scripts,
+            });
+            if (addedDeps.length > 0) console.log(`\n📥 Added to package.json: ${addedDeps.join(", ")}`);
+            if (addedScripts.length > 0) console.log(`\n📜 Added scripts: ${addedScripts.join(", ")}`);
+        } else {
+            await bunAdd(cwd, meta.npmDeps, meta.npmDevDeps);
+            if (hasScripts) {
+                const { addedScripts } = mergePkgJson(cwd, { scripts: meta.scripts });
+                if (addedScripts.length > 0) console.log(`\n📜 Added scripts: ${addedScripts.join(", ")}`);
             }
         }
+    } else if (hasScripts) {
+        const { addedScripts } = mergePkgJson(cwd, { scripts: meta.scripts });
+        if (addedScripts.length > 0) console.log(`\n📜 Added scripts: ${addedScripts.join(", ")}`);
     }
 
     // Append env vars to .env if missing
     const envEntries = Object.entries(meta.envVars ?? {});
     if (envEntries.length > 0) {
-        const envPath = join(process.cwd(), ".env");
+        const envPath = join(cwd, ".env");
         const existing = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
         const toAdd: string[] = [];
         for (const [key, val] of envEntries) {
@@ -154,51 +162,5 @@ async function installFeature(name: string, isRoot: boolean) {
     }
 }
 
-// ─── Registry resolvers ──────────────────────────────────────
-
-function resolveLocalRegistry(): string {
-    let dir = dirname(new URL(import.meta.url).pathname);
-    for (let i = 0; i < 10; i++) {
-        const candidate = join(dir, "registry");
-        if (existsSync(join(candidate, "index.json"))) return candidate;
-        const parent = dirname(dir);
-        if (parent === dir) break;
-        dir = parent;
-    }
-    console.error("❌ Could not find local registry/ directory.");
-    process.exit(1);
-}
-
-async function readMeta(name: string): Promise<FeatureMeta> {
-    if (registryRoot) {
-        const path = join(registryRoot, "features", name, "meta.json");
-        if (!existsSync(path)) {
-            throw new Error(`Feature "${name}" not found in local registry`);
-        }
-        return JSON.parse(readFileSync(path, "utf-8"));
-    }
-    return fetchJSON<FeatureMeta>(`${REGISTRY_BASE}/features/${name}/meta.json`);
-}
-
-async function readFile(name: string, file: string): Promise<string> {
-    if (registryRoot) {
-        const path = join(registryRoot, "features", name, file);
-        if (!existsSync(path)) {
-            throw new Error(`File "${file}" not found for feature "${name}" in local registry`);
-        }
-        return readFileSync(path, "utf-8");
-    }
-    return fetchText(`${REGISTRY_BASE}/features/${name}/${file}`);
-}
-
-async function fetchJSON<T>(url: string): Promise<T> {
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`Failed to fetch ${url} (${res.status})`);
-    return res.json() as Promise<T>;
-}
-
-async function fetchText(url: string): Promise<string> {
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`Failed to fetch ${url} (${res.status})`);
-    return res.text();
-}
+// Re-exports for create.ts
+export { resolveLocalRegistry, type InstallOptions } from "./registry.ts";

package/src/cli/registry.ts

@@ -0,0 +1,168 @@
+import { join, dirname } from "path";
+import { writeFileSync, readFileSync, existsSync } from "fs";
+import { spawn } from "bun";
+
+// ─── Shared registry utilities for feat.ts and add.ts ─────
+
+export const REGISTRY_URL = "https://raw.githubusercontent.com/bosapi/bosia/main/registry";
+
+export interface InstallOptions {
+    skipInstall?: boolean;  // write deps to package.json instead of `bun add`
+    skipPrompts?: boolean;  // auto-overwrite, no interactive prompts
+    cwd?: string;           // override process.cwd() for file operations
+}
+
+// ─── Local registry resolution ────────────────────────────
+
+export function resolveLocalRegistry(): string {
+    let dir = dirname(new URL(import.meta.url).pathname);
+    for (let i = 0; i < 10; i++) {
+        const candidate = join(dir, "registry");
+        if (existsSync(join(candidate, "index.json"))) return candidate;
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    throw new Error("Could not find local registry/ directory.");
+}
+
+/** Resolve local registry, exiting with error message on failure. For CLI entry points. */
+export function resolveLocalRegistryOrExit(): string {
+    try {
+        return resolveLocalRegistry();
+    } catch {
+        console.error("❌ Could not find local registry/ directory.");
+        process.exit(1);
+    }
+}
+
+// ─── Registry file readers ────────────────────────────────
+
+/** Read and parse a JSON file from the registry (local or remote). */
+export async function readRegistryJSON<T>(
+    registryRoot: string | null,
+    category: string,
+    name: string,
+    file: string,
+): Promise<T> {
+    if (registryRoot) {
+        const path = join(registryRoot, category, name, file);
+        if (!existsSync(path)) {
+            throw new Error(`"${file}" not found for ${category.slice(0, -1)} "${name}" in local registry`);
+        }
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    return fetchJSON<T>(`${REGISTRY_URL}/${category}/${name}/${file}`);
+}
+
+/** Read a text file from the registry (local or remote). */
+export async function readRegistryFile(
+    registryRoot: string | null,
+    category: string,
+    name: string,
+    file: string,
+): Promise<string> {
+    if (registryRoot) {
+        const path = join(registryRoot, category, name, file);
+        if (!existsSync(path)) {
+            throw new Error(`File "${file}" not found for ${category.slice(0, -1)} "${name}" in local registry`);
+        }
+        return readFileSync(path, "utf-8");
+    }
+    return fetchText(`${REGISTRY_URL}/${category}/${name}/${file}`);
+}
+
+// ─── package.json helpers ─────────────────────────────────
+
+export interface PkgDeps {
+    deps?: Record<string, string>;
+    devDeps?: Record<string, string>;
+    scripts?: Record<string, string>;
+}
+
+/**
+ * Merge dependencies and scripts into package.json in a single read/write.
+ * Returns the list of added keys, or empty arrays if nothing changed.
+ */
+export function mergePkgJson(cwd: string, changes: PkgDeps): { addedDeps: string[]; addedScripts: string[] } {
+    const pkgPath = join(cwd, "package.json");
+    if (!existsSync(pkgPath)) return { addedDeps: [], addedScripts: [] };
+
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    let changed = false;
+    const addedDeps: string[] = [];
+    const addedScripts: string[] = [];
+
+    if (changes.deps && Object.keys(changes.deps).length > 0) {
+        pkg.dependencies = pkg.dependencies ?? {};
+        for (const [name, ver] of Object.entries(changes.deps)) {
+            if (!pkg.dependencies[name]) {
+                pkg.dependencies[name] = ver;
+                addedDeps.push(name);
+                changed = true;
+            }
+        }
+    }
+
+    if (changes.devDeps && Object.keys(changes.devDeps).length > 0) {
+        pkg.devDependencies = pkg.devDependencies ?? {};
+        for (const [name, ver] of Object.entries(changes.devDeps)) {
+            if (!pkg.devDependencies[name]) {
+                pkg.devDependencies[name] = ver;
+                addedDeps.push(name);
+                changed = true;
+            }
+        }
+    }
+
+    if (changes.scripts && Object.keys(changes.scripts).length > 0) {
+        pkg.scripts = pkg.scripts ?? {};
+        for (const [key, val] of Object.entries(changes.scripts)) {
+            if (!pkg.scripts[key]) {
+                pkg.scripts[key] = val;
+                addedScripts.push(key);
+                changed = true;
+            }
+        }
+    }
+
+    if (changed) {
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+    }
+
+    return { addedDeps, addedScripts };
+}
+
+/** Run `bun add` for deps and optionally `bun add --dev` for devDeps. */
+export async function bunAdd(cwd: string, deps: Record<string, string>, devDeps?: Record<string, string>): Promise<void> {
+    const packages = Object.entries(deps).map(([pkg, ver]) => (ver ? `${pkg}@${ver}` : pkg));
+    if (packages.length > 0) {
+        console.log(`\n📥 npm: ${packages.join(", ")}`);
+        const proc = spawn(["bun", "add", ...packages], { stdout: "inherit", stderr: "inherit", cwd });
+        if ((await proc.exited) !== 0) {
+            console.warn(`⚠️  bun add failed for: ${packages.join(", ")}`);
+        }
+    }
+    const devPackages = Object.entries(devDeps ?? {}).map(([pkg, ver]) => (ver ? `${pkg}@${ver}` : pkg));
+    if (devPackages.length > 0) {
+        console.log(`\n📥 npm (dev): ${devPackages.join(", ")}`);
+        const proc = spawn(["bun", "add", "--dev", ...devPackages], { stdout: "inherit", stderr: "inherit", cwd });
+        if ((await proc.exited) !== 0) {
+            console.warn(`⚠️  bun add --dev failed for: ${devPackages.join(", ")}`);
+        }
+    }
+}
+
+// ─── HTTP helpers ─────────────────────────────────────────
+
+async function fetchJSON<T>(url: string): Promise<T> {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to fetch ${url} (${res.status})`);
+    return res.json() as Promise<T>;
+}
+
+async function fetchText(url: string): Promise<string> {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to fetch ${url} (${res.status})`);
+    return res.text();
+}