@weave-apps/sdk 0.4.0 → 0.6.0

package/README.md

@@ -82,12 +82,14 @@ Official SDK for building third-party applications for the Weave Platform.
 ### 1. Initialize a New App
 
 ```bash
-npx weave-init my-custom-app
+npx @weave-apps/sdk my-custom-app
 cd my-custom-app
 npm install
 npm run build
 ```
 
+> **Note:** Running `npm install` will automatically create a `WEAVE_SPEC.md` file in your project root. This is an AI assistant guide for building Weave apps and is kept up to date each time you install or update the SDK.
+
 ### 2. Develop Your App
 
 Edit `src/app.ts`:

package/bin/compile.js

@@ -3,7 +3,10 @@
 /**
  * Weave App Compiler
  *
- * Compiles TypeScript and transpiles to Weave-ready JavaScript
+ * Compiles TypeScript and transpiles to Weave-ready JavaScript.
+ * Supports multi-file apps by bundling all imports into a single output file.
+ *
+ * Uses esbuild for bundling and tsc for type-checking only.
  */
 
 const { execSync } = require('child_process');
@@ -74,6 +77,27 @@ if (!fs.existsSync(tsconfigPath)) {
   process.exit(1);
 }
 
+// Look for esbuild in multiple locations
+let esbuildPath = null;
+const possibleEsbuildPaths = [
+  path.join(appDir, 'node_modules', '.bin', 'esbuild'),
+  path.join(sdkDir, 'node_modules', '.bin', 'esbuild'),
+];
+
+for (const candidate of possibleEsbuildPaths) {
+  if (fs.existsSync(candidate)) {
+    esbuildPath = candidate;
+    break;
+  }
+}
+
+if (!esbuildPath) {
+  console.error('❌ Error: esbuild not found');
+  console.error('It should be installed as part of @weave-apps/sdk.');
+  console.error('Try running: npm install');
+  process.exit(1);
+}
+
 try {
   // Create dist directory if it doesn't exist
   const distDir = path.join(appDir, 'dist');
@@ -81,35 +105,51 @@ try {
     fs.mkdirSync(distDir, { recursive: true });
   }
 
-  // Step 1: Compile TypeScript using SDK's tsconfig and TypeScript
-  console.log('📦 Compiling TypeScript...');
+  const entryPoint = path.join(appDir, 'src', 'app.ts');
+  const targetFile = path.join(distDir, `${appName}.js`);
+
+  // Step 1: Type-check with tsc (no emit)
+  console.log('� Type-checking with TypeScript...');
   const tscCommand = tscPath === 'npx tsc'
-    ? `npx tsc --project ${tsconfigPath} --outDir ${distDir} --rootDir ${appDir}/src`
-    : `"${tscPath}" --project ${tsconfigPath} --outDir ${distDir} --rootDir ${appDir}/src`;
+    ? `npx tsc --project ${tsconfigPath} --noEmit`
+    : `"${tscPath}" --project ${tsconfigPath} --noEmit`;
 
   execSync(tscCommand, {
     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('✅ Type-check passed\n');
+
+  // Step 2: Bundle with esbuild (all imports resolved into single file)
+  console.log('📦 Bundling with esbuild...');
+  const esbuildCommand = [
+    `"${esbuildPath}"`,
+    `"${entryPoint}"`,
+    '--bundle',
+    `--outfile="${targetFile}"`,
+    '--format=esm',
+    '--target=es2020',
+    '--platform=browser',
+    // Mark SDK as external — build.js will replace with window globals
+    '--external:@weave-apps/sdk',
+    '--external:@weave/app-sdk',
+  ].join(' ');
+
+  execSync(esbuildCommand, {
+    stdio: 'inherit',
+    cwd: appDir
+  });
 
-  console.log('✅ TypeScript compiled\n');
+  console.log('✅ Bundle complete\n');
 
-  // Step 2: Extract settings schema and inject into compiled JS
+  // Step 3: 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)) {
+  if (fs.existsSync(extractSchemaScript) && fs.existsSync(entryPoint)) {
     try {
-      execSync(`node "${extractSchemaScript}" "${sourceFile}" "${targetFile}"`, {
+      execSync(`node "${extractSchemaScript}" "${entryPoint}" "${targetFile}"`, {
         stdio: 'inherit',
         cwd: appDir
       });
@@ -120,7 +160,7 @@ try {
 
   console.log('');
 
-  // Step 3: Run weave-build to transpile
+  // Step 4: Run weave-build to transpile (strip imports, add window globals)
   console.log('🔧 Transpiling to Weave format...');
   const buildScript = path.join(__dirname, 'build.js');
   execSync(`node "${buildScript}"`, {

package/bin/init.js

@@ -33,13 +33,13 @@ if (appName === '--help') {
 🚀 Weave Apps SDK Help
 
 Usage:
-  weave-init <app-name>     Create a new Weave app
-  weave-init --help         Show this help message
+  npx @weave-apps/sdk <app-name>     Create a new Weave app
+  npx @weave-apps/sdk --help         Show this help message
 
 Examples:
-  weave-init my-app
-  weave-init my-custom-app
-  weave-init dashboard
+  npx @weave-apps/sdk my-app
+  npx @weave-apps/sdk my-custom-app
+  npx @weave-apps/sdk dashboard
 
 Requirements:
   • App name must be in kebab-case (lowercase with hyphens)
@@ -59,7 +59,7 @@ Learn more:
 
 if (!appName) {
   console.error('❌ Error: App name is required');
-  console.log('Usage: npx weave-init <app-name>');
+  console.log('Usage: npx @weave-apps/sdk <app-name>');
   process.exit(1);
 }
 
@@ -254,14 +254,8 @@ if (fs.existsSync(readmePath)) {
   console.warn('⚠️  Warning: README.md template not found in SDK templates');
 }
 
-// Copy WEAVE_SPEC.md from SDK templates
-const specPath = path.join(__dirname, '..', 'templates', 'WEAVE_SPEC.md');
-if (fs.existsSync(specPath)) {
-  const specContent = fs.readFileSync(specPath, 'utf8');
-  fs.writeFileSync(path.join(projectDir, 'WEAVE_SPEC.md'), specContent);
-} else {
-  console.warn('⚠️  Warning: WEAVE_SPEC.md not found in SDK templates');
-}
+// WEAVE_SPEC.md is automatically copied/updated by the SDK's postinstall script
+// each time the consumer runs npm install. It does not need to be copied here.
 
 // Create .gitignore
 const gitignore = `node_modules/
@@ -279,11 +273,10 @@ console.log('   ├── src/');
 console.log('   │   └── app.ts');
 console.log('   ├── package.json');
 console.log('   ├── tsconfig.json (extends SDK config)');
-console.log('   ├── WEAVE_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 install          # also creates WEAVE_SPEC.md (AI assistant guide)');
 console.log('   npm run build\n');
 
 // Helper functions

package/bin/postinstall.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for @weave-apps/sdk
+ *
+ * Automatically copies/updates WEAVE_SPEC.md into the consumer's project
+ * root every time the SDK is installed or updated.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Core postinstall logic. Copies WEAVE_SPEC.md from the SDK templates
+ * directory into the consumer project root.
+ *
+ * @param {string} sdkRoot - Absolute path to the SDK package root
+ * @returns {{ status: string, message: string }}
+ */
+function runPostinstall(sdkRoot) {
+  // When running as a postinstall hook inside node_modules/@weave-apps/sdk,
+  // the project root is three levels up: node_modules/@weave-apps/sdk/ -> project root
+  const projectRoot = path.resolve(sdkRoot, '..', '..', '..');
+
+  // Safety check: only run when installed as a dependency (not during SDK development)
+  const isInstalledAsDependency = sdkRoot.includes('node_modules');
+  if (!isInstalledAsDependency) {
+    return { status: 'skipped', message: 'Not installed as a dependency' };
+  }
+
+  // Safety check: ensure we resolved to a real project (has a package.json)
+  const consumerPackageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(consumerPackageJsonPath)) {
+    return { status: 'skipped', message: 'No consumer package.json found' };
+  }
+
+  const specSource = path.join(sdkRoot, 'templates', 'WEAVE_SPEC.md');
+  const specDest = path.join(projectRoot, 'WEAVE_SPEC.md');
+
+  if (!fs.existsSync(specSource)) {
+    return { status: 'skipped', message: 'WEAVE_SPEC.md template not found' };
+  }
+
+  try {
+    const specContent = fs.readFileSync(specSource, 'utf8');
+    fs.writeFileSync(specDest, specContent);
+    return { status: 'copied', message: 'WEAVE_SPEC.md updated to latest version' };
+  } catch (err) {
+    return { status: 'error', message: err.message };
+  }
+}
+
+// Run when executed directly (postinstall hook)
+if (require.main === module) {
+  const sdkRoot = path.join(__dirname, '..');
+  const result = runPostinstall(sdkRoot);
+
+  if (result.status === 'copied') {
+    console.log(`📋 @weave-apps/sdk: ${result.message}`);
+  } else if (result.status === 'error') {
+    console.warn(`⚠️  @weave-apps/sdk: Could not update WEAVE_SPEC.md: ${result.message}`);
+  }
+}
+
+module.exports = { runPostinstall };

package/bin/postinstall.test.js

@@ -0,0 +1,103 @@
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { runPostinstall } = require('./postinstall');
+
+const SPEC_CONTENT = '# Test WEAVE_SPEC content\nThis is the latest spec.';
+
+/**
+ * Creates a fake node_modules/@weave-apps/sdk directory structure
+ * inside a temporary directory to simulate a real consumer project.
+ *
+ * Returns { projectRoot, sdkRoot, cleanup }
+ */
+function createFakeProject({ withPackageJson = true, withSpecTemplate = true } = {}) {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'weave-postinstall-test-'));
+  const sdkRoot = path.join(projectRoot, 'node_modules', '@weave-apps', 'sdk');
+
+  // Create SDK directory structure
+  fs.mkdirSync(path.join(sdkRoot, 'templates'), { recursive: true });
+
+  if (withPackageJson) {
+    fs.writeFileSync(
+      path.join(projectRoot, 'package.json'),
+      JSON.stringify({ name: 'test-consumer', version: '1.0.0' })
+    );
+  }
+
+  if (withSpecTemplate) {
+    fs.writeFileSync(path.join(sdkRoot, 'templates', 'WEAVE_SPEC.md'), SPEC_CONTENT);
+  }
+
+  const cleanup = () => fs.rmSync(projectRoot, { recursive: true, force: true });
+
+  return { projectRoot, sdkRoot, cleanup };
+}
+
+describe('postinstall', () => {
+  let project;
+
+  afterEach(() => {
+    if (project) {
+      project.cleanup();
+      project = null;
+    }
+  });
+
+  it('copies WEAVE_SPEC.md to consumer project root when installed as dependency', () => {
+    project = createFakeProject();
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'copied');
+    const dest = path.join(project.projectRoot, 'WEAVE_SPEC.md');
+    assert.ok(fs.existsSync(dest), 'WEAVE_SPEC.md should exist in project root');
+    assert.equal(fs.readFileSync(dest, 'utf8'), SPEC_CONTENT);
+  });
+
+  it('overwrites existing WEAVE_SPEC.md with latest version', () => {
+    project = createFakeProject();
+    const dest = path.join(project.projectRoot, 'WEAVE_SPEC.md');
+
+    // Write an old version first
+    fs.writeFileSync(dest, '# Old spec content');
+
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'copied');
+    assert.equal(fs.readFileSync(dest, 'utf8'), SPEC_CONTENT);
+  });
+
+  it('skips when not installed as a dependency (SDK development)', () => {
+    // Use a path that does NOT contain "node_modules"
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'weave-postinstall-dev-'));
+    const fakeSdkRoot = path.join(tmpDir, 'frontends', 'app-sdk');
+    fs.mkdirSync(path.join(fakeSdkRoot, 'templates'), { recursive: true });
+    fs.writeFileSync(path.join(fakeSdkRoot, 'templates', 'WEAVE_SPEC.md'), SPEC_CONTENT);
+
+    const result = runPostinstall(fakeSdkRoot);
+
+    assert.equal(result.status, 'skipped');
+    assert.match(result.message, /Not installed as a dependency/);
+
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('skips when no consumer package.json found', () => {
+    project = createFakeProject({ withPackageJson: false });
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'skipped');
+    assert.match(result.message, /No consumer package\.json found/);
+  });
+
+  it('skips when WEAVE_SPEC.md template is missing from SDK', () => {
+    project = createFakeProject({ withSpecTemplate: false });
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'skipped');
+    assert.match(result.message, /template not found/);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weave-apps/sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "SDK for building Weave Micro Apps",
   "publishConfig": {
     "access": "public"
@@ -19,7 +19,9 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node bin/postinstall.js",
+    "test": "node --test bin/*.test.js"
   },
   "keywords": [
     "weave",
@@ -30,6 +32,7 @@
   "author": "Weave Platform",
   "license": "MIT",
   "dependencies": {
+    "esbuild": "^0.24.0",
     "typescript": "^5.9.3"
   },
   "devDependencies": {

package/templates/WEAVE_SPEC.md

@@ -2,6 +2,9 @@
 
 > **AI Assistant Guide**: This document provides the complete specification for building Weave applications. Use this as your reference when helping developers create apps.
 
+> **Note**: When you update the SDK in your project, this SPEC sheet will be overwritten with the latest version.
+
+
 ## Architecture Overview
 
 Weave apps are **Web Components** that run in an **iframe** inside a browser extension sidebar. They interact with two secure APIs: