@fgv/repo-template 5.1.0-10

package/README.md

@@ -0,0 +1,216 @@
+# fgv Monorepo Template System
+
+This directory contains scripts and configuration for creating and maintaining fgv-derived Rush monorepos.
+
+## Overview
+
+The fgv repository contains general-purpose TypeScript utilities (`@fgv/ts-utils`, `@fgv/ts-json`, etc.) alongside domain-specific code. This template system allows domain-specific code to live in its own monorepo while sharing infrastructure, coding standards, and agent configurations.
+
+### Architecture
+
+```
+fgv (source of truth)
+├── Utility libraries (published to npm)
+├── Infrastructure & standards ──────► chocolate-lab (consumer)
+│   ├── .ai/instructions/              ├── .ai/instructions/  (synced)
+│   ├── .claude/agents/                ├── .claude/agents/    (synced)
+│   ├── rigs/heft-dual-rig/           ├── rigs/heft-dual-rig/(synced)
+│   └── ...                           ├── libraries/ts-chocolate/
+│                                      ├── apps/chocolate-lab-web/
+│                                      └── ... (domain code)
+└── scripts/template/ (this dir)
+    ├── create-repo.sh          ──────► Stamps out new repos
+    ├── sync-shared.sh          ──────► Pushes updates to consumers
+    └── patch-rush-config.mjs   ──────► JSONC config patching
+```
+
+## How It Works
+
+### Repo Creation: `rush init` + Customize
+
+New repos are created using Rush's own `rush init` as the foundation, which ensures:
+- All Rush config files have full inline documentation
+- New Rush features appear automatically as Rush evolves
+- The config structure stays in sync with the installed Rush version
+
+After `rush init`, the script applies fgv-specific customizations:
+
+1. **JSONC patches** (via `patch-rush-config.mjs`): Targeted edits to rush.json and other config files that preserve comments and formatting
+2. **Templated files**: Generated from `.tmpl` templates with parameter substitution (consumer-owned after creation)
+3. **Shared files**: Copied verbatim from fgv (overwritten on each sync)
+
+### What Gets Patched vs. Synced vs. Templated
+
+| Category | During Create | During Sync | Examples |
+|----------|--------------|-------------|---------|
+| Rush config (from `rush init`) | Patched with fgv opinions | Not touched (consumer-owned) | rush.json, build-cache.json, pnpm-config.json |
+| Templated files | Generated from .tmpl | Not touched (consumer-owned) | CLAUDE.md, command-line.json, version-policies.json |
+| Shared files | Copied from fgv | Overwritten from fgv | .ai/instructions/, .claude/agents/, rigs/, .prettierrc.js |
+
+### Rush Config Patches Applied
+
+These targeted customizations are applied to `rush init` output:
+
+| File | Patch | Reason |
+|------|-------|--------|
+| rush.json | `ensureConsistentVersions: true` | Enforce version consistency |
+| rush.json | `projectFolderMinDepth/MaxDepth: 2` | Enforce category folder structure |
+| rush.json | `repository.url`, `defaultBranch`, `defaultRemote` | Enable `rush change` |
+| rush.json | Add heft-dual-rig and typedoc-compact-theme projects | Shared build infrastructure |
+| build-cache.json | `buildCacheEnabled: true` | Enable build caching |
+| pnpm-config.json | `strictPeerDependencies: true` | Catch peer dependency issues |
+
+## File Categories
+
+### Shared Files (synced verbatim)
+These files are identical across all fgv-derived repos and are overwritten on each sync:
+
+| Category | Files |
+|----------|-------|
+| Coding standards | `.ai/instructions/CODING_STANDARDS.md`, `TESTING_GUIDELINES.md`, `CODE_REVIEW_CHECKLIST.md`, `MONOREPO_GUIDE.md` |
+| Workflows | `.ai/workflows/*.yaml` |
+| Claude agents | `.claude/agents/**/*.md` |
+| Build rig | `rigs/heft-dual-rig/` |
+| TypeDoc theme | `plugins/typedoc-compact-theme/` |
+| Code formatting | `.prettierrc.js`, `.gitattributes` |
+| CI | `.github/workflows/ci.yml` |
+| AI adapters | `.windsurfrules`, `.cursorrules`, `.github/copilot-instructions.md` |
+| Prettier | `common/autoinstallers/rush-prettier/package.json` |
+
+### Templated Files (generated once, then consumer-owned)
+These files are parameterized during repo creation and never overwritten by sync:
+
+| File | Parameters |
+|------|-----------|
+| `CLAUDE.md` | `{{PROJECT_TABLE}}` — library/purpose table |
+| `command-line.json` | Generic commands only; add domain commands manually |
+| `version-policies.json` | `{{VERSION_POLICY_NAME}}`, `{{VERSION}}` |
+| `ACTIVE_DEVELOPMENT.md` | `{{ACTIVE_LIBRARIES}}` — domain project table |
+| `.gitignore` | No parameters (but consumer may customize) |
+| `package.json` | No parameters |
+
+### Rush Config Files (from `rush init`, consumer-owned)
+These files come from `rush init` with targeted patches applied during creation. They are never synced — consumers own them fully:
+
+- `rush.json`, `common-versions.json`, `experiments.json`, `pnpm-config.json`, `build-cache.json`, `rush-plugins.json`, `.pnpmfile.cjs`, `.npmrc`, `.npmrc-publish`, `artifactory.json`, `cobuild.json`, `custom-tips.json`, `subspaces.json`
+
+## Usage
+
+### Creating a New Repo
+
+```bash
+./create-repo.sh \
+  --target-dir /path/to/new-repo \
+  --repo-url https://github.com/ErikFortune/new-repo \
+  --version-policy my-domain \
+  --version 0.1.0
+```
+
+For existing git repos (e.g., already created on GitHub):
+```bash
+./create-repo.sh \
+  --target-dir /path/to/existing-repo \
+  --repo-url https://github.com/ErikFortune/existing-repo \
+  --version-policy my-domain \
+  --version 0.1.0 \
+  --allow-existing \
+  --no-git-init
+```
+
+After creation:
+
+1. Copy your domain packages into `libraries/`, `apps/`, `tools/`, `services/`
+2. Register them in `rush.json` (use `patch-rush-config.mjs` or edit directly)
+3. Convert `workspace:*` dependencies on `@fgv/*` utilities to published versions (e.g., `^5.1.0-0`)
+4. Fill in `CLAUDE.md` project table and `ACTIVE_DEVELOPMENT.md`
+5. Add domain-specific Rush commands to `command-line.json`
+6. Run `rush install && rush build && rush test`
+
+### Syncing Updates
+
+When shared files (coding standards, agents, etc.) are updated in fgv:
+
+```bash
+# Preview what would change
+./sync-shared.sh --target-dir /path/to/consumer-repo --dry-run
+
+# Apply changes
+./sync-shared.sh --target-dir /path/to/consumer-repo
+
+# Review and commit in the consumer repo
+cd /path/to/consumer-repo
+git diff
+git add -A
+git commit -m "Sync shared files from fgv template"
+```
+
+### JSONC Config Patching
+
+The `patch-rush-config.mjs` helper can modify any JSONC file while preserving comments:
+
+```bash
+# Set a value
+node patch-rush-config.mjs rush.json --set 'ensureConsistentVersions=true'
+
+# Uncomment a property then set its value
+node patch-rush-config.mjs rush.json --uncomment 'projectFolderMinDepth' --set 'projectFolderMinDepth=2'
+
+# Add to an array (JSON value)
+node patch-rush-config.mjs rush.json --add-to-array 'projects={"packageName":"@my/lib","projectFolder":"libraries/my-lib"}'
+
+# Set a value using raw JSON
+node patch-rush-config.mjs rush.json --set-json 'repository={"url":"https://github.com/...","defaultBranch":"main"}'
+
+# Remove a property
+node patch-rush-config.mjs rush.json --remove 'telemetryEnabled'
+```
+
+### How Sync Tracking Works
+
+Each consumer repo has a `.template-sync` file that records:
+- When the repo was created from the template
+- Which source commit was last synced
+- When the last sync occurred
+
+This is informational — the sync script always copies the latest files regardless of tracking state.
+
+## Consuming @fgv/* Utilities
+
+Domain repos depend on fgv utility packages via npm (not workspace links):
+
+```json
+{
+  "dependencies": {
+    "@fgv/ts-utils": "^5.1.0-0",
+    "@fgv/ts-json": "^5.1.0-0"
+  }
+}
+```
+
+To update utility versions, use `rush add -p @fgv/ts-utils@^5.2.0` etc. in the consumer repo.
+
+## Manifest Reference
+
+The `sync-manifest.json` file is the source of truth for which files are shared vs. templated. It has three sections:
+
+- **`shared`** — Individual files copied verbatim
+- **`sharedPackages`** — Entire directories synced (excluding build artifacts)
+- **`templated`** — Files generated from `.tmpl` templates during creation only
+
+## Extending
+
+### Adding a new shared file
+1. Add an entry to `sync-manifest.json` under `shared.files`
+2. Run `sync-shared.sh` against consumer repos
+
+### Adding a new template parameter
+1. Add `{{PARAM_NAME}}` to the `.tmpl` file
+2. Add the substitution to `create-repo.sh`'s `render_template` function
+3. Document the parameter in this README
+
+### Adding a Rush config patch
+1. Add the patch command to `create-repo.sh` in the "Patch rush config" step
+2. Document the patch in this README's "Rush Config Patches Applied" table
+
+### Creating a new consumer repo
+Follow the "Creating a New Repo" steps above. The template system is designed so that consumer repos are fully independent after creation — they can diverge as needed while still receiving shared file updates via sync.

