@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/gitflow/cli/finish/execute.ts

@@ -0,0 +1,127 @@
+import * as git from '../lib/git.js'
+import * as branch from '../lib/branch.js'
+import * as config from '../lib/config.js'
+import * as worktree from '../lib/worktree.js'
+import * as version from '../lib/version.js'
+import type { FinishResult, FinishOptions } from './types.js'
+
+export async function execute(
+  opts: FinishOptions,
+  cwd?: string,
+): Promise<FinishResult> {
+  try {
+    // Get current or specified branch
+    let currentBranch = opts.branch || await git.getCurrentBranch(cwd)
+
+    // Detect type
+    const branchType = branch.detectBranchType(currentBranch)
+
+    // Block if main/develop/other
+    if (branchType === 'main' || branchType === 'develop' || branchType === 'other') {
+      return {
+        success: false,
+        branch: currentBranch,
+        branchType: 'feature',
+        error: `Cannot finish ${branchType} branch`,
+      }
+    }
+
+    // Read config
+    const cfg = await config.readConfigForPlatform()
+
+    // Verify PR is merged
+    const isMerged = await git.isMerged(currentBranch, cfg.git.branches.main, cwd)
+    if (!isMerged) {
+      return {
+        success: false,
+        branch: currentBranch,
+        branchType: branchType as 'feature' | 'release' | 'hotfix',
+        error: `Branch ${currentBranch} is not merged into ${cfg.git.branches.main}`,
+      }
+    }
+
+    let tag: string | undefined
+    let mergedBack = false
+    let versionBumped = false
+
+    // For release/hotfix: tag on main, merge-back to develop, bump version
+    if (branchType === 'release' || branchType === 'hotfix') {
+      // Detect version from branch name
+      const versionMatch = currentBranch.match(/(?:release|hotfix)\/(.+)/)
+      if (versionMatch) {
+        const versionStr = versionMatch[1]
+        const tagName = `${cfg.versioning.tagPrefix}${versionStr}`
+        tag = tagName
+
+        // Create and push tag
+        const tagMessage = `Release ${versionStr} (${branchType})`
+        await git.createTag(tagName, tagMessage, cwd)
+        await git.pushTag(tagName, cwd)
+
+        // Merge-back to develop if not feature
+        const developBranch = cfg.git.branches.develop
+        const isDevMerged = await git.isMerged(currentBranch, developBranch, cwd)
+
+        if (!isDevMerged) {
+          // Checkout develop, merge with no-ff
+          await git.checkout(developBranch, cwd)
+          await git.mergeNoFf(currentBranch, `Merge ${currentBranch} back to ${developBranch}`, cwd)
+          await git.push(developBranch, cwd)
+          mergedBack = true
+        }
+
+        // Bump version in source files
+        const projDir = cfg.repository.rootFolder || cwd || process.cwd()
+        const bumpType = version.getBumpType(branchType)
+        const newVersion = version.bumpVersion(cfg.versioning.current, bumpType)
+        await version.updateVersionSources(projDir, newVersion, cfg.versioning.sources)
+        versionBumped = true
+      }
+    }
+
+    // Cleanup worktree if enabled
+    let worktreeCleaned = false
+    if (cfg.worktrees.enabled) {
+      const wtPath = worktree.getWorktreePath(currentBranch, cfg)
+      if (wtPath) {
+        try {
+          await worktree.removeWorktree(wtPath, cwd)
+          worktreeCleaned = true
+        } catch {
+          // Ignore worktree cleanup errors
+        }
+      }
+    }
+
+    // Delete branch locally and remotely
+    try {
+      await git.deleteBranch(currentBranch, false, false, cwd)
+    } catch {
+      // Ignore local deletion errors
+    }
+
+    try {
+      await git.deleteBranch(currentBranch, true, false, cwd)
+    } catch {
+      // Ignore remote deletion errors
+    }
+
+    return {
+      success: true,
+      branch: currentBranch,
+      branchType: branchType as 'feature' | 'release' | 'hotfix',
+      tag,
+      mergedBack,
+      versionBumped,
+      worktreeCleaned,
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return {
+      success: false,
+      branch: opts.branch || '',
+      branchType: 'feature',
+      error: message,
+    }
+  }
+}

package/templates/skills/gitflow/cli/finish/index.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * cli:finish — Finish a feature/release/hotfix branch
+ * Responsabilité : Parse args → validate → execute → output JSON
+ */
+import { parseArgs } from 'node:util'
+import { validate } from './validate.js'
+import { execute } from './execute.js'
+import type { FinishResult } from './types.js'
+
+// ─── Parse des arguments ──────────────────────────────────────────────────────
+
+const { values } = parseArgs({
+  options: {
+    spec: { type: 'string' },
+    json: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+  },
+})
+
+if (values.help) {
+  console.log(`
+cli:finish — Finish a feature/release/hotfix branch
+
+Usage:
+  npx ts-node cli/finish/index.ts --spec '<JSON>'
+
+Options:
+  --spec   JSON spec with { branch?: string } (defaults to current branch)
+  --json   Output JSON only
+  --help   Show this help
+  `)
+  process.exit(0)
+}
+
+// ─── Parse du JSON ────────────────────────────────────────────────────────────
+
+let spec: unknown = {}
+
+if (values.spec) {
+  try {
+    spec = JSON.parse(values.spec)
+  } catch {
+    const result: FinishResult = {
+      success: false,
+      branch: '',
+      branchType: 'feature',
+      error: 'Invalid JSON in --spec',
+    }
+    output(result, values.json ?? false)
+    process.exit(2)
+  }
+}
+
+// ─── Validation ───────────────────────────────────────────────────────────────
+
+const validation = validate(spec)
+
+if (!validation.valid) {
+  const result: FinishResult = {
+    success: false,
+    branch: '',
+    branchType: 'feature',
+    error: validation.blockers.join('; '),
+  }
+  output(result, values.json ?? false)
+  process.exit(2)
+}
+
+// ─── Exécution ────────────────────────────────────────────────────────────────
+
+execute(validation.data as any, process.cwd())
+  .then((result) => {
+    output(result, values.json ?? false)
+    const exitCode = result.success ? 0 : validation.blockers.length > 0 ? 2 : 1
+    process.exit(exitCode)
+  })
+  .catch((err) => {
+    const message = err instanceof Error ? err.message : String(err)
+    const result: FinishResult = {
+      success: false,
+      branch: '',
+      branchType: 'feature',
+      error: message,
+    }
+    output(result, values.json ?? false)
+    process.exit(2)
+  })
+
+// ─── Helper ───────────────────────────────────────────────────────────────────
+
+function output(data: FinishResult, json: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(data, null, 2))
+  } else {
+    if (data.success) {
+      console.log(`✓ Finished ${data.branchType} branch: ${data.branch}`)
+      if (data.tag) console.log(`  Tagged as: ${data.tag}`)
+      if (data.mergedBack) console.log(`  Merged back to develop`)
+      if (data.versionBumped) console.log(`  Version bumped`)
+      if (data.worktreeCleaned) console.log(`  Worktree cleaned`)
+    } else {
+      console.error(`✗ Failed to finish branch: ${data.error}`)
+    }
+  }
+}

