@fgv/repo-template 5.1.0-2

package/src/commands/init-library.ts

@@ -0,0 +1,249 @@
+/**
+ * init-library command — scaffolds a new library package within an existing Rush monorepo.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { patchFile, IPatchOperation } from '../packlets/jsonc';
+
+export type RigType = 'dual' | 'node' | 'browser';
+export type CategoryType = 'libraries' | 'tools' | 'apps' | 'services';
+
+export interface IInitLibraryOptions {
+  /** Package name (e.g. "ts-my-lib" — will be prefixed with @fgv/) */
+  name: string;
+  /** Short description */
+  description: string;
+  /** Heft rig to use */
+  rig: RigType;
+  /** Category folder */
+  category: CategoryType;
+  /** Rush monorepo root */
+  repoDir: string;
+  /** Version policy name (from version-policies.json) */
+  versionPolicy: string;
+  /** Initial version */
+  version: string;
+  /** Dependency version for @fgv/* packages ("workspace:*" for fgv, "^5.1.0-0" for consumers) */
+  fgvDepVersion: string;
+}
+
+interface IRigConfig {
+  rigPackageName: string;
+  rigProfile?: string;
+  rigDevDeps: Record<string, string>;
+  tsconfigExtends: string;
+  tsconfigTypes: string[];
+  tsconfigLib?: string[];
+}
+
+const RIG_CONFIGS: Record<RigType, IRigConfig> = {
+  dual: {
+    rigPackageName: '@fgv/heft-dual-rig',
+    rigDevDeps: {
+      '@fgv/heft-dual-rig': 'FGV_DEP',
+      '@rushstack/heft': '1.2.7',
+      '@rushstack/heft-node-rig': '2.11.27'
+    },
+    tsconfigExtends: './node_modules/@rushstack/heft-node-rig/profiles/default/tsconfig-base.json',
+    tsconfigTypes: ['heft-jest', 'node'],
+    tsconfigLib: ['es2018']
+  },
+  node: {
+    rigPackageName: '@rushstack/heft-node-rig',
+    rigDevDeps: {
+      '@rushstack/heft': '1.2.7',
+      '@rushstack/heft-node-rig': '2.11.27'
+    },
+    tsconfigExtends: './node_modules/@rushstack/heft-node-rig/profiles/default/tsconfig-base.json',
+    tsconfigTypes: ['heft-jest', 'node']
+  },
+  browser: {
+    rigPackageName: '@rushstack/heft-web-rig',
+    rigProfile: 'library',
+    rigDevDeps: {
+      '@rushstack/heft': '1.2.7',
+      '@rushstack/heft-web-rig': '1.4.3'
+    },
+    tsconfigExtends: './node_modules/@rushstack/heft-web-rig/profiles/library/tsconfig-base.json',
+    tsconfigTypes: ['heft-jest', 'node'],
+    tsconfigLib: ['es2018', 'DOM']
+  }
+};
+
+export async function runInitLibrary(options: IInitLibraryOptions): Promise<void> {
+  const { name, description, rig, category, repoDir, versionPolicy, version, fgvDepVersion } = options;
+
+  const packageName = name.startsWith('@fgv/') ? name : `@fgv/${name}`;
+  const shortName = packageName.replace('@fgv/', '');
+  const projectFolder = `${category}/${shortName}`;
+  const projectDir = path.join(repoDir, projectFolder);
+
+  if (fs.existsSync(projectDir)) {
+    throw new Error(`Project directory already exists: ${projectDir}`);
+  }
+
+  const rushJsonPath = path.join(repoDir, 'rush.json');
+  if (!fs.existsSync(rushJsonPath)) {
+    throw new Error(`Not a Rush repo (no rush.json): ${repoDir}`);
+  }
+
+  const rigConfig = RIG_CONFIGS[rig];
+
+  console.log(`Initializing library: ${packageName}`);
+  console.log(`  Directory: ${projectFolder}`);
+  console.log(`  Rig:       ${rig} (${rigConfig.rigPackageName})`);
+  console.log(`  Version:   ${versionPolicy}@${version}`);
+  console.log('');
+
+  // ── Create directory structure ──
+  fs.mkdirSync(path.join(projectDir, 'src', 'test', 'unit'), { recursive: true });
+  fs.mkdirSync(path.join(projectDir, 'config'), { recursive: true });
+
+  // ── package.json ──
+  console.log('==> Creating package.json...');
+
+  const devDependencies: Record<string, string> = {};
+  // Add rig dependencies — @fgv/* packages use fgvDepVersion, others use their pinned version
+  for (const [dep, ver] of Object.entries(rigConfig.rigDevDeps)) {
+    devDependencies[dep] = dep.startsWith('@fgv/') ? fgvDepVersion : ver;
+  }
+  // Standard dev dependencies
+  devDependencies['@fgv/ts-utils-jest'] = fgvDepVersion;
+  devDependencies['@types/heft-jest'] = '1.0.6';
+  devDependencies['@types/jest'] = '^29.5.14';
+  devDependencies['@types/node'] = '^20.14.9';
+  devDependencies['typescript'] = '5.9.3';
+  devDependencies['@rushstack/eslint-config'] = '4.6.4';
+  devDependencies['eslint'] = '^9.39.2';
+
+  const packageJson: Record<string, unknown> = {
+    name: packageName,
+    version,
+    description,
+    main: 'lib/index.js',
+    types: 'lib/index.d.ts',
+    scripts: {
+      build: 'heft build --clean',
+      clean: 'heft clean',
+      test: 'heft test --clean',
+      coverage: 'jest --coverage',
+      lint: 'eslint src --ext .ts',
+      fixlint: 'eslint src --ext .ts --fix'
+    },
+    author: '',
+    license: 'MIT',
+    dependencies: {
+      '@fgv/ts-utils': fgvDepVersion,
+      '@fgv/ts-json-base': fgvDepVersion
+    },
+    devDependencies,
+    repository: {
+      type: 'git',
+      url: ''
+    }
+  };
+
+  // Add dual-emit exports for dual rig
+  if (rig === 'dual') {
+    packageJson['module'] = 'dist/index.js';
+    packageJson['exports'] = {
+      '.': {
+        types: './lib/index.d.ts',
+        import: './dist/index.js',
+        require: './lib/index.js',
+        default: './lib/index.js'
+      }
+    };
+  }
+
+  fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\n');
+
+  // ── tsconfig.json ──
+  console.log('  Creating tsconfig.json...');
+
+  const tsconfig: Record<string, unknown> = {
+    extends: rigConfig.tsconfigExtends,
+    compilerOptions: {
+      types: rigConfig.tsconfigTypes,
+      ...(rigConfig.tsconfigLib ? { lib: rigConfig.tsconfigLib } : {})
+    }
+  };
+
+  fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2) + '\n');
+
+  // ── config/rig.json ──
+  console.log('  Creating config/rig.json...');
+
+  const rigJson: Record<string, unknown> = {
+    $schema: 'https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json',
+    rigPackageName: rigConfig.rigPackageName
+  };
+  if (rigConfig.rigProfile) {
+    rigJson['rigProfile'] = rigConfig.rigProfile;
+  }
+
+  fs.writeFileSync(path.join(projectDir, 'config', 'rig.json'), JSON.stringify(rigJson, null, 2) + '\n');
+
+  // ── config/jest.config.json ──
+  console.log('  Creating config/jest.config.json...');
+
+  const jestConfig = {
+    extends: '@rushstack/heft-node-rig/profiles/default/config/jest.config.json',
+    coverageThreshold: {
+      global: {
+        branches: 100,
+        functions: 100,
+        lines: 100,
+        statements: 100
+      }
+    },
+    collectCoverage: true,
+    coverageReporters: ['text', 'lcov', 'html']
+  };
+
+  fs.writeFileSync(
+    path.join(projectDir, 'config', 'jest.config.json'),
+    JSON.stringify(jestConfig, null, 2) + '\n'
+  );
+
+  // ── src/index.ts ──
+  console.log('  Creating src/index.ts...');
+
+  fs.writeFileSync(
+    path.join(projectDir, 'src', 'index.ts'),
+    `/**\n * @packageDocumentation\n * ${description}\n */\n`
+  );
+
+  // ── Register in rush.json ──
+  console.log('');
+  console.log('==> Registering in rush.json...');
+
+  const rushJsonOps: IPatchOperation[] = [
+    {
+      type: 'add-to-array',
+      path: 'projects',
+      value: JSON.stringify({
+        packageName,
+        projectFolder,
+        shouldPublish: true,
+        versionPolicyName: versionPolicy,
+        tags: [category]
+      })
+    }
+  ];
+
+  patchFile(rushJsonPath, rushJsonOps);
+  console.log(`  Added ${packageName} at ${projectFolder}`);
+
+  // ── Done ──
+  console.log('');
+  console.log(`=== Library ${packageName} initialized at ${projectFolder} ===`);
+  console.log('');
+  console.log('Next steps:');
+  console.log(`  1. cd ${projectDir}`);
+  console.log('  2. rush update');
+  console.log('  3. rushx build');
+  console.log('  4. Start adding code to src/');
+  console.log('');
+}

