NNO Shell Feature Config

1. Developer installs:     pnpm add @neutrino-io/feature-analytics
2. Vite plugin scans:      package.json → finds neutrino.type === "feature"
3. Virtual module generated: import * as _f0 from '@neutrino-io/feature-analytics'
4. features.config.ts:      merges manifest + local features + overrides
5. Shell boots normally:    FeatureRegistry loads from virtual module

// virtual:feature-registry (auto-generated, not a real file)
import * as _f0 from "@neutrino-io/feature-billing";
import * as _f1 from "@neutrino-io/feature-settings";

export const featureImports = {
  "@neutrino-io/feature-billing": _f0,
  "@neutrino-io/feature-settings": _f1,
};

export const featureManifests = [
  _f0.featureManifest,
  _f1.featureManifest,
].filter(Boolean);

interface FeatureManifest {
  id: string; // Feature identifier (kebab-case)
  name: string; // Human-readable name
  package: string; // npm package name
  module?: string; // Module path within package
  enabledByDefault: boolean; // Default enabled state
  loadPriority?: number; // Load order (lower = earlier)
  lazyLoad?: boolean; // Lazy-load flag
  environment?: string; // Environment restriction
  domain?: string; // Business domain grouping
  type?: "system" | "business"; // Feature type
  group?: string; // Sidebar group heading
  defaultComponent?: string; // Default component name
  defaultRedirect?: string; // Default redirect path
  subRoutes?: Record<string, SubRouteConfig>;
  settingsConfig?: Record<string, unknown>;
  navigation?: FeatureNavigationConfig;
}

// packages/sdk/src/types/feature-config.ts

export type FeaturesConfig = Record<string, FeatureConfig>;

export interface FeatureConfig {
  // ── Identity ──────────────────────────────────────────────────
  /** Unique feature slug. Kebab-case. Matches FeatureDefinition.id */
  id: string;

  /**
   * Human-readable display name shown in shell chrome.
   * Legacy optional alias for FeatureDefinition.displayName — omit in new entries.
   */
  name?: string;

  /**
   * Semver of the installed package (from FeatureDefinition.version).
   * Optional — can be inferred from the package at load time.
   */
  version?: string;

  // ── Load Control ─────────────────────────────────────────────
  /**
   * Whether this feature is active. NNO sets false on deactivation.
   * Shell skips loading disabled features.
   */
  enabled: boolean;

  /**
   * Load order priority. Lower = earlier.
   * Core features: 1–9. Domain features: 10–89. Client features: 90–98.
   * System features (404, 500): 0.
   */
  loadPriority?: number;

  /**
   * Whether to defer loading until first navigation to the feature.
   * false = eager (bundled in main chunk). true = lazy (code-split).
   * Core features are eager; domain and client features are lazy.
   */
  lazyLoad?: boolean;

  // ── Package Binding ──────────────────────────────────────────
  /** npm package name, e.g. '@neutrino-io/feature-billing' */
  package: string;

  /** Module path within the package, e.g. 'features/billing' */
  module: string;

  /** Default exported component name to mount at the feature root */
  defaultComponent?: string;

  /** Default redirect when landing on the feature root */
  defaultRedirect?: string;

  // ── Environment ──────────────────────────────────────────────
  /** Which environments to enable this feature in */
  environment?: "development" | "staging" | "production" | "all";

  // ── Domain / Type Classification ────────────────────────────
  /**
   * Feature domain classification.
   * 'core' = always present (auth, settings)
   * Any other string = client/domain-specific feature domain
   */
  domain: string;

  /**
   * 'business' = appears in sidebar and routing.
   * 'system'   = error pages, auth flows — hidden from sidebar.
   */
  type: "business" | "system";

  // ── Sidebar ─────────────────────────────────────────────────
  /** Optional sidebar group label for this feature's nav entry */
  group?: string;

  // ── Routing ─────────────────────────────────────────────────
  /** Sub-routes within this feature, keyed by path segment */
  subRoutes?: Record<string, SubRouteConfig>;

  /** Whether this feature's route is the app's default landing page */
  isDefault?: boolean;

  // ── Navigation ──────────────────────────────────────────────
  navigation?: FeatureNavigationConfig;

  // ── Permissions ─────────────────────────────────────────────
  /**
   * Permission keys required to access this feature.
   * Matches FeatureDefinition.permissions[].key where required: true.
   * If the current user lacks ALL required permissions, the feature
   * route renders a <Forbidden> page and sidebar entry is hidden.
   */
  permissions?: string[];

  // ── Feature-Specific Config ──────────────────────────────────
  /** Arbitrary config bag passed to the feature's onActivate hook */
  featureConfig?: Record<string, unknown>;

