@indigoai-us/hq-cli 5.47.15 → 5.47.17

package/src/utils/feedback-screenshots.ts

@@ -0,0 +1,124 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { vaultApiFetch } from "./vault-api.js";
+
+export const MAX_SCREENSHOTS = 5;
+// Per-image ceiling. Screenshots are PNG/JPEG captures; 10 MB is generous.
+export const MAX_SCREENSHOT_BYTES = 10 * 1024 * 1024;
+
+// Extension → content type. Must stay in sync with the server's allowed set
+// (hq-pro feedback-screenshots.ts ALLOWED_CONTENT_TYPES).
+const EXT_CONTENT_TYPE: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+export function contentTypeForPath(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  const contentType = EXT_CONTENT_TYPE[ext];
+  if (!contentType) {
+    throw new Error(
+      `unsupported screenshot type: ${filePath} (allowed: ${Object.keys(EXT_CONTENT_TYPE).join(", ")})`,
+    );
+  }
+  return contentType;
+}
+
+export interface ScreenshotInput {
+  path: string;
+  contentType: string;
+  bytes: Buffer;
+}
+
+/** Validate + read the given screenshot paths (count, type, existence, size). */
+export function loadScreenshots(paths: string[]): ScreenshotInput[] {
+  if (paths.length > MAX_SCREENSHOTS) {
+    throw new Error(
+      `at most ${MAX_SCREENSHOTS} screenshots are allowed (got ${paths.length})`,
+    );
+  }
+  return paths.map((filePath) => {
+    const contentType = contentTypeForPath(filePath);
+    let bytes: Buffer;
+    try {
+      bytes = fs.readFileSync(filePath);
+    } catch {
+      throw new Error(`cannot read screenshot: ${filePath}`);
+    }
+    if (bytes.byteLength === 0) {
+      throw new Error(`screenshot is empty: ${filePath}`);
+    }
+    if (bytes.byteLength > MAX_SCREENSHOT_BYTES) {
+      throw new Error(
+        `screenshot too large: ${filePath} (${bytes.byteLength} bytes, max ${MAX_SCREENSHOT_BYTES})`,
+      );
+    }
+    return { path: filePath, contentType, bytes };
+  });
+}
+
+interface PresignResponse {
+  screenshots: Array<{ key: string; url: string; contentType: string }>;
+}
+
+/**
+ * Validate the screenshot paths, request presigned PUT URLs from the feedback
+ * endpoint, upload each image direct to S3, and return the object keys to
+ * attach to the feedback submission. Returns [] for no screenshots.
+ *
+ * `fetchImpl` is injectable for tests; defaults to the global fetch.
+ */
+export async function uploadScreenshots(opts: {
+  paths: string[];
+  token: string;
+  fetchImpl?: typeof fetch;
+}): Promise<string[]> {
+  if (opts.paths.length === 0) return [];
+  const inputs = loadScreenshots(opts.paths);
+
+  const res = await vaultApiFetch({
+    token: opts.token,
+    path: "/v1/feedback/screenshots/presign",
+    method: "POST",
+    body: { contentTypes: inputs.map((i) => i.contentType) },
+  });
+  if (!res.ok) {
+    const data = await res.json().catch(() => ({}));
+    const msg =
+      data &&
+      typeof data === "object" &&
+      typeof (data as { error?: unknown }).error === "string"
+        ? (data as { error: string }).error
+        : res.statusText;
+    throw new Error(`Failed to presign screenshots: ${msg}`);
+  }
+  const parsed = (await res.json()) as PresignResponse;
+  if (
+    !parsed ||
+    !Array.isArray(parsed.screenshots) ||
+    parsed.screenshots.length !== inputs.length
+  ) {
+    throw new Error("Presign response did not match the requested screenshots");
+  }
+
+  const doFetch = opts.fetchImpl ?? fetch;
+  const keys: string[] = [];
+  for (let i = 0; i < inputs.length; i++) {
+    const slot = parsed.screenshots[i]!;
+    const put = await doFetch(slot.url, {
+      method: "PUT",
+      headers: { "Content-Type": slot.contentType },
+      body: inputs[i]!.bytes,
+    });
+    if (!put.ok) {
+      throw new Error(
+        `Failed to upload screenshot ${inputs[i]!.path}: HTTP ${put.status}`,
+      );
+    }
+    keys.push(slot.key);
+  }
+  return keys;
+}

package/src/utils/feedback-versions.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+vi.mock("./manifest.js", () => ({
+  findHqRoot: vi.fn(() => "/fake/hq"),
+}));
+vi.mock("./pack-contributions.js", () => ({
+  readHqVersion: vi.fn(() => "15.0.20"),
+}));
+
+import { findHqRoot } from "./manifest.js";
+import { readHqVersion } from "./pack-contributions.js";
+import { CLI_VERSION } from "../cli-version.js";
+import {
+  collectVersions,
+  readCoreVersion,
+  readSyncVersion,
+} from "./feedback-versions.js";
+
+describe("readSyncVersion", () => {
+  let tmpHome: string;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "hqsync-"));
+    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
+  });
+  afterEach(() => {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  function writeMarker(contents: string): void {
+    fs.writeFileSync(path.join(tmpHome, ".hq", "sync-version.json"), contents);
+  }
+
+  it("reads the version the hq-sync app records", () => {
+    writeMarker(JSON.stringify({ version: "0.8.22-beta.1", updatedAt: "x" }));
+    expect(readSyncVersion(tmpHome)).toBe("0.8.22-beta.1");
+  });
+
+  it("returns null when the marker file is absent (hq-sync not installed)", () => {
+    expect(readSyncVersion(tmpHome)).toBeNull();
+  });
+
+  it("returns null on malformed JSON rather than throwing", () => {
+    writeMarker("{ not json");
+    expect(readSyncVersion(tmpHome)).toBeNull();
+  });
+
+  it("returns null when version is missing or not a non-empty string", () => {
+    writeMarker(JSON.stringify({ updatedAt: "x" }));
+    expect(readSyncVersion(tmpHome)).toBeNull();
+    writeMarker(JSON.stringify({ version: "" }));
+    expect(readSyncVersion(tmpHome)).toBeNull();
+    writeMarker(JSON.stringify({ version: 123 }));
+    expect(readSyncVersion(tmpHome)).toBeNull();
+  });
+});
+
+describe("readCoreVersion", () => {
+  beforeEach(() => {
+    vi.mocked(findHqRoot).mockReset().mockReturnValue("/fake/hq");
+    vi.mocked(readHqVersion).mockReset().mockReturnValue("15.0.20");
+  });
+
+  it("reads hqVersion from the resolved HQ root", () => {
+    expect(readCoreVersion()).toBe("15.0.20");
+    expect(readHqVersion).toHaveBeenCalledWith("/fake/hq");
+  });
+
+  it("returns null (never throws) when resolution fails", () => {
+    vi.mocked(findHqRoot).mockImplementation(() => {
+      throw new Error("no hq root");
+    });
+    expect(readCoreVersion()).toBeNull();
+  });
+
+  it("returns null when core.yaml has no hqVersion", () => {
+    vi.mocked(readHqVersion).mockReturnValue(null);
+    expect(readCoreVersion()).toBeNull();
+  });
+});
+
+describe("collectVersions", () => {
+  beforeEach(() => {
+    vi.mocked(findHqRoot).mockReset().mockReturnValue("/fake/hq");
+    vi.mocked(readHqVersion).mockReset().mockReturnValue("15.0.20");
+  });
+
+  it("always reports the cli version and best-effort core/sync", () => {
+    const versions = collectVersions();
+    expect(versions.cli).toBe(CLI_VERSION);
+    expect(versions.core).toBe("15.0.20");
+    // sync reads the real homedir marker, which won't exist in CI → null.
+    expect(["string", "object"]).toContain(typeof versions.sync); // string | null
+  });
+});

