@agjs/tsforge 0.1.9 → 0.1.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/config/external-plugins.ts

@@ -0,0 +1,152 @@
+import { resolve } from "node:path";
+import { isRecord } from "../lib/guards";
+import { registerExternalPack } from "../rule-packs";
+import type { IRulePack } from "../rule-packs/rule-packs.types";
+
+/** One external plugin entry from tsforge.config.json `plugins`. */
+export interface IExternalPlugin {
+  /** Module specifier or path (relative paths resolve against the repo root). */
+  readonly path: string;
+  /** Named exports to load as rule packs. Omit to load every exported pack. */
+  readonly packs?: readonly string[];
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Type guard: a well-formed IRulePack (no `as` — every field is checked). */
+export function isRulePack(value: unknown): value is IRulePack {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  if (typeof value.id !== "string" || value.id.length === 0) {
+    return false;
+  }
+
+  if (typeof value.description !== "string") {
+    return false;
+  }
+
+  if (!isRecord(value.rules) || !isRecord(value.rulesConfig)) {
+    return false;
+  }
+
+  for (const severity of Object.values(value.rulesConfig)) {
+    if (severity !== "error" && severity !== "warn") {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/** Parse the `plugins` config field into validated entries. */
+export function parsePlugins(raw: unknown): IExternalPlugin[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  const plugins: IExternalPlugin[] = [];
+
+  for (const item of raw) {
+    if (
+      !isRecord(item) ||
+      typeof item.path !== "string" ||
+      item.path.length === 0
+    ) {
+      continue;
+    }
+
+    const packs = Array.isArray(item.packs)
+      ? item.packs.filter((p): p is string => typeof p === "string")
+      : undefined;
+
+    plugins.push({
+      path: item.path,
+      ...(packs !== undefined && packs.length > 0 ? { packs } : {}),
+    });
+  }
+
+  return plugins;
+}
+
+/** Collect the candidate exports to validate from a loaded module. */
+function candidateExports(
+  mod: Record<string, unknown>,
+  names: readonly string[] | undefined
+): unknown[] {
+  if (names === undefined) {
+    return Object.values(mod);
+  }
+
+  return names.map((name) => mod[name]);
+}
+
+/**
+ * Dynamically import each plugin and collect its valid exported rule packs.
+ * Never throws — an unimportable module or an export that is not a valid pack is
+ * reported and skipped, so a broken plugin can't take down a run.
+ */
+export async function loadExternalPacks(
+  plugins: readonly IExternalPlugin[],
+  cwd: string,
+  report: (message: string) => void
+): Promise<IRulePack[]> {
+  const out: IRulePack[] = [];
+
+  for (const plugin of plugins) {
+    const specifier = plugin.path.startsWith(".")
+      ? resolve(cwd, plugin.path)
+      : plugin.path;
+
+    let mod: unknown;
+
+    try {
+      mod = await import(specifier);
+    } catch (err) {
+      report(`plugin '${plugin.path}' failed to load: ${errMessage(err)}`);
+
+      continue;
+    }
+
+    if (!isRecord(mod)) {
+      continue;
+    }
+
+    for (const candidate of candidateExports(mod, plugin.packs)) {
+      if (isRulePack(candidate)) {
+        out.push(candidate);
+        report(`plugin '${plugin.path}': loaded pack '${candidate.id}'`);
+      } else {
+        report(
+          `plugin '${plugin.path}': an export is not a valid rule pack — skipped`
+        );
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Load every configured plugin, register its packs in the rule-pack registry,
+ * and return the registered pack ids (to fold into the active pack list so the
+ * gate runs them). Never throws.
+ */
+export async function loadAndRegisterPlugins(
+  plugins: readonly IExternalPlugin[],
+  cwd: string,
+  report: (message: string) => void
+): Promise<string[]> {
+  const packs = await loadExternalPacks(plugins, cwd, report);
+  const ids: string[] = [];
+
+  for (const pack of packs) {
+    registerExternalPack(pack);
+    ids.push(pack.id);
+  }
+
+  return ids;
+}

package/src/config/tsforge-config.ts

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { isRecord } from "../lib/guards";
 import { PACK_REGISTRY } from "../stack-detection";
 import { parseMcpServers, type IMcpServerConfig } from "../mcp";
+import { parsePlugins, type IExternalPlugin } from "./external-plugins";
 
 /**
  * User-defined configuration from tsforge.config.json
@@ -31,6 +32,13 @@ export interface ITsforgeProjectConfig {
    * interpolated from the environment at load time. Opt-in: absent ⇒ no MCP.
    */
   readonly mcpServers?: Readonly<Record<string, IMcpServerConfig>>;
+
+  /**
+   * External plugins providing extra rule packs, loaded without recompiling
+   * tsforge. Each entry names a module (or relative path) and, optionally, which
+   * exported packs to use. Opt-in: absent ⇒ only built-in packs.
+   */
+  readonly plugins?: readonly IExternalPlugin[];
 }
 
 function warnConfig(msg: string): void {
@@ -177,6 +185,7 @@ function buildConfigFields(
     packs?: { include?: readonly string[]; exclude?: readonly string[] };
     rules?: Record<string, "error" | "warn" | "off">;
     mcpServers?: Record<string, IMcpServerConfig>;
+    plugins?: readonly IExternalPlugin[];
   } = {};
 
   if (parsed.stack !== undefined) {
@@ -211,6 +220,14 @@ function buildConfigFields(
     }
   }
 
+  if (parsed.plugins !== undefined) {
+    const plugins = parsePlugins(parsed.plugins);
+
+    if (plugins.length > 0) {
+      configFields.plugins = plugins;
+    }
+  }
+
   return configFields;
 }
 

package/src/loop/run.ts

@@ -191,20 +191,31 @@ function effectiveParserFor(
   return flags.legacyFeedback() ? parseEslintJson : parse;
 }
 
-/** Detect the stack and fold in tsforge.config.json pack/rule overrides. */
-async function resolveStackForRun(cwd: string): Promise<{
+/** Detect the stack and fold in tsforge.config.json pack/rule overrides, plus any
+ *  rule packs from configured external plugins. */
+async function resolveStackForRun(
+  cwd: string,
+  report: (message: string) => void
+): Promise<{
   stackProfile: Awaited<ReturnType<typeof detectStack>>;
   ruleOverrides: Readonly<Record<string, "error" | "warn" | "off">>;
 }> {
   const detectedProfile = await detectStack(cwd);
   const { loadTsforgeConfig, resolveActivePacks, normalizeRuleOverrides } =
     await import("../config/tsforge-config");
+  const { loadAndRegisterPlugins } = await import("../config/external-plugins");
   const cfg = await loadTsforgeConfig(cwd);
+  const activePacks = resolveActivePacks(detectedProfile.packs, cfg);
+  const externalIds =
+    cfg.plugins === undefined
+      ? []
+      : await loadAndRegisterPlugins(cfg.plugins, cwd, report);
 
   return {
     stackProfile: {
       ...detectedProfile,
-      packs: resolveActivePacks(detectedProfile.packs, cfg),
+      packs:
+        externalIds.length > 0 ? [...activePacks, ...externalIds] : activePacks,
     },
     ruleOverrides: normalizeRuleOverrides(cfg),
   };
@@ -268,7 +279,12 @@ export async function runTask(
   });
 
   // Detect stack once per run, early; tsforge.config.json may adjust it
-  const { stackProfile, ruleOverrides } = await resolveStackForRun(cwd);
+  const { stackProfile, ruleOverrides } = await resolveStackForRun(
+    cwd,
+    (message) => {
+      report({ kind: "tool", task: task.id, message });
+    }
+  );
 
   report({
     kind: "tool",

package/src/loop/session.ts

@@ -26,6 +26,7 @@ import {
   resolveActivePacks,
 } from "../config/tsforge-config";
 import { connectMcpServers } from "../mcp";
+import { loadAndRegisterPlugins } from "../config/external-plugins";
 import { LOOP_LIMITS, RUN_STATUS } from "./loop.constants";
 import type { Reporter } from "./loop.types";
 import { CHAT_SYSTEM, COMPACT_SYSTEM } from "./prompt";
@@ -434,9 +435,25 @@ export class Session {
     // pack selection and rule-severity overrides.
     const detected = await detectStack(cfg.cwd);
     const projectConfig = await loadTsforgeConfig(cfg.cwd);
+    const activePacks = resolveActivePacks(detected.packs, projectConfig);
+    // Opt-in: load rule packs from external plugins and fold their ids into the
+    // active packs so the gate runs them. loadAndRegisterPlugins never throws.
+    const externalPackIds =
+      projectConfig.plugins === undefined
+        ? []
+        : await loadAndRegisterPlugins(
+            projectConfig.plugins,
+            cfg.cwd,
+            (message) => {
+              report({ kind: "tool", task: SESSION_ID, message });
+            }
+          );
     const stackProfile = {
       ...detected,
-      packs: resolveActivePacks(detected.packs, projectConfig),
+      packs:
+        externalPackIds.length > 0
+          ? [...activePacks, ...externalPackIds]
+          : activePacks,
     };
     const ruleOverrides = normalizeRuleOverrides(projectConfig);
 

package/src/rule-packs/index.ts

@@ -1,5 +1,6 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
+import type { IRulePack } from "./rule-packs.types";
 import { bullmqPack } from "./bullmq";
 import { commentHygienePack } from "./comment-hygiene";
 import { codeFlowPack } from "./code-flow";
@@ -43,6 +44,31 @@ function isRulePackId(id: unknown): id is IRulePackId {
   return typeof id === "string" && id in RULE_PACKS;
 }
 
+/** Externally-registered rule packs (from tsforge.config.json `plugins`). Kept
+ *  separate from the built-in RULE_PACKS so a user pack can never shadow a
+ *  built-in by id; rule-name collisions still fail the build in
+ *  buildPackEslintConfig. */
+const EXTERNAL_PACKS = new Map<string, IRulePack>();
+
+/** Register an external rule pack so its id resolves in buildPackEslintConfig. */
+export function registerExternalPack(pack: IRulePack): void {
+  EXTERNAL_PACKS.set(pack.id, pack);
+}
+
+/** Drop all registered external packs (used by tests for isolation). */
+export function clearExternalPacks(): void {
+  EXTERNAL_PACKS.clear();
+}
+
+/** Resolve a pack id to its definition, built-ins first, then external packs. */
+function lookupPack(packId: string): IRulePack | undefined {
+  if (isRulePackId(packId)) {
+    return RULE_PACKS[packId];
+  }
+
+  return EXTERNAL_PACKS.get(packId);
+}
+
 /** Apply rule overrides: "off" drops a rule, error/warn replaces its severity. */
 function applyOverrides(
   mergedRulesConfig: Readonly<Record<string, "error" | "warn">>,
@@ -93,7 +119,7 @@ export function buildPackEslintConfig(
   const seenRuleNames = new Set<string>();
 
   for (const packId of packIds) {
-    const pack = isRulePackId(packId) ? RULE_PACKS[packId] : undefined;
+    const pack = lookupPack(packId);
 
     // Skip pack IDs known to stack-detection but absent from RULE_PACKS
     if (pack === undefined) {