@codedrifters/configulator 0.0.237 → 0.0.239

package/lib/index.d.mts

@@ -2721,6 +2721,77 @@ declare class AwsDeployWorkflow extends Component {
     preSynthesize(): void;
 }
 
+/**
+ * Canonical top-level folders for a configulator monorepo (ADR-006).
+ *
+ * Every sub-project must live under one of these roots. `DOCS` is a
+ * singleton (the single Starlight site at `/docs`); `APPS`, `PACKAGES`,
+ * and `SITES` are parents for `@scope/<name>` sub-projects.
+ *
+ * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+ */
+declare const MONOREPO_LAYOUT: {
+    readonly DOCS: "docs";
+    readonly APPS: "apps";
+    readonly PACKAGES: "packages";
+    readonly SITES: "sites";
+};
+type MonorepoLayoutRoot = (typeof MONOREPO_LAYOUT)[keyof typeof MONOREPO_LAYOUT];
+/**
+ * How `MonorepoProject` reacts when a sub-project's `outdir` falls outside
+ * the root expected for its project type (see ADR-006 §4).
+ *
+ * - `"off"` — no validation runs.
+ * - `"warn"` — log a console warning per offending sub-project; synth proceeds.
+ * - `"error"` — throw on the first offending sub-project; synth fails.
+ */
+declare const LAYOUT_ENFORCEMENT: {
+    readonly OFF: "off";
+    readonly WARN: "warn";
+    readonly ERROR: "error";
+};
+type LayoutEnforcement = (typeof LAYOUT_ENFORCEMENT)[keyof typeof LAYOUT_ENFORCEMENT];
+/**
+ * Mapping from configulator project-type class name to the root folder its
+ * `outdir` must live under.
+ *
+ * We key by class name (not class reference) so this module stays free of
+ * import cycles with the project-type files that validate against it.
+ * `StarlightProject` maps to `DOCS` because the docs-singleton rule says
+ * Starlight is only ever used as the monorepo-wide docs site.
+ *
+ * @see ADR-006 §4 — Configulator project-type → `outdir` mapping
+ */
+declare const LAYOUT_ROOT_BY_PROJECT_TYPE: Readonly<Record<string, MonorepoLayoutRoot>>;
+/**
+ * A single offender reported by {@link validateMonorepoLayout}. One entry
+ * per sub-project whose `outdir` falls outside its expected root.
+ */
+interface LayoutViolation {
+    readonly projectName: string;
+    readonly projectType: string;
+    readonly outdir: string;
+    readonly expectedRoot: MonorepoLayoutRoot;
+}
+/**
+ * Inspect every sub-project of `root` and collect those whose `outdir` does
+ * not live under the root expected for their project class (ADR-006 §4).
+ *
+ * - Sub-projects whose class name is not in
+ *   {@link LAYOUT_ROOT_BY_PROJECT_TYPE} are skipped — the contract only
+ *   covers the four documented project types.
+ * - The root project itself is skipped (it *is* the monorepo root, not a
+ *   sub-project).
+ * - `outdir` comparison is done in POSIX form against the project root so
+ *   absolute paths synthesised on Windows still match.
+ */
+declare function validateMonorepoLayout(root: Project$1): Array<LayoutViolation>;
+/**
+ * Render one {@link LayoutViolation} as an actionable, single-line error
+ * message pointing the reader at ADR-006.
+ */
+declare function formatLayoutViolation(violation: LayoutViolation): string;
+
 /**
  * Each of the below options corresponds to a task property found here:
  *  * https://turborepo.com/docs/reference/configuration#defining-tasks
@@ -3303,6 +3374,22 @@ interface MonorepoProjectOptions extends Omit<TypeScriptProjectOptions$1, "defau
      * @default true
      */
     readonly syncLabels?: SyncLabelsOptions | boolean;
+    /**
+     * How to react when a sub-project's `outdir` falls outside the root
+     * expected for its project type (ADR-006 §4).
+     *
+     * - `"off"` — skip validation entirely.
+     * - `"warn"` — log a console warning per violation; synth proceeds.
+     * - `"error"` — throw on the first violation; synth fails.
+     *
+     * Defaults to `"warn"` during the ADR-006 rollout so existing consumers
+     * with legacy outdirs see actionable warnings but do not break. A future
+     * release will flip the default to `"error"`.
+     *
+     * @default "warn"
+     * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+     */
+    readonly layoutEnforcement?: LayoutEnforcement;
 }
 declare class MonorepoProject extends TypeScriptAppProject {
     /**
@@ -3313,7 +3400,22 @@ declare class MonorepoProject extends TypeScriptAppProject {
      * Whether this monorepo consumes configulator from a registry (drives upgrade workflow steps).
      */
     readonly configulatorRegistryConsumer: boolean;
+    /**
+     * Layout-enforcement mode for sub-project `outdir` validation (ADR-006).
+     */
+    readonly layoutEnforcement: LayoutEnforcement;
     constructor(userOptions: MonorepoProjectOptions);
+    /**
+     * Validate sub-project `outdir` values against the ADR-006 monorepo
+     * layout contract. Runs in `preSynthesize` so all sub-projects are
+     * attached by the time we inspect the tree.
+     *
+     * Behavior is controlled by `layoutEnforcement`:
+     * - `"off"`  — skip validation.
+     * - `"warn"` — log a `console.warn` per violation; continue.
+     * - `"error"` — throw on the first violation.
+     */
+    preSynthesize(): void;
     /**
      * Allows a sub project to request installation of dependency at the Monorepo root
      * They must provide a function that is executed after dependencies have been installed
@@ -3636,4 +3738,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 AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, 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 CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, type LabelDefinition, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, type McpServerConfig, type McpTransport, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightSidebarItem, type StarlightSocialLink, type SyncLabelsOptions, 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, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, 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 CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightSidebarItem, type StarlightSocialLink, type SyncLabelsOptions, 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, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, vitestBundle };

package/lib/index.d.ts

@@ -2770,6 +2770,77 @@ declare class AwsDeployWorkflow extends Component {
     preSynthesize(): void;
 }
 
+/**
+ * Canonical top-level folders for a configulator monorepo (ADR-006).
+ *
+ * Every sub-project must live under one of these roots. `DOCS` is a
+ * singleton (the single Starlight site at `/docs`); `APPS`, `PACKAGES`,
+ * and `SITES` are parents for `@scope/<name>` sub-projects.
+ *
+ * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+ */
+declare const MONOREPO_LAYOUT: {
+    readonly DOCS: "docs";
+    readonly APPS: "apps";
+    readonly PACKAGES: "packages";
+    readonly SITES: "sites";
+};
+type MonorepoLayoutRoot = (typeof MONOREPO_LAYOUT)[keyof typeof MONOREPO_LAYOUT];
+/**
+ * How `MonorepoProject` reacts when a sub-project's `outdir` falls outside
+ * the root expected for its project type (see ADR-006 §4).
+ *
+ * - `"off"` — no validation runs.
+ * - `"warn"` — log a console warning per offending sub-project; synth proceeds.
+ * - `"error"` — throw on the first offending sub-project; synth fails.
+ */
+declare const LAYOUT_ENFORCEMENT: {
+    readonly OFF: "off";
+    readonly WARN: "warn";
+    readonly ERROR: "error";
+};
+type LayoutEnforcement = (typeof LAYOUT_ENFORCEMENT)[keyof typeof LAYOUT_ENFORCEMENT];
+/**
+ * Mapping from configulator project-type class name to the root folder its
+ * `outdir` must live under.
+ *
+ * We key by class name (not class reference) so this module stays free of
+ * import cycles with the project-type files that validate against it.
+ * `StarlightProject` maps to `DOCS` because the docs-singleton rule says
+ * Starlight is only ever used as the monorepo-wide docs site.
+ *
+ * @see ADR-006 §4 — Configulator project-type → `outdir` mapping
+ */
+declare const LAYOUT_ROOT_BY_PROJECT_TYPE: Readonly<Record<string, MonorepoLayoutRoot>>;
+/**
+ * A single offender reported by {@link validateMonorepoLayout}. One entry
+ * per sub-project whose `outdir` falls outside its expected root.
+ */
+interface LayoutViolation {
+    readonly projectName: string;
+    readonly projectType: string;
+    readonly outdir: string;
+    readonly expectedRoot: MonorepoLayoutRoot;
+}
+/**
+ * Inspect every sub-project of `root` and collect those whose `outdir` does
+ * not live under the root expected for their project class (ADR-006 §4).
+ *
+ * - Sub-projects whose class name is not in
+ *   {@link LAYOUT_ROOT_BY_PROJECT_TYPE} are skipped — the contract only
+ *   covers the four documented project types.
+ * - The root project itself is skipped (it *is* the monorepo root, not a
+ *   sub-project).
+ * - `outdir` comparison is done in POSIX form against the project root so
+ *   absolute paths synthesised on Windows still match.
+ */
+declare function validateMonorepoLayout(root: Project): Array<LayoutViolation>;
+/**
+ * Render one {@link LayoutViolation} as an actionable, single-line error
+ * message pointing the reader at ADR-006.
+ */
+declare function formatLayoutViolation(violation: LayoutViolation): string;
+
 /**
  * Each of the below options corresponds to a task property found here:
  *  * https://turborepo.com/docs/reference/configuration#defining-tasks
@@ -3352,6 +3423,22 @@ interface MonorepoProjectOptions extends Omit<TypeScriptProjectOptions$1, "defau
      * @default true
      */
     readonly syncLabels?: SyncLabelsOptions | boolean;
+    /**
+     * How to react when a sub-project's `outdir` falls outside the root
+     * expected for its project type (ADR-006 §4).
+     *
+     * - `"off"` — skip validation entirely.
+     * - `"warn"` — log a console warning per violation; synth proceeds.
+     * - `"error"` — throw on the first violation; synth fails.
+     *
+     * Defaults to `"warn"` during the ADR-006 rollout so existing consumers
+     * with legacy outdirs see actionable warnings but do not break. A future
+     * release will flip the default to `"error"`.
+     *
+     * @default "warn"
+     * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+     */
+    readonly layoutEnforcement?: LayoutEnforcement;
 }
 declare class MonorepoProject extends TypeScriptAppProject {
     /**
@@ -3362,7 +3449,22 @@ declare class MonorepoProject extends TypeScriptAppProject {
      * Whether this monorepo consumes configulator from a registry (drives upgrade workflow steps).
      */
     readonly configulatorRegistryConsumer: boolean;
+    /**
+     * Layout-enforcement mode for sub-project `outdir` validation (ADR-006).
+     */
+    readonly layoutEnforcement: LayoutEnforcement;
     constructor(userOptions: MonorepoProjectOptions);
+    /**
+     * Validate sub-project `outdir` values against the ADR-006 monorepo
+     * layout contract. Runs in `preSynthesize` so all sub-projects are
+     * attached by the time we inspect the tree.
+     *
+     * Behavior is controlled by `layoutEnforcement`:
+     * - `"off"`  — skip validation.
+     * - `"warn"` — log a `console.warn` per violation; continue.
+     * - `"error"` — throw on the first violation.
+     */
+    preSynthesize(): void;
     /**
      * Allows a sub project to request installation of dependency at the Monorepo root
      * They must provide a function that is executed after dependencies have been installed
@@ -3685,5 +3787,5 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };
-export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, McpServerConfig, McpTransport, MergeMethod, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightSidebarItem, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, vitestBundle };
+export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, LayoutEnforcement, LayoutViolation, McpServerConfig, McpTransport, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightSidebarItem, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };

package/lib/index.js

@@ -195,10 +195,13 @@ __export(index_exports, {
   DEFAULT_TEARDOWN_BRANCH_PATTERNS: () => DEFAULT_TEARDOWN_BRANCH_PATTERNS,
   DEFAULT_TYPE_LABELS: () => DEFAULT_TYPE_LABELS,
   JsiiFaker: () => JsiiFaker,
+  LAYOUT_ENFORCEMENT: () => LAYOUT_ENFORCEMENT,
+  LAYOUT_ROOT_BY_PROJECT_TYPE: () => LAYOUT_ROOT_BY_PROJECT_TYPE,
   MCP_TRANSPORT: () => MCP_TRANSPORT,
   MERGE_METHODS: () => MERGE_METHODS,
   MIMIMUM_RELEASE_AGE: () => MIMIMUM_RELEASE_AGE,
   MINIMUM_RELEASE_AGE: () => MINIMUM_RELEASE_AGE,
+  MONOREPO_LAYOUT: () => MONOREPO_LAYOUT,
   MonorepoProject: () => MonorepoProject,
   PROD_DEPLOY_NAME: () => PROD_DEPLOY_NAME,
   PnpmWorkspace: () => PnpmWorkspace,
@@ -225,6 +228,7 @@ __export(index_exports, {
   baseBundle: () => baseBundle,
   bcmWriterBundle: () => bcmWriterBundle,
   companyProfileBundle: () => companyProfileBundle,
+  formatLayoutViolation: () => formatLayoutViolation,
   getLatestEligibleVersion: () => getLatestEligibleVersion,
   githubWorkflowBundle: () => githubWorkflowBundle,
   industryDiscoveryBundle: () => industryDiscoveryBundle,
@@ -246,6 +250,7 @@ __export(index_exports, {
   softwareProfileBundle: () => softwareProfileBundle,
   turborepoBundle: () => turborepoBundle,
   typescriptBundle: () => typescriptBundle,
+  validateMonorepoLayout: () => validateMonorepoLayout,
   vitestBundle: () => vitestBundle
 });
 module.exports = __toCommonJS(index_exports);
@@ -537,7 +542,7 @@ var baseBundle = {
         "## Important Notes",
         "",
         "- **Never edit generated files** \u2014 they are marked with `// ~~ Generated by projen`",
-        "- **After modifying Projen configuration**, run `npx projen` to regenerate files, then `pnpm install` to update the lockfile.",
+        "- **After modifying Projen configuration**, run `pnpm exec projen` to regenerate files, then `pnpm install` to update the lockfile.",
         "- **Configure dependencies through Projen** \u2014 never use `npm install`, `pnpm add`, or `yarn add`. Add them to `deps` or `devDeps` in Projen config.",
         "- **Export from index.ts** to maintain clean public APIs"
       ].join("\n"),
@@ -554,7 +559,7 @@ var baseBundle = {
         "",
         "## Prohibited Commands",
         "",
-        "- `npx projen` \u2014 synthesize project files",
+        "- `pnpm exec 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",
@@ -567,7 +572,7 @@ var baseBundle = {
         "",
         "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`",
+        "1. **After projen config changes** \u2014 tell the user to run `pnpm exec 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"),
@@ -2525,7 +2530,7 @@ var githubWorkflowBundle = {
         "",
         "When the user says **open a PR** (or similar), follow these steps exactly:",
         "",
-        "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.",
+        "1. **Regenerate project files** \u2014 run `pnpm exec 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",
@@ -4671,7 +4676,7 @@ var issueWorkerSubAgent = {
     "",
     "Run the appropriate verification commands depending on what changed:",
     "",
-    "1. If Projen config was changed: `npx projen && pnpm install`",
+    "1. If Projen config was changed: `pnpm exec projen && pnpm install`",
     "2. Compile the affected package: `pnpm --filter @codedrifters/<package> compile`",
     "3. Test the affected package: `pnpm --filter @codedrifters/<package> test`",
     "4. If changes span multiple packages: `pnpm build:all`",
@@ -5664,7 +5669,7 @@ var pnpmBundle = {
         "- Configure dependencies in Projen configuration files (`.projenrc.ts` or `projenrc/*.ts`)",
         "- Add dependencies to `deps`, `devDeps`, or `peerDeps` arrays in project configuration",
         '- Use catalog dependencies when available (e.g., `"aws-cdk-lib@catalog:"`)',
-        "- Ask the user to run `npx projen` and `pnpm install` after updating dependency configuration",
+        "- Ask the user to run `pnpm exec projen` and `pnpm install` after updating dependency configuration",
         "",
         "**DO NOT:**",
         "- Run `npm install some-package`",
@@ -7093,11 +7098,11 @@ var projenBundle = {
         "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files:",
         "",
         "```sh",
-        "npx projen",
+        "pnpm exec projen",
         "pnpm install",
         "```",
         "",
-        "Both steps are required \u2014 `npx projen` regenerates files, `pnpm install` updates the lockfile to match.",
+        "Both steps are required \u2014 `pnpm exec projen` regenerates files, `pnpm install` updates the lockfile to match.",
         "",
         "## Building",
         "",
@@ -7178,7 +7183,7 @@ var projenBundle = {
         "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`",
+        "   - Run `pnpm exec projen` then `pnpm install`",
         "   - Verify no unexpected generated file changes with `git diff`",
         "",
         "2. **Source code changes** (in a sub-package):",
@@ -7195,7 +7200,7 @@ var projenBundle = {
         "",
         "| Task | Command |",
         "|------|---------|",
-        "| Synthesize projen | `npx projen` |",
+        "| Synthesize projen | `pnpm exec projen` |",
         "| Install deps | `pnpm install` |",
         "| Full monorepo build | `pnpm build:all` |",
         "| Root build only | `pnpm build` |",
@@ -7221,7 +7226,7 @@ var projenBundle = {
       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.",
+        "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 `pnpm exec projen` run.",
         "",
         "## Adding Repo-Specific Rules",
         "",
@@ -7254,7 +7259,7 @@ var projenBundle = {
         "",
         "## After Any Change",
         "",
-        "Run `npx projen` then `pnpm install` to regenerate the output files."
+        "Run `pnpm exec projen` then `pnpm install` to regenerate the output files."
       ].join("\n"),
       tags: ["workflow"]
     },
@@ -7272,7 +7277,7 @@ var projenBundle = {
         "- Edit Projen configuration in:",
         "  - `.projenrc.ts` (root)",
         "  - `projenrc/*.ts` (package-specific)",
-        "- After making Projen changes, run `npx projen` to synthesize",
+        "- After making Projen changes, run `pnpm exec projen` to synthesize",
         "",
         "## Workspace Dependencies",
         "",
@@ -15556,6 +15561,77 @@ var import_javascript3 = require("projen/lib/javascript");
 var import_typescript3 = require("projen/lib/typescript");
 var import_ts_deepmerge = require("ts-deepmerge");
 
+// src/projects/monorepo-layout.ts
+var MONOREPO_LAYOUT = {
+  DOCS: "docs",
+  APPS: "apps",
+  PACKAGES: "packages",
+  SITES: "sites"
+};
+var LAYOUT_ENFORCEMENT = {
+  OFF: "off",
+  WARN: "warn",
+  ERROR: "error"
+};
+var LAYOUT_ROOT_BY_PROJECT_TYPE = {
+  TypeScriptProject: MONOREPO_LAYOUT.PACKAGES,
+  AwsCdkProject: MONOREPO_LAYOUT.APPS,
+  AstroProject: MONOREPO_LAYOUT.SITES,
+  StarlightProject: MONOREPO_LAYOUT.DOCS
+};
+function validateMonorepoLayout(root) {
+  const violations = [];
+  const rootOutdir = toPosix(root.outdir);
+  for (const sub of root.subprojects) {
+    const className = sub.constructor.name;
+    const expectedRoot = LAYOUT_ROOT_BY_PROJECT_TYPE[className];
+    if (expectedRoot === void 0) {
+      continue;
+    }
+    const relOutdir = relativeOutdir(rootOutdir, toPosix(sub.outdir));
+    if (!outdirMatchesRoot(relOutdir, expectedRoot)) {
+      violations.push({
+        projectName: sub.name,
+        projectType: className,
+        outdir: relOutdir,
+        expectedRoot
+      });
+    }
+  }
+  return violations;
+}
+function formatLayoutViolation(violation) {
+  const { projectName, projectType, outdir, expectedRoot } = violation;
+  const expectedExample = expectedRoot === MONOREPO_LAYOUT.DOCS ? "docs/" : `${expectedRoot}/<scope>/<name>`;
+  return `[monorepo-layout] ${projectType} "${projectName}" has outdir "${outdir}", which is outside the expected root "${expectedRoot}/" (expected e.g. "${expectedExample}"). See docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md.`;
+}
+function outdirMatchesRoot(relOutdir, expectedRoot) {
+  const segments = relOutdir.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    return false;
+  }
+  if (segments[0] !== expectedRoot) {
+    return false;
+  }
+  if (expectedRoot === MONOREPO_LAYOUT.DOCS) {
+    return true;
+  }
+  return segments.length >= 2;
+}
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+function relativeOutdir(rootOutdir, subOutdir) {
+  if (subOutdir === rootOutdir) {
+    return "";
+  }
+  const prefix2 = rootOutdir.endsWith("/") ? rootOutdir : `${rootOutdir}/`;
+  if (subOutdir.startsWith(prefix2)) {
+    return subOutdir.slice(prefix2.length);
+  }
+  return subOutdir;
+}
+
 // src/tasks/reset-task.ts
 var import_projen13 = require("projen");
 var ResetTask = class _ResetTask extends import_projen13.Component {
@@ -16064,6 +16140,11 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
        * By default treat as a registry consumer (upgrade workflow syncs configulator).
        */
       configulatorRegistryConsumer: true,
+      /**
+       * ADR-006 layout enforcement defaults to "warn" during rollout so
+       * legacy outdirs log actionable warnings but do not break synth.
+       */
+      layoutEnforcement: LAYOUT_ENFORCEMENT.WARN,
       /**
        * We don't want sample code generated for the root project.
        */
@@ -16177,6 +16258,7 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
     this.tsconfig?.removeInclude(`${this.srcdir}/**/*.ts`);
     this.pnpmVersion = options.pnpmVersion;
     this.configulatorRegistryConsumer = options.configulatorRegistryConsumer ?? true;
+    this.layoutEnforcement = options.layoutEnforcement ?? LAYOUT_ENFORCEMENT.WARN;
     new VSCodeConfig(this);
     new PnpmWorkspace(this, options.pnpmOptions?.pnpmWorkspaceOptions);
     if (options.turbo) {
@@ -16271,6 +16353,32 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
       );
     }
   }
