sunpeak 0.9.12 → 0.10.3

package/README.md

@@ -57,7 +57,7 @@ sunpeak is an npm package consisting of:
 2. **The `sunpeak` framework** (`./template`). Next.js for ChatGPT Apps. This templated npm package includes:
    1. Project scaffold - Complete development setup with build, test, and mcp tooling, including the sunpeak library.
    2. UI components - Production-ready components following ChatGPT design guidelines and using OpenAI apps-sdk-ui React components.
-   3. Convention over configuration - Create UIs (resources) by simply creating a `src/resources/NAME-resource.tsx` React file and `src/resources/NAME-resource.json` metadata file.
+   3. Convention over configuration - Create UIs (resources) by simply creating a `src/resources/NAME/NAME-resource.tsx` React file and `src/resources/NAME/NAME-resource.json` metadata file.
 3. **The `sunpeak` CLI** (`./bin`). Commands for managing ChatGPT Apps. Includes a client for the [sunpeak Resource Repository](https://app.sunpeak.ai/) (ECR for ChatGPT Apps). The repository helps you & your CI/CD decouple your App from your client-agnostic MCP server:
    1. Tag your app builds with version numbers and environment names (like `v1.0.0` and `prod`)
    2. `push` built Apps to a central location
@@ -68,7 +68,7 @@ Note that each `sunpeak` component can be used in isolation if preferred, though
 ## Example Component
 
 ```tsx
-import { Card } from '../card';
+import { Card } from './components';
 
 export function MCPResource() {
   return (

package/bin/commands/build.mjs

@@ -4,6 +4,7 @@ import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
 import { existsSync, rmSync, readdirSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, unlinkSync } from 'fs';
 import path from 'path';
+import { toPascalCase, isSimulationFile } from '../lib/patterns.mjs';
 
 /**
  * Build all resources for a Sunpeak project
@@ -83,31 +84,38 @@ export async function build(projectRoot = process.cwd()) {
   mkdirSync(distDir, { recursive: true });
   mkdirSync(tempDir, { recursive: true });
 
-  // Auto-discover all resources
-  const resourceFiles = readdirSync(resourcesDir)
-    .filter(file => file.endsWith('-resource.tsx'))
-    .map(file => {
-      // Extract kebab-case name: 'review-resource.tsx' -> 'review'
-      const kebabName = file.replace('-resource.tsx', '');
+  // Auto-discover all resources (each resource is a subdirectory)
+  const resourceFiles = readdirSync(resourcesDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => {
+      const kebabName = entry.name;
+      const resourceFile = `${kebabName}-resource.tsx`;
+      const resourcePath = path.join(resourcesDir, kebabName, resourceFile);
+
+      // Skip directories without a resource file
+      if (!existsSync(resourcePath)) {
+        return null;
+      }
 
       // Convert kebab-case to PascalCase: 'review' -> 'Review', 'my-widget' -> 'MyWidget'
-      const pascalName = kebabName
-        .split('-')
-        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-        .join('');
+      const pascalName = toPascalCase(kebabName);
 
       return {
         componentName: `${pascalName}Resource`,
-        componentFile: file.replace('.tsx', ''),
+        componentFile: `${kebabName}-resource`,
+        kebabName,
+        resourceDir: path.join(resourcesDir, kebabName),
         entry: `.tmp/index-${kebabName}.tsx`,
         output: `${kebabName}.js`,
         buildOutDir: path.join(buildDir, kebabName),
+        distOutDir: path.join(distDir, kebabName),  // Final output: dist/{resource}/
       };
-    });
+    })
+    .filter(Boolean);
 
   if (resourceFiles.length === 0) {
-    console.error('Error: No resource files found in src/resources/');
-    console.error('Resource files should be named like: review-resource.tsx');
+    console.error('Error: No resource directories found in src/resources/');
+    console.error('Each resource should be a directory like: src/resources/review/review-resource.tsx');
     process.exit(1);
   }
 
@@ -133,7 +141,7 @@ export async function build(projectRoot = process.cwd()) {
 
   // Build all resources (but don't copy yet)
   for (let i = 0; i < resourceFiles.length; i++) {
-    const { componentName, componentFile, entry, output, buildOutDir } = resourceFiles[i];
+    const { componentName, componentFile, kebabName, entry, output, buildOutDir } = resourceFiles[i];
     console.log(`[${i + 1}/${resourceFiles.length}] Building ${output}...`);
 
     try {
@@ -144,7 +152,7 @@ export async function build(projectRoot = process.cwd()) {
 
       // Create entry file from template in temp directory
       const entryContent = template
-        .replace('// RESOURCE_IMPORT', `import { ${componentName} } from '../src/resources/${componentFile}';`)
+        .replace('// RESOURCE_IMPORT', `import { ${componentName} } from '../src/resources/${kebabName}/${componentFile}';`)
         .replace('// RESOURCE_MOUNT', `createRoot(root).render(<${componentName} />);`);
 
       const entryPath = path.join(projectRoot, entry);
@@ -194,15 +202,23 @@ export async function build(projectRoot = process.cwd()) {
     }
   }
 
-  // Now copy all files from build-output to dist/
+  // Now copy all files from build-output to dist/{resource}/
   console.log('\nCopying built files to dist/...');
-  for (const { output, buildOutDir } of resourceFiles) {
+  const timestamp = Date.now().toString(36);
+
+  for (const { output, buildOutDir, distOutDir, kebabName, componentFile, resourceDir } of resourceFiles) {
+    // Create resource-specific output directory
+    if (!existsSync(distOutDir)) {
+      mkdirSync(distOutDir, { recursive: true });
+    }
+
+    // Copy built JS file
     const builtFile = path.join(buildOutDir, output);
-    const destFile = path.join(distDir, output);
+    const destFile = path.join(distOutDir, output);
 
     if (existsSync(builtFile)) {
       copyFileSync(builtFile, destFile);
-      console.log(`✓ Copied ${output}`);
+      console.log(`✓ Copied ${kebabName}/${output}`);
     } else {
       console.error(`Built file not found: ${builtFile}`);
       if (existsSync(buildOutDir)) {
@@ -212,22 +228,28 @@ export async function build(projectRoot = process.cwd()) {
       }
       process.exit(1);
     }
-  }
 
-  // Generate resource metadata JSON files with URIs
-  console.log('\nGenerating resource metadata JSON files...');
-  const timestamp = Date.now().toString(36);
-  for (const { componentFile } of resourceFiles) {
-    const kebabName = componentFile.replace('-resource', '');
-    const srcJson = path.join(resourcesDir, `${componentFile}.json`);
-    const destJson = path.join(distDir, `${kebabName}.json`);
+    // Copy and process resource metadata JSON file
+    const srcJson = path.join(resourceDir, `${componentFile}.json`);
+    const destJson = path.join(distOutDir, `${kebabName}.json`);
 
     if (existsSync(srcJson)) {
       const meta = JSON.parse(readFileSync(srcJson, 'utf-8'));
       // Generate URI using resource name and build timestamp
       meta.uri = `ui://${meta.name}-${timestamp}`;
       writeFileSync(destJson, JSON.stringify(meta, null, 2));
-      console.log(`✓ Generated ${kebabName}.json (uri: ${meta.uri})`);
+      console.log(`✓ Generated ${kebabName}/${kebabName}.json (uri: ${meta.uri})`);
+    }
+
+    // Copy affiliated simulation files (matching {resource}-*-simulation.json pattern)
+    const simulationFiles = readdirSync(resourceDir)
+      .filter(file => isSimulationFile(file, kebabName));
+
+    for (const simFile of simulationFiles) {
+      const srcSim = path.join(resourceDir, simFile);
+      const destSim = path.join(distOutDir, simFile);
+      copyFileSync(srcSim, destSim);
+      console.log(`✓ Copied ${kebabName}/${simFile}`);
     }
   }
 