package/src/commands/patch.ts

@@ -0,0 +1,84 @@
+/**
+ * Patch command — apply targeted edits to JSONC config files.
+ */
+
+import * as fs from 'fs';
+import { IPatchOperation, PatchOperationType, applyOperations, parseValue } from '../packlets/jsonc';
+
+export interface IPatchOptions {
+  file: string;
+  operations: IPatchOperation[];
+}
+
+/**
+ * Parse CLI arguments for the patch command into operations.
+ * Expects pairs like: --set 'path=value', --uncomment 'path', etc.
+ */
+export function parsePatchArgs(args: string[]): IPatchOperation[] {
+  const operations: IPatchOperation[] = [];
+  const validOps: PatchOperationType[] = ['set', 'set-json', 'uncomment', 'add-to-array', 'remove'];
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+
+    const opType = arg.slice(2) as PatchOperationType;
+    if (!validOps.includes(opType)) {
+      throw new Error(`Unknown operation: ${arg}`);
+    }
+
+    i++;
+    if (i >= args.length) {
+      throw new Error(`Missing value for ${arg}`);
+    }
+
+    const operand = args[i];
+    i++;
+
+    if (opType === 'uncomment' || opType === 'remove') {
+      operations.push({ type: opType, path: operand });
+    } else {
+      const eqIndex = operand.indexOf('=');
+      if (eqIndex === -1) {
+        throw new Error(`Expected path=value for ${arg}, got: ${operand}`);
+      }
+      const opPath = operand.slice(0, eqIndex);
+      const rawValue = operand.slice(eqIndex + 1);
+
+      if (opType === 'set') {
+        operations.push({ type: opType, path: opPath, value: parseValue(rawValue) });
+      } else {
+        // set-json and add-to-array pass raw JSON string
+        operations.push({ type: opType, path: opPath, value: rawValue });
+      }
+    }
+  }
+
+  return operations;
+}
+
+export async function runPatch(options: IPatchOptions): Promise<void> {
+  const { file, operations } = options;
+
+  if (!fs.existsSync(file)) {
+    throw new Error(`File not found: ${file}`);
+  }
+
+  console.log(`Patching: ${file}`);
+  let source = fs.readFileSync(file, 'utf-8');
+
+  for (const op of operations) {
+    const desc =
+      op.type === 'uncomment' || op.type === 'remove'
+        ? `  ${op.type}: ${op.path}`
+        : `  ${op.type}: ${op.path} = ${op.value}`;
+    console.log(desc);
+  }
+
+  source = applyOperations(source, operations);
+  fs.writeFileSync(file, source);
+  console.log(`  Done: ${operations.length} operation(s) applied`);
+}

