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

package/src/helpers/__tests__/config-builder.spec.ts

@@ -0,0 +1,231 @@
+/**
+ * Tests for Configuration Builder Utilities
+ *
+ * Validates that config builders generate correct configurations
+ * and handle remote fetching correctly.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  buildBaseConfig,
+  buildConfigWithRemote,
+  type ConfigBuilderOptions
+} from '../config-builder.js';
+import type { MCPIConfig } from '@kya-os/contracts/config';
+import type { RemoteConfigCache } from '@kya-os/mcp-i-core';
+
+describe('buildBaseConfig', () => {
+  it('should generate valid base config with defaults', () => {
+    const env = {};
+    const config = buildBaseConfig(env);
+
+    expect(config.environment).toBe('development');
+    expect(config.identity?.enabled).toBe(true);
+    expect(config.proofing?.enabled).toBe(true);
+    expect(config.delegation?.enabled).toBe(true);
+    expect(config.audit?.enabled).toBe(true);
+  });
+
+  it('should use environment variables when provided', () => {
+    const env = {
+      MCPI_ENV: 'production',
+      AGENTSHIELD_API_URL: 'https://custom.example.com',
+      AGENTSHIELD_API_KEY: 'custom-key'
+    };
+
+    const config = buildBaseConfig(env);
+
+    expect(config.environment).toBe('production');
+    expect(config.identity?.environment).toBe('production');
+    expect(config.proofing?.batchQueue?.destinations?.[0].apiUrl).toBe('https://custom.example.com');
+    expect(config.delegation?.verifier?.apiUrl).toBe('https://custom.example.com');
+  });
+
+  it('should include all required config sections', () => {
+    const env = {};
+    const config = buildBaseConfig(env);
+
+    expect(config).toHaveProperty('environment');
+    expect(config).toHaveProperty('identity');
+    expect(config).toHaveProperty('proofing');
+    expect(config).toHaveProperty('delegation');
+    expect(config).toHaveProperty('audit');
+    expect(config).toHaveProperty('session');
+  });
+
+  it('should set debug mode based on environment', () => {
+    const devConfig = buildBaseConfig({ MCPI_ENV: 'development' });
+    const prodConfig = buildBaseConfig({ MCPI_ENV: 'production' });
+
+    expect(devConfig.proofing?.batchQueue?.debug).toBe(true);
+    expect(prodConfig.proofing?.batchQueue?.debug).toBe(false);
+  });
+});
+
+describe('buildConfigWithRemote', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+  let mockCache: RemoteConfigCache;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    mockCache = {
+      get: vi.fn(),
+      set: vi.fn()
+    };
+  });
+
+  it('should use remote config when API key is provided', async () => {
+    const remoteConfig: MCPIConfig = {
+      environment: 'production',
+      identity: { enabled: true, environment: 'production' }
+    };
+
+    vi.mocked(mockCache.get).mockResolvedValue(null);
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ success: true, data: remoteConfig })
+    } as Response);
+
+    const options: ConfigBuilderOptions = {
+      env: {
+        AGENTSHIELD_API_KEY: 'test-key',
+        AGENTSHIELD_API_URL: 'https://kya.vouched.id'
+      },
+      fetchProvider: mockFetch,
+      cache: mockCache,
+      agentDid: 'did:key:test'
+    };
+
+    const config = await buildConfigWithRemote(options);
+
+    expect(config).toEqual(remoteConfig);
+    expect(mockFetch).toHaveBeenCalled();
+  });
+
+  it('should fallback to local config when remote fetch fails', async () => {
+    vi.mocked(mockCache.get).mockResolvedValue(null);
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 500
+    } as Response);
+
+    const options: ConfigBuilderOptions = {
+      env: {
+        AGENTSHIELD_API_KEY: 'test-key',
+        MCPI_ENV: 'production'
+      },
+      fetchProvider: mockFetch,
+      cache: mockCache
+    };
+
+    const config = await buildConfigWithRemote(options);
+
+    expect(config.environment).toBe('production');
+    expect(config).toHaveProperty('identity');
+    expect(config).toHaveProperty('proofing');
+  });
+
+  it('should fallback to local config when API key not provided', async () => {
+    const options: ConfigBuilderOptions = {
+      env: {
+        MCPI_ENV: 'development'
+      },
+      fetchProvider: mockFetch,
+      cache: mockCache
+    };
+
+    const config = await buildConfigWithRemote(options);
+
+    expect(config.environment).toBe('development');
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('should fallback to local config when fetch provider not provided', async () => {
+    const options: ConfigBuilderOptions = {
+      env: {
+        AGENTSHIELD_API_KEY: 'test-key',
+        MCPI_ENV: 'development'
+      },
+      cache: mockCache
+      // fetchProvider not provided
+    };
+
+    const config = await buildConfigWithRemote(options);
+
+    expect(config.environment).toBe('development');
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('should use projectId when provided', async () => {
+    const remoteConfig: MCPIConfig = {
+      environment: 'production'
+    };
+
+    vi.mocked(mockCache.get).mockResolvedValue(null);
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ success: true, data: remoteConfig })
+    } as Response);
+
+    const options: ConfigBuilderOptions = {
+      env: {
+        AGENTSHIELD_API_KEY: 'test-key',
+        AGENTSHIELD_PROJECT_ID: 'test-project'
+      },
+      fetchProvider: mockFetch,
+      cache: mockCache
+    };
+
+    const config = await buildConfigWithRemote(options);
+
+    expect(config).toEqual(remoteConfig);
+    // Verify fetch was called with projectId endpoint
+    expect(mockFetch).toHaveBeenCalled();
+  });
+
+  it('should handle cache hit from remote config', async () => {
+    const cachedConfig: MCPIConfig = {
+      environment: 'production',
+      identity: { enabled: true, environment: 'production' }
+    };
+
+    vi.mocked(mockCache.get).mockResolvedValue(
+      JSON.stringify({
+        config: cachedConfig,
+        expiresAt: Date.now() + 60000
+      })
+    );
+
+    const options: ConfigBuilderOptions = {
+      env: {
+        AGENTSHIELD_API_KEY: 'test-key',
+        AGENTSHIELD_PROJECT_ID: 'test-project'
+      },
+      fetchProvider: mockFetch,
+      cache: mockCache
+    };
+
+    const config = await buildConfigWithRemote(options);
+
+    expect(config).toEqual(cachedConfig);
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});
+
+describe('Environment variable parsing', () => {
+  it('should handle different environment variable names', () => {
+    const config1 = buildBaseConfig({ MCPI_ENV: 'production' });
+    const config2 = buildBaseConfig({ ENVIRONMENT: 'production' });
+
+    expect(config1.environment).toBe('production');
+    expect(config2.environment).toBe('production');
+  });
+
+  it('should default to development when no env var provided', () => {
+    const config = buildBaseConfig({});
+
+    expect(config.environment).toBe('development');
+    expect(config.identity?.environment).toBe('development');
+  });
+});
+

package/src/helpers/apply-identity-preset.ts

@@ -0,0 +1,209 @@
+import fs from "fs-extra";
+import path from "path";
+import chalk from "chalk";
+
+interface IdentityPresetOptions {
+  projectPath: string;
+  projectName: string;
+  transports: string[];
+  noIdentity?: boolean;
+}
+
+/**
+ * Apply identity preset to an XMCP project
+ * This enhances the upstream XMCP template with identity features
+ * If noIdentity is true, leaves the XMCP project unchanged
+ */
+export async function applyIdentityPreset(
+  options: IdentityPresetOptions
+): Promise<void> {
+  const { projectPath, projectName, transports, noIdentity = false } = options;
+
+  if (noIdentity) {
+    console.log(
+      chalk.blue("📦 Keeping plain XMCP project (--no-identity flag)")
+    );
+    return;
+  }
+
+  console.log(chalk.blue("🔐 Applying identity preset..."));
+
+  const srcDir = path.join(projectPath, "src");
+  const toolsDir = path.join(srcDir, "tools");
+
+  // Skip middleware creation for now since xmcp has issues with middleware imports
+  // The identity features will be integrated differently in the future
+  // TODO: Once xmcp supports middleware properly, we can re-enable this
+  /*
+  const middlewarePath = path.join(srcDir, "middleware.ts");
+  if (await fs.pathExists(middlewarePath)) {
+    // Enhance existing middleware.ts with identity features
+    console.log(
+      chalk.gray(
+        "📝 Enhancing existing middleware.ts with identity features..."
+      )
+    );
+    // ... middleware enhancement code ...
+  } else {
+    // Create middleware.ts with identity features
+    // ... middleware creation code ...
+  }
+  */
+
+  // Enhance existing tools or create identity-aware tools
+  if (await fs.pathExists(toolsDir)) {
+    console.log(
+      chalk.gray("🔧 Enhancing existing tools with identity features...")
+    );
+
+    // Check for existing tools and enhance them
+    const toolFiles = await fs.readdir(toolsDir);
+    const tsFiles = toolFiles.filter(
+      (f) => f.endsWith(".ts") && f !== "index.ts"
+    );
+
+    if (tsFiles.length > 0) {
+      // Enhance existing tools
+      for (const toolFile of tsFiles) {
+        const toolPath = path.join(toolsDir, toolFile);
+        let toolContent = await fs.readFile(toolPath, "utf-8");
+
+        // Add identity comment to existing tools
+        const identityComment = `// Enhanced with XMCP-I identity features\n`;
+        toolContent = identityComment + toolContent;
+
+        await fs.writeFile(toolPath, toolContent);
+      }
+    } else {
+      // Create identity-aware hello tool if no tools exist
+      await createIdentityHelloTool(toolsDir);
+    }
+  } else {
+    // Create tools directory and identity-aware tools
+    await fs.ensureDir(toolsDir);
+    await createIdentityHelloTool(toolsDir);
+  }
+
+  // Update package.json with identity dependencies and scripts
+  await updatePackageJsonForIdentity(projectPath, projectName, transports);
+
+  // Create .mcpi directory for identity files
+  const mcpiDir = path.join(projectPath, ".mcpi");
+  await fs.ensureDir(mcpiDir);
+
+  // Create .gitignore with identity-specific entries
+  await updateGitignore(projectPath);
+
+  console.log(chalk.green("✅ Identity preset applied"));
+}
+
+async function createIdentityHelloTool(toolsDir: string): Promise<void> {
+  // Create tools/hello.ts with identity features
+  const helloToolContent = `// Enhanced with XMCP-I identity features
+import { z } from "zod";
+
+export const hello = {
+  name: "hello",
+  description: "Say hello with identity verification",
+  inputSchema: z.object({
+    name: z.string().describe("Name to greet"),
+  }),
+  handler: async ({ name }: { name: string }) => {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: \`Hello, \${name}! This message is cryptographically signed.\`,
+        },
+      ],
+    };
+  },
+};
+`;
+
+  await fs.writeFile(path.join(toolsDir, "hello.ts"), helloToolContent);
+
+  // Create or update tools/index.ts
+  const indexPath = path.join(toolsDir, "index.ts");
+  let indexContent = "";
+
+  if (await fs.pathExists(indexPath)) {
+    indexContent = await fs.readFile(indexPath, "utf-8");
+  }
+
+  // Add hello export if not already present (no .js extension for TypeScript)
+  if (!indexContent.includes("hello")) {
+    indexContent += `\nexport * from "./hello";`;
+    await fs.writeFile(indexPath, indexContent);
+  }
+}
+
+async function updatePackageJsonForIdentity(
+  projectPath: string,
+  projectName: string,
+  transports: string[]
+): Promise<void> {
+  const packageJsonPath = path.join(projectPath, "package.json");
+  const packageJson = await fs.readJson(packageJsonPath);
+
+  // Add identity dependencies
+  // Use workspace dependencies for local testing, published versions for production
+  const useWorkspace = process.env.MCPI_USE_WORKSPACE === "true";
+
+  // Add @kya-os dependencies - packages are now published!
+  if (useWorkspace) {
+    packageJson.dependencies = {
+      ...packageJson.dependencies,
+      "@kya-os/mcp-i": "workspace:*",
+      "@kya-os/cli": "workspace:*",
+    };
+  } else {
+    // Add published packages
+    packageJson.dependencies = {
+      ...packageJson.dependencies,
+      "@kya-os/mcp-i": "^1.2.7",
+      "@kya-os/cli": "^1.2.7",
+    };
+  }
+
+  // Add exactly 8 scripts as required by spec
+  // Now using actual mcpi commands since @kya-os/cli is published
+  packageJson.scripts = {
+    dev: "xmcp dev",
+    build: "xmcp build",
+    start: "xmcp start",
+    init: "mcpi init",
+    register: "mcpi register",
+    "keys:rotate": "mcpi rotate",
+    "identity:clean": "rm -rf .mcpi",
+    status: "mcpi status",
+  };
+
+  await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+}
+
+async function updateGitignore(projectPath: string): Promise<void> {
+  const gitignorePath = path.join(projectPath, ".gitignore");
+  let gitignoreContent = "";
+
+  if (await fs.pathExists(gitignorePath)) {
+    gitignoreContent = await fs.readFile(gitignorePath, "utf-8");
+  }
+
+  // Add identity-specific gitignore entries if not already present
+  const identityEntries = [
+    "# MCP-I Identity",
+    ".mcpi/",
+    ".env.local",
+    "generated-identity.json",
+    ".mcp-identity.json",
+  ];
+
+  for (const entry of identityEntries) {
+    if (!gitignoreContent.includes(entry)) {
+      gitignoreContent += `\n${entry}`;
+    }
+  }
+
+  await fs.writeFile(gitignorePath, gitignoreContent);
+}

