@claude-flow/deployment 3.0.0-alpha.1

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * @claude-flow/deployment
+ * Release management, CI/CD, and versioning module
+ */
+
+// Export types
+export type {
+  VersionBumpType,
+  ReleaseChannel,
+  ReleaseOptions,
+  ReleaseResult,
+  PublishOptions,
+  PublishResult,
+  ValidationOptions,
+  ValidationResult,
+  PackageInfo,
+  GitCommit,
+  ChangelogEntry
+} from './types.js';
+
+// Export classes
+export { ReleaseManager } from './release-manager.js';
+export { Publisher } from './publisher.js';
+export { Validator } from './validator.js';
+
+// Export convenience functions
+export {
+  prepareRelease
+} from './release-manager.js';
+
+export {
+  publishToNpm,
+  checkVersionExists,
+  getLatestVersion
+} from './publisher.js';
+
+export {
+  validate
+} from './validator.js';
+
+// Legacy exports for backward compatibility
+export interface ReleaseConfig {
+  version: string;
+  channel: 'alpha' | 'beta' | 'stable';
+  changelog: boolean;
+  dryRun: boolean;
+}
+
+export interface DeploymentTarget {
+  name: string;
+  type: 'npm' | 'docker' | 'github-release';
+  config: Record<string, unknown>;
+}
+
+/**
+ * Legacy prepare release function
+ * @deprecated Use prepareRelease from release-manager instead
+ */
+export async function prepare(config: ReleaseConfig): Promise<void> {
+  const { ReleaseManager } = await import('./release-manager.js');
+  const manager = new ReleaseManager();
+
+  await manager.prepareRelease({
+    version: config.version,
+    channel: config.channel as any,
+    generateChangelog: config.changelog,
+    dryRun: config.dryRun
+  });
+}
+
+/**
+ * Legacy deploy function
+ * @deprecated Use publishToNpm from publisher instead
+ */
+export async function deploy(target: DeploymentTarget): Promise<void> {
+  if (target.type === 'npm') {
+    const { Publisher } = await import('./publisher.js');
+    const publisher = new Publisher();
+
+    await publisher.publishToNpm({
+      tag: (target.config.tag as string) || 'latest',
+      dryRun: (target.config.dryRun as boolean) || false
+    });
+  } else {
+    console.log(`Deploying to ${target.name} (${target.type})`);
+    throw new Error(`Deployment type ${target.type} not yet implemented`);
+  }
+}

package/src/publisher.ts