package/src/commands/sync.ts

@@ -0,0 +1,137 @@
+/**
+ * Sync command — updates shared files in a consumer repo from the template source.
+ * Templated files are NOT touched — they are owned by the consumer after creation.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadManifest, getDefaultManifestPath } from '../packlets/manifest';
+import { copyFile, copyPackage, filesAreEqual, getGitCommit } from '../packlets/fs';
+
+export interface ISyncOptions {
+  targetDir: string;
+  sourceDir: string;
+  dryRun: boolean;
+}
+
+export async function runSync(options: ISyncOptions): Promise<void> {
+  const { targetDir, sourceDir, dryRun } = options;
+
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`Target directory does not exist: ${targetDir}`);
+  }
+  if (!fs.existsSync(path.join(sourceDir, 'rush.json'))) {
+    throw new Error(`Source directory is not a Rush repo: ${sourceDir}`);
+  }
+
+  const manifestPath = getDefaultManifestPath();
+  const manifest = loadManifest(manifestPath);
+
+  console.log('Syncing shared files');
+  console.log(`  Source: ${sourceDir}`);
+  console.log(`  Target: ${targetDir}`);
+  if (dryRun) {
+    console.log('  Mode:   DRY RUN (no changes will be made)');
+  }
+  console.log('');
+
+  let copied = 0;
+  let skipped = 0;
+  let warnings = 0;
+
+  // ── Sync individual shared files ──
+  console.log('==> Syncing shared files...');
+
+  for (const file of manifest.shared.files) {
+    const srcPath = path.join(sourceDir, file.source);
+    const dstPath = path.join(targetDir, file.destination);
+
+    if (!fs.existsSync(srcPath)) {
+      console.log(`  WARNING: Source not found: ${file.source}`);
+      warnings++;
+      continue;
+    }
+
+    if (dryRun) {
+      if (fs.existsSync(dstPath) && filesAreEqual(srcPath, dstPath)) {
+        console.log(`  [unchanged] ${file.destination}`);
+        skipped++;
+      } else if (fs.existsSync(dstPath)) {
+        console.log(`  [would update] ${file.destination}`);
+        copied++;
+      } else {
+        console.log(`  [would create] ${file.destination}`);
+        copied++;
+      }
+    } else {
+      if (fs.existsSync(dstPath) && filesAreEqual(srcPath, dstPath)) {
+        skipped++;
+      } else {
+        copyFile(srcPath, dstPath);
+        console.log(`  Updated: ${file.destination}`);
+        copied++;
+      }
+    }
+  }
+
+  // ── Sync shared packages ──
+  console.log('');
+  console.log('==> Syncing shared packages...');
+
+  for (const pkg of manifest.sharedPackages.packages) {
+    const srcPath = path.join(sourceDir, pkg.source);
+    const dstPath = path.join(targetDir, pkg.destination);
+
+    if (!fs.existsSync(srcPath)) {
+      console.log(`  WARNING: Source directory not found: ${pkg.source}`);
+      warnings++;
+      continue;
+    }
+
+    if (dryRun) {
+      console.log(`  [would sync] ${pkg.destination}/`);
+      copied++;
+    } else {
+      copyPackage(srcPath, dstPath);
+      console.log(`  Synced package: ${pkg.destination}`);
+      copied++;
+    }
+  }
+
+  // ── Update sync metadata ──
+  if (!dryRun) {
+    const syncFilePath = path.join(targetDir, '.template-sync');
+    if (fs.existsSync(syncFilePath)) {
+      try {
+        const syncData = JSON.parse(fs.readFileSync(syncFilePath, 'utf-8'));
+        syncData.lastSyncedAt = new Date().toISOString();
+        syncData.sourceCommit = getGitCommit(sourceDir);
+        fs.writeFileSync(syncFilePath, JSON.stringify(syncData, null, 2) + '\n');
+        console.log('');
+        console.log('  Updated .template-sync');
+      } catch {
+        console.log('  WARNING: Could not update .template-sync');
+      }
+    }
+  }
+
+  // ── Summary ──
+  console.log('');
+  console.log('=== Sync complete ===');
+  console.log(`  Updated:   ${copied}`);
+  console.log(`  Unchanged: ${skipped}`);
+  console.log(`  Warnings:  ${warnings}`);
+
+  if (dryRun) {
+    console.log('');
+    console.log('This was a dry run. No files were modified.');
+    console.log('Run without --dry-run to apply changes.');
+  }
+
+  if (!dryRun && copied > 0) {
+    console.log('');
+    console.log('Next steps:');
+    console.log(`  1. Review changes: cd ${targetDir} && git diff`);
+    console.log("  2. Commit: git add -A && git commit -m 'Sync shared files from template'");
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @fgv/repo-template — CLI tool for creating and maintaining fgv-derived Rush monorepos.
+ *
+ * @packageDocumentation
+ */
+
+export { RepoTemplateCli } from './cli';
+export { runCreate, ICreateOptions } from './commands/create';
+export { runSync, ISyncOptions } from './commands/sync';
+export { runPatch, IPatchOptions, parsePatchArgs } from './commands/patch';
+export { runInitLibrary, IInitLibraryOptions, RigType, CategoryType } from './commands/init-library';
+export { applyOperations, applyOperation, patchFile, IPatchOperation } from './packlets/jsonc';
+export { loadManifest, IManifest, ISharedFile, ISharedPackage, ITemplatedFile } from './packlets/manifest';
+export { renderTemplate, renderTemplateFile, ITemplateVars } from './packlets/template';

