@nlaprell/shipit 1.0.0

package/cli/src/commands/init.js

@@ -0,0 +1,267 @@
+/**
+ * shipit init command - Attach ShipIt to existing project
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import fsExtra from 'fs-extra';
+
+const { mkdirSync } = fsExtra;
+import { join, resolve } from 'path';
+import { readManifest, getFrameworkRoot } from '../utils/manifest.js';
+import { detectTechStack, isValidStack } from '../utils/stack-detection.js';
+import { copyFrameworkFiles } from '../utils/file-copy.js';
+import { mergePackageJson, getShipitScripts, getShipitDevDependencies } from '../utils/package-json-merge.js';
+import { createReadlineInterface, promptUser } from '../utils/prompts.js';
+import { readConfig } from '../utils/config.js';
+import { createCIWorkflow } from '../utils/stack-files.js';
+
+/**
+ * Check if ShipIt is already initialized
+ * @param {string} projectPath - Project directory path
+ * @returns {boolean} True if ShipIt is initialized
+ */
+function isShipItInitialized(projectPath) {
+  const projectJsonPath = join(projectPath, 'project.json');
+  const canonPath = join(projectPath, '_system', 'architecture', 'CANON.md');
+  return existsSync(projectJsonPath) || existsSync(canonPath);
+}
+
+/**
+ * Read description from existing project files
+ * @param {string} projectPath - Project directory path
+ * @param {string} stack - Tech stack
+ * @returns {string|null} Description or null
+ */
+function readDescription(projectPath, stack) {
+  if (stack === 'typescript-nodejs') {
+    const packageJsonPath = join(projectPath, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        return pkg.description || null;
+      } catch (e) {
+        // Ignore errors
+      }
+    }
+  } else if (stack === 'python') {
+    const pyprojectPath = join(projectPath, 'pyproject.toml');
+    if (existsSync(pyprojectPath)) {
+      // Simple extraction (could use toml parser)
+      const content = readFileSync(pyprojectPath, 'utf-8');
+      const match = content.match(/description\s*=\s*["']([^"']+)["']/);
+      if (match) {
+        return match[1];
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Create project.json
+ * @param {string} projectPath - Project directory path
+ * @param {object} metadata - Project metadata
+ */
+function createProjectJson(projectPath, metadata) {
+  const projectJsonPath = join(projectPath, 'project.json');
+  
+  const projectJson = {
+    name: metadata.name,
+    description: metadata.description,
+    version: metadata.version || '0.1.0',
+    techStack: metadata.techStack,
+    created: new Date().toISOString(),
+    highRiskDomains: metadata.highRiskDomains || [],
+    settings: {
+      humanResponseTime: 'minutes',
+      confidenceThreshold: 0.7,
+      testCoverageMinimum: 80
+    },
+    shipitVersion: metadata.shipitVersion || '1.0.0'
+  };
+
+  writeFileSync(projectJsonPath, JSON.stringify(projectJson, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Create .override directory structure
+ * @param {string} projectPath - Project directory path
+ */
+function createOverrideDirectory(projectPath) {
+  const overrideDirs = [
+    '.override/rules',
+    '.override/commands',
+    '.override/scripts',
+    '.override/config'
+  ];
+
+  for (const dir of overrideDirs) {
+    const dirPath = join(projectPath, dir);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Init command implementation
+ * @param {object} options - Command options
+ */
+export async function initCommand(options) {
+  const projectPath = resolve(options.path || process.cwd());
+  const nonInteractive = options.nonInteractive || process.env.SHIPIT_NON_INTERACTIVE === '1';
+  const force = options.force || false;
+
+  // Check if ShipIt already initialized
+  if (isShipItInitialized(projectPath) && !force) {
+    if (nonInteractive) {
+      throw new Error('ShipIt already initialized. Use --force to re-initialize or shipit upgrade to update.');
+    }
+    const rl = createReadlineInterface();
+    const answer = await promptUser(rl, 'ShipIt already initialized. Use "shipit upgrade" instead? (y/N): ');
+    rl.close();
+    if (answer.toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+    // User wants to upgrade instead - this should call upgrade command
+    // For now, just exit with message
+    console.log('Run "shipit upgrade" to update framework files.');
+    process.exit(0);
+  }
+
+  // Read config
+  const config = readConfig(projectPath);
+
+  // Detect or get tech stack
+  let techStack = options.techStack || config.techStack;
+  if (!techStack) {
+    techStack = detectTechStack(projectPath);
+  }
+
+  if (!techStack) {
+    if (nonInteractive) {
+      techStack = 'other'; // Default for non-interactive
+    } else {
+      const rl = createReadlineInterface();
+      console.log('Tech stack selection:');
+      console.log('1) TypeScript/Node.js (recommended)');
+      console.log('2) Python');
+      console.log('3) Other (manual setup)');
+      const choice = await promptUser(rl, 'Select tech stack [1=TS/Node, 2=Python, 3=Other]: ');
+      rl.close();
+      
+      switch (choice.trim()) {
+        case '1': techStack = 'typescript-nodejs'; break;
+        case '2': techStack = 'python'; break;
+        case '3': techStack = 'other'; break;
+        default: techStack = 'typescript-nodejs';
+      }
+    }
+  }
+
+  if (!isValidStack(techStack)) {
+    throw new Error(`Invalid tech stack: ${techStack}. Must be typescript-nodejs, python, or other.`);
+  }
+
+  // Get description
+  let description = options.description || config.description;
+  if (!description) {
+    description = readDescription(projectPath, techStack);
+  }
+  if (!description && !nonInteractive) {
+    const rl = createReadlineInterface();
+    description = await promptUser(rl, 'Project description (short): ');
+    rl.close();
+  }
+  description = description || 'ShipIt project';
+
+  // Get high-risk domains
+  let highRisk = options.highRisk || config.highRisk;
+  if (!highRisk && !nonInteractive) {
+    const rl = createReadlineInterface();
+    console.log('High-Risk Domains (comma-separated, or "none"):');
+    console.log('Examples: auth, payments, permissions, infrastructure, pii');
+    highRisk = await promptUser(rl, 'High-risk domains: ');
+    rl.close();
+  }
+  highRisk = highRisk || 'none';
+  const highRiskArray = highRisk === 'none' ? [] : highRisk.split(',').map(s => s.trim());
+
+  // Read manifest
+  const manifest = readManifest();
+  const frameworkRoot = getFrameworkRoot();
+
+  console.log('Initializing ShipIt...');
+  console.log(`  Tech stack: ${techStack}`);
+  console.log(`  Description: ${description}`);
+
+  // Copy framework files
+  const copyResult = copyFrameworkFiles(frameworkRoot, projectPath, techStack, manifest, {
+    verbose: !nonInteractive,
+    dryRun: false
+  });
+
+  if (copyResult.errors.length > 0) {
+    console.error('Errors during file copy:');
+    copyResult.errors.forEach(err => console.error(`  ${err}`));
+    throw new Error('Failed to copy some framework files');
+  }
+
+  // Merge package.json if exists
+  const packageJsonPath = join(projectPath, 'package.json');
+  if (existsSync(packageJsonPath) && techStack === 'typescript-nodejs') {
+    console.log('Merging package.json...');
+    const shipitScripts = getShipitScripts();
+    const shipitDevDeps = getShipitDevDependencies();
+    mergePackageJson(packageJsonPath, shipitScripts, shipitDevDeps, {
+      verbose: !nonInteractive
+    });
+  }
+
+  // Create project.json
+  const projectName = readProjectName(projectPath, techStack);
+  createProjectJson(projectPath, {
+    name: projectName,
+    description,
+    techStack,
+    highRiskDomains: highRiskArray,
+    shipitVersion: '1.0.0' // TODO: Get from package.json
+  });
+
+  // Create .override directory
+  createOverrideDirectory(projectPath);
+
+  // Create stack-specific CI workflow (only if .github/workflows doesn't exist or ci.yml doesn't exist)
+  const workflowsDir = join(projectPath, '.github', 'workflows');
+  const ciPath = join(workflowsDir, 'ci.yml');
+  if (!existsSync(ciPath)) {
+    createCIWorkflow(projectPath, techStack);
+  }
+
+  console.log('\n✓ ShipIt initialized successfully!');
+  console.log('\nNext steps:');
+  console.log('1. Run /scope-project to break down into features');
+  console.log('2. Review project.json and customize as needed');
+  console.log('3. Start creating intents with /new_intent');
+}
+
+/**
+ * Read project name from existing files
+ */
+function readProjectName(projectPath, stack) {
+  if (stack === 'typescript-nodejs') {
+    const packageJsonPath = join(projectPath, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        return pkg.name || 'my-project';
+      } catch (e) {
+        // Ignore
+      }
+    }
+  }
+  // Default or extract from directory name
+  const dirName = projectPath.split('/').pop() || 'my-project';
+  return dirName;
+}

package/cli/src/commands/upgrade.js

@@ -0,0 +1,196 @@
+/**
+ * shipit upgrade command - Upgrade ShipIt framework files
+ * shipit restore / shipit list-backups - Backup management
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { readManifest, getFrameworkRoot } from '../utils/manifest.js';
+import { getInstalledShipItVersion, getProjectShipItVersion, compareVersions } from '../utils/version.js';
+import {
+  isFileModified,
+  backupFile,
+  listBackups,
+  restoreFromBackup,
+  getFrameworkFileList
+} from '../utils/upgrade-backup.js';
+import { mergeProjectJson } from '../utils/project-json-merge.js';
+import { mergeGitignore } from '../utils/gitignore-merge.js';
+import { mergePackageJson, getShipitScripts, getShipitDevDependencies } from '../utils/package-json-merge.js';
+import { createReadlineInterface, promptUser } from '../utils/prompts.js';
+import fsExtra from 'fs-extra';
+
+const { copySync, mkdirSync } = fsExtra;
+
+const BACKUP_DIR = '._shipit_backup';
+
+function isShipItInitialized(projectPath) {
+  return (
+    existsSync(join(projectPath, 'project.json')) ||
+    existsSync(join(projectPath, '_system', 'architecture', 'CANON.md'))
+  );
+}
+
+function getNeverCopiedSet(manifest) {
+  return new Set([
+    ...(manifest.neverCopied?.files || []),
+    ...(manifest.neverCopied?.directories || []),
+    '.override'
+  ]);
+}
+
+/**
+ * Upgrade command implementation
+ */
+export async function upgradeCommand(options) {
+  const projectPath = resolve(options.path || process.cwd());
+  const backupDir = options.backupDir || BACKUP_DIR;
+  const dryRun = options.dryRun || false;
+  const force = options.force || false;
+
+  if (!existsSync(projectPath)) {
+    const err = new Error(`Directory not found: ${projectPath}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  if (!isShipItInitialized(projectPath)) {
+    const err = new Error('ShipIt is not initialized in this project. Run "shipit init" first.');
+    err.exitCode = 3;
+    throw err;
+  }
+
+  const installedVersion = getInstalledShipItVersion();
+  const projectVersion = getProjectShipItVersion(projectPath);
+  const comparison = compareVersions(installedVersion, projectVersion || '0.0.0');
+
+  if (comparison === 'same') {
+    console.log(`Already up to date (ShipIt ${installedVersion}).`);
+    return;
+  }
+
+  if (comparison === 'older') {
+    console.warn(
+      `Warning: Project has ShipIt ${projectVersion || 'unknown'}, installed is ${installedVersion}. Project may be ahead.`
+    );
+    if (!force && !dryRun) {
+      const rl = createReadlineInterface();
+      const answer = await promptUser(rl, 'Continue anyway? (y/N): ');
+      rl.close();
+      if (answer.toLowerCase() !== 'y') {
+        console.log('Aborted.');
+        process.exit(0);
+      }
+    }
+  }
+
+  const manifest = readManifest();
+  const frameworkRoot = getFrameworkRoot();
+  const neverCopied = getNeverCopiedSet(manifest);
+  const frameworkFiles = getFrameworkFileList(frameworkRoot, manifest, neverCopied);
+
+  const modified = [];
+  for (const rel of frameworkFiles) {
+    if (isFileModified(projectPath, frameworkRoot, rel)) {
+      modified.push(rel);
+    }
+  }
+
+  if (modified.length > 0 && !force && !dryRun) {
+    console.log('The following framework files have been modified and will be backed up before replacement:');
+    modified.slice(0, 20).forEach((f) => console.log(`  - ${f}`));
+    if (modified.length > 20) console.log(`  ... and ${modified.length - 20} more`);
+    const rl = createReadlineInterface();
+    const answer = await promptUser(rl, 'Continue? (y/N): ');
+    rl.close();
+    if (answer.toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+  }
+
+  if (dryRun) {
+    console.log('\nDry run - would perform:');
+    console.log(`  Backup ${modified.length} modified file(s)`);
+    console.log(`  Replace ${frameworkFiles.length} framework file(s)`);
+    console.log(`  Merge project.json (shipitVersion → ${installedVersion})`);
+    console.log('  Merge package.json if present');
+    console.log('  Merge .gitignore if present');
+    return;
+  }
+
+  // Backup modified files
+  for (const rel of modified) {
+    backupFile(projectPath, rel, backupDir);
+    if (options.verbose) console.log(`  Backed up: ${rel}`);
+  }
+
+  // Replace all framework files
+  for (const rel of frameworkFiles) {
+    const src = join(frameworkRoot, rel);
+    const dest = join(projectPath, rel);
+    if (!existsSync(src)) continue;
+    mkdirSync(join(dest, '..'), { recursive: true });
+    copySync(src, dest, { overwrite: true });
+  }
+
+  // Merge project.json
+  mergeProjectJson(projectPath, installedVersion, { verbose: options.verbose });
+
+  // Merge package.json if present (use project's tech stack from project.json)
+  const projectJsonPath = join(projectPath, 'project.json');
+  let techStack = 'typescript-nodejs';
+  if (existsSync(projectJsonPath)) {
+    try {
+      const pj = JSON.parse(readFileSync(projectJsonPath, 'utf-8'));
+      techStack = pj.techStack || techStack;
+    } catch (_) {}
+  }
+  const packageJsonPath = join(projectPath, 'package.json');
+  if (existsSync(packageJsonPath) && techStack === 'typescript-nodejs') {
+    const shipitScripts = getShipitScripts();
+    const shipitDevDeps = getShipitDevDependencies();
+    mergePackageJson(packageJsonPath, shipitScripts, shipitDevDeps, { verbose: options.verbose });
+  }
+
+  // Merge .gitignore
+  mergeGitignore(projectPath, { verbose: options.verbose });
+
+  console.log(`\n✓ ShipIt upgraded to ${installedVersion}`);
+  if (modified.length > 0) {
+    console.log(`  ${modified.length} modified file(s) backed up to ${backupDir}/`);
+  }
+}
+
+/**
+ * List backups command
+ */
+export async function listBackupsCommand(options) {
+  const projectPath = resolve(options.path || process.cwd());
+  const backupDir = options.backupDir || BACKUP_DIR;
+  const backups = listBackups(projectPath, backupDir);
+  if (backups.length === 0) {
+    console.log('No backups found.');
+    return;
+  }
+  console.log(`Backups in ${backupDir}/:\n`);
+  for (const b of backups) {
+    console.log(`  ${b.relative}  (${b.timestamp}) → ${b.original}`);
+  }
+}
+
+/**
+ * Restore from backup
+ */
+export async function restoreCommand(backupPath, options) {
+  const projectPath = resolve(options.path || process.cwd());
+  const backupDir = options.backupDir || BACKUP_DIR;
+  const fullBackupPath = backupPath.startsWith('/') ? backupPath : resolve(projectPath, backupPath);
+  if (!existsSync(fullBackupPath)) {
+    const err = new Error(`Backup not found: ${backupPath}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  restoreFromBackup(fullBackupPath, null, projectPath, backupDir, options.removeBackup || false);
+  console.log(`Restored: ${backupPath}`);
+}

package/cli/src/utils/config.js

@@ -0,0 +1,27 @@
+/**
+ * Config file utilities (.shipitrc)
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Read .shipitrc config file
+ * @param {string} projectPath - Project directory path
+ * @returns {object} Config object (empty if no config)
+ */
+export function readConfig(projectPath) {
+  const configPath = join(projectPath, '.shipitrc');
+  
+  if (!existsSync(configPath)) {
+    return {};
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    console.warn(`Warning: Invalid .shipitrc file: ${error.message}`);
+    return {};
+  }
+}

package/cli/src/utils/file-copy.js

@@ -0,0 +1,144 @@
+/**
+ * File copying utilities
+ */
+
+import fsExtra from 'fs-extra';
+import { join, dirname, relative } from 'path';
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+
+const { copySync, mkdirSync, existsSync, statSync } = fsExtra;
+
+/**
+ * Copy framework files to target directory
+ * @param {string} frameworkRoot - Framework root directory
+ * @param {string} targetDir - Target directory
+ * @param {string} stack - Tech stack (typescript-nodejs | python | other)
+ * @param {object} manifest - Framework files manifest
+ * @param {object} options - Options (verbose, dryRun)
+ * @returns {object} Summary of copied files
+ */
+export function copyFrameworkFiles(frameworkRoot, targetDir, stack, manifest, options = {}) {
+  const { verbose = false, dryRun = false } = options;
+  const copied = [];
+  const skipped = [];
+  const errors = [];
+
+  // Get stack-specific files
+  const stackSpecific = manifest.stackSpecific[stack] || { files: [], directories: [] };
+  const stackFiles = new Set(stackSpecific.files || []);
+  const stackDirs = new Set(stackSpecific.directories || []);
+
+  // Get never-copied files/directories
+  const neverCopied = new Set([
+    ...(manifest.neverCopied?.files || []),
+    ...(manifest.neverCopied?.directories || []),
+    '.override' // Always skip override directory
+  ]);
+
+  // Copy framework-owned directories
+  for (const dir of manifest.frameworkOwned.directories || []) {
+    const sourcePath = join(frameworkRoot, dir);
+    const targetPath = join(targetDir, dir);
+
+    // Skip if never copied
+    if (neverCopied.has(dir) || dir.startsWith('.override')) {
+      skipped.push(dir);
+      continue;
+    }
+
+    // Skip stack-specific directories for other stacks
+    if (stackDirs.has(dir) && stack !== 'typescript-nodejs' && stack !== 'python') {
+      skipped.push(dir);
+      continue;
+    }
+
+    if (!existsSync(sourcePath)) {
+      errors.push(`Source directory not found: ${dir}`);
+      continue;
+    }
+
+    if (!dryRun) {
+      try {
+        mkdirSync(targetPath, { recursive: true });
+        copySync(sourcePath, targetPath, { overwrite: true });
+        copied.push(dir);
+        if (verbose) {
+          console.log(`  Copied directory: ${dir}`);
+        }
+      } catch (error) {
+        errors.push(`Failed to copy ${dir}: ${error.message}`);
+      }
+    } else {
+      copied.push(dir);
+    }
+  }
+
+  // Copy framework-owned files
+  // Note: Some files like project.json are created, not copied
+  const createdFiles = new Set(['project.json']); // Files that are created, not copied from framework
+  
+  for (const file of manifest.frameworkOwned.files || []) {
+    const sourcePath = join(frameworkRoot, file);
+    const targetPath = join(targetDir, file);
+
+    // Skip if never copied
+    if (neverCopied.has(file)) {
+      skipped.push(file);
+      continue;
+    }
+
+    // Skip files that are created (not copied)
+    if (createdFiles.has(file)) {
+      skipped.push(file);
+      continue;
+    }
+
+    // Skip stack-specific files for other stacks
+    if (stackFiles.has(file) && stack !== 'typescript-nodejs' && stack !== 'python') {
+      skipped.push(file);
+      continue;
+    }
+
+    if (!existsSync(sourcePath)) {
+      // Some files may not exist in framework (like project.json which is created)
+      if (createdFiles.has(file)) {
+        skipped.push(file);
+        continue;
+      }
+      errors.push(`Source file not found: ${file}`);
+      continue;
+    }
+
+    if (!dryRun) {
+      try {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        copySync(sourcePath, targetPath, { overwrite: true });
+        copied.push(file);
+        if (verbose) {
+          console.log(`  Copied file: ${file}`);
+        }
+      } catch (error) {
+        errors.push(`Failed to copy ${file}: ${error.message}`);
+      }
+    } else {
+      copied.push(file);
+    }
+  }
+
+  return { copied, skipped, errors };
+}
+
+/**
+ * Calculate file hash (SHA-256)
+ * @param {string} filePath - Path to file
+ * @returns {string} Hex hash
+ */
+export function calculateFileHash(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  const content = readFileSync(filePath);
+  return createHash('sha256').update(content).digest('hex');
+}

package/cli/src/utils/gitignore-merge.js

@@ -0,0 +1,44 @@
+/**
+ * .gitignore merge for upgrade - append ShipIt patterns if missing
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const SHIPIT_PATTERNS = [
+  '',
+  '# ShipIt',
+  '._shipit_backup/',
+  '_system/artifacts/usage.json',
+  ''
+];
+
+/**
+ * Merge ShipIt patterns into .gitignore
+ * @param {string} projectPath - Project root
+ * @param {object} options - { dryRun, verbose }
+ * @returns {boolean} True if file was updated
+ */
+export function mergeGitignore(projectPath, options = {}) {
+  const { dryRun = false, verbose = false } = options;
+  const gitignorePath = join(projectPath, '.gitignore');
+
+  let existing = '';
+  if (existsSync(gitignorePath)) {
+    existing = readFileSync(gitignorePath, 'utf-8');
+  }
+
+  const hasBackup = existing.includes('._shipit_backup');
+  if (hasBackup) {
+    if (verbose) console.log('  .gitignore already has ShipIt patterns');
+    return false;
+  }
+
+  const toAppend = SHIPIT_PATTERNS.join('\n');
+  const newContent = existing.trimEnd() ? `${existing.trimEnd()}\n${toAppend}\n` : `${toAppend}\n`;
+
+  if (!dryRun) {
+    writeFileSync(gitignorePath, newContent, 'utf-8');
+  }
+  return true;
+}