@codedrifters/configulator 0.0.244 → 0.0.246

package/lib/index.d.mts

@@ -1534,6 +1534,14 @@ interface ResolvedProjectMetadata {
     readonly milestones?: ReadonlyArray<string>;
     readonly docsPath?: string;
     readonly deployment?: DeploymentMetadata;
+    /**
+     * Markdown block appended to the `project-context` maintainer seed
+     * template. Resolved to the grouped sub-project list skeleton when
+     * the root project is a `MonorepoProject` with layout enforcement
+     * on (`layoutEnforcement !== "off"`); empty otherwise. Consumed by
+     * the `{{monorepoLayoutSeedBlock}}` template variable.
+     */
+    readonly monorepoLayoutSeedBlock?: string;
 }
 
 /**
@@ -3636,6 +3644,19 @@ declare class ProjectMetadata extends Component {
      * Explicit options always take precedence over auto-detected values.
      */
     private resolveMetadata;
+    /**
+     * Return the maintainer-seed addendum for the `project-context`
+     * bundle, or an empty string when the root project either has no
+     * layout-enforcement opinion or has opted out (`layoutEnforcement:
+     * "off"`).
+     *
+     * Uses duck-typing on the root project's `layoutEnforcement`
+     * property to avoid a circular import with `MonorepoProject`. The
+     * concrete `MonorepoProject` class exposes this property as a
+     * string; anything else resolves to the empty string so repos that
+     * predate the monorepo layout contract see no change.
+     */
+    private resolveMonorepoLayoutSeedBlock;
     /**
      * Attempts to auto-detect repository owner and name from the Projen
      * project's package.json repository field.

package/lib/index.d.ts

@@ -1583,6 +1583,14 @@ interface ResolvedProjectMetadata {
     readonly milestones?: ReadonlyArray<string>;
     readonly docsPath?: string;
     readonly deployment?: DeploymentMetadata;
+    /**
+     * Markdown block appended to the `project-context` maintainer seed
+     * template. Resolved to the grouped sub-project list skeleton when
+     * the root project is a `MonorepoProject` with layout enforcement
+     * on (`layoutEnforcement !== "off"`); empty otherwise. Consumed by
+     * the `{{monorepoLayoutSeedBlock}}` template variable.
+     */
+    readonly monorepoLayoutSeedBlock?: string;
 }
 
 /**
@@ -3685,6 +3693,19 @@ declare class ProjectMetadata extends Component {
      * Explicit options always take precedence over auto-detected values.
      */
     private resolveMetadata;
+    /**
+     * Return the maintainer-seed addendum for the `project-context`
+     * bundle, or an empty string when the root project either has no
+     * layout-enforcement opinion or has opted out (`layoutEnforcement:
+     * "off"`).
+     *
+     * Uses duck-typing on the root project's `layoutEnforcement`
+     * property to avoid a circular import with `MonorepoProject`. The
+     * concrete `MonorepoProject` class exposes this property as a
+     * string; anything else resolves to the empty string so repos that
+     * predate the monorepo layout contract see no change.
+     */
+    private resolveMonorepoLayoutSeedBlock;
     /**
      * Attempts to auto-detect repository owner and name from the Projen
      * project's package.json repository field.

package/lib/index.js

@@ -476,6 +476,122 @@ var awsCdkBundle = {
 };
 
 // src/agent/bundles/base.ts
+var createPackageSkill = {
+  name: "create-package",
+  description: "Scaffold a new TypeScriptProject sub-project under packages/@scope/<name> by emitting the projen block to add to the monorepo config",
+  disableModelInvocation: true,
+  instructions: [
+    "# Create Package",
+    "",
+    "Scaffold a new shared-library sub-project at",
+    "`packages/@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.",
+    "",
+    "## Usage",
+    "",
+    "```",
+    "/create-package @<scope>/<name>",
+    "```",
+    "",
+    "Example: `/create-package @codedrifters/my-lib` \u2192 scaffolds a new",
+    "`TypeScriptProject` at `packages/@codedrifters/my-lib`.",
+    "",
+    "## Steps",
+    "",
+    "1. **Parse and validate the package 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. `my-lib`) are **not** allowed \u2014 every",
+    "     package under `packages/` is scoped by owner.",
+    "   If the input is missing or invalid, ask the user to supply a",
+    "   scoped name. Do not guess the scope.",
+    "",
+    "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 package does.",
+    "   - **Publish to npm?** \u2014 `true` or `false`. Workspace-internal",
+    "     libraries should answer `false`.",
+    "   Skip any question the user has already answered in the initial",
+    "   prompt.",
+    "",
+    "3. **Determine the target outdir.** The sub-project lives at:",
+    "",
+    "   ```",
+    "   packages/<scope>/<name>",
+    "   ```",
+    "",
+    "   `<scope>` is everything after `@` and before `/` in the package",
+    "   name; `<name>` is everything after the `/`. This matches the",
+    "   default `outdir` that `TypeScriptProject` 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/packages.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/my-lib`:",
+    "",
+    "   ```typescript",
+    "   import { TypeScriptProject } from '@codedrifters/configulator';",
+    "",
+    "   // Inside the monorepo's configuration function, alongside",
+    "   // sibling sub-projects:",
+    "   new TypeScriptProject({",
+    "     parent: monorepo,",
+    "     name: '@codedrifters/my-lib',",
+    "     description: '<one-line description>',",
+    "     defaultReleaseBranch: 'main',",
+    "     publishToNpm: false, // or true if this package publishes",
+    "   });",
+    "   ```",
+    "",
+    "   Substitute the user's scope, name, description, and",
+    "   `publishToNpm` value. Do not hard-code `outdir` \u2014 the default",
+    "   places the sub-project at `packages/<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 outside `packages/`. Deployable apps belong under",
+    "  `apps/<scope>/<name>` (use `/create-app`); user-facing sites belong",
+    "  under `sites/<scope>/<name>` (use `/create-site`).",
+    "- Never scope by category (e.g. `@libs/foo`, `@packages/foo`). The",
+    "  scope identifies the **owning party**; the top-level folder",
+    "  identifies the kind.",
+    "- Do not invent an `outdir` \u2014 rely on the `TypeScriptProject`",
+    "  default that places the sub-project at `packages/<scope>/<name>`.",
+    "",
+    "## Related Skills",
+    "",
+    "- `/create-app` \u2014 scaffold a new `AwsCdkProject` under",
+    "  `apps/<scope>/<name>`.",
+    "- `/create-site` \u2014 scaffold a new `AstroProject` under",
+    "  `sites/<scope>/<name>`."
+  ].join("\n")
+};
 var createRuleSkill = {
   name: "create-rule",
   description: "Guide for creating new agent rules in this project using configulator",
@@ -534,7 +650,7 @@ var baseBundle = {
   name: "base",
   description: "Core rules: project overview, interaction style, and general coding conventions",
   appliesWhen: () => true,
-  skills: [createRuleSkill],
+  skills: [createPackageSkill, createRuleSkill],
   rules: [
     {
       name: "project-overview",
@@ -997,6 +1113,28 @@ var baseBundle = {
 
 // src/agent/bundles/project-context.ts
 var PROJECT_CONTEXT_PATH = "docs/project-context.md";
+var SUBPROJECT_ROLE_GUIDANCE = [
+  "### Sub-project roles",
+  "",
+  "When the repository follows the configulator monorepo layout,",
+  "every sub-project's role is derivable from the first segment of",
+  "its `outdir` path. No other lookup is required.",
+  "",
+  "- `apps/<scope>/<name>` \u2014 deployable application (CDK stack,",
+  "  mobile app, backend service).",
+  "- `packages/<scope>/<name>` \u2014 shared library (published npm",
+  "  package or workspace-internal library).",
+  "- `sites/<scope>/<name>` \u2014 user-facing web front end that is",
+  "  not the monorepo-wide docs site.",
+  "- `docs/` \u2014 the single Starlight documentation site for the",
+  "  whole monorepo (exactly one per repo; lives at `/docs`, not",
+  "  under `sites/`).",
+  "",
+  "Repositories that have not adopted the layout contract may use a",
+  "different folder structure \u2014 in that case fall back to whatever",
+  `\`${PROJECT_CONTEXT_PATH}\` documents explicitly.`,
+  ""
+];
 var PROJECT_CONTEXT_READER_SECTION = [
   "## Project Context",
   "",
@@ -1011,6 +1149,7 @@ var PROJECT_CONTEXT_READER_SECTION = [
   "",
   "You are a **read-only consumer** of this file. Do not edit it.",
   "",
+  ...SUBPROJECT_ROLE_GUIDANCE,
   "---",
   ""
 ];
@@ -1023,6 +1162,7 @@ var PROJECT_CONTEXT_MAINTAINER_SECTION = [
   "key stakeholders. Use it to judge relevance when scanning source",
   "material in this session.",
   "",
+  ...SUBPROJECT_ROLE_GUIDANCE,
   "### Seed on first use",
   "",
   `If \`${PROJECT_CONTEXT_PATH}\` does not exist, create it from this`,
@@ -1052,7 +1192,7 @@ var PROJECT_CONTEXT_MAINTAINER_SECTION = [
   "",
   "## Key Stakeholders",
   "TODO: named people or teams and what they care about.",
-  "",
+  "{{monorepoLayoutSeedBlock}}",
   "## References",
   "TODO: links to BCM docs, competitive analysis, product roadmap, and",
   "other authoritative sources.",
@@ -1077,6 +1217,26 @@ var PROJECT_CONTEXT_MAINTAINER_SECTION = [
   "---",
   ""
 ];
+var MONOREPO_LAYOUT_SEED_BLOCK = [
+  "",
+  "## Sub-Projects",
+  "",
+  "TODO: one bullet per sub-project, grouped by role. The role is",
+  "derivable from the first segment of each sub-project's `outdir`.",
+  "",
+  "### Applications (`apps/`)",
+  "TODO: deployable applications (CDK stacks, mobile apps, services).",
+  "",
+  "### Packages (`packages/`)",
+  "TODO: shared libraries (published npm packages, workspace-internal libraries).",
+  "",
+  "### Sites (`sites/`)",
+  "TODO: user-facing web front ends (marketing sites, SPAs, client apps).",
+  "",
+  "### Docs (`docs/`)",
+  "TODO: the single monorepo-wide Starlight documentation site.",
+  ""
+].join("\n");
 
 // src/agent/bundles/bcm-writer.ts
 var bcmWriterSubAgent = {
@@ -12603,9 +12763,30 @@ var ProjectMetadata = class _ProjectMetadata extends import_projen2.Component {
       labels: options.labels,
       milestones: options.milestones,
       docsPath: options.docsPath,
-      deployment: options.deployment
+      deployment: options.deployment,
+      monorepoLayoutSeedBlock: this.resolveMonorepoLayoutSeedBlock()
     };
   }
+  /**
+   * Return the maintainer-seed addendum for the `project-context`
+   * bundle, or an empty string when the root project either has no
+   * layout-enforcement opinion or has opted out (`layoutEnforcement:
+   * "off"`).
+   *
+   * Uses duck-typing on the root project's `layoutEnforcement`
+   * property to avoid a circular import with `MonorepoProject`. The
+   * concrete `MonorepoProject` class exposes this property as a
+   * string; anything else resolves to the empty string so repos that
+   * predate the monorepo layout contract see no change.
+   */
+  resolveMonorepoLayoutSeedBlock() {
+    const root = this.project.root;
+    const enforcement = root.layoutEnforcement;
+    if (typeof enforcement !== "string" || enforcement === "off") {
+      return "";
+    }
+    return MONOREPO_LAYOUT_SEED_BLOCK;
+  }
   /**
    * Attempts to auto-detect repository owner and name from the Projen
    * project's package.json repository field.
@@ -14625,7 +14806,12 @@ var FALLBACKS = {
   "githubProject.name": "<project-name>",
   "githubProject.number": "<project-number>",
   "githubProject.nodeId": "<project-node-id>",
-  docsPath: "<docs-path>"
+  docsPath: "<docs-path>",
+  // The monorepo-layout seed block is additive: when absent, the
+  // seeded `project-context.md` template reads cleanly without it.
+  // Fall back to an empty string so no placeholder text leaks into
+  // rendered prompts for repos that predate the layout contract.
+  monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
 function getNestedValue(obj, path2) {