stack/packages/mosaic/src/commands/fleet-profiles.ts

/**
 * `mosaic fleet profile <list|show>` — system-type profiles (North Star H2).
 *
 * A profile is a DECLARATIVE mapping from a "system type" (software-delivery,
 * personal-assistant, research, business, marketing, …) to a persona roster plus
 * its org topology. Profiles are DATA, seeded from the framework like roles:
 *   framework/fleet/profiles/*.yaml  ->  <mosaicHome>/fleet/profiles/*.yaml
 * so an operator declares a system type and gets the matching roster from the
 * baseline library with NO code change (NS-9 / AC-NS-6).
 *
 * This module loads, parses, and VALIDATES those yaml files. Validation guards
 * roster/library drift: every persona class a profile references MUST resolve to
 * a real persona in the role library. Because the library encodes class identity
 * INLINE in prose (e.g. `` (`class: marketing-lead`) ``) — not YAML frontmatter —
 * and a few engineering personas (planner/decomposition) carry no marker at all,
 * the set of valid classes is the UNION of three signals:
 *   1. inline `` `class: X` `` markers scanned from roles/*.md,
 *   2. the persona rows in roles/LIBRARY.md (the authoritative index),
 *   3. the role filenames themselves (roles/<class>.md).
 * See `listPersonaClasses`.
 */

import { readFile, readdir } from 'node:fs/promises';
import { homedir } from 'node:os';
import { basename, join } from 'node:path';
import type { Command } from 'commander';
import YAML from 'yaml';
import {
  defaultOverrideDir,
  extractClassesFromDir,
  listPersonaClasses as listOverrideAwarePersonaClasses,
} from './fleet-personas.js';

function defaultMosaicHome(): string {
  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
}

/** Directory holding the seeded profile yaml files. */
export function defaultProfilesDir(mosaicHome = defaultMosaicHome()): string {
  return join(mosaicHome, 'fleet', 'profiles');
}

/** Directory holding the persona role contracts. */
export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
  return join(mosaicHome, 'fleet', 'roles');
}

export interface ProfileRosterEntry {
  class: string;
  reportsTo?: string;
  multiplicity: number;
}

export interface FleetProfile {
  id: string;
  title: string;
  description: string;
  lead: string;
  floor: string[];
  roster: ProfileRosterEntry[];
  notes?: string;
}

/**
 * Extract the set of valid persona classes from a single baseline role dir.
 *
 * Thin wrapper over the shared {@link extractClassesFromDir} in fleet-personas.ts
 * — the single source of truth for "what classes exist" (DRY). Kept as a
 * baseline-only, positional-`rolesDir` helper for backward compatibility; the
 * override-aware union (baseline ⊕ roles.local) used by roster validation is
 * {@link listPersonaClassesWithOverrides} below.
 */
export async function listPersonaClasses(rolesDir = defaultRolesDir()): Promise<Set<string>> {
  return (await extractClassesFromDir(rolesDir)).classes;
}

/**
 * Override-aware valid-class set: baseline roles/ ⊕ override roles.local/. A
 * profile may legitimately reference a user-customized OR user-ADDED persona, so
 * roster validation resolves against this union (H4). Delegates to the shared
 * fleet-personas resolver.
 */
export async function listPersonaClassesWithOverrides(
  rolesDir: string,
  overrideDir: string,
): Promise<Set<string>> {
  return listOverrideAwarePersonaClasses({ rolesDir, overrideDir });
}

function asString(value: unknown, ctx: string): string {
  if (typeof value !== 'string' || value.trim() === '') {
    throw new Error(`profile ${ctx} must be a non-empty string`);
  }
  return value.trim();
}

/**
 * Parse raw yaml text into a typed FleetProfile. Pure (no IO). Throws a
 * descriptive error on a malformed profile so the loader/CLI fail loudly.
 * `sourceId` (typically the filename stem) is used only for error messages and
 * to validate that the declared `id` matches the file it came from.
 */
