Merge pull request #562 from Chris0Jeky/fix/524-feature-flag-route-guard

fix: enforce feature-flag gate in route guard (#524)

Author: Chris0Jeky

frontend/taskdeck-web/src/router/index.ts

@@ -5,6 +5,18 @@ import { isTokenExpired } from '../utils/jwt'
 import { isDemoMode, isDemoSessionActive } from '../utils/demoMode'
 import * as tokenStorage from '../utils/tokenStorage'
 import { usePerformanceMark } from '../composables/usePerformanceMark'
+import { useFeatureFlagStore } from '../store/featureFlagStore'
+import type { FeatureFlags } from '../types/feature-flags'
+
+// Augment vue-router's RouteMeta so that `requiresFlag` is type-safe throughout.
+declare module 'vue-router' {
+  interface RouteMeta {
+    public?: boolean
+    requiresShell?: boolean
+    automationSurface?: string
+    requiresFlag?: keyof FeatureFlags
+  }
+}
 
 // Lazy-loaded route components — keeps initial bundle small and speeds up
 // first-paint for login/register (the only eagerly-loaded views).
@@ -92,25 +104,25 @@ const router = createRouter({
       path: '/workspace/activity',
       name: 'workspace-activity',
       component: ActivityView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newActivity' },
     },
     {
       path: '/workspace/activity/board/:boardId',
       name: 'workspace-activity-board',
       component: ActivityView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newActivity' },
     },
     {
       path: '/workspace/activity/entity/:entityType/:entityId',
       name: 'workspace-activity-entity',
       component: ActivityView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newActivity' },
     },
     {
       path: '/workspace/activity/user',
       name: 'workspace-activity-user',
       component: ActivityView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newActivity' },
     },
     {
       path: '/workspace/activity/user/:userId',
@@ -130,13 +142,13 @@ const router = createRouter({
       path: '/workspace/automations/queue',
       name: 'workspace-automations-queue',
       component: AutomationQueueView,
-      meta: { requiresShell: true, automationSurface: 'queue' },
+      meta: { requiresShell: true, automationSurface: 'queue', requiresFlag: 'newAutomation' },
     },
     {
       path: '/workspace/review',
       name: 'workspace-review',
       component: ReviewView,
-      meta: { requiresShell: true, automationSurface: 'review' },
+      meta: { requiresShell: true, automationSurface: 'review', requiresFlag: 'newAutomation' },
     },
     {
       path: '/workspace/automations/proposals',
@@ -150,35 +162,35 @@ const router = createRouter({
       path: '/workspace/automations/chat',
       name: 'workspace-automations-chat',
       component: AutomationChatView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newAutomation' },
     },
 
     // Ops routes
     {
       path: '/workspace/ops/cli',
       name: 'workspace-ops-cli',
       component: OpsConsoleView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newOps' },
     },
     {
       path: '/workspace/ops/endpoints',
       name: 'workspace-ops-endpoints',
       component: OpsConsoleView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newOps' },
     },
     {
       path: '/workspace/ops/logs',
       name: 'workspace-ops-logs',
       component: OpsConsoleView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newOps' },
     },
 
     // Settings routes
     {
       path: '/workspace/settings/profile',
       name: 'workspace-settings-profile',
       component: ProfileSettingsView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newAuth' },
     },
     {
       path: '/workspace/settings/access/:boardId?',
@@ -187,7 +199,7 @@ const router = createRouter({
       props: (route) => ({
         boardId: typeof route.params.boardId === 'string' ? route.params.boardId : null,
       }),
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newAccess' },
     },
     {
       path: '/workspace/settings/export-import',
@@ -207,7 +219,7 @@ const router = createRouter({
       path: '/workspace/archive',
       name: 'workspace-archive',
       component: ArchiveView,
-      meta: { requiresShell: true },
+      meta: { requiresShell: true, requiresFlag: 'newArchive' },
     },
     {
       path: '/workspace/inbox',
@@ -227,7 +239,7 @@ const router = createRouter({
 // Route-transition performance instrumentation
 const routePerf = usePerformanceMark('route-transition')
 
-// Navigation guard for auth
+// Navigation guard for auth and feature flags
 router.beforeEach((to) => {
   routePerf.start()
 
@@ -248,6 +260,19 @@ router.beforeEach((to) => {
   if (isPublic && hasValidSession && (to.path === '/login' || to.path === '/register')) {
     return { path: '/workspace/home' }
   }
+
+  // Feature-flag gate: block direct URL access to flagged routes when the flag
+  // is disabled. The store is read synchronously from localStorage on first
+  // access so the guard works correctly on hard refresh before App.vue mounts.
+  const requiredFlag = to.meta.requiresFlag
+  if (requiredFlag !== undefined) {
+    const featureFlags = useFeatureFlagStore()
+    // Restore from localStorage in case App.vue hasn't mounted yet (direct nav).
+    featureFlags.restore()
+    if (!featureFlags.isEnabled(requiredFlag)) {
+      return { path: '/workspace/home' }
+    }
+  }
 })
 
 router.afterEach(() => {

frontend/taskdeck-web/src/tests/router/featureFlagGuard.spec.ts

@@ -0,0 +1,129 @@
+/**
+ * Tests for the feature-flag route guard logic (issue #524).
+ *
+ * The guard in router/index.ts reads `to.meta.requiresFlag` and redirects to
+ * /workspace/home when the flag is disabled. These tests exercise the
+ * featureFlagStore behaviour that the guard depends on, and verify the guard's
+ * decision table directly via a simulated meta object — without needing a full
+ * vue-router instance.
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+import { useFeatureFlagStore } from '../../store/featureFlagStore'
+import type { FeatureFlags } from '../../types/feature-flags'
+
+// ─── helper that mirrors the guard's decision logic ───────────────────────────
+function guardDecision(
+  meta: { requiresFlag?: keyof FeatureFlags },
+  store: ReturnType<typeof useFeatureFlagStore>,
+): { path: string } | undefined {
+  const requiredFlag = meta.requiresFlag
+  if (requiredFlag !== undefined) {
+    store.restore()
+    if (!store.isEnabled(requiredFlag)) {
+      return { path: '/workspace/home' }
+    }
+  }
+  return undefined // allow navigation
+}
+
+// ─── routes that are gated by feature flags (mirrors router/index.ts) ─────────
+const FLAGGED_ROUTES: { path: string; flag: keyof FeatureFlags }[] = [
+  { path: '/workspace/activity', flag: 'newActivity' },
+  { path: '/workspace/activity/board/123', flag: 'newActivity' },
+  { path: '/workspace/activity/entity/task/456', flag: 'newActivity' },
+  { path: '/workspace/activity/user', flag: 'newActivity' },
+  { path: '/workspace/automations/queue', flag: 'newAutomation' },
+  { path: '/workspace/review', flag: 'newAutomation' },
+  { path: '/workspace/automations/chat', flag: 'newAutomation' },
+  { path: '/workspace/ops/cli', flag: 'newOps' },
+  { path: '/workspace/ops/endpoints', flag: 'newOps' },
+  { path: '/workspace/ops/logs', flag: 'newOps' },
+  { path: '/workspace/settings/profile', flag: 'newAuth' },
+  { path: '/workspace/settings/access', flag: 'newAccess' },
+  { path: '/workspace/archive', flag: 'newArchive' },
+]
+
+describe('feature-flag route guard (#524)', () => {
+  let store: ReturnType<typeof useFeatureFlagStore>
+
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    localStorage.clear()
+    store = useFeatureFlagStore()
+  })
+
+  describe('routes without a flag requirement', () => {
+    it('allows navigation when meta.requiresFlag is undefined', () => {
+      expect(guardDecision({}, store)).toBeUndefined()
+    })
+  })
+
+  describe('routes with a flag requirement — flag enabled', () => {
+    it.each(FLAGGED_ROUTES)(
+      'allows $path when $flag is enabled',
+      ({ path: _path, flag }) => {
+        store.setFlag(flag, true)
+        expect(guardDecision({ requiresFlag: flag }, store)).toBeUndefined()
+      },
+    )
+  })
+
+  describe('routes with a flag requirement — flag disabled', () => {
+    it.each(FLAGGED_ROUTES)(
+      'redirects $path to /workspace/home when $flag is disabled',
+      ({ path: _path, flag }) => {
+        store.setFlag(flag, false)
+        expect(guardDecision({ requiresFlag: flag }, store)).toEqual({
+          path: '/workspace/home',
+        })
+      },
+    )
+  })
+
+  describe('hard-refresh scenario — restore() called by guard before check', () => {
+    it('reads disabled flag from localStorage before App.vue mounts', () => {
+      // Persist a disabled flag directly to localStorage (simulating a prior session).
+      localStorage.setItem(
+        'taskdeck_feature_flags',
+        JSON.stringify({ newOps: false }),
+      )
+      // A fresh store instance starts with defaults — newOps default is false, but
+      // let's explicitly test that restore() picks up what localStorage says.
+      setActivePinia(createPinia())
+      const freshStore = useFeatureFlagStore()
+      // Guard calls restore() before isEnabled() — simulate that.
+      expect(guardDecision({ requiresFlag: 'newOps' }, freshStore)).toEqual({
+        path: '/workspace/home',
+      })
+    })
+
+    it('reads enabled flag from localStorage before App.vue mounts', () => {
+      localStorage.setItem(
+        'taskdeck_feature_flags',
+        JSON.stringify({ newActivity: true }),
+      )
+      setActivePinia(createPinia())
+      const freshStore = useFeatureFlagStore()
+      expect(guardDecision({ requiresFlag: 'newActivity' }, freshStore)).toBeUndefined()
+    })
+  })
+
+  describe('guard coverage — all flagged routes have a flag entry', () => {
+    it('FLAGGED_ROUTES list is non-empty', () => {
+      expect(FLAGGED_ROUTES.length).toBeGreaterThan(0)
+    })
+
+    it('every route in FLAGGED_ROUTES references a valid FeatureFlags key', () => {
+      // If a key is invalid, TypeScript would have already caught it, but this
+      // runtime check guards against future key renames at the type level.
+      const validFlags = [
+        'newShell', 'newAuth', 'newAccess', 'newActivity',
+        'newOps', 'newAutomation', 'newArchive',
+      ] as const
+      for (const { flag } of FLAGGED_ROUTES) {
+        expect(validFlags).toContain(flag)
+      }
+    })
+  })
+})

frontend/taskdeck-web/tests/e2e/support/authSession.ts

@@ -49,6 +49,16 @@ export async function attachSessionToPage(page: Page, auth: AuthResult): Promise
   await page.addInitScript((initPayload: { token: string; session: { userId: string; username: string; email: string } }) => {
     localStorage.setItem('taskdeck_token', initPayload.token)
     localStorage.setItem('taskdeck_session', JSON.stringify(initPayload.session))
+    // Enable all feature flags so E2E tests can reach gated routes
+    localStorage.setItem('taskdeck_feature_flags', JSON.stringify({
+      newShell: true,
+      newAuth: true,
+      newAccess: true,
+      newActivity: true,
+      newOps: true,
+      newAutomation: true,
+      newArchive: true,
+    }))
   }, payload)
 }