@codedrifters/configulator 0.0.279 → 0.0.280

package/lib/index.mjs

@@ -1424,10 +1424,14 @@ function renderIssueTemplatesCheckerScript(it) {
     "# that includes a `--title` flag on a subsequent line. Single-line",
     "# fragments and prose mentions are permitted.",
     "#",
-    "# Two paths are allow-listed: the templates page itself, and the",
-    "# `github-workflow` bundle's `create-issue-workflow` rule source",
-    "# (which documents the conventional call shape as taxonomy, not a",
-    "# downstream template).",
+    "# Five paths are allow-listed: the templates page itself, the",
+    "# `github-workflow` bundle's `create-issue-workflow` rule source,",
+    "# the `upstream-configulator-docs` bundle's rule source, the",
+    "# `issue-templates` bundle source (which renders the templates",
+    "# page and so necessarily embeds the recipes as its content), and",
+    "# the `issue-templates` test source (which contains recipe fixtures",
+    "# used to exercise this very lint). All five legitimately contain",
+    "# `gh issue create` recipes as taxonomy, content, or test fixtures.",
     "#",
     "# The bundle-path patterns and templates path are rendered from the",
     "# consumer's IssueTemplatesConfig at synth time \u2014 do not edit by",
@@ -1448,12 +1452,16 @@ function renderIssueTemplatesCheckerScript(it) {
     "",
     `templates_path=${JSON.stringify(it.templatesPath)}`,
     "",
-    "# Allow-listed paths: the templates page itself and the",
-    "# create-issue-workflow rule source (both legitimately contain",
-    "# `gh issue create` recipes).",
+    "# Allow-listed paths: the templates page itself, the",
+    "# create-issue-workflow rule source, the upstream-configulator-docs",
+    "# rule source, and the issue-templates bundle source + test (which",
+    "# render and exercise the lint and so necessarily embed recipes).",
     "allowlist=(",
     `  "$templates_path"`,
     '  "packages/@codedrifters/configulator/src/agent/bundles/github-workflow.ts"',
+    '  "packages/@codedrifters/configulator/src/agent/bundles/upstream-configulator-docs.ts"',
+    '  "packages/@codedrifters/configulator/src/agent/bundles/issue-templates.ts"',
+    '  "packages/@codedrifters/configulator/src/agent/bundles/issue-templates.test.ts"',
     ")",
     "",
     "# Bundle-path glob patterns. Translated to anchored POSIX-extended",
@@ -25907,6 +25915,223 @@ var typescriptBundle = {
   }
 };
 
+// src/agent/bundles/upstream-configulator-docs.ts
+var DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED = true;
+var UPSTREAM_CONFIGULATOR_DOCS_SUMMARY = [
+  "# Upstream Configulator Docs",
+  "",
+  "This project consumes `@codedrifters/configulator` from the upstream repository **`codedrifters/packages`**. When you need to understand a configulator behaviour, project type, bundle, or rule, read the upstream docs first \u2014 the configulator package in this checkout is generated, not authoritative.",
+  "",
+  "## Where the docs live",
+  "",
+  "- **Repository:** `codedrifters/packages`",
+  "- **Docs root:** `docs/src/content/docs/`",
+  "- **Canonical absolute base URL:**",
+  "  <https://github.com/codedrifters/packages/tree/main/docs/src/content/docs/>",
+  "",
+  "Always link to upstream docs from this repo's CLAUDE.md or `.claude/rules/` using **absolute** GitHub URLs \u2014 relative links only work inside a single repo's tree, not across repos.",
+  "",
+  "## Reading the docs without cloning",
+  "",
+  "Use the `gh` CLI to read upstream docs from inside this checkout \u2014 no clone of `codedrifters/packages` required:",
+  "",
+  "```sh",
+  "# Read one doc by path:",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<path> \\",
+  "  --jq '.content' | base64 -d",
+  "",
+  "# List a docs directory:",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<dir> \\",
+  "  --jq '.[].path'",
+  "",
+  "# Search docs by keyword:",
+  "gh search code --repo codedrifters/packages --filename '*.md' '<query>'",
+  "```",
+  "",
+  "The Contents API returns base64-encoded payloads \u2014 `--jq '.content' | base64 -d` is the canonical decode recipe.",
+  "",
+  "## Upstream-issue-first preference",
+  "",
+  "When configulator is missing a feature, surfaces a bug, or behaves wrong, **file an issue against `codedrifters/packages`** rather than patching around it locally. Manual downstream overrides in `agentConfig.rules` or `agentConfig.ruleExtensions` are a last resort, not a first response \u2014 they fork divergence into every consumer that hits the same gap.",
+  "",
+  "Use the conventional issue recipe (mirrors the `Create Issue Workflow` in this project's CLAUDE.md):",
+  "",
+  "```sh",
+  "gh issue create --repo codedrifters/packages \\",
+  "  --title 'feat: <short description>' \\",
+  "  --label 'type:feat' \\",
+  "  --label 'priority:medium' \\",
+  "  --label 'status:ready' \\",
+  "  --body $'## Summary\\n\\n<1-3 sentences>\\n\\n## Details\\n\\n<context, acceptance criteria, or repro steps>'",
+  "```",
+  "",
+  "Pick the `type:*` and matching prefix that describes the work (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`). Set `priority:*` from the urgency and use `status:blocked` instead of `status:ready` if the issue depends on another open issue.",
+  "",
+  "See `.claude/rules/upstream-configulator-docs-detail.md` for the full reference \u2014 extended `gh` recipes, common pitfalls (rate limits, base64 decoding, search vs. browse), and a complete issue-creation walkthrough."
+].join("\n");
+var UPSTREAM_CONFIGULATOR_DOCS_DETAIL = [
+  "# Upstream Configulator Docs \u2014 Detail",
+  "",
+  "This project depends on `@codedrifters/configulator` for its Projen project types, agent bundles, and generated rules. Configulator itself is developed in the upstream repository **`codedrifters/packages`** \u2014 the source of record for project-type defaults, bundle behaviour, rule content, and the agent-config schema.",
+  "",
+  "When you are editing `.projenrc.ts`, `projenrc/**`, `.claude/**`, or `CLAUDE.md` and need to confirm how a configulator feature works, **read the upstream docs before editing**. Generated files in this checkout are not authoritative; the upstream markdown is.",
+  "",
+  "## 1. Where configulator's docs live",
+  "",
+  "- **Upstream repo:** `codedrifters/packages`",
+  "- **Docs root inside the repo:** `docs/src/content/docs/`",
+  "- **Canonical absolute base URL:**",
+  "  <https://github.com/codedrifters/packages/tree/main/docs/src/content/docs/>",
+  "",
+  "Always cite upstream docs with **absolute** `https://github.com/codedrifters/packages/...` URLs when linking from this consumer's CLAUDE.md or `.claude/rules/`. Relative `../docs/...` links only resolve inside a single repo's tree \u2014 they break the moment a downstream agent loads the rule from a different checkout.",
+  "",
+  "Common doc subtrees (browse the canonical base above for the live tree):",
+  "",
+  "- `docs/src/content/docs/agents/` \u2014 agent bundles, phase contracts, issue templates",
+  "- `docs/src/content/docs/components/` \u2014 Projen components and project types",
+  "- `docs/src/content/docs/requirements/` \u2014 requirement documents and ADRs",
+  "",
+  "## 2. Reading the docs via the GitHub API",
+  "",
+  "Use `gh` to fetch upstream docs without cloning `codedrifters/packages`. The recipes below run from inside any consumer's checkout.",
+  "",
+  "### Browse a single doc by path",
+  "",
+  "```sh",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<path> \\",
+  "  --jq '.content' | base64 -d",
+  "```",
+  "",
+  'The GitHub Contents API returns `{ content: "<base64>", encoding: "base64", ... }`. The `--jq \'.content\'` filter strips the JSON envelope and `base64 -d` decodes the payload to plain Markdown. On macOS the decode flag is `base64 -D` on older `base64` versions \u2014 use `base64 -d` (lowercase) on the GNU coreutils install that ships with most modern dev environments.',
+  "",
+  "Example \u2014 fetch the agent issue-templates page:",
+  "",
+  "```sh",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/agents/issue-templates.md \\",
+  "  --jq '.content' | base64 -d",
+  "```",
+  "",
+  "### List a docs directory",
+  "",
+  "```sh",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<dir> \\",
+  "  --jq '.[].path'",
+  "```",
+  "",
+  "Lists the immediate children (files and subdirectories) of `<dir>`. Use this to discover what's inside an agents/ or components/ subtree before browsing individual files.",
+  "",
+  "### Search docs by keyword",
+  "",
+  "```sh",
+  "gh search code --repo codedrifters/packages --filename '*.md' '<query>'",
+  "```",
+  "",
+  "`gh search code` hits the GitHub code-search index and is the right tool when you don't know which file to read. Scope by `--filename '*.md'` to keep results to documentation. Scope further with `--path 'docs/src/content/docs/<subtree>'` when you only care about one section.",
+  "",
+  "### Common pitfalls",
+  "",
+  "- **Forgot to base64-decode.** The Contents API never returns plain text \u2014 without `base64 -d` you get a base64 blob, not Markdown. Pipe through `base64 -d` every time.",
+  "- **Rate limits.** Unauthenticated `gh` calls share a tight per-IP quota. Authenticate with `gh auth login` before running these recipes; an authenticated token gets a 5,000-request hourly quota that is more than enough for interactive doc browsing.",
+  "- **Search vs. browse.** `gh search code` is best when you don't know the path. `gh api .../contents/...` is best when you do. Don't search for a path you already know \u2014 it's slower and the search index can lag behind the live file by a few minutes.",
+  "- **Branch defaults.** All recipes default to the repo's default branch (`main`). To read a doc from a feature branch, append `?ref=<branch>` to the contents-API path: `gh api 'repos/codedrifters/packages/contents/<path>?ref=<branch>' --jq '.content' | base64 -d`.",
+  "- **Large directories.** `gh api .../contents/<dir>` truncates responses over 1,000 entries. The `docs/src/content/docs/` subtrees are well under that limit today, but if you ever hit truncation, fall back to the Git Trees API: `gh api repos/codedrifters/packages/git/trees/main?recursive=1 --jq '.tree[] | select(.path | startswith(\"docs/src/content/docs/\")) | .path'`.",
+  "",
+  "## 3. Upstream-issue-first preference",
+  "",
+  "Configulator's rules, bundles, project types, and agent contracts ship for every consumer of the package. When you find a gap or a bug, the right fix is almost always upstream \u2014 patching around it locally forks divergence into this consumer and silently denies every other consumer the fix.",
+  "",
+  "**Default policy:** file an issue against `codedrifters/packages`. Reach for `agentConfig.rules` (new local rule) or `agentConfig.ruleExtensions` (append to a bundle rule) only when the upstream change is non-trivial and you need to unblock immediate work.",
+  "",
+  "### Canonical issue-creation recipe",
+  "",
+  "The recipe mirrors the `Create Issue Workflow` documented in this project's CLAUDE.md \u2014 same conventional-prefix titles, same `type:*` / `priority:*` / `status:*` label set, same body template \u2014 with `--repo codedrifters/packages` so it works from inside any consumer's checkout:",
+  "",
+  "```sh",
+  "gh issue create --repo codedrifters/packages \\",
+  "  --title '<type>: <short description>' \\",
+  "  --label '<type-label>' \\",
+  "  --label '<priority-label>' \\",
+  "  --label '<status-label>' \\",
+  "  --body $'## Summary\\n\\n<1-3 sentences describing the issue>\\n\\n## Details\\n\\n<acceptance criteria, repro steps, or context>'",
+  "```",
+  "",
+  "### Title prefix \u2192 type label",
+  "",
+  "Pick exactly one matching pair:",
+  "",
+  "| Title prefix | `type:*` label | Use for |",
+  "|--------------|----------------|---------|",
+  "| `feat:` | `type:feat` | New features or functionality |",
+  "| `fix:` | `type:fix` | Bug fixes |",
+  "| `chore:` | `type:chore` | Maintenance: deps, tooling, config |",
+  "| `docs:` | `type:docs` | Documentation-only work |",
+  "| `refactor:` | `type:refactor` | Code restructure, no behavior change |",
+  "| `release:` | `type:release` | Release preparation, version bumps |",
+  "| `hotfix:` | `type:hotfix` | Urgent production fixes |",
+  "| `epic:` | `type:feat` | Large initiatives spanning multiple child issues |",
+  "",
+  "### Priority and status labels",
+  "",
+  "- `priority:*` \u2014 pick exactly one of `priority:critical`, `priority:high`, `priority:medium`, `priority:low`, `priority:trivial`. Default to `priority:medium` when nothing in the request signals urgency. Use `priority:high` for blockers and `priority:critical` only for outages or release-blocking work.",
+  "- `status:*` \u2014 `status:ready` for self-contained issues, `status:blocked` when the issue declares `Depends on: #<n>` against another open issue.",
+  "",
+  "### Worked example",
+  "",
+  "Suppose configulator's `software-profile-analyst` agent prompt is missing a step you need. Instead of forking the prompt locally:",
+  "",
+  "```sh",
+  "gh issue create --repo codedrifters/packages \\",
+  "  --title 'feat: software-profile-analyst should record vendor pricing tier' \\",
+  "  --label 'type:feat' \\",
+  "  --label 'priority:medium' \\",
+  "  --label 'status:ready' \\",
+  "  --body $'## Summary\\n\\nThe `software-profile-analyst` Phase 2 prompt does not capture the vendor pricing tier (free / paid / enterprise), which downstream consumers need for segment matching.\\n\\n## Details\\n\\n- Add a `Pricing tier` field to the profile template at `docs/src/content/docs/agents/software-profile-analyst.md`\\n- Update the Phase 2 instructions to require the field before commit\\n- Add a regression test in `bundles.test.ts`'",
+  "```",
+  "",
+  "After filing, reference the upstream issue from any local workaround so it can be reverted once the upstream fix lands:",
+  "",
+  "```typescript",
+  "// TODO(codedrifters/packages#<N>): remove this override once upstream lands the fix.",
+  "agentConfig: {",
+  "  ruleExtensions: {",
+  "    'software-profile-analyst': '## Local override\\n\\n- Capture pricing tier...',",
+  "  },",
+  "}",
+  "```",
+  "",
+  "### When a local override is the right call",
+  "",
+  "Reach for `agentConfig.rules` or `agentConfig.ruleExtensions` only when **all** of the following hold:",
+  "",
+  "- The need is genuinely consumer-specific (not a gap that affects every configulator user).",
+  "- An upstream fix would take longer than you can wait, **and** you have already filed the upstream issue with a `TODO(codedrifters/packages#<N>)` reference in the local override.",
+  "- The override is small enough that diverging from upstream for a few days is cheaper than blocking on the upstream change.",
+  "",
+  "Anything that fails one of those tests belongs upstream first. The `# Reference Documentation` rule in this project's CLAUDE.md says it explicitly: trust the project sources and ask for clarification \u2014 that protocol extends across repo boundaries to `codedrifters/packages` for anything configulator owns."
+].join("\n");
+var upstreamConfigulatorDocsBundle = {
+  name: "upstream-configulator-docs",
+  description: "Pointers to @codedrifters/configulator's upstream docs and the upstream-issue protocol for missing features. Gated by AgentConfigOptions.upstreamConfigulator.enabled (default true).",
+  appliesWhen: () => true,
+  rules: [
+    {
+      name: "upstream-configulator-docs",
+      description: "Top-level reminder that the project consumes @codedrifters/configulator and where the upstream docs live",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: UPSTREAM_CONFIGULATOR_DOCS_SUMMARY,
+      tags: ["project"]
+    },
+    {
+      name: "upstream-configulator-docs-detail",
+      description: "Detailed protocol for reading @codedrifters/configulator upstream docs and filing upstream issues",
+      scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+      filePatterns: [".projenrc.ts", "projenrc/**", ".claude/**", "CLAUDE.md"],
+      content: UPSTREAM_CONFIGULATOR_DOCS_DETAIL,
+      tags: ["project"]
+    }
+  ]
+};
+
 // src/vitest/vitest-component.ts
 import { Component as Component5 } from "projen";
 import { Jest } from "projen/lib/javascript";
@@ -26508,6 +26733,7 @@ function renderPriorityRulesSection(rules) {
 function buildBuiltInBundles(paths = DEFAULT_AGENT_PATHS) {
   return [
     buildBaseBundle(paths),
+    upstreamConfigulatorDocsBundle,
     typescriptBundle,
     vitestBundle,
     jestBundle,
@@ -27831,6 +28057,13 @@ ${hook}`
     } else {
       ruleMap.delete("source-quality-verification");
     }
+    if (this.options.upstreamConfigulator?.enabled === false) {
+      for (const ruleName of [...ruleMap.keys()]) {
+        if (ruleName.startsWith("upstream-configulator-docs")) {
+          ruleMap.delete(ruleName);
+        }
+      }
+    }
     return [...ruleMap.values()].sort((a, b) => {
       if (a.name === "project-overview") return -1;
       if (b.name === "project-overview") return 1;
@@ -32338,6 +32571,7 @@ export {
   DEFAULT_TYPE_LABELS,
   DEFAULT_UNBLOCK_COMMENT_TEMPLATE,
   DEFAULT_UNBLOCK_DEPENDENTS_ENABLED,
+  DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED,
   DOCS_SYNC_AUDIT_SCHEMA_VERSION,
   JsiiFaker,
   LAYOUT_ENFORCEMENT,
@@ -32504,6 +32738,7 @@ export {
   tsdocRecordToFindings,
   turborepoBundle,
   typescriptBundle,
+  upstreamConfigulatorDocsBundle,
   validateAgentTierConfig,
   validateIssueTemplatesConfig,
   validateMonorepoLayout,