package/src/utils/feedback-versions.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CLI_VERSION } from "../cli-version.js";
+import { findHqRoot } from "./manifest.js";
+import { readHqVersion } from "./pack-contributions.js";
+
+/**
+ * The three HQ component versions captured from the submitter's environment
+ * and attached to a feedback submission so triage can see exactly which
+ * versions a report came from.
+ *
+ *   - `cli`  — this hq-cli build (always known).
+ *   - `core` — the HQ scaffold version from `core/core.yaml` (`hqVersion`);
+ *               null when the command runs outside an HQ tree.
+ *   - `sync` — the installed hq-sync menubar app version, which the app
+ *               records at `~/.hq/sync-version.json` on startup; null when
+ *               hq-sync is not installed (e.g. CLI-only / CI environments).
+ */
+export interface VersionInfo {
+  cli: string;
+  core: string | null;
+  sync: string | null;
+}
+
+/**
+ * Best-effort read of the hq-core scaffold version (`core/core.yaml`
+ * `hqVersion`). Resolves the HQ root from the working directory; returns
+ * null when no HQ root / core.yaml is found rather than throwing — version
+ * capture must never break a feedback submission.
+ */
+export function readCoreVersion(): string | null {
+  try {
+    return readHqVersion(findHqRoot());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort read of the hq-sync menubar app version. The app writes
+ * `{ version, updatedAt }` to `~/.hq/sync-version.json` on startup; the CLI
+ * reads it here. Returns null when the file is absent or malformed (hq-sync
+ * not installed, or an older build that predates the marker).
+ */
+export function readSyncVersion(homeDir: string = os.homedir()): string | null {
+  try {
+    const raw = fs.readFileSync(
+      path.join(homeDir, ".hq", "sync-version.json"),
+      "utf-8",
+    );
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    return typeof parsed.version === "string" && parsed.version.length > 0
+      ? parsed.version
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Collect all three component versions, each independently best-effort. */
+export function collectVersions(): VersionInfo {
+  return {
+    cli: CLI_VERSION,
+    core: readCoreVersion(),
+    sync: readSyncVersion(),
+  };
+}

package/src/utils/people.ts

@@ -0,0 +1,222 @@
+/**
+ * Company people (membership) directory reader + search.
+ *
+ * The local source of truth for "who belongs to a company" is the per-company
+ * people store on disk:
+ *
+ *     companies/<company-slug>/people/<person-slug>/meta.yaml
+ *
+ * Each `meta.yaml` carries at least `name` and `type` ("internal" | "external")
+ * plus optional `email`, `role`, `organization`, `tags`, etc. (see
+ * `companies/_template/people/_example/meta.yaml` for the canonical schema).
+ *
+ * Everything here is scoped to ONE company directory. Callers resolve a single
+ * company slug up front; nothing in this module ever enumerates or reads across
+ * company boundaries — HQ tenancy rules forbid cross-company member lookups.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+
+/** A single person/member record parsed from a `people/<slug>/meta.yaml`. */
+export interface PersonRecord {
+  /** Folder slug under `companies/<company>/people/<slug>/`. */
+  slug: string;
+  /** Display name (required field in `meta.yaml`). */
+  name: string;
+  /** Contact email, when recorded. */
+  email?: string;
+  /** "internal" (team member) | "external" (client, vendor, …). */
+  type?: string;
+  /** Role/title inside (or relative to) the company. */
+  role?: string;
+  /** External-only: the person's own organization. */
+  organization?: string;
+  /** Freeform tags for filtering. */
+  tags?: string[];
+  /** Absolute path to the `meta.yaml` this record was parsed from. */
+  source: string;
+}
+
+/**
+ * Company slugs map directly onto a filesystem path segment, so we validate
+ * them before joining to keep a malicious or fat-fingered `--company` value
+ * from escaping the `companies/` tree. Mirrors the slug rules used by
+ * cloud-provision.
+ */
+const COMPANY_SLUG_REGEX = /^[A-Za-z0-9._-]+$/;
+const FORBIDDEN_COMPANY_SLUGS = new Set(["personal", ".", ".."]);
+
+export function assertSafeCompanySlug(slug: string): void {
+  if (!slug || !COMPANY_SLUG_REGEX.test(slug)) {
+    throw new Error(
+      `Invalid company slug "${slug}" — must match ${COMPANY_SLUG_REGEX.source}`,
+    );
+  }
+  if (FORBIDDEN_COMPANY_SLUGS.has(slug)) {
+    throw new Error(`Company slug "${slug}" is reserved and cannot be used here`);
+  }
+}
+
+/** Absolute path to a company's `people/` directory. */
+export function companyPeopleDir(hqRoot: string, companySlug: string): string {
+  assertSafeCompanySlug(companySlug);
+  return path.join(hqRoot, "companies", companySlug, "people");
+}
+
+/**
+ * Parse a single `meta.yaml` body into a `PersonRecord`. Returns `null` when the
+ * file is empty, unparseable, or has no usable `name` — a person record without
+ * a name can't be listed, searched, or resolved, so it's skipped rather than
+ * surfaced as a half-row. Exported for unit testing.
+ */
+export function parsePersonMeta(
+  raw: string,
+  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)}`,
+    );
+  }
+  if (!doc || typeof doc !== "object") return null;
+  const d = doc as Record<string, unknown>;
+
+  const name = typeof d.name === "string" ? d.name.trim() : "";
+  if (!name) return null;
+
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.trim() ? v.trim() : undefined;
+
+  const tags = Array.isArray(d.tags)
+    ? d.tags.filter((t): t is string => typeof t === "string")
+    : undefined;
+
+  return {
+    slug,
+    name,
+    email: str(d.email),
+    type: str(d.type),
+    role: str(d.role),
+    organization: str(d.organization),
+    ...(tags && tags.length > 0 ? { tags } : {}),
+    source,
+  };
+}
+
+/**
+ * List every person recorded for ONE company. Reads
+ * `companies/<companySlug>/people/<personSlug>/meta.yaml` for each person
+ * folder.
+ *
+ * - Folders whose name starts with `_` are skipped (e.g. the `_example`
+ *   template that ships in `companies/_template/people/`).
+ * - Folders without a `meta.yaml`, or whose `meta.yaml` has no `name`, are
+ *   skipped silently — they aren't members yet.
+ * - Returns `[]` when the company has no `people/` directory at all.
+ *
+ * Results are sorted by name (case-insensitive) for stable output.
+ */
+export function listCompanyPeople(
+  hqRoot: string,
+  companySlug: string,
+): PersonRecord[] {
+  const dir = companyPeopleDir(hqRoot, companySlug);
+  if (!fs.existsSync(dir)) return [];
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const people: PersonRecord[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith("_")) continue; // _example and other scaffolding
+
+    const metaPath = path.join(dir, entry.name, "meta.yaml");
+    if (!fs.existsSync(metaPath)) continue;
+
+    const raw = fs.readFileSync(metaPath, "utf-8");
+    const record = parsePersonMeta(raw, entry.name, metaPath);
+    if (record) people.push(record);
+  }
+
+  people.sort((a, b) =>
+    a.name.localeCompare(b.name, undefined, { sensitivity: "base" }),
+  );
+  return people;
+}
+
+/**
+ * Case-insensitive keyword search over a person's NAME and EMAIL (plus the
+ * folder slug, which is a normalized alias of the name). Pure — operates on an
+ * already-loaded list so it's trivially testable and reusable.
+ *
+ * An empty/whitespace keyword matches nothing (callers should treat that as a
+ * usage error rather than "return everyone").
+ */
+export function searchPeople(
+  people: PersonRecord[],
+  keyword: string,
+): PersonRecord[] {
+  const needle = keyword.trim().toLowerCase();
+  if (!needle) return [];
+  return people.filter((p) => {
+    const haystacks = [p.name, p.email, p.slug].filter(
+      (v): v is string => typeof v === "string",
+    );
+    return haystacks.some((h) => h.toLowerCase().includes(needle));
+  });
+}
+
+/** Outcome of resolving a name to an email address. */
+export type ResolveResult =
+  | { status: "found"; email: string; person: PersonRecord }
+  | { status: "no_email"; person: PersonRecord }
+  | { status: "ambiguous"; matches: PersonRecord[] }
+  | { status: "not_found" };
+
+/**
+ * Resolve a person NAME to their email, built on top of {@link searchPeople}.
+ *
+ * Match precedence (narrowest first) so a precise query isn't drowned out by
+ * looser substring hits:
+ *   1. exact name match (case-insensitive, trimmed)
+ *   2. exact folder-slug match
+ *   3. substring search over name/email/slug
+ *
+ * The first tier that yields any match decides the result:
+ *   - exactly one match with an email  → `found`
+ *   - exactly one match, no email      → `no_email`
+ *   - more than one match              → `ambiguous` (caller disambiguates)
+ *   - no match in any tier             → `not_found`
+ */
+export function resolveNameToEmail(
+  people: PersonRecord[],
+  name: string,
+): ResolveResult {
+  const query = name.trim();
+  if (!query) return { status: "not_found" };
+  const lowered = query.toLowerCase();
+
+  const exactName = people.filter((p) => p.name.toLowerCase() === lowered);
+  const exactSlug = people.filter((p) => p.slug.toLowerCase() === lowered);
+  const substring = searchPeople(people, query);
+
+  const matches =
+    exactName.length > 0
+      ? exactName
+      : exactSlug.length > 0
+        ? exactSlug
+        : substring;
+
+  if (matches.length === 0) return { status: "not_found" };
+  if (matches.length > 1) return { status: "ambiguous", matches };
+
+  const person = matches[0];
+  if (!person.email) return { status: "no_email", person };
+  return { status: "found", email: person.email, person };
+}