@codedrifters/configulator 0.0.155 → 0.0.157

package/lib/index.mjs

@@ -173,7 +173,7 @@ var require_lib = __commonJS({
 });
 
 // src/agent/agent-config.ts
-import { Component as Component7 } from "projen";
+import { Component as Component8 } from "projen";
 
 // src/agent/types.ts
 var AGENT_RULE_SCOPE = {
@@ -284,10 +284,109 @@ var awsCdkBundle = {
 };
 
 // src/agent/bundles/base.ts
+var createRuleSkill = {
+  name: "create-rule",
+  description: "Guide for creating new agent rules in this project using configulator",
+  disableModelInvocation: true,
+  instructions: [
+    "# Create Agent Rule",
+    "",
+    "Create a new agent rule for the **{{repository.owner}}/{{repository.name}}** project.",
+    "",
+    "## Steps",
+    "",
+    "1. **Identify the rule purpose** \u2014 ask what behavior the rule should enforce or guide",
+    "2. **Choose a scope:**",
+    "   - `AGENT_RULE_SCOPE.ALWAYS` \u2014 active in all contexts",
+    "   - `AGENT_RULE_SCOPE.FILE_PATTERN` \u2014 active only when working on matching files (requires `filePatterns`)",
+    "3. **Pick a name** \u2014 lowercase kebab-case (e.g., `react-conventions`, `api-error-handling`)",
+    "4. **Write the content** \u2014 clear, actionable markdown instructions",
+    "5. **Add to the project config** \u2014 add the rule to `AgentConfigOptions.rules` in the Projen config file",
+    "",
+    "## Rule Template",
+    "",
+    "```typescript",
+    "import { AGENT_RULE_SCOPE } from '@codedrifters/configulator';",
+    "",
+    "// In your AgentConfig options:",
+    "{",
+    "  rules: [",
+    "    {",
+    "      name: 'my-new-rule',",
+    "      description: 'What this rule does \u2014 used by AI for rule selection',",
+    "      scope: AGENT_RULE_SCOPE.ALWAYS, // or FILE_PATTERN",
+    "      // filePatterns: ['src/**/*.ts'],  // required for FILE_PATTERN scope",
+    "      content: [",
+    "        '# Rule Title',",
+    "        '',",
+    "        '## Guidelines',",
+    "        '',",
+    "        '- Guideline 1',",
+    "        '- Guideline 2',",
+    "      ].join('\\n'),",
+    "      tags: ['coding'], // optional: for ordering",
+    "    },",
+    "  ],",
+    "}",
+    "```",
+    "",
+    "## Best Practices",
+    "",
+    "- Keep rules **focused** \u2014 one concern per rule",
+    '- Use **imperative tone** \u2014 "Use X" not "You should use X"',
+    "- Include **examples** for complex patterns",
+    "- Use `ruleExtensions` to add project-specific content to existing bundle rules instead of replacing them"
+  ].join("\n")
+};
+var reviewPrSkill = {
+  name: "review-pr",
+  description: "Review a pull request for code quality, conventions, and correctness",
+  instructions: [
+    "# Review Pull Request",
+    "",
+    "Review the current pull request in **{{repository.owner}}/{{repository.name}}**.",
+    "",
+    "## Review Checklist",
+    "",
+    "1. **Read the PR description** \u2014 understand the intent and linked issue",
+    "2. **Review the diff** \u2014 check all changed files for:",
+    "   - Correctness and logic errors",
+    "   - Adherence to project conventions",
+    "   - Test coverage for new/changed behavior",
+    "   - No unintended side effects",
+    "3. **Check PR conventions:**",
+    "   - Title uses conventional commit prefix (`feat:`, `fix:`, `docs:`, etc.)",
+    "   - Body includes a closing keyword (`Closes #<issue>`)",
+    "   - Summary of changes is present",
+    "4. **Verify build and tests pass**",
+    "",
+    "## Commands",
+    "",
+    "```bash",
+    "# View the PR details",
+    "gh pr view",
+    "",
+    "# View the diff",
+    "gh pr diff",
+    "",
+    "# Check CI status",
+    "gh pr checks",
+    "```",
+    "",
+    "## Output Format",
+    "",
+    "Provide a structured review with:",
+    "- **Summary**: One-line verdict (approve, request changes, or comment)",
+    "- **Findings**: Bulleted list of issues or suggestions, grouped by severity",
+    "- **Positive notes**: What was done well"
+  ].join("\n"),
+  allowedTools: ["Read", "Glob", "Grep", "Bash(gh *)"]
+};
 var baseBundle = {
   name: "base",
   description: "Core rules: project overview, interaction style, and general coding conventions",
   appliesWhen: () => true,
+  skills: [createRuleSkill, reviewPrSkill],
   rules: [
     {
       name: "project-overview",
@@ -296,6 +395,9 @@ var baseBundle = {
       content: [
         "# Project Overview",
         "",
+        "**Repository:** {{repository.owner}}/{{repository.name}}",
+        "**Default branch:** {{repository.defaultBranch}}",
+        "",
         "## Important Notes",
         "",
         "- **Never edit generated files** \u2014 they are marked with `// ~~ Generated by projen`",
@@ -1256,6 +1358,76 @@ var BUILT_IN_BUNDLES = [
   projenBundle
 ];
 
+// src/projects/project-metadata.ts
+import { Component as Component5 } from "projen";
+import { NodeProject as NodeProject2 } from "projen/lib/javascript";
+var GITHUB_HTTPS_RE = /(?:https?:\/\/|git\+https:\/\/)github\.com\/([^/]+)\/([^/.]+)(?:\.git)?/;
+var GITHUB_SSH_RE = /git@github\.com:([^/]+)\/([^/.]+)(?:\.git)?/;
+function parseGitHubUrl(url) {
+  const httpsMatch = url.match(GITHUB_HTTPS_RE);
+  if (httpsMatch) {
+    return { owner: httpsMatch[1], name: httpsMatch[2] };
+  }
+  const sshMatch = url.match(GITHUB_SSH_RE);
+  if (sshMatch) {
+    return { owner: sshMatch[1], name: sshMatch[2] };
+  }
+  return { owner: void 0, name: void 0 };
+}
+var ProjectMetadata = class _ProjectMetadata extends Component5 {
+  /**
+   * Returns the ProjectMetadata instance for a project, or undefined
+   * if the component has not been added.
+   */
+  static of(project) {
+    const isProjectMetadata = (c) => c instanceof _ProjectMetadata;
+    return project.components.find(isProjectMetadata);
+  }
+  constructor(project, options = {}) {
+    super(project);
+    this.metadata = this.resolveMetadata(options);
+  }
+  /**
+   * Merges explicit options with auto-detected values.
+   * Auto-detection reads the repository URL from package.json
+   * (via Projen's NodePackage manifest) and parses GitHub owner/name.
+   * Explicit options always take precedence over auto-detected values.
+   */
+  resolveMetadata(options) {
+    const autoDetected = this.autoDetectRepository();
+    return {
+      repository: {
+        owner: options.repository?.owner ?? autoDetected.owner,
+        name: options.repository?.name ?? autoDetected.name,
+        defaultBranch: options.repository?.defaultBranch ?? "main"
+      },
+      githubProject: options.githubProject,
+      organization: options.organization,
+      slack: options.slack,
+      labels: options.labels,
+      milestones: options.milestones,
+      docsPath: options.docsPath,
+      deployment: options.deployment
+    };
+  }
+  /**
+   * Attempts to auto-detect repository owner and name from the Projen
+   * project's package.json repository field.
+   */
+  autoDetectRepository() {
+    if (!(this.project instanceof NodeProject2)) {
+      return { owner: void 0, name: void 0 };
+    }
+    const manifest = this.project.package.manifest;
+    const repoField = manifest.repository;
+    if (!repoField) {
+      return { owner: void 0, name: void 0 };
+    }
+    const url = typeof repoField === "string" ? repoField : repoField.url ?? "";
+    return parseGitHubUrl(url);
+  }
+};
+
 // src/agent/renderers/claude-renderer.ts
 import { JsonFile as JsonFile2 } from "projen";
 import { TextFile as TextFile2 } from "projen/lib/textfile";
@@ -1485,6 +1657,15 @@ var ClaudeRenderer = class _ClaudeRenderer {
           lines.push(`  - "${p}"`);
         }
       }
+      if (skill.context) {
+        lines.push(`context: "${skill.context}"`);
+      }
+      if (skill.agent) {
+        lines.push(`agent: "${skill.agent}"`);
+      }
+      if (skill.shell) {
+        lines.push(`shell: "${skill.shell}"`);
+      }
       if (skill.allowedTools && skill.allowedTools.length > 0) {
         lines.push(`allowed-tools:`);
         for (const tool of skill.allowedTools) {
@@ -1601,6 +1782,15 @@ var CursorRenderer = class _CursorRenderer {
       if (skill.userInvocable === false) {
         lines.push(`user-invocable: false`);
       }
+      if (skill.context) {
+        lines.push(`context: "${skill.context}"`);
+      }
+      if (skill.agent) {
+        lines.push(`agent: "${skill.agent}"`);
+      }
+      if (skill.shell) {
+        lines.push(`shell: "${skill.shell}"`);
+      }
       if (skill.allowedTools && skill.allowedTools.length > 0) {
         lines.push(`allowed-tools:`);
         for (const tool of skill.allowedTools) {
@@ -1707,8 +1897,57 @@ var CursorRenderer = class _CursorRenderer {
   }
 };
 
+// src/agent/template-resolver.ts
+var FALLBACKS = {
+  "repository.owner": "<owner>",
+  "repository.name": "<repo>",
+  "repository.defaultBranch": "main",
+  "organization.name": "<organization>",
+  "organization.githubOrg": "<org>",
+  "githubProject.name": "<project-name>",
+  "githubProject.number": "<project-number>",
+  "githubProject.nodeId": "<project-node-id>",
+  docsPath: "<docs-path>"
+};
+var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
+function getNestedValue(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[part];
+  }
+  if (current == null) {
+    return void 0;
+  }
+  return String(current);
+}
+function resolveTemplateVariables(template, metadata) {
+  if (!TEMPLATE_RE.test(template)) {
+    return { resolved: template, unresolvedKeys: [] };
+  }
+  const unresolvedKeys = [];
+  TEMPLATE_RE.lastIndex = 0;
+  const resolved = template.replace(TEMPLATE_RE, (_match, key) => {
+    if (metadata) {
+      const value = getNestedValue(
+        metadata,
+        key
+      );
+      if (value !== void 0) {
+        return value;
+      }
+    }
+    unresolvedKeys.push(key);
+    return FALLBACKS[key] ?? `<${key}>`;
+  });
+  return { resolved, unresolvedKeys };
+}
+
 // src/agent/agent-config.ts
-var AgentConfig = class _AgentConfig extends Component7 {
+var AgentConfig = class _AgentConfig extends Component8 {
   /**
    * Find the AgentConfig component on a project.
    */
@@ -1727,12 +1966,20 @@ var AgentConfig = class _AgentConfig extends Component7 {
     const skills = this.resolveSkills();
     const subAgents = this.resolveSubAgents();
     const mcpServers = this.options.mcpServers ?? {};
+    const projectMetadata = ProjectMetadata.of(this.project);
+    const metadata = projectMetadata?.metadata;
+    const resolvedRules = this.resolveTemplates(rules, metadata);
+    const resolvedSkills = this.resolveSkillTemplates(skills, metadata);
+    const resolvedSubAgents = this.resolveSubAgentTemplates(
+      subAgents,
+      metadata
+    );
     if (platforms.includes(AGENT_PLATFORM.CURSOR)) {
       CursorRenderer.render(
         this,
-        rules,
-        skills,
-        subAgents,
+        resolvedRules,
+        resolvedSkills,
+        resolvedSubAgents,
         mcpServers,
         this.options.cursorSettings
       );
@@ -1740,18 +1987,28 @@ var AgentConfig = class _AgentConfig extends Component7 {
     if (platforms.includes(AGENT_PLATFORM.CLAUDE)) {
       ClaudeRenderer.render(
         this,
-        rules,
-        skills,
-        subAgents,
+        resolvedRules,
+        resolvedSkills,
+        resolvedSubAgents,
         mcpServers,
         this.options.claudeSettings
       );
     }
     if (platforms.includes(AGENT_PLATFORM.CODEX)) {
-      CodexRenderer.render(this, rules, skills, subAgents);
+      CodexRenderer.render(
+        this,
+        resolvedRules,
+        resolvedSkills,
+        resolvedSubAgents
+      );
     }
     if (platforms.includes(AGENT_PLATFORM.COPILOT)) {
-      CopilotRenderer.render(this, rules, skills, subAgents);
+      CopilotRenderer.render(
+        this,
+        resolvedRules,
+        resolvedSkills,
+        resolvedSubAgents
+      );
     }
   }
   resolvePlatforms() {
@@ -1854,13 +2111,65 @@ ${extra}`
     }
     return [...agentMap.values()];
   }
+  /**
+   * Resolves template variables in rule content using project metadata.
+   * Emits synthesis warnings for rules with unresolved variables.
+   */
+  resolveTemplates(rules, metadata) {
+    return rules.map((rule) => {
+      const { resolved, unresolvedKeys } = resolveTemplateVariables(
+        rule.content,
+        metadata
+      );
+      if (unresolvedKeys.length > 0) {
+        this.project.logger.warn(
+          `AgentConfig: ProjectMetadata not found; rule '${rule.name}' using default values`
+        );
+      }
+      return resolved !== rule.content ? { ...rule, content: resolved } : rule;
+    });
+  }
+  /**
+   * Resolves template variables in skill instructions using project metadata.
+   */
+  resolveSkillTemplates(skills, metadata) {
+    return skills.map((skill) => {
+      const { resolved, unresolvedKeys } = resolveTemplateVariables(
+        skill.instructions,
+        metadata
+      );
+      if (unresolvedKeys.length > 0) {
+        this.project.logger.warn(
+          `AgentConfig: ProjectMetadata not found; skill '${skill.name}' using default values`
+        );
+      }
+      return resolved !== skill.instructions ? { ...skill, instructions: resolved } : skill;
+    });
+  }
+  /**
+   * Resolves template variables in sub-agent prompts using project metadata.
+   */
+  resolveSubAgentTemplates(subAgents, metadata) {
+    return subAgents.map((agent) => {
+      const { resolved, unresolvedKeys } = resolveTemplateVariables(
+        agent.prompt,
+        metadata
+      );
+      if (unresolvedKeys.length > 0) {
+        this.project.logger.warn(
+          `AgentConfig: ProjectMetadata not found; sub-agent '${agent.name}' using default values`
+        );
+      }
+      return resolved !== agent.prompt ? { ...agent, prompt: resolved } : agent;
+    });
+  }
 };
 
 // src/aws/aws-deployment-config.ts
 var import_utils8 = __toESM(require_lib());
 import { join, relative as relative2 } from "path";
-import { Component as Component8 } from "projen";
-var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component8 {
+import { Component as Component9 } from "projen";
+var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component9 {
   constructor(project) {
     super(project);
     /**
@@ -1977,8 +2286,8 @@ var AwsDeploymentConfig = class _AwsDeploymentConfig extends Component8 {
 
 // src/aws/aws-deployment-target.ts
 var import_utils9 = __toESM(require_lib());
-import { Component as Component9 } from "projen";
-var AwsDeploymentTarget = class _AwsDeploymentTarget extends Component9 {
+import { Component as Component10 } from "projen";
+var AwsDeploymentTarget = class _AwsDeploymentTarget extends Component10 {
   constructor(project, options) {
     super(project);
     /**
@@ -2193,12 +2502,12 @@ var VERSION_KEYS_SKIP = [
 
 // src/jsii/jsii-faker.ts
 import * as spec from "@jsii/spec";
-import { Component as Component10, JsonFile as JsonFile4 } from "projen";
+import { Component as Component11, JsonFile as JsonFile4 } from "projen";
 var ProjenBaseFqn = {
   TYPESCRIPT_PROJECT: "projen.typescript.TypeScriptProject",
   TYPESCRIPT_PROJECT_OPTIONS: "projen.typescript.TypeScriptProjectOptions"
 };
-var JsiiFaker = class _JsiiFaker extends Component10 {
+var JsiiFaker = class _JsiiFaker extends Component11 {
   constructor(project) {
     super(project);
     this.project = project;
@@ -2257,7 +2566,7 @@ import {
 import { merge as merge2 } from "ts-deepmerge";
 
 // src/tasks/reset-task.ts
-import { Component as Component11 } from "projen";
+import { Component as Component12 } from "projen";
 
 // src/projects/typescript-project.ts
 import { typescript } from "projen";
@@ -2432,7 +2741,7 @@ var TypeScriptProject = class extends typescript.TypeScriptProject {
 };
 
 // src/tasks/reset-task.ts
-var ResetTask = class _ResetTask extends Component11 {
+var ResetTask = class _ResetTask extends Component12 {
   constructor(project, options = {}) {
     super(project);
     this.project = project;
@@ -2505,8 +2814,8 @@ var ResetTask = class _ResetTask extends Component11 {
 };
 
 // src/vscode/vscode.ts
-import { Component as Component12, vscode } from "projen";
-var VSCodeConfig = class extends Component12 {
+import { Component as Component13, vscode } from "projen";
+var VSCodeConfig = class extends Component13 {
   constructor(project) {
     super(project);
     const vsConfig = new vscode.VsCode(project);
@@ -2882,6 +3191,12 @@ var MonorepoProject = class extends TypeScriptAppProject {
     if (options.approveMergeUpgradeOptions) {
       addApproveMergeUpgradeWorkflow(this, options.approveMergeUpgradeOptions);
     }
+    if (options.projectMetadata !== false) {
+      new ProjectMetadata(
+        this,
+        typeof options.projectMetadata === "object" ? options.projectMetadata : {}
+      );
+    }
     if (options.agentConfig) {
       new AgentConfig(this, options.agentConfigOptions);
     }
@@ -2943,9 +3258,9 @@ var MonorepoProject = class extends TypeScriptAppProject {
 
 // src/typescript/typescript-config.ts
 import { relative as relative3 } from "path";
-import { Component as Component13 } from "projen";
+import { Component as Component14 } from "projen";
 import { ensureRelativePathStartsWithDot } from "projen/lib/util/path";
-var TypeScriptConfig = class extends Component13 {
+var TypeScriptConfig = class extends Component14 {
   constructor(project) {
     super(project);
     let tsPaths = {};
@@ -2973,12 +3288,12 @@ var TypeScriptConfig = class extends Component13 {
 
 // src/workflows/aws-deploy-workflow.ts
 var import_utils10 = __toESM(require_lib());
-import { Component as Component14 } from "projen";
+import { Component as Component15 } from "projen";
 import { BuildWorkflow } from "projen/lib/build";
 import { GitHub } 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 Component14 {
+var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component15 {
   constructor(project, options = {}) {
     super(project);
     this.project = project;
@@ -3259,6 +3574,7 @@ export {
   MonorepoProject,
   PROD_DEPLOY_NAME,
   PnpmWorkspace,
+  ProjectMetadata,
   ROOT_CI_TASK_NAME,
   ROOT_TURBO_TASK_NAME,
   ResetTask,
@@ -3280,6 +3596,7 @@ export {
   jestBundle,
   pnpmBundle,
   projenBundle,
+  resolveTemplateVariables,
   turborepoBundle,
   typescriptBundle,
   vitestBundle