@fgv/repo-template 5.1.0-10

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,22 @@
+/**
+ * @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 {
+  runLink,
+  runUnlink,
+  runUpdateFgvVersions,
+  ILinkOptions,
+  IUnlinkOptions,
+  IUpdateFgvVersionsOptions
+} from './commands/link';
+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;
+}

package/src/packlets/jsonc/index.ts

@@ -0,0 +1,134 @@
+/**
+ * JSONC patching operations using jsonc-parser.
+ * Modifies JSON-with-comments files while preserving all comments and formatting.
+ */
+
+import { modify, applyEdits } from 'jsonc-parser';
+
+const FORMATTING_OPTIONS = {
+  tabSize: 2,
+  insertSpaces: true,
+  eol: '\n'
+};
+
+export type PatchOperationType = 'set' | 'set-json' | 'uncomment' | 'add-to-array' | 'remove';
+
+export interface IPatchOperation {
+  type: PatchOperationType;
+  path: string;
+  value?: unknown;
+}
+
+/**
+ * Parse a dot-separated path into a JSON path array.
+ * Numeric segments are treated as array indices.
+ */
+function parsePath(pathStr: string): (string | number)[] {
+  return pathStr.split('.').map((seg) => {
+    const num = Number(seg);
+    return Number.isInteger(num) && num >= 0 ? num : seg;
+  });
+}
+
+/**
+ * Parse a value string into a JS value.
+ */
+export function parseValue(valueStr: string): unknown {
+  if (valueStr === 'true') return true;
+  if (valueStr === 'false') return false;
+  if (valueStr === 'null') return null;
+  const num = Number(valueStr);
+  if (!isNaN(num) && valueStr.trim() !== '') return num;
+  // Strip surrounding quotes if present
+  if (
+    (valueStr.startsWith('"') && valueStr.endsWith('"')) ||
+    (valueStr.startsWith("'") && valueStr.endsWith("'"))
+  ) {
+    return valueStr.slice(1, -1);
+  }
+  return valueStr;
+}
+
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Uncomment a commented-out JSON property in a JSONC string.
+ * Handles `// "propertyName": value` patterns.
+ */
+function uncommentProperty(source: string, propertyName: string): string {
+  const pattern = new RegExp(`^(\\s*)\\/\\/\\s*("${escapeRegExp(propertyName)}"\\s*:.*)$`, 'm');
+
+  const match = source.match(pattern);
+  if (!match) {
+    console.warn(`  Warning: Could not find commented-out property "${propertyName}" to uncomment`);
+    return source;
+  }
+
+  const indent = match[1];
+  const content = match[2];
+  return source.replace(match[0], `${indent}${content}`);
+}
+
+/**
+ * Apply a single patch operation to a JSONC source string.
+ */
+export function applyOperation(source: string, op: IPatchOperation): string {
+  switch (op.type) {
+    case 'set': {
+      const jsonPath = parsePath(op.path);
+      const edits = modify(source, jsonPath, op.value, { formattingOptions: FORMATTING_OPTIONS });
+      return applyEdits(source, edits);
+    }
+    case 'set-json': {
+      const jsonPath = parsePath(op.path);
+      const value = JSON.parse(op.value as string);
+      const edits = modify(source, jsonPath, value, { formattingOptions: FORMATTING_OPTIONS });
+      return applyEdits(source, edits);
+    }
+    case 'uncomment': {
+      // Use the leaf property name for the regex, since nested properties
+      // appear as just their leaf name in the file.
+      const leafName = op.path.split('.').pop()!;
+      return uncommentProperty(source, leafName);
+    }
+    case 'add-to-array': {
+      const jsonPath = parsePath(op.path);
+      const value = JSON.parse(op.value as string);
+      const edits = modify(source, [...jsonPath, -1], value, {
+        formattingOptions: FORMATTING_OPTIONS,
+        isArrayInsertion: true
+      });
+      return applyEdits(source, edits);
+    }
+    case 'remove': {
+      const jsonPath = parsePath(op.path);
+      const edits = modify(source, jsonPath, undefined, { formattingOptions: FORMATTING_OPTIONS });
+      return applyEdits(source, edits);
+    }
+    default:
+      throw new Error(`Unknown operation type: ${(op as IPatchOperation).type}`);
+  }
+}
+
+/**
+ * Apply a sequence of patch operations to a JSONC source string.
+ */
+export function applyOperations(source: string, operations: IPatchOperation[]): string {
+  let result = source;
+  for (const op of operations) {
+    result = applyOperation(result, op);
+  }
+  return result;
+}
+
+/**
+ * Read a JSONC file, apply patch operations, and write it back.
+ */
+export function patchFile(filePath: string, operations: IPatchOperation[]): void {
+  const fs = require('fs');
+  let source = fs.readFileSync(filePath, 'utf-8');
+  source = applyOperations(source, operations);
+  fs.writeFileSync(filePath, source);
+}

