@codedrifters/configulator 0.0.154 → 0.0.156

package/lib/index.d.ts

@@ -671,6 +671,20 @@ interface AgentConfigOptions {
      * Names of individual rules to exclude from any source.
      */
     readonly excludeRules?: ReadonlyArray<string>;
+    /**
+     * Additional content to append to existing rules (from bundles or custom rules).
+     * Keys are rule names, values are markdown content appended after a horizontal rule.
+     * Use this to supplement bundle rules with project-specific additions without
+     * replacing the entire rule.
+     *
+     * @example
+     * ```ts
+     * ruleExtensions: {
+     *   'typescript-conventions': '## Additional Conventions\n\n- Use branded types for IDs',
+     * }
+     * ```
+     */
+    readonly ruleExtensions?: Readonly<Record<string, string>>;
     /**
      * Claude Code settings.json configuration.
      * Generated to .claude/settings.json (committed, team-shared).
@@ -718,16 +732,326 @@ declare class AgentConfig extends Component {
     private resolveRules;
     private resolveSkills;
     private resolveSubAgents;
+    /**
+     * Resolves template variables in rule content using project metadata.
+     * Emits synthesis warnings for rules with unresolved variables.
+     */
+    private resolveTemplates;
+    /**
+     * Resolves template variables in skill instructions using project metadata.
+     */
+    private resolveSkillTemplates;
+    /**
+     * Resolves template variables in sub-agent prompts using project metadata.
+     */
+    private resolveSubAgentTemplates;
 }
 
+/**
+ * AWS CDK bundle — auto-detected when `aws-cdk-lib` is in dependencies.
+ */
+declare const awsCdkBundle: AgentRuleBundle;
+
+/**
+ * Base bundle — always included unless `includeBaseRules: false`.
+ * Contains project-overview, interaction-style, and general-conventions rules.
+ */
+declare const baseBundle: AgentRuleBundle;
+
+/**
+ * Jest bundle — auto-detected when Jest is in dependencies.
+ */
+declare const jestBundle: AgentRuleBundle;
+
+/**
+ * PNPM bundle — auto-detected when the PnpmWorkspace component is present.
+ */
+declare const pnpmBundle: AgentRuleBundle;
+
+/**
+ * Projen bundle — auto-detected when `projen` is in dependencies.
+ */
+declare const projenBundle: AgentRuleBundle;
+
+/**
+ * Turborepo bundle — auto-detected when the TurboRepo component is present.
+ */
+declare const turborepoBundle: AgentRuleBundle;
+
+/**
+ * TypeScript bundle — auto-detected when a tsconfig is present.
+ */
+declare const typescriptBundle: AgentRuleBundle;
+
+/**
+ * Vitest bundle — auto-detected when the Vitest component is present.
+ */
+declare const vitestBundle: AgentRuleBundle;
+
 /**
  * Built-in rule bundles that ship with configulator.
  * Each bundle is auto-detected based on project introspection.
  *
- * Actual bundles are added in issue #101.
+ * Order matters: base is first so its rules can be overridden by
+ * more specific bundles. The base bundle's `appliesWhen` always
+ * returns true; it is filtered by the `includeBaseRules` option
+ * in AgentConfig.
  */
 declare const BUILT_IN_BUNDLES: ReadonlyArray<AgentRuleBundle>;
 
