@ollie-shop/cli 1.4.0 → 1.5.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @ollie-shop/cli@1.4.0 build /home/runner/work/ollie-shop/ollie-shop/packages/cli
+> @ollie-shop/cli@1.5.0 build /home/runner/work/ollie-shop/ollie-shop/packages/cli
 > tsup
 
 CLI Building entry: src/index.tsx
@@ -9,5 +9,5 @@
 CLI Target: node22
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 93.69 KB
-ESM ⚡️ Build success in 295ms
+ESM dist/index.js 105.76 KB
+ESM ⚡️ Build success in 353ms

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ollie-shop/cli
 
+## 1.5.0
+
+### Minor Changes
+
+- 54cca83: Make `ollie.json` the source of truth for Studio components via a `components` map (`{ id: { path, slot } }`), replacing per-folder `meta.json` while staying backward-compatible: existing `meta.json` projects keep working, and folders not referenced anywhere are still discovered as unlinked. Add a `setup` command that migrates legacy `meta.json` / `meta.{stage}.json` files into the config map and removes the old metas (`--dry-run` supported). The dev server exposes `/stages` and `/stage` endpoints for runtime stage switching, and the manifest now carries `otherStage` (component owned by another stage's config) and `unlinked` (no component id) flags. All additive — older Studio clients ignore the new endpoints and fields.
+
+## 1.4.1
+
+### Patch Changes
+
+- 630ae3e: Keep Studio live reload working after a component is added or removed. The dev server proxy now owns the `/esbuild` connection and re-subscribes across context recreates, so the browser's EventSource no longer drops when the esbuild context is disposed.
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/index.js

@@ -70,6 +70,10 @@ function HelpCommand() {
         /* @__PURE__ */ jsx(Box, { width: 24, children: /* @__PURE__ */ jsx(Text, { color: "green", children: "init" }) }),
         /* @__PURE__ */ jsx(Text, { children: "Write store/version IDs to ollie.json" })
       ] }),