package/src/packlets/manifest/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Manifest loader — reads and parses sync-manifest.json.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { IManifest } from './types';
+
+export { IManifest, ISharedFile, ISharedPackage, ITemplatedFile } from './types';
+
+/**
+ * Load and parse a sync-manifest.json file.
+ */
+export function loadManifest(manifestPath: string): IManifest {
+  const content = fs.readFileSync(manifestPath, 'utf-8');
+  return JSON.parse(content) as IManifest;
+}
+
+/**
+ * Resolve the default manifest path relative to this tool's location.
+ * Works whether running from source (src/) or compiled (lib/).
+ */
+export function getDefaultManifestPath(): string {
+  // Walk up from this file to the tool root, then find sync-manifest.json
+  // In compiled form: lib/packlets/manifest/index.js → ../../.. → tool root
+  // In source form: src/packlets/manifest/index.ts → ../../.. → tool root
+  const toolRoot = path.resolve(__dirname, '..', '..', '..');
+  return path.join(toolRoot, 'sync-manifest.json');
+}

package/src/packlets/manifest/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for the sync-manifest.json file.
+ */
+
+export interface ISharedFile {
+  description: string;
+  source: string;
+  destination: string;
+}
+
+export interface ISharedPackage {
+  description: string;
+  source: string;
+  destination: string;
+}
+
+export interface ITemplatedFile {
+  description: string;
+  template: string;
+  destination: string;
+}
+
+export interface IManifest {
+  shared: {
+    description: string;
+    files: ISharedFile[];
+  };
+  sharedPackages: {
+    description: string;
+    packages: ISharedPackage[];
+  };
+  templated: {
+    description: string;
+    files: ITemplatedFile[];
+  };
+}

package/src/packlets/template/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Template rendering — simple variable substitution for .tmpl files.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface ITemplateVars {
+  REPO_URL: string;
+  VERSION_POLICY_NAME: string;
+  VERSION: string;
+  [key: string]: string;
+}
+
+/**
+ * Render a template string by replacing `{{VAR_NAME}}` placeholders.
+ */
+export function renderTemplate(template: string, vars: ITemplateVars): string {
+  let result = template;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+  }
+  return result;
+}
+
+/**
+ * Read a template file, render it with variables, and write to destination.
+ */
+export function renderTemplateFile(templatePath: string, destPath: string, vars: ITemplateVars): void {
+  if (!fs.existsSync(templatePath)) {
+    console.warn(`  WARNING: Template not found, skipping: ${templatePath}`);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  const template = fs.readFileSync(templatePath, 'utf-8');
+  const rendered = renderTemplate(template, vars);
+  fs.writeFileSync(destPath, rendered);
+  console.log(`  Generated: ${destPath}`);
+}
+
+/**
+ * Resolve the default templates directory relative to this tool's location.
+ */
+export function getDefaultTemplatesDir(): string {
+  const toolRoot = path.resolve(__dirname, '..', '..', '..');
+  return path.join(toolRoot, 'templates');
+}