+/*******************************************************************************
+ *
+ * Repository Metadata
+ *
+ ******************************************************************************/
+/**
+ * Repository identity. Required fields are auto-detected when not provided.
+ */
+interface RepositoryMetadata {
+    /**
+     * Repository owner (GitHub user or organization).
+     * Auto-detected from package.json repository URL when not provided.
+     * @example 'codedrifters'
+     */
+    readonly owner?: string;
+    /**
+     * Repository name.
+     * Auto-detected from package.json repository URL when not provided.
+     * @example 'packages'
+     */
+    readonly name?: string;
+    /**
+     * Default branch name.
+     * @default 'main'
+     */
+    readonly defaultBranch?: string;
+}
+/*******************************************************************************
+ *
+ * GitHub Projects Metadata
+ *
+ ******************************************************************************/
+/**
+ * A board or view within a GitHub Project.
+ */
+interface GitHubBoardMetadata {
+    /** Board/view name. */
+    readonly name: string;
+    /** Board/view ID. */
+    readonly id?: string;
+}
+/**
+ * Sprint/iteration field metadata for GitHub Projects.
+ */
+interface GitHubSprintMetadata {
+    /** Name of the iteration field in GitHub Projects. */
+    readonly fieldName?: string;
+    /** Current sprint/iteration name. */
+    readonly current?: string;
+    /** Known sprint/iteration names. */
+    readonly iterations?: ReadonlyArray<string>;
+}
+/**
+ * GitHub Projects (v2) context for workflow automation.
+ */
+interface GitHubProjectMetadata {
+    /**
+     * GitHub Project name.
+     * @example 'CodeDrifters Packages'
+     */
+    readonly name?: string;
+    /**
+     * GitHub Project number (visible in the project URL).
+     * @example 3
+     */
+    readonly number?: number;
+    /**
+     * GitHub Project node ID (for GraphQL API).
+     * @example 'PVT_kwHOABCDEf4AGHIJ'
+     */
+    readonly nodeId?: string;
+    /**
+     * Board or view definitions within the project.
+     */
+    readonly boards?: ReadonlyArray<GitHubBoardMetadata>;
+    /**
+     * Sprint/iteration field metadata.
+     */
+    readonly sprints?: GitHubSprintMetadata;
+    /**
+     * Kanban column (status field) definitions.
+     * @example [{ name: 'To Do', id: 'status_1' }, { name: 'In Progress', id: 'status_2' }]
+     */
+    readonly columns?: ReadonlyArray<{
+        readonly name: string;
+        readonly id?: string;
+    }>;
+}
+/*******************************************************************************
+ *
+ * Organization Metadata
+ *
+ ******************************************************************************/
+/**
+ * Organization or team context.
+ */
+interface OrganizationMetadata {
+    /**
+     * Organization or team display name.
+     * Used in generated documentation and rule content.
+     * @example 'CodeDrifters'
+     */
+    readonly name?: string;
+    /**
+     * GitHub organization login (may differ from display name).
+     * @example 'codedrifters'
+     */
+    readonly githubOrg?: string;
+}
+/*******************************************************************************
+ *
+ * Slack Metadata
+ *
+ ******************************************************************************/
+/**
+ * Slack channel references for workflow skills.
+ */
+interface SlackMetadata {
+    /**
+     * Primary project channel.
+     * @example '#packages-dev'
+     */
+    readonly projectChannel?: string;
+    /**
+     * Alerts or notifications channel.
+     * @example '#packages-alerts'
+     */
+    readonly alertsChannel?: string;
+    /**
+     * Additional named channels. Keys are purpose identifiers.
+     * @example { releases: '#releases', support: '#customer-support' }
+     */
+    readonly channels?: Readonly<Record<string, string>>;
+}
+/*******************************************************************************
+ *
+ * Deployment Metadata
+ *
+ ******************************************************************************/
+/**
+ * Deployment and environment hints.
+ */
+interface DeploymentMetadata {
+    /**
+     * AWS account ID for the primary deployment target.
+     * @example '123456789012'
+     */
+    readonly awsAccountId?: string;
+    /**
+     * Primary AWS region.
+     * @example 'us-east-1'
+     */
+    readonly awsRegion?: string;
+    /**
+     * Named environments.
+     * @example { dev: { accountId: '111', region: 'us-east-1' }, prod: { accountId: '222', region: 'us-east-1' } }
+     */
+    readonly environments?: Readonly<Record<string, {
+        readonly accountId?: string;
+        readonly region?: string;
+    }>>;
+}
+/*******************************************************************************
+ *
+ * ProjectMetadata Options & Resolved Shape
+ *
+ ******************************************************************************/
+/**
+ * Options for the ProjectMetadata component.
+ */
+interface ProjectMetadataOptions {
+    /**
+     * Repository identity. When omitted, auto-detected from the Projen
+     * project's package.json repository field.
+     */
+    readonly repository?: RepositoryMetadata;
+    /**
+     * GitHub Projects (v2) context for workflow automation.
+     * Optional — only needed when skills or rules reference project boards.
+     */
+    readonly githubProject?: GitHubProjectMetadata;
+    /**
+     * Organization or team metadata.
+     * Optional — used in branch naming, PR conventions, and rule content.
+     */
+    readonly organization?: OrganizationMetadata;
+    /**
+     * Slack channel references for workflow skills.
+     * Optional — only needed when skills post to or reference Slack channels.
+     */
+    readonly slack?: SlackMetadata;
+    /**
+     * Important label names used by the project.
+     * Optional — allows skills and rules to reference canonical labels.
+     * @example ['auto-approve', 'wontfix', 'breaking-change']
+     */
+    readonly labels?: ReadonlyArray<string>;
+    /**
+     * Milestone names or IDs for release planning.
+     * Optional — allows skills to reference milestones by name.
+     */
+    readonly milestones?: ReadonlyArray<string>;
+    /**
+     * Documentation base path (relative to repo root) or external URL.
+     * Optional — used by "reference docs" skills to point to the right location.
+     * @example 'docs/' or 'https://docs.example.com'
+     */
+    readonly docsPath?: string;
+    /**
+     * Deployment or environment hints.
+     * Optional — used by deploy-related skills or rules.
+     */
+    readonly deployment?: DeploymentMetadata;
+}
+/**
+ * Resolved project metadata with auto-detected values filled in.
+ * Consumed by AgentConfig and other configulator features at synthesis time.
+ */
+interface ResolvedProjectMetadata {
+    readonly repository: {
+        readonly owner: string | undefined;
+        readonly name: string | undefined;
+        /** Always has a value (default: 'main'). */
+        readonly defaultBranch: string;
+    };
+    readonly githubProject?: GitHubProjectMetadata;
+    readonly organization?: OrganizationMetadata;
+    readonly slack?: SlackMetadata;
+    readonly labels?: ReadonlyArray<string>;
+    readonly milestones?: ReadonlyArray<string>;
+    readonly docsPath?: string;
+    readonly deployment?: DeploymentMetadata;
+}
+
+/**
+ * Result of template variable resolution.
+ */
+interface TemplateResolveResult {
+    /** The template string with all variables resolved or replaced with fallbacks. */
+    readonly resolved: string;
+    /** Template variable keys that could not be resolved from metadata. */
+    readonly unresolvedKeys: ReadonlyArray<string>;
+}
+/**
+ * Resolves `{{dotted.path}}` template variables in a string using project metadata.
+ * Unresolved variables are replaced with their fallback placeholders.
+ *
+ * @param template - String potentially containing `{{variable}}` patterns
+ * @param metadata - Resolved project metadata, or undefined if not available
+ * @returns The resolved string and a list of any unresolved variable keys
+ */
+declare function resolveTemplateVariables(template: string, metadata: ResolvedProjectMetadata | undefined): TemplateResolveResult;
+
 /*******************************************************************************
  *
  * Git configs for this repo. This venn diagram has a great deal of overlap
@@ -2037,6 +2361,30 @@ interface MonorepoProjectOptions extends Omit<TypeScriptProjectOptions$1, "defau
      * @default true
      */
     readonly configulatorRegistryConsumer?: boolean;