+  /**
+   * Validate sub-project `outdir` values against the ADR-006 monorepo
+   * layout contract. Runs in `preSynthesize` so all sub-projects are
+   * attached by the time we inspect the tree.
+   *
+   * Behavior is controlled by `layoutEnforcement`:
+   * - `"off"`  — skip validation.
+   * - `"warn"` — log a `console.warn` per violation; continue.
+   * - `"error"` — throw on the first violation.
+   */
+  preSynthesize() {
+    super.preSynthesize();
+    if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.OFF) {
+      return;
+    }
+    const violations = validateMonorepoLayout(this);
+    if (violations.length === 0) {
+      return;
+    }
+    if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.ERROR) {
+      throw new Error(formatLayoutViolation(violations[0]));
+    }
+    for (const violation of violations) {
+      console.warn(formatLayoutViolation(violation));
+    }
+  }
   /**
    * Allows a sub project to request installation of dependency at the Monorepo root
    * They must provide a function that is executed after dependencies have been installed
@@ -17388,10 +17496,13 @@ var TypeScriptConfig = class extends import_projen22.Component {
   DEFAULT_TEARDOWN_BRANCH_PATTERNS,
   DEFAULT_TYPE_LABELS,
   JsiiFaker,
+  LAYOUT_ENFORCEMENT,
+  LAYOUT_ROOT_BY_PROJECT_TYPE,
   MCP_TRANSPORT,
   MERGE_METHODS,
   MIMIMUM_RELEASE_AGE,
   MINIMUM_RELEASE_AGE,
+  MONOREPO_LAYOUT,
   MonorepoProject,
   PROD_DEPLOY_NAME,
   PnpmWorkspace,
@@ -17418,6 +17529,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   baseBundle,
   bcmWriterBundle,
   companyProfileBundle,
+  formatLayoutViolation,
   getLatestEligibleVersion,
   githubWorkflowBundle,
   industryDiscoveryBundle,
@@ -17439,6 +17551,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   softwareProfileBundle,
   turborepoBundle,
   typescriptBundle,
+  validateMonorepoLayout,
   vitestBundle
 });
 //# sourceMappingURL=index.js.map