@indigoai-us/hq-cli 5.8.6 → 5.9.0

package/src/run/hq-plugin.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { internal } from 'varlock';
+import {
+  installHqPlugin,
+  prewarmHqSecrets,
+  type InstallHqPluginOpts,
+  type PluginState,
+} from './hq-plugin.js';
+
+// Prevent any test run from writing to ~/.hq/secrets-cache/. Each test uses a
+// unique uid (random suffix) so cross-test contamination in the in-memory store
+// is not possible even without clearing between tests.
+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 tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-plugin-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function makeMocks(overrides?: Partial<InstallHqPluginOpts>): InstallHqPluginOpts {
+  return {
+    resolveCompanyUid: async () => `test-uid-${Math.random().toString(36).slice(2)}`,
+    fetchBatch: async () => ({ secrets: [], errors: [] }),
+    ...overrides,
+  };
+}
+
+describe('hq-plugin', () => {
+  it('happy path: resolves hq() vars via batch fetch and cache', async () => {
+    const schemaPath = path.join(tmpDir, '.env.schema');
+    // Empty line after @hqCompany is required: varlock's env-spec parser only treats
+    // a decorator comment as a root (file-level) decorator when it is separated from the
+    // first var by a blank line. Without it, the decorator attaches to FOO as an item decorator.
+    fs.writeFileSync(schemaPath, `# @hqCompany("test")\n\nFOO=hq()\n`);
+
+    const uid = `test-uid-${Math.random().toString(36).slice(2)}`;
+    const mocks = makeMocks({
+      resolveCompanyUid: async () => uid,
+      fetchBatch: async (_uid, names) => ({
+        secrets: names.map((name) => ({ name, value: 'fixture-value' })),
+        errors: [],
+      }),
+    });
+
+    let state!: PluginState;
+    const graph = await internal.loadEnvGraph({
+      entryFilePaths: [schemaPath],
+      afterInit: async (g) => {
+        state = installHqPlugin(g, mocks);
+      },
+    });
+    await prewarmHqSecrets(graph, mocks, state);
+    await graph.resolveEnvValues();
+    expect(graph.getResolvedEnvObject().FOO).toBe('fixture-value');
+  });
+
+  it('missing-company-error: throws when no @hqCompany and no companyOverride', async () => {
+    const schemaPath = path.join(tmpDir, '.env.schema');
+    // Schema has hq() resolver but no @hqCompany annotation and no opts.companyOverride
+    fs.writeFileSync(schemaPath, `FOO=hq()\n`);
+
+    const mocks = makeMocks();
+
+    let state!: PluginState;
+    const graph = await internal.loadEnvGraph({
+      entryFilePaths: [schemaPath],
+      afterInit: async (g) => {
+        state = installHqPlugin(g, mocks);
+      },
+    });
+    await expect(prewarmHqSecrets(graph, mocks, state)).rejects.toThrow(
+      '@hqCompany("...") not declared and --company not passed',
+    );
+  });
+
+  it('batch-error-passthrough-403: forbidden error is surfaced as ResolutionError', async () => {
+    const schemaPath = path.join(tmpDir, '.env.schema');
+    // Empty line after @hqCompany is required: varlock's env-spec parser only treats
+    // a decorator comment as a root (file-level) decorator when it is separated from the
+    // first var by a blank line. Without it, the decorator attaches to FOO as an item decorator.
+    fs.writeFileSync(schemaPath, `# @hqCompany("test")\n\nFOO=hq()\n`);
+
+    const uid = `test-uid-${Math.random().toString(36).slice(2)}`;
+    const mocks = makeMocks({
+      resolveCompanyUid: async () => uid,
+      fetchBatch: async () => ({
+        secrets: [],
+        errors: [{ name: 'FOO', code: 'forbidden' }],
+      }),
+    });
+
+    let state!: PluginState;
+    const graph = await internal.loadEnvGraph({
+      entryFilePaths: [schemaPath],
+      afterInit: async (g) => {
+        state = installHqPlugin(g, mocks);
+      },
+    });
+    await prewarmHqSecrets(graph, mocks, state);
+    await graph.resolveEnvValues();
+    // varlock collects ResolutionErrors on ConfigItem.errors (not re-thrown from resolveEnvValues).
+    // We verify the per-item error contains the forbidden diagnostic.
+    const fooErrors = (graph as any).configSchema['FOO'].errors as Array<{ message: string }>;
+    expect(fooErrors.some((e) => e.message.includes('No read permission for secret "FOO"'))).toBe(true);
+  });
+});

package/src/run/hq-plugin.ts

@@ -0,0 +1,174 @@
+import { ResolutionError } from 'varlock/plugin-lib';
+import type { Resolver } from 'varlock/plugin-lib';
+import { readCache, writeCache } from '../utils/secrets-cache.js';
+
+export interface InstallHqPluginOpts {
+  companyOverride?: string;
+  resolveCompanyUid: (slug: string) => Promise<string>;
+  fetchBatch: (uid: string, names: string[]) => Promise<{
+    secrets: Array<{ name: string; value: string }>;
+    errors: Array<{ name: string; code: string; message?: string }>;
+  }>;
+}
+
+export interface PluginState {
+  schemaCompanySlug: string | null;
+  uid: string | null;
+  errorsByName: Map<string, { code: string; message?: string }>;
+}
+
+export function installHqPlugin(graph: any /* EnvGraph */, opts: InstallHqPluginOpts) {
+  const pluginState: 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: any;
+  try {
+    const fns = graph.registeredResolverFunctions as Record<string, unknown>;
+    const first = Object.values(fns)[0];
+    if (first == null) throw new Error('registeredResolverFunctions is empty');
+    const proto = Object.getPrototypeOf(first) as { prototype?: { process?: unknown } } | null;
+    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' as const, arrayMaxLength: 1 },
+      resolve: async function (this: HqResolver) {
+        // 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.
+    private _ownerKey?: string;
+
+    process(parent?: Parameters<Resolver['process']>[0]) {
+      super.process(parent);
+      if (parent != null && typeof (parent as { key?: unknown }).key === 'string') {
+        this._ownerKey = (parent as { key: string }).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: any) => {
+      const slug = decoratorValue.arrArgs?.[0]?.staticValue;
+      return typeof slug === 'string' ? slug : null;
+    },
+    execute: (slug: string | null) => {
+      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: any /* EnvGraph */,
+  opts: InstallHqPluginOpts,
+  state: PluginState,
+): Promise<void> {
+  const queue: Array<{ key: string; secretName: string }> = [];
+  for (const [key, item] of Object.entries(graph.configSchema)) {
+    const resolver = (item as any).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: string;
+  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<string, { code: string; message?: string }>();
+  for (const e of result.errors) {
+    errorsByName.set(e.name, { code: e.code, message: e.message });
+  }
+  state.errorsByName = errorsByName;
+  state.uid = uid;
+}

package/src/run/varlock-shape.test.ts

@@ -0,0 +1,57 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { internal } from 'varlock';
+// Resolver is a type-only export in varlock@1.0.0's plugin-lib.js (d.ts/JS mismatch);
+// the value is extracted at runtime from graph.registeredResolverFunctions below.
+import type { Resolver } from 'varlock/plugin-lib';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let RuntimeResolver: typeof Resolver;
+
+beforeAll(async () => {
+  // Spin up a minimal graph to access built-in resolvers registered by varlock.
+  // No schema files are needed — varlock registers built-in resolvers in afterInit.
+  await internal.loadEnvGraph({
+    entryFilePaths: [],
+    afterInit: async (graph) => {
+      const fns = (graph as any).registeredResolverFunctions as Record<string, unknown>;
+      const firstClass = Object.values(fns)[0];
+      if (firstClass == null) throw new Error('registeredResolverFunctions is empty — varlock API shape changed');
+      // Each registered class extends Resolver; its prototype chain gives us the base class.
+      RuntimeResolver = Object.getPrototypeOf(firstClass) as typeof Resolver;
+    },
+  });
+});
+
+describe('varlock 1.0.0 API shape smoke test', () => {
+  it('internal.loadEnvGraph is a function', () => {
+    expect(typeof internal.loadEnvGraph).toBe('function');
+  });
+
+  it('internal.EnvGraph is a function (class)', () => {
+    expect(typeof internal.EnvGraph).toBe('function');
+  });
+
+  it('EnvGraph.prototype.registerRootDecorator exists', () => {
+    expect(typeof internal.EnvGraph.prototype.registerRootDecorator).toBe('function');
+  });
+
+  it('EnvGraph.prototype.registerResolver exists', () => {
+    expect(typeof internal.EnvGraph.prototype.registerResolver).toBe('function');
+  });
+
+  it('EnvGraph.prototype.registerItemDecorator exists', () => {
+    expect(typeof internal.EnvGraph.prototype.registerItemDecorator).toBe('function');
+  });
+
+  it('EnvGraph.prototype.registerDataType exists', () => {
+    expect(typeof internal.EnvGraph.prototype.registerDataType).toBe('function');
+  });
+
+  it('Resolver.prototype.process exists', () => {
+    expect(typeof RuntimeResolver.prototype.process).toBe('function');
+  });
+
+  it('Resolver.prototype.resolve exists', () => {
+    expect(typeof RuntimeResolver.prototype.resolve).toBe('function');
+  });
+});

package/src/utils/vault-api.ts

@@ -0,0 +1,80 @@
+import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
+
+export interface VaultApiOptions {
+  token: string;
+  path: string;
+  method?: string;
+  body?: Record<string, unknown>;
+  query?: Record<string, string>;
+}
+
+export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
+  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,
+  });
+}
+
+interface MembershipEntry {
+  companyUid: string;
+  role: string;
+  status: string;
+  membershipKey: string;
+}
+
+async function resolveCompanyUid(token: string, slug: string): Promise<string> {
+  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 as Record<string, string>).error ?? res.statusText}`,
+    );
+  }
+  const data = (await res.json()) as { entity: { uid: string } };
+  return data.entity.uid;
+}
+
+async function resolveCompanyFromMemberships(token: string): Promise<string> {
+  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()) as { memberships: MembershipEntry[] };
+  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: string,
+  companySlug: string | undefined,
+): Promise<string> {
+  if (companySlug) {
+    return resolveCompanyUid(token, companySlug);
+  }
+  return resolveCompanyFromMemberships(token);
+}