@kya-os/create-mcpi-app 1.7.19 → 1.7.20

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@kya-os/create-mcpi-app",
-  "version": "1.7.19",
+  "version": "1.7.20",
   "description": "Bootstrap MCP applications with identity features",
   "type": "module",
-  "bin": {
-    "create-mcpi-app": "index.js"
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./config-builder": {
+      "import": "./dist/helpers/config-builder.js",
+      "require": "./dist/helpers/config-builder.js",
+      "types": "./dist/helpers/config-builder.d.ts"
+    }
   },
-  "files": [
-    "index.js",
-    "dist/**/*"
-  ],
   "scripts": {
     "build": "tsc --build && chmod +x dist/index.js",
     "dev": "tsc --watch",

package/scripts/prepare-pack.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+/**
+ * Prepare package for npm pack by ensuring no workspace: references
+ * This script is run before npm pack in CI to ensure clean dependencies
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const packagePath = path.join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
+
+// Map of workspace dependencies to their published versions
+const workspaceMap = {
+  '@kya-os/contracts': '^1.2.1',
+  '@kya-os/cli': '^1.2.4',
+  '@kya-os/cli-effects': '^1.0.9',
+  '@kya-os/mcp-i': '^1.2.3'
+};
+
+// Replace any workspace:* dependencies with published versions
+if (packageJson.dependencies) {
+  for (const [dep, version] of Object.entries(packageJson.dependencies)) {
+    if (version === 'workspace:*' && workspaceMap[dep]) {
+      console.log(`Replacing ${dep}: workspace:* → ${workspaceMap[dep]}`);
+      packageJson.dependencies[dep] = workspaceMap[dep];
+    }
+  }
+}
+
+if (packageJson.devDependencies) {
+  for (const [dep, version] of Object.entries(packageJson.devDependencies)) {
+    if (version === 'workspace:*' && workspaceMap[dep]) {
+      console.log(`Replacing ${dep}: workspace:* → ${workspaceMap[dep]}`);
+      packageJson.devDependencies[dep] = workspaceMap[dep];
+    }
+  }
+}
+
+// Write the updated package.json
+fs.writeFileSync(packagePath, JSON.stringify(packageJson, null, 2) + '\n');
+console.log('✅ Package prepared for packing');

package/scripts/validate-no-workspace.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * Validate that package.json has no workspace: references before publishing
+ * This prevents publishing broken packages to npm
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Find package.json (supports being run from any package)
+let packagePath;
+if (fs.existsSync(path.join(process.cwd(), 'package.json'))) {
+  packagePath = path.join(process.cwd(), 'package.json');
+} else if (fs.existsSync(path.join(__dirname, '..', 'package.json'))) {
+  packagePath = path.join(__dirname, '..', 'package.json');
+} else {
+  console.error('❌ Cannot find package.json');
+  process.exit(1);
+}
+
+const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
+const packageName = packageJson.name || 'unknown';
+
+// Skip root monorepo package - it's not published
+if (packageName === 'mcp-monorepo') {
+  console.log(`⏭️  Skipping root monorepo package (not published)`);
+  process.exit(0);
+}
+
+console.log(`🔍 Validating ${packageName} has no workspace: references...`);
+
+let hasWorkspaceRefs = false;
+
+// Check dependencies
+if (packageJson.dependencies) {
+  for (const [dep, version] of Object.entries(packageJson.dependencies)) {
+    if (typeof version === 'string' && version.includes('workspace:')) {
+      console.error(`❌ Found workspace: reference in dependencies: ${dep}: ${version}`);
+      hasWorkspaceRefs = true;
+    }
+  }
+}
+
+// Check devDependencies
+if (packageJson.devDependencies) {
+  for (const [dep, version] of Object.entries(packageJson.devDependencies)) {
+    if (typeof version === 'string' && version.includes('workspace:')) {
+      console.error(`❌ Found workspace: reference in devDependencies: ${dep}: ${version}`);
+      hasWorkspaceRefs = true;
+    }
+  }
+}
+
+// Check peerDependencies
+if (packageJson.peerDependencies) {
+  for (const [dep, version] of Object.entries(packageJson.peerDependencies)) {
+    if (typeof version === 'string' && version.includes('workspace:')) {
+      console.error(`❌ Found workspace: reference in peerDependencies: ${dep}: ${version}`);
+      hasWorkspaceRefs = true;
+    }
+  }
+}
+
+if (hasWorkspaceRefs) {
+  console.error('');
+  console.error('❌ PUBLISH BLOCKED: workspace: references found in package.json');
+  console.error('');
+  console.error('Please replace all workspace: references with actual version numbers.');
+  console.error('Example: "workspace:*" → "^1.0.0"');
+  console.error('');
+  process.exit(1);
+}
+
+console.log(`✅ ${packageName} validation passed - no workspace: references`);

package/src/__tests__/cloudflare-template.test.ts

@@ -0,0 +1,488 @@
+/**
+ * Cloudflare Template Tests
+ *
+ * Tests for Cloudflare Worker template generation, including file structure,
+ * configuration, KV namespace setup, and tool protection configuration.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "fs-extra";
+import path from "path";
+import { fetchCloudflareMcpiTemplate } from "../helpers/fetch-cloudflare-mcpi-template";
+
+describe("Cloudflare Template Generation", () => {
+  let tempDir: string;
+  const originalConsoleLog = console.log;
+  const originalConsoleError = console.error;
+
+  beforeEach(() => {
+    // Create temporary directory for each test
+    tempDir = path.join(
+      process.cwd(),
+      "test-temp",
+      `test-${Date.now()}-${Math.random().toString(36).substring(7)}`
+    );
+    fs.ensureDirSync(tempDir);
+
+    // Suppress console output during tests
+    console.log = vi.fn();
+    console.error = vi.fn();
+  });
+
+  afterEach(async () => {
+    // Clean up temporary directory
+    if (fs.existsSync(tempDir)) {
+      try {
+        fs.removeSync(tempDir);
+      } catch (error) {
+        // Ignore errors if directory is already being cleaned up by another test
+      }
+    }
+
+    // Only try to remove parent directory if it exists and is empty
+    const testTempDir = path.join(process.cwd(), "test-temp");
+    if (fs.existsSync(testTempDir)) {
+      try {
+        const testTempContents = fs.readdirSync(testTempDir);
+        if (testTempContents.length === 0) {
+          fs.removeSync(testTempDir);
+        }
+      } catch (error) {
+        // Ignore errors if directory is being modified by another test
+      }
+    }
+
+    // Restore console
+    console.log = originalConsoleLog;
+    console.error = originalConsoleError;
+  });
+
+  describe("Basic template structure", () => {
+    it("should create all required files and directories", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+        skipIdentity: false,
+      });
+
+      // Check package.json exists
+      expect(fs.existsSync(path.join(tempDir, "package.json"))).toBe(true);
+
+      // Check src directory structure
+      expect(fs.existsSync(path.join(tempDir, "src"))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, "src", "tools"))).toBe(true);
+      expect(
+        fs.existsSync(path.join(tempDir, "src", "tools", "greet.ts"))
+      ).toBe(true);
+
+      // Check scripts directory
+      expect(fs.existsSync(path.join(tempDir, "scripts"))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, "scripts", "setup.js"))).toBe(
+        true
+      );
+
+      // Check configuration files
+      expect(fs.existsSync(path.join(tempDir, "wrangler.toml"))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, "tsconfig.json"))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, ".gitignore"))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, "README.md"))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, "vitest.config.ts"))).toBe(true);
+    });
+
+    it("should create mcpi-runtime-config.ts with correct structure", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const configPath = path.join(tempDir, "src", "mcpi-runtime-config.ts");
+      expect(fs.existsSync(configPath)).toBe(true);
+
+      const configContent = fs.readFileSync(configPath, "utf-8");
+      expect(configContent).toContain("getRuntimeConfig");
+      expect(configContent).toContain("buildBaseConfig");
+      expect(configContent).toContain("CloudflareRuntimeConfig");
+    });
+
+    it("should create index.ts with correct structure", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const indexPath = path.join(tempDir, "src", "index.ts");
+      expect(fs.existsSync(indexPath)).toBe(true);
+
+      const indexContent = fs.readFileSync(indexPath, "utf-8");
+      expect(indexContent).toContain("McpAgent");
+      expect(indexContent).toContain("createCloudflareRuntime");
+      expect(indexContent).toContain("class");
+    });
+  });
+
+  describe("MCP_SERVER_URL configuration", () => {
+    it("should include MCP_SERVER_URL placeholder in wrangler.toml", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const wranglerPath = path.join(tempDir, "wrangler.toml");
+      const wranglerContent = fs.readFileSync(wranglerPath, "utf-8");
+
+      expect(wranglerContent).toContain("MCP_SERVER_URL");
+      expect(wranglerContent).toContain(
+        "Optional: MCP Server URL for tool discovery"
+      );
+    });
+
+    it("should log warning when MCP_SERVER_URL not configured", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const indexPath = path.join(tempDir, "src", "index.ts");
+      const indexContent = fs.readFileSync(indexPath, "utf-8");
+
+      // Check that warning is logged in index.ts
+      expect(indexContent).toContain("Warning: MCP_SERVER_URL not configured");
+    });
+
+    it("should store MCP_SERVER_URL in class property", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const indexPath = path.join(tempDir, "src", "index.ts");
+      const indexContent = fs.readFileSync(indexPath, "utf-8");
+
+      expect(indexContent).toContain("this.mcpServerUrl");
+      expect(indexContent).toContain("env.MCP_SERVER_URL");
+    });
+  });
+
+  describe("KV namespace setup", () => {
+    it("should include all required KV namespace bindings in wrangler.toml", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "TestProject",
+      });
+
+      const wranglerPath = path.join(tempDir, "wrangler.toml");
+      const wranglerContent = fs.readFileSync(wranglerPath, "utf-8");
+
+      // Check for all KV namespace bindings (using className TESTPROJECT)
+      expect(wranglerContent).toContain("TESTPROJECT_NONCE_CACHE");
+      expect(wranglerContent).toContain("TESTPROJECT_PROOF_ARCHIVE");
+      expect(wranglerContent).toContain("TESTPROJECT_IDENTITY_STORAGE");
+      expect(wranglerContent).toContain("TESTPROJECT_DELEGATION_STORAGE");
+      expect(wranglerContent).toContain("TESTPROJECT_TOOL_PROTECTION_KV");
+    });
+
+    it("should create KV namespace creation scripts in package.json", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const packageJsonPath = path.join(tempDir, "package.json");
+      const packageJson = fs.readJsonSync(packageJsonPath);
+
+      expect(packageJson.scripts).toHaveProperty("kv:create");
+      expect(packageJson.scripts).toHaveProperty("kv:create-nonce");
+      expect(packageJson.scripts).toHaveProperty("kv:create-proof");
+      expect(packageJson.scripts).toHaveProperty("kv:create-identity");
+      expect(packageJson.scripts).toHaveProperty("kv:create-delegation");
+      expect(packageJson.scripts).toHaveProperty("kv:create-tool-protection");
+    });
+
+    it("should create KV namespace listing scripts", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const packageJsonPath = path.join(tempDir, "package.json");
+      const packageJson = fs.readJsonSync(packageJsonPath);
+
+      expect(packageJson.scripts).toHaveProperty("kv:list");
+      expect(packageJson.scripts).toHaveProperty("kv:keys-nonce");
+      expect(packageJson.scripts).toHaveProperty("kv:keys-proof");
+      expect(packageJson.scripts).toHaveProperty("kv:keys-identity");
+      expect(packageJson.scripts).toHaveProperty("kv:keys-delegation");
+      expect(packageJson.scripts).toHaveProperty("kv:keys-tool-protection");
+    });
+  });
+
+  describe("Tool protection setup", () => {
+    it("should include tool protection configuration in runtime config", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+        apikey: "test-api-key",
+      });
+
+      const configPath = path.join(tempDir, "src", "mcpi-runtime-config.ts");
+      const configContent = fs.readFileSync(configPath, "utf-8");
+
+      expect(configContent).toContain("toolProtection");
+      expect(configContent).toContain("CloudflareRuntime");
+    });
+
+    it("should include CloudflareRuntime import for tool protection", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const configPath = path.join(tempDir, "src", "mcpi-runtime-config.ts");
+      const configContent = fs.readFileSync(configPath, "utf-8");
+
+      expect(configContent).toContain("CloudflareRuntime");
+      expect(configContent).toContain('from "@kya-os/mcp-i-cloudflare"');
+    });
+
+    it("should conditionally enable tool protection KV when API key provided", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+        apikey: "test-api-key",
+      });
+
+      const wranglerPath = path.join(tempDir, "wrangler.toml");
+      const wranglerContent = fs.readFileSync(wranglerPath, "utf-8");
+
+      // When API key is provided, TOOL_PROTECTION_KV should not be commented out
+      const lines = wranglerContent.split("\n");
+      const toolProtectionLines = lines.filter((line) =>
+        line.includes("TOOL_PROTECTION_KV")
+      );
+      const commentedLines = toolProtectionLines.filter((line) =>
+        line.trim().startsWith("#")
+      );
+
+      // Should have some non-commented lines for TOOL_PROTECTION_KV
+      expect(toolProtectionLines.length).toBeGreaterThan(0);
+    });
+
+    it("should comment out tool protection KV when no API key provided", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const wranglerPath = path.join(tempDir, "wrangler.toml");
+      const wranglerContent = fs.readFileSync(wranglerPath, "utf-8");
+
+      // Tool protection KV is always included (not conditionally commented)
+      // The namespace is automatically created by the setup script
+      const lines = wranglerContent.split("\n");
+      const bindingLine = lines.find(
+        (line) =>
+          line.includes("binding =") && line.includes("TOOL_PROTECTION_KV")
+      );
+
+      // Should be present and not commented out
+      expect(bindingLine).toBeDefined();
+      expect(bindingLine?.trim().startsWith("#")).toBe(false);
+    });
+  });
+
+  describe("Identity provider configuration", () => {
+    it("should generate identity when skipIdentity is false", async () => {
+      const generateIdentitySpy = vi.spyOn(
+        await import("../helpers/generate-identity"),
+        "generateIdentity"
+      );
+      generateIdentitySpy.mockResolvedValue({
+        did: "did:key:ztest123",
+        kid: "did:key:ztest123#key-1",
+        privateKey: "test-private-key",
+        publicKey: "test-public-key",
+        createdAt: new Date().toISOString(),
+        type: "development",
+      });
+
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+        skipIdentity: false,
+      });
+
+      // Check that identity was generated (would be in .dev.vars)
+      const devVarsPath = path.join(tempDir, ".dev.vars");
+      if (fs.existsSync(devVarsPath)) {
+        const devVarsContent = fs.readFileSync(devVarsPath, "utf-8");
+        expect(devVarsContent).toContain("MCP_IDENTITY_PRIVATE_KEY");
+        expect(devVarsContent).toContain("MCP_IDENTITY_PUBLIC_KEY");
+      }
+
+      generateIdentitySpy.mockRestore();
+    });
+
+    it("should skip identity generation when skipIdentity is true", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+        skipIdentity: true,
+      });
+
+      // Identity should not be generated
+      const devVarsPath = path.join(tempDir, ".dev.vars");
+      // When skipIdentity is true, .dev.vars might not exist or might not have identity
+      // This is expected behavior
+    });
+
+    it("should include identity variables in wrangler.toml", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const wranglerPath = path.join(tempDir, "wrangler.toml");
+      const wranglerContent = fs.readFileSync(wranglerPath, "utf-8");
+
+      expect(wranglerContent).toContain("MCP_IDENTITY_AGENT_DID");
+      expect(wranglerContent).toContain("MCP_IDENTITY_PRIVATE_KEY");
+      expect(wranglerContent).toContain("MCP_IDENTITY_PUBLIC_KEY");
+    });
+
+    it("should create .dev.vars.example template", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const examplePath = path.join(tempDir, ".dev.vars.example");
+      expect(fs.existsSync(examplePath)).toBe(true);
+
+      const exampleContent = fs.readFileSync(examplePath, "utf-8");
+      expect(exampleContent).toContain("MCP_IDENTITY_PRIVATE_KEY");
+      expect(exampleContent).toContain("your-private-key-here");
+    });
+  });
+
+  describe("Error handling", () => {
+    it("should handle file system errors gracefully", async () => {
+      // Create a read-only directory to simulate permission errors
+      const readOnlyDir = path.join(tempDir, "readonly");
+      fs.ensureDirSync(readOnlyDir);
+      fs.chmodSync(readOnlyDir, 0o444); // Read-only
+
+      try {
+        await fetchCloudflareMcpiTemplate(readOnlyDir, {
+          packageManager: "npm",
+          projectName: "test-project",
+        });
+        // Should throw or handle error
+      } catch (error) {
+        expect(error).toBeDefined();
+      } finally {
+        // Restore permissions for cleanup
+        fs.chmodSync(readOnlyDir, 0o755);
+      }
+    });
+
+    it("should handle invalid project names", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "123invalid-name!!!",
+        skipIdentity: true,
+      });
+
+      // Should sanitize project name for class names
+      const indexPath = path.join(tempDir, "src", "index.ts");
+      if (fs.existsSync(indexPath)) {
+        const indexContent = fs.readFileSync(indexPath, "utf-8");
+        // Class name should be sanitized
+        expect(indexContent).toMatch(/class\s+\w+MCP/);
+      }
+    });
+  });
+
+  describe("Package manager configuration", () => {
+    it("should use correct package manager in scripts", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "pnpm",
+        projectName: "test-project",
+      });
+
+      const packageJsonPath = path.join(tempDir, "package.json");
+      const packageJson = fs.readJsonSync(packageJsonPath);
+
+      // Scripts should use pnpm commands
+      expect(packageJson.scripts.setup).toContain("node");
+      // Other scripts should use pnpm
+      expect(packageJson.scripts.dev).toBe("wrangler dev");
+    });
+
+    it("should create correct package.json structure", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const packageJsonPath = path.join(tempDir, "package.json");
+      const packageJson = fs.readJsonSync(packageJsonPath);
+
+      expect(packageJson.name).toBe("test-project");
+      expect(packageJson.version).toBe("0.1.0");
+      expect(packageJson.private).toBe(true);
+      expect(packageJson.dependencies).toBeDefined();
+      expect(packageJson.devDependencies).toBeDefined();
+    });
+  });
+
+  describe("Template files content", () => {
+    it("should create greet tool with correct structure", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const greetPath = path.join(tempDir, "src", "tools", "greet.ts");
+      const greetContent = fs.readFileSync(greetPath, "utf-8");
+
+      expect(greetContent).toContain("greetTool");
+      expect(greetContent).toContain('name: "greet"');
+      expect(greetContent).toContain("inputSchema");
+      expect(greetContent).toContain("handler");
+    });
+
+    it("should create test files with correct structure", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "test-project",
+      });
+
+      const testsDir = path.join(tempDir, "tests");
+      expect(fs.existsSync(testsDir)).toBe(true);
+
+      const delegationTestPath = path.join(testsDir, "delegation.test.ts");
+      expect(fs.existsSync(delegationTestPath)).toBe(true);
+
+      const delegationTestContent = fs.readFileSync(
+        delegationTestPath,
+        "utf-8"
+      );
+      expect(delegationTestContent).toContain("Delegation Management");
+      expect(delegationTestContent).toContain("describe");
+    });
+
+    it("should create README with project name", async () => {
+      await fetchCloudflareMcpiTemplate(tempDir, {
+        packageManager: "npm",
+        projectName: "my-awesome-project",
+      });
+
+      const readmePath = path.join(tempDir, "README.md");
+      const readmeContent = fs.readFileSync(readmePath, "utf-8");
+
+      expect(readmeContent).toContain("my-awesome-project");
+      expect(readmeContent).toContain("Quick Start");
+      expect(readmeContent).toContain("Features");
+    });
+  });
+});