@@ -0,0 +1,273 @@
+/**
+ * NPM Publisher
+ * Handles npm package publishing with tag support
+ */
+
+import { execSync, execFileSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import type { PublishOptions, PublishResult, PackageInfo } from './types.js';
+
+export class Publisher {
+  private cwd: string;
+
+  constructor(cwd: string = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Publish package to npm
+   */
+  async publishToNpm(options: PublishOptions = {}): Promise<PublishResult> {
+    const {
+      tag = 'latest',
+      access,
+      dryRun = false,
+      registry,
+      otp,
+      skipBuild = false,
+      buildCommand = 'npm run build'
+    } = options;
+
+    const result: PublishResult = {
+      packageName: '',
+      version: '',
+      tag,
+      success: false
+    };
+
+    try {
+      // Read package.json
+      const pkgPath = join(this.cwd, 'package.json');
+      if (!existsSync(pkgPath)) {
+        throw new Error('package.json not found');
+      }
+
+      const pkg: PackageInfo = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+      if (pkg.private) {
+        throw new Error('Cannot publish private package');
+      }
+
+      result.packageName = pkg.name;
+      result.version = pkg.version;
+
+      // Run build if not skipped
+      if (!skipBuild) {
+        console.log('Building package...');
+        this.execCommand(buildCommand);
+      }
+
+      // Construct npm publish command arguments (without 'npm' prefix for execNpmCommand)
+      const publishArgs: string[] = ['publish'];
+
+      if (tag) {
+        publishArgs.push('--tag', tag);
+      }
+
+      if (access) {
+        publishArgs.push('--access', access);
+      }
+
+      if (registry) {
+        publishArgs.push('--registry', registry);
+      }
+
+      if (otp) {
+        publishArgs.push('--otp', otp);
+      }
+
+      if (dryRun) {
+        publishArgs.push('--dry-run');
+      }
+
+      // Execute publish
+      console.log(`Publishing ${result.packageName}@${result.version} with tag '${tag}'...`);
+
+      if (dryRun) {
+        console.log('Dry run mode - no actual publish');
+        console.log('Command: npm', publishArgs.join(' '));
+      }
+
+      const output = this.execNpmCommand(publishArgs, true);
+
+      // Parse output for tarball URL
+      const tarballMatch = output.match(/https:\/\/[^\s]+\.tgz/);
+      if (tarballMatch) {
+        result.tarball = tarballMatch[0];
+      }
+
+      result.publishedAt = new Date();
+      result.success = true;
+
+      console.log(`Successfully published ${result.packageName}@${result.version}`);
+
+      return result;
+
+    } catch (error) {
+      result.error = error instanceof Error ? error.message : String(error);
+      console.error('Publish failed:', result.error);
+      return result;
+    }
+  }
+
+  /**
+   * Check if package version already exists on npm
+   */
+  async checkVersionExists(packageName: string, version: string): Promise<boolean> {
+    try {
+      const output = this.execNpmCommand(['view', `${packageName}@${version}`, 'version'], true);
+      return output.trim() === version;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get latest published version
+   */
+  async getLatestVersion(packageName: string, tag = 'latest'): Promise<string | null> {
+    try {
+      const output = this.execNpmCommand(['view', `${packageName}@${tag}`, 'version'], true);
+      return output.trim();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get package info from npm registry
+   */
+  async getPackageInfo(packageName: string): Promise<PackageInfo | null> {
+    try {
+      const output = this.execNpmCommand(['view', packageName, '--json'], true);
+      return JSON.parse(output);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Verify npm authentication
+   */
+  async verifyAuth(): Promise<boolean> {
+    try {
+      const output = this.execNpmCommand(['whoami'], true);
+      return output.trim().length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get npm registry URL
+   */
+  async getRegistry(): Promise<string> {
+    try {
+      const output = this.execNpmCommand(['config', 'get', 'registry'], true);
+      return output.trim();
+    } catch {
+      return 'https://registry.npmjs.org/';
+    }
+  }
+
+  /**
+   * Pack package to tarball
+   */
+  async pack(outputDir?: string): Promise<string> {
+    try {
+      const packArgs = ['pack'];
+      if (outputDir) {
+        packArgs.push('--pack-destination', outputDir);
+      }
+
+      const output = this.execNpmCommand(packArgs, true);
+      const tarballName = output.trim().split('\n').pop() || '';
+
+      return outputDir ? join(outputDir, tarballName) : tarballName;
+    } catch (error) {
+      throw new Error(`Failed to pack: ${error}`);
+    }
+  }
+
+  /**
+   * Execute npm command safely using execFileSync
+   */
+  private execNpmCommand(args: string[], returnOutput = false): string {
+    try {
+      // Validate args don't contain shell metacharacters
+      for (const arg of args) {
+        if (/[;&|`$()<>]/.test(arg)) {
+          throw new Error(`Invalid argument: contains shell metacharacters`);
+        }
+      }
+      const output = execFileSync('npm', args, {
+        cwd: this.cwd,
+        encoding: 'utf-8',
+        shell: false,
+        stdio: returnOutput ? ['pipe', 'pipe', 'pipe'] : 'inherit'
+      });
+      return returnOutput ? output : '';
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Execute command (for build scripts only - validated)
+   */
+  private execCommand(cmd: string, returnOutput = false): string {
+    // Only allow npm/npx build commands for safety
+    const allowedPrefixes = ['npm run ', 'npm ', 'npx ', 'pnpm ', 'yarn '];
+    const isAllowed = allowedPrefixes.some(prefix => cmd.startsWith(prefix));
+    if (!isAllowed) {
+      throw new Error(`Disallowed command: only npm/npx/pnpm/yarn commands are permitted`);
+    }
+    // Validate no dangerous shell metacharacters
+    if (/[;&|`$()<>]/.test(cmd)) {
+      throw new Error(`Invalid command: contains shell metacharacters`);
+    }
+    try {
+      const output = execSync(cmd, {
+        cwd: this.cwd,
+        encoding: 'utf-8',
+        stdio: returnOutput ? 'pipe' : 'inherit'
+      });
+      return returnOutput ? output : '';
+    } catch (error) {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Convenience function to publish to npm
+ */
+export async function publishToNpm(
+  options: PublishOptions = {}
+): Promise<PublishResult> {
+  const publisher = new Publisher();
+  return publisher.publishToNpm(options);
+}
+
+/**
+ * Convenience function to check version exists
+ */
+export async function checkVersionExists(
+  packageName: string,
+  version: string
+): Promise<boolean> {
+  const publisher = new Publisher();
+  return publisher.checkVersionExists(packageName, version);
+}
+
+/**
+ * Convenience function to get latest version
+ */
+export async function getLatestVersion(
+  packageName: string,
+  tag?: string
+): Promise<string | null> {
+  const publisher = new Publisher();
+  return publisher.getLatestVersion(packageName, tag);
+}

package/src/release-manager.ts

@@ -0,0 +1,345 @@
+/**
+ * Release Manager
+ * Handles version bumping, changelog generation, and git tagging
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import type {
+  ReleaseOptions,
+  ReleaseResult,
+  PackageInfo,
+  GitCommit,
+  ChangelogEntry,
+  VersionBumpType
+} from './types.js';
+
+export class ReleaseManager {
+  private cwd: string;
+
+  constructor(cwd: string = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Prepare a release with version bumping, changelog, and git tagging
+   */
+  async prepareRelease(options: ReleaseOptions = {}): Promise<ReleaseResult> {
+    const {
+      bumpType = 'patch',
+      version,
+      channel = 'latest',
+      generateChangelog = true,
+      createTag = true,
+      commit = true,
+      dryRun = false,
+      skipValidation = false,
+      tagPrefix = 'v',
+      changelogPath = 'CHANGELOG.md'
+    } = options;
+
+    const result: ReleaseResult = {
+      oldVersion: '',
+      newVersion: '',
+      success: false,
+      warnings: []
+    };
+
+    try {
+      // Read package.json
+      const pkgPath = join(this.cwd, 'package.json');
+      if (!existsSync(pkgPath)) {
+        throw new Error('package.json not found');
+      }
+
+      const pkg: PackageInfo = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      result.oldVersion = pkg.version;
+
+      // Check for uncommitted changes
+      if (!skipValidation) {
+        const gitStatus = this.execCommand('git status --porcelain', true);
+        if (gitStatus && !dryRun) {
+          result.warnings?.push('Uncommitted changes detected');
+        }
+      }
+
+      // Determine new version
+      result.newVersion = version || this.bumpVersion(pkg.version, bumpType, channel);
+
+      // Generate changelog if requested
+      if (generateChangelog) {
+        const commits = this.getCommitsSinceLastTag();
+        const changelogEntry = this.generateChangelogEntry(result.newVersion, commits);
+        result.changelog = this.formatChangelogEntry(changelogEntry);
+
+        if (!dryRun) {
+          this.updateChangelogFile(changelogPath, result.changelog);
+        }
+      }
+
+      // Update package.json version
+      if (!dryRun) {
+        pkg.version = result.newVersion;
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      }
+
+      // Create git commit
+      if (commit && !dryRun) {
+        const commitMessage = `chore(release): ${result.newVersion}`;
+
+        // Stage changes
+        this.execCommand(`git add package.json ${changelogPath}`);
+
+        // Commit
+        this.execCommand(`git commit -m "${commitMessage}"`);
+
+        result.commitHash = this.execCommand('git rev-parse HEAD', true).trim();
+      }
+
+      // Create git tag
+      if (createTag && !dryRun) {
+        result.tag = `${tagPrefix}${result.newVersion}`;
+        const tagMessage = `Release ${result.newVersion}`;
+        this.execCommand(`git tag -a ${result.tag} -m "${tagMessage}"`);
+      }
+
+      result.success = true;
+      return result;
+
+    } catch (error) {
+      result.error = error instanceof Error ? error.message : String(error);
+      return result;
+    }
+  }
+
+  /**
+   * Bump version based on type
+   */
+  private bumpVersion(
+    currentVersion: string,
+    bumpType: VersionBumpType,
+    channel: string
+  ): string {
+    const versionMatch = currentVersion.match(/^(\d+)\.(\d+)\.(\d+)(?:-([a-z]+)\.(\d+))?$/);
+
+    if (!versionMatch) {
+      throw new Error(`Invalid version format: ${currentVersion}`);
+    }
+
+    let [, major, minor, patch, prerelease, prereleaseNum] = versionMatch;
+    let newMajor = parseInt(major);
+    let newMinor = parseInt(minor);
+    let newPatch = parseInt(patch);
+    let newPrerelease: string | undefined = prerelease;
+    let newPrereleaseNum = prereleaseNum ? parseInt(prereleaseNum) : 0;
+
+    switch (bumpType) {
+      case 'major':
+        newMajor++;
+        newMinor = 0;
+        newPatch = 0;
+        newPrerelease = undefined;
+        break;
+
+      case 'minor':
+        newMinor++;
+        newPatch = 0;
+        newPrerelease = undefined;
+        break;
+
+      case 'patch':
+        newPatch++;
+        newPrerelease = undefined;
+        break;
+
+      case 'prerelease':
+        if (newPrerelease && channel === newPrerelease) {
+          newPrereleaseNum++;
+        } else {
+          newPrereleaseNum = 1;
+          newPrerelease = channel;
+        }
+        break;
+    }
+
+    let version = `${newMajor}.${newMinor}.${newPatch}`;
+    if (newPrerelease && bumpType === 'prerelease') {
+      version += `-${newPrerelease}.${newPrereleaseNum}`;
+    }
+
+    return version;
+  }
+
+  /**
+   * Get git commits since last tag
+   */
+  private getCommitsSinceLastTag(): GitCommit[] {
+    try {
+      const lastTag = this.execCommand('git describe --tags --abbrev=0', true).trim();
+      const range = `${lastTag}..HEAD`;
+      return this.parseCommits(range);
+    } catch {
+      // No tags found, get all commits
+      return this.parseCommits('');
+    }
+  }
+
+  /**
+   * Parse git commits
+   */
+  private parseCommits(range: string): GitCommit[] {
+    const format = '--pretty=format:%H%n%s%n%an%n%ai%n---COMMIT---';
+    const cmd = range
+      ? `git log ${range} ${format}`
+      : `git log ${format}`;
+
+    const output = this.execCommand(cmd, true);
+    const commits: GitCommit[] = [];
+
+    const commitBlocks = output.split('---COMMIT---').filter(Boolean);
+
+    for (const block of commitBlocks) {
+      const lines = block.trim().split('\n');
+      if (lines.length < 4) continue;
+
+      const [hash, message, author, date] = lines;
+
+      // Parse conventional commit format
+      const conventionalMatch = message.match(/^(\w+)(?:\(([^)]+)\))?: (.+)$/);
+
+      commits.push({
+        hash: hash.trim(),
+        message: message.trim(),
+        author: author.trim(),
+        date: date.trim(),
+        type: conventionalMatch?.[1],
+        scope: conventionalMatch?.[2],
+        breaking: message.includes('BREAKING CHANGE')
+      });
+    }
+
+    return commits;
+  }
+
+  /**
+   * Generate changelog entry from commits
+   */
+  private generateChangelogEntry(version: string, commits: GitCommit[]): ChangelogEntry {
+    const entry: ChangelogEntry = {
+      version,
+      date: new Date().toISOString().split('T')[0],
+      changes: {
+        breaking: [],
+        features: [],
+        fixes: [],
+        chore: [],
+        docs: [],
+        other: []
+      }
+    };
+
+    for (const commit of commits) {
+      const message = commit.scope
+        ? `**${commit.scope}**: ${commit.message.split(':').slice(1).join(':').trim()}`
+        : commit.message;
+
+      if (commit.breaking) {
+        entry.changes.breaking?.push(message);
+      } else if (commit.type === 'feat') {
+        entry.changes.features?.push(message);
+      } else if (commit.type === 'fix') {
+        entry.changes.fixes?.push(message);
+      } else if (commit.type === 'chore') {
+        entry.changes.chore?.push(message);
+      } else if (commit.type === 'docs') {
+        entry.changes.docs?.push(message);
+      } else {
+        entry.changes.other?.push(message);
+      }
+    }
+
+    return entry;
+  }
+
+  /**
+   * Format changelog entry as markdown
+   */
+  private formatChangelogEntry(entry: ChangelogEntry): string {
+    let markdown = `## [${entry.version}] - ${entry.date}\n\n`;
+
+    const sections = [
+      { title: 'BREAKING CHANGES', items: entry.changes.breaking },
+      { title: 'Features', items: entry.changes.features },
+      { title: 'Bug Fixes', items: entry.changes.fixes },
+      { title: 'Documentation', items: entry.changes.docs },
+      { title: 'Chores', items: entry.changes.chore },
+      { title: 'Other Changes', items: entry.changes.other }
+    ];
+
+    for (const section of sections) {
+      if (section.items && section.items.length > 0) {
+        markdown += `### ${section.title}\n\n`;
+        for (const item of section.items) {
+          markdown += `- ${item}\n`;
+        }
+        markdown += '\n';
+      }
+    }
+
+    return markdown;
+  }
+
+  /**
+   * Update CHANGELOG.md file
+   */
+  private updateChangelogFile(path: string, newEntry: string): void {
+    const changelogPath = join(this.cwd, path);
+    let content = '';
+
+    if (existsSync(changelogPath)) {
+      content = readFileSync(changelogPath, 'utf-8');
+
+      // Insert after header
+      const headerEnd = content.indexOf('\n\n') + 2;
+      if (headerEnd > 1) {
+        content = content.slice(0, headerEnd) + newEntry + content.slice(headerEnd);
+      } else {
+        content = newEntry + '\n' + content;
+      }
+    } else {
+      content = `# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n${newEntry}`;
+    }
+
+    writeFileSync(changelogPath, content);
+  }
+
+  /**
+   * Execute command
+   */
+  private execCommand(cmd: string, returnOutput = false): string {
+    try {
+      const output = execSync(cmd, {
+        cwd: this.cwd,
+        encoding: 'utf-8',
+        stdio: returnOutput ? 'pipe' : 'inherit'
+      });
+      return returnOutput ? output : '';
+    } catch (error) {
+      if (returnOutput && error instanceof Error) {
+        return '';
+      }
+      throw error;
+    }
+  }
+}
+
+/**
+ * Convenience function to prepare a release
+ */
+export async function prepareRelease(
+  options: ReleaseOptions = {}
+): Promise<ReleaseResult> {
+  const manager = new ReleaseManager();
+  return manager.prepareRelease(options);
+}