@codedrifters/configulator 0.0.154 → 0.0.156

package/lib/index.d.mts

@@ -622,6 +622,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).
@@ -669,16 +683,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
@@ -1988,6 +2312,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 {
     /**
@@ -2012,6 +2360,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$1): ProjectMetadata | undefined;
+    /** Resolved metadata with auto-detected values filled in. */
+    readonly metadata: ResolvedProjectMetadata;
+    constructor(project: Project$1, 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).
  *
@@ -2260,4 +2640,4 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, type AwsAccount, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, type DeployWorkflowOptions, type GitBranch, type IDependencyResolver, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, type McpServerConfig, type McpTransport, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, ResetTask, type ResetTaskOptions, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, getLatestEligibleVersion };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, type AwsAccount, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, type McpServerConfig, type McpTransport, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type TemplateResolveResult, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, awsCdkBundle, baseBundle, getLatestEligibleVersion, jestBundle, pnpmBundle, projenBundle, resolveTemplateVariables, turborepoBundle, typescriptBundle, vitestBundle };