@pellux/goodvibes-tui 0.19.27 → 0.19.29

package/src/runtime/onboarding/derivation.ts

@@ -240,22 +240,22 @@ function hasExternalIntegrations(snapshot: OnboardingSnapshotState): boolean {
 
 function describeLocalTuiOnly(snapshot: OnboardingSnapshotState): string {
   if (!hasAnyServerEnabled(snapshot)) {
-    return 'Keep GoodVibes in this terminal and disable browser access, background services, network listeners, and external surfaces.';
+    return 'Use GoodVibes only in this terminal. No browser access, background service, HTTP listener, external app surface, or network setup.';
   }
 
-  return 'Switching to this disables browser access, background services, network listeners, and external surfaces.';
+  return 'Turn off browser access, background services, HTTP listeners, external app surfaces, and network setup.';
 }
 
 function describeBrowserAccess(snapshot: OnboardingSnapshotState): string {
   return snapshot.bindSettings.web.enabled
-    ? 'Keep the background service and web UI enabled, reachable according to the network step.'
-    : 'Enable the background service and web UI, reachable on the local network by default unless customized.';
+    ? 'Keep the background service and web UI enabled. Network reachability is controlled on the next screen.'
+    : 'Run the background service and web UI. GoodVibes will use the local network by default; you can restrict or customize it next.';
 }
 
 function describeRemoteDeviceAccess(snapshot: OnboardingSnapshotState): string {
   return hasRemoteDeviceAccess(snapshot)
-    ? 'Keep enabled GoodVibes services reachable from other devices on your LAN. Local auth is required.'
-    : 'Expose enabled GoodVibes services on your LAN so other devices can reach them. Local auth is required.';
+    ? 'Keep enabled GoodVibes services reachable from other devices on your LAN. Local authentication is required.'
+    : 'Make enabled GoodVibes services reachable from other devices on your LAN. Local authentication is required.';
 }
 
 function describeWebhookIngress(snapshot: OnboardingSnapshotState): string {
@@ -272,7 +272,7 @@ function describeExternalIntegrations(snapshot: OnboardingSnapshotState): string
   ]).size;
 
   if (integrationCount === 0) {
-    return 'Show Slack, Discord, Telegram, Teams, Matrix, and other app surfaces so they can be enabled and configured here.';
+    return 'Enable setup screens for Slack, Discord, Telegram, Teams, Matrix, and other app surfaces you choose.';
   }
 
   return `Review and configure ${integrationCount} detected external app, service, or surface integration signal(s).`;

package/src/runtime/onboarding/markers.ts