@@ -240,7 +262,11 @@ export async function build(projectRoot = process.cwd()) {
   }
 
   console.log('\n✓ All resources built successfully!');
-  console.log(`\nBuilt files:`, readdirSync(distDir));
+  console.log('\nBuilt resources:');
+  for (const { kebabName, distOutDir } of resourceFiles) {
+    const files = readdirSync(distOutDir);
+    console.log(`  ${kebabName}/: ${files.join(', ')}`);
+  }
 }
 
 // Allow running directly

package/bin/commands/deploy.mjs

@@ -23,7 +23,7 @@ export async function deploy(projectRoot = process.cwd(), options = {}, deps = d
 sunpeak deploy - Push resources to production (push with "prod" tag)
 
 Usage:
-  sunpeak deploy [file] [options]
+  sunpeak deploy [directory] [options]
 
 Options:
   -r, --repository <owner/repo>  Repository name (defaults to git remote origin)
@@ -31,15 +31,15 @@ Options:
   -h, --help                     Show this help message
 
 Arguments:
-  file                           Optional JS file to deploy (e.g., dist/carousel.js)
+  directory                      Optional resource directory to deploy (e.g., dist/carousel)
                                  If not provided, looks for resources in current
                                  directory first, then falls back to dist/
 
 Examples:
-  sunpeak deploy                     Push all resources with "prod" tag
-  sunpeak deploy dist/carousel.js    Deploy a single resource
-  sunpeak deploy -r myorg/my-app     Deploy to "myorg/my-app" repository
-  sunpeak deploy -t v1.0              Deploy with "prod" and "v1.0" tags
+  sunpeak deploy                 Deploy all resources with "prod" tag
+  sunpeak deploy dist/carousel   Deploy a single resource
+  sunpeak deploy -r myorg/my-app Deploy to "myorg/my-app" repository
+  sunpeak deploy -t v1.0         Deploy with "prod" and "v1.0" tags
 
 This command is equivalent to: sunpeak push --tag prod
 `);
@@ -56,13 +56,13 @@ This command is equivalent to: sunpeak push --tag prod
   d.console.log('Deploying to production...');
   d.console.log();
 
-  // If no specific file provided, check current directory first, then dist/
-  if (!deployOptions.file) {
+  // If no specific directory provided, check current directory first, then dist/
+  if (!deployOptions.dir) {
     const cwdResources = findResources(projectRoot, d);
     if (cwdResources.length > 0) {
       // Found resources in current directory, push each one
       for (const resource of cwdResources) {
-        await push(projectRoot, { ...deployOptions, file: resource.jsPath }, d);
+        await push(projectRoot, { ...deployOptions, dir: resource.dir }, d);
       }
       return;
     }
@@ -91,7 +91,7 @@ function parseArgs(args) {
 sunpeak deploy - Deploy resources to production (push with "prod" tag)
 
 Usage:
-  sunpeak deploy [file] [options]
+  sunpeak deploy [directory] [options]
 
 Options:
   -r, --repository <owner/repo>  Repository name (defaults to git remote origin)
@@ -99,22 +99,22 @@ Options:
   -h, --help                     Show this help message
 
 Arguments:
-  file                           Optional JS file to deploy (e.g., dist/carousel.js)
+  directory                      Optional resource directory to deploy (e.g., dist/carousel)
                                  If not provided, looks for resources in current
                                  directory first, then falls back to dist/
 
 Examples:
-  sunpeak deploy                     Deploy all resources with "prod" tag
-  sunpeak deploy dist/carousel.js    Deploy a single resource
-  sunpeak deploy -r myorg/my-app     Deploy to "myorg/my-app" repository
-  sunpeak deploy -t v1.0              Deploy with "prod" and "v1.0" tags
+  sunpeak deploy                 Deploy all resources with "prod" tag
+  sunpeak deploy dist/carousel   Deploy a single resource
+  sunpeak deploy -r myorg/my-app Deploy to "myorg/my-app" repository
+  sunpeak deploy -t v1.0         Deploy with "prod" and "v1.0" tags
 
 This command is equivalent to: sunpeak push --tag prod
 `);
       process.exit(0);
     } else if (!arg.startsWith('-')) {
-      // Positional argument - treat as file path
-      options.file = arg;
+      // Positional argument - treat as directory path
+      options.dir = arg;
     }
 
     i++;