  /** Settings-specific metadata passed to the settings feature */
  settingsConfig?: Record<string, unknown>;
}

export interface SubRouteConfig {
  /** Component name exported by the feature package */
  component: string;

  /** Additional permission keys required for this specific sub-route */
  permissions?: string[];
}

export interface FeatureNavigationConfig {
  mode: "default" | "custom" | "hybrid";
  sidebar: {
    show: boolean;
    /** If true, this feature replaces the default sidebar entirely */
    replace?: boolean;
  };
  header: {
    show: boolean;
    title?: string;
    replace?: boolean;
  };
  layout: {
    fullscreen?: boolean;
    containerClass?: string;
    contentClass?: string;
  };
}

// src/config/features.config.ts
// ⚠️  GENERATED FILE — DO NOT EDIT MANUALLY
// Managed by NNO CLI Service. Changes will be overwritten on next feature activation.
// Last generated: 2026-02-22T10:34:00Z by NNO CLI Service v1.0.0

import type { FeaturesConfig } from "@neutrino-io/sdk";

export const featuresConfig: FeaturesConfig = {
  // ── Core Features (always present) ──────────────────────────────────────────

  auth: {
    id: "auth",
    name: "Authentication",
    version: "^2.1.0", // version is optional; can be inferred from package at load time
    enabled: true,
    loadPriority: 1,
    lazyLoad: false,
    package: "@neutrino-io/ui-auth",
    module: "features/auth",
    environment: "all",
    domain: "core",
    type: "system",
    navigation: {
      mode: "custom",
      sidebar: { show: false },
      header: { show: false },
      layout: { fullscreen: true },
    },
  },

  settings: {
    id: "settings",
    name: "Settings",
    // version is optional — omitted here; inferred from package at load time
    enabled: true,
    loadPriority: 2,
    lazyLoad: true,
    package: "@neutrino-io/feature-settings",
    module: "features/settings",
    defaultComponent: "ProfileSettings",
    defaultRedirect: "/settings/profile",
    environment: "all",
    domain: "core",
    type: "business",
    group: "Account",
    subRoutes: {
      profile: { component: "ProfileSettings" },
      account: { component: "AccountSettings" },
      organization: { component: "OrganizationSettings" },
      appearance: { component: "AppearanceSettings" },
      notifications: { component: "NotificationSettings" },
      display: { component: "DisplaySettings" },
    },
    navigation: {
      mode: "default",
      sidebar: { show: true },
      header: { show: true, title: "Settings" },
      layout: { fullscreen: false },
    },
  },

  // ── Domain Features (activated per tenant) ──────────────────────────────────

  billing: {
    id: "billing",
    name: "Billing",
    // version is optional — omitted here; inferred from package at load time
    enabled: true, // ← set to false on deactivation
    // Note: starter template defaults to enabled: false (billing not yet wired).
    // This example shows the config after billing is activated on a live platform.
    loadPriority: 80,
    lazyLoad: true,
    package: "@neutrino-io/feature-billing",
    module: "features/billing",
    defaultComponent: "BillingDashboard",
    environment: "all",
    domain: "billing", // billing has its own domain (not 'core')
    type: "business",
    group: "Account",
    permissions: ["billing:read"],
    navigation: {
      mode: "default",
      sidebar: { show: true },
      header: { show: true, title: "Billing" },
      layout: { fullscreen: false },
    },
  },

  // ── Console-local Features (from @neutrino-io/ui-core, platform template) ────────

  helpCenter: {
    id: "help-center",
    name: "Help Center",
    enabled: true,
    loadPriority: 99,
    lazyLoad: true,
    package: "@neutrino-io/ui-core",
    module: "features/help",
    defaultComponent: "Help",
    environment: "all",
    domain: "core",
    type: "business",
    group: "Overview",
    navigation: {
      mode: "default",
      sidebar: { show: true },
      header: { show: true, title: "Help Center" },
      layout: { fullscreen: false },
    },
  },

  // ── System Features ──────────────────────────────────────────────────────────

  notFound: {
    id: "404",
    name: "Not Found",
    enabled: true,
    loadPriority: 0,
    lazyLoad: false,
    package: "@neutrino-io/ui-core",
    module: "features/errors/not-found",
    environment: "all",
    domain: "core",
    type: "system",
  },

  serverError: {
    id: "500",
    name: "Server Error",
    enabled: true,
    loadPriority: 0,
    lazyLoad: false,
    package: "@neutrino-io/ui-core",
    module: "features/errors/server-error",
    environment: "all",
    domain: "core",
    type: "system",
  },

  forbidden: {
    id: "403",
    name: "Forbidden",
    enabled: true,
    loadPriority: 0,
    lazyLoad: false,
    package: "@neutrino-io/ui-core",
    module: "features/errors/forbidden",
    environment: "all",
    domain: "core",
    type: "system",
  },
};

