@microsoft/cmr-cli 0.0.0-stage → 0.32.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @microsoft/cmr-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line interface for Copilot Managed Runtime. Create, build, deploy, share, and manage apps and their data sources from your terminal.
+
+## Install
+
+```bash
+npm install -g @microsoft/cmr-cli
+```
+
+Run commands with `ms <command>`.
+
+## Commands
+
+- **`ms app …`** — app lifecycle and configuration: create, clone platform-managed repositories, init, list, info (`show` is a deprecated alias), build, build-status, pack, deploy, play (including branch or commit previews), dev, delete, share/unshare, share list, share link (create, list, revoke), add config (preview, requires the `alm` feature; registers a project deployment and creates its local overlay), add data-source (including repeated `--table` flags for adding multiple tables with per-table partial-success reporting), remove data-source, refresh data-source (`--offline`), and settings (get-settings, set-setting).
+- **`ms project …`** — project-related command groups. Managed project commands (`create`, `info`, `list`, `add deployment-target`, `build`, `build-status`, `deploy`, `deployment-status`, `pack`, `add approval`, `list approval`, `remove approval`) are preview and require the `projects` feature; project creation supports a platform-managed repository or `--repo <github-url>`. State commands are experimental and require the `state` feature.
+- **`ms project add|remove|list approval`** — manage who can approve deployments to a project's `Prod` target (preview, requires the `projects` feature). Approvers are Microsoft Entra object IDs or user/group email addresses; `remove --all` clears the list. Use `--project` and `--environment-id` outside a managed project directory.
+- **`ms deployment list|status`** — list project-scoped or environment-wide deployment history, or show the latest or selected deployment (preview, requires the `projects` feature). Use `--project <project-id>` to select project history explicitly; otherwise a local project config or the current app's live project association is used when available. Use `--environment-id` alone for environment-wide history and `--target` to select `prod` or a named target. Use `--continuation-token` to resume when the output reports more history. Latest-deployment detail includes created time, source links, requester and approval metadata, and build status when available.
+- **`ms deployment approve|reject|cancel --target <name>`** — act on a deployment that is awaiting approval (preview, requires the `projects` feature). `approve` and `reject` accept an optional `--comment`. They run only where the service's approvals feature is enabled.
+- **`ms connector …`** — list connectors and discover connector actions and functions in the environment.
+- **`ms project state …`** — clear Preview state or define and inspect the app's configured state schema (`add`, `alter`, `remove`, `list-schema`, `list-settings`, `set-setting`), or generate standalone TypeScript with `generate-code`. Experimental and off by default; turn it on with `ms feature enable --name state` or `MS_CLI_FEATURE_STATE=1`. It is also on for an app whose `ms.config.json` sets `state.enabled: true`.
+- **`ms auth …`** — sign in/out and manage cached accounts (login, logout, status, switch).
+- **`ms git auth …`** — refresh or establish the Entra↔GitHub identity mapping for external repos.
+- **`ms telemetry …`** — enable, disable, or check CLI telemetry.
+- **`ms feature …`** — list, inspect, enable, disable, or reset experimental and preview CLI features.
+
+Run `ms <command> --help` for the options on any command.
+
+## TLS certificate errors
+
+If the CLI reports `TlsCertificateTrustFailure`, configure your operating system and Node.js to
+trust your organization's certificate authority, or contact your network administrator. Do not
+disable TLS certificate validation. `TlsCertificateValidationFailure` indicates that the service
+certificate could not be validated; try again later, then contact Microsoft support with the
+reported session ID if the problem continues.
+
+Use `ms --version` or `ms -v` to print the CLI version. The version option is
+available only on the root command, not on commands such as `ms app list`.
+
+Managed project and deployment commands require the `projects` feature. Enable it with
+`ms feature enable --name projects`; it is also enabled automatically inside
+a managed project or an app associated with one. Project state commands additionally require the
+`state` feature.
+
+`ms app deploy` guards git-backed deployments when the working tree has uncommitted changes or local `main` is ahead of `origin/main`. Interactive runs can confirm and continue; non-interactive runs must pass `--force` to bypass the guard.
+
+On the default `/appframework` route, a deployment that needs app data migration is accepted as an operation. `ms app deploy` waits for that operation (up to 20 minutes) and reports success only after the service confirms the deployment. With the Managed DevOps route enabled, the service instead returns a durable deployment ID and the CLI polls until the deployment succeeds or reaches `AwaitingApproval`. Approval is a handoff point: the CLI returns the deployment ID instead of waiting for a human decision.
+
+`ms app deploy --no-wait` is available when the `projects` feature is enabled. It skips deployment polling, but still waits for a queued prerequisite build on git-backed apps and still packs/uploads external artifacts before submitting the deployment. After the service accepts the deployment, the command returns its stable deployment ID for later tracking.
+
+`ms app deploy --target <name>` requires the `alm` feature; without the feature the option is not
+registered and is rejected as unknown. Enable it with `ms feature enable --name alm` or
+`MS_CLI_FEATURE_ALM=1`. The target name is validated locally before any build or deploy call.
+After a successful targeted deploy, human output and the JSON `appPlayUri` field report the
+target-specific `/target/<name>` play URL rather than the base production URL.
+
+`ms project deploy` requires the `projects` feature and is a temporary single-app alias for the app
+deployment pipeline. Unless
+`--project` is supplied, it prefers the current app and its server-side project association
+before falling back to `ms.project.config.json`. The fallback project route requires the project to
+contain exactly one app. `--environment-id` takes precedence over app config, project config, and
+developer-environment routing. The final deploy uses Managed DevOps, matching `ms app deploy`
+when the `projects` feature is enabled, so `--no-wait` is available for the command. The command does
+not expose
+`--app` or `--artifact`. Without `--no-wait`, it waits until deployment succeeds or reaches
+`AwaitingApproval`, then returns the deployment ID instead of waiting for a human approval decision.
+When `--target` is supplied, successful output reports that target's `/target/<name>` play URL
+instead of the production URL. Multi-app project deployment will move to a dedicated service API.
+
+`ms project deployment-status` shows the latest deployment for the resolved project, or a specific
+deployment when `--deployment-id` is supplied. It prefers the current app's server-side project
+association, then falls back to local app/project configuration; use `--project` to select a
+project explicitly. Use `--environment-id` to route that project lookup to a specific environment;
+when an explicit project ID has no environment flag, the default environment is used.
+`ms deployment status` is an alias with the same flags and behavior.
+
+The complete `ms project state` command group is experimental and requires
+`MS_CLI_FEATURE_STATE=1`; without it the group is hidden from help and rejected as an
+unknown command.
+
+`ms project state clear [--app <app-id>] [--environment-id <id>]` discards the app's
+Preview state for **all users and all item types**. Live data, source code, and
+the app itself are unchanged. The app ID defaults from `ms.config.json`; an explicit
+real, non-zero app GUID (without `-dev`) works outside a checkout. The environment is resolved
+before confirmation, without inheriting an unrelated config environment.
+
+JSON/non-interactive runs require explicit `--force` acknowledgement, for example
+`ms project state clear --app <app-id> --force --json --non-interactive`. This skips
+local confirmation only, never Update authorization or server locks. A valid 200
+returns exit 0 with the exact `wasAlreadyEmpty`, `observedEmpty`, and `isComplete`
+Booleans; **request success does not mean purge completion**. The current service
+normally returns `isComplete: false`, which produces a stderr warning. Missing or
+invalid completion fields are errors. The client waits up to 120 seconds, never
+automatically retries or polls, and reports unknown outcome on interruption or
+connection loss. Do not chain Preview, writes, reindex, or deploy while completion
+is unconfirmed; there is no public reset-status endpoint.
+
+To include a schema in `ms app pack`, set `state.schemaPath` in the base app config to a
+project-relative JSON file. `data.schemaPath` and the legacy `db.schemaPath` alias remain supported;
+when multiple aliases are present, they must either all omit `schemaPath` or set path strings that
+match exactly (no normalization). Invalid aliases fail even if another alias is valid. These
+settings are base-only and cannot be overridden by a deployment overlay. Pack writes
+`dataSchema.json` and points the unchanged `manifest.dataSchemaPath` field to it, regardless of
+which alias was configured.
+`schemaPath` is optional: without it, pack writes no schema file and no `dataSchemaPath`.
+
+Optionally set `state.enabled`, `data.enabled`, or legacy `db.enabled` to a boolean to copy it to
+`manifest.dataEnabled`. Both `true` and `false` are preserved; if unset, the manifest field is
+omitted. When both aliases specify `enabled`, their values must agree; if only one specifies it,
+that value is used. This flag is also base-only and does not skip schema validation or packaging:
+a configured `schemaPath` is still validated and packaged when `enabled` is `false`, and
+`{ "data": { "enabled": true } }` enables data without a schema.
+
+For `ms project state` commands, `state.schemaPath` is the preferred state schema location.
+`state.enabled` is also accepted and copied to `manifest.dataEnabled` during pack.
+
+`ms app pack` also includes `package-inventory.json` beside the manifest (not under
+`client/`). The CLI selects the app's direct production dependencies and records their
+installed names and versions, following npm, pnpm, and Bun `node_modules` layouts and
+package symlinks without reading lockfiles. Dev and transitive-only dependencies are excluded.
+The versioned artifact distinguishes an explicit zero-package inventory from unavailable
+data and reports unresolved required dependencies and truncation.
+It does not include registry URLs, attest to bundled code, or select the build's package manager.
+Collection failures warn on stderr without failing the build or changing JSON stdout.
+See the [pack artifact contract](../../docs/specs/managed-apps-cli/commands.md#deploy)
+for the schema, limits, and consumer requirements.
+
+With the `alm` feature enabled, `ms project pack` uses the directory containing
+`ms.project.config.json` as the project root. When `components.apps` is present, only those listed
+directories are searched for app configs; each path must be the project root or a descendant, and
+symlinks that resolve outside that boundary are rejected. This supports apps nested anywhere within
+the project.
+When the list is absent, pack falls back to discovering app configs at the root and in immediate
+child directories. When no project config is present, it treats the directory containing the
+current app config as a single-app project. An empty app set fails before staging begins.
+`ms.config.json` takes precedence when both supported app config names exist in a directory. Packing
+logs which discovery mode it selected, remains local, and does not retrieve live app information.
+Apps without `package.json` and apps with `buildType: "none"` skip dependency installation. Output
+is written to `.ms/packed/apps/<appId>/` alongside `.ms/packed/project.manifest.json`, preserving
+the existing artifact if validation, an app build, or artifact promotion fails.
+
+`ms project pack --json` returns a discriminated project result. Successful responses include the
+promoted project paths, app pack results under `components.apps`, and install/pack/finalization
+timings. Success and failure responses include `logFile` when available, pointing to captured stdout
+and stderr from dependency-install and app-build commands, plus app-pack failure
+diagnostics, up to a 50 MB limit. Log creation and capture are best-effort and never change the
+command result. The five newest logs are retained, and staging directories older than 24 hours are
+removed. Failed responses include partial app results and timings, including elapsed app-pack phases
+measured before failure, but omit project artifact paths; dependency-install or app-pack failures do
+not prevent remaining project apps from being attempted.
+
+`ms project state generate-code` reads that schema locally and writes models, validators, and
+typed data services to `generated-typescript/` beside it. It needs no login or network connection,
+including in CI; there are no command-specific flags. Use `--json` for relative paths, item types,
+file count, and any cleanup warnings. Keep handwritten code outside the output directory:
+replacement requires a valid ownership manifest and refuses untracked files.
+
+Generated `update` methods send a complete writable document using PUT. Use `edit` for a fresh
+read/merge/conditional PUT with bounded conflict retries. Per-user services preserve private/shared
+scope. The generated services require Preview or a deployed app, not `ms app dev`; code generation
+does not deploy or provide a local state store. Attachment upload/clear and undocumented query
+operators are not generated. See the [command reference](../../docs/specs/managed-apps-cli/commands.md#generate-typescript)
+for output ownership, rollback, validation, and paging behavior.
+
+## Global options
+
+| Option              | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--non-interactive` | Run without prompts (all values must be supplied). |
+| `--json`            | Format output as JSON.                             |
+| `--no-color`        | Disable coloured output.                           |
+
+Full documentation is available in the [Copilot Managed Runtime documentation](https://go.microsoft.com/fwlink/?LinkId=2369054).