@stackable-labs/cli-app-extension 1.77.0 → 1.78.1

package/dist/index.js

@@ -8,6 +8,7 @@ import Spinner5 from 'ink-spinner';
 import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import TextInput from 'ink-text-input';
+import { SURFACE_TARGETS } from '@stackable-labs/sdk-extension-contracts';
 import { execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import { installDependencies } from 'nypm';
@@ -78,8 +79,6 @@ var Banner = ({ userId, orgId } = {}) => {
     ] })
   ] });
 };
-
-// src/constants.ts
 var TEMPLATE_SOURCES = {
   minimal: "github:stackable-labs/templates/app-extension-minimal",
   starter: "github:stackable-labs/templates/app-extension",
@@ -90,7 +89,7 @@ var TEMPLATE_FLAVOR_META = {
   minimal: {
     label: "Minimal",
     description: "Bare minimum \u2014 single surface, hello-world component",
-    defaultTargets: ["slot.content"],
+    defaultTargets: [SURFACE_TARGETS.CONTENT],
     skipTargetStep: true
   },
   starter: {
@@ -102,15 +101,15 @@ var TEMPLATE_FLAVOR_META = {
   "kitchen-sink": {
     label: "Kitchen Sink",
     description: "Everything including the kitchen sink \u2014 every component, capability, surface, and hook we could fit",
-    defaultTargets: ["slot.header", "slot.content", "slot.footer", "slot.footer-links"],
+    defaultTargets: [SURFACE_TARGETS.HEADER, SURFACE_TARGETS.CONTENT, SURFACE_TARGETS.FOOTER, SURFACE_TARGETS.FOOTER_LINKS],
     skipTargetStep: true
   }
 };
 var TARGET_PERMISSION_MAP = {
-  "slot.header": ["context:read"],
-  "slot.content": ["context:read", "data:query", "data:fetch", "actions:toast", "actions:invoke"],
-  "slot.footer": [],
-  "slot.footer-links": []
+  [SURFACE_TARGETS.HEADER]: ["context:read"],
+  [SURFACE_TARGETS.CONTENT]: ["context:read", "data:query", "data:fetch", "actions:toast", "actions:invoke"],
+  [SURFACE_TARGETS.FOOTER]: [],
+  [SURFACE_TARGETS.FOOTER_LINKS]: []
 };
 var divider = (width) => "\u2500".repeat(width);
 var INNER_DIVIDER_WIDTH = 40;
@@ -1424,6 +1423,165 @@ var postScaffold = async (options) => {
   }
 };
 
+// ../../sdk/extension/ai-docs/src/generated/template-content.ts
+var PATTERN_SECTIONS = [
+  {
+    path: "index.tsx",
+    title: "Entry Point",
+    code: `import { createExtension } from '@stackable-labs/sdk-extension-react'
+import { Header } from './surfaces/Header'
+import { Content } from './surfaces/Content'
+import { Footer } from './surfaces/Footer'
+
+const Extension = () => (
+  <>
+    <Header />
+    <Content />
+    <Footer />
+  </>
+)
+
+createExtension(() => <Extension />, { extensionId: '__EXTENSION_ID__' })`
+  },
+  {
+    path: "store.ts",
+    title: "Store-Based Navigation",
+    code: `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' },
+})`
+  },
+  {
+    path: "surfaces/Content.tsx",
+    title: "Content Surface with Loading State",
+    code: `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>
+  )
+}`
+  },
+  {
+    path: "surfaces/Footer.tsx",
+    title: "Surface Composition",
+    code: `import { ui, Surface } from '@stackable-labs/sdk-extension-react'
+
+export function Footer() {
+  return (
+    <>
+      <Surface id="slot.footer">
+        <ui.Text className="text-xs">Powered by My Extension</ui.Text>
+      </Surface>
+      <Surface id="slot.footer-links">
+        <ui.FooterLink href="https://example.com">My Extension</ui.FooterLink>
+      </Surface>
+    </>
+  )
+}`
+  },
+  {
+    path: "surfaces/Header.tsx",
+    title: "Simple Surface",
+    code: `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>
+  )
+}`
+  },
+  {
+    path: "lib/api.ts",
+    title: "API Wrapper (data.query + data.fetch)",
+    code: `/**
+ * API wrapper patterns \u2014 choose one based on your integration model.
+ *
+ * data.query  \u2192 host-mediated: the host handles the API call, extension sends
+ *               an action name + params, host returns data.
+ *               Permission: "data:query"
+ *
+ * data.fetch  \u2192 direct HTTP: the extension calls external APIs through the
+ *               platform proxy. Domains must be in allowedDomains in manifest.
+ *               Permission: "data:fetch"
+ *
+ * Usage in a surface:
+ *   const capabilities = useCapabilities()
+ *   const api = createApi(capabilities.data.query)
+ *   // or: const api = createFetchApi(capabilities.data.fetch)
+ */
+
+import type { ApiRequest, FetchRequestInit, FetchResponse } from '@stackable-labs/sdk-extension-contracts'
+
+type QueryFn = <T = unknown>(payload: ApiRequest) => Promise<T>
+type FetchFn = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>
+
+// \u2500\u2500 data.query wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export function createApi(query: QueryFn) {
+  return {
+    async getItems(): Promise<unknown[]> {
+      return query<unknown[]>({ action: 'getItems' })
+    },
+
+    async getItem(itemId: string): Promise<unknown> {
+      return query<unknown>({ action: 'getItem', itemId })
+    },
+  }
+}
+
+// \u2500\u2500 data.fetch wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL as string
+
+export function createFetchApi(fetch: FetchFn) {
+  return {
+    async getItems(): Promise<unknown[]> {
+      const result = await fetch(\`\${API_BASE_URL}/items\`, { method: 'GET' })
+      if (!result.ok) throw new Error(\`getItems failed: \${result.status}\`)
+      return result.data as unknown[]
+    },
+
+    async getItem(itemId: string): Promise<unknown> {
+      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, { method: 'GET' })
+      if (!result.ok) throw new Error(\`getItem failed: \${result.status}\`)
+      return result.data as unknown
+    },
+  }
+}`
+  }
+];
+
 // ../../lib/contracts/src/base.ts
 var asClerkUserId = (value) => value;
 var asClerkOrgId = (value) => value;
@@ -1528,6 +1686,13 @@ var writeDevContext = async (projectRoot, ctx) => {
 };
 
 // src/lib/scaffold.ts
+var getPattern = (title) => {
+  const section = PATTERN_SECTIONS.find((s) => s.title === title);
+  if (!section) {
+    throw new Error(`PATTERN_SECTIONS missing "${title}" \u2014 run pnpm generate:docs`);
+  }
+  return section.code;
+};
 var isTextFile = (filePath) => /\.(ts|tsx|js|jsx|json|md|html|yml|yaml|env|gitignore|nvmrc)$/i.test(filePath);
 var normalizeTargets = (targets) => Array.from(new Set(targets));
 var deriveScaffoldPermissions = (targets) => {
@@ -1597,16 +1762,13 @@ var generateManifest = async (rootDir, extensionName, targets, permissions) => {
 `);
 };
 var buildFooterSurface = (targets) => {
+  const fullFooter = getPattern("Surface Composition");
+  const surfaceBlockRegex = /<Surface id="(slot\.footer(?:-links)?)">[\s\S]*?<\/Surface>/g;
   const blocks = [];
-  if (targets.includes("slot.footer")) {
-    blocks.push(
-      '      <Surface id="slot.footer">\n        <ui.Text className="text-xs">Powered by My Extension</ui.Text>\n      </Surface>'
-    );
-  }
-  if (targets.includes("slot.footer-links")) {
-    blocks.push(
-      '      <Surface id="slot.footer-links">\n        <ui.FooterLink href="https://example.com">My Extension</ui.FooterLink>\n      </Surface>'
-    );
+  for (const match of fullFooter.matchAll(surfaceBlockRegex)) {
+    if (targets.includes(match[1])) {
+      blocks.push(`      ${match[0]}`);
+    }
   }
   return `import { ui, Surface } from '@stackable-labs/sdk-extension-react'
 
@@ -1621,60 +1783,26 @@ ${blocks.join("\n")}
 };
 var generateSurfaceFiles = async (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");
+  const wantsHeader = targets.includes(SURFACE_TARGETS.HEADER);
+  const wantsContent = targets.includes(SURFACE_TARGETS.CONTENT);
+  const wantsFooter = targets.includes(SURFACE_TARGETS.FOOTER) || targets.includes(SURFACE_TARGETS.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>
-  )
-}
+    `${getPattern("Simple 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>
-  )
-}
+    `${getPattern("Content Surface with Loading State")}
 `
   );
   await upsertOrRemove(
     join(rootDir, "packages/extension/src/store.ts"),
     wantsContent,
-    "import { createStore } from '@stackable-labs/sdk-extension-react'\n\nexport type ViewState = { type: 'menu' }\n\nexport interface AppState {\n  viewState: ViewState\n}\n\nexport const appStore = createStore<AppState>({\n  viewState: { type: 'menu' },\n})\n"
+    `${getPattern("Store-Based Navigation")}
+`
   );
   await upsertOrRemove(join(surfaceDir, "Footer.tsx"), wantsFooter, buildFooterSurface(targets));
 };
@@ -1682,15 +1810,15 @@ var rewriteExtensionIndex = async (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")) {
+  if (targets.includes(SURFACE_TARGETS.HEADER)) {
     imports.push("import { Header } from './surfaces/Header'");
     components.push("      <Header />");
   }
-  if (targets.includes("slot.content")) {
+  if (targets.includes(SURFACE_TARGETS.CONTENT)) {
     imports.push("import { Content } from './surfaces/Content'");
     components.push("      <Content />");
   }
-  if (targets.includes("slot.footer") || targets.includes("slot.footer-links")) {
+  if (targets.includes(SURFACE_TARGETS.FOOTER) || targets.includes(SURFACE_TARGETS.FOOTER_LINKS)) {
     imports.push("import { Footer } from './surfaces/Footer'");
     components.push("      <Footer />");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/cli-app-extension",
-  "version": "1.77.0",
+  "version": "1.78.1",
   "type": "module",
   "private": false,
   "bin": {
@@ -12,6 +12,7 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@stackable-labs/sdk-extension-ai-docs": "workspace:*",
     "adm-zip": "0.x",
     "clipboardy": "5.x",
     "cloudflared": "0.x",