@stackable-labs/cli-app-extension 1.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+LICENSE
+
+Copyright (c) 2026-present UNIQUELY PARTICULAR LLC, STACKABLE LABS, LLC, agnoStack, Inc., and Adam Grohs ("Author" herein)
+
+Permission is hereby granted to use, copy, and modify this software
+(the "Software") solely for the purpose of developing, testing,
+or maintaining integration with Author's products and services.
+
+The Software may not be used:
+- as a standalone product or service,
+- to integrate with any platform or service other than Author's,
+- to build or enhance a competing product or service,
+- or for any purpose unrelated to integrations with Author.
+
+Redistribution of the Software, in whole or in part, is permitted
+only as part of an application or service that integrates with Author
+and does not expose the Software as a general-purpose library.
+
+This Software is provided "AS IS", without warranty of any kind, express
+or implied, including but not limited to the warranties of merchantability,
+fitness for a particular purpose, and noninfringement.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+PUBLISHER, AUTHORS, ANY CONTRIBUTOR OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @stackable-labs/cli-app-extension
+
+CLI for scaffolding Stackable extension projects from the local `extension-template` package.
+
+## Development
+
+```bash
+pnpm --filter @stackable-labs/cli-app-extension build
+```

package/dist/index.js

@@ -0,0 +1,862 @@
+#!/usr/bin/env node
+
+// src/index.tsx
+import { program } from "commander";
+import { render } from "ink";
+
+// src/App.tsx
+import { Box as Box9, Text as Text9, useApp } from "ink";
+import { useCallback, useState as useState6 } from "react";
+
+// src/components/Confirm.tsx
+import { Box, Text, useInput } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Confirm({ name, extensionId, extensionPort, previewPort, targets, outputDir, onConfirm, onCancel }) {
+  useInput((input, key) => {
+    if (input === "y" || key.return) {
+      onConfirm();
+      return;
+    }
+    if (input === "n" || key.escape) {
+      onCancel();
+    }
+  });
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx(Text, { bold: true, children: "Ready to scaffold" }),
+    /* @__PURE__ */ jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [
+      /* @__PURE__ */ jsxs(Box, { gap: 2, children: [
+        /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Name" }),
+        /* @__PURE__ */ jsx(Text, { children: name })
+      ] }),
+      /* @__PURE__ */ jsxs(Box, { gap: 2, children: [
+        /* @__PURE__ */ jsx(Text, { dimColor: true, children: "ID  " }),
+        /* @__PURE__ */ jsx(Text, { children: extensionId })
+      ] }),
+      /* @__PURE__ */ jsxs(Box, { gap: 2, children: [
+        /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Dir " }),
+        /* @__PURE__ */ jsx(Text, { children: outputDir })
+      ] }),
+      /* @__PURE__ */ jsxs(Box, { gap: 2, children: [
+        /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Extension port" }),
+        /* @__PURE__ */ jsx(Text, { children: extensionPort })
+      ] }),
+      /* @__PURE__ */ jsxs(Box, { gap: 2, children: [
+        /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Preview port   " }),
+        /* @__PURE__ */ jsx(Text, { children: previewPort })
+      ] }),
+      /* @__PURE__ */ jsxs(Box, { gap: 2, flexDirection: "column", children: [
+        /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Targets" }),
+        targets.map((t) => /* @__PURE__ */ jsxs(Box, { marginLeft: 2, children: [
+          /* @__PURE__ */ jsx(Text, { color: "green", children: "\u2022 " }),
+          /* @__PURE__ */ jsx(Text, { children: t })
+        ] }, t))
+      ] })
+    ] }),
+    /* @__PURE__ */ jsxs(Text, { children: [
+      "Proceed? ",
+      /* @__PURE__ */ jsx(Text, { bold: true, color: "green", children: "Y" }),
+      "/",
+      /* @__PURE__ */ jsx(Text, { bold: true, color: "red", children: "n" })
+    ] })
+  ] });
+}
+
+// src/components/DirPrompt.tsx
+import { Box as Box2, Text as Text2 } from "ink";
+import TextInput from "ink-text-input";
+import { useState } from "react";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function DirPrompt({ defaultDir, onSubmit }) {
+  const [value, setValue] = useState(defaultDir);
+  const handleSubmit = (val) => {
+    const trimmed = val.trim();
+    if (trimmed.length === 0) {
+      return;
+    }
+    onSubmit(trimmed);
+  };
+  return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx2(Text2, { bold: true, children: "Output directory:" }),
+    /* @__PURE__ */ jsxs2(Box2, { children: [
+      /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: "\u2192 " }),
+      /* @__PURE__ */ jsx2(TextInput, { value, onChange: setValue, onSubmit: handleSubmit })
+    ] }),
+    /* @__PURE__ */ jsx2(Text2, { dimColor: true, children: "(Press Enter to confirm)" })
+  ] });
+}
+
+// src/components/Done.tsx
+import { Box as Box3, Text as Text3 } from "ink";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function Done({ name, outputDir }) {
+  return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsxs3(Box3, { gap: 1, children: [
+      /* @__PURE__ */ jsx3(Text3, { color: "green", bold: true, children: "\u2714" }),
+      /* @__PURE__ */ jsx3(Text3, { bold: true, children: "Extension scaffolded successfully!" })
+    ] }),
+    /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", marginLeft: 2, children: [
+      /* @__PURE__ */ jsxs3(Text3, { dimColor: true, children: [
+        "Created: ",
+        /* @__PURE__ */ jsx3(Text3, { color: "cyan", children: name })
+      ] }),
+      /* @__PURE__ */ jsxs3(Text3, { dimColor: true, children: [
+        "Location: ",
+        /* @__PURE__ */ jsx3(Text3, { color: "cyan", children: outputDir })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", marginTop: 1, borderStyle: "round", borderColor: "green", paddingX: 2, paddingY: 1, children: [
+      /* @__PURE__ */ jsx3(Text3, { bold: true, children: "Next steps:" }),
+      /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", marginTop: 1, gap: 1, children: [
+        /* @__PURE__ */ jsxs3(Box3, { gap: 1, children: [
+          /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "1." }),
+          /* @__PURE__ */ jsxs3(Text3, { children: [
+            /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "cd " }),
+            /* @__PURE__ */ jsx3(Text3, { color: "cyan", children: outputDir })
+          ] })
+        ] }),
+        /* @__PURE__ */ jsxs3(Box3, { gap: 1, children: [
+          /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "2." }),
+          /* @__PURE__ */ jsx3(Text3, { color: "cyan", children: "pnpm install" })
+        ] }),
+        /* @__PURE__ */ jsxs3(Box3, { gap: 1, children: [
+          /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "3." }),
+          /* @__PURE__ */ jsx3(Text3, { color: "cyan", children: "pnpm dev" })
+        ] })
+      ] })
+    ] })
+  ] });
+}
+
+// src/components/IdPrompt.tsx
+import { Box as Box4, Text as Text4 } from "ink";
+import TextInput2 from "ink-text-input";
+import { useEffect, useState as useState2 } from "react";
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+function toKebabCase(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function IdPrompt({ extensionName, onSubmit }) {
+  const derived = toKebabCase(extensionName);
+  const [value, setValue] = useState2(derived);
+  const [error, setError] = useState2();
+  useEffect(() => {
+    setValue(toKebabCase(extensionName));
+  }, [extensionName]);
+  const handleSubmit = (val) => {
+    const trimmed = val.trim() || derived;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(trimmed)) {
+      setError("Extension ID must be lowercase kebab-case (letters, numbers, hyphens only)");
+      return;
+    }
+    setError(void 0);
+    onSubmit(trimmed);
+  };
+  return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx4(Text4, { bold: true, children: "Extension ID" }),
+    /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "Used as the unique identifier in the manifest. Press Enter to accept the default." }),
+    /* @__PURE__ */ jsxs4(Box4, { children: [
+      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "> " }),
+      /* @__PURE__ */ jsx4(TextInput2, { value, onChange: setValue, onSubmit: handleSubmit })
+    ] }),
+    error && /* @__PURE__ */ jsx4(Text4, { color: "red", children: error })
+  ] });
+}
+
+// src/components/NamePrompt.tsx
+import { Box as Box5, Text as Text5 } from "ink";
+import TextInput3 from "ink-text-input";
+import { useState as useState3 } from "react";
+import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
+function NamePrompt({ initialValue = "", onSubmit }) {
+  const [value, setValue] = useState3(initialValue);
+  const [error, setError] = useState3();
+  const handleSubmit = (val) => {
+    const trimmed = val.trim();
+    if (trimmed.length === 0) {
+      setError("Extension name is required");
+      return;
+    }
+    setError(void 0);
+    onSubmit(trimmed);
+  };
+  return /* @__PURE__ */ jsxs5(Box5, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx5(Text5, { bold: true, children: "What is your extension name?" }),
+    /* @__PURE__ */ jsxs5(Box5, { children: [
+      /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: "> " }),
+      /* @__PURE__ */ jsx5(TextInput3, { value, onChange: setValue, onSubmit: handleSubmit })
+    ] }),
+    error && /* @__PURE__ */ jsx5(Text5, { color: "red", children: error })
+  ] });
+}
+
+// src/components/PortsPrompt.tsx
+import { Box as Box6, Text as Text6 } from "ink";
+import TextInput4 from "ink-text-input";
+import { useState as useState4 } from "react";
+import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
+function PortsPrompt({ onSubmit }) {
+  const [extensionPort, setExtensionPort] = useState4("5173");
+  const [previewPort, setPreviewPort] = useState4("");
+  const [step, setStep] = useState4("extension");
+  const handleExtensionSubmit = (value) => {
+    const trimmed = value.trim();
+    const port = trimmed === "" ? 5173 : parseInt(trimmed, 10);
+    if (isNaN(port) || port < 1024 || port > 65535) {
+      return;
+    }
+    setExtensionPort(String(port));
+    setPreviewPort(String(port + 1));
+    setStep("preview");
+  };
+  const handlePreviewSubmit = (value) => {
+    const extPort = parseInt(extensionPort, 10);
+    const trimmed = value.trim();
+    const prevPort = trimmed === "" ? extPort + 1 : parseInt(trimmed, 10);
+    if (isNaN(prevPort) || prevPort < 1024 || prevPort > 65535) {
+      return;
+    }
+    onSubmit(extPort, prevPort);
+  };
+  if (step === "extension") {
+    return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", gap: 1, children: [
+      /* @__PURE__ */ jsx6(Text6, { bold: true, children: "Extension dev server port:" }),
+      /* @__PURE__ */ jsxs6(Box6, { children: [
+        /* @__PURE__ */ jsx6(Text6, { color: "cyan", children: "\u2192 " }),
+        /* @__PURE__ */ jsx6(
+          TextInput4,
+          {
+            value: extensionPort,
+            onChange: setExtensionPort,
+            onSubmit: handleExtensionSubmit,
+            placeholder: "5173"
+          }
+        )
+      ] }),
+      /* @__PURE__ */ jsx6(Text6, { dimColor: true, children: "(Press Enter to use default: 5173)" })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx6(Text6, { bold: true, children: "Preview host dev server port:" }),
+    /* @__PURE__ */ jsxs6(Box6, { children: [
+      /* @__PURE__ */ jsx6(Text6, { color: "cyan", children: "\u2192 " }),
+      /* @__PURE__ */ jsx6(
+        TextInput4,
+        {
+          value: previewPort,
+          onChange: setPreviewPort,
+          onSubmit: handlePreviewSubmit,
+          placeholder: String(parseInt(extensionPort, 10) + 1)
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsxs6(Text6, { dimColor: true, children: [
+      "(Press Enter to use: ",
+      parseInt(extensionPort, 10) + 1,
+      ")"
+    ] })
+  ] });
+}
+
+// src/components/ScaffoldProgress.tsx
+import { Box as Box7, Text as Text7 } from "ink";
+import Spinner from "ink-spinner";
+import { jsx as jsx7, jsxs as jsxs7 } from "react/jsx-runtime";
+function stepIcon(status) {
+  switch (status) {
+    case "running":
+      return /* @__PURE__ */ jsx7(Spinner, { type: "dots" });
+    case "done":
+      return /* @__PURE__ */ jsx7(Text7, { color: "green", children: "\u2714" });
+    case "error":
+      return /* @__PURE__ */ jsx7(Text7, { color: "red", children: "\u2716" });
+    default:
+      return /* @__PURE__ */ jsx7(Text7, { dimColor: true, children: "\u25CB" });
+  }
+}
+function ScaffoldProgress({ steps }) {
+  return /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx7(Text7, { bold: true, children: "Scaffolding your extension\u2026" }),
+    /* @__PURE__ */ jsx7(Box7, { flexDirection: "column", children: steps.map((step) => /* @__PURE__ */ jsxs7(Box7, { gap: 2, children: [
+      stepIcon(step.status),
+      /* @__PURE__ */ jsx7(Text7, { dimColor: step.status === "pending", color: step.status === "running" ? "cyan" : void 0, children: step.label })
+    ] }, step.label)) })
+  ] });
+}
+
+// src/components/TargetSelect.tsx
+import { Box as Box8, Text as Text8, useInput as useInput2 } from "ink";
+import { useState as useState5 } from "react";
+
+// src/constants.ts
+var TARGET_OPTIONS = [
+  "slot.header",
+  "slot.content",
+  "slot.footer",
+  "slot.footer-links"
+];
+var CAPABILITY_PERMISSION_MAP = {
+  "slot.header": ["context:read"],
+  "slot.content": ["context:read", "data:query", "actions:toast", "actions:invoke"],
+  "slot.footer": [],
+  "slot.footer-links": []
+};
+var DEFAULT_PERMISSION_FALLBACK = ["context:read"];
+var TEMPLATE_SOURCE = "github:stackable-labs/templates/app-extension";
+
+// src/components/TargetSelect.tsx
+import { jsx as jsx8, jsxs as jsxs8 } from "react/jsx-runtime";
+var TARGET_DESCRIPTIONS = {
+  "slot.header": "Renders content in the panel header area",
+  "slot.content": "Renders the main panel body (includes store + navigation state)",
+  "slot.footer": "Renders a footer bar at the bottom of the panel",
+  "slot.footer-links": "Renders a link row in the global footer"
+};
+function TargetSelect({ onSubmit }) {
+  const [cursor, setCursor] = useState5(0);
+  const [selected, setSelected] = useState5(/* @__PURE__ */ new Set(["slot.content"]));
+  const [error, setError] = useState5();
+  useInput2((input, key) => {
+    if (key.upArrow) {
+      setCursor((c) => (c - 1 + TARGET_OPTIONS.length) % TARGET_OPTIONS.length);
+      return;
+    }
+    if (key.downArrow) {
+      setCursor((c) => (c + 1) % TARGET_OPTIONS.length);
+      return;
+    }
+    if (input === " ") {
+      const target = TARGET_OPTIONS[cursor];
+      setSelected((prev) => {
+        const next = new Set(prev);
+        if (next.has(target)) {
+          next.delete(target);
+        } else {
+          next.add(target);
+        }
+        return next;
+      });
+      setError(void 0);
+      return;
+    }
+    if (key.return) {
+      if (selected.size === 0) {
+        setError("Select at least one target slot");
+        return;
+      }
+      onSubmit([...selected]);
+    }
+  });
+  return /* @__PURE__ */ jsxs8(Box8, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx8(Text8, { bold: true, children: "Select target slots" }),
+    /* @__PURE__ */ jsx8(Text8, { dimColor: true, children: "Space to toggle, Enter to confirm" }),
+    /* @__PURE__ */ jsx8(Box8, { flexDirection: "column", children: TARGET_OPTIONS.map((target, i) => {
+      const isSelected = selected.has(target);
+      const isCursor = i === cursor;
+      return /* @__PURE__ */ jsxs8(Box8, { gap: 1, children: [
+        /* @__PURE__ */ jsx8(Text8, { color: isCursor ? "cyan" : void 0, children: isCursor ? "\u276F" : " " }),
+        /* @__PURE__ */ jsx8(Text8, { color: isSelected ? "green" : void 0, children: isSelected ? "\u25C9" : "\u25CB" }),
+        /* @__PURE__ */ jsxs8(Box8, { flexDirection: "column", children: [
+          /* @__PURE__ */ jsx8(Text8, { bold: isSelected, children: target }),
+          /* @__PURE__ */ jsx8(Text8, { dimColor: true, children: TARGET_DESCRIPTIONS[target] })
+        ] })
+      ] }, target);
+    }) }),
+    error && /* @__PURE__ */ jsx8(Text8, { color: "red", children: error })
+  ] });
+}
+
+// src/lib/postScaffold.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { installDependencies } from "nypm";
+var execFileAsync = promisify(execFile);
+async function postScaffold(options) {
+  if (!options.skipGit) {
+    await gitInit(options.outputDir);
+  }
+  if (!options.skipInstall) {
+    await installDependencies({ cwd: options.outputDir, silent: true });
+  }
+}
+async function gitInit(dir) {
+  try {
+    await execFileAsync("git", ["init"], { cwd: dir });
+    await execFileAsync("git", ["add", "-A"], { cwd: dir });
+    await execFileAsync("git", ["commit", "-m", "chore: initial scaffold"], { cwd: dir });
+  } catch {
+  }
+}
+
+// src/lib/scaffold.ts
+import { downloadTemplate } from "giget";
+import { readFile, readdir, rm, writeFile } from "fs/promises";
+import { join } from "path";
+async function scaffold(options) {
+  const { dir } = await downloadTemplate(TEMPLATE_SOURCE, {
+    dir: options.outputDir,
+    force: true
+  });
+  const selectedTargets = normalizeTargets(options.targets);
+  const derivedPermissions = derivePermissions(selectedTargets);
+  await replacePlaceholders(dir, {
+    "__EXTENSION_ID__": toKebabCase2(options.extensionId || options.name),
+    "__EXTENSION_DISPLAY_NAME__": options.name,
+    "replace-with-extension-name": toKebabCase2(options.name),
+    "replace-with-extension-package-name": `@agnostack/extensions-${toKebabCase2(options.extensionId || options.name)}`
+  });
+  await generateManifest(dir, options.name, selectedTargets, derivedPermissions);
+  await generateSurfaceFiles(dir, selectedTargets);
+  await rewriteExtensionIndex(dir, options.extensionId || options.name, selectedTargets);
+  await rewritePreviewApp(dir, selectedTargets, derivedPermissions);
+  await rewriteTurboJson(dir);
+  await writeEnvFile(dir, options.extensionPort, options.previewPort);
+  return options;
+}
+function normalizeTargets(targets) {
+  const valid = new Set(TARGET_OPTIONS);
+  const selected = targets.filter((target) => valid.has(target));
+  if (selected.length > 0) {
+    return Array.from(new Set(selected));
+  }
+  return ["slot.content"];
+}
+function derivePermissions(targets) {
+  const permissions = /* @__PURE__ */ new Set();
+  for (const target of targets) {
+    for (const permission of CAPABILITY_PERMISSION_MAP[target]) {
+      permissions.add(permission);
+    }
+  }
+  if (permissions.size === 0) {
+    for (const fallback of DEFAULT_PERMISSION_FALLBACK) {
+      permissions.add(fallback);
+    }
+  }
+  return [...permissions];
+}
+function toKebabCase2(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function replacePlaceholders(rootDir, replacements) {
+  const files = await walkFiles(rootDir);
+  for (const filePath of files) {
+    if (!isTextFile(filePath)) {
+      continue;
+    }
+    let content = await readFile(filePath, "utf8");
+    let changed = false;
+    for (const [needle, value] of Object.entries(replacements)) {
+      if (content.includes(needle)) {
+        content = content.split(needle).join(value);
+        changed = true;
+      }
+    }
+    if (changed) {
+      await writeFile(filePath, content);
+    }
+  }
+}
+async function generateManifest(rootDir, extensionName, targets, permissions) {
+  const manifestPath = join(rootDir, "packages/extension/public/manifest.json");
+  const raw = await readFile(manifestPath, "utf8");
+  const manifest = JSON.parse(raw);
+  manifest.name = extensionName;
+  manifest.targets = targets;
+  manifest.permissions = permissions;
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+}
+async function generateSurfaceFiles(rootDir, targets) {
+  const surfaceDir = join(rootDir, "packages/extension/src/surfaces");
+  const wantsHeader = targets.includes("slot.header");
+  const wantsContent = targets.includes("slot.content");
+  const wantsFooter = targets.includes("slot.footer") || targets.includes("slot.footer-links");
+  await upsertOrRemove(
+    join(surfaceDir, "Header.tsx"),
+    wantsHeader,
+    `import { ui, Surface } from '@stackable-labs/sdk-extension-react'
+
+export function Header() {
+  return (
+    <Surface id="slot.header">
+      <ui.Text>Header content goes here</ui.Text>
+    </Surface>
+  )
+}
+`
+  );
+  await upsertOrRemove(
+    join(surfaceDir, "Content.tsx"),
+    wantsContent,
+    `import { ui, useStore, useContextData, Surface } from '@stackable-labs/sdk-extension-react'
+import { appStore } from '../store'
+
+export function Content() {
+  const viewState = useStore(appStore, (s) => s.viewState)
+  const { loading } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.content">
+        <ui.Stack direction="column" gap="2" className="animate-pulse">
+          <ui.Card className="h-24" />
+          <ui.Card className="h-32" />
+        </ui.Stack>
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.content">
+      {viewState.type === 'menu' && (
+        <ui.Menu>
+          {/* Add ui.MenuItem entries here */}
+        </ui.Menu>
+      )}
+    </Surface>
+  )
+}
+`
+  );
+  await upsertOrRemove(
+    join(rootDir, "packages/extension/src/store.ts"),
+    wantsContent,
+    `import { createStore } from '@stackable-labs/sdk-extension-react'
+
+export type ViewState = { type: 'menu' }
+
+export interface AppState {
+  viewState: ViewState
+}
+
+export const appStore = createStore<AppState>({
+  viewState: { type: 'menu' },
+})
+`
+  );
+  await upsertOrRemove(join(surfaceDir, "Footer.tsx"), wantsFooter, buildFooterSurface(targets));
+}
+function buildFooterSurface(targets) {
+  const blocks = [];
+  if (targets.includes("slot.footer")) {
+    blocks.push(
+      `      <Surface id="slot.footer">
+        <ui.Text className="text-xs">Powered by My Extension</ui.Text>
+      </Surface>`
+    );
+  }
+  if (targets.includes("slot.footer-links")) {
+    blocks.push(
+      `      <Surface id="slot.footer-links">
+        <ui.FooterLink href="https://example.com">My Extension</ui.FooterLink>
+      </Surface>`
+    );
+  }
+  return `import { ui, Surface } from '@stackable-labs/sdk-extension-react'
+
+export function Footer() {
+  return (
+    <>
+${blocks.join("\n")}
+    </>
+  )
+}
+`;
+}
+async function rewriteExtensionIndex(rootDir, extensionId, targets) {
+  const indexPath = join(rootDir, "packages/extension/src/index.tsx");
+  const imports = ["import { createExtension } from '@stackable-labs/sdk-extension-react'"];
+  const components = [];
+  if (targets.includes("slot.header")) {
+    imports.push("import { Header } from './surfaces/Header'");
+    components.push("      <Header />");
+  }
+  if (targets.includes("slot.content")) {
+    imports.push("import { Content } from './surfaces/Content'");
+    components.push("      <Content />");
+  }
+  if (targets.includes("slot.footer") || targets.includes("slot.footer-links")) {
+    imports.push("import { Footer } from './surfaces/Footer'");
+    components.push("      <Footer />");
+  }
+  const content = `${imports.join("\n")}
+
+createExtension(
+  () => (
+    <>
+${components.join("\n")}
+    </>
+  ),
+  { extensionId: '${toKebabCase2(extensionId)}' },
+)
+`;
+  await writeFile(indexPath, content);
+}
+async function rewritePreviewApp(rootDir, targets, permissions) {
+  const appPath = join(rootDir, "packages/preview/src/App.tsx");
+  const includeDataQuery = permissions.includes("data:query");
+  const includeToast = permissions.includes("actions:toast");
+  const includeInvoke = permissions.includes("actions:invoke");
+  const includeContextRead = permissions.includes("context:read");
+  const typeImports = [
+    "ExtensionRegistryEntry",
+    "Permission",
+    includeInvoke ? "ActionInvokePayload" : "",
+    includeDataQuery ? "ApiRequest" : "",
+    includeToast ? "ToastPayload" : ""
+  ].filter(Boolean);
+  const handlers = [];
+  if (includeDataQuery) {
+    handlers.push(`  'data.query': async (_payload: ApiRequest) => {
+    return mockData
+  },`);
+  }
+  if (includeToast) {
+    handlers.push(`  'actions.toast': async (payload: ToastPayload) => {
+    console.log('[Preview] toast:', payload)
+  },`);
+  }
+  if (includeInvoke) {
+    handlers.push(`  'actions.invoke': async (payload: ActionInvokePayload) => {
+    console.log('[Preview] action invoke:', payload)
+    return {}
+  },`);
+  }
+  if (includeContextRead) {
+    handlers.push("  'context.read': async () => mockContext,");
+  }
+  const appContent = `import { ExtensionProvider, ExtensionSlot } from '@stackable-labs/sdk-extension-host'
+import type { CapabilityHandlers } from '@stackable-labs/sdk-extension-host'
+import { hostComponents } from '@stackable-labs/embeddables/components'
+import type {
+  ${typeImports.join(",\n  ")}
+} from '@stackable-labs/sdk-extension-contracts'
+import manifestRaw from '../../extension/public/manifest.json'
+import mockData from './mockData.json'
+
+const manifest = {
+  ...manifestRaw,
+  permissions: manifestRaw.permissions as Permission[],
+}
+
+const extensions: ExtensionRegistryEntry[] = [
+  {
+    id: manifest.name.toLowerCase().replace(/\\s+/g, '-'),
+    manifest,
+    bundleUrl: \`http://localhost:\${import.meta.env.VITE_EXTENSION_PORT || '5173'}\`,
+    enabled: true,
+  },
+]
+
+const mockContext = {
+  customerId: 'cust_preview_123',
+  customerEmail: 'preview@example.com',
+}
+
+const capabilityHandlers: CapabilityHandlers = {
+${handlers.join("\n")}
+}
+
+export default function App() {
+  return (
+    <div style={{ maxWidth: 400, margin: '0 auto', padding: 16 }}>
+      <ExtensionProvider
+        extensions={extensions}
+        components={hostComponents()}
+        capabilityHandlers={capabilityHandlers}
+      >
+        {manifest.targets.map((target) => (
+          <div key={target} style={{ marginBottom: 8 }}>
+            <div style={{ fontSize: 10, color: '#888' }}>{target}</div>
+            <ExtensionSlot target={target} context={mockContext} />
+          </div>
+        ))}
+      </ExtensionProvider>
+    </div>
+  )
+}
+`;
+  await writeFile(appPath, appContent);
+}
+async function rewriteTurboJson(rootDir) {
+  const turboPath = join(rootDir, "turbo.json");
+  const raw = await readFile(turboPath, "utf8");
+  const turbo = JSON.parse(raw);
+  delete turbo["extends"];
+  turbo["globalEnv"] = ["VITE_EXTENSION_PORT", "VITE_PREVIEW_PORT"];
+  await writeFile(turboPath, `${JSON.stringify(turbo, null, 2)}
+`);
+}
+async function walkFiles(rootDir) {
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "dist") {
+      continue;
+    }
+    const fullPath = join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkFiles(fullPath));
+      continue;
+    }
+    files.push(fullPath);
+  }
+  return files;
+}
+function isTextFile(filePath) {
+  return /\.(ts|tsx|js|jsx|json|md|html|yml|yaml|env|gitignore|nvmrc)$/i.test(filePath);
+}
+async function writeEnvFile(dir, extensionPort, previewPort) {
+  const envPath = join(dir, ".env");
+  const content = `VITE_EXTENSION_PORT=${extensionPort}
+VITE_PREVIEW_PORT=${previewPort}
+`;
+  await writeFile(envPath, content);
+}
+async function upsertOrRemove(filePath, shouldExist, content) {
+  if (shouldExist) {
+    await writeFile(filePath, content);
+    return;
+  }
+  await rm(filePath, { force: true });
+}
+
+// src/App.tsx
+import { join as join2 } from "path";
+import { jsx as jsx9, jsxs as jsxs9 } from "react/jsx-runtime";
+var INITIAL_STEPS = [
+  { label: "Fetching template", status: "pending" },
+  { label: "Generating files", status: "pending" },
+  { label: "Installing dependencies", status: "pending" }
+];
+function toKebabCase3(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function App({ initialName, options }) {
+  const { exit } = useApp();
+  const [step, setStep] = useState6(initialName ? "id" : "name");
+  const [name, setName] = useState6(initialName ?? "");
+  const [extensionId, setExtensionId] = useState6(options?.id ?? "");
+  const [extensionPort, setExtensionPort] = useState6(
+    options?.extensionPort ? parseInt(options.extensionPort, 10) : 5173
+  );
+  const [previewPort, setPreviewPort] = useState6(
+    options?.previewPort ? parseInt(options.previewPort, 10) : 5174
+  );
+  const [targets, setTargets] = useState6([]);
+  const [outputDir, setOutputDir] = useState6("");
+  const [progressSteps, setProgressSteps] = useState6(INITIAL_STEPS);
+  const [errorMessage, setErrorMessage] = useState6();
+  const updateStep = useCallback((index, status) => {
+    setProgressSteps(
+      (prev) => prev.map((s, i) => i === index ? { ...s, status } : s)
+    );
+  }, []);
+  const handleName = (value) => {
+    setName(value);
+    setExtensionId(toKebabCase3(value));
+    setStep("id");
+  };
+  const handleId = (value) => {
+    setExtensionId(value);
+    setStep("targets");
+  };
+  const handleTargets = (value) => {
+    setTargets(value);
+    setStep(options?.extensionPort || options?.previewPort ? "dir" : "ports");
+  };
+  const handlePorts = (extPort, prevPort) => {
+    setExtensionPort(extPort);
+    setPreviewPort(prevPort);
+    setStep("dir");
+  };
+  const handleDir = (dir) => {
+    setOutputDir(dir);
+    setStep("confirm");
+  };
+  const handleConfirm = async () => {
+    setStep("scaffolding");
+    setProgressSteps([
+      { label: "Fetching template", status: "running" },
+      { label: "Generating files", status: "pending" },
+      { label: "Installing dependencies", status: "pending" }
+    ]);
+    try {
+      updateStep(0, "running");
+      await scaffold({
+        name,
+        extensionId,
+        targets,
+        outputDir,
+        extensionPort,
+        previewPort
+      });
+      updateStep(0, "done");
+      updateStep(1, "running");
+      await new Promise((r) => setTimeout(r, 200));
+      updateStep(1, "done");
+      if (!options?.skipInstall) {
+        updateStep(2, "running");
+        await postScaffold({ outputDir, skipInstall: false, skipGit: options?.skipGit });
+        updateStep(2, "done");
+      } else {
+        updateStep(2, "done");
+      }
+      setStep("done");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setErrorMessage(message);
+      setStep("error");
+    }
+  };
+  const handleCancel = () => {
+    exit();
+  };
+  if (step === "name") {
+    return /* @__PURE__ */ jsx9(NamePrompt, { initialValue: name, onSubmit: handleName });
+  }
+  if (step === "id") {
+    return /* @__PURE__ */ jsx9(IdPrompt, { extensionName: name, onSubmit: handleId });
+  }
+  if (step === "targets") {
+    return /* @__PURE__ */ jsx9(TargetSelect, { onSubmit: handleTargets });
+  }
+  if (step === "ports") {
+    return /* @__PURE__ */ jsx9(PortsPrompt, { onSubmit: handlePorts });
+  }
+  if (step === "dir") {
+    return /* @__PURE__ */ jsx9(DirPrompt, { defaultDir: join2(process.cwd(), toKebabCase3(name)), onSubmit: handleDir });
+  }
+  if (step === "confirm") {
+    return /* @__PURE__ */ jsx9(
+      Confirm,
+      {
+        name,
+        extensionId,
+        extensionPort,
+        previewPort,
+        targets,
+        outputDir,
+        onConfirm: handleConfirm,
+        onCancel: handleCancel
+      }
+    );
+  }
+  if (step === "scaffolding") {
+    return /* @__PURE__ */ jsx9(ScaffoldProgress, { steps: progressSteps });
+  }
+  if (step === "done") {
+    return /* @__PURE__ */ jsx9(Done, { name, outputDir });
+  }
+  return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsx9(Text9, { color: "red", bold: true, children: "Scaffold failed" }),
+    errorMessage && /* @__PURE__ */ jsx9(Text9, { color: "red", children: errorMessage })
+  ] });
+}
+
+// src/index.tsx
+import { jsx as jsx10 } from "react/jsx-runtime";
+program.name("create-extension").description("Scaffold a new Stackable extension project").argument("[name]", "Extension project name").option("--id <id>", "Extension ID").option("--targets <targets>", "Comma-separated target slots").option("--extension-port <port>", "Extension dev server port (default: 5173)").option("--preview-port <port>", "Preview host dev server port (default: extension port + 1)").option("--skip-install", "Skip package manager install").option("--skip-git", "Skip git initialization").action((name, options) => {
+  render(/* @__PURE__ */ jsx10(App, { initialName: name, options }));
+});
+program.parse();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@stackable-labs/cli-app-extension",
+  "version": "1.0.0",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "create-extension": "./dist/index.js",
+    "cli-app-extension": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "giget": "^3.1.2",
+    "ink": "^5.0.1",
+    "ink-select-input": "^6.0.0",
+    "ink-text-input": "^6.0.0",
+    "ink-spinner": "^5.0.0",
+    "nypm": "^0.4.1",
+    "react": "^18.3.1"
+  },
+  "description": "CLI for scaffolding Stackable extension projects.",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://www.npmjs.com/package/@stackable-labs/cli-app-extension"
+}