package/src/packlets/fs/index.ts

@@ -0,0 +1,114 @@
+/**
+ * File system and shell execution helpers.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync, ExecSyncOptions } from 'child_process';
+
+/**
+ * Directories to exclude when copying shared packages.
+ */
+const EXCLUDED_DIRS = new Set(['node_modules', 'lib', 'dist', '.heft', 'temp', 'coverage', 'rush-logs']);
+
+/**
+ * Copy a single file, creating parent directories as needed.
+ */
+export function copyFile(src: string, dest: string): void {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+/**
+ * Copy a directory recursively, excluding build artifacts.
+ */
+export function copyPackage(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  fs.cpSync(src, dest, {
+    recursive: true,
+    filter: (source: string) => {
+      const basename = path.basename(source);
+      return !EXCLUDED_DIRS.has(basename);
+    }
+  });
+}
+
+/**
+ * Compare two files for equality.
+ * Returns true if files are identical.
+ */
+export function filesAreEqual(pathA: string, pathB: string): boolean {
+  if (!fs.existsSync(pathA) || !fs.existsSync(pathB)) {
+    return false;
+  }
+  const a = fs.readFileSync(pathA);
+  const b = fs.readFileSync(pathB);
+  return Buffer.compare(a, b) === 0;
+}
+
+/**
+ * Execute a shell command, returning stdout.
+ */
+export function exec(command: string, options?: ExecSyncOptions): string {
+  const result = execSync(command, {
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    ...options
+  });
+  return (result as string).trim();
+}
+
+/**
+ * Execute a shell command, inheriting stdio (output goes to terminal).
+ */
+export function execInherit(command: string, options?: ExecSyncOptions): void {
+  execSync(command, {
+    stdio: 'inherit',
+    ...options
+  });
+}
+
+/**
+ * Try to get the current git commit hash from a directory.
+ * Returns empty string if not a git repo or git is not available.
+ */
+export function getGitCommit(dir: string): string {
+  try {
+    return exec('git rev-parse HEAD', { cwd: dir });
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Try to get the git remote URL from a directory.
+ */
+export function getGitRemoteUrl(dir: string): string {
+  try {
+    return exec('git remote get-url origin', { cwd: dir });
+  } catch {
+    return 'local';
+  }
+}
+
+/**
+ * Auto-detect the fgv source repository root by walking up from a starting directory,
+ * looking for a rush.json that belongs to the fgv repo.
+ */
+export function detectSourceDir(startDir: string): string | undefined {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    const rushJsonPath = path.join(dir, 'rush.json');
+    if (fs.existsSync(rushJsonPath)) {
+      // Verify it looks like the fgv repo by checking for the template tool
+      const manifestPath = path.join(dir, 'tools', 'repo-template', 'sync-manifest.json');
+      if (fs.existsSync(manifestPath)) {
+        return dir;
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}