@indigoai-us/hq-cli 5.77.2 → 5.77.4

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.77.4]
+
+### Fixed
+
+- Malformed user-managed YAML now reports the affected file and line/column as
+  an expected, actionable CLI error instead of creating a Sentry exception.
+
 ## [5.77.2]
 
 ### Fixed

package/dist/commands/cloud-demote.js

@@ -30,6 +30,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import chalk from "chalk";
 import { ProvisionError, companyConfigPath, companyDirPath, createDefaultVaultClient, manifestPath, validateManifestAndDir, validateSlug, } from "./cloud-provision.js";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
@@ -49,7 +50,7 @@ export function flipCompanyYamlCloudOff(hqRoot, slug) {
     if (!fs.existsSync(yPath))
         return false;
     const raw = fs.readFileSync(yPath, "utf-8");
-    const parsed = yaml.load(raw) ?? {};
+    const parsed = parseUserYaml(raw, yPath) ?? {};
     if (parsed.cloud === false)
         return false;
     parsed.cloud = false;
@@ -72,7 +73,7 @@ export function stripManifestCloudForSlug(hqRoot, slug) {
     if (!fs.existsSync(mPath))
         return false;
     const raw = fs.readFileSync(mPath, "utf-8");
-    const parsed = yaml.load(raw) ?? {};
+    const parsed = parseUserYaml(raw, mPath) ?? {};
     const companies = parsed.companies;
     if (!companies || !(slug in companies))
         return false;

package/dist/commands/cloud-provision.js

@@ -31,6 +31,7 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { share } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 /** Custom error class so the CLI runner can map to exit codes. */
@@ -105,7 +106,7 @@ export function validateManifestAndDir(hqRoot, slug) {
         throw new ProvisionError(2, `companies/manifest.yaml not found at ${mPath}`);
     }
     const raw = fs.readFileSync(mPath, "utf-8");
-    const parsed = yaml.load(raw);
+    const parsed = parseUserYaml(raw, mPath);
     if (!parsed ||
         typeof parsed !== "object" ||
         !("companies" in parsed) ||
@@ -225,7 +226,7 @@ export function ensureManifestEntryForProvision(hqRoot, slug) {
 export function patchManifest(hqRoot, slug, cloudUid, bucketName) {
     const mPath = manifestPath(hqRoot);
     const raw = fs.readFileSync(mPath, "utf-8");
-    const parsed = yaml.load(raw) ?? { companies: {} };
+    const parsed = parseUserYaml(raw, mPath) ?? { companies: {} };
     if (!parsed.companies)
         parsed.companies = {};
     const existing = parsed.companies[slug];

package/dist/commands/files.js

@@ -381,7 +381,7 @@ export function registerFilesCommand(program) {
     });
     files
         .command("versions <path>")
-        .description("List prior content versions and delete markers for one exact vault key. Use --personal for your personal vault.")
+        .description("List prior content versions and delete markers for one exact vault key. Restore a listed version with restore --version-id <id>. Use --personal for your personal vault.")
         .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
         .action(async (path, opts) => {
         try {
@@ -397,9 +397,9 @@ export function registerFilesCommand(program) {
     });
     files
         .command("restore <path>")
-        .description("Restore a prior version or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.")
+        .description("Restore a prior version with --version-id or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.")
         .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
-        .option("--version <id>", "Content version ID to restore")
+        .option("--version-id <id>", "Content version ID to restore")
         .option("-y, --yes", "Skip the overwrite confirmation prompt (for scripts)")
         .action(async (path, opts) => {
         try {
@@ -408,7 +408,7 @@ export function registerFilesCommand(program) {
             assertRecoveryScope(personal, companySlug);
             await runFilesRestore({
                 key: path,
-                versionId: opts.version,
+                versionId: opts.versionId,
                 yes: opts.yes === true,
                 personal,
                 companySlug,

package/dist/commands/pack-install.js

@@ -37,7 +37,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { createHash, createPublicKey, verify as cryptoVerify, } from 'node:crypto';
 import { execFileSync, spawnSync } from 'child_process';
 import chalk from 'chalk';
@@ -940,9 +940,12 @@ export function validateManifest(payloadDir, hqVersion) {
     }
     let parsed;
     try {
-        parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+        parsed = parseUserYaml(fs.readFileSync(manifestPath, 'utf-8'), manifestPath);
     }
     catch (e) {
+        if (e instanceof Error && e.expected === true) {
+            throw e;
+        }
         throw new Error(`package.yaml invalid YAML: ${e.message}`);
     }
     const m = parsed;

package/dist/commands/people.js

@@ -14,7 +14,7 @@
 import * as fs from "fs";
 import { Option } from "commander";
 import chalk from "chalk";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath } from "./cloud-provision.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -96,13 +96,7 @@ export function resolveCompanySlug(hqRoot, explicit) {
         throw new Error("Could not determine the active company — companies/manifest.yaml not found. " +
             "Re-run with --company <slug>.");
     }
-    let manifest;
-    try {
-        manifest = yaml.load(fs.readFileSync(mPath, "utf-8"));
-    }
-    catch (err) {
-        throw new Error(`companies/manifest.yaml is malformed: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const manifest = parseUserYaml(fs.readFileSync(mPath, "utf-8"), mPath);
     const slugs = activeCompanySlugs(manifest ?? {});
     if (slugs.length === 1)
         return slugs[0];

package/dist/commands/pkg-install.js

@@ -15,7 +15,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
@@ -117,7 +117,7 @@ async function installPackage(slug, company) {
         const packageYamlPath = path.resolve(installDir, 'package.yaml');
         if (fs.existsSync(packageYamlPath)) {
             const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-            const pkgMeta = yaml.load(pkgContent);
+            const pkgMeta = parseUserYaml(pkgContent, packageYamlPath);
             if (pkgMeta?.slug && pkgMeta.slug !== slug) {
                 // Mismatch — clean up and abort
                 fs.rmSync(installDir, { recursive: true, force: true });
@@ -137,7 +137,7 @@ async function installPackage(slug, company) {
             const packageYaml = path.resolve(installDir, 'package.yaml');
             if (fs.existsSync(packageYaml)) {
                 const content = fs.readFileSync(packageYaml, 'utf-8');
-                const meta = yaml.load(content);
+                const meta = parseUserYaml(content, packageYaml);
                 if (meta?.version)
                     version = meta.version;
                 if (meta?.name)

package/dist/commands/pkg-update.js

@@ -7,7 +7,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
@@ -92,7 +92,7 @@ async function updatePackages(slug) {
                 const packageYamlPath = path.resolve(installDir, 'package.yaml');
                 if (fs.existsSync(packageYamlPath)) {
                     const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-                    const pkgMeta = yaml.load(pkgContent);
+                    const pkgMeta = parseUserYaml(pkgContent, packageYamlPath);
                     if (pkgMeta?.slug && pkgMeta.slug !== entry.slug) {
                         fs.rmSync(installDir, { recursive: true, force: true });
                         throw new Error(`Package slug mismatch: expected "${entry.slug}", got "${pkgMeta.slug}"`);

package/dist/commands/publish.js

@@ -31,6 +31,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
@@ -91,7 +92,7 @@ export function stampAuthorYaml(manifest, author) {
 /** Read package.yaml, stamp author, write it back. Returns the stamped author. */
 export function stampAuthorIntoPackage(payloadDir, author) {
     const manifestPath = path.join(payloadDir, 'package.yaml');
-    const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+    const parsed = parseUserYaml(fs.readFileSync(manifestPath, 'utf-8'), manifestPath);
     fs.writeFileSync(manifestPath, stampAuthorYaml(parsed, author));
 }
 // ---------------------------------------------------------------------------

package/dist/commands/workers.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
@@ -11,7 +12,7 @@ export function readWorkerRegistry(hqRoot) {
     const p = path.join(hqRoot, "core/workers/registry.yaml");
     if (!fs.existsSync(p))
         return [];
-    const doc = yaml.load(fs.readFileSync(p, "utf8"));
+    const doc = parseUserYaml(fs.readFileSync(p, "utf8"), p);
     return doc?.workers ?? [];
 }
 /**
@@ -87,7 +88,7 @@ export function writeGrantSidecar(hqRoot, workerPath, principalLabel) {
     const sidecar = path.join(dir, ".grants.yaml");
     let grants = [];
     if (fs.existsSync(sidecar)) {
-        const doc = yaml.load(fs.readFileSync(sidecar, "utf8"));
+        const doc = parseUserYaml(fs.readFileSync(sidecar, "utf8"), sidecar);
         if (Array.isArray(doc?.grants))
             grants = doc.grants.filter((g) => typeof g === "string");
     }

package/dist/utils/manifest.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from './user-yaml-error.js';
 const MANIFEST_FILE = 'modules.yaml';
 const LOCK_FILE = 'modules.lock';
 const STATE_FILE = '.hq-sync-state.json';
@@ -51,7 +52,7 @@ export function readManifest(hqRoot) {
         return null;
     }
     const content = fs.readFileSync(manifestPath, 'utf-8');
-    return yaml.load(content);
+    return parseUserYaml(content, manifestPath);
 }
 export function writeManifest(hqRoot, manifest) {
     const manifestPath = getManifestPath(hqRoot);
@@ -68,7 +69,7 @@ export function readLock(hqRoot) {
         return null;
     }
     const content = fs.readFileSync(lockPath, 'utf-8');
-    return yaml.load(content);
+    return parseUserYaml(content, lockPath);
 }
 export function writeLock(hqRoot, lock) {
     const lockPath = getLockPath(hqRoot);

package/dist/utils/people.js

@@ -16,7 +16,7 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "./user-yaml-error.js";
 /**
  * Company slugs map directly onto a filesystem path segment, so we validate
  * them before joining to keep a malicious or fat-fingered `--company` value
@@ -45,13 +45,7 @@ export function companyPeopleDir(hqRoot, companySlug) {
  * surfaced as a half-row. Exported for unit testing.
  */
 export function parsePersonMeta(raw, slug, source) {
-    let doc;
-    try {
-        doc = yaml.load(raw);
-    }
-    catch (err) {
-        throw new Error(`Failed to parse ${source}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const doc = parseUserYaml(raw, source);
     if (!doc || typeof doc !== "object")
         return null;
     const d = doc;

package/dist/utils/registry-client.js

@@ -6,8 +6,8 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
 import { resolveDefaultHqRoot } from './cognito-session.js';
+import { parseUserYaml } from './user-yaml-error.js';
 // ---------------------------------------------------------------------------
 // URL helper (unchanged from US-004)
 // ---------------------------------------------------------------------------
@@ -23,7 +23,7 @@ export function getRegistryUrl() {
         throw new Error(`No packages/sources.yaml found at ${sourcesPath}. Is your HQ packages directory set up?`);
     }
     const content = fs.readFileSync(sourcesPath, 'utf-8');
-    const parsed = yaml.load(content);
+    const parsed = parseUserYaml(content, sourcesPath);
     if (!parsed?.sources?.length) {
         throw new Error('No sources defined in packages/sources.yaml');
     }

package/dist/utils/registry.js

@@ -4,6 +4,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from './user-yaml-error.js';
 function registryPath(hqRoot) {
     return path.resolve(hqRoot, 'packages', 'registry.yaml');
 }
@@ -17,7 +18,7 @@ export function readRegistry(hqRoot) {
         return [];
     }
     const content = fs.readFileSync(filePath, 'utf-8');
-    const parsed = yaml.load(content);
+    const parsed = parseUserYaml(content, filePath);
     return parsed?.packages ?? [];
 }
 /**

package/dist/utils/user-yaml-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse YAML supplied from an on-disk HQ file.
+ *
+ * YAML syntax is user-correctable content, not an hq-cli defect. js-yaml's
+ * default error includes a source excerpt, which can inadvertently echo
+ * secrets, so replace it with a concise, actionable location instead.
+ */
+export declare function parseUserYaml<T>(content: string, filePath: string): T;
+//# sourceMappingURL=user-yaml-error.d.ts.map

package/dist/utils/user-yaml-error.js

@@ -0,0 +1,25 @@
+import * as yaml from "js-yaml";
+/**
+ * Parse YAML supplied from an on-disk HQ file.
+ *
+ * YAML syntax is user-correctable content, not an hq-cli defect. js-yaml's
+ * default error includes a source excerpt, which can inadvertently echo
+ * secrets, so replace it with a concise, actionable location instead.
+ */
+export function parseUserYaml(content, filePath) {
+    try {
+        return yaml.load(content, { filename: filePath });
+    }
+    catch (err) {
+        if (!(err instanceof yaml.YAMLException))
+            throw err;
+        const line = err.mark ? err.mark.line + 1 : undefined;
+        const column = err.mark ? err.mark.column + 1 : undefined;
+        const location = line !== undefined && column !== undefined
+            ? `:${line}:${column}`
+            : "";
+        throw Object.assign(new Error(`Invalid YAML in ${filePath}${location}: ${err.reason}. ` +
+            "Fix the indentation or syntax and try again."), { expected: true });
+    }
+}
+//# sourceMappingURL=user-yaml-error.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.77.2",
+  "version": "5.77.4",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/cloud-demote.ts

@@ -31,6 +31,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { Command } from "commander";
 import chalk from "chalk";
 
@@ -98,7 +99,7 @@ export function flipCompanyYamlCloudOff(hqRoot: string, slug: string): boolean {
   const yPath = path.join(companyDirPath(hqRoot, slug), "company.yaml");
   if (!fs.existsSync(yPath)) return false;
   const raw = fs.readFileSync(yPath, "utf-8");
-  const parsed = (yaml.load(raw) as Record<string, unknown> | null) ?? {};
+  const parsed = parseUserYaml<Record<string, unknown> | null>(raw, yPath) ?? {};
   if (parsed.cloud === false) return false;
   parsed.cloud = false;
   const dump = yaml.dump(parsed, { lineWidth: -1, noRefs: true });
@@ -120,7 +121,7 @@ export function stripManifestCloudForSlug(hqRoot: string, slug: string): boolean
   const mPath = manifestPath(hqRoot);
   if (!fs.existsSync(mPath)) return false;
   const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = (yaml.load(raw) as { companies?: Record<string, unknown> } | null) ?? {};
+  const parsed = parseUserYaml<{ companies?: Record<string, unknown> } | null>(raw, mPath) ?? {};
   const companies = parsed.companies;
   if (!companies || !(slug in companies)) return false;
   const entry = companies[slug];

package/src/commands/cloud-provision.ts

@@ -33,6 +33,7 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 
 import { share } from "@indigoai-us/hq-cloud";
 
@@ -255,7 +256,7 @@ export function validateManifestAndDir(
     );
   }
   const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = yaml.load(raw) as unknown;
+  const parsed = parseUserYaml<unknown>(raw, mPath);
   if (
     !parsed ||
     typeof parsed !== "object" ||
@@ -411,7 +412,7 @@ export function patchManifest(
 ): boolean {
   const mPath = manifestPath(hqRoot);
   const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = (yaml.load(raw) as ManifestDoc) ?? { companies: {} };
+  const parsed = parseUserYaml<ManifestDoc | null>(raw, mPath) ?? { companies: {} };
   if (!parsed.companies) parsed.companies = {};
   const existing = parsed.companies[slug];
   // Preserve null / object / unknown — promote null → {} so we can write keys.

package/src/commands/files-recovery.test.ts

@@ -308,18 +308,20 @@ describe("hq files trash", () => {
 });
 
 describe("hq files recovery command help", () => {
-  it("documents the finalized --version and --prefix option forms", () => {
+  it("documents the finalized --version-id and --prefix option forms", () => {
     const program = buildProgram();
     const files = program.commands.find((command) => command.name() === "files");
     const restore = files?.commands.find((command) => command.name() === "restore");
     const trash = files?.commands.find((command) => command.name() === "trash");
 
     expect(files?.helpInformation()).toContain("versions [options] <path>");
-    expect(restore?.helpInformation()).toContain("--version <id>");
+    expect(files?.helpInformation()).toContain("restore --version-id <id>");
+    expect(restore?.helpInformation()).toContain("--version-id <id>");
+    expect(restore?.helpInformation()).not.toContain("--version <id>");
     expect(trash?.helpInformation()).toContain("--prefix <prefix>");
   });
 
-  it("passes --version to the restore request", async () => {
+  it("passes --version-id to the restore request", async () => {
     fetchSpy.mockResolvedValueOnce(membershipResponse());
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(200, {
@@ -331,7 +333,14 @@ describe("hq files recovery command help", () => {
     );
 
     await buildProgram().parseAsync(
-      ["files", "restore", "notes/a.md", "--version", "old-version", "--yes"],
+      [
+        "files",
+        "restore",
+        "notes/a.md",
+        "--version-id",
+        "old-version",
+        "--yes",
+      ],
       { from: "user" },
     );
 

package/src/commands/files.ts

@@ -515,7 +515,7 @@ export function registerFilesCommand(program: Command): Command {
   files
     .command("versions <path>")
     .description(
-      "List prior content versions and delete markers for one exact vault key. Use --personal for your personal vault.",
+      "List prior content versions and delete markers for one exact vault key. Restore a listed version with restore --version-id <id>. Use --personal for your personal vault.",
     )
     .option(
       "--personal",
@@ -539,18 +539,18 @@ export function registerFilesCommand(program: Command): Command {
   files
     .command("restore <path>")
     .description(
-      "Restore a prior version or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.",
+      "Restore a prior version with --version-id or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.",
     )
     .option(
       "--personal",
       "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
     )
-    .option("--version <id>", "Content version ID to restore")
+    .option("--version-id <id>", "Content version ID to restore")
     .option("-y, --yes", "Skip the overwrite confirmation prompt (for scripts)")
     .action(
       async (
         path: string,
-        opts: { personal?: boolean; yes?: boolean; version?: string },
+        opts: { personal?: boolean; yes?: boolean; versionId?: string },
       ) => {
         try {
           const companySlug = files.opts().company as string | undefined;
@@ -558,7 +558,7 @@ export function registerFilesCommand(program: Command): Command {
           assertRecoveryScope(personal, companySlug);
           await runFilesRestore({
             key: path,
-            versionId: opts.version,
+            versionId: opts.versionId,
             yes: opts.yes === true,
             personal,
             companySlug,

package/src/commands/pack-install.ts

@@ -38,7 +38,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import {
   createHash,
   createPublicKey,
@@ -1261,8 +1261,11 @@ export function validateManifest(
   }
   let parsed: unknown;
   try {
-    parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+    parsed = parseUserYaml(fs.readFileSync(manifestPath, 'utf-8'), manifestPath);
   } catch (e) {
+    if (e instanceof Error && (e as { expected?: unknown }).expected === true) {
+      throw e;
+    }
     throw new Error(`package.yaml invalid YAML: ${(e as Error).message}`);
   }
   const m = parsed as Partial<PackManifest> & Record<string, unknown>;

package/src/commands/people.test.ts

@@ -19,6 +19,7 @@ import {
   resolveNameToEmail,
   type PersonRecord,
 } from "../utils/people.js";
+import { isExpectedUserError } from "../utils/expected-cli-error.js";
 import {
   activeMemberToPersonRecord,
   mergePeople,
@@ -138,9 +139,17 @@ describe("parsePersonMeta", () => {
   });
 
   it("throws on unparseable yaml", () => {
-    expect(() => parsePersonMeta("name: [unterminated\n", "x", "/x")).toThrow(
-      /Failed to parse/,
-    );
+    const error = (() => {
+      try {
+        parsePersonMeta("name: [unterminated\n", "x", "/x");
+      } catch (err) {
+        return err;
+      }
+      throw new Error("expected malformed YAML to throw");
+    })();
+
+    expect(isExpectedUserError(error)).toBe(true);
+    expect((error as Error).message).toContain("Invalid YAML in /x:2:1");
   });
 });
 

package/src/commands/people.ts

@@ -15,7 +15,7 @@
 import * as fs from "fs";
 import { Command, Option } from "commander";
 import chalk from "chalk";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath, type ManifestDoc } from "./cloud-provision.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -146,14 +146,10 @@ export function resolveCompanySlug(
         "Re-run with --company <slug>.",
     );
   }
-  let manifest: ManifestDoc;
-  try {
-    manifest = yaml.load(fs.readFileSync(mPath, "utf-8")) as ManifestDoc;
-  } catch (err) {
-    throw new Error(
-      `companies/manifest.yaml is malformed: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
+  const manifest = parseUserYaml<ManifestDoc>(
+    fs.readFileSync(mPath, "utf-8"),
+    mPath,
+  );
   const slugs = activeCompanySlugs(manifest ?? {});
   if (slugs.length === 1) return slugs[0];
   if (slugs.length === 0) {

package/src/commands/pkg-install.ts

@@ -16,7 +16,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -157,7 +157,7 @@ async function installPackage(
     const packageYamlPath = path.resolve(installDir, 'package.yaml');
     if (fs.existsSync(packageYamlPath)) {
       const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-      const pkgMeta = yaml.load(pkgContent) as { slug?: string } | null;
+      const pkgMeta = parseUserYaml<{ slug?: string } | null>(pkgContent, packageYamlPath);
       if (pkgMeta?.slug && pkgMeta.slug !== slug) {
         // Mismatch — clean up and abort
         fs.rmSync(installDir, { recursive: true, force: true });
@@ -179,10 +179,10 @@ async function installPackage(
       const packageYaml = path.resolve(installDir, 'package.yaml');
       if (fs.existsSync(packageYaml)) {
         const content = fs.readFileSync(packageYaml, 'utf-8');
-        const meta = yaml.load(content) as {
+        const meta = parseUserYaml<{
           version?: string;
           name?: string;
-        } | null;
+        } | null>(content, packageYaml);
         if (meta?.version) version = meta.version;
         if (meta?.name) name = meta.name;
       }

package/src/commands/pkg-update.ts

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -146,9 +146,9 @@ async function updatePackages(slug?: string): Promise<void> {
         const packageYamlPath = path.resolve(installDir, 'package.yaml');
         if (fs.existsSync(packageYamlPath)) {
           const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-          const pkgMeta = yaml.load(pkgContent) as {
+          const pkgMeta = parseUserYaml<{
             slug?: string;
-          } | null;
+          } | null>(pkgContent, packageYamlPath);
           if (pkgMeta?.slug && pkgMeta.slug !== entry.slug) {
             fs.rmSync(installDir, { recursive: true, force: true });
             throw new Error(

package/src/commands/publish.ts

@@ -32,6 +32,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from '../utils/user-yaml-error.js';
 import { execFileSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -124,7 +125,10 @@ export function stampAuthorIntoPackage(
   author: ResolvedAuthor,
 ): void {
   const manifestPath = path.join(payloadDir, 'package.yaml');
-  const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>;
+  const parsed = parseUserYaml<Record<string, unknown>>(
+    fs.readFileSync(manifestPath, 'utf-8'),
+    manifestPath,
+  );
   fs.writeFileSync(manifestPath, stampAuthorYaml(parsed, author));
 }
 

package/src/commands/workers.ts

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
+import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
@@ -26,9 +27,10 @@ export interface RegistryWorker {
 export function readWorkerRegistry(hqRoot: string): RegistryWorker[] {
   const p = path.join(hqRoot, "core/workers/registry.yaml");
   if (!fs.existsSync(p)) return [];
-  const doc = yaml.load(fs.readFileSync(p, "utf8")) as
-    | { workers?: RegistryWorker[] }
-    | null;
+  const doc = parseUserYaml<{ workers?: RegistryWorker[] } | null>(
+    fs.readFileSync(p, "utf8"),
+    p,
+  );
   return doc?.workers ?? [];
 }
 
@@ -120,9 +122,10 @@ export function writeGrantSidecar(
   const sidecar = path.join(dir, ".grants.yaml");
   let grants: string[] = [];
   if (fs.existsSync(sidecar)) {
-    const doc = yaml.load(fs.readFileSync(sidecar, "utf8")) as
-      | { grants?: string[] }
-      | null;
+    const doc = parseUserYaml<{ grants?: string[] } | null>(
+      fs.readFileSync(sidecar, "utf8"),
+      sidecar,
+    );
     if (Array.isArray(doc?.grants)) grants = doc!.grants.filter((g) => typeof g === "string");
   }
   if (!grants.includes(principalLabel)) grants.push(principalLabel);

package/src/utils/manifest.test.ts

@@ -28,6 +28,7 @@ import {
   writeManifest,
 } from './manifest.js';
 import type { ModulesManifest } from '../types.js';
+import { isExpectedUserError } from './expected-cli-error.js';
 
 let tmpRoot: string;
 
@@ -83,6 +84,24 @@ describe('getManifestPath', () => {
 });
 
 describe('readManifest / writeManifest round-trip', () => {
+  it('surfaces malformed user YAML with the manifest file and location', () => {
+    const nested = path.join(tmpRoot, 'modules', 'modules.yaml');
+    fs.mkdirSync(path.dirname(nested), { recursive: true });
+    fs.writeFileSync(nested, 'modules:\n  - name: hq\n bad: indentation\n');
+
+    const error = (() => {
+      try {
+        readManifest(tmpRoot);
+      } catch (err) {
+        return err;
+      }
+      throw new Error('expected malformed YAML to throw');
+    })();
+
+    expect(isExpectedUserError(error)).toBe(true);
+    expect((error as Error).message).toContain(`${nested}:3:2`);
+  });
+
   it('round-trips against the nested layout', () => {
     writeManifest(tmpRoot, sampleManifest);
 

package/src/utils/manifest.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import type { ModulesManifest, ModuleDefinition, ModuleLock, SyncState } from '../types.js';
+import { parseUserYaml } from './user-yaml-error.js';
 
 const MANIFEST_FILE = 'modules.yaml';
 const LOCK_FILE = 'modules.lock';
@@ -57,7 +58,7 @@ export function readManifest(hqRoot: string): ModulesManifest | null {
     return null;
   }
   const content = fs.readFileSync(manifestPath, 'utf-8');
-  return yaml.load(content) as ModulesManifest;
+  return parseUserYaml<ModulesManifest>(content, manifestPath);
 }
 
 export function writeManifest(hqRoot: string, manifest: ModulesManifest): void {
@@ -76,7 +77,7 @@ export function readLock(hqRoot: string): ModuleLock | null {
     return null;
   }
   const content = fs.readFileSync(lockPath, 'utf-8');
-  return yaml.load(content) as ModuleLock;
+  return parseUserYaml<ModuleLock>(content, lockPath);
 }
 
 export function writeLock(hqRoot: string, lock: ModuleLock): void {

package/src/utils/people.ts

@@ -17,7 +17,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import * as yaml from "js-yaml";
+import { parseUserYaml } from "./user-yaml-error.js";
 
 /** A single person/member record parsed from a `people/<slug>/meta.yaml`. */
 export interface PersonRecord {
@@ -76,14 +76,7 @@ export function parsePersonMeta(
   slug: string,
   source: string,
 ): PersonRecord | null {
-  let doc: unknown;
-  try {
-    doc = yaml.load(raw);
-  } catch (err) {
-    throw new Error(
-      `Failed to parse ${source}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
+  const doc = parseUserYaml<unknown>(raw, source);
   if (!doc || typeof doc !== "object") return null;
   const d = doc as Record<string, unknown>;
 

package/src/utils/registry-client.ts

@@ -7,8 +7,8 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
 import { resolveDefaultHqRoot } from './cognito-session.js';
+import { parseUserYaml } from './user-yaml-error.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -86,7 +86,7 @@ export function getRegistryUrl(): string {
   }
 
   const content = fs.readFileSync(sourcesPath, 'utf-8');
-  const parsed = yaml.load(content) as SourcesFile;
+  const parsed = parseUserYaml<SourcesFile>(content, sourcesPath);
 
   if (!parsed?.sources?.length) {
     throw new Error('No sources defined in packages/sources.yaml');

package/src/utils/registry.ts

@@ -5,6 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { parseUserYaml } from './user-yaml-error.js';
 
 export interface RegistryEntry {
   name: string;
@@ -35,7 +36,7 @@ export function readRegistry(hqRoot: string): RegistryEntry[] {
     return [];
   }
   const content = fs.readFileSync(filePath, 'utf-8');
-  const parsed = yaml.load(content) as RegistryFile | null;
+  const parsed = parseUserYaml<RegistryFile | null>(content, filePath);
   return parsed?.packages ?? [];
 }
 

package/src/utils/user-yaml-error.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { isExpectedUserError } from "./expected-cli-error.js";
+import { parseUserYaml } from "./user-yaml-error.js";
+
+describe("parseUserYaml", () => {
+  it("marks malformed user YAML as expected and names its file and location", () => {
+    const filePath = "/tmp/HQ/modules/modules.yaml";
+    const error = (() => {
+      try {
+        parseUserYaml('apiKey: "secret-do-not-echo"\nmodule:\n  name: hq\n bad: indentation\n', filePath);
+      } catch (err) {
+        return err;
+      }
+      throw new Error("expected malformed YAML to throw");
+    })();
+
+    expect(isExpectedUserError(error)).toBe(true);
+    expect((error as Error).message).toContain(
+      `Invalid YAML in ${filePath}:4:2: bad indentation of a mapping entry.`,
+    );
+    expect((error as Error).message).toContain("Fix the indentation or syntax and try again.");
+    expect((error as Error).message).not.toContain("secret-do-not-echo");
+  });
+});

package/src/utils/user-yaml-error.ts

@@ -0,0 +1,30 @@
+import * as yaml from "js-yaml";
+
+/**
+ * Parse YAML supplied from an on-disk HQ file.
+ *
+ * YAML syntax is user-correctable content, not an hq-cli defect. js-yaml's
+ * default error includes a source excerpt, which can inadvertently echo
+ * secrets, so replace it with a concise, actionable location instead.
+ */
+export function parseUserYaml<T>(content: string, filePath: string): T {
+  try {
+    return yaml.load(content, { filename: filePath }) as T;
+  } catch (err) {
+    if (!(err instanceof yaml.YAMLException)) throw err;
+
+    const line = err.mark ? err.mark.line + 1 : undefined;
+    const column = err.mark ? err.mark.column + 1 : undefined;
+    const location = line !== undefined && column !== undefined
+      ? `:${line}:${column}`
+      : "";
+
+    throw Object.assign(
+      new Error(
+        `Invalid YAML in ${filePath}${location}: ${err.reason}. ` +
+          "Fix the indentation or syntax and try again.",
+      ),
+      { expected: true as const },
+    );
+  }
+}