fix(#792): make fleet roster errors actionable

packages/mosaic/src/commands/fleet.ts

@@ -19,8 +19,11 @@ import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
 import {
+  FleetRosterConfigurationError,
   getRosterAgent,
   loadFleetRoster,
+  parseFleetRosterDocument,
+  readFleetRosterText,
   resolveInstalledFleetRosterPath,
   type FleetAgent,
   type FleetRoster,
@@ -1913,7 +1916,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
         const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
         const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
         const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-        const roster = await loadFleetRoster(rosterPath);
+        const roster = await loadRosterAtPath(cmd, rosterPath);
 
         const newAgent: FleetAgent = {
           name,
@@ -1973,7 +1976,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
       const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
       const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
       const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-      const roster = await loadFleetRoster(rosterPath);
+      const roster = await loadRosterAtPath(cmd, rosterPath);
 
       // Guard: throws if removing leaves 0 orchestrators or agent not in roster
       const updatedRoster = removeAgentFromRoster(roster, name);
@@ -2402,14 +2405,19 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
 
 async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
   const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
-  return loadFleetRoster(await resolveRosterPath(opts.mosaicHome, opts.roster));
+  return loadRosterAtPath(cmd, await resolveRosterPath(opts.mosaicHome, opts.roster));
 }
 
 /** Routes only a v2 roster to the M3 desired-state control plane; v1 aliases stay compatible. */
 async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
   const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
   const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
-  const parsed: unknown = YAML.parse(await readFile(path, 'utf8'));
+  let parsed: unknown;
+  try {
+    parsed = parseFleetRosterDocument(await readFleetRosterText(path), path);
+  } catch (error) {
+    reportFleetRosterConfigurationError(cmd, error);
+  }
   return (
     typeof parsed === 'object' &&
     parsed !== null &&
@@ -2425,7 +2433,22 @@ async function loadRosterFromAgentCommand(
 ): Promise<FleetRoster> {
   const opts = command.optsWithGlobals<{ mosaicHome?: string; roster?: string }>();
   const mosaicHome = opts.mosaicHome ?? mosaicHomeOverride ?? defaultMosaicHome();
-  return loadFleetRoster(await resolveRosterPath(mosaicHome, opts.roster));
+  return loadRosterAtPath(command, await resolveRosterPath(mosaicHome, opts.roster));
+}
+
+async function loadRosterAtPath(command: Command, path: string): Promise<FleetRoster> {
+  try {
+    return await loadFleetRoster(path);
+  } catch (error) {
+    reportFleetRosterConfigurationError(command, error);
+  }
+}
+
+function reportFleetRosterConfigurationError(command: Command, error: unknown): never {
+  if (error instanceof FleetRosterConfigurationError) {
+    command.error(error.message, { code: 'fleet.roster', exitCode: 1 });
+  }
+  throw error;
 }
 
 function resolveMosaicHomeFromCommand(command: Command, override?: string): string {

packages/mosaic/src/fleet/fleet-roster-v1.ts

@@ -104,6 +104,10 @@ export interface FleetRoster {
 
 export type FleetRosterInputFormat = 'yaml' | 'json';
 
+export class FleetRosterConfigurationError extends Error {
+  override name = 'FleetRosterConfigurationError';
+}
+
 export function resolveInstalledFleetRosterPath(mosaicHome: string): string {
   const yamlPath = join(mosaicHome, 'fleet', 'roster.yaml');
   try {
@@ -138,8 +142,52 @@ export function parseFleetRosterV1(
 }
 
 export async function loadFleetRoster(path: string): Promise<FleetRoster> {
-  const source = await readFile(path, 'utf8');
-  return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
+  const source = await readFleetRosterText(path);
+  try {
+    return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
+  } catch (error) {
+    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
+    throw error;
+  }
+}
+
+/** Read an operator-owned roster with errors that say how to recover. */
+export async function readFleetRosterText(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if (isNodeErrorCode(error, 'ENOENT')) {
+      throw new FleetRosterConfigurationError(
+        `No fleet roster found at ${path}. Run \`mosaic fleet init\` to create one.`,
+      );
+    }
+    throw new FleetRosterConfigurationError(
+      `Could not read fleet roster at ${path}. Check the file exists and is readable.`,
+    );
+  }
+}
+
+/** Parse a roster document needed only to select the v1/v2 command path. */
+export function parseFleetRosterDocument(source: string, path: string): unknown {
+  try {
+    return YAML.parse(source);
+  } catch (error) {
+    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
+    throw error;
+  }
+}
+
+function invalidFleetRosterError(path: string): FleetRosterConfigurationError {
+  return new FleetRosterConfigurationError(
+    `Fleet roster at ${path} is invalid. Fix the file or run \`mosaic fleet init --force\`.`,
+  );
+}
+
+function isRosterParserError(error: unknown): boolean {
+  return (
+    error instanceof SyntaxError ||
+    (error instanceof Error && (error.name === 'YAMLParseError' || error.name === 'YAMLWarning'))
+  );
 }
 
 export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {