fix(licensing): rename variant values to skipper/admiral and store resolved type (#379)

Rename internal variant values from 'personal'/'team' to 'skipper'/'admiral',
aligning code with user-facing tier names. Variant type is now resolved once
at activation/validation and stored in DB via license_variant_type, instead
of string-matching the Lemon Squeezy variant_name on every read. Also captures
variant_id for future lookups. Pre-existing installs auto-migrate on first
getVariant() call.

backend/src/__tests__/auth.test.ts

@@ -100,7 +100,7 @@ describe('POST /api/system/console-token', () => {
   beforeAll(async () => {
     const { LicenseService } = await import('../services/LicenseService');
     vi.spyOn(LicenseService.getInstance(), 'getTier').mockReturnValue('paid');
-    vi.spyOn(LicenseService.getInstance(), 'getVariant').mockReturnValue('team');
+    vi.spyOn(LicenseService.getInstance(), 'getVariant').mockReturnValue('admiral');
   });
 
   afterAll(() => {

backend/src/__tests__/distributed-license.test.ts

@@ -41,7 +41,7 @@ describe('authMiddleware - distributed license headers', () => {
       .get(PAID_ROUTE)
       .set('Authorization', `Bearer ${token}`)
       .set('x-sencho-tier', 'paid')
-      .set('x-sencho-variant', 'personal');
+      .set('x-sencho-variant', 'skipper');
 
     // Should NOT get 403 PAID_REQUIRED; the proxy tier assertion grants access
     expect(res.status).not.toBe(403);
@@ -54,7 +54,7 @@ describe('authMiddleware - distributed license headers', () => {
       .get(PAID_ROUTE)
       .set('Authorization', `Bearer ${token}`)
       .set('x-sencho-tier', 'paid')
-      .set('x-sencho-variant', 'team');
+      .set('x-sencho-variant', 'admiral');
 
     // Local license is community in test env → should get 403
     expect(res.status).toBe(403);
@@ -125,24 +125,24 @@ describe('requirePaid - distributed license', () => {
 // ─── requireAdmiral guard ───────────────────────────────────────────────────
 
 describe('requireAdmiral - distributed license', () => {
-  it('allows access when proxy asserts paid tier with team variant', async () => {
+  it('allows access when proxy asserts paid tier with admiral variant', async () => {
     const token = signToken({ scope: 'node_proxy' });
     const res = await request(app)
       .get(ADMIRAL_ROUTE)
       .set('Authorization', `Bearer ${token}`)
       .set('x-sencho-tier', 'paid')
-      .set('x-sencho-variant', 'team');
+      .set('x-sencho-variant', 'admiral');
 
     expect(res.status).not.toBe(403);
   });
 
-  it('blocks when proxy asserts paid tier with personal variant', async () => {
+  it('blocks when proxy asserts paid tier with skipper variant', async () => {
     const token = signToken({ scope: 'node_proxy' });
     const res = await request(app)
       .get(ADMIRAL_ROUTE)
       .set('Authorization', `Bearer ${token}`)
       .set('x-sencho-tier', 'paid')
-      .set('x-sencho-variant', 'personal');
+      .set('x-sencho-variant', 'skipper');
 
     expect(res.status).toBe(403);
     expect(res.body.code).toBe('ADMIRAL_REQUIRED');
@@ -181,7 +181,7 @@ describe('Security - tier header injection', () => {
       .get(ADMIRAL_ROUTE)
       .set('Authorization', `Bearer ${token}`)
       .set('x-sencho-tier', 'paid')
-      .set('x-sencho-variant', 'team');
+      .set('x-sencho-variant', 'admiral');
 
     // User session → tier headers ignored → local community tier → 403
     expect(res.status).toBe(403);
@@ -191,7 +191,7 @@ describe('Security - tier header injection', () => {
     const res = await request(app)
       .get(PAID_ROUTE)
       .set('x-sencho-tier', 'paid')
-      .set('x-sencho-variant', 'team');
+      .set('x-sencho-variant', 'admiral');
 
     expect(res.status).toBe(401);
   });

backend/src/__tests__/license-service.test.ts

@@ -26,6 +26,7 @@ function setLicenseState(overrides: Record<string, string>) {
     'license_status', 'license_key', 'license_valid_until',
     'license_last_validated', 'license_customer_name',
     'license_product_name', 'license_variant_name',
+    'license_variant_type', 'license_variant_id',
     'billing_portal_url', 'billing_portal_expires',
   ];
   for (const key of keys) {
@@ -37,9 +38,9 @@ function setLicenseState(overrides: Record<string, string>) {
 }
 
 describe('LicenseService.getVariant()', () => {
-  it('returns "personal" for trial licenses', () => {
+  it('returns "skipper" for trial licenses', () => {
     setLicenseState({ license_status: 'trial' });
-    expect(svc.getVariant()).toBe('personal');
+    expect(svc.getVariant()).toBe('skipper');
   });
 
   it('returns null when no variant name is stored', () => {
@@ -47,39 +48,51 @@ describe('LicenseService.getVariant()', () => {
     expect(svc.getVariant()).toBeNull();
   });
 
-  it('maps "Team" variant name to "team"', () => {
+  it('reads pre-resolved variant type from DB (admiral)', () => {
+    setLicenseState({ license_status: 'active', license_variant_type: 'admiral' });
+    expect(svc.getVariant()).toBe('admiral');
+  });
+
+  it('reads pre-resolved variant type from DB (skipper)', () => {
+    setLicenseState({ license_status: 'active', license_variant_type: 'skipper' });
+    expect(svc.getVariant()).toBe('skipper');
+  });
+
+  it('falls back to name resolution and persists type (Team -> admiral)', () => {
     setLicenseState({ license_status: 'active', license_variant_name: 'Team' });
-    expect(svc.getVariant()).toBe('team');
+    expect(svc.getVariant()).toBe('admiral');
+    expect(DatabaseService.getInstance().getSystemState('license_variant_type')).toBe('admiral');
   });
 
-  it('maps "Personal" variant name to "personal"', () => {
+  it('falls back to name resolution and persists type (Personal -> skipper)', () => {
     setLicenseState({ license_status: 'active', license_variant_name: 'Personal' });
-    expect(svc.getVariant()).toBe('personal');
+    expect(svc.getVariant()).toBe('skipper');
+    expect(DatabaseService.getInstance().getSystemState('license_variant_type')).toBe('skipper');
   });
 
-  it('maps "Admiral" variant name to "team"', () => {
+  it('maps "Admiral" variant name to "admiral"', () => {
     setLicenseState({ license_status: 'active', license_variant_name: 'Admiral' });
-    expect(svc.getVariant()).toBe('team');
+    expect(svc.getVariant()).toBe('admiral');
   });
 
-  it('maps "Admiral Lifetime" variant name to "team"', () => {
+  it('maps "Admiral Lifetime" variant name to "admiral"', () => {
     setLicenseState({ license_status: 'active', license_variant_name: 'Admiral Lifetime' });
-    expect(svc.getVariant()).toBe('team');
+    expect(svc.getVariant()).toBe('admiral');
   });
 
-  it('maps "Skipper" variant name to "personal"', () => {
+  it('maps "Skipper" variant name to "skipper"', () => {
     setLicenseState({ license_status: 'active', license_variant_name: 'Skipper' });
-    expect(svc.getVariant()).toBe('personal');
+    expect(svc.getVariant()).toBe('skipper');
   });
 
-  it('maps "Skipper Lifetime" variant name to "personal"', () => {
+  it('maps "Skipper Lifetime" variant name to "skipper"', () => {
     setLicenseState({ license_status: 'active', license_variant_name: 'Skipper Lifetime' });
-    expect(svc.getVariant()).toBe('personal');
+    expect(svc.getVariant()).toBe('skipper');
   });
 
-  it('defaults unknown variant names to "personal"', () => {
+  it('defaults unknown variant names to "skipper"', () => {
     setLicenseState({ license_status: 'active', license_variant_name: 'Unknown Variant' });
-    expect(svc.getVariant()).toBe('personal');
+    expect(svc.getVariant()).toBe('skipper');
   });
 });
 
@@ -203,7 +216,7 @@ describe('LicenseService.getLicenseInfo() - full scenarios', () => {
     const info = svc.getLicenseInfo();
     expect(info.tier).toBe('paid');
     expect(info.status).toBe('active');
-    expect(info.variant).toBe('team');
+    expect(info.variant).toBe('admiral');
     expect(info.isLifetime).toBe(true);
     expect(info.trialDaysRemaining).toBeNull();
     expect(info.customerName).toBe('Test User');
@@ -226,7 +239,7 @@ describe('LicenseService.getLicenseInfo() - full scenarios', () => {
     const info = svc.getLicenseInfo();
     expect(info.tier).toBe('paid');
     expect(info.status).toBe('active');
-    expect(info.variant).toBe('personal');
+    expect(info.variant).toBe('skipper');
     expect(info.isLifetime).toBe(false);
     expect(info.trialDaysRemaining).toBeNull();
     expect(info.customerName).toBe('Another User');

backend/src/__tests__/scheduler-service.test.ts

@@ -29,7 +29,7 @@ const {
   mockInsertSnapshotFiles: vi.fn(),
   mockClearStackUpdateStatus: vi.fn(),
   mockGetTier: vi.fn().mockReturnValue('paid'),
-  mockGetVariant: vi.fn().mockReturnValue('team'),
+  mockGetVariant: vi.fn().mockReturnValue('admiral'),
   mockGetContainersByStack: vi.fn().mockResolvedValue([]),
   mockRestartContainer: vi.fn().mockResolvedValue(undefined),
   mockPruneSystem: vi.fn().mockResolvedValue({ success: true, reclaimedBytes: 0 }),
@@ -198,7 +198,7 @@ describe('SchedulerService - license gating', () => {
 
   it('allows all actions for admiral (pro + team)', async () => {
     mockGetTier.mockReturnValue('paid');
-    mockGetVariant.mockReturnValue('team');
+    mockGetVariant.mockReturnValue('admiral');
     mockGetDueScheduledTasks.mockReturnValue([makeTask({ action: 'restart' })]);
     mockGetContainersByStack.mockResolvedValue([{ Id: 'c1', Service: 'web' }]);
 
@@ -215,7 +215,7 @@ describe('SchedulerService - license gating', () => {
 describe('SchedulerService - concurrent task prevention', () => {
   it('does not execute a task that is already in runningTasks', async () => {
     mockGetTier.mockReturnValue('paid');
-    mockGetVariant.mockReturnValue('team');
+    mockGetVariant.mockReturnValue('admiral');
     mockGetDueScheduledTasks.mockReturnValue([{
       id: 42,
       name: 'running-task',
@@ -240,7 +240,7 @@ describe('SchedulerService - concurrent task prevention', () => {
 
   it('removes task from runningTasks after completion', async () => {
     mockGetTier.mockReturnValue('paid');
-    mockGetVariant.mockReturnValue('team');
+    mockGetVariant.mockReturnValue('admiral');
     mockGetContainersByStack.mockResolvedValue([{ Id: 'c1', Service: 'web' }]);
 
     const svc = SchedulerService.getInstance();
@@ -612,7 +612,7 @@ describe('SchedulerService - error handling', () => {
 describe('SchedulerService - cleanup', () => {
   it('calls cleanupOldTaskRuns(30) on every tick', async () => {
     mockGetTier.mockReturnValue('paid');
-    mockGetVariant.mockReturnValue('team');
+    mockGetVariant.mockReturnValue('admiral');
     mockGetDueScheduledTasks.mockReturnValue([]);
 
     const svc = SchedulerService.getInstance();

backend/src/index.ts

@@ -861,7 +861,7 @@ const requireAdmiral = (req: Request, res: Response): boolean => {
     res.status(403).json({ error: 'This feature requires a Skipper or Admiral license.', code: 'PAID_REQUIRED' });
     return false;
   }
-  if (variant !== 'team') {
+  if (variant !== 'admiral') {
     res.status(403).json({ error: 'This feature requires a Sencho Admiral license.', code: 'ADMIRAL_REQUIRED' });
     return false;
   }
@@ -936,7 +936,7 @@ function checkPermission(
 
   // Scoped assignments only apply when a resource is specified and license is Admiral
   if (!resourceType || !resourceId) return false;
-  if (LicenseService.getInstance().getVariant() !== 'team') return false;
+  if (LicenseService.getInstance().getVariant() !== 'admiral') return false;
 
   const assignments = DatabaseService.getInstance().getRoleAssignments(req.user.userId, resourceType, resourceId);
   for (const assignment of assignments) {
@@ -2327,7 +2327,7 @@ app.get('/api/permissions/me', authMiddleware, (req: Request, res: Response): vo
       globalRole,
       globalPermissions,
       scopedPermissions,
-      isAdmiral: LicenseService.getInstance().getVariant() === 'team',
+      isAdmiral: LicenseService.getInstance().getVariant() === 'admiral',
     });
   } catch (error) {
     console.error('[Permissions] Error:', error);
@@ -2628,7 +2628,7 @@ server.on('upgrade', async (req, socket, head) => {
       }
       // Admiral license gate: host console requires Admiral (paid + team variant)
       const ls = LicenseService.getInstance();
-      if (ls.getTier() !== 'paid' || ls.getVariant() !== 'team') {
+      if (ls.getTier() !== 'paid' || ls.getVariant() !== 'admiral') {
         socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
         socket.destroy();
         return;
@@ -4382,7 +4382,7 @@ app.get('/api/scheduled-tasks', (req: Request, res: Response): void => {
     let tasks = DatabaseService.getInstance().getScheduledTasks();
     // Skipper users only see 'update' tasks; Admiral sees all
     const ls = LicenseService.getInstance();
-    if (ls.getVariant() !== 'team') {
+    if (ls.getVariant() !== 'admiral') {
       tasks = tasks.filter(t => t.action === 'update');
     }
     res.json(tasks);

backend/src/services/LicenseService.ts

@@ -5,10 +5,10 @@ import { DatabaseService } from './DatabaseService';
 export type LicenseTier = 'community' | 'paid';
 export type LicenseStatus = 'community' | 'trial' | 'active' | 'expired' | 'disabled';
 
-export type LicenseVariant = 'personal' | 'team' | null;
+export type LicenseVariant = 'skipper' | 'admiral' | null;
 
 const VALID_TIERS: readonly string[] = ['community', 'paid'] satisfies readonly LicenseTier[];
-const VALID_VARIANTS: readonly string[] = ['personal', 'team'] satisfies readonly LicenseVariant[];
+const VALID_VARIANTS: readonly string[] = ['skipper', 'admiral'] satisfies readonly LicenseVariant[];
 
 export function isLicenseTier(value: unknown): value is LicenseTier {
     return typeof value === 'string' && (VALID_TIERS as readonly string[]).includes(value);
@@ -43,8 +43,8 @@ export interface SeatLimits {
 }
 
 const SEAT_LIMITS: Record<string, SeatLimits> = {
-    personal: { maxAdmins: 1, maxViewers: 3 },
-    team: { maxAdmins: null, maxViewers: null },
+    skipper: { maxAdmins: 1, maxViewers: 3 },
+    admiral: { maxAdmins: null, maxViewers: null },
 };
 
 interface LemonSqueezyActivationResponse {
@@ -194,21 +194,49 @@ export class LicenseService {
     }
 
     /**
-     * Get the license variant (personal or team) from stored metadata.
-     * Trial licenses default to "personal"; Admiral features require an Admiral license.
-     * Maps Lemon Squeezy variant names (which may use brand names like "Admiral"
-     * or "Skipper") to the internal 'team' or 'personal' values.
+     * Resolve a Lemon Squeezy variant name string to the internal variant type.
+     * Handles legacy names ("Team", "Personal") and current names ("Admiral", "Skipper").
+     */
+    private resolveVariantType(variantName: string): 'skipper' | 'admiral' {
+        const lower = variantName.toLowerCase();
+        if (lower.includes('team') || lower.includes('admiral')) return 'admiral';
+        if (lower.includes('personal') || lower.includes('skipper')) return 'skipper';
+        return 'skipper';
+    }
+
+    /** Persist variant metadata from Lemon Squeezy response to DB. */
+    private storeVariantMeta(db: DatabaseService, meta: { variant_name?: string; variant_id?: number }): void {
+        if (meta.variant_name) {
+            db.setSystemState('license_variant_name', meta.variant_name);
+            db.setSystemState('license_variant_type', this.resolveVariantType(meta.variant_name));
+        }
+        if (meta.variant_id) {
+            db.setSystemState('license_variant_id', String(meta.variant_id));
+        }
+    }
+
+    /**
+     * Get the license variant (skipper or admiral) from stored metadata.
+     * Trial licenses default to "skipper"; Admiral features require an Admiral license.
+     * Reads the pre-resolved `license_variant_type` from DB. Falls back to name-based
+     * resolution for pre-existing installs, then persists the result so the fallback
+     * only runs once.
      */
     public getVariant(): LicenseVariant {
         const db = DatabaseService.getInstance();
         const status = db.getSystemState('license_status');
-        if (status === 'trial') return 'personal';
+        if (status === 'trial') return 'skipper';
+
+        // Primary path: read the pre-resolved type stored at activation/validation
+        const storedType = db.getSystemState('license_variant_type');
+        if (isLicenseVariant(storedType)) return storedType;
+
+        // Backward compat: resolve from variant name for pre-existing installs
         const variantName = db.getSystemState('license_variant_name');
         if (!variantName) return null;
-        const lower = variantName.toLowerCase();
-        if (lower.includes('team') || lower.includes('admiral')) return 'team';
-        if (lower.includes('personal') || lower.includes('skipper')) return 'personal';
-        return 'personal'; // default activated licenses to personal
+        const resolved = this.resolveVariantType(variantName);
+        db.setSystemState('license_variant_type', resolved);
+        return resolved;
     }
 
     /**
@@ -217,7 +245,7 @@ export class LicenseService {
     public getSeatLimits(): SeatLimits {
         const variant = this.getVariant();
         if (!variant) return { maxAdmins: 1, maxViewers: 0 }; // community
-        return SEAT_LIMITS[variant] || SEAT_LIMITS.personal;
+        return SEAT_LIMITS[variant] || SEAT_LIMITS.skipper;
     }
 
     /**
@@ -295,8 +323,8 @@ export class LicenseService {
             if (data.meta?.product_name) {
                 db.setSystemState('license_product_name', data.meta.product_name);
             }
-            if (data.meta?.variant_name) {
-                db.setSystemState('license_variant_name', data.meta.variant_name);
+            if (data.meta) {
+                this.storeVariantMeta(db, data.meta);
             }
             if (data.meta?.customer_id) {
                 db.setSystemState('customer_id', String(data.meta.customer_id));
@@ -353,6 +381,8 @@ export class LicenseService {
             'license_customer_name',
             'license_product_name',
             'license_variant_name',
+            'license_variant_type',
+            'license_variant_id',
             'subscription_id',
             'customer_id',
             'customer_portal_url',
@@ -428,8 +458,8 @@ export class LicenseService {
             if (data.meta?.product_name) {
                 db.setSystemState('license_product_name', data.meta.product_name);
             }
-            if (data.meta?.variant_name) {
-                db.setSystemState('license_variant_name', data.meta.variant_name);
+            if (data.meta) {
+                this.storeVariantMeta(db, data.meta);
             }
             if (data.meta?.customer_id && !db.getSystemState('customer_id')) {
                 db.setSystemState('customer_id', String(data.meta.customer_id));

backend/src/services/SchedulerService.ts

@@ -50,7 +50,7 @@ export class SchedulerService {
         try {
             const ls = LicenseService.getInstance();
             const isPaid = ls.getTier() === 'paid';
-            const isAdmiral = isPaid && ls.getVariant() === 'team';
+            const isAdmiral = isPaid && ls.getVariant() === 'admiral';
             if (!isPaid) return; // No scheduled tasks for unpaid tiers
 
             const db = DatabaseService.getInstance();