create-forgeon 0.2.9 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ Project name stays text input; fixed-choice prompts use arrow-key selection (`Up
 npx create-forgeon@latest add --list
 npx create-forgeon@latest add i18n --project ./my-app
 npx create-forgeon@latest add jwt-auth --project ./my-app
+npx create-forgeon@latest add files --with-required --provider db-adapter=db-prisma
 ```
 
 ```bash
@@ -38,3 +39,6 @@ pnpm forgeon:sync-integrations
 - `add jwt-auth` is implemented and auto-detects DB adapter support for refresh-token persistence.
 - Integration sync is bundled by default and runs after `add` commands (best-effort).
 - Module notes are written under `modules/<module-id>/README.md`.
+- Hard prerequisites are explicit:
+  - TTY mode prompts for provider resolution and install plan confirmation
+  - non-TTY mode can use `--with-required` plus `--provider <capability>=<module>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Forgeon project generator CLI",
   "license": "MIT",
   "author": "Forgeon",

package/src/cli/add-help.mjs

@@ -6,11 +6,15 @@ Usage:
 
 Options:
   --project <path>   Target project path (default: current directory)
+  --with-required    Allow recursive installation of hard prerequisites
+  --provider <capability>=<module>
+                     Explicit provider mapping for non-interactive dependency resolution
   --list             List available modules
   -h, --help         Show this help
 
 Note:
-  Pair integrations are explicit.
+  Hard prerequisites are resolved explicitly.
+  Pair integrations remain explicit follow-up actions.
   Run "pnpm forgeon:sync-integrations" in the target project after add-module steps.
 `);
 }

package/src/cli/add-options.mjs

@@ -1,12 +1,14 @@
-export function parseAddCliArgs(argv) {
-  const args = [...argv];
-  const options = {
-    moduleId: undefined,
-    project: '.',
-    list: false,
-    help: false,
-  };
-  const positional = [];
+export function parseAddCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    moduleId: undefined,
+    project: '.',
+    list: false,
+    help: false,
+    withRequired: false,
+    providers: {},
+  };
+  const positional = [];
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -17,13 +19,47 @@ export function parseAddCliArgs(argv) {
       continue;
     }
 
-    if (arg === '--list') {
-      options.list = true;
-      continue;
-    }
-
-    if (arg.startsWith('--project=')) {
-      options.project = arg.split('=')[1] || '.';
+    if (arg === '--list') {
+      options.list = true;
+      continue;
+    }
+
+    if (arg === '--with-required') {
+      options.withRequired = true;
+      continue;
+    }
+
+    if (arg.startsWith('--provider=')) {
+      const raw = arg.slice('--provider='.length);
+      const separatorIndex = raw.indexOf('=');
+      if (separatorIndex > 0) {
+        const capabilityId = raw.slice(0, separatorIndex).trim();
+        const moduleId = raw.slice(separatorIndex + 1).trim();
+        if (capabilityId && moduleId) {
+          options.providers[capabilityId] = moduleId;
+        }
+      }
+      continue;
+    }
+
+    if (arg === '--provider') {
+      const nextValue = args[i + 1];
+      if (nextValue && !nextValue.startsWith('-')) {
+        const separatorIndex = nextValue.indexOf('=');
+        if (separatorIndex > 0) {
+          const capabilityId = nextValue.slice(0, separatorIndex).trim();
+          const moduleId = nextValue.slice(separatorIndex + 1).trim();
+          if (capabilityId && moduleId) {
+            options.providers[capabilityId] = moduleId;
+          }
+        }
+        i += 1;
+      }
+      continue;
+    }
+
+    if (arg.startsWith('--project=')) {
+      options.project = arg.split('=')[1] || '.';
       continue;
     }
 

package/src/cli/add-options.test.mjs

@@ -16,9 +16,25 @@ describe('parseAddCliArgs', () => {
     assert.equal(options.help, true);
   });
 
-  it('uses second positional as project when project flag is absent', () => {
-    const options = parseAddCliArgs(['queue', './my-app']);
-    assert.equal(options.moduleId, 'queue');
-    assert.equal(options.project, './my-app');
-  });
-});
+  it('uses second positional as project when project flag is absent', () => {
+    const options = parseAddCliArgs(['queue', './my-app']);
+    assert.equal(options.moduleId, 'queue');
+    assert.equal(options.project, './my-app');
+  });
+
+  it('parses dependency resolution flags', () => {
+    const options = parseAddCliArgs([
+      'files',
+      '--with-required',
+      '--provider',
+      'db-adapter=db-prisma',
+      '--provider=queue-adapter=queue',
+    ]);
+    assert.equal(options.moduleId, 'files');
+    assert.equal(options.withRequired, true);
+    assert.deepEqual(options.providers, {
+      'db-adapter': 'db-prisma',
+      'queue-adapter': 'queue',
+    });
+  });
+});

package/src/integrations/flow.mjs

@@ -116,3 +116,28 @@ export function printModuleAdded(moduleId, docsPath) {
   console.log(colorize('green', `✔ Module added: ${moduleId}`));
   console.log(`- readme: ${docsPath}`);
 }
+
+export function printOptionalIntegrationsWarning(integrations) {
+  if (!Array.isArray(integrations) || integrations.length === 0) {
+    return;
+  }
+
+  for (const integration of integrations) {
+    console.log(`\n${colorize('yellow', 'Warning: optional integration available')}`);
+    console.log(`- ${integration.title}`);
+    console.log('Modules:');
+    for (const moduleId of integration.modules ?? []) {
+      console.log(`- ${colorize('cyan', moduleId)}`);
+    }
+    console.log('This enables:');
+    for (const line of integration.description ?? []) {
+      console.log(`- ${line}`);
+    }
+    if (Array.isArray(integration.followUpCommands) && integration.followUpCommands.length > 0) {
+      console.log('Apply later:');
+      for (const command of integration.followUpCommands) {
+        console.log(`- ${command}`);
+      }
+    }
+  }
+}

package/src/modules/dependencies.mjs

@@ -0,0 +1,268 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { promptSelect } from '../cli/prompt-select.mjs';
+import { getCapabilityProviders, listModulePresets } from './registry.mjs';
+
+function getPresetMap(presets) {
+  return new Map(presets.map((preset) => [preset.id, preset]));
+}
+
+function getDetectionPaths(preset) {
+  if (Array.isArray(preset.detectionPaths) && preset.detectionPaths.length > 0) {
+    return preset.detectionPaths;
+  }
+  return [path.join('packages', preset.id, 'package.json')];
+}
+
+export function detectInstalledModules(targetRoot, presets = listModulePresets()) {
+  const installed = new Set();
+  const absoluteRoot = path.resolve(targetRoot);
+
+  for (const preset of presets) {
+    const detectionPaths = getDetectionPaths(preset);
+    if (
+      detectionPaths.some((relativePath) => fs.existsSync(path.join(absoluteRoot, relativePath)))
+    ) {
+      installed.add(preset.id);
+    }
+  }
+
+  return installed;
+}
+
+export function collectProvidedCapabilities(moduleIds, presets = listModulePresets()) {
+  const presetMap = getPresetMap(presets);
+  const capabilities = new Set();
+
+  for (const moduleId of moduleIds) {
+    const preset = presetMap.get(moduleId);
+    if (!preset || !Array.isArray(preset.provides)) {
+      continue;
+    }
+    for (const capabilityId of preset.provides) {
+      capabilities.add(capabilityId);
+    }
+  }
+
+  return capabilities;
+}
+
+function describeMissingRequirement(requirement) {
+  if (requirement.type === 'capability') {
+    return `required capability "${requirement.id}" is missing`;
+  }
+  return `required module "${requirement.id}" is missing`;
+}
+
+function getNonInteractiveHint(requirement, providers, selectedProviderId) {
+  if (requirement.type === 'capability') {
+    if (providers.length === 0) {
+      return 'No implemented providers are currently available for this capability.';
+    }
+    const providerLines = providers.map((provider) => `- npx create-forgeon@latest add ${provider.id}`);
+    const withRequiredExample = selectedProviderId
+      ? [
+          '',
+          'Or re-run with:',
+          `- npx create-forgeon@latest add <module-id> --with-required --provider ${requirement.id}=${selectedProviderId}`,
+        ]
+      : [];
+    return [
+      'Install one of the supported providers first:',
+      ...providerLines,
+      ...withRequiredExample,
+    ].join('\n');
+  }
+
+  return `Install it first:\n- npx create-forgeon@latest add ${requirement.id}`;
+}
+
+function createResolutionError(moduleId, requirement, providers = [], selectedProviderId = null) {
+  const hint = getNonInteractiveHint(requirement, providers, selectedProviderId);
+  return new Error(`Cannot install "${moduleId}": ${describeMissingRequirement(requirement)}.\n\n${hint}`);
+}
+
+async function selectProviderForCapability({
+  moduleId,
+  capabilityId,
+  providers,
+  promptSelectImpl,
+}) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      `Interactive provider selection requires a TTY for capability "${capabilityId}" while installing "${moduleId}".`,
+    );
+  }
+
+  const choices = providers.map((provider, index) => ({
+    label: index === 0 ? `${provider.id} (Recommended)` : provider.id,
+    value: provider.id,
+  }));
+  choices.push({ label: 'Cancel', value: '__cancel' });
+
+  const picked = await promptSelectImpl({
+    message: `Module "${moduleId}" requires capability: ${capabilityId}`,
+    defaultValue: '__cancel',
+    choices,
+  });
+
+  if (picked === '__cancel') {
+    return null;
+  }
+
+  return picked;
+}
+
+export async function resolveModuleInstallPlan({
+  moduleId,
+  targetRoot,
+  presets = listModulePresets(),
+  withRequired = false,
+  providerSelections = {},
+  promptSelectImpl = promptSelect,
+  isInteractive = process.stdin.isTTY && process.stdout.isTTY,
+}) {
+  const presetMap = getPresetMap(presets);
+  if (!presetMap.has(moduleId)) {
+    throw new Error(`Unknown module "${moduleId}".`);
+  }
+
+  const installed = detectInstalledModules(targetRoot, presets);
+  const planned = [];
+  const plannedSet = new Set();
+  const providedCapabilities = collectProvidedCapabilities(installed, presets);
+  const selectedProviders = new Map();
+
+  async function ensureModule(moduleIdToEnsure, isRoot = false) {
+    const preset = presetMap.get(moduleIdToEnsure);
+    if (!preset) {
+      throw new Error(`Unknown module "${moduleIdToEnsure}".`);
+    }
+
+    const requirements = Array.isArray(preset.requires) ? preset.requires : [];
+    for (const requirement of requirements) {
+      if (requirement.type === 'module') {
+        if (installed.has(requirement.id) || plannedSet.has(requirement.id)) {
+          continue;
+        }
+        if (!isInteractive && !withRequired) {
+          throw createResolutionError(moduleId, requirement);
+        }
+        await ensureModule(requirement.id);
+        continue;
+      }
+
+      if (requirement.type !== 'capability') {
+        continue;
+      }
+
+      if (providedCapabilities.has(requirement.id)) {
+        continue;
+      }
+
+      const providers = getCapabilityProviders(requirement.id, { implementedOnly: true });
+      if (providers.length === 0) {
+        throw createResolutionError(moduleId, requirement, providers);
+      }
+
+      let providerId = null;
+      if (selectedProviders.has(requirement.id)) {
+        providerId = selectedProviders.get(requirement.id);
+      } else if (isInteractive) {
+        providerId = await selectProviderForCapability({
+          moduleId,
+          capabilityId: requirement.id,
+          providers,
+          promptSelectImpl,
+        });
+        if (!providerId) {
+          return { cancelled: true };
+        }
+      } else {
+        if (!withRequired) {
+          throw createResolutionError(moduleId, requirement, providers);
+        }
+
+        if (providers.length === 1) {
+          providerId = providers[0].id;
+        } else {
+          const explicitProvider = providerSelections[requirement.id];
+          if (!explicitProvider) {
+            throw createResolutionError(moduleId, requirement, providers);
+          }
+          const matchedProvider = providers.find((provider) => provider.id === explicitProvider);
+          if (!matchedProvider) {
+            throw createResolutionError(moduleId, requirement, providers, explicitProvider);
+          }
+          providerId = matchedProvider.id;
+        }
+      }
+
+      selectedProviders.set(requirement.id, providerId);
+      const providerResult = await ensureModule(providerId);
+      if (providerResult?.cancelled) {
+        return providerResult;
+      }
+    }
+
+    if (!isRoot && !installed.has(moduleIdToEnsure) && !plannedSet.has(moduleIdToEnsure)) {
+      planned.push(moduleIdToEnsure);
+      plannedSet.add(moduleIdToEnsure);
+      const provided = Array.isArray(preset.provides) ? preset.provides : [];
+      for (const capabilityId of provided) {
+        providedCapabilities.add(capabilityId);
+      }
+    }
+
+    if (isRoot && !plannedSet.has(moduleIdToEnsure)) {
+      planned.push(moduleIdToEnsure);
+      plannedSet.add(moduleIdToEnsure);
+    }
+    return { cancelled: false };
+  }
+
+  const result = await ensureModule(moduleId, true);
+  return {
+    cancelled: result?.cancelled === true,
+    moduleSequence: planned,
+    selectedProviders: Object.fromEntries(selectedProviders),
+  };
+}
+
+function requirementIsMissing(requirement, installedModules, providedCapabilities) {
+  if (requirement.type === 'capability') {
+    return !providedCapabilities.has(requirement.id);
+  }
+  return !installedModules.has(requirement.id);
+}
+
+export function getPendingOptionalIntegrations({
+  moduleId,
+  targetRoot,
+  presets = listModulePresets(),
+}) {
+  const presetMap = getPresetMap(presets);
+  const preset = presetMap.get(moduleId);
+  if (!preset || !Array.isArray(preset.optionalIntegrations)) {
+    return [];
+  }
+
+  const installedModules = detectInstalledModules(targetRoot, presets);
+  const providedCapabilities = collectProvidedCapabilities(installedModules, presets);
+
+  return preset.optionalIntegrations
+    .map((integration) => {
+      const requirements = Array.isArray(integration.requires) ? integration.requires : [];
+      const missing = requirements.filter((requirement) =>
+        requirementIsMissing(requirement, installedModules, providedCapabilities),
+      );
+      if (missing.length === 0) {
+        return null;
+      }
+      return {
+        ...integration,
+        missing,
+      };
+    })
+    .filter(Boolean);
+}

package/src/modules/dependencies.test.mjs

@@ -0,0 +1,158 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  collectProvidedCapabilities,
+  detectInstalledModules,
+  getPendingOptionalIntegrations,
+  resolveModuleInstallPlan,
+} from './dependencies.mjs';
+
+function mkTmp(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+const TEST_PRESETS = [
+  {
+    id: 'db-prisma',
+    label: 'DB Prisma',
+    implemented: true,
+    detectionPaths: ['packages/db-prisma/package.json'],
+    provides: ['db-adapter'],
+    requires: [],
+    optionalIntegrations: [],
+  },
+  {
+    id: 'files',
+    label: 'Files',
+    implemented: false,
+    detectionPaths: ['packages/files/package.json'],
+    provides: ['files-runtime'],
+    requires: [{ type: 'capability', id: 'db-adapter' }],
+    optionalIntegrations: [],
+  },
+  {
+    id: 'jwt-auth',
+    label: 'JWT Auth',
+    implemented: true,
+    detectionPaths: ['packages/auth-api/package.json'],
+    provides: ['auth-runtime'],
+    requires: [],
+    optionalIntegrations: [
+      {
+        id: 'auth-persistence',
+        title: 'Auth Persistence Integration',
+        modules: ['jwt-auth', 'db-prisma'],
+        requires: [{ type: 'module', id: 'db-prisma' }],
+        description: ['Persist refresh-token state'],
+        followUpCommands: [
+          'npx create-forgeon@latest add db-prisma',
+          'pnpm forgeon:sync-integrations',
+        ],
+      },
+    ],
+  },
+];
+
+describe('module dependency helpers', () => {
+  it('detects installed modules from detection paths', () => {
+    const targetRoot = mkTmp('forgeon-deps-detect-');
+    try {
+      fs.mkdirSync(path.join(targetRoot, 'packages', 'db-prisma'), { recursive: true });
+      fs.writeFileSync(path.join(targetRoot, 'packages', 'db-prisma', 'package.json'), '{}\n', 'utf8');
+
+      const installed = detectInstalledModules(targetRoot, TEST_PRESETS);
+      assert.equal(installed.has('db-prisma'), true);
+      assert.equal(installed.has('files'), false);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('collects provided capabilities from installed module ids', () => {
+    const capabilities = collectProvidedCapabilities(new Set(['db-prisma']), TEST_PRESETS);
+    assert.deepEqual([...capabilities], ['db-adapter']);
+  });
+
+  it('fails in non-interactive mode without --with-required when a capability is missing', async () => {
+    const targetRoot = mkTmp('forgeon-deps-fail-');
+
+    try {
+      await assert.rejects(
+        () =>
+          resolveModuleInstallPlan({
+            moduleId: 'files',
+            targetRoot,
+            presets: TEST_PRESETS,
+            withRequired: false,
+            isInteractive: false,
+          }),
+        /required capability "db-adapter" is missing/,
+      );
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('builds a concrete install plan in non-interactive mode with --with-required', async () => {
+    const targetRoot = mkTmp('forgeon-deps-plan-');
+
+    try {
+      const result = await resolveModuleInstallPlan({
+        moduleId: 'files',
+        targetRoot,
+        presets: TEST_PRESETS,
+        withRequired: true,
+        isInteractive: false,
+      });
+
+      assert.equal(result.cancelled, false);
+      assert.deepEqual(result.moduleSequence, ['db-prisma', 'files']);
+      assert.deepEqual(result.selectedProviders, { 'db-adapter': 'db-prisma' });
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('reports missing optional integrations for the installed module', () => {
+    const targetRoot = mkTmp('forgeon-deps-optional-');
+    try {
+      fs.mkdirSync(path.join(targetRoot, 'packages', 'auth-api'), { recursive: true });
+      fs.writeFileSync(path.join(targetRoot, 'packages', 'auth-api', 'package.json'), '{}\n', 'utf8');
+
+      const pending = getPendingOptionalIntegrations({
+        moduleId: 'jwt-auth',
+        targetRoot,
+        presets: TEST_PRESETS,
+      });
+
+      assert.equal(pending.length, 1);
+      assert.equal(pending[0].id, 'auth-persistence');
+      assert.equal(pending[0].missing[0].id, 'db-prisma');
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps the requested module in the plan even when it is already installed', async () => {
+    const targetRoot = mkTmp('forgeon-deps-reapply-');
+
+    try {
+      fs.mkdirSync(path.join(targetRoot, 'packages', 'db-prisma'), { recursive: true });
+      fs.writeFileSync(path.join(targetRoot, 'packages', 'db-prisma', 'package.json'), '{}\n', 'utf8');
+
+      const result = await resolveModuleInstallPlan({
+        moduleId: 'db-prisma',
+        targetRoot,
+        presets: TEST_PRESETS,
+        isInteractive: false,
+      });
+
+      assert.deepEqual(result.moduleSequence, ['db-prisma']);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+});

package/src/modules/registry.mjs

@@ -5,6 +5,10 @@ const MODULE_PRESETS = {
     category: 'database-layer',
     implemented: true,
     description: 'Prisma/Postgres module wiring with env config, scripts, and DB probe endpoint.',
+    detectionPaths: ['packages/db-prisma/package.json'],
+    provides: ['db-adapter'],
+    requires: [],
+    optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
   i18n: {
@@ -13,6 +17,10 @@ const MODULE_PRESETS = {
     category: 'localization',
     implemented: true,
     description: 'Backend/frontend i18n wiring with locale contracts and translation resources.',
+    detectionPaths: ['packages/i18n/package.json'],
+    provides: ['i18n-runtime'],
+    requires: [],
+    optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
   logger: {
@@ -21,6 +29,10 @@ const MODULE_PRESETS = {
     category: 'observability',
     implemented: true,
     description: 'Structured API logger with request id middleware and HTTP logging interceptor.',
+    detectionPaths: ['packages/logger/package.json'],
+    provides: ['logger-runtime'],
+    requires: [],
+    optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
   swagger: {
@@ -29,6 +41,10 @@ const MODULE_PRESETS = {
     category: 'api-documentation',
     implemented: true,
     description: 'OpenAPI docs setup with env-based toggle and route path.',
+    detectionPaths: ['packages/swagger/package.json'],
+    provides: ['openapi-runtime'],
+    requires: [],
+    optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
   'jwt-auth': {
@@ -37,6 +53,39 @@ const MODULE_PRESETS = {
     category: 'auth-security',
     implemented: true,
     description: 'JWT auth preset with contracts/api module split, guard+strategy, and DB-aware refresh token storage wiring.',
+    detectionPaths: ['packages/auth-api/package.json'],
+    provides: ['auth-runtime'],
+    requires: [],
+    optionalIntegrations: [
+      {
+        id: 'auth-persistence',
+        title: 'Auth Persistence Integration',
+        modules: ['jwt-auth', 'db-prisma'],
+        requires: [{ type: 'module', id: 'db-prisma' }],
+        description: [
+          'Persist refresh-token state through the current DB integration',
+          'Enable stronger refresh-token invalidation flows after logout and rotation',
+        ],
+        followUpCommands: [
+          'npx create-forgeon@latest add db-prisma',
+          'pnpm forgeon:sync-integrations',
+        ],
+      },
+      {
+        id: 'auth-rbac-claims',
+        title: 'Auth Claims Integration',
+        modules: ['jwt-auth', 'rbac'],
+        requires: [{ type: 'module', id: 'rbac' }],
+        description: [
+          'Expose demo RBAC permissions inside JWT payloads',
+          'Return permissions through refresh and /me responses',
+        ],
+        followUpCommands: [
+          'npx create-forgeon@latest add rbac',
+          'pnpm forgeon:sync-integrations',
+        ],
+      },
+    ],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
   'rate-limit': {
@@ -45,6 +94,10 @@ const MODULE_PRESETS = {
     category: 'auth-security',
     implemented: true,
     description: 'Request throttling preset with env-based limits, proxy-aware trust, and a runtime probe endpoint.',
+    detectionPaths: ['packages/rate-limit/package.json'],
+    provides: ['rate-limit-runtime'],
+    requires: [],
+    optionalIntegrations: [],
     docFragments: [
       '00_title',
       '10_overview',
@@ -63,6 +116,25 @@ const MODULE_PRESETS = {
     category: 'auth-security',
     implemented: true,
     description: 'Role and permission decorators with a Nest guard and a protected probe endpoint.',
+    detectionPaths: ['packages/rbac/package.json'],
+    provides: ['rbac-runtime'],
+    requires: [],
+    optionalIntegrations: [
+      {
+        id: 'auth-rbac-claims',
+        title: 'Auth Claims Integration',
+        modules: ['jwt-auth', 'rbac'],
+        requires: [{ type: 'module', id: 'jwt-auth' }],
+        description: [
+          'Expose demo RBAC permissions inside JWT payloads',
+          'Return permissions through refresh and /me responses',
+        ],
+        followUpCommands: [
+          'npx create-forgeon@latest add jwt-auth',
+          'pnpm forgeon:sync-integrations',
+        ],
+      },
+    ],
     docFragments: [
       '00_title',
       '10_overview',
@@ -78,20 +150,33 @@ const MODULE_PRESETS = {
   queue: {
     id: 'queue',
     label: 'Queue Worker',
-    category: 'background-jobs',
-    implemented: false,
-    description: 'Queue processing preset (BullMQ-style app wiring).',
-    docFragments: ['00_title', '10_overview', '20_scope', '90_status_planned'],
-  },
-};
+    category: 'background-jobs',
+    implemented: false,
+    description: 'Queue processing preset (BullMQ-style app wiring).',
+    detectionPaths: ['packages/queue/package.json'],
+    provides: ['queue-runtime'],
+    requires: [],
+    optionalIntegrations: [],
+    docFragments: ['00_title', '10_overview', '20_scope', '90_status_planned'],
+  },
+};
 
 export function listModulePresets() {
   return Object.values(MODULE_PRESETS);
 }
 
-export function getModulePreset(moduleId) {
-  return MODULE_PRESETS[moduleId] ?? null;
-}
+export function getModulePreset(moduleId) {
+  return MODULE_PRESETS[moduleId] ?? null;
+}
+
+export function getCapabilityProviders(capabilityId, { implementedOnly = true } = {}) {
+  return listModulePresets().filter((preset) => {
+    if (implementedOnly && !preset.implemented) {
+      return false;
+    }
+    return Array.isArray(preset.provides) && preset.provides.includes(capabilityId);
+  });
+}
 
 export function ensureModuleExists(moduleId) {
   const preset = getModulePreset(moduleId);

package/src/run-add-module.mjs

@@ -3,9 +3,15 @@ import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { printAddHelp } from './cli/add-help.mjs';
 import { parseAddCliArgs } from './cli/add-options.mjs';
+import { promptSelect } from './cli/prompt-select.mjs';
 import { addModule } from './modules/executor.mjs';
+import { getPendingOptionalIntegrations, resolveModuleInstallPlan } from './modules/dependencies.mjs';
 import { listModulePresets } from './modules/registry.mjs';
-import { printModuleAdded, runIntegrationFlow } from './integrations/flow.mjs';
+import {
+  printModuleAdded,
+  printOptionalIntegrationsWarning,
+  runIntegrationFlow,
+} from './integrations/flow.mjs';
 import { writeJson } from './utils/fs.mjs';
 
 function printModuleList() {
@@ -114,8 +120,40 @@ function ensureSyncTooling({ packageRoot, targetRoot }) {
   writeJson(packagePath, packageJson);
 }
 
+function printInstallPlan(moduleSequence) {
+  if (!Array.isArray(moduleSequence) || moduleSequence.length === 0) {
+    return;
+  }
+
+  console.log('Install plan:');
+  moduleSequence.forEach((moduleId, index) => {
+    console.log(`${index + 1}. ${moduleId}`);
+  });
+}
+
+async function confirmInstallPlan(moduleSequence, requestedModuleId) {
+  if (moduleSequence.length <= 1) {
+    return true;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return true;
+  }
+
+  printInstallPlan(moduleSequence);
+  const picked = await promptSelect({
+    message: `Apply now for "${requestedModuleId}"?`,
+    defaultValue: 'cancel',
+    choices: [
+      { label: 'Yes, apply install plan', value: 'apply' },
+      { label: 'Cancel', value: 'cancel' },
+    ],
+  });
+  return picked === 'apply';
+}
+
 export async function runAddModule(argv = process.argv.slice(2)) {
-  const options = parseAddCliArgs(argv);
+  const options = parseAddCliArgs(argv);
 
   if (options.help) {
     printAddHelp();
@@ -135,19 +173,45 @@ export async function runAddModule(argv = process.argv.slice(2)) {
   const packageRoot = path.resolve(srcDir, '..');
   const targetRoot = path.resolve(process.cwd(), options.project);
   const dependencyManifestStateBefore = collectDependencyManifestState(targetRoot);
-
-  const result = addModule({
+  const plan = await resolveModuleInstallPlan({
     moduleId: options.moduleId,
     targetRoot,
-    packageRoot,
+    withRequired: options.withRequired,
+    providerSelections: options.providers,
   });
+
+  if (plan.cancelled) {
+    console.log('Installation cancelled.');
+    return;
+  }
+
+  const confirmed = await confirmInstallPlan(plan.moduleSequence, options.moduleId);
+  if (!confirmed) {
+    console.log('Installation cancelled.');
+    return;
+  }
+
+  for (const moduleId of plan.moduleSequence) {
+    const currentResult = addModule({
+      moduleId,
+      targetRoot,
+      packageRoot,
+    });
+    printModuleAdded(currentResult.preset.id, currentResult.docsPath);
+  }
+
   ensureSyncTooling({ packageRoot, targetRoot });
-  printModuleAdded(result.preset.id, result.docsPath);
   await runIntegrationFlow({
     targetRoot,
     packageRoot,
-    relatedModuleId: result.preset.id,
+    relatedModuleId: options.moduleId,
+  });
+
+  const pendingOptionalIntegrations = getPendingOptionalIntegrations({
+    moduleId: options.moduleId,
+    targetRoot,
   });
+  printOptionalIntegrationsWarning(pendingOptionalIntegrations);
 
   const dependencyManifestStateAfter = collectDependencyManifestState(targetRoot);
   const changedDependencyManifestPaths = getChangedDependencyManifestPaths(