@supacloud/compiler 0.8.0 → 0.9.0

package/dist/index.js

@@ -101,6 +101,15 @@ function createDefaultTraitHandlers() {
         return initializer && ts.isCallExpression(initializer) && expressionName(initializer.expression) === "defineModule" ? node.name.text : undefined;
       }
     },
+    {
+      kind: "defineFeatureSlice",
+      detect: (node) => {
+        if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name))
+          return;
+        const initializer = node.initializer;
+        return initializer && ts.isCallExpression(initializer) && expressionName(initializer.expression) === "defineFeatureSlice" ? node.name.text : undefined;
+      }
+    },
     {
       kind: "injectionToken",
       detect: (node) => {
@@ -449,6 +458,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     checker,
     tokensByName: new Map,
     classesByName: new Map,
+    variablesByName: new Map,
     diagnostics: []
   };
   const nativeTraitFiles = new Map;
@@ -483,9 +493,9 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
         });
       }
     }
-    if (!cache || traits?.has("defineModule")) {
+    if (!cache || traits?.has("defineModule") || traits?.has("defineFeatureSlice")) {
       for (const call of descendantsOfKind(sf, ts3.isCallExpression)) {
-        if (nodeText(call.expression) !== "defineModule")
+        if (!["defineModule", "defineFeatureSlice"].includes(nodeText(call.expression)))
           continue;
         const parent = call.parent;
         if (!parent || !ts3.isVariableDeclaration(parent))
@@ -791,6 +801,9 @@ function indexFile(sf, ctx) {
   }
   for (const statement of sf.statements.filter(ts3.isVariableStatement)) {
     for (const decl of statement.declarationList.declarations) {
+      if (ts3.isIdentifier(decl.name) && !ctx.variablesByName.has(decl.name.text)) {
+        ctx.variablesByName.set(decl.name.text, decl);
+      }
       const info = parseTokenVariable(decl, sf.fileName);
       if (info && !ctx.tokensByName.has(info.name)) {
         ctx.tokensByName.set(info.name, info);
@@ -828,6 +841,7 @@ function parseTokenVariable(decl, file) {
 function parseModule(candidate, nameByNode, ctx) {
   const { options, className, file, line } = candidate;
   const name = nameByNode.get(candidate.node) ?? className;
+  const featureSpec = parseFeatureSpec(getProp(options, "spec"), ctx);
   const tags = arrayProp(options, "tags").map((el) => ts3.isStringLiteral(el) ? el.text : nodeText(el).replace(/['"]/g, "")).filter(Boolean);
   const aspects = parseAspectRefs(getProp(options, "aspects"), ctx, `module ${name}`);
   const imports = arrayProp(options, "imports").map((el) => {
@@ -1002,8 +1016,71 @@ function parseModule(candidate, nameByNode, ctx) {
     jobs,
     queries,
     ...aspects.length > 0 ? { aspects } : {},
-    exports
+    exports,
+    ...featureSpec ? { featureSpec } : {}
+  };
+}
+function parseFeatureSpec(input, ctx, seen = new Set) {
+  if (!input)
+    return;
+  if (seen.has(input))
+    return;
+  seen.add(input);
+  if (ts3.isIdentifier(input)) {
+    const local = input.getSourceFile().statements.flatMap((statement) => ts3.isVariableStatement(statement) ? [...statement.declarationList.declarations] : []);
+    const resolved = resolveDeclaration(input, ctx)[0];
+    const decl = (resolved && ts3.isVariableDeclaration(resolved) ? resolved : undefined) ?? ctx.variablesByName.get(input.text) ?? local.find((candidate) => ts3.isIdentifier(candidate.name) && candidate.name.text === input.text) ?? descendantsOfKind(input.getSourceFile(), ts3.isVariableDeclaration).find((candidate) => ts3.isIdentifier(candidate.name) && candidate.name.text === input.text);
+    if (decl && ts3.isVariableDeclaration(decl))
+      return parseFeatureSpec(decl.initializer, ctx, seen);
+  }
+  if (ts3.isCallExpression(input) && nodeText(input.expression) === "defineFeatureSpec") {
+    return parseFeatureSpec(input.arguments[0], ctx, seen);
+  }
+  if (ts3.isAsExpression(input) || ts3.isSatisfiesExpression(input) || ts3.isParenthesizedExpression(input)) {
+    return parseFeatureSpec(input.expression, ctx, seen);
+  }
+  const invalid = () => {
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "invalid-feature-spec",
+      message: "Feature spec must use static name, states and transition objects.",
+      file: sourcePath(ctx.rootDir, input.getSourceFile().fileName),
+      line: lineOf(input)
+    });
+    return;
   };
+  if (!ts3.isObjectLiteralExpression(input))
+    return invalid();
+  const name = stringLiteralProp(input, "name");
+  const statesExpr = getProp(input, "states");
+  const transitionObject = getProp(input, "transitions");
+  if (!name || !statesExpr || !ts3.isArrayLiteralExpression(statesExpr) || statesExpr.elements.some((state) => !ts3.isStringLiteral(state)) || !transitionObject || !ts3.isObjectLiteralExpression(transitionObject) || input.properties.some((property) => !ts3.isPropertyAssignment(property))) {
+    return invalid();
+  }
+  const states = statesExpr.elements.map((state) => state.text);
+  const transitions = [];
+  for (const property of transitionObject.properties) {
+    if (!ts3.isPropertyAssignment(property) || ts3.isComputedPropertyName(property.name) || !ts3.isObjectLiteralExpression(property.initializer))
+      return invalid();
+    const options = property.initializer;
+    const from = stringLiteralProp(options, "from");
+    const to = stringLiteralProp(options, "to");
+    if (!from || !to || options.properties.some((prop) => !ts3.isPropertyAssignment(prop)) || ["permission", "command", "route", "audit"].some((key) => getProp(options, key) && !stringLiteralProp(options, key)) || ["transaction", "idempotency"].some((key) => getProp(options, key) && !commandModeProp(options, key))) {
+      return invalid();
+    }
+    transitions.push({
+      name: propertyName(property.name),
+      from,
+      to,
+      permission: stringLiteralProp(options, "permission"),
+      command: stringLiteralProp(options, "command"),
+      route: stringLiteralProp(options, "route"),
+      transaction: commandModeProp(options, "transaction"),
+      idempotency: commandModeProp(options, "idempotency"),
+      audit: stringLiteralProp(options, "audit")
+    });
+  }
+  return { name, states, transitions, file: sourcePath(ctx.rootDir, input.getSourceFile().fileName), line: lineOf(input) };
 }
 function commandModeProp(object, name) {
   const value = stringLiteralProp(object, name);
@@ -2174,9 +2251,297 @@ function sourcePath(rootDir, absFile) {
 function warn(ctx, code, message, file, line) {
   ctx.diagnostics.push({ severity: "warn", code, message, file, line });
 }
+// src/feature.ts
+function validateFeatureSpec(spec, module) {
+  const diagnostics = [];
+  const error = (code, message) => {
+    diagnostics.push({ severity: "error", code, message, file: spec.file, line: spec.line });
+  };
+  if (!spec.name.trim() || spec.states.length === 0 || spec.states.some((state) => !state.trim()) || new Set(spec.states).size !== spec.states.length) {
+    error("invalid-feature-states", "Feature name and states must be non-empty; states must be unique.");
+  }
+  const names = new Set;
+  for (const transition of spec.transitions) {
+    if (!transition.name.trim() || names.has(transition.name)) {
+      error("duplicate-feature-transition", `Feature ${spec.name} has duplicate/empty transition '${transition.name}'.`);
+    }
+    names.add(transition.name);
+    if (!spec.states.includes(transition.from) || !spec.states.includes(transition.to)) {
+      error("invalid-feature-transition", `Transition ${transition.name} references an undeclared state.`);
+    }
+    if (transition.permission !== undefined && !transition.permission.trim()) {
+      error("feature-governance-drift", `Transition ${transition.name} declares an empty permission.`);
+    }
+    if (!module)
+      continue;
+    const commands = module.commands.filter((command2) => command2.className === transition.command || command2.name === transition.command);
+    const command = commands[0];
+    if (transition.command && commands.length !== 1) {
+      error("feature-command-unresolved", `Transition ${transition.name} must reference exactly one command in module ${module.name}.`);
+    }
+    if (!transition.command && [transition.permission, transition.transaction, transition.idempotency, transition.audit].some((value) => value !== undefined)) {
+      error("feature-command-unresolved", `Transition ${transition.name} declares governance without a command binding.`);
+    }
+    if (command) {
+      for (const key of ["permission", "transaction", "idempotency", "audit"]) {
+        if (transition[key] !== undefined && transition[key] !== command[key]) {
+          error("feature-governance-drift", `Transition ${transition.name} ${key} differs from command ${command.className}.`);
+        }
+      }
+    }
+    if (transition.route) {
+      const routes = module.controllers.flatMap((controller) => controller.routes.filter((route) => `${route.method} ${joinRoutePaths(controller.path, route.path)}` === transition.route));
+      if (routes.length !== 1) {
+        error("feature-route-unresolved", `Transition ${transition.name} must reference exactly one route '${transition.route}' in module ${module.name}.`);
+      } else if (command && routes[0].command !== command.className) {
+        error("feature-route-drift", `Route ${transition.route} is not bound to ${command.className}.`);
+      }
+    }
+  }
+  return diagnostics;
+}
+function generateFeatureSource(spec) {
+  const errors = validateFeatureSpec(spec);
+  if (errors.length)
+    throw new Error(errors.map((error) => error.message).join(`
+`));
+  if (spec.transitions.some((transition) => !transition.permission)) {
+    throw new Error("Spec-to-Code requires an explicit permission for every transition.");
+  }
+  const transitions = spec.transitions.map((transition, index) => ({
+    ...transition,
+    command: `Transition${index + 1}Command`
+  }));
+  if (transitions.some((transition) => transition.route)) {
+    throw new Error("Generate the command slice first; existing HTTP routes require explicit schema and handler implementations.");
+  }
+  const sourceSpec = { name: spec.name, states: spec.states, transitions: Object.fromEntries(transitions.map((transition) => {
+    const { name, ...options } = transition;
+    return [name, options];
+  })) };
+  return [
+    'import { Command, defineFeatureSlice, defineFeatureSpec } from "@supacloud/app";',
+    "",
+    `export const featureSpec = defineFeatureSpec(${JSON.stringify(sourceSpec, null, 2)});`,
+    `export type FeatureState = typeof featureSpec.states[number];`,
+    "",
+    ...transitions.flatMap((transition) => [
+      `@Command(${JSON.stringify({
+        name: `${spec.name}.${transition.name}`,
+        permission: transition.permission,
+        transaction: transition.transaction ?? "none",
+        idempotency: transition.idempotency ?? "none",
+        audit: transition.audit
+      })})`,
+      `export class ${transition.command} {`,
+      `  execute(state: FeatureState): never {`,
+      `    if (state !== ${JSON.stringify(transition.from)}) throw new Error("Invalid transition state");`,
+      `    throw new Error(${JSON.stringify(`Implement ${spec.name}.${transition.name}: persist state ${transition.to}`)});`,
+      "  }",
+      ""
+    ]),
+    "export const FeatureSlice = defineFeatureSlice({",
+    `  name: ${JSON.stringify(spec.name)},`,
+    '  tags: ["type:feature"],',
+    "  spec: featureSpec,",
+    `  providers: [${transitions.map((transition) => transition.command).join(", ")}],`,
+    "});",
+    ""
+  ].join(`
+`);
+}
+// src/fixes.ts
+import { randomUUID } from "node:crypto";
+import { lstat, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname as dirname2, isAbsolute, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
+import * as ts4 from "@typescript/typescript6";
+async function applyDiagnosticFix(fix, options = {}) {
+  if (!fix || typeof fix.targetFile !== "string")
+    throw new Error("Invalid DiagnosticFix");
+  const root = await realpath(options.rootDir ?? process.cwd());
+  const file = resolve2(root, fix.targetFile);
+  const stat = await lstat(file);
+  const resolved = await realpath(file);
+  const relativePath = relative2(root, resolved);
+  if (stat.isSymbolicLink() || !stat.isFile() || isAbsolute(relativePath) || relativePath === ".." || relativePath.startsWith(`..${sep2}`)) {
+    throw new Error("Fix target must be a regular file inside rootDir");
+  }
+  const original = await readFile(file, "utf8");
+  let source = parse(file, original);
+  let content;
+  switch (fix.type) {
+    case "add_module_import": {
+      if (!fix.importPath || !fix.symbol)
+        throw new Error("Module fix requires importPath and symbol");
+      identifier(fix.symbol);
+      const withImport = importSymbol(source, fix.importPath, fix.symbol);
+      source = parse(file, withImport);
+      const object = unique(moduleObjects(source).filter((candidate) => !fix.targetModule || stringProperty(candidate, "name") === fix.targetModule), "target module");
+      const imports = property(object, "imports");
+      if (imports && !ts4.isArrayLiteralExpression(imports.initializer)) {
+        throw new Error("Module imports must be a static array");
+      }
+      const values = imports && ts4.isArrayLiteralExpression(imports.initializer) ? imports.initializer.elements : [];
+      if (values.some(ts4.isSpreadElement))
+        throw new Error("Module imports cannot contain spread elements");
+      content = values.some((value) => ts4.isIdentifier(value) && value.text === fix.symbol) ? withImport : replaceProperty(source, object, "imports", ts4.factory.createArrayLiteralExpression([
+        ...values,
+        ts4.factory.createIdentifier(fix.symbol)
+      ]));
+      break;
+    }
+    case "add_command_permission": {
+      const permission = options.permission ?? fix.permission;
+      if (!permission?.trim()) {
+        throw new Error("Permission fix requires an explicit permission; privileges are never inferred");
+      }
+      const command = findClass(source, fix.command);
+      const object = decoratorObject(command, "Command");
+      const current = property(object, "permission");
+      if (current && (!ts4.isStringLiteral(current.initializer) || current.initializer.text !== permission)) {
+        throw new Error("Command permission already exists with a different value");
+      }
+      content = current ? original : replaceProperty(source, object, "permission", ts4.factory.createStringLiteral(permission));
+      break;
+    }
+    case "add_route_parameter_binding": {
+      const controller = findClass(source, fix.controller);
+      const method = unique(controller.members.filter((member) => ts4.isMethodDeclaration(member) && nameOf(member.name) === fix.route), "route handler");
+      const parameter = unique(method.parameters.filter((candidate) => ts4.isIdentifier(candidate.name) && candidate.name.text === fix.parameter), "same-named route parameter");
+      const binding = fix.binding === "param" ? "Param" : fix.binding === "query" ? "Query" : undefined;
+      if (!binding)
+        throw new Error("Invalid route binding");
+      const decorators = ts4.getDecorators(parameter) ?? [];
+      if (decorators.length > 0)
+        throw new Error("Parameter already has a decorator");
+      const framework = unique(source.statements.filter((statement) => ts4.isImportDeclaration(statement) && statement.importClause?.namedBindings && ts4.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some((element) => ["Controller", "Get", "Post", "Put", "Patch", "Delete", "Head", "Options"].includes(element.name.text))), "framework import");
+      if (!ts4.isImportDeclaration(framework) || !ts4.isStringLiteral(framework.moduleSpecifier)) {
+        throw new Error("Framework import must be static");
+      }
+      const edited = original.slice(0, parameter.getStart(source)) + `@${binding}(${JSON.stringify(fix.parameter)}) ` + original.slice(parameter.getStart(source));
+      content = importSymbol(parse(file, edited), framework.moduleSpecifier.text, binding);
+      break;
+    }
+    default:
+      throw new Error(`Diagnostic fix '${fix.type}' requires a manual semantic decision; no files changed`);
+  }
+  parse(file, content);
+  const result = { file, changed: content !== original, content };
+  if (options.dryRun === false && result.changed) {
+    const temporary = `${file}.supacloud-fix-${randomUUID()}`;
+    try {
+      await writeFile(temporary, content, { encoding: "utf8", flag: "wx", mode: stat.mode });
+      if (await readFile(file, "utf8") !== original)
+        throw new Error("Target changed while preparing the fix");
+      await rename(temporary, file);
+    } finally {
+      await unlink(temporary).catch(() => {});
+    }
+  }
+  return result;
+}
+function parse(file, text) {
+  const result = ts4.transpileModule(text, {
+    fileName: file,
+    reportDiagnostics: true,
+    compilerOptions: { target: ts4.ScriptTarget.ESNext, experimentalDecorators: true }
+  });
+  if (result.diagnostics?.some((item) => item.category === ts4.DiagnosticCategory.Error)) {
+    throw new Error("Cannot fix syntactically invalid TypeScript");
+  }
+  return ts4.createSourceFile(file, text, ts4.ScriptTarget.Latest, true, ts4.ScriptKind.TS);
+}
+function unique(items, description) {
+  if (items.length !== 1)
+    throw new Error(`Expected exactly one ${description}; found ${items.length}`);
+  return items[0];
+}
+function identifier(value) {
+  if (!/^[A-Za-z_$][\w$]*$/.test(value))
+    throw new Error(`Invalid identifier '${value}'`);
+}
+function nameOf(name) {
+  if (!name)
+    return "";
+  return ts4.isIdentifier(name) || ts4.isStringLiteral(name) || ts4.isNumericLiteral(name) ? name.text : "";
+}
+function property(object, key) {
+  if (object.properties.some((item) => !ts4.isPropertyAssignment(item) || ts4.isComputedPropertyName(item.name))) {
+    throw new Error("Fix requires explicit static object properties");
+  }
+  const values = object.properties.filter((item) => ts4.isPropertyAssignment(item) && nameOf(item.name) === key);
+  if (values.length > 1)
+    throw new Error(`Duplicate '${key}' property`);
+  return values[0];
+}
+function stringProperty(object, key) {
+  const value = property(object, key)?.initializer;
+  return value && ts4.isStringLiteral(value) ? value.text : undefined;
+}
+function replaceProperty(source, object, key, value) {
+  const previous = property(object, key);
+  const replacement = ts4.factory.createPropertyAssignment(key, value);
+  const properties = object.properties.map((item) => item === previous ? replacement : item);
+  if (!previous)
+    properties.push(replacement);
+  const updated = ts4.factory.updateObjectLiteralExpression(object, properties);
+  return source.text.slice(0, object.getStart(source)) + ts4.createPrinter().printNode(ts4.EmitHint.Expression, updated, source) + source.text.slice(object.end);
+}
+function findClass(source, name) {
+  return unique(source.statements.filter((statement) => ts4.isClassDeclaration(statement) && statement.name?.text === name), `class '${name}'`);
+}
+function decoratorObject(node, name) {
+  const decorator = unique((ts4.getDecorators(node) ?? []).filter((item) => ts4.isCallExpression(item.expression) && item.expression.expression.getText() === name), `@${name} decorator`);
+  const argument = ts4.isCallExpression(decorator.expression) ? decorator.expression.arguments[0] : undefined;
+  if (!argument || !ts4.isObjectLiteralExpression(argument))
+    throw new Error(`@${name} requires a static object`);
+  return argument;
+}
+function moduleObjects(source) {
+  const result = [];
+  for (const statement of source.statements) {
+    if (ts4.isClassDeclaration(statement) && (ts4.getDecorators(statement) ?? []).some((item) => ts4.isCallExpression(item.expression) && item.expression.expression.getText() === "Module")) {
+      result.push(decoratorObject(statement, "Module"));
+    }
+    if (ts4.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        const call = declaration.initializer;
+        if (call && ts4.isCallExpression(call) && ["defineModule", "defineFeatureSlice"].includes(call.expression.getText()) && call.arguments[0] && ts4.isObjectLiteralExpression(call.arguments[0])) {
+          result.push(call.arguments[0]);
+        }
+      }
+    }
+  }
+  return result;
+}
+function importSymbol(source, path, symbol) {
+  identifier(symbol);
+  const current = resolve2(source.fileName).replace(/\.(tsx?|mts|cts)$/, "");
+  const target = resolve2(dirname2(source.fileName), path).replace(/\.(tsx?|mts|cts)$/, "");
+  if (current === target)
+    return source.text;
+  const matches = source.statements.filter((item) => ts4.isImportDeclaration(item) && ts4.isStringLiteral(item.moduleSpecifier) && item.moduleSpecifier.text === path);
+  if (matches.length > 1)
+    throw new Error(`Ambiguous imports from '${path}'`);
+  const match = matches[0];
+  if (match && ts4.isImportDeclaration(match) && match.importClause?.namedBindings && ts4.isNamedImports(match.importClause.namedBindings) && !match.importClause.isTypeOnly) {
+    if (match.importClause.namedBindings.elements.some((item) => item.name.text === symbol))
+      return source.text;
+    const bindings = match.importClause.namedBindings;
+    const updated = ts4.factory.updateNamedImports(bindings, [
+      ...bindings.elements,
+      ts4.factory.createImportSpecifier(false, undefined, ts4.factory.createIdentifier(symbol))
+    ]);
+    return source.text.slice(0, bindings.getStart(source)) + ts4.createPrinter().printNode(ts4.EmitHint.Unspecified, updated, source) + source.text.slice(bindings.end);
+  }
+  if (match)
+    throw new Error(`Import from '${path}' is not a named value import`);
+  return `import { ${symbol} } from ${JSON.stringify(path)};
+${source.text}`;
+}
 // src/generate.ts
 import { createHash as createHash4 } from "node:crypto";
-import { access, mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { access, mkdir, rename as rename2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join2 } from "node:path";
 var HEADER = "// GENERATED BY @supacloud/compiler — do not edit";
 var INTERFACES = `export interface CompiledRoute {
@@ -2477,10 +2842,10 @@ async function writeFileIfChanged(path, content, hashes) {
 async function writeFileAtomic(path, content) {
   const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
   try {
-    await writeFile(temporaryPath, content, "utf8");
-    await rename(temporaryPath, path);
+    await writeFile2(temporaryPath, content, "utf8");
+    await rename2(temporaryPath, path);
   } catch (error) {
-    await unlink(temporaryPath).catch(() => {
+    await unlink2(temporaryPath).catch(() => {
       return;
     });
     throw error;
@@ -2885,10 +3250,10 @@ ${indent(item, 2)}`).join(",")}
           const constLine = `const ${local2} = resolveFactoryValue(${tokenIdent});`;
           return { constLine, key, expr: local2 };
         }
-        const factory = this.imports.add(provider.useFactoryName ?? "", provider.importPath, provider.importModule);
+        const factory2 = this.imports.add(provider.useFactoryName ?? "", provider.importPath, provider.importModule);
         const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
         const local = this.localVar(isMulti ? provider.useFactoryName ?? `${provider.token}Item` : provider.token, kind);
-        return { constLine: `const ${local} = ${factory}(${args});`, key, expr: local };
+        return { constLine: `const ${local} = ${factory2}(${args});`, key, expr: local };
       }
       case "existing": {
         return {
@@ -3271,6 +3636,9 @@ function renderPermissions(graph) {
 `);
 }
 
+// src/validate.ts
+import { dirname as dirname3, relative as relative3, sep as sep3 } from "node:path";
+
 // src/profiles.ts
 var MODULAR_MONOLITH_RULES = [
   {
@@ -3469,6 +3837,7 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "invalid-http-method-body": { code: "SC3004", docsUrl: "https://supacloud.dev/errors/SC3004" },
   "unmatched-route-parameter": { code: "SC3005", docsUrl: "https://supacloud.dev/errors/SC3005" },
   "missing-route-parameter-binding": { code: "SC3006", docsUrl: "https://supacloud.dev/errors/SC3006" },
+  "missing-path-param": { code: "SC3006", docsUrl: "https://supacloud.dev/errors/SC3006" },
   "duplicate-route": { code: "SC3007", docsUrl: "https://supacloud.dev/errors/SC3007" },
   "missing-body-schema": { code: "SC3008", docsUrl: "https://supacloud.dev/errors/SC3008" },
   "unused-route-schema": { code: "SC3009", docsUrl: "https://supacloud.dev/errors/SC3009" },
@@ -3479,6 +3848,7 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "unmatched-path-param-decorator": { code: "SC3014", docsUrl: "https://supacloud.dev/errors/SC3014" },
   "invalid-query-default-type": { code: "SC3015", docsUrl: "https://supacloud.dev/errors/SC3015" },
   "disallowed-body-on-get-delete": { code: "SC3016", docsUrl: "https://supacloud.dev/errors/SC3016" },
+  "invalid-body-binding": { code: "SC3016", docsUrl: "https://supacloud.dev/errors/SC3016" },
   "duplicate-query-param-binding": { code: "SC3017", docsUrl: "https://supacloud.dev/errors/SC3017" },
   "conflicting-route-method": { code: "SC3018", docsUrl: "https://supacloud.dev/errors/SC3018" },
   "missing-param-colon": { code: "SC3019", docsUrl: "https://supacloud.dev/errors/SC3019" },
@@ -3494,7 +3864,15 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "invalid-job-scope": { code: "SC4007", docsUrl: "https://supacloud.dev/errors/SC4007" },
   "dynamic-aspect-reference": { code: "SC4010", docsUrl: "https://supacloud.dev/errors/SC4010" },
   "invalid-aspect-reference": { code: "SC4011", docsUrl: "https://supacloud.dev/errors/SC4011" },
-  "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" }
+  "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" },
+  "invalid-feature-states": { code: "SC6001", docsUrl: "https://supacloud.dev/errors/SC6001" },
+  "duplicate-feature-transition": { code: "SC6002", docsUrl: "https://supacloud.dev/errors/SC6002" },
+  "invalid-feature-transition": { code: "SC6003", docsUrl: "https://supacloud.dev/errors/SC6003" },
+  "feature-command-unresolved": { code: "SC6004", docsUrl: "https://supacloud.dev/errors/SC6004" },
+  "feature-governance-drift": { code: "SC6005", docsUrl: "https://supacloud.dev/errors/SC6005" },
+  "feature-route-unresolved": { code: "SC6006", docsUrl: "https://supacloud.dev/errors/SC6006" },
+  "feature-route-drift": { code: "SC6007", docsUrl: "https://supacloud.dev/errors/SC6007" },
+  "invalid-feature-spec": { code: "SC6008", docsUrl: "https://supacloud.dev/errors/SC6008" }
 };
 function validateGraph(graph, options = false) {
   const strict = typeof options === "boolean" ? options : options.strict ?? false;
@@ -3550,7 +3928,7 @@ function validateGraph(graph, options = false) {
     }
     return;
   }
-  const error = (code, message, file, line, suggestion) => {
+  const error = (code, message, file, line, suggestion, fix) => {
     const meta = COMPILER_DIAGNOSTIC_CODES[code];
     diagnostics.push({
       severity: "error",
@@ -3560,10 +3938,11 @@ function validateGraph(graph, options = false) {
       line,
       suggestion,
       errorCode: meta?.code,
-      docsUrl: meta?.docsUrl
+      docsUrl: meta?.docsUrl,
+      fix
     });
   };
-  const warn2 = (code, message, file, line, suggestion) => {
+  const warn2 = (code, message, file, line, suggestion, fix) => {
     const meta = COMPILER_DIAGNOSTIC_CODES[code];
     diagnostics.push({
       severity: strict ? "error" : "warn",
@@ -3573,7 +3952,8 @@ function validateGraph(graph, options = false) {
       line,
       suggestion,
       errorCode: meta?.code,
-      docsUrl: meta?.docsUrl
+      docsUrl: meta?.docsUrl,
+      fix
     });
   };
   const modulesByName = new Map;
@@ -3581,6 +3961,12 @@ function validateGraph(graph, options = false) {
   const routesByKey = new Map;
   const declaredRoutes = [];
   for (const module of graph.modules) {
+    if (module.featureSpec) {
+      for (const diagnostic of validateFeatureSpec(module.featureSpec, module)) {
+        const meta = COMPILER_DIAGNOSTIC_CODES[diagnostic.code];
+        diagnostics.push({ ...diagnostic, errorCode: meta?.code, docsUrl: meta?.docsUrl });
+      }
+    }
     const previousModule = modulesByName.get(module.name);
     if (previousModule) {
       error("duplicate-module", `模块名 ${module.name} 重复（首次声明于 ${previousModule.file}:${previousModule.line}）`, module.file, module.line);
@@ -3673,7 +4059,14 @@ function validateGraph(graph, options = false) {
         if (paramBindings.length > 0) {
           for (const param of pathParams) {
             if (!paramBindings.includes(param)) {
-              warn2("missing-path-param", `Route path '${route.path}' defines parameter ':${param}', but handler ${controller.className}.${route.handler} does not bind it with @Param('${param}').`, controller.file, undefined, `Add @Param('${param}') to ${route.handler} arguments.`);
+              warn2("missing-path-param", `Route path '${route.path}' defines parameter ':${param}', but handler ${controller.className}.${route.handler} does not bind it with @Param('${param}').`, controller.file, undefined, `Add @Param('${param}') to ${route.handler} arguments.`, {
+                type: "add_route_parameter_binding",
+                targetFile: controller.file,
+                controller: controller.className,
+                route: route.handler,
+                parameter: param,
+                binding: "param"
+              });
             }
           }
         }
@@ -3700,10 +4093,20 @@ function validateGraph(graph, options = false) {
           }
         }
         if ((route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS" || route.method === "DELETE") && (route.hasBodyBinding || route.body)) {
-          error("disallowed-body-on-get-delete", `Route handler ${controller.className}.${route.handler} binds @Body() or declares body schema on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`);
+          error("disallowed-body-on-get-delete", `Route handler ${controller.className}.${route.handler} binds @Body() or declares body schema on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`, {
+            type: "remove_route_body_binding",
+            targetFile: controller.file,
+            controller: controller.className,
+            route: route.handler
+          });
         }
         if (route.hasBodyBinding && (route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS")) {
-          error("invalid-body-binding", `Route handler ${controller.className}.${route.handler} binds @Body() on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`);
+          error("invalid-body-binding", `Route handler ${controller.className}.${route.handler} binds @Body() on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`, {
+            type: "remove_route_body_binding",
+            targetFile: controller.file,
+            controller: controller.className,
+            route: route.handler
+          });
         } else if (route.hasBodyBinding && !route.body) {
           warn2("missing-body-schema", `Route handler ${controller.className}.${route.handler} binds @Body() on route '${route.path}', but route definition does not specify a body validation schema.`, controller.file, undefined, `Add schema to route options (e.g. body: Schema) for compile-time and runtime validation.`);
         } else if (route.body && !route.hasBodyBinding && !route.command) {
@@ -3844,23 +4247,51 @@ function validateGraph(graph, options = false) {
               const owner = globalProviders.get(dep);
               if (!owner)
                 continue;
-              error("module-boundary", `模块 ${module.name} 的 provider ${provider.token} 依赖 ${dep}，该 token 由模块 ${owner.module.name} 提供但未被 import`, provider.file, provider.line, `Import module '${owner.module.name}' in '${module.name}', add '${dep}' to '${owner.module.name}' exports, or mark @Injectable({ providedIn: 'root' }).`);
+              error("module-boundary", `模块 ${module.name} 的 provider ${provider.token} 依赖 ${dep}，该 token 由模块 ${owner.module.name} 提供但未被 import`, provider.file, provider.line, `Import module '${owner.module.name}' in '${module.name}', add '${dep}' to '${owner.module.name}' exports, or mark @Injectable({ providedIn: 'root' }).`, {
+                type: "add_module_import",
+                targetFile: module.file,
+                module: owner.module.name,
+                provider: dep,
+                symbol: owner.module.className,
+                targetModule: module.name,
+                importPath: (() => {
+                  const value = relative3(dirname3(module.file), owner.module.file).replace(/\.(tsx?|mts|cts)$/, "").split(sep3).join("/");
+                  return value.startsWith(".") ? value : `./${value}`;
+                })()
+              });
             } else if (dep.includes("TOKEN") || dep.endsWith("Token") || dep.length > 2 && dep === dep.toUpperCase()) {
               error("missing-token-factory", `InjectionToken '${dep}' referenced by provider '${provider.token}' has no provider in module '${module.name}' and no default factory function.`, provider.file, provider.line, `Provide '${dep}' in @Module({ providers: [...] }) or declare it with new InjectionToken('${dep}', { factory: () => ... }).`);
             } else {
-              error("unresolved-token", `模块 ${module.name} 的 provider ${provider.token} 依赖的 token ${dep} 无法解析`, provider.file, provider.line, `Provide '${dep}' in a module, mark constructor parameter @Optional(), or define @Injectable({ providedIn: 'root' }).`);
+              error("unresolved-token", `模块 ${module.name} 的 provider ${provider.token} 依赖的 token ${dep} 无法解析`, provider.file, provider.line, `Provide '${dep}' in a module, mark constructor parameter @Optional(), or define @Injectable({ providedIn: 'root' }).`, {
+                type: "add_provider",
+                targetFile: module.file,
+                token: dep,
+                module: module.name
+              });
             }
           }
           continue;
         }
         if (SCOPE_LIFETIME_RANK[resolved.provider.scope] > SCOPE_LIFETIME_RANK[provider.scope]) {
-          error("scope-violation", `模块 ${module.name} 的 ${provider.scope} provider ${provider.token} 不能依赖 ${resolved.provider.scope} provider ${dep}`, provider.file, provider.line, `Change provider '${provider.token}' scope to '${resolved.provider.scope}', or inject a factory/context instead.`);
+          error("scope-violation", `模块 ${module.name} 的 ${provider.scope} provider ${provider.token} 不能依赖 ${resolved.provider.scope} provider ${dep}`, provider.file, provider.line, `Change provider '${provider.token}' scope to '${resolved.provider.scope}', or inject a factory/context instead.`, {
+            type: "change_provider_scope",
+            targetFile: provider.file,
+            provider: provider.token,
+            from: provider.scope,
+            to: resolved.provider.scope
+          });
         }
       }
     }
     for (const command of module.commands) {
       if (!command.permission) {
-        error("command-missing-permission", `模块 ${module.name} 的 command ${command.name} (${command.className}) 未声明 permission`, module.file, module.line, "Add 'permission: string' to @Command({ ... }) or configure command execution capabilities permission=false.");
+        error("command-missing-permission", `模块 ${module.name} 的 command ${command.name} (${command.className}) 未声明 permission`, module.file, module.line, "Add 'permission: string' to @Command({ ... }) or configure command execution capabilities permission=false.", {
+          type: "add_command_permission",
+          targetFile: module.providers.find((provider) => provider.useClass === command.className || provider.token === command.className)?.file ?? module.file,
+          command: command.className,
+          module: module.name,
+          permission: `${module.name}.${command.name}`
+        });
       }
       if (typeof options === "object" && options.commandCapabilities) {
         const caps = options.commandCapabilities;
@@ -4214,8 +4645,8 @@ import { join as join4 } from "node:path";
 
 // src/type-safety.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join3, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
-import * as ts4 from "@typescript/typescript6";
+import { dirname as dirname4, join as join3, relative as relative4, resolve as resolve3, sep as sep4 } from "node:path";
+import * as ts5 from "@typescript/typescript6";
 var DEFAULT_EXCLUDES = [
   "**/*.test.ts",
   "**/*.spec.ts",
@@ -4239,7 +4670,7 @@ function scanGeneratedArtifacts(artifacts, strict = true) {
   for (const [file, content] of Object.entries(artifacts)) {
     if (content === undefined)
       continue;
-    const sourceFile = ts4.createSourceFile(file, content, ts4.ScriptTarget.Latest, true, ts4.ScriptKind.TS);
+    const sourceFile = ts5.createSourceFile(file, content, ts5.ScriptTarget.Latest, true, ts5.ScriptKind.TS);
     for (const node of descendantsOfKind2(sourceFile, isAnyKeyword)) {
       diagnostics.push(makeDiagnostic("generated-any", `生成产物 ${file} 包含 any；严格生成模式要求使用 unknown、具体接口或泛型约束。`, sourceFile, node, strict));
     }
@@ -4247,30 +4678,30 @@ function scanGeneratedArtifacts(artifacts, strict = true) {
   return diagnostics;
 }
 function scanProductionSource(options) {
-  const rootDir = resolve2(options.rootDir);
+  const rootDir = resolve3(options.rootDir);
   const configPath = join3(rootDir, "tsconfig.json");
   const projectConfig = existsSync2(configPath) ? readProjectConfig2(configPath) : {
     options: {
       strict: true,
       skipLibCheck: true,
-      target: ts4.ScriptTarget.ES2022,
-      module: ts4.ModuleKind.ESNext
+      target: ts5.ScriptTarget.ES2022,
+      module: ts5.ModuleKind.ESNext
     },
     errors: []
   };
   const include = options.include ?? ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"];
-  const rootNames = ts4.sys.readDirectory(rootDir, [".ts", ".tsx", ".mts", ".cts"], ["node_modules", "dist"], include).filter((file) => isProductionSourcePath(rootDir, file, [...DEFAULT_EXCLUDES, ...options.exclude ?? []]));
+  const rootNames = ts5.sys.readDirectory(rootDir, [".ts", ".tsx", ".mts", ".cts"], ["node_modules", "dist"], include).filter((file) => isProductionSourcePath(rootDir, file, [...DEFAULT_EXCLUDES, ...options.exclude ?? []]));
   const compilerOptions = { ...projectConfig.options, noEmit: true };
-  const host = ts4.createCompilerHost(compilerOptions);
+  const host = ts5.createCompilerHost(compilerOptions);
   host.getCurrentDirectory = () => rootDir;
-  const program = ts4.createProgram(rootNames, compilerOptions, host);
+  const program = ts5.createProgram(rootNames, compilerOptions, host);
   const outDir = options.outDir ? normalizeRelative(rootDir, options.outDir) : undefined;
   const excludes = [...DEFAULT_EXCLUDES, ...options.exclude ?? []];
   const sourceFiles = program.getSourceFiles().filter((sourceFile) => isProductionSource(rootDir, sourceFile, excludes, outDir));
   const diagnostics = [...projectConfig.errors, ...program.getOptionsDiagnostics()].map((diagnostic) => ({
     severity: "error",
     code: "source-config",
-    message: ts4.flattenDiagnosticMessageText(diagnostic.messageText, `
+    message: ts5.flattenDiagnosticMessageText(diagnostic.messageText, `
 `),
     file: diagnostic.file ? normalizeRelative(rootDir, diagnostic.file.fileName) : normalizeRelative(rootDir, configPath),
     line: diagnostic.file && diagnostic.start !== undefined ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1 : undefined,
@@ -4287,22 +4718,22 @@ function scanSourceFile(sourceFile, checker, rootDir, diagnostics, strict) {
     diagnostics.push(makeDiagnostic("source-any", "生产源码使用了显式 any；请改用 unknown、具体接口或泛型约束。", sourceFile, node, strict, rootDir));
   }
   for (const node of descendants(sourceFile)) {
-    if (ts4.isAsExpression(node)) {
-      if (ts4.isAsExpression(node.parent) || ts4.isTypeAssertionExpression(node.parent))
+    if (ts5.isAsExpression(node)) {
+      if (ts5.isAsExpression(node.parent) || ts5.isTypeAssertionExpression(node.parent))
         continue;
       const assertedType = node.type.getText(sourceFile);
       if (assertedType === "const")
         continue;
       diagnostics.push(makeDiagnostic("source-type-assertion", `生产源码包含类型断言 ${node.getText(sourceFile)}；请优先使用类型守卫、satisfies 或显式边界解析。`, sourceFile, node, strict, rootDir));
-    } else if (ts4.isTypeAssertionExpression(node)) {
-      if (ts4.isAsExpression(node.parent) || ts4.isTypeAssertionExpression(node.parent))
+    } else if (ts5.isTypeAssertionExpression(node)) {
+      if (ts5.isAsExpression(node.parent) || ts5.isTypeAssertionExpression(node.parent))
         continue;
       diagnostics.push(makeDiagnostic("source-type-assertion", `生产源码包含类型断言 ${node.getText(sourceFile)}；请优先使用类型守卫、satisfies 或显式边界解析。`, sourceFile, node, strict, rootDir));
-    } else if (ts4.isNonNullExpression(node)) {
+    } else if (ts5.isNonNullExpression(node)) {
       diagnostics.push(makeDiagnostic("source-non-null-assertion", `生产源码包含非空断言 ${node.getText(sourceFile)}；请显式处理 null/undefined。`, sourceFile, node, strict, rootDir));
     }
   }
-  for (const declaration of descendantsOfKind2(sourceFile, ts4.isVariableDeclaration)) {
+  for (const declaration of descendantsOfKind2(sourceFile, ts5.isVariableDeclaration)) {
     const initializer = declaration.initializer;
     if (!initializer || declaration.type)
       continue;
@@ -4318,11 +4749,11 @@ function scanSourceFile(sourceFile, checker, rootDir, diagnostics, strict) {
     if (isLetDeclaration(declaration) && isLiteralSyntax(initializer) && !isLiteralType(declarationType)) {
       diagnostics.push(makeDiagnostic("source-implicit-widening", `变量 ${declaration.name.getText(sourceFile)} 的字面量类型从 ${checker.typeToString(initializerType, initializer)} 隐式宽化为 ${checker.typeToString(declarationType, declaration)}；请补充类型或使用 const。`, sourceFile, declaration, strict, rootDir));
     }
-    if (ts4.isObjectLiteralExpression(initializer) && isConstDeclaration(declaration) && initializer.getText(sourceFile).length > 0 && initializer.properties.some((property) => ts4.isPropertyAssignment(property) && property.initializer !== undefined && !ts4.isAsExpression(property.initializer) && isLiteralExpression(property.initializer))) {
+    if (ts5.isObjectLiteralExpression(initializer) && isConstDeclaration(declaration) && initializer.getText(sourceFile).length > 0 && initializer.properties.some((property2) => ts5.isPropertyAssignment(property2) && property2.initializer !== undefined && !ts5.isAsExpression(property2.initializer) && isLiteralExpression(property2.initializer))) {
       diagnostics.push(makeDiagnostic("source-implicit-widening", `常量对象 ${declaration.name.getText(sourceFile)} 的字面量属性会隐式宽化；请补充对象类型或使用 as const。`, sourceFile, declaration, strict, rootDir));
     }
   }
-  for (const parameter of descendantsOfKind2(sourceFile, ts4.isParameter)) {
+  for (const parameter of descendantsOfKind2(sourceFile, ts5.isParameter)) {
     if (parameter.type)
       continue;
     for (const name of bindingNames(parameter.name)) {
@@ -4333,10 +4764,10 @@ function scanSourceFile(sourceFile, checker, rootDir, diagnostics, strict) {
   }
 }
 function readProjectConfig2(configPath) {
-  const config = ts4.readConfigFile(configPath, (file) => readFileSync2(file, "utf8"));
+  const config = ts5.readConfigFile(configPath, (file) => readFileSync2(file, "utf8"));
   if (config.error)
     return { options: {}, errors: [config.error] };
-  const parsed = ts4.parseJsonConfigFileContent(config.config, ts4.sys, dirname2(configPath));
+  const parsed = ts5.parseJsonConfigFileContent(config.config, ts5.sys, dirname4(configPath));
   return { options: parsed.options, errors: parsed.errors };
 }
 function isProductionSource(rootDir, sourceFile, excludes, outDir) {
@@ -4356,42 +4787,42 @@ function globMatches(value, pattern) {
   return new RegExp(`^${escaped}$`).test(value);
 }
 function bindingNames(name) {
-  if (ts4.isIdentifier(name))
+  if (ts5.isIdentifier(name))
     return [name];
-  return name.elements.flatMap((element) => ts4.isBindingElement(element) ? bindingNames(element.name) : []);
+  return name.elements.flatMap((element) => ts5.isBindingElement(element) ? bindingNames(element.name) : []);
 }
 function isLiteralExpression(node) {
   if (!node)
     return false;
   return [
-    ts4.SyntaxKind.StringLiteral,
-    ts4.SyntaxKind.NumericLiteral,
-    ts4.SyntaxKind.TrueKeyword,
-    ts4.SyntaxKind.FalseKeyword
+    ts5.SyntaxKind.StringLiteral,
+    ts5.SyntaxKind.NumericLiteral,
+    ts5.SyntaxKind.TrueKeyword,
+    ts5.SyntaxKind.FalseKeyword
   ].includes(node.kind);
 }
 function isLiteralSyntax(node) {
-  return ts4.isStringLiteral(node) || ts4.isNumericLiteral(node) || node.kind === ts4.SyntaxKind.TrueKeyword || node.kind === ts4.SyntaxKind.FalseKeyword;
+  return ts5.isStringLiteral(node) || ts5.isNumericLiteral(node) || node.kind === ts5.SyntaxKind.TrueKeyword || node.kind === ts5.SyntaxKind.FalseKeyword;
 }
 function isLiteralType(type) {
-  return (type.flags & (ts4.TypeFlags.StringLiteral | ts4.TypeFlags.NumberLiteral | ts4.TypeFlags.BooleanLiteral | ts4.TypeFlags.BigIntLiteral)) !== 0;
+  return (type.flags & (ts5.TypeFlags.StringLiteral | ts5.TypeFlags.NumberLiteral | ts5.TypeFlags.BooleanLiteral | ts5.TypeFlags.BigIntLiteral)) !== 0;
 }
 function isAnyType(type) {
-  return (type.flags & ts4.TypeFlags.Any) !== 0;
+  return (type.flags & ts5.TypeFlags.Any) !== 0;
 }
 function isLetDeclaration(declaration) {
-  return ts4.isVariableDeclarationList(declaration.parent) && (declaration.parent.flags & ts4.NodeFlags.Let) !== 0;
+  return ts5.isVariableDeclarationList(declaration.parent) && (declaration.parent.flags & ts5.NodeFlags.Let) !== 0;
 }
 function isConstDeclaration(declaration) {
-  return ts4.isVariableDeclarationList(declaration.parent) && (declaration.parent.flags & ts4.NodeFlags.Const) !== 0;
+  return ts5.isVariableDeclarationList(declaration.parent) && (declaration.parent.flags & ts5.NodeFlags.Const) !== 0;
 }
 function descendants(root) {
   const result = [];
   const visit = (node) => {
     result.push(node);
-    ts4.forEachChild(node, visit);
+    ts5.forEachChild(node, visit);
   };
-  ts4.forEachChild(root, visit);
+  ts5.forEachChild(root, visit);
   return result;
 }
 function descendantsOfKind2(root, predicate) {
@@ -4399,9 +4830,9 @@ function descendantsOfKind2(root, predicate) {
   const visit = (node) => {
     if (predicate(node))
       result.push(node);
-    ts4.forEachChild(node, visit);
+    ts5.forEachChild(node, visit);
   };
-  ts4.forEachChild(root, visit);
+  ts5.forEachChild(root, visit);
   return result;
 }
 function makeDiagnostic(code, message, fileOrSourceFile, node, strict, rootDir) {
@@ -4419,10 +4850,10 @@ function makeDiagnostic(code, message, fileOrSourceFile, node, strict, rootDir)
   };
 }
 function normalizeRelative(rootDir, filePath) {
-  return relative2(rootDir, filePath).split(sep2).join("/").replace(/^\.\//, "");
+  return relative4(rootDir, filePath).split(sep4).join("/").replace(/^\.\//, "");
 }
 function isAnyKeyword(node) {
-  return node.kind === ts4.SyntaxKind.AnyKeyword;
+  return node.kind === ts5.SyntaxKind.AnyKeyword;
 }
 
 // src/compile.ts
@@ -4571,12 +5002,12 @@ function resolveTypeSafety(options) {
 }
 // src/watch.ts
 import { watch } from "node:fs";
-import { relative as relative4, resolve as resolve4 } from "node:path";
+import { relative as relative6, resolve as resolve5 } from "node:path";
 
 // src/incremental.ts
 import { createHash as createHash5 } from "node:crypto";
-import { access as access2, readdir, readFile } from "node:fs/promises";
-import { isAbsolute, relative as relative3, resolve as resolve3, sep as sep3 } from "node:path";
+import { access as access2, readdir, readFile as readFile2 } from "node:fs/promises";
+import { isAbsolute as isAbsolute2, relative as relative5, resolve as resolve4, sep as sep5 } from "node:path";
 function createDependencyGraphCache() {
   return {
     modules: new Map,
@@ -4650,20 +5081,20 @@ function createIncrementalCompiler() {
   };
 }
 async function updateSnapshot(previous, options, changedPaths) {
-  const rootDir = resolve3(options.rootDir);
-  const outDir = resolve3(options.outDir);
+  const rootDir = resolve4(options.rootDir);
+  const outDir = resolve4(options.outDir);
   const files = { ...previous.files };
   for (const changedPath of changedPaths) {
-    const absolutePath = isAbsolute(changedPath) ? resolve3(changedPath) : resolve3(rootDir, changedPath);
-    const relativeChangedPath = relative3(rootDir, absolutePath);
-    if (relativeChangedPath === ".." || relativeChangedPath.startsWith(`..${sep3}`))
+    const absolutePath = isAbsolute2(changedPath) ? resolve4(changedPath) : resolve4(rootDir, changedPath);
+    const relativeChangedPath = relative5(rootDir, absolutePath);
+    if (relativeChangedPath === ".." || relativeChangedPath.startsWith(`..${sep5}`))
       continue;
     if (absolutePath === outDir || absolutePath.startsWith(`${outDir}/`))
       continue;
-    const relativePath = relative3(rootDir, absolutePath).split(sep3).join("/");
+    const relativePath = relative5(rootDir, absolutePath).split(sep5).join("/");
     try {
       await access2(absolutePath);
-      const content = await readFile(absolutePath);
+      const content = await readFile2(absolutePath);
       files[relativePath] = createHash5("sha256").update(content).digest("hex");
     } catch {
       delete files[relativePath];
@@ -4672,20 +5103,20 @@ async function updateSnapshot(previous, options, changedPaths) {
   return { files, optionsKey: optionsKeyOf(options) };
 }
 async function createSnapshot(options) {
-  const rootDir = resolve3(options.rootDir);
-  const outDir = resolve3(options.outDir);
+  const rootDir = resolve4(options.rootDir);
+  const outDir = resolve4(options.outDir);
   const paths = await listSourceFiles(rootDir, outDir);
   const files = {};
   for (const path of paths) {
-    const content = await readFile(path);
-    files[relative3(rootDir, path).split(sep3).join("/")] = createHash5("sha256").update(content).digest("hex");
+    const content = await readFile2(path);
+    files[relative5(rootDir, path).split(sep5).join("/")] = createHash5("sha256").update(content).digest("hex");
   }
   return { files, optionsKey: optionsKeyOf(options) };
 }
 function optionsKeyOf(options) {
   return JSON.stringify({
-    rootDir: resolve3(options.rootDir),
-    outDir: resolve3(options.outDir),
+    rootDir: resolve4(options.rootDir),
+    outDir: resolve4(options.outDir),
     include: options.include,
     strict: options.strict,
     writeOnError: options.writeOnError,
@@ -4705,7 +5136,7 @@ async function listSourceFiles(rootDir, outDir) {
   const result = [];
   const visit = async (directory) => {
     for (const entry of await readdir(directory, { withFileTypes: true })) {
-      const path = resolve3(directory, entry.name);
+      const path = resolve4(directory, entry.name);
       if (entry.isDirectory()) {
         if (entry.name === "node_modules" || entry.name === ".git" || path === outDir)
           continue;
@@ -4829,8 +5260,8 @@ function findAffectedModules(previous, current, changedFiles) {
 // src/watch.ts
 var DEFAULT_DEBOUNCE_MS = 100;
 function watchProject(options) {
-  const rootDir = resolve4(options.rootDir);
-  const outDir = resolve4(options.outDir);
+  const rootDir = resolve5(options.rootDir);
+  const outDir = resolve5(options.outDir);
   const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
   let timer;
   let closed = false;
@@ -4914,12 +5345,12 @@ function watchProject(options) {
     watcher = watch(rootDir, { recursive: true }, (_eventType, filename) => {
       if (!filename)
         return schedule();
-      const changedPath = resolve4(rootDir, filename.toString());
-      const relativePath = relative4(outDir, changedPath);
+      const changedPath = resolve5(rootDir, filename.toString());
+      const relativePath = relative6(outDir, changedPath);
       if (!relativePath.startsWith("..") && relativePath !== "")
         return;
       if (/\.(tsx?|mts|cts)$/.test(changedPath))
-        schedule(relative4(rootDir, changedPath));
+        schedule(relative6(rootDir, changedPath));
     });
     if (initialEvent)
       resolveReady(initialEvent);
@@ -4978,6 +5409,61 @@ function explainGraph(graph, subject) {
   const known = [...graph.modules.map((item) => item.name), ...graph.externalTokens].sort();
   throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
 }
+function createContextPack(graph, subject) {
+  const subjectModule = graph.modules.find((module) => module.name === subject);
+  if (!subjectModule) {
+    throw new Error(`No module named "${subject}". Context packs require a module name.`);
+  }
+  const byName = new Map(graph.modules.map((module) => [module.name, module]));
+  const selected = new Set([subjectModule.name]);
+  const queue = [subjectModule.name];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current)
+      continue;
+    const module = byName.get(current);
+    if (!module)
+      continue;
+    const neighbors = [
+      ...module.imports,
+      ...graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name)
+    ];
+    for (const neighbor of neighbors) {
+      if (!selected.has(neighbor) && byName.has(neighbor)) {
+        selected.add(neighbor);
+        queue.push(neighbor);
+      }
+    }
+  }
+  const modules = graph.modules.filter((module) => selected.has(module.name));
+  const files = [...new Set(modules.flatMap((module) => [
+    module.file,
+    ...module.providers.map((provider) => provider.file),
+    ...module.controllers.map((controller) => controller.file)
+  ]))].sort();
+  const referencedTokens = new Set;
+  for (const module of modules) {
+    for (const provider of module.providers) {
+      for (const token of provider.deps)
+        referencedTokens.add(token);
+    }
+    for (const controller of module.controllers) {
+      for (const token of controller.deps)
+        referencedTokens.add(token);
+    }
+  }
+  return {
+    version: 1,
+    subject: subjectModule.name,
+    modules,
+    files,
+    externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
+    relatedModules: {
+      imports: subjectModule.imports.filter((name) => selected.has(name)),
+      importedBy: graph.modules.filter((module) => module.imports.includes(subjectModule.name)).map((module) => module.name).sort()
+    }
+  };
+}
 function doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
   const checks = [
     {
@@ -5077,7 +5563,7 @@ function exportGraphDot(graph) {
 }
 // src/config.ts
 import { existsSync as existsSync5 } from "node:fs";
-import { join as join6, resolve as resolve5 } from "node:path";
+import { join as join6, resolve as resolve6 } from "node:path";
 import { pathToFileURL } from "node:url";
 var DEFAULT_SUPACLOUD_CONFIG = {
   root: "src",
@@ -5099,8 +5585,8 @@ function defineSupacloudConfig(config = {}) {
 function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
   const resolved = defineSupacloudConfig(config);
   return {
-    rootDir: resolve5(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
-    outDir: resolve5(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
+    rootDir: resolve6(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
+    outDir: resolve6(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
     include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
     strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
     generateClient: resolved.generateClient ?? DEFAULT_SUPACLOUD_CONFIG.generateClient,
@@ -5147,11 +5633,13 @@ export {
   ModuleDependencyGraph,
   TraitCompiler,
   analyzeProject,
+  applyDiagnosticFix,
   camelName,
   checkProject,
   compileOptionsFromConfig,
   compileProject,
   compileTraits,
+  createContextPack,
   createDependencyGraphCache,
   createIncrementalCompiler,
   createIncrementalProgramSession,
@@ -5162,6 +5650,7 @@ export {
   exportGraphMermaid,
   formatGraph,
   generateApplication,
+  generateFeatureSource,
   getModuleBoundaryPreset,
   getModuleBoundaryProfile,
   loadSupacloudConfig,
@@ -5170,6 +5659,7 @@ export {
   resolveSupacloudConfig,
   scanGeneratedArtifacts,
   scanProductionSource,
+  validateFeatureSpec,
   validateGraph,
   watchProject
 };