@indigoai-us/hq-cli 5.8.5 → 5.9.0

package/dist/run/hq-plugin.js

@@ -0,0 +1,144 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="01fee323-1f63-5411-bfc9-ff49e241f712")}catch(e){}}();
+import { ResolutionError } from 'varlock/plugin-lib';
+import { readCache, writeCache } from '../utils/secrets-cache.js';
+export function installHqPlugin(graph /* EnvGraph */, opts) {
+    const pluginState = {
+        schemaCompanySlug: null,
+        uid: null,
+        errorsByName: new Map(),
+    };
+    // varlock@1.0.0's plugin-lib.js omits the Resolver export (d.ts/JS mismatch);
+    // extract it at runtime from any already-registered built-in resolver's prototype.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let RuntimeResolver;
+    try {
+        const fns = graph.registeredResolverFunctions;
+        const first = Object.values(fns)[0];
+        if (first == null)
+            throw new Error('registeredResolverFunctions is empty');
+        const proto = Object.getPrototypeOf(first);
+        if (proto == null || typeof proto.prototype?.process !== 'function') {
+            throw new Error('prototype has no process method');
+        }
+        RuntimeResolver = proto;
+    }
+    catch (e) {
+        throw new Error('varlock Resolver base class extraction failed — the varlock@1.0.0 d.ts/JS mismatch ' +
+            'may have been resolved; switch to `import { Resolver } from "varlock/plugin-lib"`. ' +
+            `Underlying: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // HqResolver is declared INSIDE installHqPlugin so its static def.resolve
+    // closes over `pluginState`. Module-scope declaration is forbidden — resolve()
+    // would hit `ReferenceError: pluginState is not defined`.
+    class HqResolver extends RuntimeResolver {
+        static def = {
+            name: 'hq',
+            impliesSensitive: true,
+            argsSchema: { type: 'array', arrayMaxLength: 1 },
+            resolve: async function () {
+                // Cache-only read. `pluginState` is captured by this inner-class closure;
+                // `prewarmHqSecrets(graph, opts, state)` populates `state.uid` and
+                // `state.errorsByName` before `graph.resolveEnvValues()` calls us.
+                const explicit = this.arrArgs?.[0]?.staticValue;
+                const secretName = (typeof explicit === 'string' && explicit) ? explicit : this._ownerKey;
+                if (!secretName) {
+                    throw new ResolutionError('hq() resolver could not determine secret name (missing owner key)');
+                }
+                const err = pluginState.errorsByName.get(secretName);
+                if (err) {
+                    if (err.code === 'forbidden') {
+                        throw new ResolutionError(`No read permission for secret "${secretName}" — ask an admin to share it via \`hq secrets share ${secretName} --with <you> --permission read\``);
+                    }
+                    if (err.code === 'not_found') {
+                        throw new ResolutionError(`Secret "${secretName}" does not exist in company`);
+                    }
+                    throw new ResolutionError(`Failed to load secret "${secretName}": ${err.message ?? err.code}`);
+                }
+                // Sentinel-check style throughout: `readCache` returns `string | null`
+                // (verified at `hq/packages/hq-cli/src/utils/secrets-cache.ts:45`); `pluginState.uid`
+                // is `string | null` per `PluginState`. Use `== null` (covers null AND undefined defensively)
+                // for both — do not mix in truthy checks like `if (!x)`, which would silently swallow a
+                // legitimate empty-string value if the contract ever loosened.
+                if (pluginState.uid == null) {
+                    throw new ResolutionError('Internal error: prewarmHqSecrets was not called before resolveEnvValues');
+                }
+                const cached = readCache(pluginState.uid, secretName); // string | null
+                if (cached == null) {
+                    throw new ResolutionError(`Internal error: pre-warm did not populate cache for "${secretName}"`);
+                }
+                return cached;
+            },
+        };
+        // Captured during process(parent); used by resolve() to fall back to the var key.
+        _ownerKey;
+        process(parent) {
+            super.process(parent);
+            if (parent != null && typeof parent.key === 'string') {
+                this._ownerKey = parent.key;
+            }
+        }
+    }
+    // varlock@1.0.0's env-spec parser rejects dots in decorator names ([a-zA-Z0-9_] only),
+    // so `@hq.company` is not valid syntax. We register as `@hqCompany` (camelCase) instead.
+    // Schema files must use `# @hqCompany("slug")` followed by a blank line so the parser
+    // treats it as a file-level root decorator rather than an item decorator for the next var.
+    graph.registerRootDecorator({
+        name: 'hqCompany',
+        isFunction: true,
+        process: (decoratorValue) => {
+            const slug = decoratorValue.arrArgs?.[0]?.staticValue;
+            return typeof slug === 'string' ? slug : null;
+        },
+        execute: (slug) => {
+            if (slug)
+                pluginState.schemaCompanySlug = slug;
+        },
+    });
+    graph.registerResolver(HqResolver);
+    // Returned so `prewarmHqSecrets(graph, opts, state)` can read schemaCompanySlug
+    // and write `uid` + `errorsByName`. The state is held by the closure; the returned handle
+    // is purely for the prewarm helper.
+    return pluginState;
+}
+export async function prewarmHqSecrets(graph /* EnvGraph */, opts, state) {
+    const queue = [];
+    for (const [key, item] of Object.entries(graph.configSchema)) {
+        const resolver = item.valueResolver;
+        if (resolver?.def?.name === 'hq') {
+            const explicit = resolver.arrArgs?.[0]?.staticValue;
+            const secretName = (typeof explicit === 'string' && explicit) ? explicit : key;
+            queue.push({ key, secretName });
+        }
+    }
+    if (queue.length === 0) {
+        return;
+    }
+    let slug;
+    if (state.schemaCompanySlug) {
+        slug = state.schemaCompanySlug;
+    }
+    else if (opts.companyOverride) {
+        slug = opts.companyOverride;
+    }
+    else {
+        throw new Error('@hqCompany("...") not declared and --company not passed');
+    }
+    const uid = await opts.resolveCompanyUid(slug);
+    const uniqueNames = [...new Set(queue.map((q) => q.secretName))];
+    if (uniqueNames.length > 100) {
+        throw new Error(`hq run supports at most 100 hq() resolvers per schema; got ${uniqueNames.length}`);
+    }
+    const result = await opts.fetchBatch(uid, uniqueNames);
+    for (const s of result.secrets) {
+        writeCache(uid, s.name, s.value);
+    }
+    const errorsByName = new Map();
+    for (const e of result.errors) {
+        errorsByName.set(e.name, { code: e.code, message: e.message });
+    }
+    state.errorsByName = errorsByName;
+    state.uid = uid;
+}
+//# sourceMappingURL=hq-plugin.js.map
+//# debugId=01fee323-1f63-5411-bfc9-ff49e241f712

