@nlaprell/shipit 1.0.0

package/cli/src/utils/stack-files.js

@@ -0,0 +1,364 @@
+/**
+ * Stack-specific file creation utilities
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import fsExtra from 'fs-extra';
+
+const { copySync } = fsExtra;
+
+/**
+ * Create TypeScript/Node.js project files
+ * @param {string} projectPath - Project directory path
+ * @param {string} projectName - Project name
+ * @param {string} description - Project description
+ * @param {object} shipitScripts - ShipIt scripts to include
+ * @param {object} shipitDevDeps - ShipIt devDependencies to include
+ */
+export function createTypeScriptNodeFiles(projectPath, projectName, description, shipitScripts, shipitDevDeps) {
+  const normalizedName = projectName.toLowerCase().replace(/\s+/g, '-');
+
+  // Create package.json
+  const packageJson = {
+    name: normalizedName,
+    version: '0.1.0',
+    description: description,
+    type: 'module',
+    scripts: {
+      test: 'vitest run',
+      'test:watch': 'vitest',
+      'test:coverage': 'vitest run --coverage',
+      'test:mutate': 'stryker run',
+      lint: 'eslint . --ext .ts',
+      typecheck: 'tsc --noEmit',
+      build: 'tsc',
+      dev: 'tsx watch src/index.ts',
+      ...shipitScripts
+    },
+    keywords: [],
+    author: '',
+    license: 'MIT',
+    devDependencies: {
+      '@types/node': '^20.10.0',
+      '@typescript-eslint/eslint-plugin': '^6.15.0',
+      '@typescript-eslint/parser': '^6.15.0',
+      '@stryker-mutator/core': '^8.0.0',
+      '@stryker-mutator/vitest-runner': '^8.0.0',
+      '@vitest/coverage-v8': '^1.0.4',
+      eslint: '^8.56.0',
+      prettier: '^3.1.1',
+      tsx: '^4.7.0',
+      typescript: '^5.3.3',
+      vitest: '^1.0.4',
+      ...shipitDevDeps
+    },
+    dependencies: {}
+  };
+
+  writeFileSync(
+    join(projectPath, 'package.json'),
+    JSON.stringify(packageJson, null, 2) + '\n',
+    'utf-8'
+  );
+
+  // Create tsconfig.json
+  const tsconfig = {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'ESNext',
+      lib: ['ES2022'],
+      moduleResolution: 'node',
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+      resolveJsonModule: true,
+      outDir: './dist',
+      rootDir: './src',
+      declaration: true,
+      declarationMap: true,
+      sourceMap: true,
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+      noImplicitReturns: true,
+      noFallthroughCasesInSwitch: true
+    },
+    include: ['src/**/*'],
+    exclude: ['node_modules', 'dist', '**/*.test.ts', '**/*.spec.ts']
+  };
+
+  writeFileSync(
+    join(projectPath, 'tsconfig.json'),
+    JSON.stringify(tsconfig, null, 2) + '\n',
+    'utf-8'
+  );
+
+  // Create tsconfig.eslint.json
+  const tsconfigEslint = {
+    extends: './tsconfig.json',
+    include: ['src/**/*.ts', 'tests/**/*.ts', 'scripts/**/*.ts', '*.config.ts'],
+    exclude: ['node_modules', 'dist']
+  };
+
+  writeFileSync(
+    join(projectPath, 'tsconfig.eslint.json'),
+    JSON.stringify(tsconfigEslint, null, 2) + '\n',
+    'utf-8'
+  );
+
+  // Create .eslintrc.json
+  const eslintrc = {
+    root: true,
+    parser: '@typescript-eslint/parser',
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      project: ['./tsconfig.eslint.json'],
+      tsconfigRootDir: '.'
+    },
+    extends: [
+      'eslint:recommended',
+      'plugin:@typescript-eslint/recommended',
+      'plugin:@typescript-eslint/strict-type-checked'
+    ],
+    plugins: ['@typescript-eslint'],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/ban-types': 'error',
+      'no-eval': 'error',
+      'no-console': ['error', { allow: ['warn', 'error'] }]
+    },
+    overrides: [
+      {
+        files: ['scripts/**/*.ts', 'tests/**/*.ts', '**/*.config.ts'],
+        rules: {
+          'no-console': 'off',
+          '@typescript-eslint/no-unsafe-assignment': 'off',
+          '@typescript-eslint/no-unsafe-call': 'off',
+          '@typescript-eslint/no-unsafe-member-access': 'off',
+          '@typescript-eslint/no-unsafe-return': 'off',
+          '@typescript-eslint/no-unsafe-argument': 'off'
+        }
+      }
+    ],
+    ignorePatterns: ['dist', 'node_modules', '*.config.js']
+  };
+
+  writeFileSync(
+    join(projectPath, '.eslintrc.json'),
+    JSON.stringify(eslintrc, null, 2) + '\n',
+    'utf-8'
+  );
+
+  // Create vitest.config.ts
+  const vitestConfig = `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        '**/*.config.ts',
+      ],
+    },
+  },
+});
+`;
+
+  writeFileSync(join(projectPath, 'vitest.config.ts'), vitestConfig, 'utf-8');
+
+  // Create .npmrc
+  writeFileSync(join(projectPath, '.npmrc'), 'audit-level=high\n', 'utf-8');
+
+  // Create src/index.ts
+  const srcDir = join(projectPath, 'src');
+  if (!existsSync(srcDir)) {
+    mkdirSync(srcDir, { recursive: true });
+  }
+  const indexTs = `// ${projectName}
+// ${description}
+
+export const projectName = '${projectName}';
+export const projectDescription = '${description}';
+`;
+  writeFileSync(join(srcDir, 'index.ts'), indexTs, 'utf-8');
+}
+
+/**
+ * Create Python project files
+ * @param {string} projectPath - Project directory path
+ * @param {string} projectName - Project name
+ * @param {string} description - Project description
+ */
+export function createPythonFiles(projectPath, projectName, description) {
+  // Create pyproject.toml if not exists
+  const pyprojectPath = join(projectPath, 'pyproject.toml');
+  if (!existsSync(pyprojectPath)) {
+    const pyprojectContent = `[project]
+name = "${projectName}"
+description = "${description}"
+version = "0.1.0"
+requires-python = ">=3.10"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+`;
+    writeFileSync(pyprojectPath, pyprojectContent, 'utf-8');
+  }
+
+  // Create requirements.txt if not exists
+  const requirementsPath = join(projectPath, 'requirements.txt');
+  if (!existsSync(requirementsPath)) {
+    writeFileSync(requirementsPath, '# Project dependencies\n', 'utf-8');
+  }
+}
+
+/**
+ * Create Other stack project files
+ * @param {string} projectPath - Project directory path
+ */
+export function createOtherStackFiles(projectPath) {
+  // Create minimal .gitignore
+  const gitignorePath = join(projectPath, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, '*.log\n.DS_Store\n.env\n', 'utf-8');
+  }
+
+  // Create src directory
+  const srcPath = join(projectPath, 'src');
+  if (!existsSync(srcPath)) {
+    mkdirSync(srcPath, { recursive: true });
+  }
+}
+
+/**
+ * Create stack-specific CI workflow
+ * @param {string} projectPath - Project directory path
+ * @param {string} stack - Tech stack (typescript-nodejs | python | other)
+ */
+export function createCIWorkflow(projectPath, stack) {
+  const workflowsDir = join(projectPath, '.github', 'workflows');
+  if (!existsSync(workflowsDir)) {
+    mkdirSync(workflowsDir, { recursive: true });
+  }
+
+  const ciPath = join(workflowsDir, 'ci.yml');
+  
+  let ciContent = '';
+  
+  if (stack === 'typescript-nodejs') {
+    ciContent = `name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 10.11.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 10.11.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test:coverage
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        if: always()
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false
+`;
+  } else if (stack === 'python') {
+    ciContent = `name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - run: pip install -r requirements.txt
+      - run: ruff check .
+      - run: mypy .
+
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - run: pip install -r requirements.txt
+      - run: pytest --cov
+`;
+  } else {
+    // Other stack - minimal template
+    ciContent = `name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo "Add your build steps here"
+`;
+  }
+
+  writeFileSync(ciPath, ciContent, 'utf-8');
+}