package/templates/skills/gitflow/cli/finish/types.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+// ─── Input Options ───────────────────────────────────────────────────────
+
+export const FinishOptionsSchema = z.object({
+  branch: z.string().optional(),
+})
+
+// ─── Result ───────────────────────────────────────────────────────────
+
+export const FinishResultSchema = z.object({
+  success: z.boolean(),
+  branch: z.string(),
+  branchType: z.enum(['feature', 'release', 'hotfix']),
+  tag: z.string().optional(),
+  mergedBack: z.boolean().optional(),
+  versionBumped: z.boolean().optional(),
+  worktreeCleaned: z.boolean().optional(),
+  error: z.string().optional(),
+})
+
+// ─── Inferred Types ───────────────────────────────────────────────────────
+
+export type FinishOptions = z.infer<typeof FinishOptionsSchema>
+export type FinishResult = z.infer<typeof FinishResultSchema>

package/templates/skills/gitflow/cli/finish/validate.ts

@@ -0,0 +1,44 @@
+import { FinishOptionsSchema } from './types.js'
+
+export interface ValidationResult {
+  valid: boolean
+  data?: Record<string, unknown>
+  blockers: string[]
+  warnings: string[]
+}
+
+export function validate(spec: unknown): ValidationResult {
+  const blockers: string[] = []
+  const warnings: string[] = []
+
+  try {
+    const parsed = FinishOptionsSchema.parse(spec)
+
+    // Validate branch name format if provided (pure string validation, no lib)
+    if (parsed.branch) {
+      if (parsed.branch.trim().length === 0) {
+        blockers.push('Branch name cannot be empty')
+      }
+      if (parsed.branch.length > 100) {
+        blockers.push('Branch name too long (max 100 characters)')
+      }
+      if (/[~^:?*\[\\]/.test(parsed.branch)) {
+        blockers.push(`Branch name contains invalid characters: ${parsed.branch}`)
+      }
+      if (parsed.branch.startsWith('-') || parsed.branch.endsWith('.') || parsed.branch.endsWith('/') || parsed.branch.includes('..')) {
+        blockers.push(`Branch name has invalid format: ${parsed.branch}`)
+      }
+    }
+
+    return {
+      valid: blockers.length === 0,
+      data: parsed as Record<string, unknown>,
+      blockers,
+      warnings,
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    blockers.push(`Invalid spec: ${message}`)
+    return { valid: false, blockers, warnings }
+  }
+}

package/templates/skills/gitflow/cli/generate-msg/execute.ts

@@ -0,0 +1,51 @@
+/**
+ * generate-msg CLI execute — Formalize Claude's analysis into a conventional commit message
+ *
+ * Receives structured analysis from the Skill (Claude) and produces
+ * a formatted commit message in Markdown with conventional commits header.
+ */
+
+import type { GenerateMsgSpec, GenerateMsgResult } from './types.js';
+
+const TYPE_MAP: Record<string, string> = {
+  feature: 'feat',
+  hotfix: 'fix',
+  release: 'chore',
+  develop: 'chore',
+  main: 'chore',
+  other: 'chore',
+};
+
+export async function execute(spec: GenerateMsgSpec): Promise<GenerateMsgResult> {
+  try {
+    const type = TYPE_MAP[spec.branchType] || 'chore';
+    const scope = spec.scope ? `(${spec.scope})` : '';
+    const header = `${type}${scope}: ${spec.summary}`;
+
+    // Build MD body from file analysis
+    const lines: string[] = [header];
+
+    if (spec.files.length > 0) {
+      lines.push('');
+      for (const file of spec.files) {
+        const icon = file.status === 'added' ? '+' : file.status === 'deleted' ? '-' : '~';
+        lines.push(`- ${icon} \`${file.path}\`: ${file.summary}`);
+      }
+    }
+
+    if (spec.breaking) {
+      lines.push('');
+      lines.push(`BREAKING CHANGE: ${spec.breaking}`);
+    }
+
+    const message = lines.join('\n');
+
+    return { success: true, message };
+  } catch (err: unknown) {
+    return {
+      success: false,
+      error: (err as Error).message,
+      message: '',
+    };
+  }
+}

package/templates/skills/gitflow/cli/generate-msg/index.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * generate-msg CLI — Formalize commit message from Claude's analysis
+ *
+ * Input: JSON spec with branch info + Claude's per-file analysis
+ * Output: Formatted conventional commit message in Markdown
+ */
+
+import { parseArgs } from 'node:util';
+import { validate } from './validate.js';
+import { execute } from './execute.js';
+import { GenerateMsgResultSchema } from './types.js';
+
+async function main() {
+  try {
+    const args = parseArgs({
+      options: {
+        spec: { type: 'string' },
+        json: { type: 'boolean', default: false },
+      },
+      allowPositionals: false,
+    });
+
+    if (!args.values.spec) {
+      console.error('Error: --spec is required');
+      process.exit(2);
+    }
+
+    let specObj: unknown;
+    try {
+      specObj = JSON.parse(args.values.spec);
+    } catch {
+      console.error('Error: --spec must be valid JSON');
+      process.exit(2);
+    }
+
+    const validation = validate(specObj);
+    if (!validation.valid) {
+      if (args.values.json) {
+        console.log(JSON.stringify({
+          success: false,
+          error: validation.blockers.join('; '),
+          message: '',
+        }, null, 2));
+      } else {
+        console.error('Validation failed:');
+        validation.blockers.forEach((b) => console.error(`  - ${b}`));
+      }
+      process.exit(2);
+    }
+
+    const result = await execute(validation.data!);
+    const validated = GenerateMsgResultSchema.parse(result);
+
+    if (args.values.json) {
+      console.log(JSON.stringify(validated, null, 2));
+    } else {
+      if (validated.success) {
+        console.log(validated.message);
+      } else {
+        console.error(`Error: ${validated.error}`);
+      }
+    }
+
+    process.exit(validated.success ? 0 : 1);
+  } catch (err: unknown) {
+    console.error('Fatal error:', (err as Error).message);
+    process.exit(2);
+  }
+}
+
+main();

package/templates/skills/gitflow/cli/generate-msg/types.ts

@@ -0,0 +1,37 @@
+/**
+ * generate-msg CLI types — Input spec and output result
+ *
+ * The Skill (Claude) analyzes the changes and passes its analysis to this CLI.
+ * The CLI formalizes the commit message in conventional format.
+ */
+
+import { z } from 'zod';
+
+export const FileAnalysisSchema = z.object({
+  path: z.string(),
+  status: z.enum(['added', 'modified', 'deleted', 'renamed']),
+  summary: z.string(),
+});
+
+export const GenerateMsgSpecSchema = z.object({
+  branch: z.string(),
+  branchType: z.enum(['feature', 'release', 'hotfix', 'develop', 'main', 'other']),
+  scope: z.string(),
+  /** One-line summary of all changes (from Claude's analysis) */
+  summary: z.string(),
+  /** Per-file analysis (from Claude reading each file) */
+  files: z.array(FileAnalysisSchema),
+  /** Optional breaking change description */
+  breaking: z.string().optional(),
+});
+
+export type GenerateMsgSpec = z.infer<typeof GenerateMsgSpecSchema>;
+
+export const GenerateMsgResultSchema = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+  /** The formatted commit message (conventional commits + MD body) */
+  message: z.string(),
+});
+
+export type GenerateMsgResult = z.infer<typeof GenerateMsgResultSchema>;

