@codedrifters/configulator 0.0.162 → 0.0.164

package/lib/index.mjs

@@ -262,6 +262,37 @@ var awsCdkBundle = {
         "}",
         "```",
         "",
+        "## L2 Over L1 Construct Preference",
+        "",
+        "- Always prefer L2 constructs (e.g., `s3.Bucket`, `lambda.Function`) over L1 escape hatches (`CfnBucket`, `CfnFunction`)",
+        "- Only drop to L1 when the L2 construct is missing the feature you need or does not exist yet",
+        "- When using L1, add a comment explaining why the L2 was insufficient",
+        "",
+        "## Filename / Class Name Matching",
+        "",
+        "- Kebab-case filenames must mirror PascalCase class names (e.g., `my-construct.ts` \u2192 `MyConstruct`)",
+        "- One primary construct per file; supporting types (props interface, enums) live in the same file",
+        "- Test files follow the same pattern: `my-construct.spec.ts`",
+        "",
+        "## Cross-Stack Lookup Patterns",
+        "",
+        "- Lookups live on **service classes**, not component/construct classes",
+        "- Use static methods for cross-stack lookups so consumers don't need an instance:",
+        "",
+        "```typescript",
+        "export class MyService {",
+        "  /** Look up a resource from another stack via SSM. */",
+        "  public static lookupArn(scope: Construct, id: string): string {",
+        "    return StringParameter.valueForStringParameter(",
+        "      scope,",
+        "      `/my-app/my-resource-arn`,",
+        "    );",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- Store outputs in SSM parameters with well-known paths; do not pass values between stacks via props",
+        "",
         "## AWS Best Practices",
         "",
         "- Use AWS CDK v2 (`aws-cdk-lib`)",
@@ -275,8 +306,30 @@ var awsCdkBundle = {
         "",
         "- Mock `Code.fromAsset` in any test file that synthesizes CDK stacks",
         "- Use static S3 values (`mock-assets-bucket`, `mock-asset-key.zip`) so snapshots are stable",
-        "- Add the mock in `beforeAll` and restore in `afterAll`",
-        "- Normalize the template before snapshotting when the stack includes asset-based Lambdas"
+        "- Add the mock in `beforeAll` and restore in `afterAll`:",
+        "",
+        "```typescript",
+        "let fromAssetMock: MockInstance;",
+        "",
+        "beforeAll(() => {",
+        '  fromAssetMock = vi.spyOn(Code, "fromAsset").mockReturnValue({',
+        "    isInline: false,",
+        "    bind: () => ({",
+        "      s3Location: {",
+        '        bucketName: "mock-assets-bucket",',
+        '        objectKey: "mock-asset-key.zip",',
+        "      },",
+        "    }),",
+        "  } as unknown as AssetCode);",
+        "});",
+        "",
+        "afterAll(() => {",
+        "  fromAssetMock.mockRestore();",
+        "});",
+        "```",
+        "",
+        "- Normalize the template before snapshotting when the stack includes asset-based Lambdas",
+        "- Use `Template.fromStack(stack)` and assert with `hasResourceProperties` for targeted checks"
       ].join("\n"),
       tags: ["infrastructure"]
     }
@@ -585,6 +638,98 @@ var baseBundle = {
   ]
 };
 