+      /* @__PURE__ */ jsxs(Box, { children: [
+        /* @__PURE__ */ jsx(Box, { width: 24, children: /* @__PURE__ */ jsx(Text, { color: "green", children: "setup" }) }),
+        /* @__PURE__ */ jsx(Text, { children: "Migrate legacy meta.json into the config components map" })
+      ] }),
       /* @__PURE__ */ jsxs(Box, { children: [
         /* @__PURE__ */ jsx(Box, { width: 24, children: /* @__PURE__ */ jsx(Text, { color: "green", children: "help" }) }),
         /* @__PURE__ */ jsx(Text, { children: "Show this help message" })
@@ -386,9 +390,14 @@ import { useCallback, useEffect as useEffect2, useRef, useState as useState2 } f
 import fs2 from "fs/promises";
 import path2 from "path";
 import { z } from "zod";
+var ComponentEntrySchema = z.object({
+  path: z.string(),
+  slot: z.string().optional()
+});
 var OllieConfigSchema = z.object({
   storeId: z.string().uuid(),
-  versionId: z.string().uuid().optional()
+  versionId: z.string().uuid().optional(),
+  components: z.record(z.string(), ComponentEntrySchema).optional()
 }).passthrough();
 var CONFIG_FILE = "ollie.json";
 function getConfigFileName(stage) {
@@ -443,6 +452,51 @@ async function saveConfig(config, options = {}) {
   };
   await fs2.writeFile(configPath, JSON.stringify(merged, null, 2));
 }
+async function listStages(cwd = process.cwd()) {
+  let files;
+  try {
+    files = await fs2.readdir(cwd);
+  } catch {
+    return [];
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const stages = [];
+  for (const file of files.sort()) {
+    const match = file.match(/^ollie(?:\.([^.]+))?\.json$/);
+    if (!match) continue;
+    const stage = match[1] ?? "prod";
+    if (seen.has(stage)) continue;
+    seen.add(stage);
+    let versionId;
+    try {
+      const config = await loadConfig({ cwd, stage: match[1] });
+      versionId = config?.versionId;
+    } catch {
+    }
+    stages.push({ stage, versionId });
+  }
+  return stages;
+}
+async function upsertComponentEntry(id, values, options = {}) {
+  const { cwd = process.cwd(), stage } = options;
+  const configPath = path2.join(cwd, getConfigFileName(stage));
+  const existing = await loadConfigFile(configPath) ?? {};
+  const components = {
+    ...existing.components ?? {}
+  };
+  const prev = components[id];
+  const slot = values.slot ?? prev?.slot;
+  const entry = {
+    path: prev?.path ?? values.defaultPath,
+    ...slot !== void 0 ? { slot } : {}
+  };
+  components[id] = entry;
+  await fs2.writeFile(
+    configPath,
+    JSON.stringify({ ...existing, components }, null, 2)
+  );
+  return entry;
+}
 function resolveStage(cliStage) {
   return cliStage || process.env.OLLIE_STAGE || void 0;
 }
@@ -579,19 +633,84 @@ async function readComponentMeta(componentDir, stage) {
     return null;
   }
 }
+async function componentsByDir(cwd, stageLabel) {
+  const byDir = /* @__PURE__ */ new Map();
+  let config = null;
+  try {
+    config = await loadConfig({ cwd, stage: stageLabel });
+  } catch {
+    return byDir;
+  }
+  for (const [id, entry] of Object.entries(config?.components ?? {})) {
+    const dir = path4.resolve(cwd, entry.path);
+    if (!byDir.has(dir)) byDir.set(dir, { id, slot: entry.slot });
+  }
+  return byDir;
+}
 async function discoverComponents(options = {}) {
   const { cwd = process.cwd(), stage } = options;
+  const activeStage = stage ?? "prod";
+  const buildDir = path4.join(cwd, "node_modules/.ollie", "build");
+  const components = [];
+  const mappedDirs = /* @__PURE__ */ new Set();
+  const activeByDir = await componentsByDir(cwd, activeStage);
+  const otherStageByDir = /* @__PURE__ */ new Map();
+  try {
+    for (const { stage: label } of await listStages(cwd)) {
+      if (label === activeStage) continue;
+      for (const [dir, entry] of await componentsByDir(cwd, label)) {
+        if (!activeByDir.has(dir) && !otherStageByDir.has(dir)) {
+          otherStageByDir.set(dir, entry);
+        }
+      }
+    }
+  } catch {
+  }
+  for (const [componentDir, entry] of activeByDir) {
+    const entryPoint = path4.join(componentDir, "index.tsx");
+    try {
+      await fs4.access(entryPoint);
+    } catch {
+      console.warn(
+        `${entry.id}: ${componentDir}/index.tsx not found - skipping`
+      );
+      continue;
+    }
+    const name = path4.basename(componentDir);
+    mappedDirs.add(componentDir);
+    components.push({
+      id: entry.id,
+      name,
+      slot: entry.slot,
+      entryPoint,
+      outfile: path4.join(buildDir, name, "index.js")
+    });
+  }
   const componentsDir = path4.join(cwd, "components");
   try {
     await fs4.access(componentsDir);
   } catch {
-    return [];
+    return components;
   }
   const entries = await glob("*/index.tsx", { cwd: componentsDir });
-  const components = [];
   for (const entry of entries) {
     const name = path4.dirname(entry);
-    const componentDir = path4.join(componentsDir, name);
+    const componentDir = path4.resolve(componentsDir, name);
+    if (mappedDirs.has(componentDir)) continue;
+    const entryPoint = path4.join(componentsDir, entry);
+    const outfile = path4.join(buildDir, name, "index.js");
+    const other = otherStageByDir.get(componentDir);
+    if (other) {
+      components.push({
+        id: other.id,
+        name,
+        slot: other.slot,
+        otherStage: true,
+        entryPoint,
+        outfile
+      });
+      continue;
+    }
     const meta = await readComponentMeta(componentDir, stage);
     const id = meta?.id ?? `studio-${name}`;
     const isUnlinked = !meta?.id;
@@ -604,8 +723,9 @@ async function discoverComponents(options = {}) {
       id,
       name,
       slot: meta?.slot,
-      entryPoint: path4.join(componentsDir, entry),
-      outfile: path4.join(cwd, "node_modules/.ollie", "build", name, "index.js")
+      ...isUnlinked ? { unlinked: true } : {},
+      entryPoint,
+      outfile
     });
   }
   return components;
@@ -685,23 +805,29 @@ async function startDevServer(options = {}) {
   const servedir = path4.join(cwd, "node_modules/.ollie", "build");
   const componentsDir = path4.join(cwd, "components");
   const internalPort = port + 1;
+  let activeStage = stage ?? "prod";
   let ctx = null;
   let entryNames = /* @__PURE__ */ new Set();
   async function buildAndServe(components) {
     entryNames = new Set(components.map((c) => c.name));
-    ctx = await createBuildContext(components, { cwd, stage, onBuildEnd });
+    ctx = await createBuildContext(components, {
+      cwd,
+      stage: activeStage,
+      onBuildEnd
+    });
     await ctx.rebuild();
     await ctx.watch();
     await ctx.serve({ port: internalPort, host, servedir, onRequest });
   }
   async function recreate() {
-    const components = await discoverComponents({ cwd, stage });
+    const components = await discoverComponents({ cwd, stage: activeStage });
     const oldCtx = ctx;
     ctx = null;
     if (oldCtx) await oldCtx.dispose();
     await buildAndServe(components);
+    notifyComponentsChanged(components);
   }
-  await buildAndServe(await discoverComponents({ cwd, stage }));
+  await buildAndServe(await discoverComponents({ cwd, stage: activeStage }));
   async function currentComponentNames() {
     try {
       const entries = await glob("*/index.tsx", { cwd: componentsDir });
@@ -737,8 +863,80 @@ async function startDevServer(options = {}) {
     if (watchTimer) clearTimeout(watchTimer);
     watchTimer = setTimeout(maybeRecreate, 150);
   });
+  const sseClients = /* @__PURE__ */ new Set();
+  let upstreamReq = null;
+  let upstreamRetry = null;
+  function broadcast(chunk) {
+    for (const client of sseClients) {
+      if (!client.writableEnded) client.write(chunk);
+    }
+  }
+  function connectUpstream() {
+    if (upstreamReq || sseClients.size === 0) return;
+    const req = http.request(
+      {
+        hostname: host,
+        port: internalPort,
+        path: "/esbuild",
+        method: "GET",
+        headers: { accept: "text/event-stream" }
+      },
+      (upstream) => {
+        upstream.on("data", broadcast);
+        upstream.on("close", onUpstreamLost);
+        upstream.on("error", onUpstreamLost);
+      }
+    );
+    req.on("error", onUpstreamLost);
+    req.end();
+    upstreamReq = req;
+  }
+  function onUpstreamLost() {
+    if (!upstreamReq) return;
+    upstreamReq = null;
+    if (upstreamRetry) clearTimeout(upstreamRetry);
+    if (sseClients.size === 0) return;
+    upstreamRetry = setTimeout(connectUpstream, 200);
+  }
+  function teardownUpstream() {
+    if (upstreamRetry) {
+      clearTimeout(upstreamRetry);
+      upstreamRetry = null;
+    }
+    const req = upstreamReq;
+    upstreamReq = null;
+    req?.destroy();
+  }
+  function notifyComponentsChanged(components) {
+    if (sseClients.size === 0) return;
+    const updated = components.map((c) => `/${c.name}/index.js`);
+    const payload = JSON.stringify({ added: [], removed: [], updated });
+    broadcast(`event: change
+data: ${payload}
+
+`);
+  }
   const proxyServer = http.createServer(async (req, res) => {
     const url = new URL(req.url || "/", `http://${host}:${port}`);
+    if (url.pathname === "/esbuild" && req.method === "GET") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Private-Network": "true"
+      });
+      res.write("retry: 500\n\n");
+      sseClients.add(res);
+      connectUpstream();
+      const dropClient = () => {
+        sseClients.delete(res);
+        if (sseClients.size === 0) teardownUpstream();
+      };
+      req.on("close", dropClient);
+      res.on("error", dropClient);
+      return;
+    }
     if (url.pathname === "/bundle" && req.method === "GET") {
       const componentPath = url.searchParams.get("path");
       if (!componentPath) {
@@ -786,6 +984,55 @@ async function startDevServer(options = {}) {
       }
       return;
     }
+    if (url.pathname === "/stages" && req.method === "GET") {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+      res.setHeader("Content-Type", "application/json");
+      const stages = await listStages(cwd);
+      res.end(JSON.stringify({ active: activeStage, stages }));
+      return;
+    }
+    if (url.pathname === "/stage" && req.method === "POST") {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+      let body = "";
+      req.on("data", (chunk) => {
+        body += chunk.toString();
+      });
+      req.on("end", async () => {
+        try {
+          const { stage: next } = JSON.parse(body);
+          if (typeof next !== "string" || !next) {
+            res.statusCode = 400;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ error: "Missing 'stage' in body" }));
+            return;
+          }
+          activeStage = next;
+          await recreate();
+          let versionId;
+          try {
+            versionId = (await loadConfig({ cwd, stage: activeStage }))?.versionId;
+          } catch {
+          }
+          res.setHeader("Content-Type", "application/json");
+          res.end(
+            JSON.stringify({ success: true, stage: activeStage, versionId })
+          );
+        } catch (err) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "application/json");
+          res.end(
+            JSON.stringify({
+              error: err instanceof Error ? err.message : "Invalid JSON body"
+            })
+          );
+        }
+      });
+      return;
+    }
     if (url.pathname === "/meta" && req.method === "POST") {
       const componentName = url.searchParams.get("component");
       if (!componentName) {
@@ -807,6 +1054,32 @@ async function startDevServer(options = {}) {
       req.on("end", async () => {
         try {
           const updates = JSON.parse(body);
+          let cfg = null;
+          try {
+            cfg = await loadConfig({ cwd, stage: activeStage });
+          } catch {
+          }
+          if (cfg?.components !== void 0) {
+            const id = typeof updates.id === "string" ? updates.id : void 0;
+            if (!id) {
+              res.statusCode = 400;
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify({ error: "Missing 'id' in body" }));
+              return;
+            }
+            const slot = typeof updates.slot === "string" ? updates.slot : void 0;
+            const entry = await upsertComponentEntry(
+              id,
+              { defaultPath: `components/${componentName}`, slot },
+              { cwd, stage: activeStage }
+            );
+            await ctx?.rebuild();
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({ success: true, component: { id, ...entry } })
+            );
+            return;
+          }
           const metaPath = path4.join(
             cwd,
             "components",
@@ -896,6 +1169,9 @@ async function startDevServer(options = {}) {
     stop: async () => {
       if (watchTimer) clearTimeout(watchTimer);
       componentsWatcher.close();
+      teardownUpstream();
+      for (const client of sseClients) client.end();
+      sseClients.clear();
       proxyServer.close();
       await ctx?.dispose();
     }
@@ -910,7 +1186,9 @@ async function writeManifest(components, buildResult, cwd = process.cwd()) {
         id: c.id,
         name: c.name,
         js: `/${c.name}/index.js`,
-        slot: c.slot
+        slot: c.slot,
+        ...c.otherStage ? { otherStage: true } : {},
+        ...c.unlinked ? { unlinked: true } : {}
       };
       const cssPath = path4.join(outdir, c.name, "index.css");
       try {
@@ -1264,7 +1542,7 @@ function App({ command, args }) {
   }
 }
 function VersionCommand() {
-  const version = "1.4.0" ? "1.4.0" : "unknown";
+  const version = "1.5.0" ? "1.5.0" : "unknown";
   return /* @__PURE__ */ jsx4(Box4, { children: /* @__PURE__ */ jsxs4(Text4, { children: [
     "ollieshop v",
     version
@@ -2417,6 +2695,115 @@ async function schemaCommand(parsed2) {
 `);
 }
 
+// src/commands/setup-cmd.ts
+import fs5 from "fs/promises";
+import path5 from "path";
+import { glob as glob2 } from "glob";
+var META_FILE_RE = /^meta(?:\.([^.]+))?\.json$/;
+function configFileForStage(stage) {
+  return !stage || stage === "prod" ? "ollie.json" : `ollie.${stage}.json`;
+}
+async function setupCommand(parsed2) {
+  const format = detectOutputFormat(parsed2.global.output);
+  const cwd = process.cwd();
+  const dryRun = parsed2.global.dryRun;
+  try {
+    const componentsDir = path5.join(cwd, "components");
+    let folders = [];
+    try {
+      await fs5.access(componentsDir);
+      const entries = await glob2("*/index.tsx", { cwd: componentsDir });
+      folders = entries.map((entry) => path5.dirname(entry));
+    } catch {
+    }
+    const migrated = [];
+    const skipped = [];
+    for (const name of folders) {
+      const folderDir = path5.join(componentsDir, name);
+      const metaFiles = await glob2("meta*.json", { cwd: folderDir });
+      for (const metaFile of metaFiles) {
+        const match = metaFile.match(META_FILE_RE);
+        if (!match) continue;
+        const stage = match[1];
+        let meta;
+        try {
+          meta = JSON.parse(
+            await fs5.readFile(path5.join(folderDir, metaFile), "utf-8")
+          );
+        } catch {
+          skipped.push({
+            component: name,
+            metaFile,
+            reason: "unreadable meta"
+          });
+          continue;
+        }
+        const id = typeof meta.id === "string" ? meta.id : void 0;
+        if (!id) {
+          skipped.push({
+            component: name,
+            metaFile,
+            reason: "no id (unlinked) - left as-is"
+          });
+          continue;
+        }
+        const slot = typeof meta.slot === "string" ? meta.slot : void 0;
+        if (!dryRun) {
+          await upsertComponentEntry(
+            id,
+            { defaultPath: `components/${name}`, slot },
+            { cwd, stage }
+          );
+          await fs5.rm(path5.join(folderDir, metaFile));
+        }
+        migrated.push({
+          component: name,
+          stage: stage ?? "prod",
+          configFile: configFileForStage(stage),
+          metaFile,
+          id,
+          slot
+        });
+      }
+    }
+    if (format === "json") {
+      outputResult(
+        { data: { dryRun, migrated, skipped } },
+        format,
+        parsed2.global.fields
+      );
+      return;
+    }
+    const prefix = dryRun ? "\x1B[33m[dry-run]\x1B[0m " : "";
+    if (migrated.length === 0) {
+      console.log(`${prefix}No legacy meta files to migrate.`);
+    } else {
+      console.log(
+        `${prefix}\x1B[1mMigrated ${migrated.length} meta file(s) to config:\x1B[0m`
+      );
+      for (const entry of migrated) {
+        const slotLabel = entry.slot ? `, slot ${entry.slot}` : "";
+        const removed = dryRun ? "" : `  [removed ${entry.metaFile}]`;
+        console.log(
+          `  ${entry.configFile.padEnd(16)} ${entry.component}  (id ${entry.id}${slotLabel})${removed}`
+        );
+      }
+    }
+    if (skipped.length > 0) {
+      console.log("\n\x1B[2mSkipped:\x1B[0m");
+      for (const entry of skipped) {
+        console.log(`  ${entry.component}/${entry.metaFile}: ${entry.reason}`);
+      }
+    }
+  } catch (err) {
+    outputResult(
+      { error: { message: err instanceof Error ? err.message : String(err) } },
+      format
+    );
+    process.exit(1);
+  }
+}
+
 // src/commands/status-cmd.ts
 async function statusCommand(parsed2) {
   const format = detectOutputFormat(parsed2.global.output);
@@ -2800,7 +3187,8 @@ var AGENT_COMMANDS = {
   schema: schemaCommand,
   init: initCommand,
   deploy: deployCommand,
-  status: statusCommand
+  status: statusCommand,
+  setup: setupCommand
 };
 var parsed = parseArgs(process.argv);
 if (parsed.command in AGENT_COMMANDS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ollie-shop/cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Ollie Shop CLI - Development tools for custom checkouts",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/help.tsx

@@ -91,6 +91,12 @@ export function HelpCommand() {
           </Box>
           <Text>Write store/version IDs to ollie.json</Text>
         </Box>
+        <Box>
+          <Box width={24}>
+            <Text color="green">setup</Text>
+          </Box>
+          <Text>Migrate legacy meta.json into the config components map</Text>
+        </Box>
         <Box>
           <Box width={24}>
             <Text color="green">help</Text>

package/src/commands/setup-cmd.ts

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+import { upsertComponentEntry } from "../utils/config.js";
+import { detectOutputFormat, outputResult } from "../utils/output.js";
+import type { ParsedArgs } from "../utils/parse-args.js";
+
+const META_FILE_RE = /^meta(?:\.([^.]+))?\.json$/;
+
+function configFileForStage(stage?: string): string {
+  return !stage || stage === "prod" ? "ollie.json" : `ollie.${stage}.json`;
+}
+
+interface MigratedMeta {
+  component: string;
+  stage: string;
+  configFile: string;
+  metaFile: string;
+  id: string;
+  slot?: string;
+}
+
+/**
+ * Migrates legacy per-folder meta.json / meta.{stage}.json into the config
+ * `components` map (meta.json -> ollie.json, meta.{stage}.json -> ollie.{stage}.json)
+ * and removes the migrated meta files. Local-only metas (no id) are left in place.
+ */
+export async function setupCommand(parsed: ParsedArgs): Promise<void> {
+  const format = detectOutputFormat(parsed.global.output);
+  const cwd = process.cwd();
+  const dryRun = parsed.global.dryRun;
+
+  try {
+    const componentsDir = path.join(cwd, "components");
+    let folders: string[] = [];
+    try {
+      await fs.access(componentsDir);
+      const entries = await glob("*/index.tsx", { cwd: componentsDir });
+      folders = entries.map((entry) => path.dirname(entry));
+    } catch {
+      // No components directory
+    }
+
+    const migrated: MigratedMeta[] = [];
+    const skipped: Array<{
+      component: string;
+      metaFile: string;
+      reason: string;
+    }> = [];
+
+    for (const name of folders) {
+      const folderDir = path.join(componentsDir, name);
+      const metaFiles = await glob("meta*.json", { cwd: folderDir });
+
+      for (const metaFile of metaFiles) {
+        const match = metaFile.match(META_FILE_RE);
+        if (!match) continue;
+        const stage = match[1];
+
+        let meta: { id?: unknown; slot?: unknown };
+        try {
+          meta = JSON.parse(
+            await fs.readFile(path.join(folderDir, metaFile), "utf-8"),
+          );
+        } catch {
+          skipped.push({
+            component: name,
+            metaFile,
+            reason: "unreadable meta",
+          });
+          continue;
+        }
+
+        const id = typeof meta.id === "string" ? meta.id : undefined;
+        if (!id) {
+          skipped.push({
+            component: name,
+            metaFile,
+            reason: "no id (unlinked) - left as-is",
+          });
+          continue;
+        }
+        const slot = typeof meta.slot === "string" ? meta.slot : undefined;
+
+        if (!dryRun) {
+          await upsertComponentEntry(
+            id,
+            { defaultPath: `components/${name}`, slot },
+            { cwd, stage },
+          );
+          await fs.rm(path.join(folderDir, metaFile));
+        }
+
+        migrated.push({
+          component: name,
+          stage: stage ?? "prod",
+          configFile: configFileForStage(stage),
+          metaFile,
+          id,
+          slot,
+        });
+      }
+    }
+
+    if (format === "json") {
+      outputResult(
+        { data: { dryRun, migrated, skipped } },
+        format,
+        parsed.global.fields,
+      );
+      return;
+    }
+
+    const prefix = dryRun ? "\x1b[33m[dry-run]\x1b[0m " : "";
+    if (migrated.length === 0) {
+      console.log(`${prefix}No legacy meta files to migrate.`);
+    } else {
+      console.log(
+        `${prefix}\x1b[1mMigrated ${migrated.length} meta file(s) to config:\x1b[0m`,
+      );
+      for (const entry of migrated) {
+        const slotLabel = entry.slot ? `, slot ${entry.slot}` : "";
+        const removed = dryRun ? "" : `  [removed ${entry.metaFile}]`;
+        console.log(
+          `  ${entry.configFile.padEnd(16)} ${entry.component}  (id ${entry.id}${slotLabel})${removed}`,
+        );
+      }
+    }
+    if (skipped.length > 0) {
+      console.log("\n\x1b[2mSkipped:\x1b[0m");
+      for (const entry of skipped) {
+        console.log(`  ${entry.component}/${entry.metaFile}: ${entry.reason}`);
+      }
+    }
+  } catch (err) {
+    outputResult(
+      { error: { message: err instanceof Error ? err.message : String(err) } },
+      format,
+    );
+    process.exit(1);
+  }
+}

package/src/index.tsx

@@ -6,6 +6,7 @@ import { deployCommand } from "./commands/deploy-cmd.js";
 import { functionCommand } from "./commands/function-cmd.js";
 import { initCommand } from "./commands/init-cmd.js";
 import { schemaCommand } from "./commands/schema-cmd.js";
+import { setupCommand } from "./commands/setup-cmd.js";
 import { statusCommand } from "./commands/status-cmd.js";
 import { storeCommand } from "./commands/store-cmd.js";
 import { versionCommand } from "./commands/version-cmd.js";
@@ -27,6 +28,7 @@ const AGENT_COMMANDS: Record<
   init: initCommand,
   deploy: deployCommand,
   status: statusCommand,
+  setup: setupCommand,
 };
 
 const parsed = parseArgs(process.argv);

package/src/utils/config.ts

@@ -2,10 +2,18 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 
+const ComponentEntrySchema = z.object({
+  path: z.string(),
+  slot: z.string().optional(),
+});
+
+export type ComponentEntry = z.infer<typeof ComponentEntrySchema>;
+
 const OllieConfigSchema = z
   .object({
     storeId: z.string().uuid(),
     versionId: z.string().uuid().optional(),
+    components: z.record(z.string(), ComponentEntrySchema).optional(),
   })
   .passthrough(); // Allow any other fields without validation
 
@@ -114,6 +122,74 @@ export async function saveConfig(
   await fs.writeFile(configPath, JSON.stringify(merged, null, 2));
 }
 
+/**
+ * Lists the stages available in a project by scanning its ollie config files.
+ * ollie.json is the "prod" stage; ollie.{stage}.json is the "{stage}" stage.
+ */
+export async function listStages(
+  cwd: string = process.cwd(),
+): Promise<Array<{ stage: string; versionId?: string }>> {
+  let files: string[];
+  try {
+    files = await fs.readdir(cwd);
+  } catch {
+    return [];
+  }
+
+  const seen = new Set<string>();
+  const stages: Array<{ stage: string; versionId?: string }> = [];
+  for (const file of files.sort()) {
+    const match = file.match(/^ollie(?:\.([^.]+))?\.json$/);
+    if (!match) continue;
+    const stage = match[1] ?? "prod";
+    if (seen.has(stage)) continue;
+    seen.add(stage);
+
+    let versionId: string | undefined;
+    try {
+      const config = await loadConfig({ cwd, stage: match[1] });
+      versionId = config?.versionId;
+    } catch {
+      // List the stage even if its config is invalid/incomplete
+    }
+    stages.push({ stage, versionId });
+  }
+
+  return stages;
+}
+
+/**
+ * Upserts a component entry into the stage's config file (ollie.json or
+ * ollie.{stage}.json). Preserves the existing path/slot when not provided.
+ */
+export async function upsertComponentEntry(
+  id: string,
+  values: { defaultPath: string; slot?: string },
+  options: SaveConfigOptions = {},
+): Promise<ComponentEntry> {
+  const { cwd = process.cwd(), stage } = options;
+  const configPath = path.join(cwd, getConfigFileName(stage));
+
+  const existing = (await loadConfigFile(configPath)) ?? {};
+  const components = {
+    ...((existing.components as Record<string, ComponentEntry>) ?? {}),
+  };
+  const prev = components[id];
+  const slot = values.slot ?? prev?.slot;
+  const entry: ComponentEntry = {
+    path: prev?.path ?? values.defaultPath,
+    ...(slot !== undefined ? { slot } : {}),
+  };
+  components[id] = entry;
+
+  await fs.writeFile(
+    configPath,
+    JSON.stringify({ ...existing, components }, null, 2),
+  );
+
+  return entry;
+}
+
 /**
  * Returns the resolved stage from CLI args or environment.
  * Priority: CLI arg > OLLIE_STAGE env > undefined (defaults to prod behavior)

package/src/utils/esbuild.ts

@@ -5,14 +5,24 @@ import path from "node:path";
 import * as esbuild from "esbuild";
 import { glob } from "glob";
 import { createComponentBundle } from "./bundle.js";
+import {
+  type OllieConfig,
+  listStages,
+  loadConfig,
+  upsertComponentEntry,
+} from "./config.js";
 
 export interface ComponentInfo {
-  /** Component ID from meta.json (UUID) or generated temporary ID (studio-*) */
+  /** Component ID from the ollie config (UUID) or generated temporary ID (studio-*) */
   id: string;
   /** Folder name */
   name: string;
-  /** Target slot for new components (from meta.json) */
+  /** Target slot (from the ollie config) */
   slot?: string;
+  /** True when the folder belongs to another stage's config, not the active one */
+  otherStage?: boolean;
+  /** True when the folder isn't linked to a component id (synthetic studio-* id) */
+  unlinked?: boolean;
   entryPoint: string;
   outfile: string;
 }
@@ -33,7 +43,7 @@ interface ComponentMeta {
 }
 
 /**
- * Reads the meta.json file for a component.
+ * Reads the meta.json file for a component (legacy, per-folder source).
  * Supports stage-specific meta files: meta.{stage}.json
  */
 async function readComponentMeta(
@@ -66,35 +76,118 @@ export interface DiscoverComponentsOptions {
   stage?: string;
 }
 
+/** Maps resolved component dirs -> {id, slot} for a stage's config map. */
+async function componentsByDir(
+  cwd: string,
+  stageLabel: string,
+): Promise<Map<string, { id: string; slot?: string }>> {
+  const byDir = new Map<string, { id: string; slot?: string }>();
+  let config: OllieConfig | null = null;
+  try {
+    config = await loadConfig({ cwd, stage: stageLabel });
+  } catch {
+    return byDir;
+  }
+  for (const [id, entry] of Object.entries(config?.components ?? {})) {
+    const dir = path.resolve(cwd, entry.path);
+    if (!byDir.has(dir)) byDir.set(dir, { id, slot: entry.slot });
+  }
+  return byDir;
+}
+
 /**
- * Discovers components in the components directory.
- * Each component should have an index.tsx file and a meta.json with its ID.
+ * Discovers components, config-first:
+ * 1. The active stage's `components` map — the source of truth; entries may
+ *    point inside or outside components/.
+ * 2. Folders under components/ that belong to ANOTHER stage's config are
+ *    surfaced with their real id and flagged `otherStage` (hidden by default
+ *    in Studio, shown via "show all").
+ * 3. Remaining folders fall back to legacy per-folder meta.json; folders with
+ *    neither get a temporary studio-* id (unlinked).
  */
 export async function discoverComponents(
   options: DiscoverComponentsOptions = {},
 ): Promise<ComponentInfo[]> {
   const { cwd = process.cwd(), stage } = options;
-  const componentsDir = path.join(cwd, "components");
+  const activeStage = stage ?? "prod";
+  const buildDir = path.join(cwd, "node_modules/.ollie", "build");
+  const components: ComponentInfo[] = [];
+  const mappedDirs = new Set<string>();
+
+  const activeByDir = await componentsByDir(cwd, activeStage);
+
+  // Component dirs claimed by other stages (so we don't mistake them for new)
+  const otherStageByDir = new Map<string, { id: string; slot?: string }>();
+  try {
+    for (const { stage: label } of await listStages(cwd)) {
+      if (label === activeStage) continue;
+      for (const [dir, entry] of await componentsByDir(cwd, label)) {
+        if (!activeByDir.has(dir) && !otherStageByDir.has(dir)) {
+          otherStageByDir.set(dir, entry);
+        }
+      }
+    }
+  } catch {
+    // No other stages
+  }
+
+  // 1. Active stage's config map (source of truth)
+  for (const [componentDir, entry] of activeByDir) {
+    const entryPoint = path.join(componentDir, "index.tsx");
+    try {
+      await fs.access(entryPoint);
+    } catch {
+      console.warn(
+        `${entry.id}: ${componentDir}/index.tsx not found - skipping`,
+      );
+      continue;
+    }
+    const name = path.basename(componentDir);
+    mappedDirs.add(componentDir);
+    components.push({
+      id: entry.id,
+      name,
+      slot: entry.slot,
+      entryPoint,
+      outfile: path.join(buildDir, name, "index.js"),
+    });
+  }
 
+  // 2. Folders under components/ not in the active map
+  const componentsDir = path.join(cwd, "components");
   try {
     await fs.access(componentsDir);
   } catch {
-    return [];
+    return components;
   }
 
   const entries = await glob("*/index.tsx", { cwd: componentsDir });
-  const components: ComponentInfo[] = [];
-
   for (const entry of entries) {
     const name = path.dirname(entry);
-    const componentDir = path.join(componentsDir, name);
-    const meta = await readComponentMeta(componentDir, stage);
+    const componentDir = path.resolve(componentsDir, name);
+    if (mappedDirs.has(componentDir)) continue;
+
+    const entryPoint = path.join(componentsDir, entry);
+    const outfile = path.join(buildDir, name, "index.js");
+
+    // Belongs to another stage's config: surface with its real id, flagged
+    const other = otherStageByDir.get(componentDir);
+    if (other) {
+      components.push({
+        id: other.id,
+        name,
+        slot: other.slot,
+        otherStage: true,
+        entryPoint,
+        outfile,
+      });
+      continue;
+    }
 
-    // Components without id (or without meta.json) get a temporary studio-* ID
+    // Legacy per-folder meta.json fallback
+    const meta = await readComponentMeta(componentDir, stage);
     const id = meta?.id ?? `studio-${name}`;
     const isUnlinked = !meta?.id;
-
-    // Unlinked components without a slot can still be built, just not placed in checkout
     if (isUnlinked && !meta?.slot) {
       console.warn(
         `${name}: no slot defined - component will be built but not placed in checkout`,
@@ -105,8 +198,9 @@ export async function discoverComponents(
       id,
       name,
       slot: meta?.slot,
-      entryPoint: path.join(componentsDir, entry),
-      outfile: path.join(cwd, "node_modules/.ollie", "build", name, "index.js"),
+      ...(isUnlinked ? { unlinked: true } : {}),
+      entryPoint,
+      outfile,
     });
   }
 
@@ -250,26 +344,34 @@ export async function startDevServer(
   const componentsDir = path.join(cwd, "components");
   const internalPort = port + 1;
 
+  // The active stage is mutable: the admin can switch it at runtime via POST /stage.
+  let activeStage = stage ?? "prod";
+
   let ctx: esbuild.BuildContext | null = null;
   let entryNames = new Set<string>();
 
   async function buildAndServe(components: ComponentInfo[]): Promise<void> {
     entryNames = new Set(components.map((c) => c.name));
-    ctx = await createBuildContext(components, { cwd, stage, onBuildEnd });
+    ctx = await createBuildContext(components, {
+      cwd,
+      stage: activeStage,
+      onBuildEnd,
+    });
     await ctx.rebuild();
     await ctx.watch();
     await ctx.serve({ port: internalPort, host, servedir, onRequest });
   }
 
   async function recreate(): Promise<void> {
-    const components = await discoverComponents({ cwd, stage });
+    const components = await discoverComponents({ cwd, stage: activeStage });
     const oldCtx = ctx;
     ctx = null;
     if (oldCtx) await oldCtx.dispose();
     await buildAndServe(components);
+    notifyComponentsChanged(components);
   }
 
-  await buildAndServe(await discoverComponents({ cwd, stage }));
+  await buildAndServe(await discoverComponents({ cwd, stage: activeStage }));
 
   async function currentComponentNames(): Promise<Set<string>> {
     try {
@@ -313,10 +415,92 @@ export async function startDevServer(
     watchTimer = setTimeout(maybeRecreate, 150);
   });
 
+  // esbuild's /esbuild live-reload stream lives on the context, so disposing it
+  // during a recreate drops the browser's EventSource — and Studio closes that
+  // connection for good on the first error. The proxy owns the downstream
+  // connection instead and re-subscribes to esbuild's stream across recreates,
+  // so live reload survives a component being added or removed.
+  const sseClients = new Set<http.ServerResponse>();
+  let upstreamReq: http.ClientRequest | null = null;
+  let upstreamRetry: ReturnType<typeof setTimeout> | null = null;
+
+  function broadcast(chunk: string | Buffer): void {
+    for (const client of sseClients) {
+      if (!client.writableEnded) client.write(chunk);
+    }
+  }
+
+  function connectUpstream(): void {
+    if (upstreamReq || sseClients.size === 0) return;
+    const req = http.request(
+      {
+        hostname: host,
+        port: internalPort,
+        path: "/esbuild",
+        method: "GET",
+        headers: { accept: "text/event-stream" },
+      },
+      (upstream) => {
+        upstream.on("data", broadcast);
+        upstream.on("close", onUpstreamLost);
+        upstream.on("error", onUpstreamLost);
+      },
+    );
+    req.on("error", onUpstreamLost);
+    req.end();
+    upstreamReq = req;
+  }
+
+  function onUpstreamLost(): void {
+    if (!upstreamReq) return;
+    upstreamReq = null;
+    if (upstreamRetry) clearTimeout(upstreamRetry);
+    if (sseClients.size === 0) return;
+    upstreamRetry = setTimeout(connectUpstream, 200);
+  }
+
+  function teardownUpstream(): void {
+    if (upstreamRetry) {
+      clearTimeout(upstreamRetry);
+      upstreamRetry = null;
+    }
+    const req = upstreamReq;
+    upstreamReq = null;
+    req?.destroy();
+  }
+
+  function notifyComponentsChanged(components: ComponentInfo[]): void {
+    if (sseClients.size === 0) return;
+    const updated = components.map((c) => `/${c.name}/index.js`);
+    const payload = JSON.stringify({ added: [], removed: [], updated });
+    broadcast(`event: change\ndata: ${payload}\n\n`);
+  }
+
   // Create proxy server that handles /bundle/* and forwards to esbuild
   const proxyServer = http.createServer(async (req, res) => {
     const url = new URL(req.url || "/", `http://${host}:${port}`);
 
+    // Hold the Studio live-reload stream open across esbuild recreates
+    if (url.pathname === "/esbuild" && req.method === "GET") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Private-Network": "true",
+      });
+      res.write("retry: 500\n\n");
+      sseClients.add(res);
+      connectUpstream();
+      const dropClient = () => {
+        sseClients.delete(res);
+        if (sseClients.size === 0) teardownUpstream();
+      };
+      req.on("close", dropClient);
+      res.on("error", dropClient);
+      return;
+    }
+
     // Handle /bundle?path=/ComponentName/index.js
     if (url.pathname === "/bundle" && req.method === "GET") {
       const componentPath = url.searchParams.get("path");
@@ -376,6 +560,62 @@ export async function startDevServer(
       return;
     }
 
+    // List available stages (from local ollie*.json) and the active one
+    if (url.pathname === "/stages" && req.method === "GET") {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+      res.setHeader("Content-Type", "application/json");
+      const stages = await listStages(cwd);
+      res.end(JSON.stringify({ active: activeStage, stages }));
+      return;
+    }
+
+    // Switch the active stage at runtime: re-discover + rebuild for it
+    if (url.pathname === "/stage" && req.method === "POST") {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+
+      let body = "";
+      req.on("data", (chunk) => {
+        body += chunk.toString();
+      });
+      req.on("end", async () => {
+        try {
+          const { stage: next } = JSON.parse(body) as { stage?: unknown };
+          if (typeof next !== "string" || !next) {
+            res.statusCode = 400;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ error: "Missing 'stage' in body" }));
+            return;
+          }
+          activeStage = next;
+          await recreate();
+          let versionId: string | undefined;
+          try {
+            versionId = (await loadConfig({ cwd, stage: activeStage }))
+              ?.versionId;
+          } catch {
+            // Stage config may be missing/invalid
+          }
+          res.setHeader("Content-Type", "application/json");
+          res.end(
+            JSON.stringify({ success: true, stage: activeStage, versionId }),
+          );
+        } catch (err) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "application/json");
+          res.end(
+            JSON.stringify({
+              error: err instanceof Error ? err.message : "Invalid JSON body",
+            }),
+          );
+        }
+      });
+      return;
+    }
+
     // Handle POST /meta?component=ComponentName to update meta.json
     if (url.pathname === "/meta" && req.method === "POST") {
       const componentName = url.searchParams.get("component");
@@ -404,6 +644,40 @@ export async function startDevServer(
       req.on("end", async () => {
         try {
           const updates = JSON.parse(body) as Record<string, unknown>;
+
+          // A project opts into the config model by having a `components` map.
+          // Otherwise we keep writing the legacy per-folder meta.json.
+          let cfg: OllieConfig | null = null;
+          try {
+            cfg = await loadConfig({ cwd, stage: activeStage });
+          } catch {
+            // Treat as legacy if the config can't be loaded
+          }
+
+          if (cfg?.components !== undefined) {
+            const id = typeof updates.id === "string" ? updates.id : undefined;
+            if (!id) {
+              res.statusCode = 400;
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify({ error: "Missing 'id' in body" }));
+              return;
+            }
+            const slot =
+              typeof updates.slot === "string" ? updates.slot : undefined;
+            const entry = await upsertComponentEntry(
+              id,
+              { defaultPath: `components/${componentName}`, slot },
+              { cwd, stage: activeStage },
+            );
+            // Rebuild so the manifest reflects the new mapping/slot
+            await ctx?.rebuild();
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({ success: true, component: { id, ...entry } }),
+            );
+            return;
+          }
+
           const metaPath = path.join(
             cwd,
             "components",
@@ -520,6 +794,9 @@ export async function startDevServer(
     stop: async () => {
       if (watchTimer) clearTimeout(watchTimer);
       componentsWatcher.close();
+      teardownUpstream();
+      for (const client of sseClients) client.end();
+      sseClients.clear();
       proxyServer.close();
       await ctx?.dispose();
     },
@@ -555,6 +832,10 @@ export interface ManifestEntry {
   css?: string;
   /** Target slot for components */
   slot?: string;
+  /** True when the component belongs to another stage's config */
+  otherStage?: boolean;
+  /** True when the component isn't linked to a component id (studio-*) */
+  unlinked?: boolean;
 }
 
 /**
@@ -604,6 +885,8 @@ export async function writeManifest(
         name: c.name,
         js: `/${c.name}/index.js`,
         slot: c.slot,
+        ...(c.otherStage ? { otherStage: true } : {}),
+        ...(c.unlinked ? { unlinked: true } : {}),
       };
 
       // Check if CSS exists