package/templates/skills/gitflow/cli/generate-msg/validate.ts

@@ -0,0 +1,42 @@
+/**
+ * generate-msg CLI validate — Pure validation, no I/O
+ */
+
+import { GenerateMsgSpecSchema, type GenerateMsgSpec } from './types.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  data?: GenerateMsgSpec;
+  blockers: string[];
+  warnings: string[];
+}
+
+export function validate(spec: unknown): ValidationResult {
+  const blockers: string[] = [];
+  const warnings: string[] = [];
+
+  let data: GenerateMsgSpec | undefined;
+  try {
+    data = GenerateMsgSpecSchema.parse(spec);
+  } catch (err: unknown) {
+    const e = err as any;
+    if (e.errors) {
+      for (const error of e.errors) {
+        blockers.push(`${error.path?.join('.')}: ${error.message}`);
+      }
+    } else {
+      blockers.push(`Spec parse failed: ${(err as Error).message}`);
+    }
+    return { valid: false, blockers, warnings };
+  }
+
+  if (!data.summary.trim()) {
+    blockers.push('summary cannot be empty');
+  }
+
+  if (data.files.length === 0) {
+    warnings.push('No file analysis provided — message will be generic');
+  }
+
+  return { valid: blockers.length === 0, data, blockers, warnings };
+}

