sk-az-tools/src/cli.ts

#!/usr/bin/env node
// SPDX-License-Identifier: MIT

import { parseArgs } from "node:util";

import { runCommand } from "./cli/commands.ts";
import {
  normalizeOutputFormat,
  omitPermissionGuidColumns,
  outputFiltered,
  parseHeaderSpec,
  renderOutput,
} from "./cli/utils.ts";

type CliValues = {
  help?: boolean;
  "display-name"?: string;
  "app-id"?: string;
  resources?: string;
  "use-device-code"?: boolean;
  "no-browser"?: boolean;
  browser?: string;
  "browser-profile"?: string;
  all?: boolean;
  resolve?: boolean;
  short?: boolean;
  filter?: string;
  query?: string;
  header?: string;
  output?: string;
  [key: string]: string | boolean | undefined;
};

function usage(): string {
  return `Usage: sk-az-tools <command> [options]

Commands:
  login                     Authenticate selected resources
  logout                    Sign out and clear login state
  list-apps                 List Entra applications
  list-app-permissions      List required permissions for an app
  list-app-grants           List OAuth2 grants for an app
  list-resource-permissions List available permissions for a resource app
  table                     Render stdin JSON as Markdown table

Global options (all commands):
  -q, --query <jmespath>
  -o, --output <format>     table|t|alignedtable|at|prettytable|pt|tsv
  -h, --help

Use: sk-az-tools --help <command>
or:  sk-az-tools <command> --help`;
}

function usageListApps(): string {
  return `Usage: sk-az-tools list-apps [--display-name|-n <name>] [--app-id|-i <appId>] [--filter|-f <glob>] [global options]

Options:
  -n, --display-name <name>  Get app by name
  -i, --app-id <appId>       Get app by id
  -f, --filter <glob>        Filter by app display name glob`;
}

function usageLogin(): string {
  return `Usage: sk-az-tools login [--resources <csv>] [--use-device-code] [--no-browser] [--browser <name>] [--browser-profile <profile>] [global options]

Options:
  --resources <csv>         Comma-separated resources: graph,devops,arm (default: all)
  --use-device-code         Use device code flow instead of interactive flow
  --no-browser              Do not launch browser; print interactive URL to stderr
  --browser <name>          Browser keyword: brave|browser|browserPrivate|chrome|edge|firefox
  --browser-profile <name>  Chromium profile name (e.g. Default, "Profile 1")`;
}

function usageLogout(): string {
  return `Usage: sk-az-tools logout [--all] [global options]

Options:
  --all                     Clear login state and remove all cached accounts`;
}

function usageListAppPermissions(): string {
  return `Usage: sk-az-tools list-app-permissions --app-id|-i <appId> [--resolve|-r] [--short|-s] [--filter|-f <glob>] [global options]

Options:
  -i, --app-id <appId>       Application (client) ID (required)
  -r, --resolve              Resolve permission GUIDs to human-readable values
  -s, --short                Makes output more compact
  -f, --filter <glob>        Filter by permission name glob`;
}

function usageListAppGrants(): string {
  return `Usage: sk-az-tools list-app-grants --app-id|-i <appId> [global options]

Options:
  -i, --app-id <appId>       Application (client) ID (required)`;
}

function usageListResourcePermissions(): string {
  return `Usage: sk-az-tools list-resource-permissions [--app-id|-i <appId> | --display-name|-n <name>] [--filter|-f <glob>] [global options]

Options:
  -i, --app-id <appId>       Resource app ID
  -n, --display-name <name>  Resource app display name
  -f, --filter <glob>        Filter by permission name glob`;
}

function usageTable(): string {
  return `Usage: sk-az-tools table [--header|-H <spec|auto|a|original|o>] [global options]

Options:
  -H, --header <value>       Header mode/spec: auto|a (default), original|o, OR "col1, col2" OR "key1: Label 1, key2: Label 2"`;
}

function usageCommand(command: string): string {
  switch (command) {
    case "login":
      return usageLogin();
    case "list-apps":
      return usageListApps();
    case "logout":
      return usageLogout();
    case "list-app-permissions":
      return usageListAppPermissions();
    case "list-app-grants":
      return usageListAppGrants();
    case "list-resource-permissions":
      return usageListResourcePermissions();
    case "table":
      return usageTable();
    default:
      return `Unknown command: ${command}\n\n${usage()}`;
  }
}

async function main(): Promise<void> {
  const argv = process.argv.slice(2);
  const command = argv[0];
  if (!command) {
    console.log(usage());
    process.exit(0);
  }
  if (command === "-h" || command === "--help") {
    const helpCommand = argv[1];
    console.log(helpCommand ? usageCommand(helpCommand) : usage());
    process.exit(0);
  }

  const { values } = parseArgs({
    args: argv.slice(1),
    options: {
      help: { type: "boolean", short: "h" },
      "display-name": { type: "string", short: "n" },
      "app-id": { type: "string", short: "i" },
      resources: { type: "string" },
      "use-device-code": { type: "boolean" },
      "no-browser": { type: "boolean" },
      browser: { type: "string" },
      "browser-profile": { type: "string" },
      all: { type: "boolean" },
      resolve: { type: "boolean", short: "r" },
      short: { type: "boolean", short: "s" },
      filter: { type: "string", short: "f" },
      query: { type: "string", short: "q" },
      header: { type: "string", short: "H" },
      output: { type: "string", short: "o" },
    },
    strict: true,
    allowPositionals: false,
  });

  const typedValues = values as CliValues;

  if (typedValues.help) {
    console.log(usageCommand(command));
    process.exit(0);
  }

  const outputFormat = normalizeOutputFormat(typedValues.output);
  const result = await runCommand(command, typedValues);
  const filtered = outputFiltered(result, typedValues.query);
  const output = command === "list-app-permissions" && typedValues.short
    ? omitPermissionGuidColumns(filtered)
    : filtered;
  const headerSpec = parseHeaderSpec(typedValues.header);

  renderOutput(command, output, outputFormat, headerSpec);
}

main().catch((err: unknown) => {
  const error = err as Error;
  console.error(`Error: ${error.message}`);
  console.error(usage());
  process.exit(1);
});