package/bin/commands/push.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join, dirname, basename } from 'path';
+import { join, basename } from 'path';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
+import { isSimulationFile, extractSimulationName } from '../lib/patterns.mjs';
 
 const SUNPEAK_API_URL = process.env.SUNPEAK_API_URL || 'https://app.sunpeak.ai';
 const CREDENTIALS_DIR = join(homedir(), '.sunpeak');
@@ -59,9 +60,41 @@ export const defaultDeps = {
   apiUrl: SUNPEAK_API_URL,
 };
 
+/**
+ * Find simulation files for a resource in its directory
+ * Expects files matching: {resourceName}-*-simulation.json
+ * Returns array of parsed simulation objects
+ */
+function findSimulations(resourceDir, resourceName, deps = defaultDeps) {
+  const d = { ...defaultDeps, ...deps };
+
+  if (!d.existsSync(resourceDir)) {
+    return [];
+  }
+
+  const entries = d.readdirSync(resourceDir);
+  const simulations = [];
+
+  for (const entry of entries) {
+    if (isSimulationFile(entry, resourceName)) {
+      const simPath = join(resourceDir, entry);
+      try {
+        const simData = JSON.parse(d.readFileSync(simPath, 'utf-8'));
+        const simName = extractSimulationName(entry, resourceName);
+        simulations.push({ ...simData, name: simName });
+      } catch {
+        d.console.warn(`Warning: Could not parse simulation file ${entry}`);
+      }
+    }
+  }
+
+  return simulations;
+}
+
 /**
  * Find all resources in a directory
- * Returns array of { name, jsPath, metaPath, meta }
+ * Expects folder structure: dist/{resource}/{resource}.js
+ * Returns array of { name, jsPath, metaPath, meta, simulations }
  */
 export function findResources(distDir, deps = defaultDeps) {
   const d = { ...defaultDeps, ...deps };
@@ -70,62 +103,73 @@ export function findResources(distDir, deps = defaultDeps) {
     return [];
   }
 
-  const files = d.readdirSync(distDir);
-  const jsFiles = files.filter((f) => f.endsWith('.js'));
-  const jsonFiles = new Set(files.filter((f) => f.endsWith('.json')));
-
-  // Only include .js files that have a matching .json file
-  return jsFiles
-    .filter((jsFile) => {
-      const name = jsFile.replace('.js', '');
-      return jsonFiles.has(`${name}.json`);
-    })
-    .map((jsFile) => {
-      const name = jsFile.replace('.js', '');
-      const jsPath = join(distDir, jsFile);
-      const metaPath = join(distDir, `${name}.json`);
-
-      let meta = null;
-      try {
-        meta = JSON.parse(d.readFileSync(metaPath, 'utf-8'));
-      } catch {
-        d.console.warn(`Warning: Could not parse ${name}.json`);
+  const entries = d.readdirSync(distDir, { withFileTypes: true });
+  const resources = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const resourceName = entry.name;
+      const resourceDir = join(distDir, resourceName);
+      const jsPath = join(resourceDir, `${resourceName}.js`);
+      const metaPath = join(resourceDir, `${resourceName}.json`);
+
+      if (d.existsSync(jsPath) && d.existsSync(metaPath)) {
+        let meta = null;
+        try {
+          meta = JSON.parse(d.readFileSync(metaPath, 'utf-8'));
+        } catch {
+          d.console.warn(`Warning: Could not parse ${resourceName}.json`);
+        }
+        const simulations = findSimulations(resourceDir, resourceName, d);
+        resources.push({ name: resourceName, dir: resourceDir, jsPath, metaPath, meta, simulations });
       }
+    }
+  }
 
-      return { name, jsPath, metaPath, meta };
-    });
+  return resources;
 }
 
 /**
- * Build a resource from a specific JS file path
- * Returns { name, jsPath, metaPath, meta }
+ * Build a resource from a resource directory path
+ * Expects structure: dir/{name}.js, dir/{name}.json
+ * Returns { name, jsPath, metaPath, meta, simulations }
  */
