fix(#792): fleet roster ENOENT actionable exit + installer heading printf (#818)

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 {
@@ -149,6 +197,16 @@ export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
 }
 
 export function normalizeFleetRosterV1(raw: RawFleetRoster): FleetRoster {
+  try {
+    return normalizeFleetRosterV1Unchecked(raw);
+  } catch (error) {
+    if (error instanceof FleetRosterConfigurationError) throw error;
+    if (error instanceof Error) throw new FleetRosterConfigurationError(error.message);
+    throw error;
+  }
+}
+
+function normalizeFleetRosterV1Unchecked(raw: RawFleetRoster): FleetRoster {
   assertObject(raw, 'Fleet roster');
   assertKnownKeys(raw, 'Fleet roster', [
     'version',