@antasphere/chassis-cli 0.0.0-stage → 1.0.1

package/src/commands/completion.ts

@@ -0,0 +1,102 @@
+import type { Command } from 'commander';
+import { CliUsageError, type CliIo } from '../context.js';
+import type { CliIdentity } from '../identity.js';
+
+/**
+ * Shell completion scripts, generated from the live command tree (so a new
+ * command is picked up automatically). Word-level completion: top-level
+ * commands, then subcommands where they exist.
+ */
+
+interface CmdInfo {
+  name: string;
+  subs: string[];
+}
+
+function commandTree(program: Command): CmdInfo[] {
+  return program.commands
+    .filter((c) => !c.name().startsWith('help'))
+    .map((c) => ({
+      name: c.name(),
+      subs: c.commands.map((s) => s.name())
+    }));
+}
+
+function bashScript(bin: string, tree: CmdInfo[]): string {
+  const top = tree.map((c) => c.name).join(' ');
+  const cases = tree
+    .filter((c) => c.subs.length > 0)
+    .map((c) => `    ${c.name}) COMPREPLY=( $(compgen -W "${c.subs.join(' ')}" -- "$cur") ); return ;;`)
+    .join('\n');
+  return `# bash completion for ${bin} — eval "$(${bin} completion bash)"
+_${bin}_completions() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${top}" -- "$cur") )
+    return
+  fi
+  case "$prev" in
+${cases}
+  esac
+}
+complete -F _${bin}_completions ${bin}
+`;
+}
+
+function zshScript(bin: string, tree: CmdInfo[]): string {
+  const top = tree.map((c) => c.name).join(' ');
+  const cases = tree
+    .filter((c) => c.subs.length > 0)
+    .map((c) => `    ${c.name}) compadd ${c.subs.join(' ')} ;;`)
+    .join('\n');
+  return `#compdef ${bin}
+# zsh completion for ${bin} — eval "$(${bin} completion zsh)"
+_${bin}() {
+  if (( CURRENT == 2 )); then
+    compadd ${top}
+    return
+  fi
+  case "\${words[2]}" in
+${cases}
+  esac
+}
+compdef _${bin} ${bin}
+`;
+}
+
+function fishScript(bin: string, tree: CmdInfo[]): string {
+  const lines = [
+    `# fish completion for ${bin} — ${bin} completion fish | source`,
+    `complete -c ${bin} -f -n "__fish_use_subcommand" -a "${tree.map((c) => c.name).join(' ')}"`
+  ];
+  for (const c of tree) {
+    if (c.subs.length > 0) {
+      lines.push(`complete -c ${bin} -f -n "__fish_seen_subcommand_from ${c.name}" -a "${c.subs.join(' ')}"`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function registerCompletionCommand(identity: CliIdentity, program: Command, io: CliIo): void {
+  program
+    .command('completion <shell>')
+    .description('Print a completion script for bash, zsh, or fish')
+    .action(async (shell: string) => {
+      const tree = commandTree(program);
+      switch (shell) {
+        case 'bash':
+          io.out.write(bashScript(identity.bin, tree));
+          return;
+        case 'zsh':
+          io.out.write(zshScript(identity.bin, tree));
+          return;
+        case 'fish':
+          io.out.write(fishScript(identity.bin, tree));
+          return;
+        default:
+          throw new CliUsageError(`Unsupported shell "${shell}" — bash, zsh, or fish.`);
+      }
+    });
+}

package/src/commands/demo.ts

@@ -0,0 +1,271 @@
+import type { Command } from 'commander';
+import { PlatformApiError, type ChassisClient } from '@antasphere/chassis-sdk';
+import { DEMO_PASS_MAX_MINUTES, type DemoPass } from '@antasphere/chassis-contract';
+import { CliApiRefusal, CliUsageError, printJson, table, type CliIo } from '../context.js';
+import type { CliKit } from '../kit.js';
+import { withOwnerSession } from '../owner-session.js';
+
+/**
+ * The demo commands: an owner mints a link that signs one member in without
+ * a password, for a demonstration (the demo pass spec, section 8). The
+ * routes exist only while the instance's DEMO_SIGN_IN switch is on, on the
+ * self-hosted edition, and they refuse every machine credential: these
+ * commands sign in as the owner (owner-session.ts) and never send a key.
+ *
+ * The secret is in the mint's answer only, and leaves this process in one
+ * place: inside the links. `--json` is `{ passes: [{ pass, links }], refused }`
+ * through `printJson` (the raw sink); every human line goes through the sanitizing sinks the
+ * runner installed, since a member's name is somebody else's text.
+ */
+
+/** The instance's unknown-path answer: what all three routes are while the switch is off. */
+const SWITCH_OFF =
+  'Demo sign-in is off on this instance (DEMO_SIGN_IN), or this is the cloud edition, where demo links are minted at the Antasphere hub.';
+
+/**
+ * The server's refusals of the demo routes. Their sentences are the ones to
+ * read, so they reach the runner as worded refusals: its generic hints speak
+ * of API keys, and these commands hold none.
+ */
+/** The role gate's refusal: the person who signed in is an admin or a member. */
+const NOT_AN_OWNER =
+  'Only an owner of this workspace manages demo links: the account that signed in is not one.';
+
+const REFUSALS = new Set([
+  'no_such_member',
+  'owner_target',
+  'demo_address_required',
+  'two_factor_enrolled',
+  'guest_target',
+  'cross_workspace_target',
+  'invalid_demo_path',
+  'sessions_only',
+  'demo_session',
+  'not_found'
+]);
+
+/** A refusal about ONE member: the others named on the command are still served. */
+class MemberRefusal extends CliApiRefusal {
+  constructor(
+    message: string,
+    status: number,
+    public readonly code: string
+  ) {
+    super(message, status);
+  }
+}
+
+async function explained<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (e) {
+    if (e instanceof PlatformApiError) {
+      if (e.status === 404 && e.code === 'not_found' && e.message === 'Not found') {
+        throw new CliApiRefusal(SWITCH_OFF, 404);
+      }
+      // The role gate answers the generic `forbidden`; the runner's hint for
+      // a 403 speaks of an API key, which this command never holds.
+      if (e.status === 403 && e.code === 'forbidden') throw new CliApiRefusal(NOT_AN_OWNER, 403);
+      if (REFUSALS.has(e.code)) throw new MemberRefusal(e.message, e.status, e.code);
+    }
+    throw e;
+  }
+}
+
+/**
+ * The server's page rule (`isSafeDemoPath`), checked here too so a bad
+ * `--path` costs no sign-in: 1 to 2048 characters, one leading `/` (never
+ * `//` nor `/\`), no `#`, no space or control character.
+ */
+export function isSafeDemoPath(path: string): boolean {
+  if (path.length < 1 || path.length > 2048) return false;
+  if (!path.startsWith('/') || path.startsWith('//') || path.startsWith('/\\')) return false;
+  for (let i = 0; i < path.length; i++) {
+    const code = path.charCodeAt(i);
+    if (code < 0x21 || code === 0x7f) return false;
+  }
+  return !path.includes('#');
+}
+
+/** `--hours` / `--minutes` as the mint's `expiresInMinutes`, or undefined for the server's default. */
+function lifetimeMinutes(opts: { hours?: string; minutes?: string }): number | undefined {
+  if (opts.hours !== undefined && opts.minutes !== undefined) {
+    throw new CliUsageError('Pass either --hours or --minutes, not both.');
+  }
+  const raw = opts.hours ?? opts.minutes;
+  if (raw === undefined) return undefined;
+  const n = /^\d+$/.test(raw) ? Number(raw) : NaN;
+  const minutes = opts.hours !== undefined ? n * 60 : n;
+  if (!Number.isSafeInteger(minutes) || minutes < 1 || minutes > DEMO_PASS_MAX_MINUTES) {
+    throw new CliUsageError(
+      `A demo link lives from one minute to a week (${DEMO_PASS_MAX_MINUTES} minutes): ` +
+        `--${opts.hours !== undefined ? 'hours' : 'minutes'} takes a whole number in that range.`
+    );
+  }
+  return minutes;
+}
+
+/** The link for one page: the fragment never reaches a server log. */
+function demoLink(baseUrl: string, secret: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, '')}/demo#pass=${secret}&to=${encodeURIComponent(path)}`;
+}
+
+const collect = (value: string, previous: string[]): string[] => [...previous, value];
+
+interface OwnerOpts {
+  ownerEmail?: string;
+  ownerPasswordStdin: boolean;
+}
+
+export function registerDemoCommands<TClient extends ChassisClient<string>>(
+  kit: CliKit<TClient>,
+  program: Command,
+  io: CliIo
+): void {
+  const { identity, resolveContext } = kit;
+  const prefix = identity.envPrefix;
+
+  const demo = program
+    .command('demo')
+    .description(
+      'Demo links: sign a member in without a password, for a demonstration (owner; DEMO_SIGN_IN on)'
+    );
+
+  /** The owner's sign-in flags every demo command carries. */
+  const ownerFlags = (cmd: Command): Command =>
+    cmd
+      .option('--owner-email <address>', `the owner who signs in (or ${prefix}_OWNER_EMAIL)`)
+      .option(
+        '--owner-password-stdin',
+        `read the owner's password from the first line of stdin (or ${prefix}_OWNER_PASSWORD)`,
+        false
+      );
+
+  const session = (opts: OwnerOpts) => ({
+    identity,
+    ...(opts.ownerEmail !== undefined ? { ownerEmail: opts.ownerEmail } : {}),
+    ownerPasswordStdin: opts.ownerPasswordStdin
+  });
+
+  // ── demo link ─────────────────────────────────────────────────────────────
+  ownerFlags(
+    demo
+      .command('link')
+      .description('Mint one demo pass per member and print one link per page')
+      .requiredOption(
+        '--email <address>',
+        'a member the links sign in (repeatable: one sign-in, one pass per member)',
+        collect,
+        []
+      )
+      .option('--path <p>', 'a page the link lands on (repeatable; the first is the default, /)', collect, [])
+      .option('--hours <n>', 'how long the link lives, in hours (default: a day; at most a week)')
+      .option('--minutes <n>', 'how long the link lives, in minutes (instead of --hours)')
+  ).action(
+    async (
+      opts: OwnerOpts & { email: string[]; path: string[]; hours?: string; minutes?: string },
+      cmd: Command
+    ) => {
+      const paths = opts.path.length > 0 ? opts.path : ['/'];
+      // Everything the command can refuse by itself, before any sign-in.
+      for (const path of paths) {
+        if (!isSafeDemoPath(path)) {
+          throw new CliUsageError(
+            `--path "${path}" is not a page of this instance: a path starting with a single /, ` +
+              'with no #, no space and no control character, at most 2048 characters.'
+          );
+        }
+      }
+      const expiresInMinutes = lifetimeMinutes(opts);
+      const ctx = resolveContext(cmd, io);
+      // ONE sign-in for every member named: a script that makes the links of
+      // a whole demonstration calls the command once. A member the server
+      // refuses does not stop the others; the command says who and why, and
+      // exits 1.
+      const { passes, refused } = await withOwnerSession(ctx, session(opts), async (client) => {
+        const passes: { pass: DemoPass; links: { path: string; url: string }[] }[] = [];
+        const refused: { email: string; code: string; message: string }[] = [];
+        for (const email of opts.email) {
+          try {
+            const minted = await explained(() =>
+              client.mintDemoPass({
+                email,
+                path: paths[0]!,
+                ...(expiresInMinutes !== undefined ? { expiresInMinutes } : {})
+              })
+            );
+            passes.push({
+              pass: minted.pass,
+              links: paths.map((path) => ({ path, url: demoLink(ctx.baseUrl, minted.secret, path) }))
+            });
+          } catch (e) {
+            // Anything else (the switch off, the signed-in account not an
+            // owner, the network) is the same for everyone: no point going on.
+            if (!(e instanceof MemberRefusal)) throw e;
+            refused.push({ email, code: e.code, message: e.message });
+          }
+        }
+        return { passes, refused };
+      });
+      if (ctx.json) {
+        printJson(io, { passes, refused });
+      } else {
+        for (const { pass, links } of passes) {
+          io.out.write(
+            `Demo link for ${pass.name} <${pass.email}>, valid until ${pass.expiresAt}:\n` +
+              links.map((l) => `${l.url}\n`).join('')
+          );
+        }
+      }
+      if (refused.length > 0) {
+        throw new CliApiRefusal(
+          refused.map((r) => `${r.email}: ${r.message}`).join('\n'),
+          refused.length === opts.email.length ? 403 : 207
+        );
+      }
+    }
+  );
+
+  // ── demo list ─────────────────────────────────────────────────────────────
+  ownerFlags(demo.command('list').description('List the demo passes of the workspace (newest first)')).action(
+    async (opts: OwnerOpts, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      const { passes } = await withOwnerSession(ctx, session(opts), (client) =>
+        explained(() => client.demoPasses())
+      );
+      if (ctx.json) return printJson(io, { passes });
+      if (passes.length === 0) {
+        io.out.write('No demo passes.\n');
+        return;
+      }
+      io.out.write(
+        table([
+          ['ID', 'PERSON', 'PAGE', 'EXPIRES', 'REVOKED', 'LAST USED', 'USES'],
+          ...passes.map((p: DemoPass) => [
+            p.id,
+            p.email,
+            p.targetPath,
+            p.expiresAt,
+            p.revokedAt ?? '-',
+            p.lastUsedAt ?? 'never',
+            String(p.useCount)
+          ])
+        ])
+      );
+    }
+  );
+
+  // ── demo revoke ───────────────────────────────────────────────────────────
+  ownerFlags(
+    demo.command('revoke <id>').description('Revoke a demo pass; the sessions it opened end with it')
+  ).action(async (id: string, opts: OwnerOpts, cmd: Command) => {
+    const ctx = resolveContext(cmd, io);
+    const pass = await withOwnerSession(ctx, session(opts), (client) =>
+      explained(() => client.revokeDemoPass(id))
+    );
+    if (ctx.json) return printJson(io, pass);
+    io.out.write(
+      `Revoked the demo pass ${pass.id} for ${pass.email}. The sessions it opened are signed out.\n`
+    );
+  });
+}

package/src/commands/files.ts

@@ -0,0 +1,197 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, resolve, win32 } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { ReadableStream as WebReadableStream } from 'node:stream/web';
+import type { Command } from 'commander';
+import {
+  DEFAULT_DOWNLOAD_TIMEOUT_MS,
+  PlatformApiError,
+  type ChassisClient,
+  type ListParams
+} from '@antasphere/chassis-sdk';
+import { CliUsageError, fmtBytes, printJson, type CliIo } from '../context.js';
+import type { CliKit } from '../kit.js';
+import { writeContained } from '../safe-write.js';
+
+/**
+ * The platform substrate commands inherited from the template: instance
+ * discovery, the raw workspace-files surface, and the full export download.
+ */
+
+/**
+ * Turn a server-chosen `originalName` into a plain filename, or refuse.
+ *
+ * The stored name is whatever the uploader (possibly a collaborator, on a
+ * shared instance) typed: `../../.bashrc`, `/etc/cron.d/x`, `.npmrc`, and
+ * on Windows `..\\..\\x` are all valid under the wire schema. Both POSIX
+ * and Windows separators are stripped, then anything that is not an inert
+ * plain filename is refused rather than silently rewritten — the caller
+ * always has `--out <path>` to name the destination themselves.
+ */
+export function safeDownloadName(originalName: string): string {
+  const name = basename(win32.basename(originalName));
+  if (name === '' || name === '.' || name === '..' || name.startsWith('.')) {
+    throw new CliUsageError(
+      `Refusing to derive a filename from the stored name ${JSON.stringify(originalName)} — ` +
+        'pass --out <path> to choose where it goes.'
+    );
+  }
+  return name;
+}
+
+export function registerFileCommands<TClient extends ChassisClient<string>>(
+  kit: CliKit<TClient>,
+  program: Command,
+  io: CliIo
+): void {
+  const { requireApiKey, resolveContext } = kit;
+
+  program
+    .command('instance')
+    .description('Show instance discovery (public: name, version, auth methods)')
+    .action(async (_opts, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      const info = await ctx.client.instance();
+      if (ctx.json) return printJson(io, info);
+      io.out.write(
+        `${info.name}  v${info.version} (${info.edition})\n` +
+          `  setup required: ${info.setupRequired}\n` +
+          `  auth methods:   ${info.auth.methods.join(', ')}\n`
+      );
+    });
+
+  program
+    .command('export')
+    .description(`Download the full workspace export as a zip (key needs ${kit.identity.exportScope})`)
+    .option('-o, --out <path>', 'write to this path (defaults to export-<date>.zip)')
+    .action(async (opts: { out?: string }, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      const res = await ctx.client.downloadExport();
+      if (!res.body) {
+        throw new Error('The export response carried no body');
+      }
+      const out = opts.out ?? `export-${new Date().toISOString().slice(0, 10)}.zip`;
+      // Stream to disk — exports can be large, never buffer (unlike files
+      // download, whose objects are capped by MAX_FILE_SIZE_MB).
+      await pipeline(Readable.fromWeb(res.body as unknown as WebReadableStream), createWriteStream(out));
+      if (ctx.json) return printJson(io, { path: out });
+      io.out.write(`Export written to ${out}\n`);
+    });
+
+  const files = program.command('files').description('Manage workspace files');
+
+  files
+    .command('list')
+    .description('List files in the workspace (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)
+    .action(async (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 ctx.client.files(params);
+      const rows = [...first.files];
+      if (opts.all) {
+        let cursor = first.nextCursor;
+        while (cursor) {
+          const page = await ctx.client.files({ ...params, cursor });
+          rows.push(...page.files);
+          cursor = page.nextCursor;
+        }
+      }
+      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, { files: rows, nextCursor });
+      if (rows.length === 0) {
+        io.out.write('No files.\n');
+        return;
+      }
+      for (const f of rows) {
+        io.out.write(`${f.id}  ${fmtBytes(f.sizeBytes).padStart(9)}  ${f.originalName}\n`);
+      }
+      if (nextCursor) {
+        io.out.write(`More available: rerun with --cursor ${nextCursor} or --all\n`);
+      }
+    });
+
+  files
+    .command('upload <path>')
+    .description('Upload a local file')
+    .option('--name <name>', 'stored file name (defaults to the local basename)')
+    .option('--content-type <type>', 'content type', 'application/octet-stream')
+    .action(async (path: string, opts: { name?: string; contentType: string }, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      const bytes = await readFile(path);
+      const name = opts.name ?? basename(path);
+      const result = await ctx.client.uploadFile(name, new Uint8Array(bytes), opts.contentType);
+      if (ctx.json) return printJson(io, result);
+      io.out.write(
+        `Uploaded ${result.file.originalName} (${fmtBytes(result.file.sizeBytes)})` +
+          `${result.deduplicated ? ' [deduplicated]' : ''}\n  id: ${result.file.id}\n`
+      );
+    });
+
+  files
+    .command('download <id>')
+    .description('Download a file by id')
+    .option('--out <path>', 'write to this exact path (your path, used verbatim)')
+    .option('--dir <path>', 'directory to write the stored name into (default: .)')
+    .action(async (id: string, opts: { out?: string; dir?: string }, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      const apiKey = await requireApiKey(ctx);
+      if (opts.out && opts.dir) {
+        throw new CliUsageError('Pass either --out <path> or --dir <path>, not both.');
+      }
+      const meta = await ctx.client.file(id);
+      const fetchImpl = io.fetch ?? globalThis.fetch.bind(globalThis);
+      const res = await fetchImpl(ctx.client.fileContentUrl(id), {
+        // This one bypasses the SDK, so it carries the SDK's headers itself:
+        // the key, and the selected workspace (a download follows it too).
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          ...(ctx.workspaceId !== undefined ? { 'x-workspace-id': ctx.workspaceId } : {})
+        },
+        // …and the SDK's deadline.
+        signal: AbortSignal.timeout(DEFAULT_DOWNLOAD_TIMEOUT_MS)
+      });
+      if (!res.ok) {
+        throw new PlatformApiError(res.status, 'download_failed', `Download failed with ${res.status}`);
+      }
+      const buf = Buffer.from(await res.arrayBuffer());
+      let out: string;
+      if (opts.out) {
+        // The caller typed this path — honour it verbatim.
+        out = opts.out;
+        await writeFile(out, buf);
+      } else {
+        // `originalName` is SERVER-controlled and unconstrained beyond
+        // 1-255 chars: it may be `../../.ssh/authorized_keys` or an
+        // absolute path. Never join it — take its basename, refuse the
+        // names that are not a plain filename, and write it contained
+        // inside the chosen directory (symlinks refused, mode forced).
+        const dir = resolve(opts.dir ?? '.');
+        const name = safeDownloadName(meta.originalName);
+        await mkdir(dir, { recursive: true });
+        out = await writeContained(dir, name, buf);
+      }
+      io.out.write(`Downloaded ${meta.originalName} → ${out} (${fmtBytes(buf.length)})\n`);
+    });
+
+  files
+    .command('rm <id>')
+    .description('Delete a file by id')
+    .action(async (id: string, _opts, cmd: Command) => {
+      const ctx = resolveContext(cmd, io);
+      await requireApiKey(ctx);
+      await ctx.client.deleteFile(id);
+      if (ctx.json) return printJson(io, { deleted: id });
+      io.out.write(`Deleted ${id}\n`);
+    });
+}