@codedrifters/configulator 0.0.174 → 0.0.175

package/lib/index.mjs

@@ -463,12 +463,31 @@ var baseBundle = {
     },
     {
       name: "cursor-projen-restrictions",
-      description: "Cursor must not run projen or package-manager install commands",
+      description: "Cursor must not run projen, build, test, or package-manager commands",
       scope: AGENT_RULE_SCOPE.ALWAYS,
       content: [
-        "# Projen Restrictions",
+        "# Projen & Development Command Restrictions",
         "",
-        "- **Do not run `npx projen`, `pnpm install`, or `pnpm i`** \u2014 after modifying Projen configuration, the user should run these commands locally."
+        "**Never** run any of the following commands. Instead, tell the user which commands to run and why.",
+        "",
+        "## Prohibited Commands",
+        "",
+        "- `npx projen` \u2014 synthesize project files",
+        "- `pnpm install` / `pnpm i` \u2014 install dependencies",
+        "- `pnpm build` / `pnpm build:all` \u2014 build the project",
+        "- `pnpm test` / `pnpm --filter ... test` \u2014 run tests",
+        "- `pnpm eslint` / `pnpm --filter ... eslint` \u2014 run linting",
+        "- `pnpm compile` / `pnpm --filter ... compile` \u2014 compile packages",
+        "- `pnpm reset` / `pnpm reset:all` \u2014 reset build artifacts",
+        "- Any `vitest`, `tsup`, `rollup`, or `turbo` commands",
+        "",
+        "## What to Do Instead",
+        "",
+        "After making changes that need validation, tell the user the specific commands to run:",
+        "",
+        "1. **After projen config changes** \u2014 tell the user to run `npx projen && pnpm install`",
+        "2. **After source code changes** \u2014 tell the user to run `pnpm --filter @codedrifters/<package> test`",
+        "3. **After multi-package changes** \u2014 tell the user to run `pnpm build:all`"
       ].join("\n"),
       platforms: {
         claude: { exclude: true }
@@ -774,13 +793,15 @@ var githubWorkflowBundle = {
         "",
         "When the user says **open a PR** (or similar), follow these steps exactly:",
         "",
-        "1. **Check for uncommitted changes** \u2014 if any exist, commit them with a conventional commit message",
-        "2. **Pull and rebase from the default branch** \u2014 run `git pull origin {{repository.defaultBranch}} --rebase` to incorporate the latest changes and resolve any conflicts before pushing",
-        "3. **Push the branch** to origin: `git push -u origin <branch>`",
-        "4. **Create the PR** using `gh pr create`:",
+        "1. **Regenerate project files** \u2014 run `npx projen` then `pnpm install` to ensure all generated files are up to date. Check `git diff` \u2014 if there are changes, commit them before proceeding.",
+        "2. **Run the full monorepo build** \u2014 run `pnpm build:all` to compile, lint, and test all packages (mirrors the CI pipeline). This command requires the user to be authenticated to AWS on the prod account used for Turborepo remote caching (`readonlyaccess-prod-525259625215-us-east-1` profile). If the command fails due to AWS credentials, ask the user to authenticate first. If the build produces changes to turbo inputs (typically snapshot files or ESLint auto-fixes), commit those changes and run `pnpm build:all` again \u2014 the build must complete cleanly with no uncommitted changes.",
+        "3. **Check for uncommitted changes** \u2014 if any exist, commit them with a conventional commit message",
+        "4. **Pull and rebase from the default branch** \u2014 run `git pull origin {{repository.defaultBranch}} --rebase` to incorporate the latest changes and resolve any conflicts before pushing",
+        "5. **Push the branch** to origin: `git push -u origin <branch>`",
+        "6. **Create the PR** using `gh pr create`:",
         "   - **Title**: use a conventional commit style title (e.g., `feat(scope): short description`)",
         "   - **Body**: include `Closes #<issue-number>` (derived from the branch name) and a brief summary of changes",
-        "5. **Enable auto-merge with squash** \u2014 use `gh pr merge --auto --squash` with the merge commit message:",
+        "7. **Enable auto-merge with squash** \u2014 use `gh pr merge --auto --squash` with the merge commit message:",
         "",
         "```",
         "gh pr merge --auto --squash --subject '<conventional-commit-title>' --body '<extended-description>'",
@@ -1012,6 +1033,185 @@ var projenBundle = {
   description: "Projen conventions, synthesis workflow, .projenrc.ts patterns",
   appliesWhen: (project) => hasDep(project, "projen"),
   rules: [
+    {
+      name: "development-commands",
+      description: "Projen development commands for building, testing, linting, and validating changes",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Development Commands",
+        "",
+        "This project uses Projen to manage configuration and Turborepo to orchestrate builds across the monorepo. Run all commands from the **repository root** unless otherwise noted.",
+        "",
+        "## Synthesizing Projen Configuration",
+        "",
+        "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files:",
+        "",
+        "```sh",
+        "npx projen",
+        "pnpm install",
+        "```",
+        "",
+        "Both steps are required \u2014 `npx projen` regenerates files, `pnpm install` updates the lockfile to match.",
+        "",
+        "## Building",
+        "",
+        "**Full monorepo build** (compile + test + package, all sub-packages via Turborepo):",
+        "",
+        "```sh",
+        "pnpm build:all",
+        "```",
+        "",
+        "**Root project only** (synthesize + compile + lint):",
+        "",
+        "```sh",
+        "pnpm build",
+        "```",
+        "",
+        "**Single sub-package** (compile only):",
+        "",
+        "```sh",
+        "pnpm --filter @codedrifters/<package> compile",
+        "```",
+        "",
+        "Replace `<package>` with `configulator`, `constructs`, or `utils`.",
+        "",
+        "## Testing",
+        "",
+        "**Run tests for a single sub-package:**",
+        "",
+        "```sh",
+        "pnpm --filter @codedrifters/<package> test",
+        "```",
+        "",
+        "This runs ESLint + Vitest for the specified package.",
+        "",
+        "**Run only Vitest (skip lint) in a sub-package:**",
+        "",
+        "```sh",
+        "cd packages/@codedrifters/<package>",
+        "pnpm exec vitest run",
+        "```",
+        "",
+        "**Run a specific test file:**",
+        "",
+        "```sh",
+        "cd packages/@codedrifters/<package>",
+        "pnpm exec vitest run src/path/to/file.test.ts",
+        "```",
+        "",
+        "## Linting",
+        "",
+        "**Lint the root project:**",
+        "",
+        "```sh",
+        "pnpm eslint",
+        "```",
+        "",
+        "**Lint a single sub-package:**",
+        "",
+        "```sh",
+        "pnpm --filter @codedrifters/<package> eslint",
+        "```",
+        "",
+        "## Resetting Build Artifacts",
+        "",
+        "**Reset everything** (all packages + root):",
+        "",
+        "```sh",
+        "pnpm reset:all",
+        "```",
+        "",
+        "**Reset root only:**",
+        "",
+        "```sh",
+        "pnpm reset",
+        "```",
+        "",
+        "## Validating Changes Are Complete",
+        "",
+        "After finishing implementation work, validate that changes are correct by running the appropriate commands depending on what was changed:",
+        "",
+        "1. **Projen config changes** (`projenrc/`, `.projenrc.ts`):",
+        "   - Run `npx projen` then `pnpm install`",
+        "   - Verify no unexpected generated file changes with `git diff`",
+        "",
+        "2. **Source code changes** (in a sub-package):",
+        "   - Compile: `pnpm --filter @codedrifters/<package> compile`",
+        "   - Test: `pnpm --filter @codedrifters/<package> test`",
+        "",
+        "3. **Changes spanning multiple packages**:",
+        "   - Run `pnpm build:all` to validate the full monorepo build",
+        "",
+        "4. **Root-level changes** (projenrc, root config):",
+        "   - Run `pnpm build` to validate root synthesis + compilation + lint",
+        "",
+        "## Command Reference",
+        "",
+        "| Task | Command |",
+        "|------|---------|",
+        "| Synthesize projen | `npx projen` |",
+        "| Install deps | `pnpm install` |",
+        "| Full monorepo build | `pnpm build:all` |",
+        "| Root build only | `pnpm build` |",
+        "| Compile one package | `pnpm --filter @codedrifters/<pkg> compile` |",
+        "| Test one package | `pnpm --filter @codedrifters/<pkg> test` |",
+        "| Lint one package | `pnpm --filter @codedrifters/<pkg> eslint` |",
+        "| Lint root | `pnpm eslint` |",
+        "| Reset all artifacts | `pnpm reset:all` |"
+      ].join("\n"),
+      tags: ["workflow"]
+    },
+    {
+      name: "agent-rules-customization",
+      description: "How to customize agent rules for this repo via the Projen project definition",
+      scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+      filePatterns: [
+        "projenrc/**/*.ts",
+        ".projenrc.ts",
+        ".claude/rules/*.md",
+        ".cursor/rules/*.mdc",
+        "CLAUDE.md"
+      ],
+      content: [
+        "# Customizing Agent Rules",
+        "",
+        "Agent rules for Claude and Cursor are **generated** by configulator's `AgentConfig` component. The generated output files (`.claude/rules/`, `.cursor/rules/`, `CLAUDE.md`) must not be edited directly \u2014 they are overwritten on every `npx projen` run.",
+        "",
+        "## Adding Repo-Specific Rules",
+        "",
+        "Rules that only apply to this repository should be added to the `agentConfig.rules` array in the Projen project definition (`.projenrc.ts` or `projenrc/*.ts`):",
+        "",
+        "```typescript",
+        "agentConfig: {",
+        "  rules: [",
+        "    {",
+        "      name: 'my-repo-rule',",
+        "      description: 'What this rule does',",
+        "      scope: AGENT_RULE_SCOPE.ALWAYS, // or FILE_PATTERN with filePatterns",
+        "      content: '# My Rule\\n\\n- Guideline 1\\n- Guideline 2',",
+        "    },",
+        "  ],",
+        "}",
+        "```",
+        "",
+        "## Extending Existing Bundle Rules",
+        "",
+        "To append repo-specific content to a rule provided by a configulator bundle (without replacing it), use `agentConfig.ruleExtensions`:",
+        "",
+        "```typescript",
+        "agentConfig: {",
+        "  ruleExtensions: {",
+        "    'typescript-conventions': '## Additional Guidelines\\n\\n- My custom guideline',",
+        "  },",
+        "}",
+        "```",
+        "",
+        "## After Any Change",
+        "",
+        "Run `npx projen` then `pnpm install` to regenerate the output files."
+      ].join("\n"),
+      tags: ["workflow"]
+    },
     {
       name: "projen-conventions",
       description: "Projen configuration patterns and best practices",