@codedrifters/configulator 0.0.239 → 0.0.241

package/lib/index.mjs

@@ -767,6 +767,91 @@ var baseBundle = {
       ].join("\n"),
       tags: ["workflow"]
     },
+    {
+      name: "monorepo-layout",
+      description: "Canonical monorepo top-level folders (docs, apps, packages, sites), the @ownerscope/<name> scoping rule, the docs-singleton carve-out, and the scaffolding skills that place new sub-projects",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Monorepo Layout",
+        "",
+        "Every monorepo built with `@codedrifters/configulator` uses a single,",
+        "fixed top-level folder layout. Agents, scaffolding skills, pnpm-workspace",
+        "globs, Turbo filters, and CI cache keys all assume these roots.",
+        "",
+        "## Four Canonical Top-Level Folders",
+        "",
+        "| Folder | Purpose | Examples |",
+        "|--------|---------|----------|",
+        "| `/docs` | **Single** Starlight site covering the entire monorepo. The one site that lives outside `/sites`. | Monorepo-wide developer docs, ADRs, how-to guides. |",
+        "| `/apps/@scope/<name>` | Deployable applications \u2014 anything that runs or ships as a running process. | AWS CDK stacks, mobile apps (iOS/Android), backend services. |",
+        "| `/packages/@scope/<name>` | Shared libraries \u2014 published npm packages and workspace-internal libraries. | `@codedrifters/configulator`, `@codedrifters/constructs`, `@codedrifters/utils`. |",
+        "| `/sites/@scope/<name>` | User-facing web front ends that are **not** the monorepo-wide docs site. | Marketing sites, SPAs, per-client static sites. |",
+        "",
+        "No other top-level folder is part of this contract. Generated roots",
+        "(`.projen/`, `.github/`, `node_modules/`, `.turbo/`, etc.) are orthogonal",
+        "and unchanged.",
+        "",
+        "## Scoping Rule",
+        "",
+        "Every sub-project under `apps/`, `packages/`, or `sites/` is named",
+        "`@ownerscope/<name>`, where **scope is the owning party** (not a category).",
+        "",
+        "- `@codedrifters/configulator` \u2014 a shared library owned by CodeDrifters \u2192 `packages/@codedrifters/configulator`",
+        "- `@codedrifters/infrastructure-stack` \u2014 an AWS CDK app owned by CodeDrifters \u2192 `apps/@codedrifters/infrastructure-stack`",
+        "- `@clientA/iphone-app` \u2014 a mobile app owned by Client A \u2192 `apps/@clientA/iphone-app`",
+        "- `@clientB/marketing-site` \u2014 a marketing site owned by Client B \u2192 `sites/@clientB/marketing-site`",
+        "",
+        "The scope identifies **who owns the sub-project**, not what kind of",
+        "sub-project it is. Kind is captured by the top-level folder (`apps/`,",
+        "`packages/`, `sites/`). Never scope by category (e.g. `@apps/foo`,",
+        "`@libs/bar`) \u2014 the top-level folder already carries that information.",
+        "",
+        "## Docs-Singleton Carve-Out",
+        "",
+        "There is **exactly one** Starlight docs site per monorepo, and it lives",
+        "at `/docs`. It is **not** `sites/@scope/docs`.",
+        "",
+        "- The docs site is monorepo-wide. Sub-project documentation belongs",
+        "  inside that single site (under `docs/content/`), not in a per-package",
+        "  `docs/` folder.",
+        "- Configulator's `StarlightProject` defaults its `outdir` to `/docs`.",
+        "- `/sites` is reserved for end-user-facing web front ends (marketing",
+        "  sites, SPAs, client-facing apps). It deliberately does not host the",
+        "  dev-docs site.",
+        "",
+        "## Project-Type \u2192 `outdir` Mapping",
+        "",
+        "Configulator project types default their `outdir` according to the",
+        "following table. Override `outdir` explicitly only when you have a",
+        "genuine reason \u2014 the defaults cover the common path.",
+        "",
+        "| Configulator project type | Default `outdir` |",
+        "|---------------------------|------------------|",
+        "| `TypeScriptProject` | `packages/<scope>/<name>` |",
+        "| `AwsCdkProject` | `apps/<scope>/<name>` |",
+        "| `AstroProject` | `sites/<scope>/<name>` |",
+        "| `StarlightProject` (role = docs) | `docs/` |",
+        "",
+        "`<scope>` is parsed from the sub-project's package name (everything",
+        "after `@` and before `/`). `<name>` is the unscoped part of the",
+        "package name.",
+        "",
+        "## Placing New Sub-Projects",
+        "",
+        "Never hand-roll a sub-project path. Use one of the scaffolding skills,",
+        "which take `@scope/<name>` as input, validate it, and place the new",
+        "project in the correct folder:",
+        "",
+        "- `/create-package` \u2014 scaffolds a new `TypeScriptProject` under `packages/<scope>/<name>`",
+        "- `/create-app` \u2014 scaffolds a new `AwsCdkProject` under `apps/<scope>/<name>`",
+        "- `/create-site` \u2014 scaffolds a new `AstroProject` under `sites/<scope>/<name>`",
+        "",
+        "The monorepo-wide docs site at `/docs` is a singleton and is created",
+        "once per repo via `StarlightProject` \u2014 it is not scaffolded per",
+        "sub-project."
+      ].join("\n"),
+      tags: ["project"]
+    },
     {
       name: "issue-conventions",
       description: "Issue title prefixes, GitHub issue type mapping, prerequisite issues",
@@ -16333,6 +16418,40 @@ var MonorepoProject = class extends TypeScriptAppProject {
   }
 };
 