package/cli/src/utils/upgrade-backup.js

@@ -0,0 +1,159 @@
+/**
+ * Upgrade backup and file-modification detection
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+import fsExtra from 'fs-extra';
+
+const { copySync, mkdirSync } = fsExtra;
+
+const BACKUP_DIR = '._shipit_backup';
+const TIMESTAMP_FORMAT = (d) => d.toISOString().replace(/[-:]/g, '').slice(0, 15); // YYYYMMDDTHHMMSS
+
+/**
+ * Calculate SHA-256 hash of file
+ * @param {string} filePath - Absolute path
+ * @returns {string|null} Hex hash or null if not found
+ */
+export function calculateFileHash(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if project file differs from framework file
+ * @param {string} projectPath - Project root
+ * @param {string} frameworkRoot - Framework root
+ * @param {string} relativeFilePath - Path relative to root (e.g. 'scripts/verify.sh')
+ * @returns {boolean} True if file is modified (different from framework)
+ */
+export function isFileModified(projectPath, frameworkRoot, relativeFilePath) {
+  const projectFile = join(projectPath, relativeFilePath);
+  const frameworkFile = join(frameworkRoot, relativeFilePath);
+  if (!existsSync(projectFile)) return false;
+  if (!existsSync(frameworkFile)) return false;
+  const projectHash = calculateFileHash(projectFile);
+  const frameworkHash = calculateFileHash(frameworkFile);
+  return projectHash !== frameworkHash;
+}
+
+/**
+ * Backup a file to ._shipit_backup/
+ * @param {string} projectPath - Project root
+ * @param {string} relativeFilePath - Path relative to project (e.g. 'scripts/verify.sh')
+ * @param {string} backupDir - Backup directory name (default ._shipit_backup)
+ * @returns {string} Path to backup file
+ */
+export function backupFile(projectPath, relativeFilePath, backupDir = BACKUP_DIR) {
+  const src = join(projectPath, relativeFilePath);
+  if (!existsSync(src)) throw new Error(`File not found: ${relativeFilePath}`);
+  const timestamp = TIMESTAMP_FORMAT(new Date());
+  const backupRelative = `${relativeFilePath}.${timestamp}`;
+  const backupFull = join(projectPath, backupDir, backupRelative);
+  const backupParent = join(backupFull, '..');
+  mkdirSync(backupParent, { recursive: true });
+  copySync(src, backupFull, { overwrite: true });
+  return backupFull;
+}
+
+/**
+ * List backups in project's backup directory
+ * @param {string} projectPath - Project root
+ * @param {string} backupDir - Backup directory name
+ * @returns {Array<{path: string, original: string, timestamp: string}>}
+ */
+export function listBackups(projectPath, backupDir = BACKUP_DIR) {
+  const dir = join(projectPath, backupDir);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  function walk(current, prefix = '') {
+    const entries = readdirSync(current, { withFileTypes: true });
+    for (const e of entries) {
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      const full = join(current, e.name);
+      if (e.isDirectory()) walk(full, rel);
+      else if (e.isFile() && /\.\d{8}T\d{6}$/.test(e.name)) {
+        const original = rel.replace(/\.\d{8}T\d{6}$/, '');
+        const timestamp = e.name.slice(-15);
+        out.push({ path: full, original: join(projectPath, original), timestamp, relative: rel });
+      }
+    }
+  }
+  walk(dir);
+  return out.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
+/**
+ * Restore a file from backup
+ * @param {string} backupFilePath - Full path to backup file
+ * @param {string|null} targetPath - Full path to restore to (if null, derived from backup path: remove backup dir and timestamp)
+ * @param {string} projectPath - Project root (required when targetPath is null)
+ * @param {string} backupDir - Backup directory name (required when targetPath is null)
+ * @param {boolean} removeBackup - Remove backup after restore
+ */
+export function restoreFromBackup(backupFilePath, targetPath, projectPath = null, backupDir = BACKUP_DIR, removeBackup = false) {
+  if (!existsSync(backupFilePath)) throw new Error(`Backup not found: ${backupFilePath}`);
+  let target = targetPath;
+  if (!target && projectPath) {
+    const backupPrefix = join(projectPath, backupDir);
+    const rel = backupFilePath.startsWith(backupPrefix)
+      ? backupFilePath.slice(backupPrefix.length + 1).replace(/\.\d{8}T\d{6}$/, '')
+      : backupFilePath.replace(/\.\d{8}T\d{6}$/, '');
+    target = join(projectPath, rel);
+  } else if (!target) {
+    target = backupFilePath.replace(/\.\d{8}T\d{6}$/, '');
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  copySync(backupFilePath, target, { overwrite: true });
+  if (removeBackup) fsExtra.removeSync(backupFilePath);
+}
+
+/**
+ * Collect all framework-owned file paths (relative) for upgrade
+ * @param {string} frameworkRoot - Framework root
+ * @param {object} manifest - Parsed framework-files-manifest
+ * @param {Set<string>} neverCopied - Set of paths to skip
+ * @returns {string[]} Relative file paths
+ */
+export function getFrameworkFileList(frameworkRoot, manifest, neverCopied) {
+  const files = new Set();
+
+  function addFile(rel) {
+    if (neverCopied.has(rel) || rel.startsWith('.override')) return;
+    const full = join(frameworkRoot, rel);
+    if (existsSync(full) && statSync(full).isFile()) files.add(rel);
+  }
+
+  for (const dir of manifest.frameworkOwned?.directories || []) {
+    const fullDir = join(frameworkRoot, dir);
+    if (!existsSync(fullDir)) continue;
+    walkDir(fullDir, dir, (rel) => addFile(rel));
+  }
+  for (const file of manifest.frameworkOwned?.files || []) {
+    if (file === 'project.json') continue; // merged, not replaced
+    addFile(file);
+  }
+
+  return [...files];
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.turbo']);
+
+function walkDir(fullDir, prefix, add) {
+  const entries = readdirSync(fullDir, { withFileTypes: true });
+  for (const e of entries) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    const full = join(fullDir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      walkDir(full, rel, add);
+    } else if (e.isFile()) add(rel);
+  }
+}

package/cli/src/utils/version.js

@@ -0,0 +1,64 @@
+/**
+ * Version detection and comparison for ShipIt upgrade
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { getFrameworkRoot } from './manifest.js';
+
+/**
+ * Get installed ShipIt version from package
+ * @returns {string} Version string (e.g. "1.0.0")
+ */
+export function getInstalledShipItVersion() {
+  const root = getFrameworkRoot();
+  const pkgPath = join(root, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error('ShipIt not found. Install: npm install -g @nlaprell/shipit');
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  return pkg.version || '0.0.0';
+}
+
+/**
+ * Get project's ShipIt version from project.json
+ * @param {string} projectPath - Project root path
+ * @returns {string|null} Version or null if missing
+ */
+export function getProjectShipItVersion(projectPath) {
+  const projectJsonPath = join(projectPath, 'project.json');
+  if (!existsSync(projectJsonPath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(projectJsonPath, 'utf-8'));
+    return data.shipitVersion ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare two semver strings
+ * @param {string} installed - Installed version
+ * @param {string} project - Project version
+ * @returns {'same'|'newer'|'older'|'unknown'} Comparison result
+ */
+export function compareVersions(installed, project) {
+  if (!installed || !project) return 'unknown';
+  const a = parseVersion(installed);
+  const b = parseVersion(project);
+  if (!a || !b) return 'unknown';
+  if (a.major !== b.major) return a.major > b.major ? 'newer' : 'older';
+  if (a.minor !== b.minor) return a.minor > b.minor ? 'newer' : 'older';
+  if (a.patch !== b.patch) return a.patch > b.patch ? 'newer' : 'older';
+  return 'same';
+}
+
+function parseVersion(v) {
+  const match = String(v).match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10)
+  };
+}

package/dashboard-app/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+]);
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x';
+import reactDom from 'eslint-plugin-react-dom';
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+]);
+```

package/dashboard-app/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/dashboard-app/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ShipIt Dashboard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>