@appshell/cli 1.0.0-alpha.10 → 1.0.0-alpha.101

package/README.md

@@ -41,51 +41,240 @@ pnpm add -D @appshell/cli
 appshell [command]
 
 Commands:
-  appshell generate [target]  Generates a resource
-  appshell register           Register one or more appshell manifests
-  appshell start              Start the appshell runtime environment
+  appshell generate [target]           Generates a resource
+  appshell config [target]             Configures the appshell cli
+  appshell app <target>                Manage appshell applications
+  appshell dev                         Point an application at this package running
+                                       locally, for this browser only
+  appshell login                       Authenticate with an appshell registry
+  appshell logout                      Discard the stored credential for a registry
+  appshell publish                     Publish a package to the appshell registry
+  appshell unpublish <name> <version>  Remove a published package version
+  appshell trust                       Trust CI workflows to publish into a scope
+                                       without a stored secret
+  appshell outdated                    Analyzes shared dependencies for outdated versions
 ```
 
-### appshell generate
+These global options apply to every command:
+
+| Option | Default | Purpose |
+| ------ | ------- | ------- |
+| `-r, --registry` | `http://localhost:7070` | Registry to operate against |
+| `-a, --application` | — | Application, as `name` or `scope/name` |
+| `--scopeId` | `default` | Scope owning unqualified packages and applications |
+| `-k, --apiKey` | `""` | Api key, when the registry expects one |
+| `-v, --verbose` | `false` | Verbose output |
+
+`--registry` and `--application` fall back to `APPSHELL_REGISTRY` /
+`APPSHELL_APPLICATION`, then to `~/.appshell/config`. Set them once instead of
+passing them every time:
 
 ```bash
-appshell generate [target]
+appshell config set registry http://localhost:7070
+appshell config set application storefront
+appshell config list
+```
 
-Generates a resource
+## Vocabulary
 
-Commands:
-  appshell generate manifest  Generate the appshell manifest by processing the template specified by --template
-  appshell generate env       Generate the runtime environment js file that reflects the current process.env
-  appshell generate global-config     Generate the global appshell configuration file by merging sources specifed by --registry options
-  appshell generate metadata  Generate the appshell metadata file by merging sources specifed by --registry options
+| Term | Identity | What it is |
+| ---- | -------- | ---------- |
+| **Scope** | `acme` | Namespace and permission boundary |
+| **Package** | `acme/checkout@1.5.0` | What you publish. Immutable, digest-addressed |
+| **Application** | `acme/storefront` | The composition the registry serves |
+| **Remote** | `PingModule/Ping` | What the browser loads, over Module Federation |
+
+## Authenticating
+
+```bash
+appshell login                       # device flow against the configured issuer
+appshell login --clientSecret ...    # client credentials, for CI
+appshell logout
 ```
 
