@weave-apps/sdk 0.4.0 → 0.5.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/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.5.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",

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: