@indigoai-us/hq-cli 5.8.6 → 5.9.0

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);
+      }
+    });
+}

package/src/commands/secrets.ts

@@ -2,10 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
-import {
-  ensureCognitoToken,
-  DEFAULT_VAULT_API_URL,
-} from "../utils/cognito-session.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
 import {
   readCache,
   writeCache,
@@ -13,14 +10,9 @@ import {
   clearAllCache,
 } from "../utils/secrets-cache.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN } from "./_patterns.js";
-
-export interface VaultApiOptions {
-  token: string;
-  path: string;
-  method?: string;
-  body?: Record<string, unknown>;
-  query?: Record<string, string>;
-}
+import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+export type { VaultApiOptions } from "../utils/vault-api.js";
+export { vaultApiFetch, getCompanyUid };
 
 function shellSingleQuote(value: string): string {
   return "'" + value.replace(/'/g, "'\\''") + "'";
@@ -37,82 +29,6 @@ function buildSecretNamePath(companyUid: string, name: string): string {
   return `/secrets/${encodeURIComponent(companyUid)}/name/${encodedName}`;
 }
 
-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,
-  });
-}
-
-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;
-}
-
-interface MembershipEntry {
-  companyUid: string;
-  role: string;
-  status: string;
-  membershipKey: string;
-}
-
-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);
-}
-
 function parseDuration(input: string): number | null {
   const match = input.match(/^(\d+)(m|h|d)$/);
   if (!match) return null;

package/src/index.ts

@@ -23,6 +23,7 @@ import { registerPackageListCommand } from "./commands/pkg-list.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
+import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
 import { registerFilesCommand } from "./commands/files.js";
 
@@ -90,6 +91,9 @@ registerAuthCommands(program);
 // Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
 registerSecretsCommand(program);
 
+// Schema-driven dev runner — hq run [options] -- <cmd>
+registerRunCommand(program);
+
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
 registerGroupsCommand(program);
 

package/src/run/__fixtures__/discover-schemas/example.env.schema

@@ -0,0 +1,4 @@
+# @hqCompany("example-co")
+
+DATABASE_URL=hq()
+API_KEY=hq()

package/src/run/discover-schemas.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { discoverSchemas } from './discover-schemas.js';
+
+let tmpDir: string;
+
+// Helper: create directory + optional files inside it.
+function mkDir(...segments: string[]): string {
+  const dir = path.join(tmpDir, ...segments);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function writeFile(dir: string, name: string, content: string): string {
+  const p = path.join(dir, name);
+  fs.writeFileSync(p, content);
+  return p;
+}
+
+// Every temp tree gets a .git/ at the root so the walk-up never escapes tmpDir.
+function makeRoot(): string {
+  const root = mkDir('root');
+  fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+  return root;
+}
+
+const SCHEMA_CO_A = '# @hqCompany("co-a")\n\nFOO=hq()\n';
+const SCHEMA_CO_B = '# @hqCompany("co-b")\n\nBAR=hq()\n';
+const SCHEMA_CO_E = '# @hqCompany("co-e")\n\nFOO=hq()\n';
+const SCHEMA_CO_F = '# @hqCompany("co-f")\n\nFOO=hq()\n';
+const SCHEMA_CO_G = '# @hqCompany("co-g")\n\nFOO=hq()\n';
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discover-schemas-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe('discoverSchemas', () => {
+  // (a) Single schema in cwd — schemaPaths length 1, envLocalPaths length 0, slug matches.
+  it('(a) single schema in cwd', () => {
+    const root = makeRoot();
+    const cwd = mkDir('root', 'cwd');
+    writeFile(cwd, '.env.schema', SCHEMA_CO_A);
+
+    const result = discoverSchemas(cwd);
+
+    expect(result.schemaPaths).toHaveLength(1);
+    expect(result.schemaPaths[0]).toBe(path.join(cwd, '.env.schema'));
+    expect(result.envLocalPaths).toHaveLength(0);
+    expect(result.companySlug).toBe('co-a');
+    expect(result.conflict).toBeNull();
+  });
+
+  // (b) Parent + child both have schemas with same slug — schemaPaths length 2 (parent first, child last).
+  it('(b) parent and child schemas with same slug', () => {
+    const root = makeRoot();
+    const parent = mkDir('root', 'parent');
+    const child = mkDir('root', 'parent', 'child');
+    writeFile(parent, '.env.schema', SCHEMA_CO_A);
+    writeFile(child, '.env.schema', SCHEMA_CO_A);
+
+    const result = discoverSchemas(child);
+
+    expect(result.schemaPaths).toHaveLength(2);
+    expect(result.schemaPaths[0]).toBe(path.join(parent, '.env.schema')); // parent first
+    expect(result.schemaPaths[1]).toBe(path.join(child, '.env.schema'));  // child last (cwd-closest)
+    expect(result.companySlug).toBe('co-a');
+    expect(result.conflict).toBeNull();
+  });
+
+  // (c) Parent has slug A, child has slug B — conflict reported with both paths and both slugs.
+  it('(c) conflicting slugs', () => {
+    const root = makeRoot();
+    const parent = mkDir('root', 'parent');
+    const child = mkDir('root', 'parent', 'child');
+    writeFile(parent, '.env.schema', SCHEMA_CO_A);
+    writeFile(child, '.env.schema', SCHEMA_CO_B);
+
+    const result = discoverSchemas(child);
+
+    expect(result.schemaPaths).toHaveLength(2);
+    expect(result.companySlug).toBeNull();
+    expect(result.conflict).not.toBeNull();
+    expect(result.conflict!.paths).toContain(path.join(parent, '.env.schema'));
+    expect(result.conflict!.paths).toContain(path.join(child, '.env.schema'));
+    expect(result.conflict!.slugs).toContain('co-a');
+    expect(result.conflict!.slugs).toContain('co-b');
+  });
+
+  // (d) No schema found from cwd up — empty result.
+  it('(d) no schema found', () => {
+    const root = makeRoot();
+    const cwd = mkDir('root', 'cwd');
+
+    const result = discoverSchemas(cwd);
+
+    expect(result.schemaPaths).toHaveLength(0);
+    expect(result.envLocalPaths).toHaveLength(0);
+    expect(result.companySlug).toBeNull();
+    expect(result.conflict).toBeNull();
+  });
+
+  // (e) Schema at cwd PLUS sibling .env.local — schemaPaths length 1, envLocalPaths length 1.
+  it('(e) schema with sibling .env.local', () => {
+    const root = makeRoot();
+    const cwd = mkDir('root', 'cwd');
+    writeFile(cwd, '.env.schema', SCHEMA_CO_E);
+    writeFile(cwd, '.env.local', 'FOO=local-override\n');
+
+    const result = discoverSchemas(cwd);
+
+    expect(result.schemaPaths).toHaveLength(1);
+    expect(result.envLocalPaths).toHaveLength(1);
+    expect(result.envLocalPaths[0]).toBe(path.join(cwd, '.env.local'));
+    expect(result.companySlug).toBe('co-e');
+  });
+
+  // (f) Repo-root has .env.schema next to .git/, cwd is grandchild — schemaPaths length 1
+  //     pointing at repo-root (.git/-containing dir IS included).
+  it('(f) schema at .git root, cwd is grandchild', () => {
+    const root = makeRoot(); // root has .git/ already
+    writeFile(root, '.env.schema', SCHEMA_CO_F);
+    const child = mkDir('root', 'child');
+    const grandchild = mkDir('root', 'child', 'grandchild');
+
+    const result = discoverSchemas(grandchild);
+
+    expect(result.schemaPaths).toHaveLength(1);
+    expect(result.schemaPaths[0]).toBe(path.join(root, '.env.schema'));
+    expect(result.companySlug).toBe('co-f');
+  });
+
+  // (g) Parent has .env.local but no schema, child has schema — envLocalPaths length 0
+  //     (.env.local collected ONLY when next to a .env.schema).
+  it('(g) .env.local without schema in parent is ignored', () => {
+    const root = makeRoot();
+    const parent = mkDir('root', 'parent');
+    const child = mkDir('root', 'parent', 'child');
+    writeFile(parent, '.env.local', 'PARENT_ONLY=1\n');
+    writeFile(child, '.env.schema', SCHEMA_CO_G);
+
+    const result = discoverSchemas(child);
+
+    expect(result.schemaPaths).toHaveLength(1);
+    expect(result.envLocalPaths).toHaveLength(0);
+    expect(result.companySlug).toBe('co-g');
+  });
+});

package/src/run/discover-schemas.ts

@@ -0,0 +1,79 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface SchemaConflict {
+  paths: [string, string];
+  slugs: [string, string];
+}
+
+export interface DiscoverSchemasResult {
+  schemaPaths: string[];
+  envLocalPaths: string[];
+  companySlug: string | null;
+  conflict: SchemaConflict | null;
+}
+
+const SLUG_RE = /^# @hqCompany\("([^"]+)"\)/m;
+
+function parseSlug(filePath: string): string | null {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const m = SLUG_RE.exec(content);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+export function discoverSchemas(cwd: string): DiscoverSchemasResult {
+  const schemaPaths: string[] = [];
+  const envLocalPaths: string[] = [];
+
+  let dir = path.resolve(cwd);
+
+  while (true) {
+    const schemaPath = path.join(dir, '.env.schema');
+    if (fs.existsSync(schemaPath)) {
+      schemaPaths.push(schemaPath);
+      const localPath = path.join(dir, '.env.local');
+      if (fs.existsSync(localPath)) {
+        envLocalPaths.push(localPath);
+      }
+    }
+
+    const isGitRoot = fs.existsSync(path.join(dir, '.git'));
+    if (isGitRoot) break;
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+
+  // cwd-closest is pushed last during walk-up, so reversing puts it last.
+  // (During walk-up cwd is checked first → pushed first → reversed → ends up last.)
+  schemaPaths.reverse();
+  envLocalPaths.reverse();
+
+  let companySlug: string | null = null;
+  let companySlugPath: string | null = null;
+  let conflict: SchemaConflict | null = null;
+
+  for (const schemaPath of schemaPaths) {
+    const slug = parseSlug(schemaPath);
+    if (slug == null) continue;
+
+    if (companySlug == null) {
+      companySlug = slug;
+      companySlugPath = schemaPath;
+    } else if (companySlug !== slug) {
+      conflict = {
+        paths: [companySlugPath!, schemaPath],
+        slugs: [companySlug, slug],
+      };
+      companySlug = null;
+      break;
+    }
+  }
+
+  return { schemaPaths, envLocalPaths, companySlug, conflict };
+}