export default featuresConfig;

Browser loads shell (CF Pages → CDN → static bundle)
         │
         ▼
index.html executes
  → React application initialises
  → TanStack Router creates router instance
         │
         ▼
AppProviders mounts
  → AuthProvider: initialises Better Auth session check
  → FeatureRegistryProvider: reads featuresConfig (static import, zero network)
         │
         ▼
FeatureRegistry.initialize()
  1. getEnabledFeatures()
       → filters featuresConfig by enabled: true
       → filters by environment match (MODE env var)
       → sorts by loadPriority
  2. preloadPackages(enabledFeatures)
       → resolves known packages via static import registry
         (no dynamic fetch — all bundled at build time)
  3. loadFeatures(enabledFeatures)
       → for each enabled feature:
           reads FeatureDefinition from package (prefers {id}FeatureDefinition
             over legacy {id}FeatureConfig for full navigation hierarchy)
           stores component, routes, sidebarItems, navigation, permissions,
             providers in FeatureModule registry
         │
         ▼
RouteGenerator.build(registry)
  → creates TanStack Router route tree from all registered feature routes
  → features/ workspace packages (billing, settings) define their own routes
    via FeatureDefinition.routes[] — registered as-is by generateDefinitionRoutes()
  → wraps protected routes in permission checks

  > **Note**: The old "prefix each route with /{featureId}/" pattern applied only to
  > legacy single-component feature entries. All current feature packages in the
  > `features/` workspace use `FeatureDefinition.routes[]` and `generateDefinitionRoutes()`
  > (called inside `getCoreFeatureRoutes()` in `features.config.ts`), which registers
  > routes exactly as defined in each FeatureDefinition — no shell-level prefix is added.
         │
         ▼
SidebarGenerator.build(registry, userPermissions)
  → for each enabled business feature with sidebar visibility:
      1. Check feature module for FeatureDefinition.navigation[]
         → if navigation[0].children exists → collapsible sub-menu
         → otherwise → flat link
      2. Fall back to legacy settingsConfig or flat link
  → groups items by feature.group into NavGroup[]
  → merges into static navigation groups from navigation.config.ts
         │
         ▼
App renders with complete route tree and sidebar

class FeatureRegistry {
  async initialize(): Promise<void> {
    const enabledFeatures = this.getEnabledFeatures();
    // Phase 1: load all package modules (static bundles)
    await this.preloadPackages(enabledFeatures);
    // Phase 2: extract FeatureDefinition from each package
    await this.loadFeatures(enabledFeatures);
  }

  getEnabledFeatures(): FeatureConfig[] {
    return Object.values(this.config)
      .filter((f): f is FeatureConfig => f.enabled)
      .filter((f) => this.isEnvironmentMatch(f))
      .sort((a, b) => (a.loadPriority ?? 999) - (b.loadPriority ?? 999));
  }

  private isEnvironmentMatch(feature: FeatureConfig): boolean {
    const currentEnv = import.meta.env.MODE; // 'development' | 'staging' | 'production'
    return feature.environment === "all" || feature.environment === currentEnv;
  }
}

// 1. Console-local features (static import, always available)
this.packageRegistry.set("@console/features", consoleFeatures);

// 2. Auto-discovered feature packages (from Vite plugin)
for (const [packageName, packageModule] of Object.entries(featureImports)) {
  this.packageRegistry.set(packageName, packageModule);
}

// 3. Fallback: dynamic import for packages not covered above
const packageModule = await import(/* @vite-ignore */ packageName);

// Canonical: {id}FeatureDefinition (e.g. settingsFeatureDefinition)
const definitionName = `${camelCaseId}FeatureDefinition`;
// Legacy:   {id}FeatureConfig     (e.g. settingsFeatureConfig)
const configName = `${camelCaseId}FeatureConfig`;

// Prefer definition — it has the full navigation hierarchy with children
const featureConfig =
  packageModule[definitionName] ?? packageModule[configName];

User navigates to /billing
         │
         ▼
TanStack Router resolves route
         │
         ▼
<PermissionGate permissions={['billing:read']}>
  │
  ├─ User has 'billing:read'? → Render <BillingDashboard />
  └─ User lacks permission?   → Render <Forbidden />
                                 (sidebar entry is also hidden)

function PermissionGate({
  permissions,
  children,
}: {
  permissions: string[];
  children: React.ReactNode;
}) {
  const { user } = useNnoSession();

  // All listed permissions must be present (AND logic)
  const hasAccess = permissions.every((p) =>
    user.permissions.includes(p) || user.permissions.includes('*')
  );

  if (!hasAccess) return <Forbidden />;
  return <>{children}</>;
}