package/dist/utils/vault-api.d.ts

@@ -0,0 +1,10 @@
+export interface VaultApiOptions {
+    token: string;
+    path: string;
+    method?: string;
+    body?: Record<string, unknown>;
+    query?: Record<string, string>;
+}
+export declare function vaultApiFetch(opts: VaultApiOptions): Promise<Response>;
+export declare function getCompanyUid(token: string, companySlug: string | undefined): Promise<string>;
+//# sourceMappingURL=vault-api.d.ts.map

package/dist/utils/vault-api.js

@@ -0,0 +1,58 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4e482805-d129-5563-a77b-97b80410154b")}catch(e){}}();
+import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
+export async function vaultApiFetch(opts) {
+    const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
+    if (opts.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+            url.searchParams.set(k, v);
+        }
+    }
+    return fetch(url.toString(), {
+        method: opts.method ?? 'GET',
+        headers: {
+            Authorization: `Bearer ${opts.token}`,
+            'Content-Type': 'application/json',
+        },
+        body: opts.body ? JSON.stringify(opts.body) : undefined,
+    });
+}
+async function resolveCompanyUid(token, slug) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/entity/by-slug/company/${encodeURIComponent(slug)}`,
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(`Failed to resolve company slug '${slug}': ${body.error ?? res.statusText}`);
+    }
+    const data = (await res.json());
+    return data.entity.uid;
+}
+async function resolveCompanyFromMemberships(token) {
+    const res = await vaultApiFetch({
+        token,
+        path: '/membership/me',
+    });
+    if (!res.ok) {
+        throw new Error("Failed to fetch memberships — run `hq login` and try again");
+    }
+    const data = (await res.json());
+    const active = data.memberships.filter((m) => m.status === 'active');
+    if (active.length === 0) {
+        throw new Error('No active company memberships found. Use --company <slug> to specify.');
+    }
+    if (active.length === 1) {
+        return active[0].companyUid;
+    }
+    const uids = active.map((m) => m.companyUid).join(', ');
+    throw new Error(`Multiple companies found (${uids}). Use --company <slug> to specify which one.`);
+}
+export async function getCompanyUid(token, companySlug) {
+    if (companySlug) {
+        return resolveCompanyUid(token, companySlug);
+    }
+    return resolveCompanyFromMemberships(token);
+}
+//# sourceMappingURL=vault-api.js.map
+//# debugId=4e482805-d129-5563-a77b-97b80410154b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.8.5",
+  "version": "5.9.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -21,7 +21,8 @@
     "commander": "^12.1.0",
     "js-yaml": "^4.1.0",
     "simple-git": "^3.27.0",
-    "semver": "^7.6.3"
+    "semver": "^7.6.3",
+    "varlock": "1.0.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
@@ -42,5 +43,8 @@
     "cloud"
   ],
   "license": "MIT",
-  "type": "module"
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  }
 }

package/src/commands/files.ts

@@ -154,20 +154,35 @@ export function registerFilesCommand(program: Command): void {
         const companySlug = files.opts().company as string | undefined;
         const companyUid = await getCompanyUid(token, companySlug);
 
-        const res = await vaultApiFetch({
-          token,
-          path: `/files/${encodeURIComponent(companyUid)}/acl`,
-          query: { prefix: canonicalPrefix },
-        });
+        // Fetch the prefix's own ACL row (creator, open flag, effective
+        // permission) and the inherited/descendant tree in parallel so the
+        // user sees every grant that affects this prefix in one shot.
+        const [aclRes, treeRes] = await Promise.all([
+          vaultApiFetch({
+            token,
+            path: `/files/${encodeURIComponent(companyUid)}/acl`,
+            query: { prefix: canonicalPrefix },
+          }),
+          vaultApiFetch({
+            token,
+            path: `/files/${encodeURIComponent(companyUid)}/acl/tree`,
+            query: { prefix: canonicalPrefix },
+          }),
+        ]);
 
-        if (!res.ok) {
-          const body = await res.json().catch(() => ({})) as Record<string, string>;
+        async function readErrorBody(res: Response): Promise<Record<string, string>> {
+          return (await res.json().catch(() => ({}))) as Record<string, string>;
+        }
+
+        // Auth/server failures from either call are treated identically — bail
+        // out with a single message rather than printing a half-rendered view.
+        for (const res of [aclRes, treeRes]) {
+          if (res.ok || res.status === 404) continue;
+          const body = await readErrorBody(res);
           if (res.status === 401) {
             console.error(chalk.red("Not authenticated — please run `hq login`"));
           } else if (res.status === 403) {
             console.error(chalk.red("Not authorized to view this file prefix's ACL"));
-          } else if (res.status === 404) {
-            console.error(chalk.red(`No ACL record exists for '${canonicalPrefix}'`));
           } else if (res.status >= 500) {
             console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
           } else {
@@ -176,7 +191,14 @@ export function registerFilesCommand(program: Command): void {
           process.exit(1);
         }
 
-        const data = await res.json() as {
+        type AclEntry = {
+          granteeType: string;
+          granteeId: string;
+          permission: string;
+          grantedBy: string;
+          grantedAt: string;
+        };
+        type AclResponse = {
           acl: {
             itemType: string;
             companyUid: string;
@@ -186,60 +208,98 @@ export function registerFilesCommand(program: Command): void {
             prefix?: string;
             creatorUid: string;
             open?: boolean;
-            entries: Array<{
-              granteeType: string;
-              granteeId: string;
-              permission: string;
-              grantedBy: string;
-              grantedAt: string;
-            }>;
+            entries: AclEntry[];
             effectivePermission?: string | null;
             createdAt: string;
             updatedAt: string;
           };
         };
+        type TreeResponse = {
+          prefix: string;
+          direct: AclEntry[];
+          inherited: Array<AclEntry & { sourcePrefix: string }>;
+          children: Array<AclEntry & { sourcePrefix: string }>;
+        };
+
+        const acl = aclRes.ok ? (await aclRes.json() as AclResponse).acl : null;
+        const tree = treeRes.ok ? (await treeRes.json()) as TreeResponse : null;
+
+        // No own row AND nothing inherited or granted below — original
+        // "no ACL record" exit path.
+        if (!acl && (!tree || (tree.inherited.length === 0 && tree.children.length === 0))) {
+          console.error(chalk.red(`No ACL record exists for '${canonicalPrefix}'`));
+          process.exit(1);
+        }
 
-        const acl = data.acl;
-        const aclStatus = acl.open ? "open" : "restricted";
-        const aclPrefix = acl.path ?? acl.prefix ?? canonicalPrefix;
+        const aclPrefix = acl?.path ?? acl?.prefix ?? tree?.prefix ?? canonicalPrefix;
+        const aclStatus = acl?.open ? "open" : "restricted";
 
         console.log(chalk.green(`ACL for ${aclPrefix} (${aclStatus})`));
-        console.log(`Creator: ${acl.creatorUid}`);
-        if (acl.effectivePermission) {
-          console.log(`Your effective permission: ${acl.effectivePermission}`);
+        if (acl) {
+          console.log(`Creator: ${acl.creatorUid}`);
+          if (acl.effectivePermission) {
+            console.log(`Your effective permission: ${acl.effectivePermission}`);
+          }
+        } else {
+          console.log(chalk.gray(
+            "No direct ACL row — access flows from the inherited/descendant grants below.",
+          ));
         }
 
-        if (acl.entries.length === 0) {
-          if (acl.open) {
+        function printEntryTable(
+          rows: Array<AclEntry & { sourcePrefix?: string }>,
+          showSource: boolean,
+        ): void {
+          const TYPE_W = Math.max(4, ...rows.map((e) => e.granteeType.length));
+          const GRANTEE_W = Math.max(7, ...rows.map((e) => e.granteeId.length));
+          const PERM_W = Math.max(10, ...rows.map((e) => e.permission.length));
+          const BY_W = Math.max(10, ...rows.map((e) => e.grantedBy.length));
+          const SRC_W = showSource
+            ? Math.max(6, ...rows.map((e) => (e.sourcePrefix ?? "").length))
+            : 0;
+          const headerCols = [
+            "TYPE".padEnd(TYPE_W),
+            "GRANTEE".padEnd(GRANTEE_W),
+            "PERMISSION".padEnd(PERM_W),
+            "GRANTED_BY".padEnd(BY_W),
+            "GRANTED_AT",
+          ];
+          if (showSource) headerCols.splice(4, 0, "SOURCE".padEnd(SRC_W));
+          console.log(chalk.bold(headerCols.join("  ")));
+          for (const e of rows) {
+            const grantedAt = e.grantedAt.slice(0, 10);
+            const cols = [
+              e.granteeType.padEnd(TYPE_W),
+              e.granteeId.padEnd(GRANTEE_W),
+              e.permission.padEnd(PERM_W),
+              e.grantedBy.padEnd(BY_W),
+              grantedAt,
+            ];
+            if (showSource) cols.splice(4, 0, (e.sourcePrefix ?? "").padEnd(SRC_W));
+            console.log(cols.join("  "));
+          }
+        }
+
+        const directEntries = acl?.entries ?? tree?.direct ?? [];
+        if (directEntries.length === 0) {
+          if (acl?.open) {
             console.log(chalk.gray("Open ACL — all active members have read access."));
-          } else {
-            console.log(chalk.gray("No explicit grants — only creator has access."));
+          } else if (acl) {
+            console.log(chalk.gray("No explicit grants on this prefix — only creator has access."));
           }
-          return;
+        } else {
+          console.log("\nDirect entries (granted on this prefix):");
+          printEntryTable(directEntries, false);
+        }
+
+        if (tree && tree.inherited.length > 0) {
+          console.log("\nInherited (granted on an ancestor prefix):");
+          printEntryTable(tree.inherited, true);
         }
 
-        console.log("Entries:");
-        const TYPE_W = Math.max(4, ...acl.entries.map((e) => e.granteeType.length));
-        const GRANTEE_W = Math.max(7, ...acl.entries.map((e) => e.granteeId.length));
-        const PERM_W = Math.max(10, ...acl.entries.map((e) => e.permission.length));
-        const BY_W = Math.max(10, ...acl.entries.map((e) => e.grantedBy.length));
-        const tableHeader = [
-          "TYPE".padEnd(TYPE_W),
-          "GRANTEE".padEnd(GRANTEE_W),
-          "PERMISSION".padEnd(PERM_W),
-          "GRANTED_BY".padEnd(BY_W),
-          "GRANTED_AT",
-        ].join("  ");
-        console.log(chalk.bold(tableHeader));
-        for (const e of acl.entries) {
-          const grantedAt = e.grantedAt.slice(0, 10);
-          console.log([
-            e.granteeType.padEnd(TYPE_W),
-            e.granteeId.padEnd(GRANTEE_W),
-            e.permission.padEnd(PERM_W),
-            e.grantedBy.padEnd(BY_W),
-            grantedAt,
-          ].join("  "));
+        if (tree && tree.children.length > 0) {
+          console.log("\nGranted on descendant prefixes (do not affect this prefix's access):");
+          printEntryTable(tree.children, true);
         }
       } catch (err) {
         console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));

package/src/commands/run.env-local.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { internal } from 'varlock';
+import { discoverSchemas } from '../run/discover-schemas.js';
+import { installHqPlugin, prewarmHqSecrets, type PluginState } from '../run/hq-plugin.js';
+
+vi.mock('../utils/secrets-cache.js', () => {
+  const store = new Map<string, string>();
+  return {
+    readCache: (uid: string, name: string): string | null =>
+      store.get(`${uid}\0${name}`) ?? null,
+    writeCache: (uid: string, name: string, value: string): void => {
+      store.set(`${uid}\0${name}`, value);
+    },
+    removeCacheEntry: (): void => {},
+    clearAllCache: (): { removed: number } => ({ removed: 0 }),
+  };
+});
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'hq-run-envlocal-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test('.env.local overrides hq()-resolved value', async () => {
+  // Blank line after @hqCompany required: varlock only treats it as a root (file-level)
+  // decorator when separated from the first var by a blank line.
+  writeFileSync(join(dir, '.env.schema'), '# @hqCompany("indigo")\n\n# @required\nKEY=hq()\n');
+  writeFileSync(join(dir, '.env.local'), 'KEY=local-value\n');
+
+  const result = discoverSchemas(dir);
+  expect(result.schemaPaths).toEqual([join(dir, '.env.schema')]);
+  expect(result.envLocalPaths).toEqual([join(dir, '.env.local')]);
+
+  const paths = [...result.schemaPaths, ...result.envLocalPaths];
+  const opts = {
+    companyOverride: undefined,
+    resolveCompanyUid: async () => 'fake-uid',
+    // fetchBatch returns "vault-value" — if .env.local is correctly wired,
+    // graph resolution should still surface "local-value" because the local
+    // file wins precedence.
+    fetchBatch: async () => ({ secrets: [{ name: 'KEY', value: 'vault-value' }], errors: [] }),
+  };
+
+  let state!: PluginState;
+  const graph = await internal.loadEnvGraph({
+    entryFilePaths: paths,
+    afterInit: (g) => { state = installHqPlugin(g, opts); },
+  });
+  await prewarmHqSecrets(graph, opts, state);
+  await graph.resolveEnvValues();
+  expect(graph.getResolvedEnvObject().KEY).toBe('local-value');
+});
+
+test('without .env.local, vault value is returned', async () => {
+  writeFileSync(join(dir, '.env.schema'), '# @hqCompany("indigo")\n\n# @required\nKEY=hq()\n');
+
+  const result = discoverSchemas(dir);
+  expect(result.schemaPaths).toEqual([join(dir, '.env.schema')]);
+  expect(result.envLocalPaths).toEqual([]);
+
+  const paths = [...result.schemaPaths, ...result.envLocalPaths];
+  const opts = {
+    companyOverride: undefined,
+    resolveCompanyUid: async () => 'fake-uid',
+    fetchBatch: async () => ({ secrets: [{ name: 'KEY', value: 'vault-value' }], errors: [] }),
+  };
+
+  let state!: PluginState;
+  const graph = await internal.loadEnvGraph({
+    entryFilePaths: paths,
+    afterInit: (g) => { state = installHqPlugin(g, opts); },
+  });
+  await prewarmHqSecrets(graph, opts, state);
+  await graph.resolveEnvValues();
+  expect(graph.getResolvedEnvObject().KEY).toBe('vault-value');
+});

package/src/commands/run.ts

@@ -0,0 +1,137 @@
+import { Command } from 'commander';
+import { spawn } from 'node:child_process';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { internal } from 'varlock';
+import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
+import { discoverSchemas } from '../run/discover-schemas.js';
+import { installHqPlugin, prewarmHqSecrets, type PluginState, type InstallHqPluginOpts } from '../run/hq-plugin.js';
+
+export function registerRunCommand(program: Command): void {
+  program
+    .command('run')
+    .description('Load secrets from .env.schema and run a command with them injected')
+    .option('--company <slug>', 'Company slug (overrides @hqCompany in schema)')
+    .option('--schema <path>', 'Explicit schema path (skips walk-up discovery)')
+    .option('--check', 'Resolve schema and validate vars without executing the command')
+    .allowUnknownOption(true)
+    .action(async (opts: { company?: string; schema?: string; check?: boolean }) => {
+      try {
+        const dashIndex = process.argv.indexOf('--');
+        const childArgs = dashIndex !== -1 ? process.argv.slice(dashIndex + 1) : [];
+
+        if (!opts.check && childArgs.length === 0) {
+          throw new Error('no command specified. Usage: hq run [options] -- <command> [args...]');
+        }
+
+        let schemaPaths: string[];
+        let envLocalPaths: string[];
+        let schemaCompanySlug: string | null;
+
+        if (opts.schema) {
+          const schemaAbs = path.resolve(opts.schema);
+          schemaPaths = [schemaAbs];
+          const localPath = path.join(path.dirname(schemaAbs), '.env.local');
+          envLocalPaths = fs.existsSync(localPath) ? [localPath] : [];
+          const content = fs.readFileSync(schemaAbs, 'utf8');
+          const m = /^# @hqCompany\("([^"]+)"\)/m.exec(content);
+          schemaCompanySlug = m ? m[1] : null;
+        } else {
+          const discovered = discoverSchemas(process.cwd());
+          if (discovered.conflict) {
+            throw new Error(
+              `conflicting @hqCompany slugs: "${discovered.conflict.slugs[0]}" in ${discovered.conflict.paths[0]} vs "${discovered.conflict.slugs[1]}" in ${discovered.conflict.paths[1]}. Use --company <slug> to override.`,
+            );
+          }
+          if (discovered.schemaPaths.length === 0) {
+            throw new Error('no .env.schema found. Create one or use --schema <path>.');
+          }
+          schemaPaths = discovered.schemaPaths;
+          envLocalPaths = discovered.envLocalPaths;
+          schemaCompanySlug = discovered.companySlug;
+        }
+
+        const slug = opts.company ?? schemaCompanySlug;
+        if (!slug) {
+          throw new Error('company slug not set. Add # @hqCompany("slug") to your .env.schema or pass --company <slug>.');
+        }
+
+        const token = await ensureCognitoToken();
+        const uid = await getCompanyUid(token, slug);
+
+        const fetchBatch: InstallHqPluginOpts['fetchBatch'] = async (companyUid, names) => {
+          const res = await vaultApiFetch({
+            token,
+            path: `/secrets/${encodeURIComponent(companyUid)}/load`,
+            method: 'POST',
+            body: { names },
+          });
+          if (!res.ok) {
+            const body = await res.json().catch(() => ({})) as Record<string, string>;
+            throw new Error(`Failed to batch-load secrets: ${body.error ?? res.statusText}`);
+          }
+          return res.json() as Promise<{
+            secrets: Array<{ name: string; value: string }>;
+            errors: Array<{ name: string; code: string; message?: string }>;
+          }>;
+        };
+
+        const pluginOpts: InstallHqPluginOpts = {
+          companyOverride: opts.company,
+          resolveCompanyUid: async () => uid,
+          fetchBatch,
+        };
+
+        // LAST entry = highest precedence; .env.local files trail .env.schema files so any .env.local beats any schema regardless of depth.
+        const paths = [...schemaPaths, ...envLocalPaths];
+
+        let state!: PluginState;
+        const graph = await internal.loadEnvGraph({
+          entryFilePaths: paths,
+          afterInit: async (g) => { state = installHqPlugin(g, pluginOpts); },
+        });
+        await prewarmHqSecrets(graph, pluginOpts, state);
+        await graph.resolveEnvValues();
+
+        const schemaErrors = Object.entries(graph.configSchema as Record<string, any>)
+          .filter(([, item]) => (item.errors as unknown[])?.length > 0);
+        if (schemaErrors.length > 0) {
+          const msgs = schemaErrors.flatMap(([k, item]) =>
+            (item.errors as Array<{ message?: string }>).map((e) => `  ${k}: ${e.message ?? String(e)}`),
+          );
+          process.stderr.write(`Error: failed to resolve env vars:\n${msgs.join('\n')}\n`);
+          process.exit(1);
+        }
+
+        const resolvedEnv = graph.getResolvedEnvObject() as Record<string, string>;
+        const varCount = Object.keys(resolvedEnv).length;
+        process.stderr.write(`Loaded ${varCount} env vars from .env.schema (company: ${slug})\n`);
+
+        if (opts.check) {
+          process.exit(0);
+        }
+
+        const [childCmd, ...restArgs] = childArgs;
+        const child = spawn(childCmd, restArgs, {
+          stdio: 'inherit',
+          env: { ...process.env, ...resolvedEnv },
+        });
+
+        child.on('error', (err) => {
+          process.stderr.write(`Error: failed to start command '${childCmd}': ${err.message}\n`);
+          process.exit(1);
+        });
+
+        child.on('close', (code, signal) => {
+          if (signal) {
+            process.kill(process.pid, signal);
+          }
+          process.exit(code ?? 1);
+        });
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+      }
+    });
+}