-## Generate manifest
+The token is stored per registry. A registry running `AUTH_MODE=none` needs none —
+commands only fail when the registry says so, and a 401 tells you to log in.
+`APPSHELL_TOKEN` overrides the stored credential. A GitHub Actions job can publish with
+neither — see [Trusted publishing](#trusted-publishing).
+
+## Publishing a package
+
+```bash
+appshell publish --template dist/appshell.template.json
+```
+
+Publishing is idempotent: the same content under the same version is a no-op.
+Different content under an existing version is rejected unless the registry allows
+forcing. When `--application` resolves, publish also **activates** the version there.
+
+| Option | When omitted | Purpose |
+| ------ | ------------ | ------- |
+| `-t, --template` | `appshell.template.json` | Template to process |
+| `--name` | the unscoped `package.json` name | Package name |
+| `--package-version` | the `package.json` version | Version to publish as |
+| `--visibility` | the registry defaults to `private` | Whether other scopes may activate it |
+| `-w, --watch` | `false` | Republish whenever the template changes |
+
+```bash
+appshell unpublish checkout 1.5.0
+```
+
+## Trusted publishing
+
+A GitHub Actions workflow can publish into a scope with its own OIDC identity, so no
+secret is stored anywhere. The scope's owner — or an organization admin, for a scope an
+organization owns — records which workflow may:
+
+```bash
+appshell trust add acme --github acme/widgets --workflow pipeline.yml --environment production
+appshell trust list acme
+appshell trust remove acme 1b2c3d4e     # the id as `list` shows it
+```
+
+`trust add` looks the repository up on GitHub and records it by its immutable ids, so a
+renamed or transferred repository, or a new one taking the old name, does not inherit the
+trust. Set `GITHUB_TOKEN` (or `GH_TOKEN`) to look up a private repository; `--github-api
+https://<host>/api/v3` and `--issuer` cover GitHub Enterprise Server. Naming an
+`--environment` is recommended: its protection rules then decide which branches and
+reviewers can publish.
+
+The workflow needs `id-token: write` and the registry's address, nothing else:
+
+```yaml
+permissions: { id-token: write, contents: read }
+env: { APPSHELL_REGISTRY: https://registry.appshell.org }
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      # ...build...
+      - run: npx appshell publish
+```
+
+With no `APPSHELL_TOKEN` and no stored login for the registry, `appshell publish` asks the
+runner for a token whose audience is the registry url as configured, without a trailing
+slash — the registry's `TRUSTED_PUBLISHING_AUDIENCE` must be exactly that — and presents
+it for that one request. Each publish mints its own and none is stored. An explicit
+`APPSHELL_TOKEN` or stored login wins, so a job that sets one publishes as that account.
+
+The package must name its scope, as `@acme/widgets`: a workflow has no namespace of its
+own. A refusal says what to check — `appshell trust list <scope>` and the job's
+environment, or that the registry does not have trusted publishing enabled, in which case
+publish retries once without a token for a registry that needs none (`AUTH_MODE=none`).
+
+## Declaring an application
+
+`appshell app apply` reconciles an application against a declared resource, creating
+it when absent. It is the declarative counterpart to `app create` plus `publish
+--application`, and the same file works against any registry via `--registry`.
+
+**appshell.app.yaml**
+
+```yaml
+apiVersion: registry.appshell.org/v1
+kind: Application
+name: storefront
+spec:
+  shell:
+    root: ContainerModule/Container
+    title: Storefront
+  packages:
+    - acme/checkout@1.5.0
+    - acme/cart@2.0.1
+```
+
+```bash
+appshell app apply -f appshell.app.yaml
+```
+
+`spec.packages` is the **full desired set** — anything activated but absent from it is
+deactivated, and the command prints what moved:
+
+```
+Updated acme/storefront
+  activated acme/cart@2.0.1
+  deactivated acme/search
+```
+
+Omit `spec.packages` entirely and package state is left alone, which is what you want
+locally where the webpack plugin already publishes and activates on every build.
+`${VAR}` placeholders expand from the environment exactly as they do in
+`appshell.config.yaml`.
+
+## Inspecting an application
+
+```bash
+appshell app list                     # every application in the scope
+appshell app get storefront           # packages, revision, visibility
+appshell app composition storefront   # the resolved payload the shell receives
+appshell app revisions storefront     # revision history
+appshell app rollback storefront --to 3
+appshell app open storefront          # print the shell url
+```
+
+Every mutation produces a revision, so `revisions` is the audit trail and `rollback`
+is how you undo one.
+
+```bash
+appshell app create storefront        # imperative equivalent of a bare apply
+appshell app delete storefront
+appshell app deactivate acme/checkout
+appshell app clone --from prod --to my-sandbox
+appshell app sync --from prod --to staging --include packages
+```
+
+## Developing against a deployed application
 
-Generates the appshell global runtime manifest.
+`appshell dev` opens an **overlay**: a per-developer, per-browser redirect that points
+some of an application's remotes at your machine. It is resolved per request, expires
+on its own, and never reaches the application's composition or its revision history.
 
 ```bash
-appshell generate manifest
+appshell dev --port 3002          # redirect this package's remotes at localhost:3002
+appshell dev status               # what is open on the application
+appshell dev stop --package       # stop redirecting just this package
+appshell dev stop <id>            # close one, or --all
+```
 
-Generate the appshell global runtime manifest
+An overlay can only redirect remote keys the application already publishes — adding
+one outright would be a way to run code the application was never composed with. For a
+new package, publish and activate it first, or work in a clone.
 
-Options:
-      --help        Show help                                           [boolean]
-      --version     Show version number                                 [boolean]
-  -t, --template  Path to the appshell config template to process     [string] [default: "appshell.template.json"]
-  -o, --outDir      Output location for the appshell manifest           [string] [default: "dist"]
-  -f, --outFile     Output filename for the appshell manifest           [string] [default: "appshell.manifest.json"]
+`--shell dev` additionally serves the development shell build, which is what supports
+hot reloading remotes in place.
+
+## Analyzing shared dependencies
+
+```bash
+appshell outdated
 ```
 
-### Sample usage
+Compares this package's dependencies against the shared-dependency baselines the
+application declares, and reports conflicts, missing entries and matches.
+
+## Generate manifest
+
+Processes a template into an appshell manifest. `appshell publish` does this for you;
+run it directly when you want the manifest as a build artifact.
 
 ```bash
 appshell generate manifest --template dist/appshell.template.json
 ```
 
-**Where does the content of APPSHELL_REGISTRY come from?**
+| Option | Default | Purpose |
+| ------ | ------- | ------- |
+| `-t, --template` | `appshell.template.json` | Template to process |
+| `-o, --outDir` | `dist` | Output location |
+| `-f, --outFile` | `appshell.manifest.json` | Output filename |
 
-> Each micro-frontend configured to use [@appshell/webpack-plugin](https://www.npmjs.com/package/@appshell/webpack-plugin) emits a manifest template, which is subsequently used to generate a manifest for the remote module. This manifest is then registered with the APPSHELL_REGISTRY.
+**Where does the template come from?**
+
+> Each micro-frontend configured with
+> [@appshell/webpack-plugin](https://www.npmjs.com/package/@appshell/webpack-plugin)
+> emits `appshell.template.json` at build time. `appshell publish` turns that into a
+> manifest and publishes it as a package version.
 
 Sample config template `appshell.template.json`:
 
@@ -121,7 +310,7 @@ Sample config template `appshell.template.json`:
       }
     }
   },