export function parseProfile(rawText: string, sourceId?: string): FleetProfile {
  const parsed = YAML.parse(rawText) as Record<string, unknown> | null;
  if (!parsed || typeof parsed !== 'object') {
    throw new Error(`profile ${sourceId ?? '<?>'} did not parse to a mapping`);
  }

  const id = asString(parsed['id'], `${sourceId ?? '<?>'}.id`);
  if (sourceId && id !== sourceId) {
    throw new Error(`profile id "${id}" does not match its filename "${sourceId}"`);
  }

  const rawFloor = parsed['floor'] ?? [];
  if (!Array.isArray(rawFloor)) {
    throw new Error(`profile ${id}.floor must be an array`);
  }
  const floor = rawFloor.map((c, i) => asString(c, `${id}.floor[${i}]`));

  const rawRoster = parsed['roster'];
  if (!Array.isArray(rawRoster) || rawRoster.length === 0) {
    throw new Error(`profile ${id}.roster must be a non-empty array`);
  }
  const roster: ProfileRosterEntry[] = rawRoster.map((row, i) => {
    const r = row as Record<string, unknown>;
    const cls = asString(r?.['class'], `${id}.roster[${i}].class`);
    const multRaw = r?.['multiplicity'];
    let multiplicity = 1;
    if (multRaw !== undefined && multRaw !== null) {
      if (typeof multRaw !== 'number' || !Number.isInteger(multRaw) || multRaw < 1) {
        throw new Error(`profile ${id}.roster[${i}].multiplicity must be a positive integer`);
      }
      multiplicity = multRaw;
    }
    const entry: ProfileRosterEntry = { class: cls, multiplicity };
    const reportsTo = r?.['reports_to'];
    if (reportsTo !== undefined && reportsTo !== null) {
      entry.reportsTo = asString(reportsTo, `${id}.roster[${i}].reports_to`);
    }
    return entry;
  });

  const profile: FleetProfile = {
    id,
    title: asString(parsed['title'], `${id}.title`),
    description: asString(parsed['description'], `${id}.description`),
    lead: asString(parsed['lead'], `${id}.lead`),
    floor,
    roster,
  };
  const notes = parsed['notes'];
  if (notes !== undefined && notes !== null) {
    profile.notes = asString(notes, `${id}.notes`);
  }
  return profile;
}

/**
 * Validate a profile against the set of valid persona classes and its own roster.
 * Returns the list of problems (empty when valid) rather than throwing, so the
 * loader can aggregate errors across many profiles.
 *
 * Checks:
 *   - lead resolves to a real persona class.
 *   - every floor[] entry resolves.
 *   - every roster[].class resolves.
 *   - every roster[].reports_to resolves AND names a class present in THIS roster
 *     (topology edges must point at a seat that exists in the profile).
 * Cycle detection in the reports_to graph is intentionally out of scope.
 */
export function validateProfile(profile: FleetProfile, validClasses: Set<string>): string[] {
  const problems: string[] = [];
  const rosterClasses = new Set(profile.roster.map((r) => r.class));

  if (!validClasses.has(profile.lead)) {
    problems.push(`lead "${profile.lead}" is not a known persona class`);
  }
  for (const f of profile.floor) {
    if (!validClasses.has(f)) {
      problems.push(`floor entry "${f}" is not a known persona class`);
    }
  }
  for (const entry of profile.roster) {
    if (!validClasses.has(entry.class)) {
      problems.push(`roster class "${entry.class}" is not a known persona class`);
    }
    if (entry.reportsTo !== undefined) {
      if (!validClasses.has(entry.reportsTo)) {
        problems.push(
          `roster "${entry.class}" reports_to "${entry.reportsTo}" is not a known persona class`,
        );
      } else if (!rosterClasses.has(entry.reportsTo)) {
        problems.push(
          `roster "${entry.class}" reports_to "${entry.reportsTo}" which is not present in this roster`,
        );
      }
    }
  }
  return problems;
}

export interface LoadProfilesOptions {
  /** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
  profilesDir?: string;
  /** Override the roles dir (tests). Defaults to <mosaicHome>/fleet/roles. */
  rolesDir?: string;
  /** Persona override dir (tests). Defaults to <mosaicHome>/fleet/roles.local. */
  overrideDir?: string;
  mosaicHome?: string;
}

function resolveDirs(opts: LoadProfilesOptions): {
  profilesDir: string;
  rolesDir: string;
  overrideDir: string;
} {
  const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
  return {
    profilesDir: opts.profilesDir ?? defaultProfilesDir(mosaicHome),
    rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
    overrideDir: opts.overrideDir ?? defaultOverrideDir(mosaicHome),
  };
}

/**
 * Load, parse, and validate every profile yaml in the profiles dir. Throws if
 * any profile is malformed, references an unknown class, or duplicates an id.
 * Profiles are returned sorted by id for deterministic output.
 */
