@weave-apps/sdk 0.1.0

package/README.md

@@ -0,0 +1,241 @@
+# Weave App SDK
+
+Official SDK for building third-party applications for the Weave Platform.
+
+## Features
+
+- ✅ **TypeScript Support** - Write apps in TypeScript with full type safety
+- ✅ **Clean JavaScript Output** - Transpiles to readable, unobfuscated JavaScript
+- ✅ **Security Review Ready** - Generated code is easy to audit
+- ✅ **Project Scaffolding** - Quick start with `weave-init`
+- ✅ **DOM API** - Secure parent page DOM manipulation
+- ✅ **Shadow DOM Isolation** - Scoped styles and encapsulation
+
+## Installation
+
+Install directly from GitHub:
+
+```bash
+npm install github:your-org/weave-app-sdk
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "@weave/app-sdk": "github:your-org/weave-app-sdk"
+  }
+}
+```
+
+## Quick Start
+
+### 1. Initialize a New App
+
+```bash
+npx weave-init my-custom-app
+cd my-custom-app
+npm install
+```
+
+### 2. Develop Your App
+
+Edit `src/app.ts`:
+
+```typescript
+import { WeaveBaseApp } from '@weave/app-sdk';
+
+class MyCustomApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'my-custom-app',
+      name: 'My Custom App',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'My awesome app',
+      author: 'Your Name',
+      tags: ['custom']
+    });
+  }
+
+  protected render(): void {
+    this.renderHTML(`
+      <style>
+        .container { padding: 20px; }
+        button { padding: 10px 20px; }
+      </style>
+      <div class="container">
+        <h1>Hello Weave!</h1>
+        <button id="myBtn">Click Me</button>
+      </div>
+    `);
+  }
+
+  protected setupEventListeners(): void {
+    this.query('#myBtn')?.addEventListener('click', () => {
+      alert('Button clicked!');
+    });
+  }
+}
+
+customElements.define('my-custom-app', MyCustomApp);
+```
+
+### 3. Build Your App
+
+```bash
+npm run build
+```
+
+This runs:
+1. `tsc` - Compiles TypeScript to JavaScript
+2. `weave-build` - Transpiles to clean, platform-ready JavaScript
+
+Output: `dist/app.js` - ready for upload to Weave Platform.
+
+### 4. Upload to Weave
+
+Upload the generated `dist/app.js` file to the Weave Platform via the Enterprise Management Console.
+
+## API Reference
+
+### WeaveBaseApp
+
+Base class for all Weave apps.
+
+#### Constructor
+
+```typescript
+constructor(appInfo: WeaveAppInfo)
+```
+
+**App Info:**
+- `id` (string) - Unique identifier (kebab-case)
+- `name` (string) - Display name
+- `version` (string) - Semantic version (x.y.z)
+- `category` (string) - App category
+- `description` (string) - Detailed description
+- `author` (string) - Author name
+- `tags` (string[]) - Optional tags
+
+#### Methods to Implement
+
+##### `render(): void`
+Render your app's UI. Use `this.renderHTML()` to inject HTML.
+
+##### `setupEventListeners(): void` (Optional)
+Setup event listeners for your app's elements.
+
+##### `cleanup(): void` (Optional)
+Cleanup when app is removed from DOM.
+
+#### Helper Methods
+
+##### `renderHTML(html: string): void`
+Renders HTML into the shadow root.
+
+##### `query<T>(selector: string): T | null`
+Query a single element in shadow root.
+
+##### `queryAll<T>(selector: string): NodeListOf<T>`
+Query all matching elements in shadow root.
+
+##### `setState(updates: object): void`
+Update app state.
+
+### WeaveDOMAPI
+
+API for interacting with the parent page DOM.
+
+**Available globally as `window.weaveDOM`**
+
+#### Read Operations
+
+```typescript
+// Query element
+const element = await window.weaveDOM.query('h1');
+
+// Get text content
+const text = await window.weaveDOM.getText('h1');
+
+// Get attribute
+const href = await window.weaveDOM.getAttribute('a', 'href');
+
+// Check if element has class
+const hasClass = await window.weaveDOM.hasClass('.btn', 'active');
+```
+
+#### Write Operations
+
+```typescript
+// Set text
+await window.weaveDOM.setText('h1', 'New Title');
+
+// Add class
+await window.weaveDOM.addClass('.btn', 'active');
+
+// Set style
+await window.weaveDOM.setStyle('h1', 'color', 'red');
+
+// Set attribute
+await window.weaveDOM.setAttribute('input', 'placeholder', 'Enter text');
+```
+
+#### DOM Manipulation
+
+```typescript
+// Insert HTML
+await window.weaveDOM.insertHTML('.container', '<p>New content</p>', 'beforeend');
+
+// Remove element
+await window.weaveDOM.removeElement('.old-element');
+```
+
+## Build Process
+
+The build uses two commands:
+
+1. **`tsc`** - TypeScript compiler (ES2020 target)
+2. **`weave-build`** - SDK's build tool that:
+   - Removes import statements (SDK is global)
+   - Replaces SDK references with `window.*`
+   - Adds header comment
+   - Generates clean, readable JavaScript
+
+You can also run `weave-build` manually after compiling:
+```bash
+tsc
+weave-build
+```
+
+## Security
+
+- ✅ **Selector Validation** - Prevents dangerous selectors
+- ✅ **HTML Sanitization** - Removes scripts and event handlers
+- ✅ **Attribute Whitelist** - Blocks dangerous attributes
+- ✅ **Shadow DOM Isolation** - Scoped styles and encapsulation
+- ✅ **No Direct DOM Access** - All operations go through secure bridge
+
+## Project Structure
+
+```
+my-app/
+├── src/
+│   └── app.ts          # Your TypeScript source
+├── dist/
+│   └── app.js          # Compiled JavaScript (upload this)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+**Note:** The build script (`weave-build`) is part of the SDK, not copied to your app.
+
+## Examples
+
+See the [examples directory](./examples) for complete app examples.
+
+## License
+
+MIT

package/bin/build.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+ * Weave App Builder
+ * 
+ * Transpiles TypeScript to clean JavaScript for Weave Platform
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Get the app directory (where this is being run from)
+const appDir = process.cwd();
+
+// Get app name from package.json
+let appName = 'app';
+let appDisplayName = 'Weave App';
+try {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8'));
+  appName = packageJson.name || appName;
+  appDisplayName = packageJson.name || appDisplayName;
+} catch (e) {
+  console.error('❌ Error: Could not read package.json');
+  process.exit(1);
+}
+
+const distFile = path.join(appDir, 'dist', `${appName}.js`);
+
+// Check if dist file exists
+if (!fs.existsSync(distFile)) {
+  console.error(`❌ Error: dist/${appName}.js not found`);
+  console.error('Run "tsc" first to compile TypeScript');
+  process.exit(1);
+}
+
+console.log('🔨 Building Weave app...\n');
+
+// Read compiled TypeScript output
+let code = fs.readFileSync(distFile, 'utf8');
+
+// Remove import statements (SDK is globally available)
+code = code.replace(/^import .* from .*$/gm, '');
+code = code.replace(/^import .*$/gm, '');
+
+// Remove export statements
+code = code.replace(/^export \{[^}]*\};?$/gm, '');
+code = code.replace(/^export /gm, '');
+
+// Replace WeaveBaseApp with window.WeaveBaseApp
+code = code.replace(/extends WeaveBaseApp/g, 'extends window.WeaveBaseApp');
+
+// Replace weaveDOM with window.weaveDOM (but not if already prefixed)
+code = code.replace(/(?<!window\.)weaveDOM\./g, 'window.weaveDOM.');
+
+// Replace weaveAPI with window.weaveAPI (but not if already prefixed)
+code = code.replace(/(?<!window\.)weaveAPI\./g, 'window.weaveAPI.');
+
+// Remove empty lines created by removals
+code = code.replace(/\n\n\n+/g, '\n\n');
+
+// Add header comment
+const header = `/**
+ * ${appDisplayName}
+ * 
+ * Built with Weave App SDK
+ * Generated: ${new Date().toISOString()}
+ */
+
+// Access SDK from window globals
+const { WeaveBaseApp, weaveDOM } = window;
+
+`;
+
+code = header + code;
+
+// Write final JavaScript
+fs.writeFileSync(distFile, code);
+
+console.log('✅ Build complete:', distFile);
+console.log('📦 Ready to upload to Weave Platform\n');
+console.log('File size:', Math.round(code.length / 1024), 'KB');

package/bin/compile.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+/**
+ * Weave App Compiler
+ * 
+ * Compiles TypeScript and transpiles to Weave-ready JavaScript
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Get the app directory (where this is being run from)
+const appDir = process.cwd();
+
+// Get app name from package.json
+let appName = 'app';
+try {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8'));
+  appName = packageJson.name || appName;
+} catch (e) {
+  console.error('❌ Error: Could not read package.json');
+  process.exit(1);
+}
+
+console.log('🔨 Compiling Weave app...\n');
+
+// Check if src directory exists
+if (!fs.existsSync(path.join(appDir, 'src'))) {
+  console.error('❌ Error: src/ directory not found');
+  console.error('Make sure you are in the app directory');
+  process.exit(1);
+}
+
+// Get SDK directory (where this script is located)
+const sdkDir = path.join(__dirname, '..');
+const tscPath = path.join(sdkDir, 'node_modules', '.bin', 'tsc');
+
+// Use app's tsconfig.json (which extends SDK's config)
+const tsconfigPath = path.join(appDir, 'tsconfig.json');
+
+// Check if tsconfig exists in app
+if (!fs.existsSync(tsconfigPath)) {
+  console.error('❌ Error: tsconfig.json not found in app directory');
+  console.error('Make sure you ran weave-init to create the project');
+  process.exit(1);
+}
+
+// Check if TypeScript exists in SDK
+if (!fs.existsSync(tscPath)) {
+  console.error('❌ Error: TypeScript not found in SDK');
+  console.error('Run: cd SDK && npm install');
+  process.exit(1);
+}
+
+try {
+  // Create dist directory if it doesn't exist
+  const distDir = path.join(appDir, 'dist');
+  if (!fs.existsSync(distDir)) {
+    fs.mkdirSync(distDir, { recursive: true });
+  }
+
+  // Step 1: Compile TypeScript using SDK's tsconfig and TypeScript
+  console.log('📦 Compiling TypeScript...');
+  execSync(`${tscPath} --project ${tsconfigPath} --outDir ${distDir} --rootDir ${appDir}/src`, {
+    stdio: 'inherit',
+    cwd: appDir
+  });
+  
+  // Rename app.js to {appName}.js
+  const compiledFile = path.join(distDir, 'app.js');
+  const targetFile = path.join(distDir, `${appName}.js`);
+  
+  if (fs.existsSync(compiledFile)) {
+    fs.renameSync(compiledFile, targetFile);
+  }
+  
+  console.log('✅ TypeScript compiled\n');
+
+  // Step 2: Extract settings schema and inject into compiled JS
+  console.log('📋 Extracting settings schema...');
+  const extractSchemaScript = path.join(sdkDir, 'scripts', 'extract-settings-schema.js');
+  const sourceFile = path.join(appDir, 'src', 'app.ts');
+  
+  if (fs.existsSync(extractSchemaScript) && fs.existsSync(sourceFile)) {
+    try {
+      execSync(`node ${extractSchemaScript} ${sourceFile} ${targetFile}`, {
+        stdio: 'inherit',
+        cwd: appDir
+      });
+    } catch (error) {
+      console.warn('⚠️  Schema extraction failed (non-fatal)');
+    }
+  }
+  
+  console.log('');
+
+  // Step 3: Run weave-build to transpile
+  console.log('🔧 Transpiling to Weave format...');
+  const buildScript = path.join(__dirname, 'build.js');
+  execSync(`node ${buildScript}`, {
+    stdio: 'inherit',
+    cwd: appDir
+  });
+
+} catch (error) {
+  console.error('\n❌ Build failed');
+  process.exit(1);
+}

package/bin/init.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * Weave App Initializer
+ * 
+ * Creates a new Weave app project with TypeScript setup
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const args = process.argv.slice(2);
+const appName = args[0];
+
+if (!appName) {
+  console.error('❌ Error: App name is required');
+  console.log('Usage: npx weave-init <app-name>');
+  process.exit(1);
+}
+
+// Validate app name (kebab-case)
+if (!/^[a-z][a-z0-9-]*$/.test(appName)) {
+  console.error('❌ Error: App name must be in kebab-case (e.g., my-custom-app)');
+  process.exit(1);
+}
+
+const projectDir = path.join(process.cwd(), appName);
+
+// Check if directory already exists
+if (fs.existsSync(projectDir)) {
+  console.error(`❌ Error: Directory "${appName}" already exists`);
+  process.exit(1);
+}
+
+console.log(`\n🚀 Creating Weave app: ${appName}\n`);
+
+// Create project directory
+fs.mkdirSync(projectDir, { recursive: true });
+fs.mkdirSync(path.join(projectDir, 'src'), { recursive: true });
+
+// Create package.json
+const packageJson = {
+  name: appName,
+  version: '1.0.0',
+  description: 'A Weave app',
+  main: `dist/${appName}.js`,
+  scripts: {
+    build: 'weave-compile',
+    clean: 'rm -rf dist'
+  },
+  devDependencies: {
+    '@weave/app-sdk': 'github:your-org/weave-app-sdk'
+  }
+};
+
+fs.writeFileSync(
+  path.join(projectDir, 'package.json'),
+  JSON.stringify(packageJson, null, 2)
+);
+
+// Create minimal tsconfig.json that extends SDK's config
+// This is needed for IDE support (IntelliSense, type checking, etc.)
+const tsConfig = {
+  extends: '@weave/app-sdk/tsconfig.app.json',
+  compilerOptions: {
+    baseUrl: '.',
+    paths: {
+      '@weave/app-sdk': ['node_modules/@weave/app-sdk/dist']
+    }
+  },
+  include: ['src/**/*'],
+  exclude: ['node_modules', 'dist']
+};
+
+fs.writeFileSync(
+  path.join(projectDir, 'tsconfig.json'),
+  JSON.stringify(tsConfig, null, 2)
+);
+
+// Copy app template from SDK
+const templateDir = path.join(__dirname, '..', 'templates');
+const appTemplate = `import { WeaveBaseApp, WeaveAppInfo } from '@weave/app-sdk';
+
+// Define settings type for this app, this is a way of injecting settings into the app from the Enterprise Console
+// These will be auto-extracted and displayed in the Enterprise Console
+interface ${toPascalCase(appName)}Settings {
+  /**
+   * @description Example setting - API endpoint URL
+   * @default "https://api.example.com"
+   */
+  apiEndpoint?: string;
+
+  /**
+   * @description Example setting - Enable debug mode
+   * @default false
+   */
+  debugMode?: boolean;
+}
+
+// Define state type for this app
+interface ${toPascalCase(appName)}State {
+  count: number;
+  lastUpdated?: Date;
+}
+
+class ${toPascalCase(appName)} extends WeaveBaseApp<${toPascalCase(appName)}Settings, ${toPascalCase(appName)}State> {
+  constructor() {
+    super({
+      id: '${appName}',
+      name: '${toTitleCase(appName)}',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'My custom Weave app',
+      author: 'Your Name',
+      tags: ['custom']
+    });
+
+    // Initialize app state with type safety
+    this.state = {
+      count: 0
+    };
+
+    // Access settings with type safety
+    console.log('API Endpoint:', this.appSettings?.apiEndpoint);
+    console.log('Debug Mode:', this.appSettings?.debugMode);
+  }
+
+  protected render(): void {
+    this.renderHTML(\`
+      <style>
+        * {
+          margin: 0;
+          padding: 0;
+          box-sizing: border-box;
+        }
+        
+        .app-container {
+          padding: 20px;
+          font-family: system-ui, -apple-system, sans-serif;
+        }
+        
+        h1 {
+          font-size: 1.5rem;
+          margin-bottom: 1rem;
+          color: #111827;
+        }
+        
+        button {
+          padding: 10px 20px;
+          background: #4f46e5;
+          color: white;
+          border: none;
+          border-radius: 6px;
+          cursor: pointer;
+          font-size: 14px;
+          font-weight: 500;
+        }
+        
+        button:hover {
+          background: #4338ca;
+        }
+      </style>
+
+      <div class="app-container">
+        <h1>${toTitleCase(appName)}</h1>
+        <p>Count: <span id="count">0</span></p>
+        <button id="incrementBtn">Increment</button>
+      </div>
+    \`);
+  }
+
+  protected setupEventListeners(): void {
+    this.query('#incrementBtn')?.addEventListener('click', () => {
+      this.handleIncrement();
+    });
+  }
+
+  private handleIncrement(): void {
+    this.setState({ count: this.state.count + 1 });
+    const countEl = this.query('#count');
+    if (countEl) {
+      countEl.textContent = String(this.state.count);
+    }
+  }
+}
+
+// Register custom element
+customElements.define('${appName}', ${toPascalCase(appName)});
+`;
+
+fs.writeFileSync(path.join(projectDir, 'src', 'app.ts'), appTemplate);
+
+// Create README from template
+const readmePath = path.join(__dirname, '..', 'templates', 'README.md');
+if (fs.existsSync(readmePath)) {
+  let readmeContent = fs.readFileSync(readmePath, 'utf8');
+  // Replace placeholders
+  readmeContent = readmeContent.replace(/\{\{APP_NAME_TITLE\}\}/g, toTitleCase(appName));
+  readmeContent = readmeContent.replace(/\{\{APP_NAME\}\}/g, appName);
+  fs.writeFileSync(path.join(projectDir, 'README.md'), readmeContent);
+} else {
+  console.warn('⚠️  Warning: README.md template not found in SDK templates');
+}
+
+// Copy SIDEKICK_SPEC.md from SDK templates
+const specPath = path.join(__dirname, '..', 'templates', 'SIDEKICK_SPEC.md');
+if (fs.existsSync(specPath)) {
+  const specContent = fs.readFileSync(specPath, 'utf8');
+  fs.writeFileSync(path.join(projectDir, 'SIDEKICK_SPEC.md'), specContent);
+} else {
+  console.warn('⚠️  Warning: SIDEKICK_SPEC.md not found in SDK templates');
+}
+
+// Create .gitignore
+const gitignore = `node_modules/
+dist/
+*.log
+.DS_Store
+`;
+
+fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignore);
+
+console.log('✅ Project created successfully!\n');
+console.log('📁 Project structure:');
+console.log(`   ${appName}/`);
+console.log('   ├── src/');
+console.log('   │   └── app.ts');
+console.log('   ├── package.json');
+console.log('   ├── tsconfig.json (extends SDK config)');
+console.log('   ├── SIDEKICK_SPEC.md (AI assistant guide)');
+console.log('   └── README.md\n');
+console.log('🚀 Next steps:');
+console.log(`   cd ${appName}`);
+console.log('   npm install');
+console.log('   npm run build\n');
+
+// Helper functions
+function toPascalCase(str) {
+  return str
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
+function toTitleCase(str) {
+  return str
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}