-  "environment": {
+  "vars": {
     "RUNTIME_ARG_1": "${RUNTIME_ARG_1}",
     "RUNTIME_ARG_2": "${RUNTIME_ARG_2}"
   }
@@ -132,7 +321,7 @@ Sample config template `appshell.template.json`:
 
 > Note the variable expansion syntax `${CRA_MFE_URL}`. When `appshell generate manifest` is called the actual runtime environment values are injected in order to produce the remote module's appshell manifest.
 
-> **Note** the `environment` section defines runtime environment variables that are injected into the global namesapce `window.__appshell_env__[module_name]` when an Appshell component is loaded. See the examples for a use case.
+> **Note** the `vars` section defines runtime configuration values a package reads with `getVars()` from [`@appshell/runtime/vars`](../runtime/README.md) once it is loaded. The package must share `@appshell/runtime` as a singleton to receive them. See the examples for a use case.
 
 Sample appshell manifest produced by the `appshell generate manifest` function:
 
@@ -215,7 +404,7 @@ Sample appshell manifest produced by the `appshell generate manifest` function:
       }
     }
   },
-  "environment": {
+  "vars": {
     "CraModule": {
       "RUNTIME_ARG_1": "Foo",
       "RUNTIME_ARG_2": "Biz"
@@ -227,76 +416,5 @@ Sample appshell manifest produced by the `appshell generate manifest` function:
 }
 ```
 
-This appshell manifest is registered with `APPSHELL_REGISTRY` and subsequently consumed by the Appshell host.
-
-## Register a manifest
-
-Register one or more appshell manifests with the global registry.
-
-```bash
-appshell register
-
-Register one or more appshell manifests
-
-Options:
-      --help      Show help                                            [boolean]
-      --version   Show version number                                  [boolean]
-  -m, --manifest  One or more manifests to register                      [array]
-  -r, --registry  Registry path for the appshell manifests
-                                         [string] [default: "appshell_registry"]
-```
-
-## Generate runtime env
-
-Generates a runtime env js file that can be consumed by the application at runtime.
-
-```bash
-appshell generate env
-
-Generate the runtime environment js file that reflects the current process.env
-
-Options:
-      --help     Show help                                                  [boolean]
-      --version  Show version number                                        [boolean]
-  -o, --outDir   Output location for the appshell environment js             [string] [default: "."]
-  -f, --outFile  Output filename for the appshell environment js             [string] [default: "appshell.env.js"]
-  -p, --prefix   Only capture environment variables that start with prefix or regex [string] [default: ""]
-  -g, --globalName     Global variable name window[globalName] used in the output js    [string] [default: "__appshell_env__"]
-```
-
-### Sample usage
-
-```bash
-appshell generate env --prefix APPSHELL_ --outDir dist
-```
-
-Sample output `appshell.env.js`
-
-```js
-window.__appshell_env__ = {
-  APPSHELL_VAR_1 = 'val 1',
-  APPSHELL_VAR_2 = 'val 2'
-};
-```
-
-### Using regex to match prefix
-
-```bash
-appshell generate env --prefix '^(APPSHELL_|FOO_).*' --outDir dist
-```
-
-Sample output `appshell.env.js`
-
-```js
-window.__appshell_env__ = {
-  APPSHELL_VAR_1 = 'val 1',
-  APPSHELL_VAR_2 = 'val 2',
-  FOO_VAR = 'some value'
-};
-```
-
-Include in the public html
-
-```html
-<script src="appshell.env.js"></script>
-```
+`appshell publish` sends this manifest to the registry as a package version. The
+registry composes every activated package into the payload it serves to the shell.