export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<FleetProfile[]> {
  const { profilesDir, rolesDir, overrideDir } = resolveDirs(opts);
  let files: string[];
  try {
    files = (await readdir(profilesDir)).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
  } catch {
    throw new Error(`No fleet profiles directory at ${profilesDir}`);
  }
  files.sort();

  // Override-aware: a profile may reference a user-customized or user-ADDED
  // persona living in the roles.local/ layer (H4), so validate against the
  // baseline ⊕ override union, not the baseline alone.
  const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
  const profiles: FleetProfile[] = [];
  const seen = new Map<string, string>();

  for (const file of files) {
    const sourceId = basename(file, file.endsWith('.yaml') ? '.yaml' : '.yml');
    const rawText = await readFile(join(profilesDir, file), 'utf8');
    const profile = parseProfile(rawText, sourceId);

    const prior = seen.get(profile.id);
    if (prior) {
      throw new Error(`Duplicate profile id "${profile.id}" in ${file} and ${prior}`);
    }
    seen.set(profile.id, file);

    const problems = validateProfile(profile, validClasses);
    if (problems.length > 0) {
      throw new Error(`Profile ${file} is invalid:\n  - ${problems.join('\n  - ')}`);
    }
    profiles.push(profile);
  }
  return profiles;
}

/** Load and validate a single profile by id. Throws if not found. */
export async function loadProfile(
  id: string,
  opts: LoadProfilesOptions = {},
): Promise<FleetProfile> {
  const profiles = await loadProfiles(opts);
  const match = profiles.find((p) => p.id === id);
  if (!match) {
    const known = profiles.map((p) => p.id).join(', ') || '(none)';
    throw new Error(`Unknown profile "${id}". Known profiles: ${known}`);
  }
  return match;
}

/** Total seat count of a roster, honoring multiplicity. */
function rosterSize(profile: FleetProfile): number {
  return profile.roster.reduce((sum, entry) => sum + entry.multiplicity, 0);
}

function printProfileList(profiles: FleetProfile[]): void {
  if (profiles.length === 0) {
    console.log('(no profiles)');
    return;
  }
  for (const p of profiles) {
    console.log(`${p.id}\t${p.title}\tlead=${p.lead}\troster=${rosterSize(p)}`);
  }
}

function printProfileShow(profile: FleetProfile): void {
  console.log(`${profile.id} — ${profile.title}`);
  console.log(profile.description);
  console.log('');
  console.log(`lead: ${profile.lead}`);
  console.log(`floor: ${profile.floor.join(', ') || '-'}`);
  console.log(`roster (${rosterSize(profile)} seat(s)):`);
  for (const entry of profile.roster) {
    const reports = entry.reportsTo ? ` reports_to=${entry.reportsTo}` : '';
    const mult = entry.multiplicity > 1 ? ` x${entry.multiplicity}` : '';
    console.log(`  - ${entry.class}${mult}${reports}`);
  }
  if (profile.notes) {
    console.log('');
    console.log(`notes: ${profile.notes}`);
  }
}

/**
 * Register `profile` under an existing `fleet` command. `mosaicHomeFor` resolves
 * the active --mosaic-home (parent flag) at call time, matching the backlog
 * subcommand wiring. Validation errors exit non-zero with a readable message.
 */
export function registerFleetProfileCommand(
  fleetCmd: Command,
  mosaicHomeFor: () => string,
): Command {
  const profileCmd = fleetCmd
    .command('profile')
    .description('System-type profiles: declarative persona roster + topology (H2)');

  profileCmd
    .command('list')
    .description('List available system-type profiles (id, title, lead, roster size)')
    .option('--json', 'Print JSON')
    .action(async (opts: { json?: boolean }) => {
      try {
        const profiles = await loadProfiles({ mosaicHome: mosaicHomeFor() });
        if (opts.json) {
          console.log(JSON.stringify(profiles));
          return;
        }
        printProfileList(profiles);
      } catch (err) {
        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
        process.exitCode = 1;
      }
    });

  profileCmd
    .command('show <id>')
    .description('Show a profile: full roster with reports_to/multiplicity, floor, lead')
    .option('--json', 'Print JSON')
    .action(async (id: string, opts: { json?: boolean }) => {
      try {
        const profile = await loadProfile(id, { mosaicHome: mosaicHomeFor() });
        if (opts.json) {
          console.log(JSON.stringify(profile));
          return;
        }
        printProfileShow(profile);
      } catch (err) {
        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
        process.exitCode = 1;
      }
    });

  return profileCmd;
}