@hexclave/cli 1.0.67 → 1.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexclave/cli",
-  "version": "1.0.67",
+  "version": "1.0.68",
   "repository": "https://github.com/hexclave/hexclave",
   "description": "The CLI for Hexclave. https://hexclave.com",
   "main": "dist/index.js",
@@ -25,9 +25,9 @@
     "commander": "^13.1.0",
     "extract-zip": "^2.0.1",
     "jiti": "^2.4.2",
-    "@hexclave/shared-backend": "1.0.67",
-    "@hexclave/shared": "1.0.67",
-    "@hexclave/js": "1.0.67"
+    "@hexclave/shared-backend": "1.0.68",
+    "@hexclave/js": "1.0.68",
+    "@hexclave/shared": "1.0.68"
   },
   "devDependencies": {
     "@types/node": "20.17.6",

package/src/commands/init.ts

@@ -277,11 +277,9 @@ async function handleCreateCloud(_flags: Record<string, unknown>, opts: InitOpti
   const sessionAuth = await ensureLoggedInSession();
   const user = await withProgress("Loading account", async () => await getInternalUser(sessionAuth));
 
-  const { dashboardUrl } = resolveLoginConfig();
   const newProject = await createProjectInteractively(user, {
     displayName: opts.displayName,
     defaultDisplayName: path.basename(outputDir),
-    dashboardUrl,
   });
   console.log(`\nCreated project: ${newProject.displayName} (${newProject.id})\n`);
 
@@ -317,10 +315,8 @@ async function handleLinkFromCloud(_flags: Record<string, unknown>, opts: InitOp
       throw new CliError(`You don't own any projects. Create one at ${dashboardUrl} or re-run and choose to create one.`);
     }
 
-    const { dashboardUrl } = resolveLoginConfig();
     const newProject = await createProjectInteractively(user, {
       defaultDisplayName: path.basename(outputDir),
-      dashboardUrl,
     });
     console.log(`\nCreated project: ${newProject.displayName} (${newProject.id})\n`);
     projects = [newProject];

package/src/commands/project.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { getInternalUser } from "../lib/app.js";
-import { resolveLoginConfig, resolveSessionAuth } from "../lib/auth.js";
+import { resolveSessionAuth } from "../lib/auth.js";
 import { createProjectInteractively } from "../lib/create-project.js";
 import { CliError } from "../lib/errors.js";
 import { withProgress } from "../lib/progress.js";
@@ -84,22 +84,21 @@ export function registerProjectCommand(program: Command) {
     .description("Create a new cloud project")
     .option("--cloud", "Confirm that this creates a cloud project")
     .option("--display-name <name>", "Project display name")
+    .option("--team-id <id>", "Team that owns the project")
     .action(async (opts) => {
       if (!opts.cloud) {
         throw new CliError("hexclave project create currently only creates cloud projects. Pass --cloud to confirm.");
       }
-      const [{ getInternalUser }, { resolveLoginConfig, resolveSessionAuth }, { createProjectInteractively }] = await Promise.all([
+      const [{ getInternalUser }, { resolveSessionAuth }, { createProjectInteractively }] = await Promise.all([
         import("../lib/app.js"),
         import("../lib/auth.js"),
         import("../lib/create-project.js"),
       ]);
       const auth = resolveSessionAuth();
       const user = await withProgress("Loading account", async () => await getInternalUser(auth));
-      const { dashboardUrl } = resolveLoginConfig();
-
       const newProject = await createProjectInteractively(user, {
         displayName: opts.displayName,
-        dashboardUrl,
+        teamId: opts.teamId,
       });
 
       if (program.opts().json) {

package/src/commands/team.command.test.ts

@@ -0,0 +1,124 @@
+import { Command } from "commander";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { registerTeamCommand } from "./team.js";
+
+type TestTeam = {
+  id: string,
+  displayName: string,
+  listUsers: () => Promise<Array<{ id: string, teamProfile: { displayName: string | null } }>>,
+  listInvitations: () => Promise<Array<{
+    id: string,
+    recipientEmail: string | null,
+    expiresAt: Date,
+    revoke: () => Promise<void>,
+  }>>,
+  removeUser: (userId: string) => Promise<void>,
+  inviteUser: (options: { email: string }) => Promise<void>,
+  update: (options: { displayName?: string }) => Promise<void>,
+  delete: () => Promise<void>,
+};
+
+type TestUser = {
+  listTeams: () => Promise<TestTeam[]>,
+};
+
+const mockState = vi.hoisted(() => ({
+  user: null as TestUser | null,
+}));
+
+vi.mock("../lib/app.js", () => ({
+  getInternalUser: vi.fn(async () => {
+    if (mockState.user == null) {
+      throw new Error("Expected test user to be configured.");
+    }
+    return mockState.user;
+  }),
+}));
+
+vi.mock("../lib/auth.js", () => ({
+  resolveSessionAuth: vi.fn(() => ({})),
+}));
+
+function createTeam(id: string, displayName: string): TestTeam {
+  return {
+    id,
+    displayName,
+    listUsers: vi.fn(async () => [{ id: "user-2", teamProfile: { displayName: "Member" } }]),
+    listInvitations: vi.fn(async () => []),
+    removeUser: vi.fn(async () => {}),
+    inviteUser: vi.fn(async () => {}),
+    update: vi.fn(async () => {}),
+    delete: vi.fn(async () => {}),
+  };
+}
+
+function createProgram() {
+  const program = new Command();
+  program.exitOverride();
+  registerTeamCommand(program);
+  return program;
+}
+
+afterEach(() => {
+  mockState.user = null;
+  vi.restoreAllMocks();
+});
+
+describe("team command parsing", () => {
+  it("parses the team id on members remove", async () => {
+    const team = createTeam("team-1", "Acme");
+    mockState.user = {
+      listTeams: vi.fn(async () => [team]),
+    };
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await createProgram().parseAsync([
+      "node",
+      "hexclave",
+      "team",
+      "members",
+      "remove",
+      "--team-id",
+      "team-1",
+      "--user-id",
+      "user-2",
+      "--yes",
+    ]);
+
+    expect(team.removeUser).toHaveBeenCalledWith("user-2");
+    expect(logSpy.mock.calls).toMatchInlineSnapshot(`
+      [
+        [
+          "Removed team member: user-2",
+        ],
+      ]
+    `);
+  });
+
+  it("parses the team id on invitations list", async () => {
+    const team = createTeam("team-1", "Acme");
+    mockState.user = {
+      listTeams: vi.fn(async () => [team]),
+    };
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await createProgram().parseAsync([
+      "node",
+      "hexclave",
+      "team",
+      "invitations",
+      "list",
+      "--team-id",
+      "team-1",
+    ]);
+
+    expect(team.listInvitations).toHaveBeenCalledTimes(1);
+    expect(logSpy.mock.calls).toMatchInlineSnapshot(`
+      [
+        [
+          "No invitations found.",
+        ],
+      ]
+    `);
+  });
+});

package/src/commands/team.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { formatTeamList, formatTeamMembers } from "./team.js";
+
+describe("formatTeamList", () => {
+  it("formats teams as tab-separated rows", () => {
+    expect(formatTeamList([
+      { id: "team-1", displayName: "Acme" },
+      { id: "team-2", displayName: "Beta" },
+    ])).toMatchInlineSnapshot(`"team-1\tAcme\nteam-2\tBeta"`);
+  });
+
+  it("returns an empty-list sentinel", () => {
+    expect(formatTeamList([])).toMatchInlineSnapshot(`"No teams found."`);
+  });
+});
+
+describe("formatTeamMembers", () => {
+  it("uses a placeholder for missing member display names", () => {
+    expect(formatTeamMembers([{ id: "user-1", displayName: null }])).toMatchInlineSnapshot(`"user-1\t(none)"`);
+  });
+
+  it("returns an empty-list sentinel", () => {
+    expect(formatTeamMembers([])).toMatchInlineSnapshot(`"No team members found."`);
+  });
+});

package/src/commands/team.ts

@@ -0,0 +1,301 @@
+import { confirm, input } from "@inquirer/prompts";
+import { KnownErrors } from "@hexclave/shared";
+import type { CurrentInternalUser, Team } from "@hexclave/js";
+import { Command } from "commander";
+import { getInternalUser } from "../lib/app.js";
+import { resolveSessionAuth } from "../lib/auth.js";
+import { CliError } from "../lib/errors.js";
+import { isNonInteractiveEnv } from "../lib/interactive.js";
+import { resolveTeam } from "../lib/resolve-team.js";
+
+type TeamOptions = {
+  teamId?: string,
+};
+
+type ConfirmationOptions = {
+  yes?: boolean,
+};
+
+function isJson(program: Command): boolean {
+  return Boolean(program.opts<{ json?: boolean }>().json);
+}
+
+function printResult(program: Command, result: unknown, humanOutput: string): void {
+  console.log(isJson(program) ? JSON.stringify(result, null, 2) : humanOutput);
+}
+
+async function withTeamPermissionError<T>(operation: string, callback: () => Promise<T>): Promise<T> {
+  try {
+    return await callback();
+  } catch (error) {
+    if (KnownErrors.TeamPermissionRequired.isInstance(error)) {
+      throw new CliError(`Cannot ${operation}. You do not have the required permission for this team.`);
+    }
+    throw error;
+  }
+}
+
+async function getTeam(user: CurrentInternalUser, options: TeamOptions): Promise<Team> {
+  return await resolveTeam(await user.listTeams(), options);
+}
+
+async function getUser(): Promise<CurrentInternalUser> {
+  return await getInternalUser(resolveSessionAuth());
+}
+
+async function confirmDestructive(action: string, options: ConfirmationOptions): Promise<void> {
+  if (options.yes) return;
+  if (isNonInteractiveEnv()) {
+    throw new CliError(`--yes is required to ${action} in non-interactive environments (CI).`);
+  }
+  const shouldContinue = await confirm({
+    message: `Are you sure you want to ${action}?`,
+    default: false,
+  });
+  if (!shouldContinue) {
+    throw new CliError("Aborted.");
+  }
+}
+
+function printTeams(program: Command, teams: Team[]): void {
+  const result = teams.map((team) => ({ id: team.id, displayName: team.displayName }));
+  printResult(program, result, formatTeamList(result));
+}
+
+export function formatTeamList(teams: Array<{ id: string, displayName: string }>): string {
+  if (teams.length === 0) return "No teams found.";
+  return teams.map((team) => `${team.id}\t${team.displayName}`).join("\n");
+}
+
+export function formatTeamMembers(members: Array<{ id: string, displayName: string | null }>): string {
+  if (members.length === 0) return "No team members found.";
+  return members.map((member) => `${member.id}\t${member.displayName ?? "(none)"}`).join("\n");
+}
+
+function printTeam(program: Command, team: Team, prefix: string): void {
+  const result = { id: team.id, displayName: team.displayName };
+  printResult(program, result, `${prefix}: ${result.id} (${result.displayName})`);
+}
+
+function registerTeamMembersCommand(team: Command, program: Command): void {
+  const members = team
+    .command("members")
+    .description("Manage team members");
+
+  members
+    .command("list")
+    .description("List members of a team")
+    .option("--team-id <id>", "Team ID")
+    .action(async (options: TeamOptions) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      const teamUsers = await withTeamPermissionError("list team members", () => selectedTeam.listUsers());
+      const result = teamUsers.map((member) => ({
+        id: member.id,
+        displayName: member.teamProfile.displayName,
+      }));
+      printResult(program, result, formatTeamMembers(result));
+    });
+
+  members
+    .command("remove")
+    .description("Remove a member from a team")
+    .option("--team-id <id>", "Team ID")
+    .requiredOption("--user-id <id>", "User ID to remove")
+    .option("-y, --yes", "Skip the confirmation prompt")
+    .action(async (options: TeamOptions & { userId: string } & ConfirmationOptions) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      await confirmDestructive(`remove user ${options.userId} from team ${selectedTeam.id}`, options);
+      await withTeamPermissionError("remove this team member", () => selectedTeam.removeUser(options.userId));
+      printResult(program, { teamId: selectedTeam.id, userId: options.userId }, `Removed team member: ${options.userId}`);
+    });
+}
+
+function registerTeamInvitationsCommand(team: Command, program: Command): void {
+  const invitations = team
+    .command("invitations")
+    .description("Manage team invitations");
+
+  invitations
+    .command("list")
+    .description("List invitations sent by a team")
+    .option("--team-id <id>", "Team ID")
+    .action(async (options: TeamOptions) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      const sentInvitations = await withTeamPermissionError("list team invitations", () => selectedTeam.listInvitations());
+      const result = sentInvitations.map((invitation) => ({
+        id: invitation.id,
+        email: invitation.recipientEmail,
+        expiresAt: invitation.expiresAt.toISOString(),
+      }));
+      const humanOutput = result.length === 0
+        ? "No invitations found."
+        : result.map((invitation) => `${invitation.id}\t${invitation.email ?? "(unknown)"}\t${invitation.expiresAt}`).join("\n");
+      printResult(program, result, humanOutput);
+    });
+
+  invitations
+    .command("revoke")
+    .description("Revoke a team invitation")
+    .option("--team-id <id>", "Team ID")
+    .requiredOption("--invitation-id <id>", "Invitation ID")
+    .option("-y, --yes", "Skip the confirmation prompt")
+    .action(async (options: TeamOptions & { invitationId: string } & ConfirmationOptions) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      await confirmDestructive(`revoke invitation ${options.invitationId}`, options);
+      const invitation = (await withTeamPermissionError("list team invitations", () => selectedTeam.listInvitations()))
+        .find((candidate) => candidate.id === options.invitationId);
+      if (invitation == null) {
+        throw new CliError(`Invitation '${options.invitationId}' was not found for team '${selectedTeam.id}'.`);
+      }
+      await withTeamPermissionError("revoke this invitation", () => invitation.revoke());
+      printResult(program, { teamId: selectedTeam.id, invitationId: options.invitationId }, `Invitation revoked: ${options.invitationId}`);
+    });
+
+  invitations
+    .command("received")
+    .description("List invitations received by the current user")
+    .action(async () => {
+      const user = await getUser();
+      const receivedInvitations = await user.listTeamInvitations();
+      const result = receivedInvitations.map((invitation) => ({
+        id: invitation.id,
+        teamId: invitation.teamId,
+        teamDisplayName: invitation.teamDisplayName,
+        email: invitation.recipientEmail,
+        expiresAt: invitation.expiresAt.toISOString(),
+      }));
+      const humanOutput = result.length === 0
+        ? "No received invitations found."
+        : result.map((invitation) => `${invitation.id}\t${invitation.teamId}\t${invitation.teamDisplayName}\t${invitation.expiresAt}`).join("\n");
+      printResult(program, result, humanOutput);
+    });
+
+  invitations
+    .command("accept")
+    .description("Accept an invitation received by the current user")
+    .requiredOption("--invitation-id <id>", "Invitation ID")
+    .action(async (options: { invitationId: string }) => {
+      const user = await getUser();
+      const invitation = (await user.listTeamInvitations())
+        .find((candidate) => candidate.id === options.invitationId);
+      if (invitation == null) {
+        throw new CliError(`Received invitation '${options.invitationId}' was not found.`);
+      }
+      await invitation.accept();
+      printResult(program, { invitationId: options.invitationId, teamId: invitation.teamId }, `Invitation accepted for team: ${invitation.teamId}`);
+    });
+}
+
+export function registerTeamCommand(program: Command) {
+  const team = program
+    .command("team")
+    .description("Manage teams");
+
+  team
+    .command("list")
+    .description("List your teams")
+    .action(async () => {
+      const user = await getUser();
+      printTeams(program, await user.listTeams());
+    });
+
+  team
+    .command("create")
+    .description("Create a team")
+    .option("--display-name <name>", "Team display name")
+    .action(async (options: { displayName?: string }) => {
+      let displayName = options.displayName?.trim();
+      if (!displayName) {
+        if (isNonInteractiveEnv()) {
+          throw new CliError("--display-name is required in non-interactive environments (CI).");
+        }
+        displayName = (await input({
+          message: "Team display name:",
+          validate: (value) => value.trim().length > 0 || "Display name cannot be empty.",
+        })).trim();
+      }
+
+      const user = await getUser();
+      const newTeam = await user.createTeam({ displayName });
+      printTeam(program, newTeam, "Team created");
+    });
+
+  registerTeamMembersCommand(team, program);
+
+  team
+    .command("invite")
+    .description("Invite a user to a team")
+    .option("--team-id <id>", "Team ID")
+    .option("--email <email>", "Email address to invite")
+    .action(async (options: TeamOptions & { email?: string }) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      let email = options.email?.trim();
+      if (!email) {
+        if (isNonInteractiveEnv()) {
+          throw new CliError("--email is required in non-interactive environments (CI).");
+        }
+        email = (await input({
+          message: "Email address:",
+          validate: (value) => value.trim().length > 0 || "Email address cannot be empty.",
+        })).trim();
+      }
+      await withTeamPermissionError("invite this user", () => selectedTeam.inviteUser({ email }));
+      printResult(program, { teamId: selectedTeam.id, email }, `Invitation sent to ${email}.`);
+    });
+
+  registerTeamInvitationsCommand(team, program);
+
+  team
+    .command("leave")
+    .description("Leave a team")
+    .option("--team-id <id>", "Team ID")
+    .option("-y, --yes", "Skip the confirmation prompt")
+    .action(async (options: TeamOptions & ConfirmationOptions) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      await confirmDestructive(`leave team ${selectedTeam.id}`, options);
+      await user.leaveTeam(selectedTeam);
+      printResult(program, { teamId: selectedTeam.id }, `Left team: ${selectedTeam.id}`);
+    });
+
+  team
+    .command("update")
+    .description("Update a team")
+    .option("--team-id <id>", "Team ID")
+    .option("--display-name <name>", "New team display name")
+    .action(async (options: TeamOptions & { displayName?: string }) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      let displayName = options.displayName?.trim();
+      if (!displayName) {
+        if (isNonInteractiveEnv()) {
+          throw new CliError("--display-name is required in non-interactive environments (CI).");
+        }
+        displayName = (await input({
+          message: "New team display name:",
+          default: selectedTeam.displayName,
+          validate: (value) => value.trim().length > 0 || "Display name cannot be empty.",
+        })).trim();
+      }
+      await withTeamPermissionError("update this team", () => selectedTeam.update({ displayName }));
+      printResult(program, { id: selectedTeam.id, displayName }, `Team updated: ${selectedTeam.id} (${displayName})`);
+    });
+
+  team
+    .command("delete")
+    .description("Delete a team")
+    .option("--team-id <id>", "Team ID")
+    .option("-y, --yes", "Skip the confirmation prompt")
+    .action(async (options: TeamOptions & ConfirmationOptions) => {
+      const user = await getUser();
+      const selectedTeam = await getTeam(user, options);
+      await confirmDestructive(`delete team ${selectedTeam.id}`, options);
+      await withTeamPermissionError("delete this team", () => selectedTeam.delete());
+      printResult(program, { teamId: selectedTeam.id }, `Team deleted: ${selectedTeam.id}`);
+    });
+}

package/src/index.ts

@@ -17,6 +17,7 @@ import { registerDevCommand } from "./commands/dev.js";
 import { registerFixCommand } from "./commands/fix.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerWhoamiCommand } from "./commands/whoami.js";
+import { registerTeamCommand } from "./commands/team.js";
 
 const program = new Command();
 
@@ -35,6 +36,7 @@ registerInitCommand(program);
 registerProjectCommand(program);
 registerDevCommand(program);
 registerWhoamiCommand(program);
+registerTeamCommand(program);
 registerFixCommand(program);
 registerDoctorCommand(program);
 

package/src/lib/create-project.ts

@@ -1,14 +1,14 @@
 import { input } from "@inquirer/prompts";
 import type { CurrentInternalUser } from "@hexclave/js";
-import { DEFAULT_DASHBOARD_URL } from "./auth.js";
 import { CliError } from "./errors.js";
 import { isNonInteractiveEnv } from "./interactive.js";
 import { withProgress } from "./progress.js";
+import { resolveTeam } from "./resolve-team.js";
 
 type CreateProjectOptions = {
   displayName?: string,
+  teamId?: string,
   defaultDisplayName?: string,
-  dashboardUrl?: string,
 };
 
 export async function createProjectInteractively(
@@ -27,16 +27,14 @@ export async function createProjectInteractively(
     })).trim();
   }
 
