@codedrifters/configulator 0.0.247 → 0.0.249

package/lib/index.mjs

@@ -625,6 +625,170 @@ var createAppSkill = {
     "  `sites/<scope>/<name>`."
   ].join("\n")
 };
+var createSiteSkill = {
+  name: "create-site",
+  description: "Scaffold a new AstroProject sub-project under sites/@scope/<name> by emitting the projen block to add to the monorepo config",
+  disableModelInvocation: true,
+  instructions: [
+    "# Create Site",
+    "",
+    "Scaffold a new user-facing web front end at",
+    "`sites/@scope/<name>` by emitting the projen block to add to the",
+    "monorepo's projen configuration. This skill walks the user through",
+    "naming, metadata, and placement; it does **not** run projen, install",
+    "dependencies, or execute any build commands.",
+    "",
+    "The default project type is `AstroProject` \u2014 the common shape for",
+    "marketing sites, SPAs, and client-facing static sites. A",
+    '`StarlightProject` with `role: "site"` is also a valid placement',
+    "under `sites/<scope>/<name>` for consumers who specifically want a",
+    "Starlight-based front end; it is **not** the monorepo-wide docs site.",
+    "",
+    "## Usage",
+    "",
+    "```",
+    "/create-site @<scope>/<name>",
+    "```",
+    "",
+    "Example: `/create-site @codedrifters/marketing-site` \u2192 scaffolds a",
+    "new `AstroProject` at `sites/@codedrifters/marketing-site`.",
+    "",
+    "## Docs-vs-Site Guard",
+    "",
+    "There is **exactly one** Starlight docs site per monorepo, and it",
+    "lives at `/docs` \u2014 not under `sites/`. Before emitting any block,",
+    "check whether the user actually wants the monorepo-wide docs site:",
+    "",
+    "- If the user's intent is to create the single dev-docs site for the",
+    "  monorepo (names like `docs`, `documentation`, `dev-docs`, or any",
+    '  explicit mention of "the docs site"), **refuse** to scaffold it',
+    "  under `sites/`. Redirect them to the `StarlightProject` defaults",
+    "  that place the docs site at `/docs`, and explain that `sites/` is",
+    "  reserved for end-user-facing web front ends (marketing, SPAs,",
+    "  client-facing apps).",
+    "- If the user wants a user-facing site that happens to use Starlight",
+    "  (e.g. a public-facing documentation portal for a specific",
+    "  product), that is fine \u2014 they should use `StarlightProject` with",
+    '  `role: "site"`, which routes under `sites/<scope>/<name>`.',
+    "- Otherwise, proceed with `AstroProject` as the default.",
+    "",
+    "## Steps",
+    "",
+    "1. **Parse and validate the site name.** The argument must be a",
+    "   **scoped** npm name in the form `@<scope>/<name>`:",
+    "   - Starts with `@`",
+    "   - Has exactly one `/` separator",
+    "   - `<scope>` and `<name>` are lowercase, kebab-case, non-empty",
+    "   - Unscoped names (e.g. `marketing-site`) are **not** allowed \u2014",
+    "     every site under `sites/` is scoped by owner.",
+    "   If the input is missing or invalid, ask the user to supply a",
+    "   scoped name. Do not guess the scope. Run the docs-vs-site guard",
+    "   above before continuing.",
+    "",
+    "2. **Collect metadata** \u2014 ask the user for each of the following,",
+    "   one question at a time:",
+    "   - **Description** \u2014 one-line summary of what the site is for.",
+    "   - **Project type** \u2014 `AstroProject` (default) or",
+    "     `StarlightProject` (role = site). If the user is unsure,",
+    "     recommend `AstroProject` \u2014 Starlight is only the right choice",
+    "     when the site's primary purpose is a documentation-style",
+    '     layout. As an aside: a `StarlightProject` with `role: "site"`',
+    "     lives at the same `sites/<scope>/<name>` path, so switching",
+    "     between the two later is a low-cost change.",
+    "   Skip any question the user has already answered in the initial",
+    "   prompt.",
+    "",
+    "3. **Determine the target outdir.** The sub-project lives at:",
+    "",
+    "   ```",
+    "   sites/<scope>/<name>",
+    "   ```",
+    "",
+    "   `<scope>` is everything after `@` and before `/` in the site",
+    "   name; `<name>` is everything after the `/`. This matches the",
+    "   default `outdir` that `AstroProject` (and `StarlightProject` with",
+    '   `role: "site"`) computes from the package name, so the emitted',
+    "   block does **not** need to set `outdir` explicitly.",
+    "",
+    "4. **Locate the projen config file.** Prefer the monorepo's",
+    "   `projenrc/` directory \u2014 most monorepos declare sub-projects",
+    "   there (e.g. `projenrc/root-project.ts` or a dedicated",
+    "   `projenrc/sites.ts`). Fall back to `.projenrc.ts` only when",
+    "   no `projenrc/` directory exists.",
+    "",
+    "5. **Emit the projen block.** Show the TypeScript block to paste",
+    "   into the chosen projen config file. Example for",
+    "   `@codedrifters/marketing-site` as an `AstroProject`:",
+    "",
+    "   ```typescript",
+    "   import { AstroProject } from '@codedrifters/configulator';",
+    "",
+    "   // Inside the monorepo's configuration function, alongside",
+    "   // sibling sub-projects:",
+    "   new AstroProject({",
+    "     parent: monorepo,",
+    "     name: '@codedrifters/marketing-site',",
+    "     description: '<one-line description>',",
+    "   });",
+    "   ```",
+    "",
+    '   If the user chose `StarlightProject` with `role: "site"`, emit',
+    "   that variant instead \u2014 same path, different project class:",
+    "",
+    "   ```typescript",
+    "   import { StarlightProject } from '@codedrifters/configulator';",
+    "",
+    "   new StarlightProject({",
+    "     parent: monorepo,",
+    "     name: '@codedrifters/marketing-site',",
+    "     description: '<one-line description>',",
+    "     role: 'site',",
+    "   });",
+    "   ```",
+    "",
+    "   Substitute the user's scope, name, and description. Do not",
+    "   hard-code `outdir` \u2014 the default places the sub-project at",
+    "   `sites/<scope>/<name>`.",
+    "",
+    "6. **Tell the user how to synthesize.** Instruct them to run, from",
+    "   the repo root:",
+    "",
+    "   ```",
+    "   pnpm exec projen",
+    "   pnpm install",
+    "   ```",
+    "",
+    "   `pnpm exec projen` regenerates the sub-project tree;",
+    "   `pnpm install` updates the workspace lockfile. Do **not** run",
+    "   these commands yourself \u2014 the user runs them.",
+    "",
+    "## Guardrails",
+    "",
+    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm build`,",
+    "  `pnpm test`, or any other package-manager, build, or test command.",
+    "  Emit the projen block and instructions only.",
+    "- Never scaffold the monorepo-wide docs site under `sites/`. The",
+    "  dev-docs site is a singleton at `/docs` and is created once per",
+    '  repo via `StarlightProject` with its default `role: "docs"` \u2014',
+    "  redirect the user there if they ask for it.",
+    "- Never scaffold outside `sites/`. Shared libraries belong under",
+    "  `packages/<scope>/<name>` (use `/create-package`); deployable apps",
+    "  belong under `apps/<scope>/<name>` (use `/create-app`).",
+    "- Never scope by category (e.g. `@sites/foo`, `@web/foo`). The",
+    "  scope identifies the **owning party**; the top-level folder",
+    "  identifies the kind.",
+    "- Do not invent an `outdir` \u2014 rely on the `AstroProject` default",
+    '  (or the `StarlightProject` default when `role: "site"`) that',
+    "  places the sub-project at `sites/<scope>/<name>`.",
+    "",
+    "## Related Skills",
+    "",
+    "- `/create-package` \u2014 scaffold a new `TypeScriptProject` under",
+    "  `packages/<scope>/<name>`.",
+    "- `/create-app` \u2014 scaffold a new `AwsCdkProject` under",
+    "  `apps/<scope>/<name>`."
+  ].join("\n")
+};
 var createRuleSkill = {
   name: "create-rule",
   description: "Guide for creating new agent rules in this project using configulator",
@@ -683,7 +847,12 @@ var baseBundle = {
   name: "base",
   description: "Core rules: project overview, interaction style, and general coding conventions",
   appliesWhen: () => true,
-  skills: [createPackageSkill, createAppSkill, createRuleSkill],
+  skills: [
+    createPackageSkill,
+    createAppSkill,
+    createSiteSkill,
+    createRuleSkill
+  ],
   rules: [
     {
       name: "project-overview",
@@ -700,7 +869,36 @@ var baseBundle = {
         "- **Never edit generated files** \u2014 they are marked with `// ~~ Generated by projen`",
         "- **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"
+        "- **Export from index.ts** to maintain clean public APIs",
+        "",
+        "## Repository Layout",
+        "",
+        "Every monorepo built with `@codedrifters/configulator` uses a fixed",
+        "top-level folder layout. Read a sub-project's role directly from its",
+        "outdir:",
+        "",
+        "| Folder | Purpose |",
+        "|--------|---------|",
+        "| `/docs` | **Single** monorepo-wide Starlight docs site (the one site that lives outside `/sites`). |",
+        "| `/apps/@scope/<name>` | Deployable applications (CDK stacks, mobile apps, backend services). |",
+        "| `/packages/@scope/<name>` | Shared libraries (published npm packages and workspace-internal libraries). |",
+        "| `/sites/@scope/<name>` | User-facing web front ends that are **not** the monorepo-wide docs site. |",
+        "",
+        "Every sub-project under `apps/`, `packages/`, or `sites/` is named",
+        "`@ownerscope/<name>`, where **scope is the owning party** (not a",
+        "category). Kind is captured by the top-level folder \u2014 never scope by",
+        "category (e.g. `@apps/foo`, `@libs/bar`).",
+        "",
+        "To place a **new** sub-project, always use a scaffolding skill \u2014 never",
+        "hand-roll the path:",
+        "",
+        "- `/create-package` \u2014 new shared library under `packages/<scope>/<name>`",
+        "- `/create-app` \u2014 new deployable app under `apps/<scope>/<name>`",
+        "- `/create-site` \u2014 new web front end under `sites/<scope>/<name>`",
+        "",
+        "The `monorepo-layout` rule documents the full contract (outdir",
+        "defaults per project type, the docs-singleton carve-out, synth-time",
+        "enforcement)."
       ].join("\n"),
       tags: ["project"]
     },