sunpeak 0.16.14 → 0.16.18

package/README.md

@@ -18,7 +18,7 @@
 
 Local-first MCP Apps framework.
 
-Quickstart, build, test, and ship your Claude or ChatGPT App!
+Quickstart, build, test, and ship your Claude Connector or ChatGPT App!
 
 [Demo (Hosted)](https://sunpeak.ai/simulator) ~
 [Demo (Video)](https://cdn.sunpeak.ai/sunpeak-demo-prod.mp4) ~
@@ -62,14 +62,16 @@ my-app/
 ├── src/
 │   ├── resources/
 │   │   └── review/
-│   │       └── review.tsx   # Review UI component + resource metadata.
+│   │       └── review.tsx            # Review UI component + resource metadata.
 │   ├── tools/
-│   │   ├── review-diff.ts   # Tool with handler, schema, and resource reference.
-│   │   └── review-post.ts   # Multiple tools can share one resource.
-│   └── server.ts            # Optional: auth, server config.
+│   │   ├── review-diff.ts            # Tool with handler, schema, and optional resource link.
+│   │   ├── review-post.ts            # Multiple tools can share one resource.
+│   │   └── review.ts                 # Backend-only tool (no resource, no UI).
+│   └── server.ts                     # Optional: auth, server config.
 ├── tests/simulations/
-│   ├── review-diff.json     # Mock state for testing.
-│   └── review-post.json     # Mock state for testing.
+│   ├── review-diff.json              # Mock state for testing (includes serverTools).
+│   ├── review-post.json              # Mock state for testing (includes serverTools).
+│   └── review-purchase.json          # Mock state for testing (includes serverTools).
 └── package.json
 ```
 
@@ -77,7 +79,7 @@ my-app/
 2. UI components: Production-ready components following MCP App design guidelines.
 3. Convention over configuration:
    1. Create a UI by creating a `.tsx` file in `src/resources/{name}/` that exports a `ResourceConfig` and a React component ([example below](#resource-component)).
-   2. Create a tool by creating a `.ts` file in `src/tools/` that exports `tool` (metadata with resource reference), `schema` (Zod), and a `default` handler ([example below](#tool-file)).
+   2. Create a tool by creating a `.ts` file in `src/tools/` that exports `tool` (metadata with optional resource link), `schema` (Zod), and a `default` handler ([example below](#tool-file)). Tools without a `resource` field are registered as plain MCP tools (no UI).
    3. Create test state (`Simulation`s) by creating a `.json` file in `tests/simulations/` ([example below](#simulation)).
 
 ### The `sunpeak` CLI
@@ -118,7 +120,7 @@ export function ReviewResource() {
 
 ### Tool File
 
-Each tool `.ts` file exports metadata (with a direct resource reference), a Zod schema, and a handler:
+Each tool `.ts` file exports metadata (with an optional resource link for UI tools), a Zod schema, and a handler:
 
 ```ts
 // src/tools/review-diff.ts

package/bin/commands/build.mjs

@@ -75,17 +75,11 @@ export async function build(projectRoot = process.cwd(), { quiet = false } = {})
   const resourcesDir = path.join(projectRoot, 'src/resources');
   const templateFile = path.join(projectRoot, 'src/index-resource.tsx');
 
-  // Validate project structure
-  if (!existsSync(resourcesDir)) {
-    console.error('Error: src/resources directory not found');
-    console.error('Expected location: ' + resourcesDir);
-    console.error('\nThe build command expects the standard Sunpeak project structure.');
-    console.error('If you have customized your project structure, you may need to use');
-    console.error('a custom build script instead of "sunpeak build".');
-    process.exit(1);
-  }
+  // Check if resources exist (optional — projects may have only plain tools)
+  const hasResources = existsSync(resourcesDir);
+  const hasTemplateFile = existsSync(templateFile);
 
-  if (!existsSync(templateFile)) {
+  if (hasResources && !hasTemplateFile) {
     console.error('Error: src/index-resource.tsx not found');
     console.error('Expected location: ' + templateFile);
     console.error('\nThis file is the template entry point for building resources.');
@@ -93,56 +87,7 @@ export async function build(projectRoot = process.cwd(), { quiet = false } = {})
     process.exit(1);
   }
 
-  // Import vite and plugins from the user's project (not from sunpeak's node_modules)
-  // This allows sunpeak to work when installed globally
-  // We resolve to ESM entry points to avoid the CJS deprecation warning from Vite
   const require = createRequire(path.join(projectRoot, 'package.json'));
-  let viteBuild, react, tailwindcss;
-  try {
-    const [viteModule, reactModule, tailwindModule] = await Promise.all([
-      import(resolveEsmEntry(require, 'vite')),
-      import(resolveEsmEntry(require, '@vitejs/plugin-react')),
-      import(resolveEsmEntry(require, '@tailwindcss/vite')),
-    ]);
-    viteBuild = viteModule.build;
-    react = reactModule.default;
-    tailwindcss = tailwindModule.default;
-  } catch (error) {
-    console.error('Error: Could not load build dependencies from your project.');
-    console.error('\nMake sure you have these packages installed in your project:');
-    console.error('  - vite');
-    console.error('  - @vitejs/plugin-react');
-    console.error('  - @tailwindcss/vite');
-    console.error('\nRun: npm install -D vite @vitejs/plugin-react @tailwindcss/vite');
-    console.error('\nOriginal error:', error.message);
-    process.exit(1);
-  }
-
-  // Plugin factory to inline CSS into the JS bundle for all output files
-  const inlineCssPlugin = (buildOutDir) => ({
-    name: 'inline-css',
-    closeBundle() {
-      const cssFile = path.join(buildOutDir, 'style.css');
-
-      if (existsSync(cssFile)) {
-        const css = readFileSync(cssFile, 'utf-8');
-        const injectCss = `(function(){var s=document.createElement('style');s.textContent=${JSON.stringify(css)};document.head.appendChild(s);})();`;
-
-        // Find all .js files in the dist directory and inject CSS
-        const files = readdirSync(buildOutDir);
-        files.forEach((file) => {
-          if (file.endsWith('.js')) {
-            const jsFile = path.join(buildOutDir, file);
-            const js = readFileSync(jsFile, 'utf-8');
-            writeFileSync(jsFile, injectCss + js);
-          }
-        });
-
-        // Remove the separate CSS file after injecting into all bundles
-        unlinkSync(cssFile);
-      }
-    },
-  });
 
   // Clean dist and temp directories
   if (existsSync(distDir)) {
@@ -152,161 +97,213 @@ export async function build(projectRoot = process.cwd(), { quiet = false } = {})
     rmSync(tempDir, { recursive: true });
   }
   mkdirSync(distDir, { recursive: true });
-  mkdirSync(tempDir, { recursive: true });
 
-  // 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;
+  // ========================================================================
+  // Build resources (if any exist)
+  // ========================================================================
 
-      const resourceFile = `${kebabName}.tsx`;
-      const resourcePath = path.join(resourcesDir, kebabName, resourceFile);
+  let resourceFiles = [];
 
-      // Skip directories without a resource file
-      if (!existsSync(resourcePath)) {
-        return null;
-      }
+  if (hasResources && hasTemplateFile) {
+    // Import vite and plugins from the user's project (not from sunpeak's node_modules)
+    // We resolve to ESM entry points to avoid the CJS deprecation warning from Vite
+    let viteBuild, react, tailwindcss;
+    try {
+      const [viteModule, reactModule, tailwindModule] = await Promise.all([
+        import(resolveEsmEntry(require, 'vite')),
+        import(resolveEsmEntry(require, '@vitejs/plugin-react')),
+        import(resolveEsmEntry(require, '@tailwindcss/vite')),
+      ]);
+      viteBuild = viteModule.build;
+      react = reactModule.default;
+      tailwindcss = tailwindModule.default;
+    } catch (error) {
+      console.error('Error: Could not load build dependencies from your project.');
+      console.error('\nMake sure you have these packages installed in your project:');
+      console.error('  - vite');
+      console.error('  - @vitejs/plugin-react');
+      console.error('  - @tailwindcss/vite');
+      console.error('\nRun: npm install -D vite @vitejs/plugin-react @tailwindcss/vite');
+      console.error('\nOriginal error:', error.message);
+      process.exit(1);
+    }
 
-      // Convert kebab-case to PascalCase: 'review' -> 'Review', 'my-widget' -> 'MyWidget'
-      const pascalName = toPascalCase(kebabName);
-      const componentFile = resourceFile.replace(/\.tsx$/, '');
-
-      return {
-        componentName: `${pascalName}Resource`,
-        componentFile,
-        kebabName,
-        resourceDir: path.join(resourcesDir, kebabName),
-        entry: `.tmp/index-${kebabName}.tsx`,
-        jsOutput: `${kebabName}.js`,
-        htmlOutput: `${kebabName}.html`,
-        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 directories found in src/resources/');
-    console.error('Each resource should be a directory like: src/resources/review/review.tsx');
-    process.exit(1);
-  }
+    // Plugin factory to inline CSS into the JS bundle for all output files
+    const inlineCssPlugin = (buildOutDir) => ({
+      name: 'inline-css',
+      closeBundle() {
+        const cssFile = path.join(buildOutDir, 'style.css');
+
+        if (existsSync(cssFile)) {
+          const css = readFileSync(cssFile, 'utf-8');
+          const injectCss = `(function(){var s=document.createElement('style');s.textContent=${JSON.stringify(css)};document.head.appendChild(s);})();`;
+
+          // Find all .js files in the dist directory and inject CSS
+          const files = readdirSync(buildOutDir);
+          files.forEach((file) => {
+            if (file.endsWith('.js')) {
+              const jsFile = path.join(buildOutDir, file);
+              const js = readFileSync(jsFile, 'utf-8');
+              writeFileSync(jsFile, injectCss + js);
+            }
+          });
 
-  log('Building all resources...\n');
+          // Remove the separate CSS file after injecting into all bundles
+          unlinkSync(cssFile);
+        }
+      },
+    });
 
-  // Read and validate the template
-  const template = readFileSync(templateFile, 'utf-8');
+    mkdirSync(tempDir, { recursive: true });
 
-  // Verify template has required placeholders
-  if (!template.includes('// RESOURCE_IMPORT')) {
-    console.error('Error: src/index-resource.tsx is missing "// RESOURCE_IMPORT" placeholder');
-    console.error('\nThe template file must include this comment where the resource import should go.');
-    console.error('If you have customized this file, ensure it has the required placeholders.');
-    process.exit(1);
-  }
+    // Auto-discover all resources (each resource is a subdirectory)
+    resourceFiles = readdirSync(resourcesDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => {
+        const kebabName = entry.name;
 
-  if (!template.includes('// RESOURCE_MOUNT')) {
-    console.error('Error: src/index-resource.tsx is missing "// RESOURCE_MOUNT" placeholder');
-    console.error('\nThe template file must include this comment where the resource mount should go.');
-    console.error('If you have customized this file, ensure it has the required placeholders.');
-    process.exit(1);
-  }
+        const resourceFile = `${kebabName}.tsx`;
+        const resourcePath = path.join(resourcesDir, kebabName, resourceFile);
 
-  // Build all resources (but don't copy yet)
-  for (let i = 0; i < resourceFiles.length; i++) {
-    const { componentName, componentFile, kebabName, entry, jsOutput, buildOutDir } = resourceFiles[i];
-    log(`[${i + 1}/${resourceFiles.length}] Building ${kebabName}...`);
+        // Skip directories without a resource file
+        if (!existsSync(resourcePath)) {
+          return null;
+        }
 
-    try {
-      // Create build directory if it doesn't exist
-      if (!existsSync(buildOutDir)) {
-        mkdirSync(buildOutDir, { recursive: true });
+        // Convert kebab-case to PascalCase: 'review' -> 'Review', 'my-widget' -> 'MyWidget'
+        const pascalName = toPascalCase(kebabName);
+        const componentFile = resourceFile.replace(/\.tsx$/, '');
+
+        return {
+          componentName: `${pascalName}Resource`,
+          componentFile,
+          kebabName,
+          resourceDir: path.join(resourcesDir, kebabName),
+          entry: `.tmp/index-${kebabName}.tsx`,
+          jsOutput: `${kebabName}.js`,
+          htmlOutput: `${kebabName}.html`,
+          buildOutDir: path.join(buildDir, kebabName),
+          distOutDir: path.join(distDir, kebabName),  // Final output: dist/{resource}/
+        };
+      })
+      .filter(Boolean);
+
+    if (resourceFiles.length > 0) {
+      log('Building all resources...\n');
+
+      // Read and validate the template
+      const template = readFileSync(templateFile, 'utf-8');
+
+      // Verify template has required placeholders
+      if (!template.includes('// RESOURCE_IMPORT')) {
+        console.error('Error: src/index-resource.tsx is missing "// RESOURCE_IMPORT" placeholder');
+        console.error('\nThe template file must include this comment where the resource import should go.');
+        console.error('If you have customized this file, ensure it has the required placeholders.');
+        process.exit(1);
+      }
+
+      if (!template.includes('// RESOURCE_MOUNT')) {
+        console.error('Error: src/index-resource.tsx is missing "// RESOURCE_MOUNT" placeholder');
+        console.error('\nThe template file must include this comment where the resource mount should go.');
+        console.error('If you have customized this file, ensure it has the required placeholders.');
+        process.exit(1);
       }
 
-      // Create entry file from template in temp directory
-      const entryContent = template
-        .replace('// RESOURCE_IMPORT', `import { ${componentName}, resource } from '../src/resources/${kebabName}/${componentFile}';`)
-        .replace('// RESOURCE_MOUNT', `createRoot(root).render(<AppProvider appInfo={{ name: ${JSON.stringify(appName)}, version: ${JSON.stringify(appVersion)} }}><${componentName} /></AppProvider>);`);
-
-      const entryPath = path.join(projectRoot, entry);
-      writeFileSync(entryPath, entryContent);
-
-      // Build with vite programmatically
-      await viteBuild({
-        mode: 'production',
-        root: projectRoot,
-        ...(quiet && { logLevel: 'silent' }),
-        plugins: [react(), tailwindcss(), inlineCssPlugin(buildOutDir)],
-        define: {
-          'process.env.NODE_ENV': JSON.stringify('production'),
-        },
-        resolve: {
-          conditions: ['style', 'import', 'module', 'browser', 'default'],
-          alias: {
-            '@': path.resolve(projectRoot, 'src'),
-            // In workspace dev mode, use local sunpeak source
-            ...(isTemplate && {
-              sunpeak: parentSrc,
-            }),
-          },
-        },
-        build: {
-          target: 'es2020',
-          outDir: buildOutDir,
-          emptyOutDir: true,
-          cssCodeSplit: false,
-          lib: {
-            entry: entryPath,
-            name: 'SunpeakApp',
-            formats: ['iife'],
-            fileName: () => jsOutput,
-          },
-          rollupOptions: {
-            output: {
-              inlineDynamicImports: true,
-              assetFileNames: 'style.css',
+      // Build all resources (but don't copy yet)
+      for (let i = 0; i < resourceFiles.length; i++) {
+        const { componentName, componentFile, kebabName, entry, jsOutput, buildOutDir } = resourceFiles[i];
+        log(`[${i + 1}/${resourceFiles.length}] Building ${kebabName}...`);
+
+        try {
+          // Create build directory if it doesn't exist
+          if (!existsSync(buildOutDir)) {
+            mkdirSync(buildOutDir, { recursive: true });
+          }
+
+          // Create entry file from template in temp directory
+          const entryContent = template
+            .replace('// RESOURCE_IMPORT', `import { ${componentName}, resource } from '../src/resources/${kebabName}/${componentFile}';`)
+            .replace('// RESOURCE_MOUNT', `createRoot(root).render(<AppProvider appInfo={{ name: ${JSON.stringify(appName)}, version: ${JSON.stringify(appVersion)} }}><${componentName} /></AppProvider>);`);
+
+          const entryPath = path.join(projectRoot, entry);
+          writeFileSync(entryPath, entryContent);
+
+          // Build with vite programmatically
+          await viteBuild({
+            mode: 'production',
+            root: projectRoot,
+            ...(quiet && { logLevel: 'silent' }),
+            plugins: [react(), tailwindcss(), inlineCssPlugin(buildOutDir)],
+            define: {
+              'process.env.NODE_ENV': JSON.stringify('production'),
             },
-          },
-          minify: true,
-          cssMinify: true,
-        },
-      });
-    } catch (error) {
-      console.error(`Failed to build ${kebabName}`);
-      console.error(error);
-      process.exit(1);
-    }
-  }
+            resolve: {
+              conditions: ['style', 'import', 'module', 'browser', 'default'],
+              alias: {
+                '@': path.resolve(projectRoot, 'src'),
+                // In workspace dev mode, use local sunpeak source
+                ...(isTemplate && {
+                  sunpeak: parentSrc,
+                }),
+              },
+            },
+            build: {
+              target: 'es2020',
+              outDir: buildOutDir,
+              emptyOutDir: true,
+              cssCodeSplit: false,
+              lib: {
+                entry: entryPath,
+                name: 'SunpeakApp',
+                formats: ['iife'],
+                fileName: () => jsOutput,
+              },
+              rollupOptions: {
+                output: {
+                  inlineDynamicImports: true,
+                  assetFileNames: 'style.css',
+                },
+              },
+              minify: true,
+              cssMinify: true,
+            },
+          });
+        } catch (error) {
+          console.error(`Failed to build ${kebabName}`);
+          console.error(error);
+          process.exit(1);
+        }
+      }
 
-  // Now copy all files from build-output to dist/{resource}/
-  log('\nCopying built files to dist/...');
-  const timestamp = Date.now().toString(36);
+      // Now copy all files from build-output to dist/{resource}/
+      log('\nCopying built files to dist/...');
+      const timestamp = Date.now().toString(36);
 
-  for (const { jsOutput, htmlOutput, buildOutDir, distOutDir, kebabName, componentFile, resourceDir } of resourceFiles) {
-    // Create resource-specific output directory
-    if (!existsSync(distOutDir)) {
-      mkdirSync(distOutDir, { recursive: true });
-    }
+      for (const { jsOutput, htmlOutput, buildOutDir, distOutDir, kebabName, componentFile, resourceDir } of resourceFiles) {
+        // Create resource-specific output directory
+        if (!existsSync(distOutDir)) {
+          mkdirSync(distOutDir, { recursive: true });
+        }
 
-    // Extract resource metadata from .tsx file and write as JSON
-    const srcTsx = path.join(resourceDir, `${componentFile}.tsx`);
-    const destJson = path.join(distOutDir, `${kebabName}.json`);
-
-    const meta = await extractResourceExport(srcTsx);
-    // Inject name from directory key if not explicitly set
-    meta.name = meta.name ?? kebabName;
-    // Generate URI using resource name and build timestamp
-    meta.uri = `ui://${meta.name}-${timestamp}`;
-    writeFileSync(destJson, JSON.stringify(meta, null, 2));
-    log(`✓ Generated ${kebabName}/${kebabName}.json (uri: ${meta.uri})`);
-
-    // Read built JS file and wrap in HTML shell
-    const builtJsFile = path.join(buildOutDir, jsOutput);
-    const destHtmlFile = path.join(distOutDir, htmlOutput);
-
-    if (existsSync(builtJsFile)) {
-      const jsContents = readFileSync(builtJsFile, 'utf-8');
-      const html = `<!DOCTYPE html>
+        // Extract resource metadata from .tsx file and write as JSON
+        const srcTsx = path.join(resourceDir, `${componentFile}.tsx`);
+        const destJson = path.join(distOutDir, `${kebabName}.json`);
+
+        const meta = await extractResourceExport(srcTsx);
+        // Inject name from directory key if not explicitly set
+        meta.name = meta.name ?? kebabName;
+        // Generate URI using resource name and build timestamp
+        meta.uri = `ui://${meta.name}-${timestamp}`;
+        writeFileSync(destJson, JSON.stringify(meta, null, 2));
+        log(`✓ Generated ${kebabName}/${kebabName}.json (uri: ${meta.uri})`);
+
+        // Read built JS file and wrap in HTML shell
+        const builtJsFile = path.join(buildOutDir, jsOutput);
+        const destHtmlFile = path.join(distOutDir, htmlOutput);
+
+        if (existsSync(builtJsFile)) {
+          const jsContents = readFileSync(builtJsFile, 'utf-8');
+          const html = `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="UTF-8">
@@ -319,32 +316,34 @@ ${jsContents}
   </script>
 </body>
 </html>`;
-      writeFileSync(destHtmlFile, html);
-      log(`✓ Built ${kebabName}/${htmlOutput}`);
-    } else {
-      console.error(`Built file not found: ${builtJsFile}`);
-      if (existsSync(buildOutDir)) {
-        log(`  Files in ${buildOutDir}:`, readdirSync(buildOutDir));
-      } else {
-        log(`  Build directory doesn't exist: ${buildOutDir}`);
-      }
-      process.exit(1);
-    }
+          writeFileSync(destHtmlFile, html);
+          log(`✓ Built ${kebabName}/${htmlOutput}`);
+        } else {
+          console.error(`Built file not found: ${builtJsFile}`);
+          if (existsSync(buildOutDir)) {
+            log(`  Files in ${buildOutDir}:`, readdirSync(buildOutDir));
+          } else {
+            log(`  Build directory doesn't exist: ${buildOutDir}`);
+          }
+          process.exit(1);
+        }
 
-  }
+      }
 
-  // Clean up temp and build directories
-  if (existsSync(tempDir)) {
-    rmSync(tempDir, { recursive: true });
-  }
-  if (existsSync(buildDir)) {
-    rmSync(buildDir, { recursive: true });
-  }
+      // Clean up temp and build directories
+      if (existsSync(tempDir)) {
+        rmSync(tempDir, { recursive: true });
+      }
+      if (existsSync(buildDir)) {
+        rmSync(buildDir, { recursive: true });
+      }
 
-  log('\n✓ All resources built successfully!');
-  log('\nBuilt resources:');
-  for (const { kebabName } of resourceFiles) {
-    log(`  ${kebabName}`);
+      log('\n✓ All resources built successfully!');
+      log('\nBuilt resources:');
+      for (const { kebabName } of resourceFiles) {
+        log(`  ${kebabName}`);
+      }
+    }
   }
 
   // ========================================================================
@@ -356,7 +355,7 @@ ${jsContents}
 
   // Find tool files
   const toolFiles = existsSync(toolsDir)
-    ? readdirSync(toolsDir).filter(f => f.endsWith('.ts'))
+    ? readdirSync(toolsDir).filter(f => f.endsWith('.ts') && !f.endsWith('.test.ts'))
     : [];
 
   const hasServerEntry = existsSync(serverEntryPath);