@microsoft/apps-cli 0.0.1 → 0.4.0

package/README.md

@@ -1,3 +1,283 @@
 # @microsoft/apps-cli
 
-Microsoft Apps CLI — placeholder package.
+Command-line interface for the Microsoft Apps (MAAF) platform. Manage app lifecycle, sharing, and developer workflows from your terminal.
+
+## Installation
+
+```bash
+npm install --save-dev @microsoft/apps-cli
+```
+
+After installation, run commands using:
+
+```bash
+npx ms <command>
+```
+
+## Usage
+
+```bash
+npx ms app <verb> [options]
+```
+
+You can pass options on the command line, set them via environment variables (see each verb's `envVar` mapping), or in interactive mode let the CLI prompt for missing values.
+
+## Commands
+
+### `app create`
+
+Create a new MAAF app in the environment. Initializes a local git repo and scaffolds the app into `apps/<server-app-guid>`.
+
+```bash
+npx ms app create --display-name "My App" --repository-id <id>
+```
+
+### `app init`
+
+Initialize a `ms.config.json` for an existing app.
+
+```bash
+npx ms app init --display-name "My App" --environment-id <id>
+```
+
+### `app list`
+
+List all code apps in the environment.
+
+```bash
+npx ms app list
+npx ms app list --json
+```
+
+### `app show`
+
+Show the current app's configuration and bound resources (connectors, tables, procedures).
+
+```bash
+npx ms app show
+npx ms app show --json
+```
+
+### `app info`
+
+Fetch metadata for an app from the platform.
+
+```bash
+npx ms app info --app my-app
+```
+
+### `app build` / `app build-status`
+
+Initiate a cloud build for a MAAF app and poll its status.
+
+```bash
+npx ms app build --app my-app --commit abc1234
+npx ms app build-status --app my-app --operation-id <id>
+```
+
+### `app deploy`
+
+Deploy a previously-pushed commit to the environment.
+
+```bash
+npx ms app deploy
+npx ms app deploy --app my-app --commit abc1234
+```
+
+### `app push`
+
+Build the app and upload the artifact directly to the dev environment. Runs the configured build command, then zips the build output and adds `ms.config.json` at the zip root before uploading to the RP's `/uploadBuild` endpoint and deploying the resulting commit. Prompts for confirmation in interactive mode; skip the prompt with `--json` or by piping.
+
+```bash
+npx ms app push
+npx ms app push --environment-id <id>
+npx ms app push --json
+```
+
+### `app pack`
+
+Run the app's build command and copy the output to `.ms/packed/apps/<appId>/client/` for offline or manual deployment. Requires `appId`, `buildPath`, and `buildCommand` to be set in `ms.config.json`.
+
+```bash
+npx ms app pack
+```
+
+### `app dev`
+
+Run the app locally. Starts the dev script and a config server (default port 8080) that serves `ms.config.json` to the App Player. See [`docs/architecture/packages/microsoft-apps-cli/dev-command.md`](../../docs/architecture/packages/microsoft-apps-cli/dev-command.md) for the two-server design.
+
+```bash
+npx ms app dev
+npx ms app dev --port 8080 --local-app-url http://localhost:3000
+```
+
+### `app delete`
+
+Soft-delete a MAAF app. The server distinguishes "found and deleted" from "did not exist"; the CLI surfaces the latter as a warning rather than an error so the verb is safe to run idempotently in automation.
+
+```bash
+# Delete the app from the current ms.config.json directory
+npx ms app delete
+
+# Override the app name (env id still comes from ms.config.json)
+npx ms app delete --app my-app
+
+# Delete an app from outside its scaffolded directory by overriding both
+npx ms app delete --app my-app --environment-id <id>
+
+# Skip the "are you sure?" confirmation (CI mode is implicitly non-interactive)
+npx ms app delete --force
+
+# JSON output: { "appName": "...", "existed": true | false }
+npx ms app delete --json --force
+```
+
+In interactive mode the verb prompts for confirmation before deleting. `--force`/`-f` skips the prompt.
+
+### `app share` / `app unshare`
+
+Share or unshare a MAAF app with users and groups. `share` grants the `Microsoft App Reader` role at the app scope; `unshare` revokes all role assignments at that scope. Both verbs take a comma-separated positional list of principals — each entry is either a Microsoft Entra object ID (GUID) or an email address. Emails are resolved against your tenant via Microsoft Graph (`User.ReadBasic.All` and `Group.Read.All`).
+
+```bash
+# Share by email (resolved via Graph)
+npx ms app share alice@contoso.com,bob@contoso.com
+
+# Share by AAD object id
+npx ms app share 11111111-1111-4111-8111-111111111111
+
+# Unshare by email or id
+npx ms app unshare alice@contoso.com
+npx ms app unshare 22222222-2222-4222-8222-222222222222
+
+# Override the app name from ms.config.json
+npx ms app share --app my-app alice@contoso.com
+
+# JSON output for piping into other tools
+npx ms app unshare alice@contoso.com --json
+```
+
+If some entries can't be resolved (typo'd email, unsupported principal type, or insufficient Graph permissions), they're listed as a warning and the operation proceeds for the resolvable subset. If nothing resolves, the verb errors out with the per-entry reasons.
+
+In `--json` mode the output is an envelope so automation can detect partial success without parsing stderr:
+
+```json
+{
+  "result": {
+    "put": [
+      /* server response */
+    ]
+  },
+  "warnings": [
+    { "input": "unknown@contoso.com", "reason": "no user or group found in this tenant ..." }
+  ]
+}
+```
+
+`warnings` is always present (empty array on full success).
+
+### `app refresh`
+
+Refresh data sources in the current app.
+
+```bash
+npx ms app refresh
+npx ms app refresh --data-source-name contact
+```
+
+### `app add action` / `app add table` / `app add procedure` / `app remove table` / `app remove procedure`
+
+Bind or unbind data sources (connector actions, Dataverse tables, SQL stored procedures, etc.) to the app. `app add action` adds a non-tabular connector (e.g. Office 365); `app add table` adds a tabular connector data source. Both verbs run a DLP preflight, prompt for a connection when `--connection-id` is omitted, and offer to create one for you. Use `--skip-codegen` to skip TypeScript regeneration.
+
+```bash
+npx ms app add action --api-id shared_office365
+npx ms app add action --api-id shared_sql --connection-id <id>
+npx ms app add table --api-id shared_sql --connection-id <id> --dataset <db> --table <tbl>
+npx ms app add procedure --api-id shared_sql --connection-id <id> --dataset <db>
+npx ms app remove table --api-id dataverse --data-source-name contact --force
+```
+
+### `app set-setting` / `app get-settings`
+
+Read and write app settings stored in `ms.config.json`.
+
+```bash
+npx ms app get-settings
+npx ms app set-setting --show-header false --enable-catalyst true
+```
+
+### `connector list-actions`
+
+Search Dataverse actions and functions in the environment by name.
+
+```bash
+npx ms connector list-actions --search "account"
+```
+
+### `auth login`
+
+Sign in interactively using MSAL (opens the system browser). Optionally pass `--hint` to pre-fill the username.
+
+```bash
+npx ms auth login
+npx ms auth login --hint alice@contoso.com
+```
+
+On success prints `Signed in as <email>`.
+
+### `auth status`
+
+Print the currently signed-in account (or a prompt to run `auth login` if not signed in).
+
+```bash
+npx ms auth status
+```
+
+### `auth logout`
+
+Remove the cached Entra ID account.
+
+```bash
+npx ms auth logout
+```
+
+### `telemetry enable` / `telemetry disable` / `telemetry status`
+
+Manage CLI telemetry settings.
+
+```bash
+npx ms telemetry status
+npx ms telemetry disable --console
+```
+
+## Configuration
+
+The CLI reads configuration from `ms.config.json` in the current directory. Notable fields:
+
+- `appId` — Server-side app identifier; consumed by `app show`, `app deploy`, `app share`, `app unshare`, etc. when `--app` is omitted.
+- `environmentId` — The target environment. Resolved config-first, then `--environment-id`.
+
+## Global options
+
+| Option              | Alias | Description                                                           |
+| ------------------- | ----- | --------------------------------------------------------------------- |
+| `--cloud`           |       | Cloud instance to use (e.g. `prod`, `gccmoderate`, `gcchigh`, `dod`). |
+| `--environment-id`  | `-e`  | Environment ID to connect to.                                         |
+| `--non-interactive` |       | Run without interactive prompts (all parameters must be provided).    |
+| `--json`            |       | Format output as JSON.                                                |
+| `--no-color`        |       | Disable coloured output.                                              |
+
+## Telemetry
+
+CLI events are tagged with `clientType: NodeCLI` (or `PacCLI` when invoked through `pac`) and prefixed `MicrosoftAppsCLI.`. Disable transmission with `npx ms telemetry disable`.
+
+## Design Docs
+
+The product spec for this CLI lives in [`docs/specs/microsoft-apps-cli/`](../../docs/specs/microsoft-apps-cli/):
+
+| File                  | Covers                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `principles.md`       | Seven design principles in priority order — the rules that govern every CLI decision  |
+| `style-guidelines.md` | Command structure, naming conventions, output/error format, help text format          |
+| `commands.md`         | Full command reference: required flags, optional flags, and purpose for every command |
+
+**When contributing**: if you add a command, rename a flag, or change observable behavior, update `commands.md` (and `style-guidelines.md` if you introduce a new convention). The spec is the authoritative user-facing reference and must stay in sync with the code.

