@kya-os/create-molti 0.1.0-canary.1

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kya-os/create-molti",
+  "version": "0.1.0-canary.1",
+  "description": "Scaffold a Moltworker project with MCP-I identity",
+  "type": "module",
+  "main": "./dist/helpers/index.js",
+  "types": "./dist/helpers/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/helpers/index.d.ts",
+      "import": "./dist/helpers/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/index.d.ts",
+      "import": "./dist/helpers/index.js"
+    }
+  },
+  "bin": {
+    "create-molti": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "clean": "rm -rf dist .turbo node_modules",
+    "prepublishOnly": "npm run build && node scripts/validate-dependencies.js"
+  },
+  "dependencies": {
+    "@kya-os/contracts": "^1.7.20",
+    "@kya-os/mcp-i-core": "^1.4.18",
+    "@kya-os/mcp-i-cloudflare": "^1.7.70",
+    "base-x": "^5.0.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "validate-npm-package-name": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.14.9",
+    "@types/validate-npm-package-name": "^3.0.0",
+    "@vitest/coverage-v8": "^4.0.5",
+    "typescript": "^5.5.3",
+    "vitest": "^4.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/validate-dependencies.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-publish validation: ensures no workspace:* references
+ * exist in the published package.json.
+ */
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJsonPath = resolve(__dirname, '../package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+let hasErrors = false;
+
+function checkDeps(section, deps) {
+  if (!deps) return;
+  for (const [name, version] of Object.entries(deps)) {
+    if (typeof version === 'string' && version.startsWith('workspace:')) {
+      console.error(`ERROR: ${section}.${name} uses workspace reference: ${version}`);
+      hasErrors = true;
+    }
+  }
+}
+
+checkDeps('dependencies', packageJson.dependencies);
+checkDeps('devDependencies', packageJson.devDependencies);
+checkDeps('peerDependencies', packageJson.peerDependencies);
+
+if (hasErrors) {
+  console.error('\nFailed: workspace references found. Replace with published versions before publishing.');
+  process.exit(1);
+} else {
+  console.log('Validation passed: no workspace references found.');
+}

package/src/cli.ts

@@ -0,0 +1,98 @@
+/**
+ * CLI for @kya-os/create-molti
+ *
+ * Usage: npx @kya-os/create-molti my-agent
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import { generateMoltiProject } from './helpers/generate-molti-project.js';
+import { validateProjectName } from './helpers/validate-name.js';
+
+const program = new Command();
+
+program
+  .name('create-molti')
+  .description('Scaffold a Moltworker project with MCP-I identity')
+  .version('0.1.0')
+  .argument('[directory]', 'Project directory name')
+  .option('--name <name>', 'Project name (defaults to directory name)')
+  .option('--agent-name <name>', 'Human-readable agent name')
+  .option('--description <desc>', 'Agent description')
+  .option('--project-id <id>', 'AgentShield project ID')
+  .option('--api-key <key>', 'AgentShield API key')
+  .option(
+    '--instance-type <type>',
+    'Container instance type (lite, basic, standard-1..4)',
+    'basic'
+  )
+  .option('--skip-identity', 'Skip identity generation')
+  .option('--skip-install', 'Skip dependency installation')
+  .action(async (directory: string | undefined, opts: Record<string, string | boolean | undefined>) => {
+    const projectDir = directory || '.';
+    const projectName = (opts.name as string) || path.basename(path.resolve(projectDir));
+
+    // Validate name
+    const validation = validateProjectName(projectName);
+    if (!validation.valid) {
+      console.error(chalk.red('Invalid project name:'));
+      validation.errors.forEach((err) => console.error(chalk.red(`  - ${err}`)));
+      process.exit(1);
+    }
+
+    console.log(chalk.bold(`\nCreating Molti project: ${chalk.cyan(projectName)}\n`));
+
+    // Generate project files
+    const result = await generateMoltiProject({
+      projectName,
+      agentName: opts['agent-name'] as string | undefined,
+      agentDescription: opts.description as string | undefined,
+      agentShieldProjectId: opts['project-id'] as string | undefined,
+      agentShieldApiKey: opts['api-key'] as string | undefined,
+      instanceType: (opts['instance-type'] as 'lite' | 'basic' | 'standard-1') || 'basic',
+      skipIdentity: !!opts['skip-identity'],
+    });
+
+    // Write files to disk
+    const outputDir = path.resolve(projectDir);
+    await fs.ensureDir(outputDir);
+
+    for (const file of result.files) {
+      const filePath = path.join(outputDir, file.path);
+      await fs.ensureDir(path.dirname(filePath));
+      await fs.writeFile(filePath, file.content, 'utf-8');
+    }
+
+    // Make startup script executable
+    const startScript = path.join(outputDir, 'start-moltbot.sh');
+    if (await fs.pathExists(startScript)) {
+      await fs.chmod(startScript, 0o755);
+    }
+
+    // Print success
+    console.log(chalk.green('Project created successfully!\n'));
+    console.log(chalk.bold('Identity:'));
+    console.log(`  DID: ${chalk.cyan(result.identity.did)}`);
+    console.log(`  Public Key: ${result.identity.publicKey.slice(0, 20)}...`);
+    console.log();
+    console.log(chalk.bold('Secrets (add to .dev.vars or wrangler secret):'));
+    Object.keys(result.secrets).forEach((key) => {
+      console.log(`  ${chalk.yellow(key)}`);
+    });
+    console.log();
+    console.log(chalk.bold('Next steps:'));
+    console.log(`  cd ${projectDir}`);
+    console.log('  npm install');
+    console.log('  cp .dev.vars.example .dev.vars');
+    console.log('  # Edit .dev.vars with your keys');
+    console.log('  npm run dev');
+    console.log();
+  });
+
+export { program };
+
+export async function run(): Promise<void> {
+  await program.parseAsync(process.argv);
+}

package/src/helpers/generate-identity.ts

@@ -0,0 +1,90 @@
+/**
+ * Identity Generation for Molti Projects
+ *
+ * Reuses the same Ed25519 keypair generation and DID:key creation
+ * as create-mcpi-app, ensuring cryptographic compatibility across
+ * the KYA-OS ecosystem.
+ */
+
+import { webcrypto } from 'crypto';
+import baseX from 'base-x';
+import type { MoltiIdentity } from '../types.js';
+
+/**
+ * Web Crypto API key pair type
+ */
+interface WebCryptoKeyPair {
+  privateKey: webcrypto.CryptoKey;
+  publicKey: webcrypto.CryptoKey;
+}
+
+/**
+ * Generate a new Ed25519 identity with DID:key
+ *
+ * Uses the same algorithm as create-mcpi-app's generateIdentity()
+ * and mcp-i-core's WebCryptoProvider to ensure compatibility.
+ *
+ * @returns MoltiIdentity with DID, public key, and private key
+ */
+export async function generateIdentity(): Promise<MoltiIdentity> {
+  const keyPair = (await webcrypto.subtle.generateKey(
+    { name: 'Ed25519' },
+    true,
+    ['sign', 'verify']
+  )) as WebCryptoKeyPair;
+
+  const privateKeyPKCS8 = await webcrypto.subtle.exportKey('pkcs8', keyPair.privateKey);
+  const publicKeySPKI = await webcrypto.subtle.exportKey('spki', keyPair.publicKey);
+
+  const privateKeyRaw = extractEd25519PrivateKey(new Uint8Array(privateKeyPKCS8 as ArrayBuffer));
+  const publicKeyRaw = extractEd25519PublicKey(
+    Buffer.from(publicKeySPKI as ArrayBuffer).toString('base64')
+  );
+
+  const privateKey = Buffer.from(privateKeyRaw).toString('base64');
+  const publicKey = Buffer.from(publicKeyRaw).toString('base64');
+  const did = generateDIDFromPublicKeyBytes(publicKeyRaw);
+
+  return { did, publicKey, privateKey };
+}
+
+/**
+ * Generate a DID:key from raw Ed25519 public key bytes
+ *
+ * Format: did:key:z<multibase-base58btc(<multicodec-ed25519-pub><publicKey>)>
+ */
+function generateDIDFromPublicKeyBytes(publicKeyBytes: Uint8Array): string {
+  const multicodecPrefix = new Uint8Array([0xed, 0x01]);
+
+  const multicodecKey = new Uint8Array(multicodecPrefix.length + publicKeyBytes.length);
+  multicodecKey.set(multicodecPrefix);
+  multicodecKey.set(publicKeyBytes, multicodecPrefix.length);
+
+  const base58 = baseX('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');
+  const base58Encoded = base58.encode(multicodecKey);
+
+  return `did:key:z${base58Encoded}`;
+}
+
+/**
+ * Extract raw 32-byte Ed25519 private key from PKCS#8 format
+ */
+function extractEd25519PrivateKey(pkcs8: Uint8Array): Uint8Array {
+  return pkcs8.slice(16, 48);
+}
+
+/**
+ * Extract raw 32-byte Ed25519 public key from SPKI format
+ */
+function extractEd25519PublicKey(publicKey: string): Uint8Array {
+  const spkiBytes = Buffer.from(publicKey, 'base64');
+  return spkiBytes.slice(-32);
+}
+
+/**
+ * Validate that a string is a valid DID:key identifier
+ */
+export function isValidDIDKey(did: string): boolean {
+  const didKeyRegex = /^did:key:z[1-9A-HJ-NP-Za-km-z]{47,}$/;
+  return didKeyRegex.test(did);
+}

package/src/helpers/generate-molti-project.ts

@@ -0,0 +1,239 @@
+/**
+ * Molti Project Generator
+ *
+ * Generates all files for a Moltworker project with MCP-I identity.
+ * Returns files in-memory for programmatic use (e.g., GitHub API commits).
+ */
+
+import type {
+  MoltiProjectOptions,
+  MoltiGenerateResult,
+  MoltiIdentity,
+  GeneratedFile,
+} from '../types.js';
+import { generateIdentity } from './generate-identity.js';
+import { getPackageVersions } from './get-package-versions.js';
+import { generateDockerfile } from '../templates/dockerfile.js';
+import { generateWranglerJsonc } from '../templates/wrangler.js';
+import { generateWorkerIndex } from '../templates/worker-index.js';
+import { generateTypesModule } from '../templates/types-module.js';
+import { generateGatewayModule } from '../templates/gateway.js';
+import { generateAuthModule } from '../templates/auth-module.js';
+import { generateIdentityModule } from '../templates/identity-module.js';
+import { generateHealthModule } from '../templates/health-module.js';
+import { generateStartupScript } from '../templates/startup-script.js';
+import { generateMoltbotConfig } from '../templates/moltbot-config.js';
+import { generatePackageJson } from '../templates/package-json.js';
+import { generateTsconfig } from '../templates/tsconfig-template.js';
+import { generateDeployWorkflow } from '../templates/github-workflow.js';
+import { generateIdentityJson } from '../templates/identity-json.js';
+import { generateReadme } from '../templates/readme.js';
+
+/**
+ * Generate a complete Moltworker project with MCP-I identity
+ *
+ * @param options - Project configuration options
+ * @returns Generated files, identity, and secrets
+ *
+ * @example
+ * ```typescript
+ * const result = await generateMoltiProject({
+ *   projectName: "my-agent",
+ *   agentShieldProjectId: "proj-abc123",
+ * });
+ *
+ * // Commit files to GitHub
+ * for (const file of result.files) {
+ *   await github.commitFile(file.path, file.content);
+ * }
+ *
+ * // Store secrets
+ * await github.addSecret("MCP_IDENTITY_PRIVATE_KEY", result.secrets.MCP_IDENTITY_PRIVATE_KEY);
+ * ```
+ */
+export async function generateMoltiProject(
+  options: MoltiProjectOptions
+): Promise<MoltiGenerateResult> {
+  const {
+    projectName,
+    agentName,
+    agentDescription,
+    agentShieldProjectId,
+    agentShieldApiKey,
+    instanceType = 'basic',
+    skipIdentity = false,
+  } = options;
+
+  const versions = await getPackageVersions();
+
+  // Generate or mock identity
+  let identity: MoltiIdentity;
+  if (skipIdentity) {
+    identity = {
+      did: 'did:key:zTestMockIdentity',
+      publicKey: 'mock-public-key',
+      privateKey: 'mock-private-key',
+    };
+  } else {
+    identity = await generateIdentity();
+  }
+
+  const files: GeneratedFile[] = [];
+
+  // Root files
+  files.push({
+    path: 'Dockerfile',
+    content: generateDockerfile(),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'start-moltbot.sh',
+    content: generateStartupScript(),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'moltbot.json.template',
+    content: generateMoltbotConfig(),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'wrangler.jsonc',
+    content: generateWranglerJsonc({
+      projectName,
+      agentDid: identity.did,
+      publicKey: identity.publicKey,
+      agentShieldProjectId,
+      instanceType,
+    }),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'package.json',
+    content: generatePackageJson({ projectName, versions }),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'tsconfig.json',
+    content: generateTsconfig(),
+    encoding: 'utf-8',
+  });
+
+  // Source files
+  files.push({
+    path: 'src/index.ts',
+    content: generateWorkerIndex(projectName),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'src/types.ts',
+    content: generateTypesModule(),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'src/gateway.ts',
+    content: generateGatewayModule(),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'src/auth.ts',
+    content: generateAuthModule(),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'src/identity.ts',
+    content: generateIdentityModule(),
+    encoding: 'utf-8',
+  });
+
+  files.push({
+    path: 'src/routes/public.ts',
+    content: generateHealthModule(projectName),
+    encoding: 'utf-8',
+  });
+
+  // GitHub Actions
+  files.push({
+    path: '.github/workflows/deploy.yml',
+    content: generateDeployWorkflow(),
+    encoding: 'utf-8',
+  });
+
+  // Identity file (public, safe to commit)
+  files.push({
+    path: '.mcpi/identity.json',
+    content: generateIdentityJson({
+      did: identity.did,
+      publicKey: identity.publicKey,
+      agentName,
+      agentDescription,
+    }),
+    encoding: 'utf-8',
+  });
+
+  // .gitignore
+  files.push({
+    path: '.gitignore',
+    content: `node_modules/
+dist/
+.wrangler/
+.dev.vars
+*.log
+.DS_Store
+`,
+    encoding: 'utf-8',
+  });
+
+  // .dev.vars.example
+  files.push({
+    path: '.dev.vars.example',
+    content: `# Copy this to .dev.vars for local development
+# DO NOT COMMIT .dev.vars — it contains secrets
+
+# Agent Identity
+MCP_IDENTITY_PRIVATE_KEY="your-private-key-here"
+
+# AI Provider (at least one required)
+ANTHROPIC_API_KEY="your-anthropic-key"
+# OPENAI_API_KEY="your-openai-key"
+
+# AgentShield Integration
+AGENTSHIELD_API_KEY="sk_your_api_key_here"
+
+# Development mode (skips CF Access auth)
+DEV_MODE="true"
+`,
+    encoding: 'utf-8',
+  });
+
+  // README
+  files.push({
+    path: 'README.md',
+    content: generateReadme({
+      projectName,
+      agentName,
+      agentDescription,
+      agentShieldProjectId,
+    }),
+    encoding: 'utf-8',
+  });
+
+  // Build secrets
+  const secrets: Record<string, string> = {
+    MCP_IDENTITY_PRIVATE_KEY: identity.privateKey,
+  };
+
+  if (agentShieldApiKey) {
+    secrets.AGENTSHIELD_API_KEY = agentShieldApiKey;
+  }
+
+  return { files, identity, secrets };
+}

package/src/helpers/get-package-versions.ts

@@ -0,0 +1,78 @@
+/**
+ * Package Version Helper
+ *
+ * Reads dependency versions from this package's own package.json
+ * to ensure scaffolded projects use consistent, tested versions.
+ *
+ * Single source of truth for @kya-os/* package versions in Molti templates.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export interface MoltiPackageVersions {
+  '@kya-os/mcp-i-core': string;
+  '@kya-os/mcp-i-cloudflare': string;
+  '@kya-os/contracts': string;
+}
+
+let cachedVersions: MoltiPackageVersions | null = null;
+
+/**
+ * Normalize a version string for scaffolded templates
+ *
+ * - Stable versions: keep caret for minor updates
+ * - Canary versions: pin exact (no caret)
+ */
+function normalizeVersion(version: string): string {
+  const cleanVersion = version.replace(/^[\^~]/, '');
+
+  if (cleanVersion.includes('canary')) {
+    return cleanVersion;
+  }
+
+  return `^${cleanVersion}`;
+}
+
+/**
+ * Get package versions from this package's package.json
+ */
+export async function getPackageVersions(): Promise<MoltiPackageVersions> {
+  if (cachedVersions) {
+    return cachedVersions;
+  }
+
+  const packageJsonPath = path.resolve(__dirname, '../../package.json');
+
+  try {
+    const packageJson = await fs.readJson(packageJsonPath);
+    const deps = packageJson.dependencies || {};
+
+    cachedVersions = {
+      '@kya-os/mcp-i-core': normalizeVersion(deps['@kya-os/mcp-i-core'] || '^1.4.18'),
+      '@kya-os/mcp-i-cloudflare': normalizeVersion(
+        deps['@kya-os/mcp-i-cloudflare'] || '^1.7.70'
+      ),
+      '@kya-os/contracts': normalizeVersion(deps['@kya-os/contracts'] || '^1.7.20'),
+    };
+
+    return cachedVersions;
+  } catch {
+    return {
+      '@kya-os/mcp-i-core': '^1.4.18',
+      '@kya-os/mcp-i-cloudflare': '^1.7.70',
+      '@kya-os/contracts': '^1.7.20',
+    };
+  }
+}
+
+/**
+ * Clear cached versions (for testing)
+ */
+export function clearVersionCache(): void {
+  cachedVersions = null;
+}

package/src/helpers/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Helper Exports for @kya-os/create-molti
+ *
+ * This module exports helpers for programmatic use.
+ * The primary export is generateMoltiProject for one-click deployment.
+ */
+
+// Main generator
+export { generateMoltiProject } from './generate-molti-project.js';
+
+// Identity generation
+export { generateIdentity, isValidDIDKey } from './generate-identity.js';
+
+// Types
+export type {
+  MoltiProjectOptions,
+  MoltiGenerateResult,
+  MoltiIdentity,
+  GeneratedFile,
+} from '../types.js';
+
+// Utilities
+export { validateProjectName, type ValidationResult } from './validate-name.js';
+export { getPackageVersions, clearVersionCache, type MoltiPackageVersions } from './get-package-versions.js';

package/src/helpers/validate-name.ts

@@ -0,0 +1,42 @@
+/**
+ * Project Name Validation
+ *
+ * Validates project names for npm compatibility and Cloudflare Workers naming.
+ */
+
+import validate from 'validate-npm-package-name';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a project name for use as a Molti project
+ *
+ * Checks npm naming rules and Cloudflare Workers compatibility.
+ */
+export function validateProjectName(name: string): ValidationResult {
+  const errors: string[] = [];
+
+  if (!name || name.trim().length === 0) {
+    return { valid: false, errors: ['Project name is required'] };
+  }
+
+  const trimmed = name.trim();
+
+  if (trimmed.length > 100) {
+    errors.push('Project name must be 100 characters or less');
+  }
+
+  const npmResult = validate(trimmed);
+  if (!npmResult.validForNewPackages) {
+    const npmErrors = [...(npmResult.errors || []), ...(npmResult.warnings || [])];
+    errors.push(...npmErrors);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+/**
+ * @kya-os/create-molti
+ *
+ * Scaffold a Moltworker project with MCP-I identity.
+ *
+ * Usage:
+ *   npx @kya-os/create-molti my-agent
+ *   npx @kya-os/create-molti my-agent --instance-type standard-1
+ */
+
+import { run } from './cli.js';
+
+run().catch((error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});