@@ -1,15 +1,15 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type { ShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
 import type {
-  OnboardingCompletionMarkerPayload,
-  OnboardingCompletionMarkerScope,
-  OnboardingCompletionMarkerState,
-  OnboardingCompletionMarkersState,
-  WriteOnboardingCompletionMarkerOptions,
+  OnboardingCheckMarkerPayload,
+  OnboardingCheckMarkerState,
+  OnboardingCheckMarkersState,
+  OnboardingStateScope,
+  WriteOnboardingCheckMarkerOptions,
 } from './types.ts';
 
-const ONBOARDING_COMPLETION_MARKER_FILE = 'onboarding-complete.json';
+const ONBOARDING_CHECK_MARKER_FILE = 'onboarding-checked.json';
 
 type OnboardingShellPaths = Pick<
   ShellPathService,
@@ -18,26 +18,26 @@ type OnboardingShellPaths = Pick<
 
 function resolveMarkerPath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
 ): string {
   return scope === 'project'
-    ? shellPaths.resolveProjectPath('tui', ONBOARDING_COMPLETION_MARKER_FILE)
-    : shellPaths.resolveUserPath('tui', ONBOARDING_COMPLETION_MARKER_FILE);
+    ? shellPaths.resolveProjectPath('tui', ONBOARDING_CHECK_MARKER_FILE)
+    : shellPaths.resolveUserPath('tui', ONBOARDING_CHECK_MARKER_FILE);
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function isOnboardingMode(value: unknown): value is OnboardingCompletionMarkerPayload['mode'] {
+function isOnboardingMode(value: unknown): value is OnboardingCheckMarkerPayload['mode'] {
   return value === 'new' || value === 'edit' || value === 'reopen';
 }
 
-function isCompletionMarkerPayload(value: unknown): value is OnboardingCompletionMarkerPayload {
+function isCheckMarkerPayload(value: unknown): value is OnboardingCheckMarkerPayload {
   return isObject(value)
     && value.version === 1
-    && typeof value.completedAt === 'number'
-    && Number.isFinite(value.completedAt)
+    && typeof value.checkedAt === 'number'
+    && Number.isFinite(value.checkedAt)
     && typeof value.updatedAt === 'number'
     && Number.isFinite(value.updatedAt)
     && typeof value.source === 'string'
@@ -46,9 +46,9 @@ function isCompletionMarkerPayload(value: unknown): value is OnboardingCompletio
 }
 
 function buildMissingMarkerState(
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
   path: string,
-): OnboardingCompletionMarkerState {
+): OnboardingCheckMarkerState {
   return {
     scope,
     path,
@@ -58,10 +58,10 @@ function buildMissingMarkerState(
 }
 
 function buildParseErrorState(
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
   path: string,
   parseError: string,
-): OnboardingCompletionMarkerState {
+): OnboardingCheckMarkerState {
   return {
     scope,
     path,
@@ -72,34 +72,31 @@ function buildParseErrorState(
 }
 
 function pickEffectiveMarker(
-  project: OnboardingCompletionMarkerState,
-  user: OnboardingCompletionMarkerState,
-): OnboardingCompletionMarkerState | null {
-  if (project.payload) return project;
+  user: OnboardingCheckMarkerState,
+): OnboardingCheckMarkerState | null {
   if (user.payload) return user;
-  if (project.exists) return project;
   if (user.exists) return user;
   return null;
 }
 
-export function getOnboardingCompletionMarkerPath(
+export function getOnboardingCheckMarkerPath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'user',
+  scope: OnboardingStateScope = 'user',
 ): string {
   return resolveMarkerPath(shellPaths, scope);
 }
 
-export function readOnboardingCompletionMarker(
+export function readOnboardingCheckMarker(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'user',
-): OnboardingCompletionMarkerState {
+  scope: OnboardingStateScope = 'user',
+): OnboardingCheckMarkerState {
   const path = resolveMarkerPath(shellPaths, scope);
   if (!existsSync(path)) return buildMissingMarkerState(scope, path);
 
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
-    if (!isCompletionMarkerPayload(parsed)) {
-      return buildParseErrorState(scope, path, 'Invalid onboarding completion marker payload.');
+    if (!isCheckMarkerPayload(parsed)) {
+      return buildParseErrorState(scope, path, 'Invalid onboarding check marker payload.');
     }
 
     return {
@@ -114,48 +111,37 @@ export function readOnboardingCompletionMarker(
   }
 }
 
-export function readOnboardingCompletionMarkers(
+export function readOnboardingCheckMarkers(
   shellPaths: OnboardingShellPaths,
-): OnboardingCompletionMarkersState {
-  const user = readOnboardingCompletionMarker(shellPaths, 'user');
-  const project = readOnboardingCompletionMarker(shellPaths, 'project');
+): OnboardingCheckMarkersState {
+  const user = readOnboardingCheckMarker(shellPaths, 'user');
+  const project = readOnboardingCheckMarker(shellPaths, 'project');
 
   return {
     user,
     project,
-    effective: pickEffectiveMarker(project, user),
+    effective: pickEffectiveMarker(user),
   };
 }
 
-export function writeOnboardingCompletionMarker(
+export function writeOnboardingCheckMarker(
   shellPaths: OnboardingShellPaths,
-  options: WriteOnboardingCompletionMarkerOptions = {},
-): OnboardingCompletionMarkerState {
+  options: WriteOnboardingCheckMarkerOptions = {},
+): OnboardingCheckMarkerState {
   const scope = options.scope ?? 'user';
   const path = resolveMarkerPath(shellPaths, scope);
-  const completedAt = options.completedAt ?? Date.now();
-  const payload: OnboardingCompletionMarkerPayload = {
+  const checkedAt = options.checkedAt ?? Date.now();
+  const payload: OnboardingCheckMarkerPayload = {
     version: 1,
-    completedAt,
-    updatedAt: options.updatedAt ?? completedAt,
+    checkedAt,
+    updatedAt: options.updatedAt ?? checkedAt,
     source: options.source ?? 'wizard',
     ...(options.mode ? { mode: options.mode } : {}),
-    ...(options.workspaceRoot ?? shellPaths.workingDirectory
-      ? { workspaceRoot: options.workspaceRoot ?? shellPaths.workingDirectory }
-      : {}),
+    ...(options.workspaceRoot ? { workspaceRoot: options.workspaceRoot } : {}),
   };
 
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
 
-  return readOnboardingCompletionMarker(shellPaths, scope);
-}
-
-export function clearOnboardingCompletionMarker(
-  shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'user',
-): OnboardingCompletionMarkerState {
-  const path = resolveMarkerPath(shellPaths, scope);
-  if (existsSync(path)) unlinkSync(path);
-  return buildMissingMarkerState(scope, path);
+  return readOnboardingCheckMarker(shellPaths, scope);
 }

package/src/runtime/onboarding/snapshot.ts

@@ -40,6 +40,7 @@ function buildConfigSnapshot(
     network: config.getCategory('network'),
     surfaces: config.getCategory('surfaces'),
     service: config.getCategory('service'),
+    featureFlags: config.getCategory('featureFlags'),
   };
 }
 

package/src/runtime/onboarding/state.ts

@@ -3,15 +3,15 @@ import { dirname } from 'node:path';
 import type {
   OnboardingAcknowledgementRuntimeState,
   OnboardingAcknowledgementTarget,
-  OnboardingCompletionMarkerScope,
   OnboardingMode,
   OnboardingShellPaths,
+  OnboardingStateScope,
 } from './types.ts';
 
 const ONBOARDING_RUNTIME_STATE_FILE = 'onboarding-state.json';
 
 export interface OnboardingRuntimeStateRecord {
-  readonly scope: OnboardingCompletionMarkerScope;
+  readonly scope: OnboardingStateScope;
   readonly path: string;
   readonly exists: boolean;
   readonly payload: OnboardingAcknowledgementRuntimeState | null;
@@ -19,7 +19,7 @@ export interface OnboardingRuntimeStateRecord {
 }
 
 interface WriteOnboardingAcknowledgementStateOptions {
-  readonly scope?: OnboardingCompletionMarkerScope;
+  readonly scope?: OnboardingStateScope;
   readonly target: OnboardingAcknowledgementTarget;
   readonly acknowledged: boolean;
   readonly updatedAt?: number;
@@ -30,7 +30,7 @@ interface WriteOnboardingAcknowledgementStateOptions {
 
 function resolveStatePath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
 ): string {
   return scope === 'project'
     ? shellPaths.resolveProjectPath('tui', ONBOARDING_RUNTIME_STATE_FILE)
@@ -63,14 +63,14 @@ function isRuntimeStatePayload(value: unknown): value is OnboardingAcknowledgeme
 
 export function getOnboardingRuntimeStatePath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'project',
+  scope: OnboardingStateScope = 'project',
 ): string {
   return resolveStatePath(shellPaths, scope);
 }
 
 export function readOnboardingRuntimeState(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'project',
+  scope: OnboardingStateScope = 'project',
 ): OnboardingRuntimeStateRecord {
   const path = resolveStatePath(shellPaths, scope);
   if (!existsSync(path)) {

package/src/runtime/onboarding/types.ts

@@ -1,5 +1,6 @@
 import type { ConfigManager, ConfigKey, GoodVibesConfig } from '../../config/index.ts';
 import type { SecretsManager, SecretRecord, SecretStorageReview } from '../../config/secrets.ts';
+import type { FeatureFlagConfigKey } from '../surface-feature-flags.ts';
 import type { LocalAuthSnapshot, UserAuthManager } from '@pellux/goodvibes-sdk/platform/security/user-auth';
 import type { ShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
 import type {
@@ -26,9 +27,9 @@ export type OnboardingAcknowledgementReason =
 
 export type OnboardingVerificationStatus = 'pass' | 'warn' | 'fail';
 
-export type OnboardingCompletionMarkerScope = 'user' | 'project';
+export type OnboardingStateScope = 'user' | 'project';
 
-export type OnboardingCompletionMarkerSource = 'wizard' | 'command' | 'import' | 'unknown';
+export type OnboardingCheckMarkerSource = 'wizard' | 'command' | 'import' | 'unknown';
 
 export interface OnboardingConfigSnapshot {
   readonly display: GoodVibesConfig['display'];
@@ -45,6 +46,7 @@ export interface OnboardingConfigSnapshot {
   readonly network: GoodVibesConfig['network'];
   readonly surfaces: GoodVibesConfig['surfaces'];
   readonly service: GoodVibesConfig['service'];
+  readonly featureFlags: GoodVibesConfig['featureFlags'];
 }
 
 export interface OnboardingProviderRoutingSnapshot {
@@ -147,7 +149,7 @@ export interface OnboardingRuntimeDefaultsSnapshot {
 }
 
 export interface OnboardingAcknowledgementSnapshot {
-  readonly scope: OnboardingCompletionMarkerScope;
+  readonly scope: OnboardingStateScope;
   readonly exists: boolean;
   readonly updatedAt: number | null;
   readonly source: string | null;
@@ -235,7 +237,7 @@ export interface OnboardingStepDerivationState {
 export type OnboardingApplyOperation =
   | {
       readonly kind: 'set-config';
-      readonly key: ConfigKey;
+      readonly key: ConfigKey | FeatureFlagConfigKey;
       readonly value: unknown;
       readonly scope?: 'global' | 'project';
     }
@@ -258,12 +260,6 @@ export type OnboardingApplyOperation =
       readonly kind: 'acknowledge';
       readonly target: OnboardingAcknowledgementTarget;
       readonly acknowledged: boolean;
-    }
-  | {
-      readonly kind: 'set-completion-marker';
-      readonly scope: OnboardingCompletionMarkerScope;
-      readonly completed: boolean;
-      readonly payload?: Partial<OnboardingCompletionMarkerPayload>;
     };
 
 export interface OnboardingApplyRequest {
@@ -316,34 +312,34 @@ export interface OnboardingAcknowledgementRuntimeState {
   readonly acknowledgements: Partial<Record<OnboardingAcknowledgementTarget, boolean>>;
 }
 
-export interface OnboardingCompletionMarkerPayload {
+export interface OnboardingCheckMarkerPayload {
   readonly version: 1;
-  readonly completedAt: number;
+  readonly checkedAt: number;
   readonly updatedAt: number;
-  readonly source: OnboardingCompletionMarkerSource;
+  readonly source: OnboardingCheckMarkerSource;
   readonly mode?: OnboardingMode;
   readonly workspaceRoot?: string;
 }
 
-export interface OnboardingCompletionMarkerState {
-  readonly scope: OnboardingCompletionMarkerScope;
+export interface OnboardingCheckMarkerState {
+  readonly scope: OnboardingStateScope;
   readonly path: string;
   readonly exists: boolean;
-  readonly payload: OnboardingCompletionMarkerPayload | null;
+  readonly payload: OnboardingCheckMarkerPayload | null;
   readonly parseError?: string;
 }
 
-export interface OnboardingCompletionMarkersState {
-  readonly user: OnboardingCompletionMarkerState;
-  readonly project: OnboardingCompletionMarkerState;
-  readonly effective: OnboardingCompletionMarkerState | null;
+export interface OnboardingCheckMarkersState {
+  readonly user: OnboardingCheckMarkerState;
+  readonly project: OnboardingCheckMarkerState;
+  readonly effective: OnboardingCheckMarkerState | null;
 }
 
-export interface WriteOnboardingCompletionMarkerOptions {
-  readonly scope?: OnboardingCompletionMarkerScope;
-  readonly completedAt?: number;
+export interface WriteOnboardingCheckMarkerOptions {
+  readonly scope?: OnboardingStateScope;
+  readonly checkedAt?: number;
   readonly updatedAt?: number;
-  readonly source?: OnboardingCompletionMarkerSource;
+  readonly source?: OnboardingCheckMarkerSource;
   readonly mode?: OnboardingMode;
   readonly workspaceRoot?: string;
 }
@@ -371,7 +367,7 @@ export interface OnboardingSnapshotDependencies {
   readonly surfaces?: OnboardingSurfaceReadHelper;
   readonly providerAccounts?: OnboardingProviderAccountReadHelper;
   readonly shellPaths?: OnboardingShellPaths;
-  readonly acknowledgementScope?: OnboardingCompletionMarkerScope;
+  readonly acknowledgementScope?: OnboardingStateScope;
 }
 
 export interface OnboardingApplyDependencies {
@@ -387,9 +383,10 @@ export interface OnboardingApplyDependencies {
     | 'getUser'
     | 'inspect'
     | 'revokeSession'
+    | 'rotatePassword'
   >;
   readonly shellPaths: OnboardingShellPaths;
-  readonly acknowledgementScope?: OnboardingCompletionMarkerScope;
+  readonly acknowledgementScope?: OnboardingStateScope;
 }
 
 export interface OnboardingVerificationDependencies {
@@ -398,5 +395,5 @@ export interface OnboardingVerificationDependencies {
   readonly secrets?: Pick<SecretsManager, 'get'>;
   readonly auth?: Pick<UserAuthManager, 'inspect'>;
   readonly shellPaths: OnboardingShellPaths;
-  readonly acknowledgementScope?: OnboardingCompletionMarkerScope;
+  readonly acknowledgementScope?: OnboardingStateScope;
 }

package/src/runtime/onboarding/verify.ts

@@ -1,5 +1,4 @@
 import { isSecretRefInput } from '@pellux/goodvibes-sdk/platform/config/secret-refs';
-import { readOnboardingCompletionMarker } from './markers.ts';
 import { readOnboardingRuntimeState } from './state.ts';
 import type {
   OnboardingApplyOperation,
@@ -13,11 +12,6 @@ function getNow(deps: Pick<OnboardingVerificationDependencies, 'clock'>): number
   return deps.clock?.() ?? Date.now();
 }
 
-function normalizeCompletionSource(source: string): 'wizard' | 'command' | 'import' | 'unknown' {
-  if (source === 'wizard' || source === 'command' || source === 'import') return source;
-  return 'unknown';
-}
-
 function isDeepEqual(left: unknown, right: unknown): boolean {
   if (Object.is(left, right)) return true;
   if (Array.isArray(left) && Array.isArray(right)) {
@@ -49,7 +43,7 @@ function verifyConfigOperation(
   deps: OnboardingVerificationDependencies,
   operation: Extract<OnboardingApplyOperation, { kind: 'set-config' }>,
 ): OnboardingVerificationItem {
-  const actual = deps.config.get(operation.key);
+  const actual = deps.config.get(operation.key as never);
   const ok = isDeepEqual(actual, operation.value);
 
   return {
@@ -89,60 +83,6 @@ function verifyAcknowledgementOperation(
   };
 }
 
-function verifyCompletionMarkerOperation(
-  deps: OnboardingVerificationDependencies,
-  request: OnboardingApplyRequest,
-  operation: Extract<OnboardingApplyOperation, { kind: 'set-completion-marker' }>,
-): OnboardingVerificationItem {
-  const marker = readOnboardingCompletionMarker(deps.shellPaths, operation.scope);
-  if (marker.parseError) {
-    return {
-      id: `marker:${operation.scope}`,
-      status: 'fail',
-      message: `Onboarding completion marker could not be parsed: ${marker.parseError}`,
-      target: operation.scope,
-    };
-  }
-
-  if (!operation.completed) {
-    return {
-      id: `marker:${operation.scope}`,
-      status: marker.exists ? 'fail' : 'pass',
-      message: marker.exists
-        ? `${operation.scope} onboarding completion marker still exists.`
-        : `${operation.scope} onboarding completion marker is cleared.`,
-      target: operation.scope,
-    };
-  }
-
-  if (!marker.payload) {
-    return {
-      id: `marker:${operation.scope}`,
-      status: 'fail',
-      message: `${operation.scope} onboarding completion marker is missing.`,
-      target: operation.scope,
-    };
-  }
-
-  const expectedSource = operation.payload?.source ?? normalizeCompletionSource(request.source);
-  const expectedMode = operation.payload?.mode ?? request.mode;
-  const expectedWorkspaceRoot = operation.payload?.workspaceRoot ?? deps.shellPaths.workingDirectory;
-  const payloadMatches = marker.payload.source === expectedSource
-    && (expectedMode === undefined || marker.payload.mode === expectedMode)
-    && (expectedWorkspaceRoot === undefined || marker.payload.workspaceRoot === expectedWorkspaceRoot)
-    && (operation.payload?.completedAt === undefined || marker.payload.completedAt === operation.payload.completedAt)
-    && (operation.payload?.updatedAt === undefined || marker.payload.updatedAt === operation.payload.updatedAt);
-
-  return {
-    id: `marker:${operation.scope}`,
-    status: payloadMatches ? 'pass' : 'fail',
-    message: payloadMatches
-      ? `${operation.scope} onboarding completion marker matches the requested state.`
-      : `${operation.scope} onboarding completion marker does not match the requested state.`,
-    target: operation.scope,
-  };
-}
-
 async function verifySecretOperation(
   deps: OnboardingVerificationDependencies,
   operation: Extract<OnboardingApplyOperation, { kind: 'set-secret' }>,
@@ -209,21 +149,19 @@ function verifyAuthOperation(
 
 async function verifyOperation(
   deps: OnboardingVerificationDependencies,
-  request: OnboardingApplyRequest,
   operation: OnboardingApplyOperation,
 ): Promise<OnboardingVerificationItem> {
   if (operation.kind === 'set-config') return verifyConfigOperation(deps, operation);
   if (operation.kind === 'set-secret') return verifySecretOperation(deps, operation);
   if (operation.kind === 'ensure-auth-user') return verifyAuthOperation(deps, operation);
-  if (operation.kind === 'acknowledge') return verifyAcknowledgementOperation(deps, operation);
-  return verifyCompletionMarkerOperation(deps, request, operation);
+  return verifyAcknowledgementOperation(deps, operation);
 }
 
 export async function verifyOnboardingRequest(
   deps: OnboardingVerificationDependencies,
   request: OnboardingApplyRequest,
 ): Promise<OnboardingVerificationResult> {
-  const items = await Promise.all(request.operations.map((operation) => verifyOperation(deps, request, operation)));
+  const items = await Promise.all(request.operations.map((operation) => verifyOperation(deps, operation)));
 
   return {
     verifiedAt: getNow(deps),

package/src/runtime/surface-feature-flags.ts

@@ -0,0 +1,67 @@
+import type { ConfigKey, ConfigManager, PersistedFlagState } from '../config/index.ts';
+import { surfaceFeatureGateId } from '@pellux/goodvibes-sdk/platform/runtime/feature-flags/index';
+
+export const CONTROL_PLANE_FEATURE_FLAG = 'control-plane-gateway';
+export const ROUTE_BINDING_FEATURE_FLAG = 'route-binding';
+export const DELIVERY_ENGINE_FEATURE_FLAG = 'delivery-engine';
+export const OMNICHANNEL_SURFACE_FEATURE_FLAG = 'omnichannel-surface-adapters';
+export const SERVICE_MANAGEMENT_FEATURE_FLAG = 'service-management';
+
+const CORE_CHANNEL_FEATURE_FLAGS = [
+  CONTROL_PLANE_FEATURE_FLAG,
+  ROUTE_BINDING_FEATURE_FLAG,
+  DELIVERY_ENGINE_FEATURE_FLAG,
+  OMNICHANNEL_SURFACE_FEATURE_FLAG,
+] as const;
+
+export type FeatureFlagConfigKey = 'featureFlags' | `featureFlags.${string}`;
+
+export function getSurfaceFeatureFlag(surfaceId: string): string | null {
+  return surfaceFeatureGateId(surfaceId);
+}
+
+export function getServerSurfaceFeatureFlags(options: {
+  readonly serverBacked?: boolean;
+  readonly web?: boolean;
+  readonly externalSurfaces?: readonly string[];
+}): readonly string[] {
+  const flags = new Set<string>();
+  const hasExternalSurfaces = (options.externalSurfaces?.length ?? 0) > 0;
+
+  if (options.serverBacked || options.web || hasExternalSurfaces) {
+    flags.add(CONTROL_PLANE_FEATURE_FLAG);
+    flags.add(SERVICE_MANAGEMENT_FEATURE_FLAG);
+  }
+  if (options.web) {
+    const webFlag = getSurfaceFeatureFlag('web');
+    if (webFlag) flags.add(webFlag);
+  }
+
+  if (hasExternalSurfaces) {
+    for (const flag of CORE_CHANNEL_FEATURE_FLAGS) flags.add(flag);
+    for (const surfaceId of options.externalSurfaces ?? []) {
+      const surfaceFlag = getSurfaceFeatureFlag(surfaceId);
+      if (surfaceFlag) flags.add(surfaceFlag);
+    }
+  }
+
+  return [...flags].sort((left, right) => left.localeCompare(right));
+}
+
+export function isFeatureFlagEnabled(config: Pick<ConfigManager, 'getCategory'>, flagId: string): boolean {
+  const flags = (config.getCategory('featureFlags') as Record<string, PersistedFlagState | undefined>) ?? {};
+  return flags[flagId] === 'enabled';
+}
+
+export function getMissingSurfaceFeatureFlags(config: Pick<ConfigManager, 'getCategory'>, surfaceId: string): readonly string[] {
+  const required = surfaceId === 'web'
+    ? getServerSurfaceFeatureFlags({ web: true })
+    : getServerSurfaceFeatureFlags({ externalSurfaces: [surfaceId] });
+  return required.filter((flagId) => !isFeatureFlagEnabled(config, flagId));
+}
+
+export function enableFeatureFlags(config: Pick<ConfigManager, 'setDynamic'>, flagIds: readonly string[]): void {
+  for (const flagId of flagIds) {
+    config.setDynamic(`featureFlags.${flagId}` as ConfigKey, 'enabled');
+  }
+}

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.19.27';
+let _version = '0.19.29';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   _version = pkg.version ?? _version;