-  return await withProgress("Creating project", async () => {
-    const teams = await user.listTeams();
-    if (teams.length === 0) {
-      const dashboardUrl = opts.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
-      throw new CliError(`No teams found on your account. Create a team at ${dashboardUrl} first.`);
-    }
-
-    return await user.createProject({
-      displayName,
-      teamId: teams[0].id,
-    });
+  const teams = await user.listTeams();
+  const team = await resolveTeam(teams, {
+    teamId: opts.teamId,
+    createTeam: async (teamDisplayName) => await user.createTeam({ displayName: teamDisplayName }),
   });
+
+  return await withProgress("Creating project", async () => await user.createProject({
+    displayName,
+    teamId: team.id,
+  }));
 }

package/src/lib/resolve-team.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { CliError } from "./errors.js";
+import { resolveTeam } from "./resolve-team.js";
+
+function makeTeam(id: string, displayName: string) {
+  return { id, displayName };
+}
+
+const savedCi = process.env.CI;
+const savedGithubActions = process.env.GITHUB_ACTIONS;
+const savedNoninteractive = process.env.NONINTERACTIVE;
+
+afterEach(() => {
+  if (savedCi === undefined) delete process.env.CI;
+  else process.env.CI = savedCi;
+  if (savedGithubActions === undefined) delete process.env.GITHUB_ACTIONS;
+  else process.env.GITHUB_ACTIONS = savedGithubActions;
+  if (savedNoninteractive === undefined) delete process.env.NONINTERACTIVE;
+  else process.env.NONINTERACTIVE = savedNoninteractive;
+});
+
+describe("resolveTeam", () => {
+  it("returns the explicitly requested team id", async () => {
+    const teams = [makeTeam("team-1", "Acme"), makeTeam("team-2", "Beta")];
+
+    await expect(resolveTeam(teams, { teamId: "team-2" })).resolves.toBe(teams[1]);
+  });
+
+  it("throws when an explicit team id does not exist", async () => {
+    const teams = [makeTeam("team-1", "Acme")];
+
+    await expect(resolveTeam(teams, { teamId: "missing-team" })).rejects.toSatisfy((error: unknown) => (
+      error instanceof CliError && error.message === "Team 'missing-team' was not found on your account."
+    ));
+  });
+
+  it("auto-picks the only team without prompting", async () => {
+    const team = makeTeam("team-1", "Acme");
+
+    await expect(resolveTeam([team])).resolves.toBe(team);
+  });
+
+  it("rejects multi-team resolution in non-interactive environments", async () => {
+    process.env.CI = "1";
+
+    await expect(resolveTeam([makeTeam("team-1", "Acme"), makeTeam("team-2", "Beta")])).rejects.toSatisfy((error: unknown) => (
+      error instanceof CliError && error.message === "--team-id is required in non-interactive environments (CI)."
+    ));
+  });
+
+  it("rejects zero-team resolution in non-interactive environments", async () => {
+    process.env.CI = "1";
+
+    await expect(resolveTeam([], { createTeam: async () => makeTeam("team-1", "Acme") })).rejects.toSatisfy((error: unknown) => (
+      error instanceof CliError && error.message === "No teams found. Run `hexclave team create` first, or pass --team-id."
+    ));
+  });
+});