package/dist/ArgumentProvider.d.ts

@@ -0,0 +1,102 @@
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+import type { IHttpClient } from '@microsoft/apps-actions';
+import { type Cloud } from '@microsoft/apps-common/services';
+import type { CliLogger } from './Logger/CliLogger.js';
+import type { CliOption } from './Types/Argument.types.js';
+import type { IAuthenticationProvider } from './Types/Cli.types.js';
+import type { ResolvedCommand } from './Types/Command.types.js';
+export interface IArgumentProvider {
+    addOption(cliOption: CliOption): void;
+    addOptions(cliOptions: CliOption[]): void;
+    addSwitch(cliOption: CliOption): void;
+    addSwitches(cliOptions: CliOption[]): void;
+    consumePositionalArg(name: string): void;
+    getPositionalArg(index: number): string | undefined;
+    runVerb(): Promise<void>;
+    getVerb(): string;
+    getResolvedCommand(): ResolvedCommand | null;
+    handleGlobalHelpOrFlagsAndExit(): void;
+    getOption<T>(key: string, ignorePrompt?: boolean): Promise<T>;
+    getAuthenticationProvider(): IAuthenticationProvider;
+    getHttpClient(): IHttpClient;
+    getTenantIdAsync(): Promise<string | undefined>;
+    getAuthResourceUrl(): string;
+    getLoginAuthority(tenantId: string): string;
+    setDescription(description: string): void;
+    isJsonMode(): boolean;
+    addExamples(examples: string[]): void;
+    /** Returns all `--flag` tokens currently registered with the program (including short aliases). */
+    getRegisteredFlags(): ReadonlySet<string>;
+    /** Returns the validated, normalized user-facing cloud value (from --cloud or ms.config.json). */
+    getCloud(): Cloud | undefined;
+}
+export declare class ArgumentProvider implements IArgumentProvider {
+    private _httpClient;
+    private _logger;
+    private _authenticationProvider;
+    private _environmentId;
+    private _cloud;
+    private _region;
+    private _verb;
+    private _resolvedCommand;
+    private _tokensConsumed;
+    private _program;
+    private _options;
+    private _positionalArgs;
+    private _positionalArgNames;
+    private _isParsed;
+    constructor(_httpClient: IHttpClient, _logger: CliLogger, _authenticationProvider: IAuthenticationProvider);
+    addSwitch(cliOption: CliOption): void;
+    addSwitches(cliOptions: CliOption[]): void;
+    /**
+     * Consumes the next positional token from process.argv before Commander parses flags.
+     * Increments the internal token counter so runVerb() excludes this token from Commander's
+     * args, and updates the usage string so --help shows the argument name.
+     *
+     * Must be called before runVerb().
+     */
+    consumePositionalArg(name: string): void;
+    getPositionalArg(index: number): string | undefined;
+    addOption(cliOption: CliOption): void;
+    addOptions(cliOptions: CliOption[]): void;
+    runVerb(): Promise<void>;
+    handleGlobalHelpOrFlagsAndExit(): void;
+    getVerb(): string;
+    getResolvedCommand(): ResolvedCommand | null;
+    getOption<T>(key: string, ignorePrompt?: boolean): Promise<T>;
+    getAuthenticationProvider(): IAuthenticationProvider;
+    getHttpClient(): IHttpClient;
+    /**
+     * Returns the tenant ID for the authenticated user, acquiring a token first if needed.
+     *
+     * NodeMsalAuthenticationProvider only populates _tenantId after getAccessTokenForResource()
+     * is called. This method pre-acquires a token for the Power Platform resource so the tenant
+     * ID is always available after runVerb() completes.
+     */
+    getTenantIdAsync(): Promise<string | undefined>;
+    getAuthResourceUrl(): string;
+    getCloud(): Cloud | undefined;
+    getLoginAuthority(tenantId: string): string;
+    /**
+     * Sets the description for the current command context.
+     * This is used to display help information specific to the verb being executed.
+     *
+     * @param {string} description - The description to set for the program.
+     */
+    setDescription(description: string): void;
+    isJsonMode(): boolean;
+    addExamples(examples: string[]): void;
+    getRegisteredFlags(): ReadonlySet<string>;
+    getEnvironmentId(): string | undefined;
+    private _getRequiredVariables;
+    /**
+     * @param {CliOption} cliOption
+     * @param {boolean} [hasValue=true] true if the option requires a value, false for a switch such as --help
+     */
+    private _createOption;
+    private _createFlags;
+    private _createSwitchFlags;
+}
+//# sourceMappingURL=ArgumentProvider.d.ts.map

package/dist/ArgumentProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgumentProvider.d.ts","sourceRoot":"","sources":["../src/ArgumentProvider.ts"],"names":[],"mappings":"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"}