@sparkleideas/deployment 3.0.0-alpha.8

package/examples/dry-run.ts

@@ -0,0 +1,70 @@
+/**
+ * Dry Run Example
+ *
+ * Test release without making actual changes
+ */
+
+import { prepareRelease, publishToNpm, validate } from '@sparkleideas/deployment';
+
+async function dryRunRelease() {
+  console.log('Dry Run Mode - Testing release without changes\n');
+
+  // Validate package
+  console.log('1. Validating package...');
+  const validation = await validate();
+
+  if (!validation.valid) {
+    console.log('   ⚠️  Validation issues found:');
+    validation.errors.forEach(err => console.log(`      - ${err}`));
+    console.log('\n   (Continuing anyway in dry-run mode)\n');
+  } else {
+    console.log('   ✅ Package validation passed\n');
+  }
+
+  // Prepare release (dry run)
+  console.log('2. Preparing release (dry run)...');
+  const release = await prepareRelease({
+    bumpType: 'minor',
+    generateChangelog: true,
+    createTag: true,
+    commit: true,
+    dryRun: true  // No actual changes
+  });
+
+  if (release.success) {
+    console.log('   Would create release:');
+    console.log(`      Version: ${release.oldVersion} → ${release.newVersion}`);
+    console.log(`      Tag: ${release.tag}`);
+    console.log('   \n   Generated changelog:');
+    if (release.changelog) {
+      release.changelog.split('\n').forEach(line => {
+        console.log(`      ${line}`);
+      });
+    }
+    console.log();
+  }
+
+  // Publish (dry run)
+  console.log('3. Publishing to npm (dry run)...');
+  const publish = await publishToNpm({
+    tag: 'latest',
+    access: 'public',
+    dryRun: true  // No actual publish
+  });
+
+  if (publish.success) {
+    console.log('   Would publish:');
+    console.log(`      Package: ${publish.packageName}@${publish.version}`);
+    console.log(`      Tag: ${publish.tag}`);
+    console.log();
+  }
+
+  console.log('✅ Dry run completed - no changes were made');
+  console.log('   To perform actual release, remove dryRun: true option');
+}
+
+// Run dry run
+dryRunRelease().catch(error => {
+  console.error('Dry run failed:', error);
+  process.exit(1);
+});

package/examples/prerelease-workflow.ts

