@indigoai-us/hq-cloud 5.1.0 → 5.1.9

package/src/cli/conflict.ts

@@ -0,0 +1,119 @@
+/**
+ * Conflict resolution for hq share/sync (VLT-5 US-002).
+ *
+ * Interactive prompts in terminal mode; deterministic resolution via
+ * --on-conflict flag for worker/skill callers.
+ */
+
+import * as fs from "fs";
+import * as readline from "readline";
+
+export type ConflictStrategy = "overwrite" | "keep" | "abort";
+
+export interface ConflictInfo {
+  path: string;
+  localHash?: string;
+  remoteHash?: string;
+  localModified?: Date;
+  remoteModified?: Date;
+  direction: "push" | "pull";
+}
+
+export type ConflictResolution = "overwrite" | "keep" | "skip" | "diff" | "abort";
+
+/**
+ * Resolve a conflict interactively or via strategy flag.
+ *
+ * In non-interactive mode (strategy provided), returns deterministically:
+ *   overwrite → "overwrite"
+ *   keep → "keep"
+ *   abort → "abort"
+ *
+ * In interactive mode (strategy undefined), prompts the user.
+ */
+export async function resolveConflict(
+  conflict: ConflictInfo,
+  strategy?: ConflictStrategy,
+): Promise<ConflictResolution> {
+  if (strategy) {
+    return strategy === "abort" ? "abort" : strategy;
+  }
+
+  return promptConflict(conflict);
+}
+
+async function promptConflict(conflict: ConflictInfo): Promise<ConflictResolution> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+
+  const direction = conflict.direction === "push"
+    ? "Remote has a newer version"
+    : "Local file has uncommitted edits";
+
+  console.error(`\n  Conflict: ${conflict.path}`);
+  console.error(`  ${direction}`);
+  if (conflict.localModified) {
+    console.error(`  Local modified:  ${conflict.localModified.toISOString()}`);
+  }
+  if (conflict.remoteModified) {
+    console.error(`  Remote modified: ${conflict.remoteModified.toISOString()}`);
+  }
+
+  const options = conflict.direction === "push"
+    ? "[o]verwrite remote / [k]eep remote / [d]iff / [a]bort"
+    : "[o]verwrite local / [k]eep local / [d]iff / [s]kip";
+
+  const answer = await new Promise<string>((resolve) => {
+    rl.question(`  ${options}: `, (ans) => {
+      rl.close();
+      resolve(ans.trim().toLowerCase());
+    });
+  });
+
+  switch (answer) {
+    case "o":
+    case "overwrite":
+      return "overwrite";
+    case "k":
+    case "keep":
+      return "keep";
+    case "d":
+    case "diff":
+      return "diff";
+    case "s":
+    case "skip":
+      return "skip";
+    case "a":
+    case "abort":
+      return "abort";
+    default:
+      // Default to keep (safe option)
+      console.error("  Unrecognized choice, keeping current version.");
+      return "keep";
+  }
+}
+
+/**
+ * Show a simple diff between local and remote content.
+ * Returns the content strings for display.
+ */
+export function showDiff(
+  localPath: string,
+  remoteContent: Buffer,
+): void {
+  const localContent = fs.existsSync(localPath)
+    ? fs.readFileSync(localPath, "utf-8")
+    : "(file does not exist locally)";
+  const remoteStr = remoteContent.toString("utf-8");
+
+  console.error("\n--- LOCAL ---");
+  console.error(localContent.slice(0, 2000));
+  if (localContent.length > 2000) console.error("... (truncated)");
+
+  console.error("\n--- REMOTE ---");
+  console.error(remoteStr.slice(0, 2000));
+  if (remoteStr.length > 2000) console.error("... (truncated)");
+  console.error("");
+}

package/src/cli/index.ts

@@ -0,0 +1,25 @@
+/**
+ * hq-cloud CLI entry points.
+ *
+ * Registers `hq share`, `hq sync`, and membership commands.
+ * These are consumed by @indigoai-us/hq-cli or invoked directly.
+ */
+
+export { share } from "./share.js";
+export type { ShareOptions, ShareResult } from "./share.js";
+
+export { sync } from "./sync.js";
+export type { SyncOptions, SyncResult, SyncProgressEvent } from "./sync.js";
+
+export { resolveConflict, showDiff } from "./conflict.js";
+export type { ConflictStrategy, ConflictInfo, ConflictResolution } from "./conflict.js";
+
+// Membership commands (VLT-7)
+export { invite, listInvites, revokeInvite } from "./invite.js";
+export type { InviteOptions, InviteResult, InviteListOptions, InviteRevokeOptions } from "./invite.js";
+
+export { accept, parseToken } from "./accept.js";
+export type { AcceptOptions, AcceptResult } from "./accept.js";
+
+export { promote } from "./promote.js";
+export type { PromoteOptions, PromoteResult } from "./promote.js";

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