@fgv/repo-template 5.1.0-2

package/lib/packlets/template/index.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Template rendering — simple variable substitution for .tmpl files.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = renderTemplate;
+exports.renderTemplateFile = renderTemplateFile;
+exports.getDefaultTemplatesDir = getDefaultTemplatesDir;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Render a template string by replacing `{{VAR_NAME}}` placeholders.
+ */
+function renderTemplate(template, vars) {
+    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.
+ */
+function renderTemplateFile(templatePath, destPath, vars) {
+    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.
+ */
+function getDefaultTemplatesDir() {
+    const toolRoot = path.resolve(__dirname, '..', '..', '..');
+    return path.join(toolRoot, 'templates');
+}
+//# sourceMappingURL=index.js.map

package/lib/packlets/template/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/template/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeH,wCAMC;AAKD,gDAWC;AAKD,wDAGC;AA3CD,uCAAyB;AACzB,2CAA6B;AAS7B;;GAEG;AACH,SAAgB,cAAc,CAAC,QAAgB,EAAE,IAAmB;IAClE,IAAI,MAAM,GAAG,QAAQ,CAAC;IACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,SAAS,GAAG,QAAQ,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAAC,YAAoB,EAAE,QAAgB,EAAE,IAAmB;IAC5F,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,IAAI,CAAC,4CAA4C,YAAY,EAAE,CAAC,CAAC;QACzE,OAAO;IACT,CAAC;IAED,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAChD,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACrC,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAC1C,CAAC","sourcesContent":["/**\n * Template rendering — simple variable substitution for .tmpl files.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nexport interface ITemplateVars {\n  REPO_URL: string;\n  VERSION_POLICY_NAME: string;\n  VERSION: string;\n  [key: string]: string;\n}\n\n/**\n * Render a template string by replacing `{{VAR_NAME}}` placeholders.\n */\nexport function renderTemplate(template: string, vars: ITemplateVars): string {\n  let result = template;\n  for (const [key, value] of Object.entries(vars)) {\n    result = result.replace(new RegExp(`\\\\{\\\\{${key}\\\\}\\\\}`, 'g'), value);\n  }\n  return result;\n}\n\n/**\n * Read a template file, render it with variables, and write to destination.\n */\nexport function renderTemplateFile(templatePath: string, destPath: string, vars: ITemplateVars): void {\n  if (!fs.existsSync(templatePath)) {\n    console.warn(`  WARNING: Template not found, skipping: ${templatePath}`);\n    return;\n  }\n\n  fs.mkdirSync(path.dirname(destPath), { recursive: true });\n  const template = fs.readFileSync(templatePath, 'utf-8');\n  const rendered = renderTemplate(template, vars);\n  fs.writeFileSync(destPath, rendered);\n  console.log(`  Generated: ${destPath}`);\n}\n\n/**\n * Resolve the default templates directory relative to this tool's location.\n */\nexport function getDefaultTemplatesDir(): string {\n  const toolRoot = path.resolve(__dirname, '..', '..', '..');\n  return path.join(toolRoot, 'templates');\n}\n"]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fgv/repo-template",
+  "version": "5.1.0-2",
+  "description": "CLI tool for creating and maintaining fgv-derived Rush monorepos",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "bin": {
+    "repo-template": "bin/repo-template.js"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "test": "heft test --clean",
+    "coverage": "heft test --clean --coverage",
+    "clean": "heft clean",
+    "lint": "eslint src --ext .ts",
+    "fixlint": "eslint src --ext .ts --fix"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "jsonc-parser": "~3.3.1"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "1.2.7",
+    "@rushstack/heft-node-rig": "2.11.27",
+    "@types/node": "^20.14.9",
+    "typescript": "5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ErikFortune/fgv.git"
+  }
+}

package/rush-logs/repo-template.build.cache.log

@@ -0,0 +1,4 @@
+This project was not found in the build cache.
+Caching build output folders: lib, temp, .rush/temp/operation/build
+Successfully set cache entry.
+Cache key: 92e27a75687fa5062b71fdb897f0928a8aa4e0c9

package/rush-logs/repo-template.build.log

@@ -0,0 +1,7 @@
+Invoking: heft build --clean 
+ ---- build started ---- 
+[build:clean] Deleted 0 files and 2 folders
+[build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
+[build:typescript] Using TypeScript version 5.9.3
+ ---- build finished (0.796s) ---- 
+-------------------- Finished (0.797s) --------------------

package/src/cli.ts

@@ -0,0 +1,141 @@
+/**
+ * CLI entry point — sets up commander with create, sync, and patch subcommands.
+ */
+
+import { Command } from 'commander';
+import { detectSourceDir } from './packlets/fs';
+import { runCreate } from './commands/create';
+import { runSync } from './commands/sync';
+import { runPatch, parsePatchArgs } from './commands/patch';
+import { runInitLibrary, RigType, CategoryType } from './commands/init-library';
+
+export class RepoTemplateCli {
+  private readonly _program: Command;
+
+  public constructor() {
+    this._program = new Command();
+    this._setupCommands();
+  }
+
+  public async run(argv: string[]): Promise<void> {
+    await this._program.parseAsync(argv);
+  }
+
+  private _setupCommands(): void {
+    this._program
+      .name('repo-template')
+      .description('Create and maintain fgv-derived Rush monorepos')
+      .version('5.1.0');
+
+    // ── create ──
+    this._program
+      .command('create')
+      .description('Stamp out a new fgv-derived Rush monorepo using rush init + JSONC patching')
+      .requiredOption('-t, --target-dir <path>', 'Directory to create the new repo in')
+      .requiredOption('-u, --repo-url <url>', 'GitHub repository URL')
+      .option('-p, --version-policy <name>', 'Version policy name', 'default')
+      .option('--initial-version <ver>', 'Initial version', '0.1.0')
+      .option('-s, --source-dir <path>', 'Source repo for shared files (auto-detected if in fgv repo)')
+      .option('--allow-existing', 'Allow target directory to already exist', false)
+      .option('--no-git-init', 'Skip git init and initial commit')
+      .action(async (opts) => {
+        const sourceDir = opts.sourceDir ?? this._resolveSourceDir();
+        await runCreate({
+          targetDir: opts.targetDir,
+          repoUrl: opts.repoUrl,
+          versionPolicy: opts.versionPolicy,
+          version: opts.initialVersion,
+          sourceDir,
+          allowExisting: opts.allowExisting,
+          gitInit: opts.gitInit
+        });
+      });
+
+    // ── sync ──
+    this._program
+      .command('sync')
+      .description('Sync shared files from the fgv source repo to a consumer repo')
+      .requiredOption('-t, --target-dir <path>', 'Consumer repo to update')
+      .option('-s, --source-dir <path>', 'Source repo (auto-detected if in fgv repo)')
+      .option('-n, --dry-run', 'Show what would change without modifying files', false)
+      .action(async (opts) => {
+        const sourceDir = opts.sourceDir ?? this._resolveSourceDir();
+        await runSync({
+          targetDir: opts.targetDir,
+          sourceDir,
+          dryRun: opts.dryRun
+        });
+      });
+
+    // ── init-library ──
+    this._program
+      .command('init-library')
+      .description('Scaffold a new library package within an existing Rush monorepo')
+      .requiredOption('-n, --name <name>', 'Package name (e.g. "ts-my-lib" — auto-prefixed with @fgv/)')
+      .option('-d, --description <text>', 'Package description', '')
+      .option('-r, --rig <type>', 'Heft rig: dual (default), node, or browser', 'dual')
+      .option(
+        '-c, --category <type>',
+        'Category folder: libraries (default), tools, apps, services',
+        'libraries'
+      )
+      .option('--repo-dir <path>', 'Rush monorepo root (default: cwd)', process.cwd())
+      .option('-p, --version-policy <name>', 'Version policy name', 'default')
+      .option('--initial-version <ver>', 'Initial version', '0.1.0')
+      .option(
+        '--fgv-dep-version <ver>',
+        'Version spec for @fgv/* deps ("workspace:*" in fgv, version range in consumers)',
+        'workspace:*'
+      )
+      .action(async (opts) => {
+        await runInitLibrary({
+          name: opts.name,
+          description: opts.description,
+          rig: opts.rig as RigType,
+          category: opts.category as CategoryType,
+          repoDir: opts.repoDir,
+          versionPolicy: opts.versionPolicy,
+          version: opts.initialVersion,
+          fgvDepVersion: opts.fgvDepVersion
+        });
+      });
+
+    // ── patch ──
+    this._program
+      .command('patch <file>')
+      .description('Apply targeted edits to a JSONC config file while preserving comments')
+      .allowUnknownOption(true)
+      .helpOption(false)
+      .action(async (file, _opts, cmd) => {
+        // Parse the raw args after the file argument as patch operations
+        const rawArgs = cmd.args.slice(1); // skip the file arg
+        // Actually, commander passes remaining args differently. Let's get them from process.argv
+        const allArgs = process.argv;
+        const patchIdx = allArgs.indexOf('patch');
+        const fileIdx = patchIdx + 1;
+        const opArgs = allArgs.slice(fileIdx + 1);
+
+        const operations = parsePatchArgs(opArgs);
+        if (operations.length === 0) {
+          console.error('No operations specified. Use --set, --uncomment, --add-to-array, etc.');
+          process.exit(1);
+        }
+        await runPatch({ file, operations });
+      });
+  }
+
+  /**
+   * Auto-detect the fgv source directory by walking up from the current working directory.
+   */
+  private _resolveSourceDir(): string {
+    const detected = detectSourceDir(process.cwd());
+    if (!detected) {
+      console.error(
+        'ERROR: Could not auto-detect fgv source repo. ' +
+          'Please specify --source-dir or run from within the fgv repository.'
+      );
+      process.exit(1);
+    }
+    return detected;
+  }
+}

package/src/commands/create.ts

@@ -0,0 +1,216 @@
+/**
+ * Create command — stamps out a new fgv-derived Rush monorepo.
+ *
+ * Uses `rush init` to generate base config with full documentation,
+ * then applies fgv-specific customizations via JSONC patching and shared file sync.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadManifest, getDefaultManifestPath } from '../packlets/manifest';
+import { patchFile, IPatchOperation } from '../packlets/jsonc';
+import { renderTemplateFile, getDefaultTemplatesDir, ITemplateVars } from '../packlets/template';
+import { copyFile, copyPackage, exec, getGitCommit, getGitRemoteUrl } from '../packlets/fs';
+
+export interface ICreateOptions {
+  targetDir: string;
+  repoUrl: string;
+  versionPolicy: string;
+  version: string;
+  sourceDir: string;
+  allowExisting: boolean;
+  gitInit: boolean;
+}
+
+const RUSH_VERSION = '5.172.1';
+
+const NODE_VERSION_RANGE =
+  '>=14.15.0 <15.0.0 || >=16.13.0 <17.0.0 || >=18.15.0 <19.0.0 || >=20.18.0 <21.0.0 || >=22.22.0 <23.0.0';
+
+export async function runCreate(options: ICreateOptions): Promise<void> {
+  const { targetDir, repoUrl, versionPolicy, version, sourceDir, allowExisting, gitInit } = options;
+
+  // Validate
+  if (!allowExisting && fs.existsSync(targetDir)) {
+    throw new Error(`Target directory already exists: ${targetDir} (use --allow-existing to override)`);
+  }
+  if (!fs.existsSync(path.join(sourceDir, 'rush.json'))) {
+    throw new Error(`Source directory is not a Rush repo: ${sourceDir}`);
+  }
+
+  const manifestPath = getDefaultManifestPath();
+  const templatesDir = getDefaultTemplatesDir();
+  const manifest = loadManifest(manifestPath);
+
+  console.log(`Creating new monorepo at: ${targetDir}`);
+  console.log(`  Source repo: ${sourceDir}`);
+  console.log(`  Repo URL:    ${repoUrl}`);
+  console.log(`  Version:     ${versionPolicy}@${version}`);
+  console.log('');
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // ── Step 1: rush init ──
+  if (fs.existsSync(path.join(targetDir, 'rush.json'))) {
+    console.log('==> Target already has rush.json, skipping rush init');
+  } else {
+    console.log('==> Running rush init...');
+    try {
+      const output = exec(`npx "@microsoft/rush@${RUSH_VERSION}" init`, { cwd: targetDir });
+      for (const line of output.split('\n')) {
+        console.log(`  ${line}`);
+      }
+    } catch (err: unknown) {
+      // rush init writes to stderr for some messages, check if rush.json was created
+      if (!fs.existsSync(path.join(targetDir, 'rush.json'))) {
+        throw new Error(`rush init failed: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  // ── Step 2: Patch rush.json ──
+  console.log('');
+  console.log('==> Patching rush.json with fgv customizations...');
+
+  const rushJsonOps: IPatchOperation[] = [
+    { type: 'set', path: 'nodeSupportedVersionRange', value: NODE_VERSION_RANGE },
+    { type: 'set', path: 'ensureConsistentVersions', value: true },
+    { type: 'uncomment', path: 'projectFolderMinDepth' },
+    { type: 'set', path: 'projectFolderMinDepth', value: 2 },
+    { type: 'uncomment', path: 'projectFolderMaxDepth' },
+    { type: 'set', path: 'projectFolderMaxDepth', value: 2 },
+    { type: 'uncomment', path: 'url' },
+    { type: 'set', path: 'repository.url', value: repoUrl },
+    { type: 'uncomment', path: 'defaultBranch' },
+    { type: 'uncomment', path: 'defaultRemote' }
+  ];
+
+  patchFile(path.join(targetDir, 'rush.json'), rushJsonOps);
+  for (const op of rushJsonOps) {
+    const desc =
+      op.type === 'uncomment' || op.type === 'remove'
+        ? `  ${op.type}: ${op.path}`
+        : `  ${op.type}: ${op.path}`;
+    console.log(desc);
+  }
+
+  // ── Step 3: Patch other rush config files ──
+  console.log('');
+  console.log('==> Patching rush config files...');
+
+  patchFile(path.join(targetDir, 'common/config/rush/build-cache.json'), [
+    { type: 'set', path: 'buildCacheEnabled', value: true }
+  ]);
+  console.log('  build-cache.json: buildCacheEnabled = true');
+
+  patchFile(path.join(targetDir, 'common/config/rush/pnpm-config.json'), [
+    { type: 'uncomment', path: 'strictPeerDependencies' },
+    { type: 'set', path: 'strictPeerDependencies', value: true }
+  ]);
+  console.log('  pnpm-config.json: strictPeerDependencies = true');
+
+  // ── Step 4: Generate templated files ──
+  console.log('');
+  console.log('==> Generating templated config files...');
+
+  const templateVars: ITemplateVars = {
+    REPO_URL: repoUrl,
+    VERSION_POLICY_NAME: versionPolicy,
+    VERSION: version
+  };
+
+  for (const tmpl of manifest.templated.files) {
+    const templatePath = path.join(sourceDir, tmpl.template);
+    const destPath = path.join(targetDir, tmpl.destination);
+    renderTemplateFile(templatePath, destPath, templateVars);
+  }
+
+  // ── Step 5: Copy shared files ──
+  console.log('');
+  console.log('==> Copying shared files...');
+
+  for (const file of manifest.shared.files) {
+    const srcPath = path.join(sourceDir, file.source);
+    const destPath = path.join(targetDir, file.destination);
+    if (!fs.existsSync(srcPath)) {
+      console.warn(`  WARNING: Source file not found, skipping: ${file.source}`);
+      continue;
+    }
+    copyFile(srcPath, destPath);
+    console.log(`  Copied: ${file.destination}`);
+  }
+
+  for (const pkg of manifest.sharedPackages.packages) {
+    const srcPath = path.join(sourceDir, pkg.source);
+    const destPath = path.join(targetDir, pkg.destination);
+    if (!fs.existsSync(srcPath)) {
+      console.warn(`  WARNING: Source directory not found, skipping: ${pkg.source}`);
+      continue;
+    }
+    copyPackage(srcPath, destPath);
+    console.log(`  Copied package: ${pkg.destination}`);
+  }
+
+  // ── Step 6: Create standard directories ──
+  console.log('');
+  console.log('==> Creating directory structure...');
+
+  const dirs = ['libraries', 'tools', 'apps', 'services', '.claude/project', '.claude/skills'];
+  for (const dir of dirs) {
+    fs.mkdirSync(path.join(targetDir, dir), { recursive: true });
+  }
+
+  const gitkeeps = ['.claude/project/.gitkeep', '.claude/skills/.gitkeep'];
+  for (const gk of gitkeeps) {
+    fs.writeFileSync(path.join(targetDir, gk), '');
+  }
+  console.log('  Created standard directory structure');
+
+  // ── Step 7: Record template metadata ──
+  console.log('');
+  console.log('==> Recording template metadata...');
+
+  const sourceCommit = getGitCommit(sourceDir);
+  const sourceRepo = getGitRemoteUrl(sourceDir);
+
+  const syncMetadata = {
+    templateSource: repoUrl,
+    sourceRepo,
+    sourceCommit,
+    createdAt: new Date().toISOString(),
+    lastSyncedAt: new Date().toISOString(),
+    manifestVersion: '1.0.0'
+  };
+  fs.writeFileSync(path.join(targetDir, '.template-sync'), JSON.stringify(syncMetadata, null, 2) + '\n');
+  console.log('  Created .template-sync');
+
+  // ── Step 8: Git init ──
+  if (gitInit) {
+    console.log('');
+    console.log('==> Initializing git repository...');
+    try {
+      exec('git init -b main', { cwd: targetDir });
+      exec('git add -A', { cwd: targetDir });
+      exec(
+        `git commit -m "Initial commit from fgv monorepo template\n\nSource: ${sourceDir}\nTemplate commit: ${sourceCommit}"`,
+        { cwd: targetDir }
+      );
+      console.log('  Git repository initialized with initial commit');
+    } catch (err: unknown) {
+      console.warn(`  WARNING: Git init failed: ${(err as Error).message}`);
+    }
+  }
+
+  // ── Done ──
+  console.log('');
+  console.log(`=== Monorepo created successfully at: ${targetDir} ===`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Add your domain packages to libraries/, apps/, tools/, services/');
+  console.log('  2. Register them in rush.json');
+  console.log('  3. Fill in the project table in CLAUDE.md');
+  console.log('  4. Fill in ACTIVE_DEVELOPMENT.md with your domain projects');
+  console.log('  5. Add domain-specific Rush commands to common/config/rush/command-line.json');
+  console.log(`  6. Run: cd ${targetDir} && rush install && rush build`);
+  console.log('');
+}