+    /**
+     * Project metadata configuration. Provides repository identity,
+     * GitHub project context, and organizational details consumed by
+     * AgentConfig and other features at synthesis time.
+     *
+     * - `undefined` or `{}`: auto-instantiate with auto-detection (default)
+     * - `ProjectMetadataOptions`: explicit metadata configuration
+     * - `false`: disable ProjectMetadata entirely
+     *
+     * @default {} (auto-detect from package.json)
+     */
+    readonly projectMetadata?: ProjectMetadataOptions | false;
+    /**
+     * Enable AI agent configuration (Cursor, Claude Code rules).
+     * When true, generates rule files at the monorepo root with auto-detected
+     * bundles based on project and subproject introspection.
+     *
+     * @default false
+     */
+    readonly agentConfig?: boolean;
+    /**
+     * Options for the AgentConfig component. Only used when `agentConfig` is true.
+     */
+    readonly agentConfigOptions?: AgentConfigOptions;
 }
 declare class MonorepoProject extends TypeScriptAppProject {
     /**
@@ -2061,6 +2409,38 @@ declare class MonorepoProject extends TypeScriptAppProject {
     postSynthesize(): void;
 }
 
+/**
+ * Provides structured project metadata consumed by AgentConfig, skills,
+ * and other configulator features at synthesis time.
+ *
+ * This is a project-level component — it describes the project itself,
+ * not any specific feature. It lives alongside MonorepoProject and
+ * TypeScriptProject and is discovered by consumers via the static
+ * `.of()` factory method.
+ */
+declare class ProjectMetadata extends Component {
+    /**
+     * Returns the ProjectMetadata instance for a project, or undefined
+     * if the component has not been added.
+     */
+    static of(project: Project): ProjectMetadata | undefined;
+    /** Resolved metadata with auto-detected values filled in. */
+    readonly metadata: ResolvedProjectMetadata;
+    constructor(project: Project, options?: ProjectMetadataOptions);
+    /**
+     * 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.
+     */
+    private resolveMetadata;
+    /**
+     * Attempts to auto-detect repository owner and name from the Projen
+     * project's package.json repository field.
+     */
+    private autoDetectRepository;
+}
+
 /**
  * Options for the Vitest config (test block in vitest.config).
  *
@@ -2309,5 +2689,5 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, getLatestEligibleVersion };
-export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AwsAccount, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, GitBranch, IDependencyResolver, McpServerConfig, McpTransport, MergeMethod, MonorepoProjectOptions, PnpmWorkspaceOptions, RemoteCacheOptions, ResetTaskOptions, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, awsCdkBundle, baseBundle, getLatestEligibleVersion, jestBundle, pnpmBundle, projenBundle, resolveTemplateVariables, turborepoBundle, typescriptBundle, vitestBundle };
+export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AwsAccount, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, McpServerConfig, McpTransport, MergeMethod, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };