Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

46.2 KB
Raw Blame
import { describe, it, expect } from 'vitest';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
  NAV_COMMANDS,
  NAV_FEATURE_IDS,
  SECTION_FEATURE,
  getNavAliasMap,
  getNavCommandForPath,
  getNavPageForPath,
  getNavSectionForPath,
  getSectionNavGroups,
  getSectionNavTabForPath,
  getSectionNavTabs,
  resolveNavCommand,
} from './navManifest.js';
import { INSTANCE_FEATURE_IDS } from './instanceFeatureRegistry.js';
import { PORTOS_APP_ID } from './appIdentity.js';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, '..', '..');
const SETTINGS_PAGE = path.join(REPO_ROOT, 'client/src/pages/Settings.jsx');

// Maps URL prefix → how to extract the page's own tab set from its source. Each
// page validates the :tab/:section param against this list, so the nav manifest
// must agree. Two source shapes are left:
//   kind 'section' — the header exports a generated `TABS` list sourced from
//                   the nav manifest; `section` identifies the manifest group.
//   kind 'switch' — the page has no tab array; its tabs are a `switch (<switchVar>)`
//                   render-dispatch plus the `{ <switchVar> = '<id>' }` destructuring
//                   default (POST). Reading the switch directly means the guard
//                   can't drift from a parallel constant; inner subtab branches
//                   (`if (subtab === 'x')`) aren't cases, so drill-downs are excluded.
// Every OTHER tabbed page now derives its tab list from `getPageNavTabs(group)`
// (#6365, #6383), so the manifest is the one registry and there is nothing left
// to scrape — each page's own test file asserts its presentation map covers
// every manifest tab in its `tabGroup` instead.
const TABBED_PAGES = [
  { prefix: '/settings', section: 'Settings', file: 'client/src/components/settings/SettingsTabsHeader.jsx', kind: 'section', constName: 'TABS' },
  { prefix: '/models', section: 'Models', file: 'client/src/components/models/ModelsTabsHeader.jsx', kind: 'section', constName: 'TABS' },
  // POST's morse tab has routed `:mode` sub-pages (/post/morse/copy|send) and the
  // memory tab has the Elements study sub-page (/post/memory/elements) plus its
  // own routed practice modes — none are top-level switch cases, so declare their
  // sources so the guard covers them in both directions (nav ↔ real sub-page).
  // Adding an entry flows automatically. `parent` may itself be a multi-segment
  // path, which is how the two-deep Elements modes are declared.
  { prefix: '/post', file: 'client/src/components/meatspace/tabs/PostTab.jsx', kind: 'switch', switchVar: 'tab',
    nestedIdSources: [
      { parent: 'morse', file: 'client/src/components/meatspace/post/MorseTrainer.jsx', constName: 'MODES' },
      { parent: 'memory', file: 'client/src/components/meatspace/tabs/PostTab.jsx', constName: 'MEMORY_SUBROUTES' },
      { parent: 'memory/elements', file: 'client/src/components/meatspace/post/ElementsSong.jsx', constName: 'PRACTICE_MODES' },
      { parent: 'wordplay', file: 'client/src/components/meatspace/post/WordplayTrainer.jsx', constName: 'GAME_MODES' },
      { parent: 'rhetoric', file: 'client/src/components/meatspace/post/RhetoricTrainer.jsx', constName: 'RHETORIC_MODES' },
      { parent: 'progress', file: 'client/src/components/meatspace/post/PostProgress.jsx', constName: 'PROGRESS_SUBROUTES' },
    ] },
];

// Pull the inner text of `export const <constName> = [ … ];` (requiring `export`
// also asserts the constant stays importable — a forgotten `export` fails loudly).
// The terminator is line-anchored (`^];`) so a NESTED array literal can't close the
// block early and silently truncate the guard to the entries above it; a nested
// literal formatted with its own `];` at column 0 still would, but no source does.
function extractConstArrayBlock(src, constName) {
  const block = src.match(new RegExp(`export const ${constName}\\s*=\\s*\\[([\\s\\S]*?)^\\];`, 'm'));
  if (!block) throw new Error(`No exported ${constName} array found`);
  return block[1];
}

// The `case '…':` labels of a `switch (<switchVar>) { … }` block. Assumes the
// file's `switch (<switchVar>)` is the only one (cases are read to EOF); a second
// switch would loudly fold its cases in rather than fail silently. The case regex
// is line-anchored (`^\s*case`, multiline) so a `case '…':` inside a comment
// (`// case 'x':`) or string can't be counted as a real renderer case.
function extractSwitchCases(src, switchVar) {
  const block = src.match(new RegExp(`switch\\s*\\(\\s*${switchVar}\\s*\\)\\s*\\{([\\s\\S]*)`));
  if (!block) throw new Error(`No switch (${switchVar}) found`);
  return [...block[1].matchAll(/^\s*case\s+['"]([^'"]+)['"]\s*:/gm)].map((m) => m[1]);
}

// The tab ids a `switch (<switchVar>)` render-dispatch serves, plus the
// destructuring default (`{ <switchVar> = '<id>' }`) — the tab with no explicit case.
function extractSwitchTabs(src, switchVar) {
  const def = src.match(new RegExp(`\\b${switchVar}\\s*=\\s*['"]([^'"]+)['"]`));
  if (!def) throw new Error(`No destructuring default for "${switchVar}" found`);
  return [def[1], ...extractSwitchCases(src, switchVar)];
}

// The `id:` values of an exported `[{ id: '<slug>', … }]` const array, used to
// pull routed sub-page ids (e.g. morse's copy/send MODES) out of another file.
function extractConstIds(filePath, constName) {
  const src = fs.readFileSync(filePath, 'utf8');
  const block = extractConstArrayBlock(src, constName);
  return [...block.matchAll(/id:\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
}

// The set of absolute tab paths a page serves under its own prefix.
function extractTabPaths(filePath, { kind, switchVar, prefix, section, nestedIdSources }) {
  const nested = (nestedIdSources || []).flatMap(({ parent, file, constName: c }) =>
    extractConstIds(path.join(REPO_ROOT, file), c).map((id) => `${prefix}/${parent}/${id}`));
  if (kind === 'switch') {
    const src = fs.readFileSync(filePath, 'utf8');
    return [...extractSwitchTabs(src, switchVar).map((id) => `${prefix}/${id}`), ...nested];
  }
  return [...getSectionNavTabs(section).map((tab) => tab.to), ...nested];
}

describe('navManifest — shape invariants', () => {
  it('every command has id, path, label, section', () => {
    for (const cmd of NAV_COMMANDS) {
      expect(cmd.id).toBeTruthy();
      expect(cmd.path).toMatch(/^\//);
      expect(cmd.label).toBeTruthy();
      expect(cmd.section).toBeTruthy();
    }
  });

  it('ids are unique', () => {
    const ids = NAV_COMMANDS.map((c) => c.id);
    expect(new Set(ids).size).toBe(ids.length);
  });

  it('every section is one of the approved sidebar group labels', () => {
    const ALLOWED_SECTIONS = new Set([
      'Main', 'Apps', 'Brain', 'Calendar', 'Chief of Staff', 'Comms', 'Create',
      'Dev Tools', 'Goals', 'Health', 'Models', 'Settings', 'Identity', 'POST',
    ]);
    const bad = NAV_COMMANDS.filter((c) => !ALLOWED_SECTIONS.has(c.section));
    expect(bad.map((c) => `${c.id}:${c.section}`)).toEqual([]);
  });

  it('every parentPath references a declared command path', () => {
    const commandPaths = new Set(NAV_COMMANDS.map((c) => c.path));
    const parentPaths = NAV_COMMANDS.filter((c) => c.parentPath).map((c) => c.parentPath);
    expect(parentPaths.length).toBeGreaterThan(0);
    expect(parentPaths.every((p) => commandPaths.has(p))).toBe(true);

    const casting = NAV_COMMANDS.find((c) => c.id === 'nav.create.casting');
    const environments = NAV_COMMANDS.find((c) => c.id === 'nav.create.environments');
    const objects = NAV_COMMANDS.find((c) => c.id === 'nav.create.objects');
    expect(casting?.parentPath).toBe('/catalog');
    expect(environments?.parentPath).toBe('/catalog');
    expect(objects?.parentPath).toBe('/catalog');
  });
});

describe('navManifest — persistent mind dashboard', () => {
  it.each(['mind-tools', 'persistent-mind-tools', 'tools-access'])(
    'opens the embedded tools panel for the %s alias',
    (alias) => {
      expect(resolveNavCommand(alias)?.path).toBe('/cos/mind?panel=tools');
    },
  );

  it('maps both former Mind Tools routes onto the embedded tools panel', () => {
    const tools = NAV_COMMANDS.find((command) => command.id === 'nav.cos.mind-tools');
    expect(tools?.previousPaths).toEqual(['/cos/tools', '/cos/mind/tools']);
  });
});

describe('nav contract — generated section child navigation', () => {
  const headers = [
    ['Settings', 'client/src/components/settings/SettingsTabsHeader.jsx'],
    ['Models', 'client/src/components/models/ModelsTabsHeader.jsx'],
  ];

  it.each(headers)('%s header reads its tabs from navManifest', (section, file) => {
    const source = fs.readFileSync(path.join(REPO_ROOT, file), 'utf8');
    expect(source).toMatch(new RegExp(`getSectionNavTabs\\(['"]${section}['"]\\)`));
  });

  it('keeps moved Providers and Usage destinations in the Models child nav', () => {
    expect(getSectionNavTabs('Models').filter((tab) => ['providers', 'usage'].includes(tab.id))).toEqual([
      { id: 'providers', label: 'Providers', to: '/ai/presets', navGroup: 'Connect' },
      { id: 'usage', label: 'Usage', to: '/devtools/usage', navGroup: 'Operate' },
    ]);
    expect(getSectionNavTabs('Settings').some((tab) => tab.id === 'providers')).toBe(false);
  });

  it('keeps Models groups and destinations in the design order', () => {
    expect(getSectionNavGroups('Models').map(({ label, tabs }) => [label, tabs.map((tab) => tab.label)])).toEqual([
      ['Connect', ['AI Services', 'Fallbacks', 'Harnesses', 'Providers', 'Runtimes']],
      ['Evaluate', ['Comparison', 'Performance', 'Playground']],
      ['Library', ['3D', 'Embeddings', 'LoRAs', 'Media', 'Model Library']],
      ['Operate', ['Quota Burn', 'Status', 'Subscriptions', 'Usage']],
      ['Policies', ['Abuse Guard', 'Code Reviewers', 'Decision Classifiers']],
    ]);
  });

  it('resolves a promoted drill-down as itself instead of its LLM parent', () => {
    expect(getSectionNavTabForPath('Models', '/models/llms/abuse')).toMatchObject({ id: 'abuse', label: 'Abuse Guard' });
    expect(getNavCommandForPath('/models/decision-classifiers/jev')).toMatchObject({ path: '/models/decision-classifiers/jev', label: 'Jev' });
    expect(getSectionNavTabForPath('Models', '/models/training/dataset-abc')).toBeUndefined();
  });

  it.each([
    ['/ai/presets', 'Models'],
    ['/ai/presets/example-provider', 'Models'],
    ['/ai/presets/new', 'Models'],
    ['/devtools/usage', 'Models'],
    ['/models/llms/abuse', 'Models'],
    ['/models/llms-runtimes', 'Models'],
    ['/settings/general', 'Settings'],
    ['/prompts', 'Settings'],
  ])('resolves %s to the %s section', (pathname, section) => {
    expect(getNavSectionForPath(pathname)).toBe(section);
  });
});

// Feature gating hides a page from the ⌘K palette and the sidebar. A typo in a
// `feature` tag would silently gate on a flag nothing can ever turn on, hiding
// the page on every install with no other symptom.
// Runtimes (#7414) was the LLMs page's default VIEW before it became a sibling
// tab. Every way a user reaches it — the tab bar, ⌘K, voice, and the bookmark
// they still hold on the old pill — has to keep landing on the same page.
describe('nav contract — Models → Runtimes', () => {
  it('is a Models section tab at its canonical path', () => {
    expect(getSectionNavTabs('Models')).toContainEqual({ id: 'llms-runtimes', label: 'Runtimes', to: '/models/llms-runtimes', navGroup: 'Connect' });
  });

  it.each(['runtimes', 'llm runtimes', 'local runtimes', 'llama server'])(
    'resolves the spoken name %j to the Runtimes page',
    (spoken) => {
      expect(resolveNavCommand(spoken)?.path).toBe('/models/llms-runtimes');
    },
  );

  // Splitting the page must not steal the catalog's own names: both surfaces
  // start Ollama, so "ollama" staying on LLMs is a decision, not an accident.
  it.each(['llms', 'ollama', 'lm studio'])('leaves %j on the LLMs catalog page', (spoken) => {
    expect(resolveNavCommand(spoken)?.path).toBe('/models/llms');
  });

  // Two pages in this section are about "runtimes". Before #7414 a bare
  // "runtimes" landed on the image-to-3D page by suffix match, because nothing
  // else claimed the word; the local model servers are what a user asking for
  // runtimes means, so the exact alias wins it now. The 3D page keeps every
  // qualified form — losing those WOULD be a regression, and the fuzzy matcher
  // makes that a silent one.
  it('gives a bare "runtimes" to the model servers', () => {
    expect(resolveNavCommand('runtimes')?.path).toBe('/models/llms-runtimes');
  });

  it.each(['3d runtimes', 'image to 3d runtimes'])('keeps %j on the image-to-3D page', (spoken) => {
    expect(resolveNavCommand(spoken)?.path).toBe('/models/3d');
  });
});

// Readiness copy names the page it links to instead of repeating a breadcrumb,
// so a page move re-words every hint. A helper that silently returned null (or
// the parent's name) would put the neutral fallback wording on every card.
describe('getNavPageForPath', () => {
  it.each([
    ['/models/llms', 'Models → Model Library', 'Model Library'],
    ['/models/llms-runtimes', 'Models → Runtimes', 'Runtimes'],
    // Longest-match: a drill-down names itself, not the tab that hosts it.
    ['/models/llms/abuse', 'Models → Abuse Guard', 'Abuse Guard'],
  ])('names %s as %s', (pathname, breadcrumb, label) => {
    expect(getNavPageForPath(pathname)).toMatchObject({ breadcrumb, label, section: 'Models' });
  });

  it('returns null for a path no command declares, so callers can drop the clause', () => {
    expect(getNavPageForPath('/not-a-nav-path')).toBeNull();
    expect(getNavPageForPath(null)).toBeNull();
    expect(getNavPageForPath('/')).toBeNull();
  });
});

describe('nav contract — instance-feature gating', () => {
  it('every gated entry names a registered instance feature', () => {
    const unknown = NAV_FEATURE_IDS.filter((id) => !INSTANCE_FEATURE_IDS.includes(id));
    expect(unknown).toEqual([]);
  });

  // SECTION_FEATURE keys on the DISPLAY label, so renaming a section would
  // un-gate it silently — and every other assertion here would still pass,
  // because they filter on that same label and would simply match nothing.
  it('every SECTION_FEATURE key is a live section carrying that gate', () => {
    for (const [section, featureId] of SECTION_FEATURE) {
      const inSection = NAV_COMMANDS.filter((c) => c.section === section);
      expect(inSection.length, `no commands in section "${section}"`).toBeGreaterThan(0);
      expect(INSTANCE_FEATURE_IDS, `unregistered feature "${featureId}"`).toContain(featureId);
      expect(inSection.every((c) => c.feature === featureId)).toBe(true);
    }
  });

  it('gates the DataDog, JIRA, and GSD feature pages', () => {
    const byId = Object.fromEntries(NAV_COMMANDS.map((c) => [c.id, c.feature]));
    expect(byId['nav.devtools.datadog']).toBe('datadog');
    expect(byId['nav.devtools.jira']).toBe('jira');
    expect(byId['nav.devtools.jira-reports']).toBe('jira');
    expect(byId['nav.cos.gsd']).toBe('gsd');
  });

  it('gates the Eidoverse host page on its installed feature', () => {
    const command = NAV_COMMANDS.find((entry) => entry.id === 'nav.eidoverse');
    expect(command).toMatchObject({ path: '/eidoverse', feature: 'eidoverse' });
  });

  // Comms feature group (#40): iMessage, Signal, X and Stacker News join
  // FaceTime Audio and Beeper under the `comms` group. Nav gating stays
  // per-entry (unlike Health's whole-section SECTION_FEATURE gate) because
  // Comms holds ungated siblings — Inbox, Drafts, Contacts.
  it('gates the iMessage, Signal, X, Stacker News and Beeper pages on their own instance features', () => {
    const byId = Object.fromEntries(NAV_COMMANDS.map((c) => [c.id, c.feature]));
    expect(byId['nav.messages.imessage']).toBe('imessage');
    expect(byId['nav.messages.imessage-settings']).toBe('imessage');
    expect(byId['nav.messages.signal']).toBe('signal');
    expect(byId['nav.x']).toBe('x');
    expect(byId['nav.stacker-news']).toBe('stacker-news');
    expect(byId['nav.messages.beeper']).toBe('beeper');
    expect(byId['nav.messages.beeper-settings']).toBe('beeper');
    // Contacts spans both networks (and every other message source) so it stays
    // ungated even though it lives in the same Comms section.
    expect(byId['nav.messages.contacts']).toBeUndefined();
    expect(byId['nav.messages.inbox']).toBeUndefined();
  });

  it('gates the complete Health section and MortalLoom settings', () => {
    const byId = Object.fromEntries(NAV_COMMANDS.map((c) => [c.id, c.feature]));
    expect([...SECTION_FEATURE]).toContainEqual(['Health', 'health']);
    expect(NAV_COMMANDS.filter((c) => c.section === 'Health').every((c) => c.feature === 'health')).toBe(true);
    expect(byId['nav.settings.mortalloom']).toBe('health');
  });

  it('leaves ungated pages untagged', () => {
    const gated = NAV_COMMANDS.filter((c) => c.feature).map((c) => c.id);
    expect(gated).toContain('nav.devtools.jira');
    expect(gated).not.toContain('nav.dashboard');
    expect(gated).not.toContain('nav.devtools.flows');
  });

  // Sidebar rows now derive path, label, section and feature directly from this
  // array. The former Layout source-scrape parity guards are intentionally gone:
  // there is no second structural declaration left for them to compare.
});

describe('resolveNavCommand — fuzzy matching', () => {
  it('disambiguates security settings from the security camera monitor', () => {
    const settings = NAV_COMMANDS.find((command) => command.id === 'nav.settings.security');
    const camera = NAV_COMMANDS.find((command) => command.id === 'nav.security');

    expect(settings).toMatchObject({
      path: '/settings/security',
      label: 'Security',
    });
    expect(camera).toMatchObject({
      path: '/security',
      label: 'Security Camera',
      keywords: ['camera', 'webcam', 'microphone', 'audio level', 'feed'],
    });
    expect(resolveNavCommand('security')).toMatchObject({
      path: '/settings/security',
      command: { id: 'nav.settings.security' },
    });
    expect(resolveNavCommand('security camera')).toMatchObject({
      path: '/security',
      command: { id: 'nav.security' },
    });
  });

  it('resolves every declared alias to its owning command', () => {
    for (const command of NAV_COMMANDS) {
      for (const alias of command.aliases || []) {
        const hit = resolveNavCommand(alias);
        expect(hit?.path, alias).toBe(command.path);
        expect(hit?.command?.id, alias).toBe(command.id);
        expect(command.aliases, alias).toContain(hit?.matched);
      }
    }
  });

  it('resolves exact alias', () => {
    expect(resolveNavCommand('dashboard')?.path).toBe('/');
    expect(resolveNavCommand('tasks')?.path).toBe('/cos/tasks');
    expect(resolveNavCommand('goals')?.path).toBe('/goals/list');
  });

  it('resolves the Catalog settings phrase to the feature-local drawer', () => {
    expect(resolveNavCommand('catalog settings')?.path).toBe('/catalog?settings=1');
  });

  it('resolves every canonical System Resources section name', () => {
    expect(resolveNavCommand('system resources')?.path).toBe('/system-resources/overview');
    expect(resolveNavCommand('active queues')?.path).toBe('/system-resources/queues');
  });

  it('resolves the folded Model Resources aliases to Models → Status', () => {
    // The Dev Tools model-inventory page folded into /models/status (#4728),
    // which already answered "what is resident right now". Its aliases moved with
    // it rather than being dropped — a user who says "model resources" or
    // "downloaded models" must still land on the inventory, not nowhere.
    expect(resolveNavCommand('model resources')?.path).toBe('/models/status');
    expect(resolveNavCommand('downloaded models')?.path).toBe('/models/status');
  });

  it('resolves the moved model-management pages to their Models paths', () => {
    // Media models, LoRAs and embeddings moved out of Create and
    // Settings (#4728); retired training now lands in maintenance. Active command ids are opaque and
    // persisted, so paths prove the move actually landed.
    expect(resolveNavCommand('media models')?.path).toBe('/models/media');
    expect(resolveNavCommand('loras')?.path).toBe('/models/loras');
    expect(resolveNavCommand('lora training')?.path).toBe('/settings/data-maintenance');
    expect(resolveNavCommand('embeddings')?.path).toBe('/models/embeddings');
    expect(resolveNavCommand('prompt guard')?.path).toBe('/models/llms/abuse');
    expect(resolveNavCommand('abuse-guard')?.path).toBe('/models/llms/abuse');
  });

  it('resolves Universe Builder to the /universes index path', () => {
    // Promoted out of /media/universe-builder; renamed to /universes when the
    // list/table index landed (command id stays nav.create.universe-builder).
    // Nav alias must follow.
    const hit = resolveNavCommand('world builder');
    expect(hit?.path).toBe('/universes');
    expect(hit?.command?.id).toBe('nav.create.universe-builder');
  });

  it('resolves bare "health" to /cos/health (CoS owns the alias; meatspace keeps meatspace-health)', () => {
    // The CoS Health page is the canonical destination for "take me to health"
    // per the page's move into the Chief of Staff sidebar group. MeatSpace's
    // health tab is still reachable via the explicit `meatspace-health` alias.
    expect(resolveNavCommand('health')?.path).toBe('/cos/health');
    expect(resolveNavCommand('meatspace-health')?.path).toBe('/meatspace/health');
  });

  it('prefers the longest matching alias in endsWith/includes tiers', () => {
    // Multi-word voice phrasings like "take me to meatspace health" normalize
    // to "take-me-to-meatspace-health" and match BOTH `-health` and
    // `-meatspace-health` in the endsWith tier. The resolver picks the longest
    // candidate so the user reaches the more specific page.
    expect(resolveNavCommand('take me to meatspace health')?.path).toBe('/meatspace/health');
    expect(resolveNavCommand('meatspace health')?.path).toBe('/meatspace/health');
    // The bare "health" input still resolves to CoS Health (exact alias tier).
    expect(resolveNavCommand('take me to health')?.path).toBe('/cos/health');
  });

  it('resolves "pipeline" to the new Create Pipeline page (not CoS Workflow)', () => {
    // The `pipeline` alias used to belong to /cos/workflow; the new dedicated
    // Pipeline page owns it now. CoS Workflow keeps `pipeline` as a keyword.
    const hit = resolveNavCommand('pipeline');
    expect(hit?.path).toBe('/pipeline');
    expect(hit?.command?.id).toBe('nav.create.pipeline');
  });

  it('resolves multi-word voice phrasings that end on a known page', () => {
    // "take me to the tasks page" → normalized "take-me-to-the-tasks-page"
    // → the resolver's "key contained in norm" tier picks up "tasks" via the
    // trailing token fallback (tail = "page" doesn't match, then substring
    // "tasks" is present in the normalized input).
    expect(resolveNavCommand('chief of staff tasks')?.path).toBe('/cos/tasks');
    expect(resolveNavCommand('cos tasks')?.path).toBe('/cos/tasks');
  });

  it('is case- and punctuation-insensitive', () => {
    expect(resolveNavCommand('BRAIN.')?.path).toBe('/brain/inbox');
    expect(resolveNavCommand('Review Hub!')?.path).toBe('/review');
  });

  it('returns null for unknown pages', () => {
    expect(resolveNavCommand('this-page-does-not-exist')).toBeNull();
    expect(resolveNavCommand('')).toBeNull();
    expect(resolveNavCommand(null)).toBeNull();
  });

  it('surfaces the matched alias for logging/telemetry', () => {
    const hit = resolveNavCommand('gsd');
    expect(hit?.matched).toBe('gsd');
    expect(hit?.path).toBe('/cos/gsd');
  });
});

describe('nav contract — tabbed pages match their tab constants', () => {
  for (const page of TABBED_PAGES) {
    const { prefix, file } = page;
    describe(prefix, () => {
      // The nav manifest paths owned by this page: exactly `<prefix>` (a default
      // section served at the bare prefix, e.g. /sharing → buckets) or anything
      // under `<prefix>/`. Compare on the bare path so deep-link query/hash
      // variants (e.g. /media/image?settings=1) normalize first.
      const hasNestedSources = (page.nestedIdSources || []).length > 0;
      const navPaths = NAV_COMMANDS
        .filter((c) => {
          const barePath = c.path.split(/[?#]/)[0];
          if (page.section) {
            return c.section === page.section
              && (c.tabId || (hasNestedSources && (barePath === prefix || barePath.startsWith(`${prefix}/`))));
          }
          return barePath === prefix || barePath.startsWith(`${prefix}/`);
        })
        .map((c) => c.path.split(/[?#]/)[0]);

      // Read inside it() bodies (not at describe time) so a moved/renamed source
      // file surfaces as a focused test failure rather than aborting the entire
      // suite during Vitest's collection phase.
      it('every nav manifest path resolves to a real page tab', () => {
        const tabPaths = new Set(extractTabPaths(path.join(REPO_ROOT, file), page));
        const orphans = navPaths.filter((p) => !tabPaths.has(p));
        expect(orphans).toEqual([]);
      });

      it('every page tab is reachable via the nav manifest', () => {
        const tabPaths = extractTabPaths(path.join(REPO_ROOT, file), page);
        const navSet = new Set(navPaths);
        const missing = tabPaths.filter((p) => !navSet.has(p));
        expect(missing).toEqual([]);
      });
    });
  }
});

// Settings is the one tabbed page whose child-nav wrapper and render dispatch
// live in separate files: `Settings.jsx`'s `switch (activeTab)`. A tab added to
// the manifest but forgotten in the switch would silently render the default
// `general` view, and a `case` with no manifest entry would be an orphan
// reachable only by URL. The nav↔header guard above can't see the switch; this
// pins manifest↔switch parity. Standalone pages such as Prompts are intentionally
// outside the /settings switch and therefore are not part of this comparison.
describe('nav contract — Settings tab bar header ↔ page switch parity', () => {
  const SETTINGS_PAGE = 'client/src/pages/Settings.jsx';

  // Header tab ids that live under /settings/<id> (cross-links already filtered
  // by the generated section list). Require the trailing slash so a hypothetical
  // bare `/settings` index entry cannot surface as a cryptic empty tab id.
  const headerTabIds = () => getSectionNavTabs('Settings')
    .map((tab) => tab.to)
    .filter((p) => p.startsWith('/settings/'))
    .map((p) => p.slice('/settings/'.length));

  const switchCaseIds = () => extractSwitchCases(
    fs.readFileSync(path.join(REPO_ROOT, SETTINGS_PAGE), 'utf8'), 'activeTab',
  );

  it('every Settings header tab has a renderTabContent switch case', () => {
    const cases = new Set(switchCaseIds());
    const missing = headerTabIds().filter((id) => !cases.has(id));
    expect(missing).toEqual([]);
  });

  it('every renderTabContent switch case has a Settings header tab', () => {
    const headerIds = new Set(headerTabIds());
    const orphans = switchCaseIds().filter((id) => !headerIds.has(id));
    expect(orphans).toEqual([]);
  });
});

describe('getNavAliasMap — voice-agent compatibility', () => {
  it('exposes every alias as a flat path map', () => {
    const map = getNavAliasMap();
    expect(map.dashboard).toBe('/');
    expect(map.tasks).toBe('/cos/tasks');
    expect(map.twin).toBe('/digital-twin/overview');
  });

  it('has no alias collisions (first-declared-wins guarantees deterministic resolution if any are introduced)', () => {
    const counts = {};
    for (const cmd of NAV_COMMANDS) {
      for (const a of (cmd.aliases || [])) counts[a] = (counts[a] || 0) + 1;
    }
    const collisions = Object.entries(counts).filter(([, n]) => n > 1);
    expect(collisions).toEqual([]);
  });
});

// ── Route ↔ nav-manifest coverage guard ────────────────────────────────────
// Parses the <Route path="…"> tree out of client/src/App.jsx and asserts every
// concrete, navigable leaf route resolves to a NAV_COMMANDS path. This catches
// the failure mode where a page is added to App.jsx (and maybe linked from
// inside another page) but never registered in the nav manifest, leaving it
// unreachable from ⌘K and voice (ui_navigate) — exactly how /local-llm/playground
// initially shipped. The shape-invariant guard above validates entry *shape*; it
// can't see a route that has no entry at all.
//
// Skipped (not destinations the manifest should cover):
//  - routes with a `:param` segment (detail/editor sub-routes; the :tab routes
//    are covered separately by the TABS contract above)
//  - redirect routes (<Navigate>, <RedirectWithSearch>, <CanonRedirect>,
//    <UniverseRouteRedirect>) — they forward to a real route, not a page
//  - container routes that only host children (their navigable destinations are
//    the child/index routes, e.g. /media's index redirects to /media/image)
//
// Routes intentionally kept out of nav go in NAV_COVERAGE_OPT_OUT with a reason;
// a second test fails if an opt-out entry goes stale (route deleted, or the path
// gained a manifest entry) so the allow-list can't quietly rot.
const APP_JSX = path.join(REPO_ROOT, 'client/src/App.jsx');
const MAIN_JSX = path.join(REPO_ROOT, 'client/src/main.jsx');
const SOCKET_JS = path.join(REPO_ROOT, 'client/src/services/socket.js');

// Concrete leaf routes that render a real page but are deliberately absent from
// the nav manifest — reached via an in-page button or as a create-mode sentinel,
// not from ⌘K / voice / the sidebar.
const NAV_COVERAGE_OPT_OUT = new Map([
  ['/*', 'catch-all 404 page — reached only by an unmatched URL, never a destination'],
  ['/ai/presets/new', 'create-preset drawer, reached via the "Add preset" button on /ai/presets'],
  ['/ai/services/new', 'add-service drawer, reached via the "Add service" button on /ai/services'],
  ['/apps/create', 'create-app form, reached via the "New App" button on /apps'],
  ['/creative-commission/new', 'create-commission drawer, reached via the "New Commission" button on /creative-commission'],
  ['/feature-agents/create', 'create-agent form, reached via the "New Agent" button'],
  ['/fableloom/join', 'scoped QR mobile join view, reached via scanned QR code with fragment credentials'],
  ['/login', 'auth gate — surfaced only when settings.secrets.auth is enabled, reached via 401 redirect'],
  ['/songbook/import', 'import-song form, reached via the "Import" button on /songbook'],
  ['/universes/new', 'create-mode sentinel for the Universe Builder editor'],
]);

// Element wrappers that forward to another route rather than render a page. A
// NEW redirect wrapper must be added here, or the scanner will treat it as a
// real page and (loudly, not silently) demand a nav entry for its route.
const REDIRECT_ELEMENT = /element=\{<\s*(Navigate|RedirectWithSearch|PrefixRedirect|CanonRedirect|UniverseRouteRedirect)\b/;

// Of those, the ones that REBASE a prefix and carry the trailing path (ids, tabs)
// onto the new one. The others forward to a fixed destination and discard
// whatever followed — correct for a static route, silently lossy for a param'd
// one, which is how a bookmark into a specific record turns into a landing on
// the index.
const SUFFIX_PRESERVING_ELEMENTS = new Set(['PrefixRedirect', 'UniverseRouteRedirect']);

// Flatten a stack of (possibly multi-segment, possibly "/") route path pieces
// into a single absolute path: ['/', 'media', 'image'] → '/media/image'.
function joinRoutePath(segments) {
  return `/${segments.flatMap((s) => s.split('/')).filter(Boolean).join('/')}`;
}

// Walk App.jsx line-by-line, tracking the stack of currently-open <Route>
// containers. Returns:
//  - required: absolute paths of every concrete, non-redirect, non-param leaf
//    route — the set that must each have a NAV_COMMANDS entry (or an opt-out)
//  - topLevel: absolute paths of concrete leaves directly under <Routes>, rather
//    than inside a layout/container route
//  - malformed: <Route>-opening lines whose tag doesn't close on the same line
//  - stackDepth: open containers left unclosed at EOF
// The scanner assumes each <Route> is a single line (true in App.jsx today). A
// multi-line route would otherwise slip through silently — a multi-line *leaf*
// reads as a pathless index route (resolves to an already-covered parent, never
// flagged) and a multi-line *container* never gets pushed yet still pops on its
// </Route>, corrupting the stack. `malformed`/`stackDepth` make that assumption
// self-enforcing so it fails loudly instead. Returned (not thrown) so a bad
// App.jsx surfaces as a focused test failure rather than aborting collection.
function scanRoutes(appSrc) {
  const stack = []; // parent path segments of currently-open <Route> containers
  const required = [];
  const topLevel = [];
  const redirects = []; // { from, to } for every forwarding leaf route
  const malformed = [];
  for (const rawLine of appSrc.split('\n')) {
    const line = rawLine.trim();
    if (line === '</Route>') { stack.pop(); continue; }
    if (!/^<Route\b/.test(line)) continue; // skips <Routes>, comments, JSX text

    // A single-line <Route> always closes its tag with `>` (container) or `/>`
    // (leaf). Anything else is a multi-line opener the scanner can't handle.
    if (!line.endsWith('>')) { malformed.push(line); continue; }

    // A `path=` attribute that didn't parse (e.g. single-quoted) must not be
    // silently mistaken for a pathless index route — flag it loudly instead.
    const pathMatch = line.match(/\bpath="([^"]*)"/);
    if (!pathMatch && /\bpath=/.test(line)) { malformed.push(line); continue; }
    const routePath = pathMatch ? pathMatch[1] : null; // null = index route

    // A container is a layout wrapper: push its segment so children resolve to
    // absolute paths, but don't require a manifest entry for the wrapper itself.
    if (!line.endsWith('/>')) {
      stack.push(routePath ?? '');
      continue;
    }
    // An index route resolves to its parent's path (e.g. the `/` index = Dashboard).
    const absolute = routePath === null
      ? joinRoutePath(stack)
      : joinRoutePath([...stack, routePath]);
    if (stack.length === 0) topLevel.push(absolute);

    // Redirects are recorded rather than dropped: a moved page's old path has to
    // keep landing somewhere, and that is only assertable if the scanner reports
    // where each forwarding route points. `to` is read off the same line — as a
    // plain string, or as a template literal whose only interpolation is the
    // PortOS app id (`/apps/${PORTOS_APP_ID}/submodules`). A `from`-only wrapper
    // (CanonRedirect) records nothing rather than a bogus target.
    const redirectElement = line.match(REDIRECT_ELEMENT);
    if (redirectElement) {
      const quoted = line.match(/\bto="([^"]*)"/);
      const templated = line.match(/\bto=\{`([^`]*)`\}/);
      const to = quoted?.[1] ?? templated?.[1]?.replace('${PORTOS_APP_ID}', PORTOS_APP_ID);
      if (to) redirects.push({ from: absolute, to, element: redirectElement[1] });
      continue;
    }

    if (absolute.split('/').some((s) => s.startsWith(':'))) continue; // param route
    required.push(absolute);
  }
  return { required: [...new Set(required)], topLevel: [...new Set(topLevel)], redirects, malformed, stackDepth: stack.length };
}

// Settings owns a small declarative redirect map for retired tabs, while App.jsx
// owns redirects that need their own route element. Keep both forms in the
// previous-path contract so a migration can use the existing Settings page
// without turning a route-only client edit into an application-root change.
function scanSettingsRedirects(settingsSrc) {
  const block = settingsSrc.match(/const REDIRECTS\s*=\s*\{([\s\S]*?)^\};/m);
  if (!block) throw new Error('No REDIRECTS object found in Settings.jsx');
  return [...block[1].matchAll(/^\s*['"]?([\w-]+)['"]?\s*:\s*['"]([^'"]+)['"]\s*,?$/gm)]
    .map((match) => ({ from: `/settings/${match[1]}`, to: match[2] }));
}

describe('nav coverage — every navigable App.jsx route has a manifest entry', () => {
  // Query string / hash on a manifest path (e.g. /media/image?settings=1) is a
  // deep-link variant of a real route; compare on the bare path.
  const navPaths = new Set(NAV_COMMANDS.map((c) => c.path.split(/[?#]/)[0]));
  const scan = scanRoutes(fs.readFileSync(APP_JSX, 'utf8'));
  const settingsRedirects = scanSettingsRedirects(fs.readFileSync(SETTINGS_PAGE, 'utf8'));
  const routePaths = new Set(scan.required);
  const byFrom = new Map([...scan.redirects, ...settingsRedirects].map((r) => [r.from, r]));

  it('the line scanner saw every <Route> (single-line assumption holds)', () => {
    // A non-empty malformed list or unbalanced stack means a multi-line route
    // exists and would slip past the coverage check below — re-fold it to one
    // line, or upgrade the scanner before trusting the guard.
    expect(scan.malformed).toEqual([]);
    expect(scan.stackDepth).toBe(0);
  });

  it('each concrete leaf <Route> resolves to a NAV_COMMANDS path (or an opt-out)', () => {
    const uncovered = [...routePaths]
      .filter((p) => !navPaths.has(p) && !NAV_COVERAGE_OPT_OUT.has(p));
    expect(uncovered).toEqual([]);
  });

  it('keeps the hosted audience join route outside the chrome layout', () => {
    // The hosted audience shell owns a full dynamic viewport and must not be
    // nested under Layout's shorter overflow-hidden main (#5499).
    expect(scan.topLevel).toContain('/fableloom/join');
  });

  it('keeps hosted audience joins free of authenticated app bootstraps', () => {
    // A password-gated install must not redirect a QR audience device before
    // the fragment token reaches FableLoomHostedJoin (#5499).
    const appSrc = fs.readFileSync(APP_JSX, 'utf8');
    const mainSrc = fs.readFileSync(MAIN_JSX, 'utf8');
    const socketSrc = fs.readFileSync(SOCKET_JS, 'utf8');
    expect(appSrc).toMatch(/useTimezoneBootstrap\(!isHostedAudienceRoute\)/);
    expect(appSrc).toMatch(/useDocumentTitle\(!isHostedAudienceRoute\)/);
    expect(appSrc).toMatch(/isHostedAudienceRoute\s*\?\s*routeContent/);
    expect(mainSrc).toContain('const isHostedAudienceRoute = isPublicGuestRoute(window.location.pathname)');
    expect(appSrc).toContain('isPublicGuestRoute(pathname)');
    expect(socketSrc).toContain('isPublicGuestRoute(window.location.pathname)');
    expect(socketSrc).toMatch(/autoConnect: !isHostedAudienceRoute/);
  });

  // Every page that has ever moved leaves its old path behind in bookmarks, in
  // stale ⌘K history, and in links other installs' peers may hold. A move that
  // forgets the redirect 404s all of them, and nothing else in this file would
  // notice — the coverage guard above only looks at where routes point NOW.
  //
  // Driven by each command's own `previousPaths`, NOT a list maintained here: the
  // declaration then lives beside the path that moved, and the next move is one
  // edit in navManifest.js instead of two files that can disagree.
  // Compare the full destination, including any query that opens a feature-local
  // drawer or selects a subview.
  it('keeps a redirect from every declared previous path to its current one', () => {
    const broken = NAV_COMMANDS
      .flatMap((c) => (c.previousPaths || []).map((from) => ({ from, to: c.path, id: c.id })))
      .filter(({ from, to }) => byFrom.get(from)?.to !== to)
      .map(({ from, to, id }) => `${id}: ${from} → ${byFrom.get(from)?.to ?? 'NO REDIRECT'} (want ${to})`);
    expect(broken).toEqual([]);
  });

  // Landing on the right PAGE is only half of it. A previous path with a `:param`
  // segment was a deep link into one record, so its redirect has to carry that
  // segment across — swapping the PrefixRedirect for a bare <Navigate to="/models/training">
  // still points at the right page and would pass the check above, while every
  // bookmarked record quietly lands on the index instead. Retired features may
  // explicitly opt out because their destination no longer selects old records.
  it('preserves the record id when a parameterized previous path redirects', () => {
    const lossy = NAV_COMMANDS
      .flatMap((c) => (c.previousPaths || []).map((from) => ({ from, id: c.id, preserveSuffix: c.preservePreviousPathSuffix !== false })))
      .filter(({ from, preserveSuffix }) => preserveSuffix && from.split('/').some((seg) => seg.startsWith(':')))
      .map(({ from, id }) => ({ from, id, hit: byFrom.get(from) }))
      .filter(({ hit }) => !hit || !SUFFIX_PRESERVING_ELEMENTS.has(hit.element))
      .map(({ from, id, hit }) => `${id}: ${from} forwards via ${hit?.element ?? 'NO REDIRECT'}, which drops the trailing segment`);
    expect(lossy).toEqual([]);
  });

  // The guard above is only as good as what it is pointed at, and it reads a
  // field that is easy to simply not add. Pin the moves already made so deleting
  // a `previousPaths` entry fails here rather than silently shrinking coverage.
  it('still declares the previous paths of the pages already moved', () => {
    const declared = new Set(NAV_COMMANDS.flatMap((c) => c.previousPaths || []));
    const missing = [
      '/settings/local-llm',   // #4736 — Local LLM management left Settings
      '/models/llms/runtimes', // #7414 — Runtimes left the LLMs pill bar for its own tab
      '/media/models',         // #4728 — the rest of model management left Create/Settings/Dev Tools
      '/media/loras',
      '/media/training',
      '/media/training/:datasetId',
      '/models/training',
      '/models/training/:recordId',
      '/settings/embeddings',
      '/system-resources/models',
      // The dataset workbench was its own deep-linkable path, and a bookmark into
      // one dataset breaks just as silently as the index.
      // #7567 — /ai became /ai/presets and the Backend Connections drawer
      // became the Services view; a stored pin or bookmark on either must land.
      '/ai',
      '/ai/connections',
      '/ai/connections/:connectionId',
      // The rest of the moves App.jsx already redirected but nothing declared.
      // A pinned sidebar row is a STORED route path, so an undeclared move made
      // the pin stop resolving and vanish on the next update — the client reads
      // these to map a stored path onto where its page lives now.
      '/openworld', '/city',              // retired OpenWorld routes
      '/devtools/submodules',
      '/devtools/runs',
      '/settings/contacts',
      '/settings/signal',
      '/settings/catalog',
      '/imessage',
      '/system-health',
      '/datadog',
      '/jira',
      '/image-gen',
      '/video-gen',
      '/media-history',
      '/annotate', '/annotate/:mediaKey',
      '/media/sprites', '/media/sprites/:id',
      '/media/3d', '/media/3d/:id',
      '/media/creative-director', '/media/creative-director/:id/:tab',
      '/media/music-video', '/media/music-video/:projectId',
      '/media/universe-builder', '/media/universe-builder/:universeId',
      '/universe-builder', '/universe-builder/:universeId',
    ].filter((p) => !declared.has(p));
    expect(missing).toEqual([]);
  });

  // A redirect that forwards to a path nothing serves is a 404 with extra steps.
  it('every redirect lands on a real route or nav destination', () => {
    const known = new Set([...routePaths, ...navPaths]);
    const dangling = scan.redirects
      // A RELATIVE target (`to="overview"`) resolves against its own route, so it
      // has no absolute path to look up — /feature-agents/:id → overview and the
      // two pipeline/story tab defaults are all this shape.
      .filter((r) => r.to.startsWith('/'))
      .map((r) => ({ ...r, bare: r.to.split(/[?#]/)[0] }))
      // A param route can't be enumerated by path, so accept any target whose
      // parent segment is served (e.g. /models/training covers the :datasetId
      // drill-down the PrefixRedirect rebases onto).
      .filter(({ bare }) => !known.has(bare)
        && !known.has(bare.split('/').slice(0, -1).join('/')))
      .map((r) => `${r.from} → ${r.to}`);
    expect(dangling).toEqual([]);
  });

  it('opt-out list has no stale entries', () => {
    // A stale opt-out is one whose route no longer exists, or that has since
    // gained a manifest entry (so it should just be removed from the allow-list).
    const stale = [...NAV_COVERAGE_OPT_OUT.keys()]
      .filter((p) => !routePaths.has(p) || navPaths.has(p));
    expect(stale).toEqual([]);
  });
});

// The POST Practice Library (`/post/explore`) is a page of hard-coded deep links
// into every POST test surface — the one place a user can browse what exists.
// A typo or a renamed mode there produces a card that opens a blank tab, and
// nothing else in the app would notice. Every link it ships must therefore be a
// path the nav manifest already registers, which is also what makes each of
// those surfaces reachable from ⌘K and voice.
describe('nav contract — POST Practice Library links are registered destinations', () => {
  const CATALOG_FILES = [
    // Owns DRILL_PRACTICE_LINKS — where most catalog cards get their href, so
    // scanning only the catalog would leave the DERIVED half unguarded.
    'client/src/components/meatspace/post/constants.js',
    'client/src/components/meatspace/post/practiceCatalog.js',
    'client/src/components/meatspace/post/PracticeLibrary.jsx',
    'client/src/components/meatspace/post/PostSessionLauncher.jsx',
    'client/src/components/meatspace/post/BrowseCatalogLink.jsx',
    // The sidebar's POST section — a link there that no command registers is
    // unreachable from ⌘K and voice.
    'client/src/components/Layout.jsx',
  ];
  const navPaths = new Set(NAV_COMMANDS.map((c) => c.path));

  for (const file of CATALOG_FILES) {
    it(`${file} links only at registered POST paths`, () => {
      const src = fs.readFileSync(path.join(REPO_ROOT, file), 'utf8');
      // Both quote styles: JS object values use single quotes, JSX `to="…"` uses
      // double. Route PARAMS (`:id`) are excluded — those are dynamic detail
      // routes that deliberately carry no manifest entry.
      const links = [...src.matchAll(/['"](\/post\/[^'"${}]*)['"]/g)]
        .map((m) => m[1])
        .filter((p) => !p.includes(':'));
      expect(links.length).toBeGreaterThan(0);
      const unregistered = [...new Set(links)].filter((p) => !navPaths.has(p));
      expect(unregistered).toEqual([]);
    });
  }
});

it('keeps Video browsing separate from Creative Director production aliases', () => {
  expect(resolveNavCommand('video').path).toBe('/video');
  expect(resolveNavCommand('create-video').path).toBe('/creative-director');
  expect(resolveNavCommand('video-production').path).toBe('/creative-director');
});