@codedrifters/configulator 0.0.213 → 0.0.215

package/lib/index.d.mts

@@ -198,9 +198,38 @@ interface AgentSkill {
     readonly paths?: ReadonlyArray<string>;
     /**
      * Resource directories bundled with the skill (e.g., references/, scripts/, assets/).
+     * Documentation hint only — directory names listed here are not emitted to disk.
+     * Prefer {@link referenceFiles} to ship actual companion file contents.
+     *
+     * @deprecated Use {@link referenceFiles} to emit physical companion files.
      * @example ['references/', 'scripts/']
      */
     readonly references?: ReadonlyArray<string>;
+    /**
+     * Companion files shipped alongside the SKILL.md (e.g., templates, references, scripts).
+     * Each entry is rendered as a TextFile under the skill's directory on every
+     * platform that emits skills (Claude: `.claude/skills/{name}/{path}`,
+     * Cursor: `.cursor/skills/{name}/{path}`).
+     *
+     * Use this for skill assets that benefit from being separate files rather than
+     * inlined into the skill instructions — large templates, reference tables,
+     * runnable scripts.
+     *
+     * Per-platform `platforms.{claude,cursor}.exclude` flags suppress reference
+     * files for that platform alongside the SKILL.md.
+     *
+     * @example
+     * referenceFiles: [
+     *   { path: '_references/templates/_template-FR.md', content: '# Functional Requirement\n...' },
+     *   { path: '_references/standards-and-frameworks.md', content: '# Standards\n...' },
+     * ]
+     */
+    readonly referenceFiles?: ReadonlyArray<{
+        /** Path relative to the skill directory (e.g., `_references/templates/_template-FR.md`). */
+        readonly path: string;
+        /** File contents written verbatim. */
+        readonly content: string;
+    }>;
     /**
      * Context isolation mode. Set to 'fork' to run in an isolated subagent context.
      */
@@ -1146,8 +1175,15 @@ declare const requirementsAnalystBundle: AgentRuleBundle;
 declare const researchPipelineBundle: AgentRuleBundle;
 
 /**
- * Slack bundle — opt-in via `includeBundles: ["slack"]`.
- * Never auto-detected (no Slack dependency to introspect).
+ * Slack bundle — auto-activated when the consuming project declares a
+ * Slack integration via `ProjectMetadata.slack`. Consumers can still
+ * opt in manually via `includeBundles: ["slack"]` when they have no
+ * `ProjectMetadata` configured.
+ *
+ * Detection signal: any truthy value on
+ * `ProjectMetadata.of(project).metadata.slack` that carries at least one
+ * channel reference (`projectChannel`, `alertsChannel`, or a non-empty
+ * `channels` record).
  */
 declare const slackBundle: AgentRuleBundle;
 

package/lib/index.d.ts

@@ -247,9 +247,38 @@ interface AgentSkill {
     readonly paths?: ReadonlyArray<string>;
     /**
      * Resource directories bundled with the skill (e.g., references/, scripts/, assets/).
+     * Documentation hint only — directory names listed here are not emitted to disk.
+     * Prefer {@link referenceFiles} to ship actual companion file contents.
+     *
+     * @deprecated Use {@link referenceFiles} to emit physical companion files.
      * @example ['references/', 'scripts/']
      */
     readonly references?: ReadonlyArray<string>;
+    /**
+     * Companion files shipped alongside the SKILL.md (e.g., templates, references, scripts).
+     * Each entry is rendered as a TextFile under the skill's directory on every
+     * platform that emits skills (Claude: `.claude/skills/{name}/{path}`,
+     * Cursor: `.cursor/skills/{name}/{path}`).
+     *
+     * Use this for skill assets that benefit from being separate files rather than
+     * inlined into the skill instructions — large templates, reference tables,
+     * runnable scripts.
+     *
+     * Per-platform `platforms.{claude,cursor}.exclude` flags suppress reference
+     * files for that platform alongside the SKILL.md.
+     *
+     * @example
+     * referenceFiles: [
+     *   { path: '_references/templates/_template-FR.md', content: '# Functional Requirement\n...' },
+     *   { path: '_references/standards-and-frameworks.md', content: '# Standards\n...' },
+     * ]
+     */
+    readonly referenceFiles?: ReadonlyArray<{
+        /** Path relative to the skill directory (e.g., `_references/templates/_template-FR.md`). */
+        readonly path: string;
+        /** File contents written verbatim. */
+        readonly content: string;
+    }>;
     /**
      * Context isolation mode. Set to 'fork' to run in an isolated subagent context.
      */
@@ -1195,8 +1224,15 @@ declare const requirementsAnalystBundle: AgentRuleBundle;
 declare const researchPipelineBundle: AgentRuleBundle;
 
 /**
- * Slack bundle — opt-in via `includeBundles: ["slack"]`.
- * Never auto-detected (no Slack dependency to introspect).
+ * Slack bundle — auto-activated when the consuming project declares a
+ * Slack integration via `ProjectMetadata.slack`. Consumers can still
+ * opt in manually via `includeBundles: ["slack"]` when they have no
+ * `ProjectMetadata` configured.
+ *
+ * Detection signal: any truthy value on
+ * `ProjectMetadata.of(project).metadata.slack` that carries at least one
+ * channel reference (`projectChannel`, `alertsChannel`, or a non-empty
+ * `channels` record).
  */
 declare const slackBundle: AgentRuleBundle;
 

package/lib/index.js

@@ -6727,11 +6727,106 @@ var researchPipelineBundle = {
   ]
 };
 
+// src/projects/project-metadata.ts
+var import_projen2 = require("projen");
+var import_javascript = require("projen/lib/javascript");
+var GITHUB_HTTPS_RE = /(?:https?:\/\/|git\+https:\/\/)github\.com\/([^/]+)\/([^/.]+)(?:\.git)?/;
+var GITHUB_SSH_RE = /git@github\.com:([^/]+)\/([^/.]+)(?:\.git)?/;
+function parseGitHubUrl(url) {
+  const httpsMatch = url.match(GITHUB_HTTPS_RE);
+  if (httpsMatch) {
+    return { owner: httpsMatch[1], name: httpsMatch[2] };
+  }
+  const sshMatch = url.match(GITHUB_SSH_RE);
+  if (sshMatch) {
+    return { owner: sshMatch[1], name: sshMatch[2] };
+  }
+  return { owner: void 0, name: void 0 };
+}
+var ProjectMetadata = class _ProjectMetadata extends import_projen2.Component {
+  /**
+   * Returns the ProjectMetadata instance for a project. Walks up the parent
+   * chain so sub-projects resolve the metadata declared on a root
+   * `MonorepoProject` without needing a duplicate declaration of their own.
+   * Returns `undefined` if no ancestor has a `ProjectMetadata` component.
+   */
+  static of(project) {
+    const isProjectMetadata = (c) => c instanceof _ProjectMetadata;
+    let current = project;
+    while (current) {
+      const found = current.components.find(isProjectMetadata);
+      if (found) {
+        return found;
+      }
+      current = current.parent;
+    }
+    return void 0;
+  }
+  constructor(project, options = {}) {
+    super(project);
+    this.metadata = this.resolveMetadata(options);
+  }
+  /**
+   * Merges explicit options with auto-detected values.
+   * Auto-detection reads the repository URL from package.json
+   * (via Projen's NodePackage manifest) and parses GitHub owner/name.
+   * Explicit options always take precedence over auto-detected values.
+   */
+  resolveMetadata(options) {
+    const autoDetected = this.autoDetectRepository();
+    return {
+      repository: {
+        owner: options.repository?.owner ?? autoDetected.owner,
+        name: options.repository?.name ?? autoDetected.name,
+        defaultBranch: options.repository?.defaultBranch ?? "main"
+      },
+      githubProject: options.githubProject,
+      organization: options.organization,
+      slack: options.slack,
+      labels: options.labels,
+      milestones: options.milestones,
+      docsPath: options.docsPath,
+      deployment: options.deployment
+    };
+  }
+  /**
+   * Attempts to auto-detect repository owner and name from the Projen
+   * project's package.json repository field.
+   */
+  autoDetectRepository() {
+    if (!(this.project instanceof import_javascript.NodeProject)) {
+      return { owner: void 0, name: void 0 };
+    }
+    const manifest = this.project.package.manifest;
+    const repoField = manifest.repository;
+    if (!repoField) {
+      return { owner: void 0, name: void 0 };
+    }
+    const url = typeof repoField === "string" ? repoField : repoField.url ?? "";
+    return parseGitHubUrl(url);
+  }
+};
+
 // src/agent/bundles/slack.ts
+function hasSlackConfig(slack) {
+  if (!slack) {
+    return false;
+  }
+  if (slack.projectChannel || slack.alertsChannel) {
+    return true;
+  }
+  if (slack.channels && Object.keys(slack.channels).length > 0) {
+    return true;
+  }
+  return false;
+}
 var slackBundle = {
   name: "slack",
-  description: "Slack MCP message formatting and best practices",
-  appliesWhen: () => false,
+  description: "Slack MCP message formatting and best practices. Auto-activates when ProjectMetadata declares a Slack integration; can still be force-included via `includeBundles: ['slack']`.",
+  appliesWhen: (project) => {
+    const pm = ProjectMetadata.of(project);
+    return hasSlackConfig(pm?.metadata.slack);
+  },
   rules: [
     {
       name: "slack-message-formatting",
@@ -6760,7 +6855,11 @@ var slackBundle = {
         "   \u2022 Feature B: <https://github.com/org/repo/pull/2|repo#2>",
         "   ```",
         "",
-        "5. **Avoid:** Plain URLs immediately after a bullet/label on the same line (e.g., `\u2022 Feature A: https://github.com/...`) when sending via API, as it can render with bullets inside or between links"
+        "5. **Avoid:** Plain URLs immediately after a bullet/label on the same line (e.g., `\u2022 Feature A: https://github.com/...`) when sending via API, as it can render with bullets inside or between links",
+        "",
+        "## Activation",
+        "",
+        "This bundle auto-activates when the consuming project declares a Slack integration through `ProjectMetadata` (any of `slack.projectChannel`, `slack.alertsChannel`, or a non-empty `slack.channels` record). If no `ProjectMetadata` is configured, opt in manually via `AgentConfigOptions.includeBundles: ['slack']`."
       ].join("\n"),
       tags: ["workflow"]
     }
@@ -7757,8 +7856,8 @@ var typescriptBundle = {
 };
 
 // src/vitest/vitest-component.ts
-var import_projen2 = require("projen");
-var import_javascript = require("projen/lib/javascript");
+var import_projen3 = require("projen");
+var import_javascript2 = require("projen/lib/javascript");
 var import_textfile = require("projen/lib/textfile");
 
 // src/versions.ts
@@ -7836,7 +7935,7 @@ var VERSION = {
 };
 
 // src/vitest/vitest-component.ts
-var Vitest = class _Vitest extends import_projen2.Component {
+var Vitest = class _Vitest extends import_projen3.Component {
   constructor(project, options = {}) {
     super(project);
     this.project = project;
@@ -7875,7 +7974,7 @@ var Vitest = class _Vitest extends import_projen2.Component {
   preSynthesize() {
     super.preSynthesize();
     for (const component of this.project.components) {
-      if (component instanceof import_javascript.Jest) {
+      if (component instanceof import_javascript2.Jest) {
         throw new Error("Vitest cannot be used together with Jest");
       }
     }
@@ -8036,86 +8135,6 @@ function prefix(rel, entry) {
   return path.posix.join(rel, entry);
 }
 
-// src/projects/project-metadata.ts
-var import_projen5 = require("projen");
-var import_javascript2 = require("projen/lib/javascript");
-var GITHUB_HTTPS_RE = /(?:https?:\/\/|git\+https:\/\/)github\.com\/([^/]+)\/([^/.]+)(?:\.git)?/;
-var GITHUB_SSH_RE = /git@github\.com:([^/]+)\/([^/.]+)(?:\.git)?/;
-function parseGitHubUrl(url) {
-  const httpsMatch = url.match(GITHUB_HTTPS_RE);
-  if (httpsMatch) {
-    return { owner: httpsMatch[1], name: httpsMatch[2] };
-  }
-  const sshMatch = url.match(GITHUB_SSH_RE);
-  if (sshMatch) {
-    return { owner: sshMatch[1], name: sshMatch[2] };
-  }
-  return { owner: void 0, name: void 0 };
-}
-var ProjectMetadata = class _ProjectMetadata extends import_projen5.Component {
-  /**
-   * Returns the ProjectMetadata instance for a project. Walks up the parent
-   * chain so sub-projects resolve the metadata declared on a root
-   * `MonorepoProject` without needing a duplicate declaration of their own.
-   * Returns `undefined` if no ancestor has a `ProjectMetadata` component.
-   */
-  static of(project) {
-    const isProjectMetadata = (c) => c instanceof _ProjectMetadata;
-    let current = project;
-    while (current) {
-      const found = current.components.find(isProjectMetadata);
-      if (found) {
-        return found;
-      }
-      current = current.parent;
-    }
-    return void 0;
-  }
-  constructor(project, options = {}) {
-    super(project);
-    this.metadata = this.resolveMetadata(options);
-  }
-  /**
-   * Merges explicit options with auto-detected values.
-   * Auto-detection reads the repository URL from package.json
-   * (via Projen's NodePackage manifest) and parses GitHub owner/name.
-   * Explicit options always take precedence over auto-detected values.
-   */
-  resolveMetadata(options) {
-    const autoDetected = this.autoDetectRepository();
-    return {
-      repository: {
-        owner: options.repository?.owner ?? autoDetected.owner,
-        name: options.repository?.name ?? autoDetected.name,
-        defaultBranch: options.repository?.defaultBranch ?? "main"
-      },
-      githubProject: options.githubProject,
-      organization: options.organization,
-      slack: options.slack,
-      labels: options.labels,
-      milestones: options.milestones,
-      docsPath: options.docsPath,
-      deployment: options.deployment
-    };
-  }
-  /**
-   * Attempts to auto-detect repository owner and name from the Projen
-   * project's package.json repository field.
-   */
-  autoDetectRepository() {
-    if (!(this.project instanceof import_javascript2.NodeProject)) {
-      return { owner: void 0, name: void 0 };
-    }
-    const manifest = this.project.package.manifest;
-    const repoField = manifest.repository;
-    if (!repoField) {
-      return { owner: void 0, name: void 0 };
-    }
-    const url = typeof repoField === "string" ? repoField : repoField.url ?? "";
-    return parseGitHubUrl(url);
-  }
-};
-
 // src/agent/renderers/claude-renderer.ts
 var import_projen6 = require("projen");
 var import_textfile2 = require("projen/lib/textfile");
@@ -8381,6 +8400,13 @@ var ClaudeRenderer = class _ClaudeRenderer {
       new import_textfile2.TextFile(component, `.claude/skills/${skill.name}/SKILL.md`, {
         lines
       });
+      if (skill.referenceFiles && skill.referenceFiles.length > 0) {
+        for (const file of skill.referenceFiles) {
+          new import_textfile2.TextFile(component, `.claude/skills/${skill.name}/${file.path}`, {
+            lines: file.content.split("\n")
+          });
+        }
+      }
     }
   }
   static renderSubAgents(component, subAgents) {
@@ -8552,6 +8578,13 @@ var CursorRenderer = class _CursorRenderer {
       new import_textfile3.TextFile(component, `.cursor/skills/${skill.name}/SKILL.md`, {
         lines
       });
+      if (skill.referenceFiles && skill.referenceFiles.length > 0) {
+        for (const file of skill.referenceFiles) {
+          new import_textfile3.TextFile(component, `.cursor/skills/${skill.name}/${file.path}`, {
+            lines: file.content.split("\n")
+          });
+        }
+      }
     }
   }
   static renderSubAgents(component, subAgents) {