@baseworks/organization 0.2.0

package/src/cli.ts

@@ -0,0 +1,682 @@
+import { Command } from 'commander';
+import { clr, kv, table, summary, success, warn, fatal, printOutput, outputOption, prompt } from '@baseworks/cli/display';
+import { fmtDate } from '@baseworks/cli/fmt';
+import { tree }    from '@baseworks/cli/tree';
+import type { ColDef, TableOpts } from '@baseworks/cli/display';
+import type { TreeNode }          from '@baseworks/cli/tree';
+import type { ApiClient }         from '@baseworks/cli/client';
+import type { ContextManager }    from '@baseworks/cli/context';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface OrgCliDeps {
+  http:     ApiClient;
+  ctx:      ContextManager<Record<string, string | undefined>>;
+  appBase:  string;
+  cliName?: string;
+}
+
+type OrgRow  = { id: string; shortId: string; slug: string; name: string; createdAt?: number };
+type OrgMeta = OrgRow & { metadata?: Record<string, unknown> };
+type WsRow   = { id: string; shortId: string; slug: string; name: string; isDefault?: boolean };
+type ProjRow = { id: string; shortId: string; slug: string; name: string; isDefault?: boolean };
+type EnvRow  = { id: string; shortId: string; slug: string; name: string; isDefault?: boolean };
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function activeOrgSlug(ctx: OrgCliDeps['ctx'], cliName: string, flagOrg?: string): string {
+  return flagOrg
+    ?? ctx.getContext()?.['org']
+    ?? (ctx.loadConfig() as Record<string, unknown>)['activeOrg'] as string | undefined
+    ?? fatal(`No active org. Run: ${cliName} use <org>`);
+}
+
+function activeWsSlug(ctx: OrgCliDeps['ctx'], cliName: string, flagWs?: string): string {
+  return flagWs
+    ?? ctx.getContext()?.['workspace']
+    ?? fatal(`No active workspace. Run: ${cliName} use <org>/<ws>`);
+}
+
+function activeProjSlug(ctx: OrgCliDeps['ctx'], cliName: string, flagProj?: string): string {
+  return flagProj
+    ?? ctx.getContext()?.['project']
+    ?? fatal(`No active project. Run: ${cliName} use <org>/<ws>/<proj>`);
+}
+
+// ─── buildOrgCommand ──────────────────────────────────────────────────────────
+// Mounts as: program.addCommand(buildOrgCommand(deps))
+// Usage: flect org           → list
+//        flect org create    → create
+//        flect org get <slug>
+//        flect org update <slug>
+//        flect org delete <slug>
+//        flect org meta ...
+
+export function buildOrgCommand(deps: OrgCliDeps): Command {
+  const { http } = deps;
+  const cli = deps.cliName ?? 'cli';
+
+  const cmd = new Command('org')
+    .description('Organization management')
+    .option(...outputOption())
+    .action(async (opts: { output: string }) => {
+      const res = await http.get<{ orgs: OrgMeta[] }>('/v1/orgs').catch(e => { console.error(e.message); process.exit(1); });
+      printOutput(res.orgs, opts.output, (wide) => {
+        table(res.orgs, [
+          { key: 'shortId', label: 'ID' },
+          { key: 'slug',    label: 'SLUG' },
+          { key: 'name',    label: 'NAME' },
+          { key: 'createdAt', label: 'CREATED', wide: true, fmt: v => fmtDate(v as number) },
+          { key: 'id',      label: 'FULL ID',  wide: true },
+        ] as ColDef<OrgMeta>[], { wide, emptyHint: `No orgs yet.  Run: ${cli} org create --name <n>` });
+        summary(`${res.orgs.length} org${res.orgs.length !== 1 ? 's' : ''}`);
+      }, 'slug');
+    });
+
+  cmd.addCommand(
+    new Command('create')
+      .description('Create a new organization')
+      .requiredOption('--name <name>', 'Display name')
+      .option('--slug <slug>', 'URL slug (auto-generated if omitted)')
+      .action(async (opts: { name: string; slug?: string }) => {
+        const res = await http.post<{ org: OrgRow }>('/v1/orgs', { name: opts.name, slug: opts.slug }).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Org created: ${res.org.slug}`);
+        kv([['id', res.org.shortId], ['slug', res.org.slug]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('get').argument('<slug>')
+      .description('Get org details')
+      .option(...outputOption())
+      .action(async (slug: string, opts: { output: string }) => {
+        const res  = await http.get<{ org: OrgMeta }>(`/v1/orgs/${slug}`).catch(e => { console.error(e.message); process.exit(1); });
+        const meta = res.org.metadata ?? {};
+        printOutput(res.org as unknown as Record<string, unknown>, opts.output, () => {
+          kv([['id', res.org.shortId], ['slug', res.org.slug], ['name', res.org.name], ['full_id', res.org.id]]);
+          if (Object.keys(meta).length) {
+            console.log(`  ${clr.dim}── metadata ──${clr.reset}`);
+            kv(Object.entries(meta).map(([k, v]) => [k, JSON.stringify(v)] as [string, string]));
+          }
+        }, 'slug');
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('update').argument('<slug>')
+      .description('Update org name or slug')
+      .option('--name <name>', 'New display name')
+      .option('--slug <new-slug>', 'New URL slug')
+      .action(async (slug: string, opts: { name?: string; slug?: string }) => {
+        if (!opts.name && !opts.slug) { warn('Provide at least --name or --slug'); return; }
+        const body: Record<string, string> = {};
+        if (opts.name) body['name'] = opts.name;
+        if (opts.slug) body['slug'] = opts.slug;
+        const res = await http.patch<{ org: OrgRow }>(`/v1/orgs/${slug}`, body).catch(e => { console.error(e.message); process.exit(1); });
+        success('Org updated.');
+        kv([['id', res.org.shortId], ['slug', res.org.slug], ['name', res.org.name]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('delete').argument('<slug>')
+      .description('Delete an organization')
+      .action(async (slug: string) => {
+        await http.del(`/v1/orgs/${slug}`).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Org deleted: ${slug}`);
+      }),
+  );
+
+  // org meta sub-group
+  const meta = new Command('meta').description('Manage org metadata');
+
+  meta.addCommand(
+    new Command('get').argument('<slug>').argument('[key]')
+      .description('Show metadata (all or one key)')
+      .action(async (slug: string, key?: string) => {
+        const res  = await http.get<{ org: OrgMeta }>(`/v1/orgs/${slug}`).catch(e => { console.error(e.message); process.exit(1); });
+        const m    = res.org.metadata ?? {};
+        if (key) {
+          const val = m[key];
+          if (val === undefined) warn(`Key '${key}' not found.`);
+          else console.log(`  ${clr.dim}${key}${clr.reset}  ${JSON.stringify(val)}`);
+        } else if (!Object.keys(m).length) {
+          console.log(`  ${clr.dim}(no metadata)${clr.reset}`);
+        } else {
+          kv(Object.entries(m).map(([k, v]) => [k, JSON.stringify(v)] as [string, string]));
+        }
+      }),
+  );
+
+  meta.addCommand(
+    new Command('set').argument('<slug>').argument('<key>').argument('<value>')
+      .description('Set a metadata key (JSON or string)')
+      .action(async (slug: string, key: string, value: string) => {
+        let parsed: unknown;
+        try { parsed = JSON.parse(value); } catch { parsed = value; }
+        await http.patch(`/v1/orgs/${slug}/metadata`, { [key]: parsed }).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Metadata key '${key}' set.`);
+      }),
+  );
+
+  meta.addCommand(
+    new Command('delete-key').argument('<slug>').argument('<key>')
+      .description('Remove a metadata key')
+      .action(async (slug: string, key: string) => {
+        await http.del(`/v1/orgs/${slug}/metadata/${key}`).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Metadata key '${key}' deleted.`);
+      }),
+  );
+
+  cmd.addCommand(meta);
+  return cmd;
+}
+
+// ─── buildWsCommand ───────────────────────────────────────────────────────────
+// Usage: flect ws            → list (requires active org)
+//        flect ws create
+//        flect ws delete <slug>
+
+export function buildWsCommand(deps: OrgCliDeps): Command {
+  const { http, ctx } = deps;
+  const cli = deps.cliName ?? 'cli';
+
+  const cmd = new Command('ws')
+    .alias('workspace')
+    .description('Workspace management')
+    .enablePositionalOptions()
+    .option('--org <slug>', 'Override active org')
+    .option(...outputOption())
+    .action(async (opts: { org?: string; output: string }) => {
+      const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+      const res     = await http.get<{ workspaces: WsRow[] }>(`/v1/orgs/${orgSlug}/workspaces`).catch(e => { console.error(e.message); process.exit(1); });
+      printOutput(res.workspaces, opts.output, (wide) => {
+        table(res.workspaces, [
+          { key: 'shortId',   label: 'ID' },
+          { key: 'slug',      label: 'SLUG' },
+          { key: 'name',      label: 'NAME' },
+          { key: 'isDefault', label: 'DEFAULT', fmt: v => v ? '✓' : '' },
+          { key: 'id',        label: 'FULL ID',  wide: true },
+        ] as ColDef<WsRow>[], { wide, emptyHint: `No workspaces yet.  Run: ${cli} ws create --name <n>` } as TableOpts & { wide: boolean });
+        summary(`${res.workspaces.length} workspace${res.workspaces.length !== 1 ? 's' : ''}`);
+      }, 'slug');
+    });
+
+  cmd.addCommand(
+    new Command('create')
+      .description('Create a workspace')
+      .requiredOption('--name <name>', 'Display name')
+      .option('--slug <slug>', 'URL slug (auto-generated if omitted)')
+      .option('--org <slug>', 'Override active org')
+      .action(async (opts: { name: string; slug?: string; org?: string }) => {
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        const res     = await http.post<{ workspace: WsRow }>(`/v1/orgs/${orgSlug}/workspaces`, { name: opts.name, slug: opts.slug }).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Workspace created: ${res.workspace.slug}`);
+        kv([['id', res.workspace.shortId], ['slug', res.workspace.slug]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('get').argument('<ref>')
+      .description('Get workspace details')
+      .option('--org <slug>', 'Override active org')
+      .option(...outputOption())
+      .action(async (ref: string, opts: { org?: string; output: string }) => {
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        const res = await http.get<{ workspace: WsRow }>(`/v1/orgs/${orgSlug}/workspaces/${ref}`).catch(e => { console.error(e.message); process.exit(1); });
+        printOutput(res.workspace as unknown as Record<string, unknown>, opts.output, () => {
+          kv([['id', res.workspace.shortId], ['slug', res.workspace.slug], ['name', res.workspace.name], ['full_id', res.workspace.id]]);
+        }, 'slug');
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('update').argument('<ref>')
+      .description('Update a workspace')
+      .option('--name <name>', 'New display name')
+      .option('--slug <new-slug>', 'New URL slug')
+      .option('--org <slug>', 'Override active org')
+      .action(async (ref: string, opts: { name?: string; slug?: string; org?: string }) => {
+        if (!opts.name && !opts.slug) { warn('Provide at least --name or --slug'); return; }
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        const body: Record<string, string> = {};
+        if (opts.name) body['name'] = opts.name;
+        if (opts.slug) body['slug'] = opts.slug;
+        const res = await http.patch<{ workspace: WsRow }>(`/v1/orgs/${orgSlug}/workspaces/${ref}`, body).catch(e => { console.error(e.message); process.exit(1); });
+        success('Workspace updated.');
+        kv([['id', res.workspace.shortId], ['slug', res.workspace.slug], ['name', res.workspace.name]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('delete').argument('<ref>')
+      .description('Delete a workspace')
+      .option('--org <slug>', 'Override active org')
+      .action(async (ref: string, opts: { org?: string }) => {
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        await http.del(`/v1/orgs/${orgSlug}/workspaces/${ref}`).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Workspace deleted: ${ref}`);
+      }),
+  );
+
+  return cmd;
+}
+
+// ─── buildProjCommand ─────────────────────────────────────────────────────────
+// Usage: flect proj          → list (requires active org + ws)
+//        flect proj create
+//        flect proj delete <slug>
+
+export function buildProjCommand(deps: OrgCliDeps): Command {
+  const { http, ctx } = deps;
+  const cli = deps.cliName ?? 'cli';
+
+  const cmd = new Command('proj')
+    .alias('project')
+    .description('Project management')
+    .enablePositionalOptions()
+    .option('--org <slug>', 'Override active org')
+    .option('--ws <slug>',  'Override active workspace')
+    .option(...outputOption())
+    .action(async (opts: { org?: string; ws?: string; output: string }) => {
+      const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+      const wsSlug  = activeWsSlug(ctx, cli, opts.ws);
+      const res     = await http.get<{ projects: ProjRow[] }>(`/v1/orgs/${orgSlug}/workspaces/${wsSlug}/projects`).catch(e => { console.error(e.message); process.exit(1); });
+      printOutput(res.projects, opts.output, (wide) => {
+        table(res.projects, [
+          { key: 'shortId',   label: 'ID' },
+          { key: 'slug',      label: 'SLUG' },
+          { key: 'name',      label: 'NAME' },
+          { key: 'isDefault', label: 'DEFAULT', fmt: v => v ? '✓' : '' },
+          { key: 'id',        label: 'FULL ID',  wide: true },
+        ] as ColDef<ProjRow>[], { wide, emptyHint: `No projects yet.  Run: ${cli} proj create --name <n>` } as TableOpts & { wide: boolean });
+        summary(`${res.projects.length} project${res.projects.length !== 1 ? 's' : ''}`);
+      }, 'slug');
+    });
+
+  cmd.addCommand(
+    new Command('create')
+      .description('Create a project')
+      .requiredOption('--name <name>', 'Display name')
+      .option('--slug <slug>', 'URL slug (auto-generated if omitted)')
+      .option('--org <slug>', 'Override active org')
+      .option('--ws <slug>',  'Override active workspace')
+      .action(async (opts: { name: string; slug?: string; org?: string; ws?: string }) => {
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug  = activeWsSlug(ctx, cli, opts.ws);
+        const res     = await http.post<{ project: ProjRow }>(`/v1/orgs/${orgSlug}/workspaces/${wsSlug}/projects`, { name: opts.name, slug: opts.slug }).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Project created: ${res.project.slug}`);
+        kv([['id', res.project.shortId], ['slug', res.project.slug]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('get').argument('<ref>')
+      .description('Get project details')
+      .option('--org <slug>', 'Override active org')
+      .option('--ws <slug>',  'Override active workspace')
+      .option(...outputOption())
+      .action(async (ref: string, opts: { org?: string; ws?: string; output: string }) => {
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug  = activeWsSlug(ctx, cli, opts.ws);
+        const res = await http.get<{ project: ProjRow }>(`/v1/orgs/${orgSlug}/workspaces/${wsSlug}/projects/${ref}`).catch(e => { console.error(e.message); process.exit(1); });
+        printOutput(res.project as unknown as Record<string, unknown>, opts.output, () => {
+          kv([['id', res.project.shortId], ['slug', res.project.slug], ['name', res.project.name], ['full_id', res.project.id]]);
+        }, 'slug');
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('update').argument('<ref>')
+      .description('Update a project')
+      .option('--name <name>', 'New display name')
+      .option('--slug <new-slug>', 'New URL slug')
+      .option('--org <slug>', 'Override active org')
+      .option('--ws <slug>',  'Override active workspace')
+      .action(async (ref: string, opts: { name?: string; slug?: string; org?: string; ws?: string }) => {
+        if (!opts.name && !opts.slug) { warn('Provide at least --name or --slug'); return; }
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug  = activeWsSlug(ctx, cli, opts.ws);
+        const body: Record<string, string> = {};
+        if (opts.name) body['name'] = opts.name;
+        if (opts.slug) body['slug'] = opts.slug;
+        const res = await http.patch<{ project: ProjRow }>(`/v1/orgs/${orgSlug}/workspaces/${wsSlug}/projects/${ref}`, body).catch(e => { console.error(e.message); process.exit(1); });
+        success('Project updated.');
+        kv([['id', res.project.shortId], ['slug', res.project.slug], ['name', res.project.name]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('delete').argument('<ref>')
+      .description('Delete a project')
+      .option('--org <slug>', 'Override active org')
+      .option('--ws <slug>',  'Override active workspace')
+      .action(async (ref: string, opts: { org?: string; ws?: string }) => {
+        const orgSlug = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug  = activeWsSlug(ctx, cli, opts.ws);
+        await http.del(`/v1/orgs/${orgSlug}/workspaces/${wsSlug}/projects/${ref}`).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Project deleted: ${ref}`);
+      }),
+  );
+
+  return cmd;
+}
+
+// ─── buildEnvCommand ──────────────────────────────────────────────────────────
+// Usage: flect env            → list (requires active org + ws + proj)
+//        flect env create
+//        flect env get <ref>
+//        flect env update <ref>
+//        flect env delete <ref>
+
+export function buildEnvCommand(deps: OrgCliDeps): Command {
+  const { http, ctx } = deps;
+  const cli = deps.cliName ?? 'cli';
+
+  function basePath(orgSlug: string, wsSlug: string, projSlug: string) {
+    return `/v1/orgs/${orgSlug}/workspaces/${wsSlug}/projects/${projSlug}/envs`;
+  }
+
+  const cmd = new Command('env')
+    .description('Environment management')
+    .enablePositionalOptions()
+    .option('--org <slug>',  'Override active org')
+    .option('--ws <slug>',   'Override active workspace')
+    .option('--proj <slug>', 'Override active project')
+    .option(...outputOption())
+    .action(async (opts: { org?: string; ws?: string; proj?: string; output: string }) => {
+      const orgSlug  = activeOrgSlug(ctx, cli, opts.org);
+      const wsSlug   = activeWsSlug(ctx, cli, opts.ws);
+      const projSlug = activeProjSlug(ctx, cli, opts.proj);
+      const res = await http.get<{ envs: EnvRow[] }>(basePath(orgSlug, wsSlug, projSlug)).catch(e => { console.error(e.message); process.exit(1); });
+      printOutput(res.envs, opts.output, (wide) => {
+        table(res.envs, [
+          { key: 'shortId',   label: 'ID' },
+          { key: 'slug',      label: 'SLUG' },
+          { key: 'name',      label: 'NAME' },
+          { key: 'isDefault', label: 'DEFAULT', fmt: v => v ? '✓' : '' },
+          { key: 'id',        label: 'FULL ID',  wide: true },
+        ] as ColDef<EnvRow>[], { wide, emptyHint: `No envs yet.  Run: ${cli} env create --name <n>` } as TableOpts & { wide: boolean });
+        summary(`${res.envs.length} env${res.envs.length !== 1 ? 's' : ''}`);
+      }, 'slug');
+    });
+
+  cmd.addCommand(
+    new Command('create')
+      .description('Create an environment')
+      .requiredOption('--name <name>', 'Display name')
+      .option('--slug <slug>', 'URL slug (auto-generated if omitted)')
+      .option('--org <slug>',  'Override active org')
+      .option('--ws <slug>',   'Override active workspace')
+      .option('--proj <slug>', 'Override active project')
+      .action(async (opts: { name: string; slug?: string; org?: string; ws?: string; proj?: string }) => {
+        const orgSlug  = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug   = activeWsSlug(ctx, cli, opts.ws);
+        const projSlug = activeProjSlug(ctx, cli, opts.proj);
+        const res = await http.post<{ env: EnvRow }>(basePath(orgSlug, wsSlug, projSlug), { name: opts.name, slug: opts.slug }).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Env created: ${res.env.slug}`);
+        kv([['id', res.env.shortId], ['slug', res.env.slug]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('get').argument('<ref>')
+      .description('Get environment details')
+      .option('--org <slug>',  'Override active org')
+      .option('--ws <slug>',   'Override active workspace')
+      .option('--proj <slug>', 'Override active project')
+      .option(...outputOption())
+      .action(async (ref: string, opts: { org?: string; ws?: string; proj?: string; output: string }) => {
+        const orgSlug  = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug   = activeWsSlug(ctx, cli, opts.ws);
+        const projSlug = activeProjSlug(ctx, cli, opts.proj);
+        const res = await http.get<{ env: EnvRow }>(`${basePath(orgSlug, wsSlug, projSlug)}/${ref}`).catch(e => { console.error(e.message); process.exit(1); });
+        printOutput(res.env as unknown as Record<string, unknown>, opts.output, () => {
+          kv([['id', res.env.shortId], ['slug', res.env.slug], ['name', res.env.name], ['full_id', res.env.id]]);
+        }, 'slug');
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('update').argument('<ref>')
+      .description('Update an environment')
+      .option('--name <name>', 'New display name')
+      .option('--slug <new-slug>', 'New URL slug')
+      .option('--org <slug>',  'Override active org')
+      .option('--ws <slug>',   'Override active workspace')
+      .option('--proj <slug>', 'Override active project')
+      .action(async (ref: string, opts: { name?: string; slug?: string; org?: string; ws?: string; proj?: string }) => {
+        if (!opts.name && !opts.slug) { warn('Provide at least --name or --slug'); return; }
+        const orgSlug  = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug   = activeWsSlug(ctx, cli, opts.ws);
+        const projSlug = activeProjSlug(ctx, cli, opts.proj);
+        const body: Record<string, string> = {};
+        if (opts.name) body['name'] = opts.name;
+        if (opts.slug) body['slug'] = opts.slug;
+        const res = await http.patch<{ env: EnvRow }>(`${basePath(orgSlug, wsSlug, projSlug)}/${ref}`, body).catch(e => { console.error(e.message); process.exit(1); });
+        success('Env updated.');
+        kv([['id', res.env.shortId], ['slug', res.env.slug], ['name', res.env.name]]);
+      }),
+  );
+
+  cmd.addCommand(
+    new Command('delete').argument('<ref>')
+      .description('Delete an environment')
+      .option('--org <slug>',  'Override active org')
+      .option('--ws <slug>',   'Override active workspace')
+      .option('--proj <slug>', 'Override active project')
+      .action(async (ref: string, opts: { org?: string; ws?: string; proj?: string }) => {
+        const orgSlug  = activeOrgSlug(ctx, cli, opts.org);
+        const wsSlug   = activeWsSlug(ctx, cli, opts.ws);
+        const projSlug = activeProjSlug(ctx, cli, opts.proj);
+        await http.del(`${basePath(orgSlug, wsSlug, projSlug)}/${ref}`).catch(e => { console.error(e.message); process.exit(1); });
+        success(`Env deleted: ${ref}`);
+      }),
+  );
+
+  return cmd;
+}
+
+// ─── addGlobalCommands ────────────────────────────────────────────────────────
+// Adds use / ls / ps directly onto the root program.
+// Usage: flect use [org/ws/proj]
+//        flect ls
+//        flect ps
+
+export function addGlobalCommands(program: Command, deps: OrgCliDeps): void {
+  const { http, ctx } = deps;
+  const cli = deps.cliName ?? 'cli';
+
+  program.addCommand(
+    new Command('use')
+      .alias('context')
+      .description('Set active org / workspace / project (interactive if no arg)')
+      .argument('[path]', 'org  or  org/ws  or  org/ws/proj')
+      .action(async (path?: string) => {
+        await runUseCommand(http, ctx, path);
+      }),
+  );
+
+  program.addCommand(
+    new Command('ls')
+      .description('Tree view of all orgs, workspaces, and projects')
+      .action(async () => {
+        const ctxData    = ctx.getContext() as Record<string, string | undefined> | undefined;
+        const activeOrg  = ctxData?.['org'];
+        const activeWs   = ctxData?.['workspace'];
+        const activeProj = ctxData?.['project'];
+
+        const { orgs } = await http.get<{ orgs: OrgRow[] }>('/v1/orgs').catch(e => { console.error(e.message); process.exit(1); });
+
+        let totalWs   = 0;
+        let totalProj = 0;
+
+        const nodes: TreeNode[] = await Promise.all(
+          orgs.map(async (org) => {
+            const { workspaces } = await http.get<{ workspaces: WsRow[] }>(`/v1/orgs/${org.slug}/workspaces`);
+            totalWs += workspaces.length;
+
+            const wsNodes: TreeNode[] = await Promise.all(
+              workspaces.map(async (ws) => {
+                const { projects } = await http.get<{ projects: ProjRow[] }>(`/v1/orgs/${org.slug}/workspaces/${ws.slug}/projects`);
+                totalProj += projects.length;
+                const isActiveWs = org.slug === activeOrg && ws.slug === activeWs;
+                return {
+                  label:    isActiveWs ? clr.bold + ws.slug + clr.reset : ws.slug,
+                  badge:    isActiveWs ? clr.cyan + '●' + clr.reset : undefined,
+                  children: projects.map(p => {
+                    const isActiveProj = isActiveWs && p.slug === activeProj;
+                    return {
+                      label: isActiveProj ? clr.bold + p.slug + clr.reset : p.slug,
+                      badge: isActiveProj ? clr.green + '●' + clr.reset : undefined,
+                    };
+                  }),
+                };
+              }),
+            );
+
+            const isActiveOrg = org.slug === activeOrg;
+            return {
+              label:    isActiveOrg ? clr.bold + org.slug + clr.reset : org.slug,
+              badge:    isActiveOrg ? clr.cyan + '★' + clr.reset : undefined,
+              meta:     org.name && org.name !== org.slug ? org.name : undefined,
+              children: wsNodes,
+            };
+          }),
+        );
+
+        console.log();
+        tree(nodes);
+        console.log();
+        console.log(
+          `  ${clr.dim}${orgs.length} org${orgs.length !== 1 ? 's' : ''}` +
+          `  ·  ${totalWs} workspace${totalWs !== 1 ? 's' : ''}` +
+          `  ·  ${totalProj} project${totalProj !== 1 ? 's' : ''}` +
+          (activeOrg ? `  ·  active: ${clr.bold}${activeOrg}/${activeWs}/${activeProj}${clr.reset}${clr.dim}` : '') +
+          clr.reset,
+        );
+        console.log();
+      }),
+  );
+
+  program.addCommand(
+    new Command('ps')
+      .description('Show active session (context, token, api endpoint)')
+      .action(() => {
+        const ctxData = ctx.getContext() as Record<string, string | undefined> | undefined;
+        const cfg     = ctx.loadConfig() as Record<string, unknown>;
+        const token   = (cfg['token'] as string | undefined)
+          ?? Object.values((cfg['orgs'] as Record<string, { token?: string }> | undefined) ?? {})
+            .find(e => e?.token)?.token;
+        const apiBase = (cfg['apiBase'] as string | undefined) ?? deps.appBase;
+
+        console.log();
+        if (ctxData?.['org']) {
+          console.log(
+            `  ${clr.dim}context${clr.reset}   ` +
+            `${clr.bold}${ctxData['org']}${clr.reset}` +
+            ` ${clr.dim}/${clr.reset} ${ctxData['workspace'] ?? '—'}` +
+            ` ${clr.dim}/${clr.reset} ${ctxData['project'] ?? '—'}` +
+            `  ${clr.green}● active${clr.reset}`,
+          );
+        } else {
+          console.log(`  ${clr.dim}context${clr.reset}   ${clr.yellow}not set${clr.reset}  ${clr.dim}(run: ${cli} use)${clr.reset}`);
+        }
+        if (token) {
+          console.log(`  ${clr.dim}token  ${clr.reset}   ${clr.cyan}${token.slice(0, 14)}…${clr.reset}`);
+        } else {
+          console.log(`  ${clr.dim}token  ${clr.reset}   ${clr.yellow}none${clr.reset}  ${clr.dim}(run: ${cli} login)${clr.reset}`);
+        }
+        console.log(`  ${clr.dim}api    ${clr.reset}   ${clr.dim}${apiBase}${clr.reset}`);
+        console.log(`  ${clr.dim}config ${clr.reset}   ${clr.dim}${ctx.configPath}${clr.reset}`);
+        console.log();
+      }),
+  );
+}
+
+// ─── orgCommand (backward compat) ────────────────────────────────────────────
+
+export function orgCommand(deps: OrgCliDeps): Command {
+  const root = new Command('org').description('Org, workspace, and project management');
+  addGlobalCommands(root, deps);
+  root.addCommand(buildOrgCommand(deps));
+  root.addCommand(buildWsCommand(deps));
+  root.addCommand(buildProjCommand(deps));
+  return root;
+}
+
+// ─── use command implementation ───────────────────────────────────────────────
+
+async function runUseCommand(
+  http: ApiClient,
+  ctx:  ContextManager<Record<string, string | undefined>>,
+  path?: string,
+): Promise<void> {
+  async function pick<T extends { id: string; slug: string; name?: string }>(label: string, items: T[]): Promise<T> {
+    if (!items.length) fatal(`No ${label}s found.`);
+    if (items.length === 1) return items[0]!;
+    console.log(`\nSelect ${label}:`);
+    items.forEach((it, i) => console.log(`  ${clr.cyan}${i + 1}${clr.reset}  ${it.slug}${it.name ? `  ${clr.dim}${it.name}${clr.reset}` : ''}`));
+    const ans = await prompt(`${label} [1-${items.length}]: `);
+    const n   = parseInt(ans, 10);
+    if (!n || n < 1 || n > items.length) fatal('Invalid selection.');
+    return items[n - 1]!;
+  }
+
+  const parts    = (path ?? '').split('/').map(s => s.trim()).filter(Boolean);
+  const orgHint  = parts[0];
+  const wsHint   = parts[1];
+  const projHint = parts[2];
+
+  let orgSlug: string;
+  if (orgHint) {
+    orgSlug = orgHint;
+  } else {
+    const { orgs } = await http.get<{ orgs: OrgRow[] }>('/v1/orgs').catch(e => { console.error(e.message); process.exit(1); });
+    const org = await pick('org', orgs);
+    orgSlug = org.slug;
+  }
+
+  const orgRes = await http.get<{ org: OrgRow }>(`/v1/orgs/${orgSlug}`)
+    .catch(() => fatal(`Org not found: ${orgSlug}`));
+
+  if (parts.length <= 1 && orgHint) {
+    const cfg = ctx.loadConfig() as Record<string, unknown>;
+    ctx.saveConfig({ ...cfg, activeOrg: orgRes.org.slug, context: { org: orgRes.org.slug, orgId: orgRes.org.id } } as never);
+    success('Active org set.');
+    kv([['org', orgRes.org.slug]]);
+    return;
+  }
+
+  const { workspaces } = await http.get<{ workspaces: WsRow[] }>(`/v1/orgs/${orgSlug}/workspaces`).catch(e => { console.error(e.message); process.exit(1); });
+  const ws = wsHint
+    ? (workspaces.find(w => w.slug === wsHint) ?? fatal(`Workspace not found: ${wsHint}`))
+    : (workspaces.length === 1 ? workspaces[0]! : await pick('workspace', workspaces));
+
+  if (parts.length === 2) {
+    const cfg = ctx.loadConfig() as Record<string, unknown>;
+    ctx.saveConfig({ ...cfg, activeOrg: orgRes.org.slug } as never);
+    ctx.setContext({ org: orgRes.org.slug, orgId: orgRes.org.id, workspace: ws!.slug, workspaceId: ws!.id });
+    success('Active context set.');
+    kv([['org', orgRes.org.slug], ['workspace', ws!.slug]]);
+    return;
+  }
+
+  const projRes = await http.get<{ projects: ProjRow[] }>(`/v1/orgs/${orgSlug}/workspaces/${ws!.slug}/projects`).catch(e => { console.error(e.message); process.exit(1); });
+  const { projects } = projRes!;
+  const proj = projHint
+    ? (projects.find(p => p.slug === projHint) ?? fatal(`Project not found: ${projHint}`))
+    : (projects.length === 1 ? projects[0]! : await pick('project', projects));
+
+  ctx.setContext({
+    org:         orgRes.org.slug,
+    orgId:       orgRes.org.id,
+    workspace:   ws!.slug,
+    workspaceId: ws!.id,
+    project:     proj!.slug,
+    projectId:   proj!.id,
+  });
+
+  success('Active context set.');
+  kv([['org', orgRes.org.slug], ['workspace', ws!.slug], ['project', proj!.slug]]);
+}