@indigoai-us/hq-cloud 5.1.0 → 5.1.8

package/src/cli/invite.test.ts

@@ -0,0 +1,247 @@
+/**
+ * invite CLI command tests (VLT-7 US-002).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from "vitest";
+import { invite, listInvites, revokeInvite } from "./invite.js";
+import type { VaultServiceConfig } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const VAULT_CONFIG: VaultServiceConfig = {
+  apiUrl: "https://vault.test.example.com",
+  authToken: "test-token",
+};
+
+let fetchSpy: MockInstance<typeof fetch>;
+
+beforeEach(() => {
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// invite()
+// ---------------------------------------------------------------------------
+
+describe("invite", () => {
+  it("creates invite for email target and returns magic link", async () => {
+    // First call: entity.findBySlug to resolve company
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" } }),
+      )
+      // Second call: createInvite
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          membership: { membershipKey: "psn_1#cmp_abc", role: "member", status: "pending" },
+          inviteToken: "tok_secure123",
+        }),
+      );
+
+    const result = await invite({
+      target: "alice@example.com",
+      role: "member",
+      company: "acme",
+      vaultConfig: VAULT_CONFIG,
+      callerUid: "psn_admin",
+    });
+
+    expect(result.magicLink).toBe("hq://accept/tok_secure123");
+    expect(result.inviteToken).toBe("tok_secure123");
+    expect(result.membership.status).toBe("pending");
+  });
+
+  it("creates invite for person UID target", async () => {
+    // Company is already a UID — no entity lookup needed
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { membershipKey: "psn_bob#cmp_abc", role: "admin", status: "pending" },
+        inviteToken: "tok_456",
+      }),
+    );
+
+    const result = await invite({
+      target: "psn_bob",
+      role: "admin",
+      company: "cmp_abc",
+      vaultConfig: VAULT_CONFIG,
+      callerUid: "psn_admin",
+    });
+
+    expect(result.magicLink).toBe("hq://accept/tok_456");
+
+    // Should have called createInvite with personUid, not inviteeEmail
+    const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+    expect(body.personUid).toBe("psn_bob");
+    expect(body.inviteeEmail).toBeUndefined();
+  });
+
+  it("rejects --paths without --role guest", async () => {
+    await expect(
+      invite({
+        target: "alice@example.com",
+        role: "member",
+        paths: "docs/",
+        company: "acme",
+        vaultConfig: VAULT_CONFIG,
+        callerUid: "psn_admin",
+      }),
+    ).rejects.toThrow("--paths is only valid with --role guest");
+  });
+
+  it("allows --paths with --role guest", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" } }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          membership: { membershipKey: "psn_1#cmp_abc", role: "guest", status: "pending", allowedPrefixes: ["docs/", "shared/"] },
+          inviteToken: "tok_guest",
+        }),
+      );
+
+    const result = await invite({
+      target: "alice@example.com",
+      role: "guest",
+      paths: "docs/, shared/",
+      company: "acme",
+      vaultConfig: VAULT_CONFIG,
+      callerUid: "psn_admin",
+    });
+
+    expect(result.membership.allowedPrefixes).toEqual(["docs/", "shared/"]);
+
+    // Verify allowedPrefixes sent to API
+    const body = JSON.parse(fetchSpy.mock.calls[1][1]?.body as string);
+    expect(body.allowedPrefixes).toEqual(["docs/", "shared/"]);
+  });
+
+  it("maps VaultPermissionDeniedError to human-readable message", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" } }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(403, { message: "Admin required" }),
+      );
+
+    await expect(
+      invite({
+        target: "alice@example.com",
+        company: "acme",
+        vaultConfig: VAULT_CONFIG,
+        callerUid: "psn_member",
+      }),
+    ).rejects.toThrow("Permission denied — only admins and owners can invite members");
+  });
+
+  it("throws when no company specified", async () => {
+    await expect(
+      invite({
+        target: "alice@example.com",
+        vaultConfig: VAULT_CONFIG,
+        callerUid: "psn_admin",
+      }),
+    ).rejects.toThrow("No company specified");
+  });
+
+  it("maps VaultConflictError to human-readable message", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" } }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(409, { message: "Already exists" }),
+      );
+
+    await expect(
+      invite({
+        target: "alice@example.com",
+        company: "acme",
+        vaultConfig: VAULT_CONFIG,
+        callerUid: "psn_admin",
+      }),
+    ).rejects.toThrow("already has a membership or pending invite");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listInvites()
+// ---------------------------------------------------------------------------
+
+describe("listInvites", () => {
+  it("returns pending invites for a company", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" } }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          invites: [
+            { membershipKey: "psn_1#cmp_abc", status: "pending", role: "member" },
+            { membershipKey: "psn_2#cmp_abc", status: "pending", role: "guest" },
+          ],
+        }),
+      );
+
+    const invites = await listInvites({
+      company: "acme",
+      vaultConfig: VAULT_CONFIG,
+      callerUid: "psn_admin",
+    });
+
+    expect(invites).toHaveLength(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// revokeInvite()
+// ---------------------------------------------------------------------------
+
+describe("revokeInvite", () => {
+  it("revokes a pending invite", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" } }),
+      )
+      .mockResolvedValueOnce(new Response(null, { status: 204 }));
+
+    await expect(
+      revokeInvite({
+        tokenOrKey: "psn_1#cmp_abc",
+        company: "acme",
+        vaultConfig: VAULT_CONFIG,
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("maps 404 to human-readable message", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" } }),
+      )
+      .mockResolvedValueOnce(jsonResponse(404, { message: "Not found" }));
+
+    await expect(
+      revokeInvite({
+        tokenOrKey: "psn_1#cmp_abc",
+        company: "acme",
+        vaultConfig: VAULT_CONFIG,
+      }),
+    ).rejects.toThrow("Invite not found");
+  });
+});

package/src/cli/invite.ts

@@ -0,0 +1,180 @@
+/**
+ * `hq invite` command — create pending membership + magic link (VLT-7 US-002).
+ *
+ * Thin UX layer over VaultClient.createInvite(). Handles arg parsing,
+ * validation (paths only with guest role), and formats the magic link output.
+ */
+
+import type { VaultServiceConfig } from "../types.js";
+import {
+  VaultClient,
+  VaultAuthError,
+  VaultPermissionDeniedError,
+  VaultNotFoundError,
+  VaultConflictError,
+} from "../vault-client.js";
+import type { MembershipRole, Membership } from "../vault-client.js";
+
+export interface InviteOptions {
+  /** Target — email address or person slug/uid */
+  target: string;
+  /** Role for the invitee (default: member) */
+  role?: MembershipRole;
+  /** Comma-separated allowed prefixes (only valid with role=guest) */
+  paths?: string;
+  /** Company slug or UID (defaults to active company) */
+  company?: string;
+  /** Vault service config */
+  vaultConfig: VaultServiceConfig;
+  /** Caller's person UID */
+  callerUid: string;
+}
+
+export interface InviteResult {
+  inviteToken: string;
+  magicLink: string;
+  membership: Membership;
+}
+
+export interface InviteListOptions {
+  company?: string;
+  vaultConfig: VaultServiceConfig;
+  callerUid: string;
+}
+
+export interface InviteRevokeOptions {
+  tokenOrKey: string;
+  /** Company slug or UID — required so the server can authorize the caller */
+  company: string;
+  vaultConfig: VaultServiceConfig;
+}
+
+/**
+ * Create a pending membership invite and return a magic link.
+ */
+export async function invite(options: InviteOptions): Promise<InviteResult> {
+  const { target, role = "member", paths, company, vaultConfig, callerUid } = options;
+
+  // Validate: --paths only with --role guest
+  if (paths && role !== "guest") {
+    throw new Error("--paths is only valid with --role guest (allowedPrefixes are only meaningful for the guest role)");
+  }
+
+  const client = new VaultClient(vaultConfig);
+
+  // Resolve company UID
+  const companyUid = await resolveCompanyUid(client, company);
+
+  // Parse paths
+  const allowedPrefixes = paths
+    ? paths.split(",").map((p) => p.trim()).filter(Boolean)
+    : undefined;
+
+  // Determine if target is email or person identifier
+  const isEmail = target.includes("@");
+
+  try {
+    const result = await client.createInvite({
+      ...(isEmail ? { inviteeEmail: target } : { personUid: target }),
+      companyUid,
+      role,
+      allowedPrefixes,
+      invitedBy: callerUid,
+    });
+
+    const magicLink = `hq://accept/${result.inviteToken}`;
+
+    return {
+      inviteToken: result.inviteToken,
+      magicLink,
+      membership: result.membership,
+    };
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      throw new Error("Authentication failed — run `hq auth` to refresh your session");
+    }
+    if (err instanceof VaultPermissionDeniedError) {
+      throw new Error("Permission denied — only admins and owners can invite members");
+    }
+    if (err instanceof VaultConflictError) {
+      throw new Error("This person already has a membership or pending invite for this company");
+    }
+    throw err;
+  }
+}
+
+/**
+ * List pending invites for a company.
+ */
+export async function listInvites(options: InviteListOptions): Promise<Membership[]> {
+  const { company, vaultConfig } = options;
+  const client = new VaultClient(vaultConfig);
+  const companyUid = await resolveCompanyUid(client, company);
+
+  try {
+    return await client.listPendingInvites(companyUid);
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      throw new Error("Authentication failed — run `hq auth` to refresh your session");
+    }
+    if (err instanceof VaultPermissionDeniedError) {
+      throw new Error("Permission denied — only admins and owners can list invites");
+    }
+    throw err;
+  }
+}
+
+/**
+ * Revoke a pending invite.
+ */
+export async function revokeInvite(options: InviteRevokeOptions): Promise<void> {
+  const { tokenOrKey, company, vaultConfig } = options;
+  const client = new VaultClient(vaultConfig);
+  const companyUid = await resolveCompanyUid(client, company);
+
+  try {
+    await client.revokeMembership(tokenOrKey, companyUid);
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      throw new Error("Authentication failed — run `hq auth` to refresh your session");
+    }
+    if (err instanceof VaultPermissionDeniedError) {
+      throw new Error("Permission denied — only admins and owners can revoke invites");
+    }
+    if (err instanceof VaultNotFoundError) {
+      throw new Error("Invite not found — it may have already been accepted or revoked");
+    }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function resolveCompanyUid(
+  client: VaultClient,
+  companyRef?: string,
+): Promise<string> {
+  if (!companyRef) {
+    throw new Error(
+      "No company specified. Use --company <slug> or set up .hq/config.json",
+    );
+  }
+
+  // If already a UID, return it
+  if (companyRef.startsWith("cmp_")) {
+    return companyRef;
+  }
+
+  // Resolve slug → UID via entity registry
+  try {
+    const entity = await client.entity.findBySlug("company", companyRef);
+    return entity.uid;
+  } catch (err) {
+    if (err instanceof VaultNotFoundError) {
+      throw new Error(`Company "${companyRef}" not found in the vault registry`);
+    }
+    throw err;
+  }
+}

package/src/cli/promote.ts

@@ -0,0 +1,123 @@
+/**
+ * `hq promote` command — change an existing member's role (VLT-7 US-003).
+ *
+ * Admin+ only. Surfaces last-owner demotion errors as human messages.
+ */
+
+import type { VaultServiceConfig } from "../types.js";
+import {
+  VaultClient,
+  VaultAuthError,
+  VaultPermissionDeniedError,
+  VaultNotFoundError,
+  VaultConflictError,
+} from "../vault-client.js";
+import type { MembershipRole, Membership } from "../vault-client.js";
+
+export interface PromoteOptions {
+  /** Person slug or UID of the member to promote */
+  target: string;
+  /** New role to assign */
+  newRole: MembershipRole;
+  /** Allowed prefixes (only valid with guest role) */
+  paths?: string;
+  /** Company slug or UID */
+  company?: string;
+  /** Caller's person UID */
+  callerUid: string;
+  /** Vault service config */
+  vaultConfig: VaultServiceConfig;
+}
+
+export interface PromoteResult {
+  membership: Membership;
+  previousRole?: MembershipRole;
+}
+
+/**
+ * Change a member's role.
+ */
+export async function promote(options: PromoteOptions): Promise<PromoteResult> {
+  const { target, newRole, paths, company, callerUid, vaultConfig } = options;
+
+  // Validate: --paths only with guest role
+  if (paths && newRole !== "guest") {
+    throw new Error("--paths is only valid with --role guest (allowedPrefixes are only meaningful for the guest role)");
+  }
+
+  const client = new VaultClient(vaultConfig);
+
+  // Resolve company UID
+  const companyUid = await resolveCompanyUid(client, company);
+
+  // Build membership key from target + company
+  const membershipKey = buildMembershipKey(target, companyUid);
+
+  const allowedPrefixes = paths
+    ? paths.split(",").map((p) => p.trim()).filter(Boolean)
+    : undefined;
+
+  try {
+    const membership = await client.updateRole({
+      membershipKey,
+      newRole,
+      allowedPrefixes,
+      updaterUid: callerUid,
+      companyUid,
+    });
+
+    return { membership };
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      throw new Error("Authentication failed — run `hq auth` to refresh your session");
+    }
+    if (err instanceof VaultPermissionDeniedError) {
+      throw new Error("Permission denied — only admins and owners can change member roles");
+    }
+    if (err instanceof VaultNotFoundError) {
+      throw new Error(`Member "${target}" not found in this company`);
+    }
+    if (err instanceof VaultConflictError) {
+      throw new Error("Cannot leave company without an owner — promote another member to owner first");
+    }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildMembershipKey(personRef: string, companyUid: string): string {
+  // If already a composite key, use as-is
+  if (personRef.includes("#")) {
+    return personRef;
+  }
+  // Build composite key: personUid#companyUid
+  return `${personRef}#${companyUid}`;
+}
+
+async function resolveCompanyUid(
+  client: VaultClient,
+  companyRef?: string,
+): Promise<string> {
+  if (!companyRef) {
+    throw new Error(
+      "No company specified. Use --company <slug> or set up .hq/config.json",
+    );
+  }
+
+  if (companyRef.startsWith("cmp_")) {
+    return companyRef;
+  }
+
+  try {
+    const entity = await client.entity.findBySlug("company", companyRef);
+    return entity.uid;
+  } catch (err) {
+    if (err instanceof VaultNotFoundError) {
+      throw new Error(`Company "${companyRef}" not found in the vault registry`);
+    }
+    throw err;
+  }
+}

package/src/cli/share.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Unit tests for hq share command (VLT-5 US-002).
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { clearContextCache } from "../context.js";
+import type { VaultServiceConfig } from "../types.js";
+
+// Mock s3 module at the top level
+vi.mock("../s3.js", () => ({
+  uploadFile: vi.fn().mockResolvedValue(undefined),
+  downloadFile: vi.fn().mockResolvedValue(undefined),
+  listRemoteFiles: vi.fn().mockResolvedValue([]),
+  deleteRemoteFile: vi.fn().mockResolvedValue(undefined),
+  headRemoteFile: vi.fn().mockResolvedValue(null),
+}));
+
+import { share } from "./share.js";
+import { headRemoteFile } from "../s3.js";
+
+const mockConfig: VaultServiceConfig = {
+  apiUrl: "https://vault-api.test",
+  authToken: "test-jwt-token",
+  region: "us-east-1",
+};
+
+const mockEntity = {
+  uid: "cmp_01ABCDEF",
+  slug: "acme",
+  bucketName: "hq-vault-acme-123",
+  status: "active",
+};
+
+const mockVendResponse = {
+  credentials: {
+    accessKeyId: "ASIA_TEST_KEY",
+    secretAccessKey: "test-secret",
+    sessionToken: "test-session-token",
+    expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+  },
+  expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+};
+
+function setupFetchMock() {
+  const fetchMock = vi.fn().mockImplementation(async (url: string) => {
+    const urlStr = String(url);
+    if (urlStr.includes("/entity/by-slug/")) {
+      return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+    }
+    if (urlStr.includes("/sts/vend")) {
+      return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+    }
+    return { ok: false, status: 404, text: async () => "Not found" };
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("share", () => {
+  let tmpDir: string;
+  let stateDir: string;
+
+  beforeEach(() => {
+    clearContextCache();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-share-test-"));
+    // Redirect per-company journal into tmp so share() doesn't write to the
+    // real ~/.hq during tests (ADR-0001 Phase 5).
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    setupFetchMock();
+    vi.mocked(headRemoteFile).mockResolvedValue(null);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
+  });
+
+  it("shares a single file", async () => {
+    const testFile = path.join(tmpDir, "test.md");
+    fs.writeFileSync(testFile, "# Hello World");
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesUploaded).toBe(1);
+    expect(result.aborted).toBe(false);
+  });
+
+  it("respects ignore rules", async () => {
+    fs.mkdirSync(path.join(tmpDir, ".git"));
+    fs.writeFileSync(path.join(tmpDir, ".git", "config"), "git config");
+    fs.writeFileSync(path.join(tmpDir, "readme.md"), "readme");
+
+    const result = await share({
+      paths: [tmpDir],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesUploaded).toBe(1);
+  });
+
+  it("shares a directory of files", async () => {
+    fs.mkdirSync(path.join(tmpDir, "docs"));
+    fs.writeFileSync(path.join(tmpDir, "docs", "a.md"), "doc a");
+    fs.writeFileSync(path.join(tmpDir, "docs", "b.md"), "doc b");
+
+    const result = await share({
+      paths: [path.join(tmpDir, "docs")],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesUploaded).toBe(2);
+  });
+
+  it("throws when no company specified and no active company", async () => {
+    fs.writeFileSync(path.join(tmpDir, "test.md"), "test");
+
+    await expect(
+      share({
+        paths: [path.join(tmpDir, "test.md")],
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      }),
+    ).rejects.toThrow(/No company specified/);
+  });
+
+  it("resolves active company from .hq/config.json", async () => {
+    fs.mkdirSync(path.join(tmpDir, ".hq"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, ".hq", "config.json"), JSON.stringify({ activeCompany: "acme" }));
+    fs.writeFileSync(path.join(tmpDir, "test.md"), "test");
+
+    const result = await share({
+      paths: [path.join(tmpDir, "test.md")],
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesUploaded).toBe(1);
+  });
+});