package/bin/repo-template.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+const { RepoTemplateCli } = require('../lib/cli');
+
+async function main() {
+  try {
+    const cli = new RepoTemplateCli();
+    await cli.run(process.argv);
+  } catch (error) {
+    console.error('Fatal error:', error.message);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Unhandled error:', error);
+  process.exit(1);
+});

package/config/rig.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@rushstack/heft-node-rig"
+}

package/lib/cli.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI entry point — sets up commander with create, sync, and patch subcommands.
+ */
+export declare class RepoTemplateCli {
+    private readonly _program;
+    constructor();
+    run(argv: string[]): Promise<void>;
+    private _setupCommands;
+    /**
+     * Auto-detect the fgv source directory by walking up from the current working directory.
+     */
+    private _resolveSourceDir;
+}
+//# sourceMappingURL=cli.d.ts.map

package/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;;IAOtB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,OAAO,CAAC,cAAc;IAwJtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAW1B"}

package/lib/cli.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * CLI entry point — sets up commander with create, sync, and patch subcommands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepoTemplateCli = void 0;
+const commander_1 = require("commander");
+const fs_1 = require("./packlets/fs");
+const create_1 = require("./commands/create");
+const sync_1 = require("./commands/sync");
+const patch_1 = require("./commands/patch");
+const init_library_1 = require("./commands/init-library");
+const link_1 = require("./commands/link");
+class RepoTemplateCli {
+    constructor() {
+        this._program = new commander_1.Command();
+        this._setupCommands();
+    }
+    async run(argv) {
+        await this._program.parseAsync(argv);
+    }
+    _setupCommands() {
+        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) => {
+            var _a;
+            const sourceDir = (_a = opts.sourceDir) !== null && _a !== void 0 ? _a : this._resolveSourceDir();
+            await (0, create_1.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) => {
+            var _a;
+            const sourceDir = (_a = opts.sourceDir) !== null && _a !== void 0 ? _a : this._resolveSourceDir();
+            await (0, sync_1.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>', 'Explicit version spec for @fgv/* deps (auto-detected if omitted: "workspace:*" in fgv, derived from repo-template version in consumers)')
+            .option('--fgv-dep-channel <channel>', 'Channel for auto-detected @fgv/* dep version: alpha, release, or auto (default: auto — infers from repo-template build)', 'auto')
+            .action(async (opts) => {
+            var _a;
+            const repoDir = opts.repoDir;
+            const fgvDepVersion = (_a = opts.fgvDepVersion) !== null && _a !== void 0 ? _a : (0, init_library_1.resolveFgvDepVersion)(repoDir, opts.fgvDepChannel);
+            await (0, init_library_1.runInitLibrary)({
+                name: opts.name,
+                description: opts.description,
+                rig: opts.rig,
+                category: opts.category,
+                repoDir,
+                versionPolicy: opts.versionPolicy,
+                version: opts.initialVersion,
+                fgvDepVersion
+            });
+        });
+        // ── link ──
+        this._program
+            .command('link')
+            .description('Link to a local fgv worktree for cross-repo development')
+            .requiredOption('--fgv-dir <path>', 'Path to the local fgv worktree')
+            .option('--repo-dir <path>', 'Consumer Rush repo root (default: cwd)', process.cwd())
+            .action(async (opts) => {
+            await (0, link_1.runLink)({
+                fgvDir: opts.fgvDir,
+                repoDir: opts.repoDir
+            });
+        });
+        // ── unlink ──
+        this._program
+            .command('unlink')
+            .description('Switch back from local fgv worktree to published npm packages')
+            .option('--repo-dir <path>', 'Consumer Rush repo root (default: cwd)', process.cwd())
+            .option('--fgv-version <spec>', 'Also bump @fgv/* deps to this version spec')
+            .action(async (opts) => {
+            await (0, link_1.runUnlink)({
+                repoDir: opts.repoDir,
+                version: opts.fgvVersion
+            });
+        });
+        // ── update-fgv-versions ──
+        this._program
+            .command('update-fgv-versions')
+            .description('Bump @fgv/* dependency version specs across all projects')
+            .option('--repo-dir <path>', 'Consumer Rush repo root (default: cwd)', process.cwd())
+            .option('--fgv-version <spec>', 'Version spec to set (e.g. "~5.2.0"). If omitted, queries npm for latest.')
+            .action(async (opts) => {
+            await (0, link_1.runUpdateFgvVersions)({
+                repoDir: opts.repoDir,
+                version: opts.fgvVersion
+            });
+        });
+        // ── 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 = (0, patch_1.parsePatchArgs)(opArgs);
+            if (operations.length === 0) {
+                console.error('No operations specified. Use --set, --uncomment, --add-to-array, etc.');
+                process.exit(1);
+            }
+            await (0, patch_1.runPatch)({ file, operations });
+        });
+    }
+    /**
+     * Auto-detect the fgv source directory by walking up from the current working directory.
+     */
+    _resolveSourceDir() {
+        const detected = (0, fs_1.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;
+    }
+}
+exports.RepoTemplateCli = RepoTemplateCli;
+//# sourceMappingURL=cli.js.map

package/lib/cli.js.map

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

package/lib/commands/create.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export interface ICreateOptions {
+    targetDir: string;
+    repoUrl: string;
+    versionPolicy: string;
+    version: string;
+    sourceDir: string;
+    allowExisting: boolean;
+    gitInit: boolean;
+}
+export declare function runCreate(options: ICreateOptions): Promise<void>;
+//# sourceMappingURL=create.d.ts.map

package/lib/commands/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAOD,wBAAsB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA0LtE"}