-function buildResourceFromFile(jsPath, deps = defaultDeps) {
+function buildResourceFromDir(resourceDir, deps = defaultDeps) {
   const d = { ...defaultDeps, ...deps };
 
-  if (!d.existsSync(jsPath)) {
-    d.console.error(`Error: File not found: ${jsPath}`);
+  // Remove trailing slash if present
+  const dir = resourceDir.replace(/\/$/, '');
+
+  if (!d.existsSync(dir)) {
+    d.console.error(`Error: Directory not found: ${dir}`);
     d.process.exit(1);
   }
 
-  // Extract name from filename (remove .js extension)
-  const fileName = basename(jsPath);
-  const name = fileName.replace('.js', '');
-
-  // Look for .json in the same directory
-  const dir = dirname(jsPath);
+  // Extract resource name from directory name
+  const name = basename(dir);
+  const jsPath = join(dir, `${name}.js`);
   const metaPath = join(dir, `${name}.json`);
 
+  if (!d.existsSync(jsPath)) {
+    d.console.error(`Error: Resource JS file not found: ${jsPath}`);
+    d.process.exit(1);
+  }
+
+  if (!d.existsSync(metaPath)) {
+    d.console.error(`Error: Resource metadata file not found: ${metaPath}`);
+    d.process.exit(1);
+  }
+
   let meta = null;
-  if (d.existsSync(metaPath)) {
-    try {
-      meta = JSON.parse(d.readFileSync(metaPath, 'utf-8'));
-    } catch {
-      d.console.warn(`Warning: Could not parse ${name}.json`);
-    }
+  try {
+    meta = JSON.parse(d.readFileSync(metaPath, 'utf-8'));
+  } catch {
+    d.console.warn(`Warning: Could not parse ${name}.json`);
   }
 
-  return { name, jsPath, metaPath, meta };
+  const simulations = findSimulations(dir, name, d);
+
+  return { name, jsPath, metaPath, meta, simulations };
 }
 
 /**
@@ -189,6 +233,11 @@ async function pushResource(resource, repository, tags, accessToken, deps = defa
     });
   }
 
+  // Add simulations if present
+  if (resource.simulations && resource.simulations.length > 0) {
+    formData.append('simulations', JSON.stringify(resource.simulations));
+  }
+
   const response = await d.fetch(`${d.apiUrl}/api/v1/resources`, {
     method: 'POST',
     headers: {
@@ -214,7 +263,7 @@ async function pushResource(resource, repository, tags, accessToken, deps = defa
  * @param {string} projectRoot - Project root directory
  * @param {Object} options - Command options
  * @param {string} options.repository - Repository name (optional, defaults to git repo name)
- * @param {string} options.file - Path to a specific resource JS file (optional)
+ * @param {string} options.dir - Path to a specific resource directory (optional)
  * @param {string[]} options.tags - Tags to assign to the pushed resources (optional)
  * @param {Object} deps - Dependencies (for testing). Uses defaultDeps if not provided.
  */
@@ -227,7 +276,7 @@ export async function push(projectRoot = process.cwd(), options = {}, deps = def
 sunpeak push - Push resources to the Sunpeak repository
 
 Usage:
-  sunpeak push [file] [options]
+  sunpeak push [directory] [options]
 
 Options:
   -r, --repository <owner/repo>  Repository name (defaults to git remote origin)
@@ -235,15 +284,15 @@ Options:
   -h, --help                     Show this help message
 
 Arguments:
-  file                           Optional JS file to push (e.g., dist/carousel.js)
+  directory                      Optional resource directory to push (e.g., dist/carousel)
                                  If not provided, pushes all resources from dist/
 
 Examples:
-  sunpeak push                       Push all resources from dist/
-  sunpeak push dist/carousel.js      Push a single resource
-  sunpeak push -r myorg/my-app       Push to "myorg/my-app" repository
-  sunpeak push -t v1.0.0             Push with a version tag
-  sunpeak push -t v1.0.0 -t prod     Push with multiple tags
+  sunpeak push                   Push all resources from dist/
+  sunpeak push dist/carousel     Push a single resource
+  sunpeak push -r myorg/my-app   Push to "myorg/my-app" repository
+  sunpeak push -t v1.0.0         Push with a version tag
+  sunpeak push -t v1.0.0 -t prod Push with multiple tags
 `);
     return;
   }
@@ -264,11 +313,11 @@ Examples:
     d.process.exit(1);
   }
 
-  // Find resources - either a specific file or all from dist directory
+  // Find resources - either a specific directory or all from dist directory
   let resources;
-  if (options.file) {
-    // Push a single specific resource
-    resources = [buildResourceFromFile(options.file, d)];
+  if (options.dir) {
+    // Push a single specific resource from directory
+    resources = [buildResourceFromDir(options.dir, d)];
   } else {
     // Default: find all resources in dist directory
     const distDir = join(projectRoot, 'dist');
@@ -297,7 +346,9 @@ Examples:
   for (const resource of resources) {
     try {
       const result = await pushResource(resource, repository, options.tags, credentials.access_token, d);
-      d.console.log(`✓ Pushed ${resource.name} (id: ${result.id})`);
+      const simCount = resource.simulations?.length || 0;
+      const simInfo = simCount > 0 ? `, ${simCount} simulation(s)` : '';
+      d.console.log(`✓ Pushed ${resource.name} (id: ${result.id}${simInfo})`);
       if (result.tags?.length > 0) {
         d.console.log(`  Tags: ${result.tags.join(', ')}`);
       }
@@ -335,7 +386,7 @@ function parseArgs(args) {
 sunpeak push - Push resources to the Sunpeak repository
 
 Usage:
-  sunpeak push [file] [options]
+  sunpeak push [directory] [options]
 
 Options:
   -r, --repository <owner/repo>  Repository name (defaults to git remote origin)
@@ -343,20 +394,20 @@ Options:
   -h, --help                     Show this help message
 
 Arguments:
-  file                           Optional JS file to push (e.g., dist/carousel.js)
+  directory                      Optional resource directory to push (e.g., dist/carousel)
                                  If not provided, pushes all resources from dist/
 
 Examples:
-  sunpeak push                       Push all resources from dist/
-  sunpeak push dist/carousel.js      Push a single resource
-  sunpeak push -r myorg/my-app       Push to "myorg/my-app" repository
-  sunpeak push -t v1.0.0             Push with a version tag
-  sunpeak push -t v1.0.0 -t prod     Push with multiple tags
+  sunpeak push                   Push all resources from dist/
+  sunpeak push dist/carousel     Push a single resource
+  sunpeak push -r myorg/my-app   Push to "myorg/my-app" repository
+  sunpeak push -t v1.0.0         Push with a version tag
+  sunpeak push -t v1.0.0 -t prod Push with multiple tags
 `);
       process.exit(0);
     } else if (!arg.startsWith('-')) {
-      // Positional argument - treat as file path
-      options.file = arg;
+      // Positional argument - treat as directory path
+      options.dir = arg;
     }
 
     i++;

package/bin/lib/patterns.mjs

@@ -0,0 +1,40 @@
+/**
+ * Shared patterns and utilities for CLI commands.
+ * These mirror the patterns in src/lib/discovery.ts for consistency.
+ */
+
+/**
+ * Convert a kebab-case string to PascalCase
+ * @param {string} str
+ * @returns {string}
+ * @example toPascalCase('review') // 'Review'
+ * @example toPascalCase('album-art') // 'AlbumArt'
+ */
+export function toPascalCase(str) {
+  return str
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Check if a filename is a simulation file for a given resource.
+ * @param {string} filename
+ * @param {string} resourceKey
+ * @returns {boolean}
+ * @example isSimulationFile('albums-show-simulation.json', 'albums') // true
+ */
+export function isSimulationFile(filename, resourceKey) {
+  return filename.startsWith(`${resourceKey}-`) && filename.endsWith('-simulation.json');
+}
+
+/**
+ * Extract the simulation name from a simulation filename.
+ * @param {string} filename
+ * @param {string} resourceKey
+ * @returns {string}
+ * @example extractSimulationName('albums-show-simulation.json', 'albums') // 'show'
+ */
+export function extractSimulationName(filename, resourceKey) {
+  return filename.replace(`${resourceKey}-`, '').replace('-simulation.json', '');
+}