package/src/helpers/config-builder.ts

@@ -0,0 +1,165 @@
+/**
+ * Configuration Builder Utilities
+ *
+ * Shared utilities for building MCP-I configuration that works across
+ * all platforms (Node.js, Cloudflare Workers, etc.).
+ *
+ * @module @kya-os/create-mcpi-app/config-builder
+ */
+
+import type {
+  MCPIConfig,
+  RuntimeIdentityConfig,
+  ProofingConfig,
+  DelegationConfig,
+  ProofBatchQueueConfig,
+  ProofDestination,
+  DelegationVerifierConfig,
+  AuthorizationConfig
+} from '@kya-os/contracts/config';
+
+import {
+  fetchRemoteConfig,
+  type RemoteConfigOptions,
+  type RemoteConfigCache
+} from '@kya-os/mcp-i-core';
+
+/**
+ * Options for building configuration with remote fetching support
+ */
+export interface ConfigBuilderOptions {
+  /**
+   * Environment variables object
+   * Works with process.env (Node.js) or Cloudflare env bindings
+   */
+  env: Record<string, any>;
+
+  /**
+   * Fetch provider function
+   * Platform-agnostic fetch implementation
+   * Required for remote config fetching
+   */
+  fetchProvider?: (url: string, options: RequestInit) => Promise<Response>;
+
+  /**
+   * Cache implementation for remote config
+   * Optional, but recommended for performance
+   */
+  cache?: RemoteConfigCache;
+
+  /**
+   * Agent DID for agent-scoped config fetching
+   * Used when projectId is not available
+   */
+  agentDid?: string;
+}
+
+/**
+ * Build base MCPIConfig that works across all platforms
+ *
+ * Creates a platform-agnostic configuration object with sensible defaults
+ * for identity, proofing, delegation, audit, and session management.
+ *
+ * @param env - Environment variables object (works with process.env or Cloudflare env)
+ * @returns Complete MCPIConfig object
+ */
+export function buildBaseConfig(env: Record<string, any>): MCPIConfig {
+  const environment = (env.MCPI_ENV || env.ENVIRONMENT || 'development') as 'development' | 'production';
+  const isDevelopment = environment === 'development';
+
+  const baseConfig: MCPIConfig = {
+    environment,
+
+    identity: {
+      enabled: true,
+      environment,
+      devIdentityPath: '.mcpi/identity.json'
+    } as RuntimeIdentityConfig,
+
+    proofing: {
+      enabled: true,
+      batchQueue: {
+        destinations: [
+          {
+            type: 'agentshield' as const,
+            apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+            apiKey: env.AGENTSHIELD_API_KEY || ''
+          }
+        ],
+        maxBatchSize: 10,
+        flushIntervalMs: 5000,
+        maxRetries: 3,
+        debug: isDevelopment
+      }
+    } as ProofingConfig,
+
+    delegation: {
+      enabled: true,
+      enforceDelegations: true,
+      verifier: {
+        type: 'agentshield' as const,
+        apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+        apiKey: env.AGENTSHIELD_API_KEY || '',
+        cacheTtl: 60000, // 1 minute cache
+        debug: isDevelopment
+      } as DelegationVerifierConfig,
+      authorization: {
+        authorizationUrl: env.AUTHORIZATION_URL || `${env.AGENTSHIELD_API_URL || 'https://kya.vouched.id'}/authorize`,
+        resumeTokenTtl: 600000, // 10 minutes
+        minReputationScore: 76
+      } as AuthorizationConfig
+    } as DelegationConfig,
+
+    audit: {
+      enabled: true,
+      includeProofHashes: false,
+      includePayloads: false
+    },
+
+    session: {
+      timestampSkewSeconds: 120,
+      ttlMinutes: 30
+    }
+  };
+
+  return baseConfig;
+}
+
+/**
+ * Build config with remote fetching support
+ *
+ * Attempts to fetch configuration from remote API (AgentShield dashboard)
+ * first, then falls back to local environment-based configuration if remote
+ * fetch fails or is not configured.
+ *
+ * @param options - Configuration builder options
+ * @returns Promise resolving to MCPIConfig
+ */
+export async function buildConfigWithRemote(
+  options: ConfigBuilderOptions
+): Promise<MCPIConfig> {
+  const { env, fetchProvider, cache, agentDid } = options;
+
+  // Try remote fetch first if API key and fetch provider are configured
+  if (env.AGENTSHIELD_API_KEY && fetchProvider) {
+    const remote = await fetchRemoteConfig(
+      {
+        apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+        apiKey: env.AGENTSHIELD_API_KEY,
+        projectId: env.AGENTSHIELD_PROJECT_ID,
+        agentDid,
+        cacheTtl: 300000, // 5 minutes
+        fetchProvider
+      },
+      cache
+    );
+
+    if (remote) {
+      return remote;
+    }
+  }
+
+  // Fallback to local env-based config
+  return buildBaseConfig(env);
+}
+

package/src/helpers/copy-template.ts

@@ -0,0 +1,11 @@
+import fs from "fs-extra";
+import path from "path";
+
+export function copyTemplate(templateDir: string, projectPath: string): void {
+  fs.copySync(templateDir, projectPath, {
+    filter: (src: string) => {
+      const basename = path.basename(src);
+      return !basename.startsWith(".");
+    },
+  });
+}