@antasphere/chassis-cli 0.0.0-stage → 1.0.1

package/src/commands/projects.ts

@@ -0,0 +1,460 @@
+import type { Command } from 'commander';
+import { PlatformApiError, type ChassisClient, type ListParams } from '@antasphere/chassis-sdk';
+import type {
+  Project,
+  ProjectCreate,
+  ProjectMember,
+  ProjectMemberAdd,
+  ProjectRole,
+  ProjectsArchivedFilter,
+  ProjectUpdate
+} from '@antasphere/chassis-contract';
+import { CliApiRefusal, CliUsageError, drainPages, printJson, table, type CliIo } from '../context.js';
+import type { CliKit } from '../kit.js';
+import { resolveTeam, teamName } from './teams.js';
+
+/**
+ * The project commands: a project is a subgroup of the workspace with its own
+ * members and three roles (viewer < editor < manager). The chassis owns the
+ * concept, so these commands spell no tool and no resource — what a project
+ * HOLDS is the tool's own group's business.
+ *
+ * Every refusal the server has a code for is turned into a sentence here
+ * (`explainProjectRefusal`): the wire messages are correct but terse, and the
+ * tiered answer (404 for a project the caller cannot read, 403 for a proven
+ * reader who may not act, 409 for an archived one) only reads as an
+ * explanation once it says WHICH of the three happened. Anything else is
+ * rethrown and the runner prints it unchanged.
+ *
+ * `--json` is the API payload verbatim through `printJson` (the raw sink);
+ * every human line goes through the sanitizing sinks the runner installed —
+ * a project name, a description and a member's display name are all somebody
+ * else's text heading for a terminal.
+ */
+
+const ROLES: readonly ProjectRole[] = ['viewer', 'editor', 'manager'];
+
+/** `--role`, validated here so a typo is a usage error, never a 400. */
+function parseRole(value: string): ProjectRole {
+  if ((ROLES as readonly string[]).includes(value)) return value as ProjectRole;
+  throw new CliUsageError(`Unknown role "${value}" — one of ${ROLES.join(', ')}.`);
+}
+
+/** `--archived <false|true|all>`; `false` (the live projects) is the server's default. */
+function parseArchivedFilter(value: string): ProjectsArchivedFilter {
+  if (value === 'false' || value === 'true' || value === 'all') return value;
+  throw new CliUsageError(`Unknown --archived value "${value}" — one of false, true, all.`);
+}
+
+/** `--metadata <json>`: a JSON OBJECT, the opaque seam the contract defines. */
+function parseMetadata(value: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new CliUsageError('--metadata takes a JSON object, and this did not parse as JSON.');
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new CliUsageError('--metadata takes a JSON object (not an array, a string, or null).');
+  }
+  return parsed as Record<string, unknown>;
+}
+
+/**
+ * The membership argument: an `@` makes it an email, anything else a user id.
+ * Better Auth ids are opaque text, so there is no id shape to test for — but
+ * an email always carries the `@`, and a user id never may (the server reads
+ * exactly one of the two fields, so guessing wrong is a `member_not_found`
+ * rather than a silent mismatch).
+ */
+export function memberRef(value: string): { email: string } | { userId: string } {
+  return value.includes('@') ? { email: value } : { userId: value };
+}
+
+/**
+ * What the command was looking for, which is the ONE thing the wire cannot
+ * say: `member_not_found` means "nobody in this workspace matches" on `add`
+ * (the lookup is workspace-wide) and "not a member of this project" on
+ * `role` / `remove` (the lookup is inside the project). Same code, two
+ * different things to do about it.
+ */
+export type ProjectLookup =
+  'project' | 'workspace-member' | 'project-member' | 'workspace-team' | 'project-team';
+
+/**
+ * The role an `insufficient_project_role` answer names (`This needs the
+ * editor role on the project`), or null when the wire says none: the one
+ * place the sentence is parsed, for the chassis verbs and a tool's own.
+ */
+export function roleNamedBy(e: PlatformApiError): string | null {
+  return /needs the (\w+) role/.exec(e.message)?.[1] ?? null;
+}
+
+/**
+ * The server's project refusals as sentences. Returns the line, or null when
+ * the error is not one of them (the runner's generic handling is then the
+ * honest answer).
+ */
+export function explainProjectRefusal(e: PlatformApiError, what: ProjectLookup): string | null {
+  switch (e.code) {
+    case 'not_found':
+      return 'No such project, or it is not yours to read. (A project you are not a member of answers the same way: its existence is not probeable.)';
+    case 'insufficient_project_role':
+      // The chassis routes all gate on `manager`; a tool's route may gate on
+      // `editor` (linking a resource). The wire sentence names the role.
+      return `You need the ${roleNamedBy(e) ?? 'manager'} role on this project to do that.`;
+    case 'guest_forbidden':
+      return 'You are a guest of this workspace, and guests do not take part in projects.';
+    case 'project_archived':
+      return 'This project is archived and read-only. Unarchive it first to change it.';
+    case 'project_not_archived':
+      return 'This project is not archived, so there is nothing to unarchive.';
+    case 'already_member':
+      return what === 'workspace-team'
+        ? 'That team is already a member of this project. Change its role with `members role --team` instead.'
+        : 'That person is already a member of this project. Change their role with `members role` instead.';
+    case 'team_not_found':
+      return what === 'project-team'
+        ? 'That team is not a member of this project.'
+        : 'No team of this workspace matches — check the slug or id.';
+    case 'member_not_found':
+      return what === 'workspace-member'
+        ? 'No active member of this workspace matches — check the user id or email. Only a member of the workspace can join a project.'
+        : 'That person is not a member of this project.';
+    case 'guest_target':
+      return 'That person is a guest of the workspace, and a guest cannot be a project member. Invite them as a workspace member first.';
+    default:
+      return null;
+  }
+}
+
+/** Run a project call, turning the known refusals into sentences. */
+async function explained<T>(what: ProjectLookup, run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (e) {
+    if (e instanceof PlatformApiError) {
+      const line = explainProjectRefusal(e, what);
+      if (line) throw new CliApiRefusal(line, e.status);
+    }
+    throw e;
+  }
+}
+
+/** One project, as the human sees it. */
+function projectLines(p: Project): string {
+  const metadataKeys = Object.keys(p.metadata);
+  return (
+    `${p.name}${p.archivedAt ? '  [archived]' : ''}\n` +
+    `  id:          ${p.id}\n` +
+    `  your role:   ${p.myRole}\n` +
+    `  members:     ${p.memberCount}\n` +
+    (p.description ? `  description: ${p.description}\n` : '') +
+    (metadataKeys.length > 0 ? `  metadata:    ${metadataKeys.join(', ')}\n` : '') +
+    (p.archivedAt ? `  archived:    ${p.archivedAt}\n` : '') +
+    `  created:     ${p.createdAt}\n`
+  );
+}
+
+/** `a manager`, `an editor`: the article a role takes. */
+const article = (role: string) => (/^[aeiou]/i.test(role) ? 'an' : 'a');
+
+/** One member, a person or a team, as the human sees it. */
+function memberLine(m: ProjectMember): string {
+  if (m.kind === 'team') {
+    return `team ${teamName(m)} (${m.slug}) is ${article(m.role)} ${m.role} of this project for its ${m.membersCount} member${m.membersCount === 1 ? '' : 's'} (team ${m.teamId}).\n`;
+  }
+  return `${m.name} <${m.email}> is ${article(m.role)} ${m.role} of this project (user ${m.userId}).\n`;
+}
+
+export function registerProjectCommands<TClient extends ChassisClient<string>>(
+  kit: CliKit<TClient>,
+  program: Command,
+  io: CliIo
+): void {
+  const { requireApiKey, resolveContext } = kit;
+
+  const projects = program
+    .command('projects')
+    .description('Manage the projects of the workspace (subgroups with their own members)');
+
+  // ── projects list ─────────────────────────────────────────────────────────
+  projects
+    .command('list')
+    .description('List the projects you belong to (newest first, cursor-paginated)')
+    .option('--cursor <cursor>', 'resume from a previous nextCursor')
+    .option('--limit <n>', 'page size (1-100)', (v: string) => parseInt(v, 10))
+    .option('--all', 'follow nextCursor until every page is fetched', false)
+    .option('--archived <false|true|all>', 'which projects to list (default: false, the live ones)')
+    .action(
+      async (opts: { cursor?: string; limit?: number; all: boolean; archived?: string }, cmd: Command) => {
+        const ctx = resolveContext(cmd, io);
+        await requireApiKey(ctx);
+        const params: ListParams & { archived?: ProjectsArchivedFilter } = {};
+        if (opts.cursor) params.cursor = opts.cursor;
+        if (opts.limit !== undefined) params.limit = opts.limit;
+        if (opts.archived !== undefined) params.archived = parseArchivedFilter(opts.archived);
+        const first = await explained('project', () => ctx.client.projects(params));
+        const rows = opts.all
+          ? await drainPages({ rows: first.projects, nextCursor: first.nextCursor }, async (cursor) => {
+              const page = await explained('project', () => ctx.client.projects({ ...params, cursor }));
+              return { rows: page.projects, nextCursor: page.nextCursor };
+            })
+          : first.projects;
+        const nextCursor = opts.all ? null : first.nextCursor;
+        // The wire shape, so scripts can thread nextCursor (--all drains it to null).
+        if (ctx.json) return printJson(io, { projects: rows, nextCursor });
+        if (rows.length === 0) {
+          io.out.write('No projects.\n');
+          return;
+        }
+        io.out.write(
+          table(
+            rows.map((p) => [
+              p.id,
+              p.myRole,
+              `${p.memberCount} member${p.memberCount === 1 ? '' : 's'}`,
+              `${p.name}${p.archivedAt ? '  [archived]' : ''}`
+            ])
+          )
+        );
+        if (nextCursor) {
+          io.out.write(`More available: rerun with --cursor ${nextCursor} or --all\n`);
+        }
+      }
+    );
+
+  // ── projects get ──────────────────────────────────────────────────────────
+  projects
+    .command('get <id>')
+    .description('Show one project, with your own role on it')
+    .action(async (id: string, _opts, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      const project = await explained('project', () => ctx.client.project(id));
+      if (ctx.json) return printJson(io, project);
+      io.out.write(projectLines(project));
+    });
+
+  // ── projects create ───────────────────────────────────────────────────────
+  projects
+    .command('create <name>')
+    .description('Create a project; you become its first manager')
+    .option('--description <text>', 'what the project is for')
+    .option('--metadata <json>', 'a JSON object of your own, opaque to the server')
+    .action(async (name: string, opts: { description?: string; metadata?: string }, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      const body: ProjectCreate = {
+        name,
+        ...(opts.description !== undefined ? { description: opts.description } : {}),
+        ...(opts.metadata !== undefined ? { metadata: parseMetadata(opts.metadata) } : {})
+      };
+      const project = await explained('project', () => ctx.client.createProject(body));
+      if (ctx.json) return printJson(io, project);
+      io.out.write(`Created project "${project.name}".\n${projectLines(project)}`);
+    });
+
+  // ── projects update ───────────────────────────────────────────────────────
+  projects
+    .command('update <id>')
+    .description("Change a project's name, description or metadata (manager)")
+    .option('--name <name>', 'rename the project')
+    .option('--description <text>', 'replace the description')
+    .option('--clear-description', 'remove the description', false)
+    .option('--metadata <json>', 'replace the whole metadata object (a JSON object)')
+    .action(
+      async (
+        id: string,
+        opts: {
+          name?: string;
+          description?: string;
+          clearDescription: boolean;
+          metadata?: string;
+        },
+        cmd: Command
+      ) => {
+        if (opts.description !== undefined && opts.clearDescription) {
+          throw new CliUsageError('Pass either --description <text> or --clear-description, not both.');
+        }
+        const patch: ProjectUpdate = {
+          ...(opts.name !== undefined ? { name: opts.name } : {}),
+          ...(opts.clearDescription
+            ? { description: null }
+            : opts.description !== undefined
+              ? { description: opts.description }
+              : {}),
+          ...(opts.metadata !== undefined ? { metadata: parseMetadata(opts.metadata) } : {})
+        } as ProjectUpdate;
+        if (Object.keys(patch).length === 0) {
+          throw new CliUsageError(
+            'Nothing to change — pass --name, --description, --clear-description or --metadata.'
+          );
+        }
+        const ctx = resolveContext(cmd, io);
+        await requireApiKey(ctx);
+        const project = await explained('project', () => ctx.client.updateProject(id, patch));
+        if (ctx.json) return printJson(io, project);
+        io.out.write(`Updated project "${project.name}".\n${projectLines(project)}`);
+      }
+    );
+
+  // ── projects archive / unarchive ──────────────────────────────────────────
+  projects
+    .command('archive <id>')
+    .description('Archive a project: out of the default list and read-only (manager). Never deleted')
+    .action(async (id: string, _opts, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      const project = await explained('project', () => ctx.client.archiveProject(id));
+      if (ctx.json) return printJson(io, project);
+      io.out.write(
+        `Archived "${project.name}". It is read-only and out of \`projects list\` until you unarchive it.\n`
+      );
+    });
+
+  projects
+    .command('unarchive <id>')
+    .description('Bring an archived project back (manager)')
+    .action(async (id: string, _opts, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      const project = await explained('project', () => ctx.client.unarchiveProject(id));
+      if (ctx.json) return printJson(io, project);
+      io.out.write(`Unarchived "${project.name}". It is writable again.\n`);
+    });
+
+  // ── projects members ──────────────────────────────────────────────────────
+  const members = projects.command('members').description("Manage a project's members");
+
+  members
+    .command('list <project>')
+    .description('List the members of a project')
+    .option('--cursor <cursor>', 'resume from a previous nextCursor')
+    .option('--limit <n>', 'page size (1-100)', (v: string) => parseInt(v, 10))
+    .option('--all', 'follow nextCursor until every page is fetched', false)
+    .action(
+      async (project: string, opts: { cursor?: string; limit?: number; all: boolean }, cmd: Command) => {
+        const ctx = resolveContext(cmd, io);
+        await requireApiKey(ctx);
+        const params: ListParams = {};
+        if (opts.cursor) params.cursor = opts.cursor;
+        if (opts.limit !== undefined) params.limit = opts.limit;
+        const first = await explained('project', () => ctx.client.projectMembers(project, params));
+        const rows = opts.all
+          ? await drainPages({ rows: first.members, nextCursor: first.nextCursor }, async (cursor) => {
+              const page = await explained('project', () =>
+                ctx.client.projectMembers(project, { ...params, cursor })
+              );
+              return { rows: page.members, nextCursor: page.nextCursor };
+            })
+          : first.members;
+        const nextCursor = opts.all ? null : first.nextCursor;
+        if (ctx.json) return printJson(io, { members: rows, nextCursor });
+        if (rows.length === 0) {
+          io.out.write('No members.\n');
+          return;
+        }
+        io.out.write(
+          table(
+            rows.map((m) =>
+              m.kind === 'team'
+                ? [
+                    'team',
+                    m.slug,
+                    m.role,
+                    `${m.membersCount} member${m.membersCount === 1 ? '' : 's'}`,
+                    teamName(m)
+                  ]
+                : ['person', m.userId, m.role, m.email, m.name]
+            )
+          )
+        );
+        if (nextCursor) {
+          io.out.write(`More available: rerun with --cursor ${nextCursor} or --all\n`);
+        }
+      }
+    );
+
+  members
+    .command('add <project> [userIdOrEmail]')
+    .description('Add a member of the workspace, or one of its teams with --team, to the project (manager)')
+    .requiredOption('--role <viewer|editor|manager>', 'the role they get on this project')
+    .option('--team <team>', 'add this team (a slug or an id) instead of a person: its members hold the role')
+    .action(
+      async (
+        project: string,
+        who: string | undefined,
+        opts: { role: string; team?: string },
+        cmd: Command
+      ) => {
+        if ((who === undefined) === (opts.team === undefined)) {
+          throw new CliUsageError('Name exactly one: a person (<userIdOrEmail>) or a team (--team <team>).');
+        }
+        const role = parseRole(opts.role);
+        const ctx = resolveContext(cmd, io);
+        await requireApiKey(ctx);
+        if (opts.team !== undefined) {
+          const team = await resolveTeam(ctx.client, opts.team);
+          const body: ProjectMemberAdd = { teamId: team.id, role };
+          const entry = await explained('workspace-team', () => ctx.client.addProjectMember(project, body));
+          if (ctx.json) return printJson(io, entry);
+          io.out.write(`Added ${memberLine(entry)}`);
+          return;
+        }
+        const body: ProjectMemberAdd = { ...memberRef(who!), role };
+        // `add` looks the person up across the WORKSPACE, so its
+        // `member_not_found` is about the workspace, not about the project.
+        const member = await explained('workspace-member', () => ctx.client.addProjectMember(project, body));
+        if (ctx.json) return printJson(io, member);
+        io.out.write(`Added ${memberLine(member)}`);
+      }
+    );
+
+  members
+    .command('role <project> <userIdOrTeam> <role>')
+    .description("Change a member's role on the project, or a team's with --team (manager)")
+    .option('--team', 'the second argument names a team (a slug or an id), not a person', false)
+    .action(async (project: string, target: string, role: string, opts: { team: boolean }, cmd: Command) => {
+      const parsed = parseRole(role);
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      if (opts.team) {
+        const team = await resolveTeam(ctx.client, target);
+        const entry = await explained('project-team', () =>
+          ctx.client.setProjectTeamRole(project, team.id, parsed)
+        );
+        if (ctx.json) return printJson(io, entry);
+        io.out.write(`Now ${memberLine(entry)}`);
+        return;
+      }
+      const member = await explained('project-member', () =>
+        ctx.client.setProjectMemberRole(project, target, parsed)
+      );
+      if (ctx.json) return printJson(io, member);
+      io.out.write(`Now ${memberLine(member)}`);
+    });
+
+  members
+    .command('remove <project> <userIdOrTeam>')
+    .description(
+      'Remove a member from the project, or a team with --team (a manager removes anyone; anyone removes themselves)'
+    )
+    .option('--team', 'the second argument names a team (a slug or an id), not a person', false)
+    .action(async (project: string, target: string, opts: { team: boolean }, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      if (opts.team) {
+        const team = await resolveTeam(ctx.client, target);
+        const entry = await explained('project-team', () => ctx.client.removeProjectTeam(project, team.id));
+        if (ctx.json) return printJson(io, entry);
+        io.out.write(
+          `Removed team ${teamName(entry)} (${entry.slug}) from this project. Its people keep their own entries.\n`
+        );
+        return;
+      }
+      const member = await explained('project-member', () => ctx.client.removeProjectMember(project, target));
+      if (ctx.json) return printJson(io, member);
+      io.out.write(`Removed ${member.name} <${member.email}> from this project.\n`);
+    });
+}