@weave-apps/sdk 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@weave-apps/sdk",
+  "version": "0.1.0",
+  "description": "SDK for building Weave Micro Apps",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "weave-init": "./bin/init.js",
+    "weave-build": "./bin/build.js",
+    "weave-compile": "./bin/compile.js"
+  },
+  "scripts": {
+    "copy-sdk": "node scripts/copy-sdk-files.js",
+    "prebuild": "npm run copy-sdk",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "weave",
+    "browser-extension",
+    "app-sdk",
+    "typescript"
+  ],
+  "author": "Weave Platform",
+  "license": "MIT",
+  "dependencies": {
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "scripts",
+    "templates",
+    "tsconfig.app.json",
+    "README.md"
+  ]
+}

package/scripts/copy-sdk-files.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+/**
+ * Copy SDK files from sidebar-loader to app-sdk
+ * This ensures the app-sdk has its own copy of the SDK files for distribution
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const sourceDir = path.join(__dirname, '../../sidebar-loader/src/sdk');
+const targetDir = path.join(__dirname, '../src');
+
+// Files to copy
+const filesToCopy = [
+  'WeaveBaseApp.ts',
+  'WeaveDOMAPI.ts',
+  'WeaveAPIClient.ts',
+  'global.ts',
+  'app-template.js',
+  'README.md',
+  'API_GUIDE.md'
+];
+
+console.log('📦 Copying SDK files from sidebar-loader...\n');
+
+filesToCopy.forEach(file => {
+  const sourcePath = path.join(sourceDir, file);
+  const targetPath = path.join(targetDir, file);
+  
+  if (fs.existsSync(sourcePath)) {
+    // Special handling for global.ts - remove utils imports and references
+    if (file === 'global.ts') {
+      let content = fs.readFileSync(sourcePath, 'utf8');
+      
+      // Remove utils imports
+      content = content.replace(/import htmlToMarkdown from ['"]\.\.\/utils\/htmlToMarkdown['"];?\n?/g, '');
+      content = content.replace(/import markdownToHtml from ['"]\.\.\/utils\/markdownToHtml['"];?\n?/g, '');
+      
+      // Remove __weaveUtils from Window interface
+      content = content.replace(/\s+__weaveUtils:\s*\{[^}]+\};?\n?/g, '');
+      
+      // Remove __weaveUtils assignment
+      content = content.replace(/\/\/ Make utilities available globally.*\n?window\.__weaveUtils\s*=\s*\{[^}]+\};?\n?/gs, '');
+      
+      fs.writeFileSync(targetPath, content, 'utf8');
+      console.log(`✅ Copied (modified): ${file}`);
+    } else {
+      fs.copyFileSync(sourcePath, targetPath);
+      console.log(`✅ Copied: ${file}`);
+    }
+  } else {
+    console.warn(`⚠️  Warning: ${file} not found in sidebar-loader/src/sdk`);
+  }
+});
+
+console.log('\n✨ SDK files copied successfully!\n');

package/scripts/extract-settings-schema.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+
+/**
+ * Extract TypeScript interfaces and embed them as JSDoc comments
+ * This allows the enterprise console to extract settings schema without executing code
+ */
+
+const ts = require('typescript');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract interface definition from TypeScript AST
+ */
+function extractInterface(node, sourceFile, interfaceName) {
+  if (!ts.isInterfaceDeclaration(node) || node.name.text !== interfaceName) {
+    return null;
+  }
+
+  const schema = [];
+
+  node.members.forEach((member) => {
+    if (ts.isPropertySignature(member) && member.name) {
+      const propertyName = member.name.getText(sourceFile);
+      const isOptional = !!member.questionToken;
+      
+      // Extract type
+      let propertyType = 'string';
+      let options = undefined;
+      
+      if (member.type) {
+        const typeText = member.type.getText(sourceFile);
+        
+        // Handle union types (e.g., 'top' | 'bottom')
+        if (ts.isUnionTypeNode(member.type)) {
+          const literals = member.type.types
+            .filter(t => ts.isLiteralTypeNode(t))
+            .map(t => t.literal.getText(sourceFile).replace(/['"]/g, ''));
+          
+          if (literals.length > 0) {
+            propertyType = 'select';
+            options = literals.map(val => ({ label: val, value: val }));
+          }
+        } else if (typeText === 'string') {
+          propertyType = 'string';
+        } else if (typeText === 'number') {
+          propertyType = 'number';
+        } else if (typeText === 'boolean') {
+          propertyType = 'boolean';
+        }
+      }
+
+      // Extract JSDoc comment for description
+      const jsDocTags = ts.getJSDocTags(member);
+      let description = '';
+      let defaultValue = undefined;
+
+      jsDocTags.forEach(tag => {
+        if (tag.tagName.text === 'description' && tag.comment) {
+          description = typeof tag.comment === 'string' ? tag.comment : tag.comment.map(c => c.text).join('');
+        }
+        if (tag.tagName.text === 'default' && tag.comment) {
+          const defaultText = typeof tag.comment === 'string' ? tag.comment : tag.comment.map(c => c.text).join('');
+          // Try to parse as JSON, but handle string values carefully
+          try {
+            defaultValue = JSON.parse(defaultText);
+          } catch {
+            // If JSON.parse fails, it might be an unquoted string value
+            // Remove surrounding quotes if present (from JSDoc)
+            const trimmed = defaultText.trim();
+            if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+                (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+              // Remove outer quotes and use the inner value as-is
+              defaultValue = trimmed.slice(1, -1);
+            } else {
+              defaultValue = trimmed;
+            }
+          }
+        }
+      });
+
+      // Generate human-readable label from property name
+      // Handles: camelCase, UPPER_CASE, PascalCase
+      let label = propertyName;
+      
+      // Check if it's UPPER_CASE (all uppercase with underscores)
+      if (propertyName === propertyName.toUpperCase() && propertyName.includes('_')) {
+        // UPPER_CASE -> Upper Case
+        label = propertyName
+          .split('_')
+          .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+          .join(' ');
+      } else {
+        // camelCase or PascalCase -> Camel Case or Pascal Case
+        label = propertyName
+          .replace(/([A-Z])/g, ' $1') // Add space before capitals
+          .replace(/^./, str => str.toUpperCase()) // Capitalize first letter
+          .trim();
+      }
+
+      schema.push({
+        key: propertyName,
+        label: label,
+        type: propertyType,
+        description: description || undefined,
+        required: !isOptional,
+        defaultValue,
+        options
+      });
+    }
+  });
+
+  return schema;
+}
+
+/**
+ * Process TypeScript file and extract settings schema
+ */
+function processFile(filePath) {
+  const sourceCode = fs.readFileSync(filePath, 'utf-8');
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    sourceCode,
+    ts.ScriptTarget.Latest,
+    true
+  );
+
+  let settingsSchema = null;
+  let settingsInterfaceName = null;
+
+  // Find the class that extends WeaveBaseApp and extract the generic type
+  function visit(node) {
+    // Find class declaration
+    if (ts.isClassDeclaration(node) && node.heritageClauses) {
+      node.heritageClauses.forEach(clause => {
+        clause.types.forEach(type => {
+          const exprText = type.expression.getText(sourceFile);
+          if (exprText === 'WeaveBaseApp' && type.typeArguments && type.typeArguments.length > 0) {
+            // First generic is TSettings
+            settingsInterfaceName = type.typeArguments[0].getText(sourceFile);
+          }
+        });
+      });
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+
+  // Now extract the interface
+  if (settingsInterfaceName) {
+    function findInterface(node) {
+      const extracted = extractInterface(node, sourceFile, settingsInterfaceName);
+      if (extracted) {
+        settingsSchema = extracted;
+      }
+      ts.forEachChild(node, findInterface);
+    }
+    findInterface(sourceFile);
+  }
+
+  return settingsSchema;
+}
+
+/**
+ * Inject schema as JSDoc comment into compiled JavaScript
+ */
+function injectSchemaIntoJS(jsFilePath, schema) {
+  if (!schema || schema.length === 0) {
+    return;
+  }
+
+  let jsCode = fs.readFileSync(jsFilePath, 'utf-8');
+
+  // Find the class definition
+  const classMatch = jsCode.match(/class\s+(\w+)\s+extends\s+WeaveBaseApp/);
+  if (!classMatch) {
+    console.warn('⚠️  Could not find class extending WeaveBaseApp');
+    return;
+  }
+
+  const className = classMatch[1];
+
+  // Create JSDoc comment with schema
+  const schemaComment = `
+/**
+ * @weave-settings-schema ${JSON.stringify(schema, null, 2)}
+ */`;
+
+  // Inject before class definition
+  jsCode = jsCode.replace(
+    new RegExp(`(class\\s+${className}\\s+extends\\s+WeaveBaseApp)`, 'g'),
+    `${schemaComment}\n$1`
+  );
+
+  fs.writeFileSync(jsFilePath, jsCode, 'utf-8');
+  console.log(`✅ Injected settings schema into ${jsFilePath}`);
+}
+
+/**
+ * Main execution
+ */
+function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length < 2) {
+    console.error('Usage: extract-settings-schema.js <input.ts> <output.js>');
+    process.exit(1);
+  }
+
+  const [tsFile, jsFile] = args;
+
+  if (!fs.existsSync(tsFile)) {
+    console.error(`❌ TypeScript file not found: ${tsFile}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(jsFile)) {
+    console.error(`❌ JavaScript file not found: ${jsFile}`);
+    process.exit(1);
+  }
+
+  console.log(`📝 Extracting settings schema from ${tsFile}...`);
+  const schema = processFile(tsFile);
+
+  if (schema && schema.length > 0) {
+    console.log(`📦 Found ${schema.length} settings:`, schema.map(s => s.key).join(', '));
+    injectSchemaIntoJS(jsFile, schema);
+  } else {
+    console.log('ℹ️  No settings schema found');
+  }
+}
+
+main();

package/templates/README.md

@@ -0,0 +1,202 @@
+# {{APP_NAME_TITLE}}
+
+A Weave app built with TypeScript.
+
+## 🤖 AI-Powered Development
+
+This project includes **SIDEKICK_SPEC.md** - a comprehensive specification document designed for AI assistants like Windsurf, Cursor, GitHub Copilot, and ChatGPT.
+
+### How to Use with AI:
+
+1. **Reference the spec in your prompts:**
+   ```
+   "Read SIDEKICK_SPEC.md and create a feature that..."
+   "@SIDEKICK_SPEC.md help me build a form that updates the page title"
+   ```
+
+2. **Let AI read it automatically:**
+   - In **Windsurf**: The spec is automatically available in context
+   - In **Cursor**: Use `@SIDEKICK_SPEC.md` to reference it
+   - In **GitHub Copilot**: Open the file to add it to context
+
+3. **Get accurate code generation:**
+   - AI will understand the architecture constraints
+   - Generate code using proper TypeScript imports from `@weave/app-sdk`
+   - Follow security best practices automatically
+   - Include proper error handling and TypeScript types
+
+**Pro Tip:** Keep SIDEKICK_SPEC.md open in a tab while developing. AI assistants work best when they can see the specification!
+
+---
+
+## 📝 TypeScript Development Guide
+
+### ✅ CORRECT: Import Types from SDK
+
+**ALWAYS** import types and classes from the SDK package:
+
+```typescript
+import { 
+  WeaveBaseApp, 
+  type WeaveAppInfo,
+  type AIChatRequest,
+  type AIChatResponse,
+  type AppData,
+  type CreateAppDataRequest,
+  type UpdateAppDataRequest
+} from '@weave/app-sdk';
+```
+
+### ❌ WRONG: Do NOT Copy/Paste Type Definitions
+
+**NEVER** copy type definitions into your app code. The SDK provides all types you need.
+
+---
+
+## API Usage Guide
+
+Your Weave app has access to two distinct APIs:
+
+### 1. 🧠 Weave Backend API (`weaveAPI`)
+
+Use `weaveAPI` to interact with **Weave backend services**:
+
+#### AI Chat Service
+```typescript
+import { type AIChatRequest } from '@weave/app-sdk';
+
+// Call the Weave AI service
+// Note: Your app's UUID is automatically injected
+const request: AIChatRequest = {
+  prompt: 'Summarize this text...',
+  context: 'User is working on a document'
+};
+
+const response = await weaveAPI.ai.chat(request);
+console.log(response.response);
+```
+
+#### App Data Storage
+```typescript
+import { type CreateAppDataRequest } from '@weave/app-sdk';
+
+// Save data to Weave backend
+// Note: Your app's UUID is automatically injected
+const request: CreateAppDataRequest = {
+  dataKey: 'user-preferences',
+  data: { theme: 'dark', language: 'en' }
+};
+
+const saved = await weaveAPI.appData.create(request);
+console.log('Saved with ID:', saved._id);
+
+// Load all app data
+const allData = await weaveAPI.appData.getAll();
+
+// Update specific data
+await weaveAPI.appData.update(saved._id, {
+  data: { theme: 'light' }
+});
+
+// Delete data
+await weaveAPI.appData.delete(saved._id);
+```
+
+### 2. 🌐 DOM Bridge API (`weaveDOM`)
+
+Use `weaveDOM` to interact with the **parent page DOM**:
+
+```typescript
+// Read from parent page
+const title = await weaveDOM.getText('h1');
+const hasClass = await weaveDOM.hasClass('.button', 'active');
+
+// Write to parent page
+await weaveDOM.setText('.status', 'Updated!');
+await weaveDOM.addClass('.button', 'active');
+await weaveDOM.setAttribute('input[name="email"]', 'value', 'test@example.com');
+```
+
+### ⚠️ CRITICAL: Know Which API to Use
+
+- **`weaveAPI`** → Weave backend (AI, data storage)
+- **`weaveDOM`** → Parent page DOM manipulation
+
+**Example - WRONG:**
+```typescript
+// ❌ DO NOT use weaveDOM to call AI
+await weaveDOM.callAI(...); // This doesn't exist!
+```
+
+**Example - CORRECT:**
+```typescript
+// ✅ Use weaveAPI for AI calls (app UUID auto-injected)
+await weaveAPI.ai.chat({ prompt: '...' });
+
+// ✅ Use weaveDOM for page manipulation
+await weaveDOM.setText('h1', 'New Title');
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the app
+npm run build
+```
+
+## Upload to Weave
+
+After building, upload the generated `dist/{{APP_NAME}}.js` file to the Weave Platform.
+
+## Project Structure
+
+- `src/app.ts` - Your app source code (TypeScript)
+- `dist/{{APP_NAME}}.js` - Compiled JavaScript (upload this)
+- `package.json` - Project configuration
+- `tsconfig.json` - TypeScript config (extends SDK)
+- `SIDEKICK_SPEC.md` - Complete specification for AI assistants
+
+## Build Process
+
+Running `npm run build` executes `weave-compile` which:
+1. Compiles TypeScript using SDK's configuration
+2. Removes import statements (runtime uses window globals)
+3. Replaces SDK references with window globals
+4. Generates clean, readable JavaScript
+
+**Note:** During development, use TypeScript imports. The build process converts them to window globals for runtime.
+
+## Runtime Globals
+
+After compilation, your app accesses these via window globals:
+
+- **`window.WeaveBaseApp`** - Base class for creating apps
+- **`window.weaveDOM`** - DOM manipulation API for parent page
+- **`window.weaveAPI`** - Backend API client
+  - `weaveAPI.ai.chat()` - AI chat service
+  - `weaveAPI.appData.create()` - Store app data
+  - `weaveAPI.appData.getAll()` - Retrieve app data
+  - `weaveAPI.appData.update()` - Update app data
+  - `weaveAPI.appData.delete()` - Delete app data
+
+## Documentation
+
+- **SIDEKICK_SPEC.md** - Complete specification for AI assistants (Windsurf, Cursor, etc.)
+- [Weave App SDK](https://github.com/your-org/weave-app-sdk) - Full SDK documentation
+
+---
+
+## 🎯 Quick Reference for AI Assistants
+
+When building features:
+
+1. **Import types from SDK** - Never copy/paste type definitions
+2. **Use `weaveAPI`** - For AI calls and data storage (backend)
+3. **Use `weaveDOM`** - For parent page DOM manipulation only
+4. **Extend `WeaveBaseApp`** - All apps must extend this class
+5. **Follow TypeScript patterns** - Use proper imports during development