@fgv/repo-template 5.1.0-2

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;AASH,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;IAuGtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAW1B"}

package/lib/cli.js

@@ -0,0 +1,126 @@
+"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");
+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>', 'Version spec for @fgv/* deps ("workspace:*" in fgv, version range in consumers)', 'workspace:*')
+            .action(async (opts) => {
+            await (0, init_library_1.runInitLibrary)({
+                name: opts.name,
+                description: opts.description,
+                rig: opts.rig,
+                category: opts.category,
+                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 = (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 { runInitLibrary, RigType, CategoryType } from './commands/init-library';\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        'Version spec for @fgv/* deps (\"workspace:*\" in fgv, version range in consumers)',\n        'workspace:*'\n      )\n      .action(async (opts) => {\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: opts.repoDir,\n          versionPolicy: opts.versionPolicy,\n          version: opts.initialVersion,\n          fgvDepVersion: opts.fgvDepVersion\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"}

package/lib/commands/create.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * 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.
+ */
+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.runCreate = runCreate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const manifest_1 = require("../packlets/manifest");
+const jsonc_1 = require("../packlets/jsonc");
+const template_1 = require("../packlets/template");
+const fs_1 = require("../packlets/fs");
+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';
+async function runCreate(options) {
+    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 = (0, manifest_1.getDefaultManifestPath)();
+    const templatesDir = (0, template_1.getDefaultTemplatesDir)();
+    const manifest = (0, manifest_1.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 = (0, fs_1.exec)(`npx "@microsoft/rush@${RUSH_VERSION}" init`, { cwd: targetDir });
+            for (const line of output.split('\n')) {
+                console.log(`  ${line}`);
+            }
+        }
+        catch (err) {
+            // 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.message}`);
+            }
+        }
+    }
+    // ── Step 2: Patch rush.json ──
+    console.log('');
+    console.log('==> Patching rush.json with fgv customizations...');
+    const rushJsonOps = [
+        { 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' }
+    ];
+    (0, jsonc_1.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...');
+    (0, jsonc_1.patchFile)(path.join(targetDir, 'common/config/rush/build-cache.json'), [
+        { type: 'set', path: 'buildCacheEnabled', value: true }
+    ]);
+    console.log('  build-cache.json: buildCacheEnabled = true');
+    (0, jsonc_1.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 = {
+        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);
+        (0, template_1.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;
+        }
+        (0, fs_1.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;
+        }
+        (0, fs_1.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 = (0, fs_1.getGitCommit)(sourceDir);
+    const sourceRepo = (0, fs_1.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 {
+            (0, fs_1.exec)('git init -b main', { cwd: targetDir });
+            (0, fs_1.exec)('git add -A', { cwd: targetDir });
+            (0, fs_1.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) {
+            console.warn(`  WARNING: Git init failed: ${err.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('');
+}
+//# sourceMappingURL=create.js.map