+// src/agent/bundles/github-workflow.ts
+import { GitHub } from "projen/lib/github";
+var githubWorkflowBundle = {
+  name: "github-workflow",
+  description: "GitHub issue and PR workflow automation patterns",
+  appliesWhen: (project) => hasComponent(project, GitHub),
+  rules: [
+    {
+      name: "issue-workflow",
+      description: "Automated workflow for starting work on a GitHub issue",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Issue Workflow",
+        "",
+        '## "Work on issue X" Automation',
+        "",
+        "When the user says **work on issue X** (or similar), follow these steps exactly:",
+        "",
+        "1. **Fetch issue details** \u2014 use `gh issue view <number>` to get the title, body, and labels",
+        "2. **Determine branch type** from the issue title prefix:",
+        "   - `feat:` / `feature:` \u2192 `feat/`",
+        "   - `fix:` / `bug:` \u2192 `fix/`",
+        "   - `docs:` \u2192 `docs/`",
+        "   - `chore:` / `refactor:` \u2192 `chore/`",
+        "   - `test:` \u2192 `test/`",
+        "   - No prefix \u2192 `feat/`",
+        "3. **Create a branch** following the naming convention: `<type>/<short-slug>-<issue-number>` (e.g., `feat/add-login-42`)",
+        "4. **Checkout the branch** locally",
+        "5. **Link the branch to the issue** by posting a comment: `gh issue comment <number> --body 'Branch: \\`<branch-name>\\`'`",
+        "6. **Stop and wait** for user instructions \u2014 do **NOT** start implementing",
+        "",
+        "### Important",
+        "",
+        "- Never begin implementation without explicit user direction",
+        "- If the issue title has no conventional prefix, default to `feat/`",
+        "- Keep the slug short (3-5 words max, kebab-case)"
+      ].join("\n"),
+      tags: ["workflow"]
+    },
+    {
+      name: "pr-workflow",
+      description: "Automated workflow for opening a pull request",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# PR Workflow",
+        "",
+        '## "Open a PR" Automation',
+        "",
+        "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. **Push the branch** to origin: `git push -u origin <branch>`",
+        "3. **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",
+        "4. **Display merge dialog text** for the user to copy-paste when merging:",
+        "",
+        "```",
+        "Commit message:",
+        "<conventional-commit-title>",
+        "",
+        "Extended description:",
+        "- Bullet points summarizing the changes",
+        "- Closes #<issue-number>",
+        "```",
+        "",
+        "### PR Body Template",
+        "",
+        "```markdown",
+        "## Summary",
+        "",
+        "<1-3 bullet points describing what changed and why>",
+        "",
+        "Closes #<issue-number>",
+        "",
+        "## Test Plan",
+        "",
+        "- [ ] Tests pass locally",
+        "- [ ] Relevant changes have been reviewed",
+        "```",
+        "",
+        "### Important",
+        "",
+        "- Always derive the issue number from the branch name (e.g., `feat/add-login-42` \u2192 `#42`)",
+        "- Use conventional commit format for the PR title",
+        "- Do not merge the PR \u2014 only create it and display the merge text"
+      ].join("\n"),
+      tags: ["workflow"]
+    }
+  ]
+};
+
 // src/agent/bundles/jest.ts
 var jestBundle = {
   name: "jest",
@@ -771,6 +916,28 @@ var projenBundle = {
   description: "Projen conventions, synthesis workflow, .projenrc.ts patterns",
   appliesWhen: (project) => hasDep(project, "projen"),
   rules: [
+    {
+      name: "projen-sandbox-restrictions",
+      description: "Commands the agent must never run in Projen-managed projects",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Projen Sandbox Restrictions",
+        "",
+        "## Prohibited Commands",
+        "",
+        "The agent must **never** run the following commands \u2014 always ask the user to run them instead:",
+        "",
+        "- `pnpm install` / `pnpm i` \u2014 modifies the lockfile and may trigger synthesis",
+        "- `npx projen` \u2014 synthesizes generated files and must be run by the user",
+        "",
+        "## Rationale",
+        "",
+        "Projen-managed projects rely on synthesized files (`package.json`, `tsconfig.json`, etc.) that are regenerated from `.projenrc.ts`.",
+        "Running install or synthesis in the agent's sandbox can cause lockfile drift, phantom dependency changes, or overwrite user-controlled configuration.",
+        "The user must run these commands locally so they can review the resulting changes."
+      ].join("\n"),
+      tags: ["workflow", "safety"]
+    },
     {
       name: "projen-conventions",
       description: "Projen configuration patterns and best practices",
@@ -787,6 +954,41 @@ var projenBundle = {
         "  - `projenrc/*.ts` (package-specific)",
         "- After making Projen changes, ask the user to run `npx projen` locally (agent must not run it)",
         "",
+        "## DO NOT Use Manual Package Manager Commands",
+        "",
+        "- **Never** run `pnpm add`, `pnpm remove`, `npm install`, or `yarn add` to modify dependencies",
+        "- Dependencies must be added through Projen configuration (e.g., `project.addDeps()`, `project.addDevDeps()`)",
+        "- Manual package manager commands bypass Projen's dependency management and will be overwritten on the next synthesis",
+        "- Correct workflow: edit `.projenrc.ts` \u2192 ask user to run `npx projen` \u2192 user runs `pnpm install` if needed",
+        "",
+        "## Workspace Dependencies",
+        "",
+        "When adding dependencies between packages in a monorepo:",
+        "",
+        '- Use the workspace protocol: `project.addDeps("@org/sibling-pkg@workspace:*")`',
+        "- This ensures the local version is always resolved, not a registry version",
+        '- For dev dependencies: `project.addDevDeps("@org/sibling-pkg@workspace:*")`',
+        "",
+        "## The `configureMyProject` Pattern",
+        "",
+        "Each package should expose a `configureMyProject(options)` factory function that creates and configures its Projen project:",
+        "",
+        "```typescript",
+        "export function configureMyProject(",
+        "  options: MyProjectOptions,",
+        "): TypeScriptProject {",
+        "  const project = new TypeScriptProject({",
+        "    ...options,",
+        "    // package-specific defaults",
+        "  });",
+        "",
+        "  // Attach components, configure rules, etc.",
+        "  return project;",
+        "}",
+        "```",
+        "",
+        "This pattern keeps `.projenrc.ts` clean and makes package configuration reusable and testable.",
+        "",
         "## Custom Projen Components",
         "",
         "All custom components must extend `Component` from Projen and use a static `.of()` factory for discovery:",
@@ -1165,7 +1367,27 @@ var typescriptBundle = {
         "- **Functions/Methods**: camelCase (e.g., `configureProject`)",
         "- **Constants**: UPPER_SNAKE_CASE (e.g., `VERSION`, `AWS_STAGE_TYPE`)",
         "- **Files**: kebab-case for multi-word files (e.g., `aws-deployment-config.ts`)",
-        "- **Private members**: No prefix needed (TypeScript handles visibility)"
+        "- **Component file naming**: kebab-case filename must mirror the PascalCase class name (e.g., `ResetTask` \u2192 `reset-task.ts`)",
+        "- **Private members**: No prefix needed (TypeScript handles visibility)",
+        "",
+        "## Array Type Syntax",
+        "",
+        "- Prefer `Array<T>` over `T[]` for readability",
+        "- For nested generics this is especially important: `Array<Array<string>>` is clearer than `string[][]`",
+        "",
+        "## Enum Preference",
+        "",
+        "- Prefer `as const` objects over TypeScript `enum` declarations",
+        "- `as const` objects are more flexible: they support computed values, work with `keyof typeof`, and tree-shake better",
+        "- Example:",
+        "  ```typescript",
+        "  // Prefer this:",
+        "  const Status = { Active: 'active', Inactive: 'inactive' } as const;",
+        "  type Status = (typeof Status)[keyof typeof Status];",
+        "",
+        "  // Over this:",
+        "  enum Status { Active = 'active', Inactive = 'inactive' }",
+        "  ```"
       ].join("\n"),
       tags: ["coding"]
     }
@@ -1373,7 +1595,8 @@ var BUILT_IN_BUNDLES = [
   turborepoBundle,
   pnpmBundle,
   awsCdkBundle,
-  projenBundle
+  projenBundle,
+  githubWorkflowBundle
 ];
 
 // src/projects/project-metadata.ts
@@ -2204,7 +2427,7 @@ ${extra}`
 };
 
 // src/aws/aws-deployment-config.ts
-var import_utils8 = __toESM(require_lib());
+var import_utils9 = __toESM(require_lib());
 import { join, relative as relative2 } from "path";
 import { Component as Component9 } from "projen";
 var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component9 {
@@ -2262,17 +2485,17 @@ var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component9 {
    */
   get prodTargets() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.PROD
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.PROD
     );
   }
   get prodTargetsForCI() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.PROD && target.ciDeployment
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.PROD && target.ciDeployment
     );
   }
   get prodTargetsForLocal() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.PROD && target.localDeployment
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.PROD && target.localDeployment
     );
   }
   /**
@@ -2281,17 +2504,17 @@ var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component9 {
    */
   get stageTargets() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.STAGE
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.STAGE
     );
   }
   get stageTargetsForCI() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.STAGE && target.ciDeployment
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.STAGE && target.ciDeployment
     );
   }
   get stageTargetsForLocal() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.STAGE && target.localDeployment
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.STAGE && target.localDeployment
     );
   }
   /**
@@ -2300,17 +2523,17 @@ var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component9 {
    */
   get devTargets() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.DEV
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.DEV
     );
   }
   get devTargetsForCI() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.DEV && target.ciDeployment
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.DEV && target.ciDeployment
     );
   }
   get devTargetsForLocal() {
     return this.awsDeploymentTargets.filter(
-      (target) => target.awsStageType === import_utils8.AWS_STAGE_TYPE.DEV && target.localDeployment
+      (target) => target.awsStageType === import_utils9.AWS_STAGE_TYPE.DEV && target.localDeployment
     );
   }
   preSynthesize() {
@@ -2323,7 +2546,7 @@ var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component9 {
 };
 
 // src/aws/aws-deployment-target.ts
-var import_utils9 = __toESM(require_lib());
+var import_utils10 = __toESM(require_lib());
 import { Component as Component10 } from "projen";
 var AwsDeploymentTarget = class _AwsDeploymentTarget extends Component10 {
   constructor(project, options) {
@@ -2390,11 +2613,11 @@ var AwsDeploymentTarget = class _AwsDeploymentTarget extends Component10 {
     };
     this.account = options.account;
     this.region = options.region;
-    this.awsStageType = options.awsStageType || import_utils9.AWS_STAGE_TYPE.DEV;
-    const role = options.deploymentTargetRole ?? options.awsEnvironmentType ?? import_utils9.DEPLOYMENT_TARGET_ROLE.PRIMARY;
+    this.awsStageType = options.awsStageType || import_utils10.AWS_STAGE_TYPE.DEV;
+    const role = options.deploymentTargetRole ?? options.awsEnvironmentType ?? import_utils10.DEPLOYMENT_TARGET_ROLE.PRIMARY;
     this.deploymentTargetRole = role;
     this.awsEnvironmentType = role;
-    this.branches = options.branches ?? (this.awsStageType === import_utils9.AWS_STAGE_TYPE.PROD ? [
+    this.branches = options.branches ?? (this.awsStageType === import_utils10.AWS_STAGE_TYPE.PROD ? [
       {
         branch: "main"
       }
@@ -2403,7 +2626,7 @@ var AwsDeploymentTarget = class _AwsDeploymentTarget extends Component10 {
         branch: "feature/*"
       }
     ]);
-    this.localDeployment = options.localDeployment ?? this.awsStageType === import_utils9.AWS_STAGE_TYPE.DEV;
+    this.localDeployment = options.localDeployment ?? this.awsStageType === import_utils10.AWS_STAGE_TYPE.DEV;
     if (this.localDeployment) {
       const roleName = options.localDeploymentConfig?.roleName?.toLowerCase() || "poweruseraccess";
       const profile = options.localDeploymentConfig?.profile || `${roleName}-${this.awsStageType}-${this.account}-${this.region}`;
@@ -3338,10 +3561,10 @@ var TypeScriptConfig = class extends Component14 {
 };
 
 // src/workflows/aws-deploy-workflow.ts
-var import_utils10 = __toESM(require_lib());
+var import_utils11 = __toESM(require_lib());
 import { Component as Component15 } from "projen";
 import { BuildWorkflow } from "projen/lib/build";
-import { GitHub } from "projen/lib/github";
+import { GitHub as GitHub2 } from "projen/lib/github";
 import { JobPermission as JobPermission4 } from "projen/lib/github/workflows-model";
 var PROD_DEPLOY_NAME = "prod-deploy";
 var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component15 {
@@ -3355,7 +3578,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component15 {
      * @deprecated Use deployment target role terminology elsewhere. This property is maintained for backward compatibility.
      * @default 'primary' (this is the only type supported currently)
      */
-    this.awsEnvironmentType = import_utils10.DEPLOYMENT_TARGET_ROLE.PRIMARY;
+    this.awsEnvironmentType = import_utils11.DEPLOYMENT_TARGET_ROLE.PRIMARY;
     this.setupNode = () => {
       return [
         {
@@ -3457,7 +3680,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component15 {
       );
     }
     this.rootProject = project.root;
-    const github = GitHub.of(this.rootProject);
+    const github = GitHub2.of(this.rootProject);
     if (!github) {
       throw new Error(
         "AwsDeployWorkflow requires a GitHub component in the root project"
@@ -3465,7 +3688,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component15 {
     }
     const turbo = TurboRepo.of(this.rootProject);
     const buildWorkflowOptions = turbo?.remoteCacheOptions ? TurboRepo.buildWorkflowOptions(turbo.remoteCacheOptions) : {};
-    this.awsStageType = options.awsStageType ?? import_utils10.AWS_STAGE_TYPE.DEV;
+    this.awsStageType = options.awsStageType ?? import_utils11.AWS_STAGE_TYPE.DEV;
     this.awsDeploymentTargets = options.awsDeploymentTargets ?? AwsDeploymentConfig.of(project)?.awsDeploymentTargets.filter(
       (target) => target.awsStageType === this.awsStageType && target.ciDeployment
     ) ?? [];
@@ -3644,6 +3867,7 @@ export {
   awsCdkBundle,
   baseBundle,
   getLatestEligibleVersion,
+  githubWorkflowBundle,
   jestBundle,
   pnpmBundle,
   projenBundle,