+// src/projects/resolve-outdir.ts
+function parseScopedName(input) {
+  if (!input.startsWith("@")) {
+    return void 0;
+  }
+  const slashIndex = input.indexOf("/");
+  if (slashIndex < 2) {
+    return void 0;
+  }
+  const scope = input.slice(0, slashIndex);
+  const name = input.slice(slashIndex + 1);
+  if (name.length === 0 || name.includes("/")) {
+    return void 0;
+  }
+  return { scope, name };
+}
+function resolveOutdirFromPackageName(packageName, root) {
+  if (packageName === void 0 || packageName.length === 0) {
+    throw new Error(
+      "Cannot derive outdir: packageName (or name) is required when outdir is omitted. Either pass a scoped `packageName` / `name` like `@scope/foo`, or set `outdir` explicitly."
+    );
+  }
+  const parsed = parseScopedName(packageName);
+  if (parsed === void 0) {
+    throw new Error(
+      `Cannot derive outdir from unscoped packageName "${packageName}". Either use a scoped name like \`@scope/foo\`, or set \`outdir\` explicitly. Configulator places sub-projects at "${root}/<scope>/<name>".`
+    );
+  }
+  return `${root}/${parsed.scope}/${parsed.name}`;
+}
+function resolveTypeScriptProjectOutdir(packageName) {
+  return resolveOutdirFromPackageName(packageName, MONOREPO_LAYOUT.PACKAGES);
+}
+
 // src/projects/typescript-project.ts
 var TestRunner = {
   JEST: "jest",
@@ -16348,6 +16467,9 @@ var TypeScriptProject = class extends typescript.TypeScriptProject {
     const parent = userOptions.parent;
     const pnpmVersion = parent.pnpmVersion;
     const pnpmWorkspace = PnpmWorkspace.of(parent);
+    const resolvedOutdir = userOptions.outdir ?? resolveTypeScriptProjectOutdir(
+      userOptions.packageName ?? userOptions.name
+    );
     const testRunner = userOptions.testRunner ?? TestRunner.JEST;
     const useJest = testRunner === TestRunner.JEST;
     const defaultOptions = {
@@ -16355,6 +16477,12 @@ var TypeScriptProject = class extends typescript.TypeScriptProject {
        * This is a standard, so don't require it to passed in everywhere.
        */
       defaultReleaseBranch: "main",
+      /**
+       * Outdir defaults to `packages/<scope>/<name>` when the caller
+       * omits it. Explicit overrides in `userOptions` always win via
+       * the merge below.
+       */
+      outdir: resolvedOutdir,
       /**
        * Enable reset task by default.
        */
@@ -16425,10 +16553,7 @@ var TypeScriptProject = class extends typescript.TypeScriptProject {
        * (version, dependencies) changes.
        */
       releaseTrigger: ReleaseTrigger.continuous({
-        paths: [
-          `${userOptions.outdir}/src/**`,
-          `${userOptions.outdir}/package.json`
-        ]
+        paths: [`${resolvedOutdir}/src/**`, `${resolvedOutdir}/package.json`]
       })
     };
     const options = merge2(defaultOptions, userOptions);
@@ -17475,7 +17600,9 @@ export {
   requirementsWriterBundle,
   researchPipelineBundle,
   resolveModelAlias,
+  resolveOutdirFromPackageName,
   resolveTemplateVariables,
+  resolveTypeScriptProjectOutdir,
   slackBundle,
   softwareProfileBundle,
   turborepoBundle,