@@ -0,0 +1,98 @@
+/**
+ * Prerelease Workflow Example
+ *
+ * Demonstrates publishing alpha/beta/rc versions
+ */
+
+import { prepareRelease, publishToNpm } from '@sparkleideas/deployment';
+
+async function prereleaseWorkflow() {
+  console.log('Prerelease Workflow\n');
+
+  // Alpha release (early development)
+  console.log('1. Creating alpha release...');
+  const alpha = await prepareRelease({
+    bumpType: 'prerelease',
+    channel: 'alpha',
+    generateChangelog: true,
+    createTag: true,
+    commit: true
+  });
+
+  if (alpha.success) {
+    console.log(`   Created: ${alpha.newVersion}`);
+
+    await publishToNpm({
+      tag: 'alpha',
+      access: 'public'
+    });
+    console.log('   Published to npm with tag "alpha"\n');
+  }
+
+  // Beta release (feature complete, testing)
+  console.log('2. Creating beta release...');
+  const beta = await prepareRelease({
+    bumpType: 'prerelease',
+    channel: 'beta',
+    generateChangelog: true,
+    createTag: true,
+    commit: true
+  });
+
+  if (beta.success) {
+    console.log(`   Created: ${beta.newVersion}`);
+
+    await publishToNpm({
+      tag: 'beta',
+      access: 'public'
+    });
+    console.log('   Published to npm with tag "beta"\n');
+  }
+
+  // RC release (release candidate)
+  console.log('3. Creating release candidate...');
+  const rc = await prepareRelease({
+    bumpType: 'prerelease',
+    channel: 'rc',
+    generateChangelog: true,
+    createTag: true,
+    commit: true
+  });
+
+  if (rc.success) {
+    console.log(`   Created: ${rc.newVersion}`);
+
+    await publishToNpm({
+      tag: 'rc',
+      access: 'public'
+    });
+    console.log('   Published to npm with tag "rc"\n');
+  }
+
+  // Final release (stable)
+  console.log('4. Creating final release...');
+  const final = await prepareRelease({
+    bumpType: 'patch',
+    generateChangelog: true,
+    createTag: true,
+    commit: true
+  });
+
+  if (final.success) {
+    console.log(`   Created: ${final.newVersion}`);
+
+    await publishToNpm({
+      tag: 'latest',
+      access: 'public'
+    });
+    console.log('   Published to npm with tag "latest"\n');
+  }
+
+  console.log('✅ Prerelease workflow completed!');
+}
+
+// Run the workflow
+prereleaseWorkflow().catch(error => {
+  console.error('Workflow failed:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@sparkleideas/deployment",
+  "version": "3.0.0-alpha.8",
+  "type": "module",
+  "description": "Deployment module - Release management, CI/CD, versioning",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "release": "semantic-release"
+  },
+  "dependencies": {
+    "@sparkleideas/shared": "^3.0.0-alpha.1"
+  },
+  "devDependencies": {
+    "semantic-release": "^25.0.2",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "v3alpha"
+  }
+}

package/src/__tests__/release-manager.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Tests for Deployment Module
+ */
+import { describe, it, expect } from 'vitest';
+import { ReleaseManager } from '../index.js';
+
+describe('ReleaseManager', () => {
+  describe('Constructor', () => {
+    it('should create with default cwd', () => {
+      const manager = new ReleaseManager();
+      expect(manager).toBeDefined();
+    });
+
+    it('should create with custom cwd', () => {
+      const manager = new ReleaseManager('/custom/path');
+      expect(manager).toBeDefined();
+    });
+  });
+});
+
+describe('Version Bump Logic', () => {
+  it('should parse version parts', () => {
+    const version = '1.2.3';
+    const parts = version.split('.').map(Number);
+    
+    expect(parts[0]).toBe(1);
+    expect(parts[1]).toBe(2);
+    expect(parts[2]).toBe(3);
+  });
+
+  it('should bump patch version', () => {
+    const parts = '1.0.0'.split('.').map(Number);
+    const newVersion = [parts[0], parts[1], parts[2] + 1].join('.');
+    expect(newVersion).toBe('1.0.1');
+  });
+
+  it('should bump minor version', () => {
+    const parts = '1.0.0'.split('.').map(Number);
+    const newVersion = [parts[0], parts[1] + 1, 0].join('.');
+    expect(newVersion).toBe('1.1.0');
+  });
+
+  it('should bump major version', () => {
+    const parts = '1.0.0'.split('.').map(Number);
+    const newVersion = [parts[0] + 1, 0, 0].join('.');
+    expect(newVersion).toBe('2.0.0');
+  });
+});
+
+describe('Changelog Generation', () => {
+  it('should format date correctly', () => {
+    const date = new Date('2026-01-05');
+    const formatted = date.toISOString().split('T')[0];
+    expect(formatted).toBe('2026-01-05');
+  });
+
+  it('should categorize commits by type', () => {
+    const commits = [
+      { message: 'feat: add new feature' },
+      { message: 'fix: fix bug' },
+      { message: 'docs: update docs' },
+    ];
+
+    const feat = commits.filter(c => c.message.startsWith('feat:'));
+    const fix = commits.filter(c => c.message.startsWith('fix:'));
+    const docs = commits.filter(c => c.message.startsWith('docs:'));
+
+    expect(feat).toHaveLength(1);
+    expect(fix).toHaveLength(1);
+    expect(docs).toHaveLength(1);
+  });
+});

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * @sparkleideas/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);
+}