{
  "userId": "usr_abc123",
  "tenantId": "r8n4t6y1z5",
  "platformId": "k3m9p2xw7q",
  "permissions": ["billing:read", "settings:write", "zero:access"],
  "exp": 1740230400
}

subRoutes: {
  export: {
    component: 'BillingExport',
    permissions: ['billing:manage'],  // ← additional requirement
  },
}

For each enabled business feature with isSidebarVisible(config) === true:

Strategy 1: Feature sidebarItems (legacy)
  → If the FeatureModule has sidebarItems[], use the first item directly
  → Supports both flat links and collapsible sub-menus

Strategy 2: FeatureDefinition.navigation[] (canonical)
  → If the FeatureModule has navigation[] from its FeatureDefinition:
    → Read navigation[0] as the top-level nav item
    → If navigation[0].children[] exists:
      → Sort children by order (ascending, default 99)
      → Build a collapsible sub-menu with each child as a link
      → Resolve icon strings (e.g. 'User', 'Settings') to lucide components
    → Otherwise: build a flat link

Strategy 3: Settings legacy (settingsConfig)
  → Only for feature id === 'settings' with a settingsConfig object
  → Generates sub-items from enabled sections in settingsConfig

Strategy 4: Flat link fallback
  → title = config.name, url = /{config.id}, icon from getFeatureIcon()

// FeatureDefinition.navigation (from features/settings/src/feature.ts)
navigation: [
  {
    label: "Settings",
    path: "/settings",
    icon: "Settings",
    order: 90,
    children: [
      { label: "Profile", path: "/settings/profile", icon: "User", order: 1 },
      {
        label: "Account",
        path: "/settings/account",
        icon: "UserCog",
        order: 2,
      },
      {
        label: "Appearance",
        path: "/settings/appearance",
        icon: "Palette",
        order: 3,
      },
      {
        label: "Notifications",
        path: "/settings/notifications",
        icon: "Bell",
        order: 4,
      },
      { label: "Display", path: "/settings/display", icon: "Eye", order: 5 },
      {
        label: "Organization",
        path: "/settings/organization",
        icon: "Users",
        order: 6,
      },
    ],
  },
];

// Produces a collapsible sidebar item:
//   Settings ▾
//     Profile
//     Account
//     Appearance
//     Notifications
//     Display
//     Organization

debugPanel: {
  id: 'debug-panel',
  name: 'Debug Panel',
  enabled: true,
  environment: 'development',   // ← stripped out at staging/prod
  ...
}

function featureDefinitionToConfig(
  def: FeatureDefinition,
  packageName: string,
  packageVersion: string,
  loadPriority: number,
): FeatureConfig {
  return {
    // Identity
    id: def.id,
    name: def.displayName,
    version: packageVersion,

    // Load control
    enabled: true,
    loadPriority,
    lazyLoad: loadPriority > 9, // default: domain + client features are lazy; individual entries can override

    // Package
    package: packageName,
    module: `features/${def.id}`,
    defaultComponent: toPascalCase(def.id),

    // Classification
    environment: "all",
    domain: def.id === "auth" || def.id === "settings" ? "core" : def.id,
    type: "business",
    group: inferGroup(def),

    // Permissions (declared permissions from FeatureDefinition — all are gate candidates)
    permissions: def.permissions, // FeaturePermission = string (e.g. 'analytics:read')

    // Navigation (derived from FeatureDefinition.navigation)
    navigation: {
      mode: "default",
      sidebar: { show: def.navigation.length > 0 },
      header: { show: true, title: def.displayName },
      layout: { fullscreen: false },
    },
  };
}

// src/config/env.config.ts
// ⚠️  GENERATED FILE — DO NOT EDIT MANUALLY

export const serviceUrls: Record<string, string> = {
  VITE_AUTH_API_URL: "https://k3m9p2xw7q-r8n4t6y1z5-auth-prod.workers.dev",
  VITE_BILLING_API_URL:
    "https://k3m9p2xw7q-r8n4t6y1z5-billing-prod.workers.dev",
};

function useServiceUrl(envKey: string): string {
  const url = import.meta.env[envKey] ?? serviceUrls[envKey];
  if (!url) throw new Error(`Service URL not configured for ${envKey}`);
  return url;
}

FeatureDefinition (in package)     features.config.ts (in platform repo)
─────────────────────────────     ─────────────────────────────────────
Source of truth for:               Generated from FeatureDefinition when
  - contract / validation            feature is activated.
  - permissions declared           Controls:
  - routes declared                  - which features boot with the shell
  - service binding config           - sidebar/nav visibility
  - lifecycle hooks                  - load order and lazy-loading
                                     - environment scoping
                                     - permission gate keys