package/templates/skills/gitflow/cli/init/execute.ts

@@ -0,0 +1,186 @@
+/**
+ * execute.ts — Execution logic. Imports from ../lib/. NO validation.
+ * Receives validated data, returns typed result.
+ */
+import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import type { InitSpec, InitResult } from './types.js';
+import { detectPlatform } from '../lib/platform.js';
+import { detectProvider, parseAzureDevOpsUrl } from '../lib/provider.js';
+import { execGit } from '../lib/git.js';
+import { listWorktrees } from '../lib/worktree.js';
+import { detectVersion } from '../lib/version.js';
+import { normalizeForStorage } from '../lib/paths.js';
+
+export async function execute(spec: InitSpec, workDir: string = process.cwd()): Promise<InitResult> {
+  try {
+    // Detect platform
+    const platformInfo = detectPlatform();
+
+    // If no URL provided, detect from current repo or ask for input
+    let repoUrl = spec.url;
+    let repoName = spec.name;
+
+    if (!repoUrl) {
+      // Try to detect from current git remote
+      const remoteResult = await execGit(['config', '--get', 'remote.origin.url'], workDir);
+      if (remoteResult.exitCode === 0 && remoteResult.stdout) {
+        repoUrl = remoteResult.stdout;
+      }
+    }
+
+    if (!repoUrl || !repoName) {
+      // Need user input
+      return {
+        success: true,
+        needsInput: true,
+        detected: {
+          platform: platformInfo.platform,
+          provider: repoUrl ? detectProvider(repoUrl) : 'unknown',
+        },
+      };
+    }
+
+    // Detect provider and extract details
+    const provider = detectProvider(repoUrl);
+    const azureInfo = provider === 'azuredevops' ? parseAzureDevOpsUrl(repoUrl) : null;
+
+    // Detect branches
+    const mainResult = await execGit(['config', '--get', 'init.defaultBranch'], workDir);
+    const mainBranch = mainResult.stdout || 'main';
+
+    // Detect version
+    const versionInfo = await detectVersion(workDir);
+
+    // Resolve root folder (git root or workDir)
+    const gitRootResult = await execGit(['rev-parse', '--show-toplevel'], workDir);
+    const gitRoot = gitRootResult.exitCode === 0 ? gitRootResult.stdout : workDir;
+    const rootFolder = normalizeForStorage(spec.root || gitRoot);
+
+    // Create config path
+    const configDir = join(rootFolder, '.claude', 'gitflow');
+    mkdirSync(configDir, { recursive: true });
+    const configPath = join(configDir, 'config.json');
+
+    // Determine worktree settings
+    let worktreeRootPath: string | undefined;
+    if (spec.mode !== 'disabled') {
+      worktreeRootPath = spec.mode === 'organized'
+        ? join(rootFolder, '..', '.worktrees')
+        : rootFolder;
+    }
+
+    // Create config
+    const config = {
+      version: '2.1.0',
+      platform: {
+        detected: platformInfo.platform,
+        shell: platformInfo.shell,
+        detectedAt: new Date().toISOString(),
+      },
+      workspace: {
+        path: rootFolder,
+        name: spec.name || repoName,
+      },
+      repository: {
+        name: repoName,
+        rootFolder,
+        remoteUrl: repoUrl,
+        defaultBranch: mainBranch,
+        nameVariants: {
+          camelCase: toCamelCase(repoName),
+          PascalCase: toPascalCase(repoName),
+          snake_case: toSnakeCase(repoName),
+          UPPER_SNAKE: toUpperSnake(repoName),
+          kebab_case: toKebabCase(repoName),
+        },
+      },
+      git: {
+        provider,
+        branches: {
+          main: mainBranch,
+          develop: 'develop',
+        },
+        prefixes: {
+          feature: 'feature/',
+          release: 'release/',
+          hotfix: 'hotfix/',
+        },
+      },
+      worktree: {
+        mode: spec.mode,
+        rootPath: worktreeRootPath ? normalizeForStorage(worktreeRootPath) : undefined,
+      },
+    };
+
+    // Write config
+    writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+    // Repair worktree paths if needed
+    if (spec.mode !== 'disabled') {
+      await repairWorktreePaths(rootFolder, config);
+    }
+
+    return {
+      success: true,
+      config: config as any,
+      structure: {
+        configPath,
+        worktreeDir: worktreeRootPath,
+      },
+      validation: {
+        blockers: [],
+        warnings: [],
+      },
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: (err as Error).message,
+      validation: {
+        blockers: [(err as Error).message],
+        warnings: [],
+      },
+    };
+  }
+}
+
+async function repairWorktreePaths(rootFolder: string, config: any): Promise<void> {
+  const worktrees = await listWorktrees(rootFolder);
+  for (const wt of worktrees) {
+    if (wt.path && !existsSync(wt.path)) {
+      // Worktree path is broken, would need git worktree repair here
+      // For now, just log it
+    }
+  }
+}
+
+function toCamelCase(str: string): string {
+  return str
+    .replace(/[-_.]([a-z0-9])/gi, (_, char) => char.toUpperCase())
+    .replace(/^([A-Z])/, (_, char) => char.toLowerCase());
+}
+
+function toPascalCase(str: string): string {
+  return str
+    .replace(/[-_.]([a-z0-9])/gi, (_, char) => char.toUpperCase())
+    .replace(/^([a-z])/, (_, char) => char.toUpperCase());
+}
+
+function toSnakeCase(str: string): string {
+  return str
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[-.\s]/g, '_')
+    .toLowerCase();
+}
+
+function toUpperSnake(str: string): string {
+  return toSnakeCase(str).toUpperCase();
+}
+
+function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[_.\s]/g, '-')
+    .toLowerCase();
+}