sitevision-cli 1.0.0-beta.2 → 1.0.0-beta.21

package/readme.md

@@ -1,158 +1,139 @@
 # Sitevision CLI
 
-This CLI was largely built on the back of the [sitevision-scripts](https://github.com/sitevision/sitevision-scripts) project.
-However, these scripts have some limitations:
-
-- Clunky for use with environments requiring signed packages
-- Clunkly management of credentials and unsecure handling of credentials
-- No type safety
-
-## Features
-
-- **Interactive Menu** - Full-screen TUI with arrow key navigation
-- **Project Detection** - Automatically detects Sitevision projects
-- **Two Modes** - Interactive menu OR direct command execution
-- **Automatic Setup** - Guided setup for dev properties and signing credentials
-- **Secure Credentials** - Passwords live in the OS keychain (macOS Keychain / Windows Credential Manager / Linux libsecret), never on disk
+`svc` builds, signs and deploys Sitevision apps (WebApp, Widget, RESTApp,
+MCPServer) from a full-screen terminal shell or as plain commands.
+
+- **One shell for one app or a whole repo.** Run it inside an app, or at the
+  root of a repo with many apps and switch between them. Dev and watch keep
+  running in the background.
+- **Three ways to authenticate deploys:** username and password, OAuth2 (PKCE,
+  works with SSO), or a captured browser session for SAML-only sites.
+- **No secrets on disk.** Passwords, tokens and cookies live in the OS keychain.
+- **Environments.** dev, test and prod in one config; production deploys use
+  the signed zip, confirm and activate.
+- **Shared config in git.** Site and auth settings for the whole team live in
+  `package.json`, once at the repo root; your username stays in a local
+  `.dev_properties.json`. Compatible with plain sitevision-scripts.
+- **Builds the way Sitevision does.** Bundled apps without their own webpack
+  config are built by `@sitevision/sitevision-scripts`.
+- English and Swedish UI.
+
+📖 **[User guide](docs/user-guide.md)** · **[Användarguide (svenska)](docs/anvandarguide.md)**
 
 ## Install
 
+Requires Node.js 22+.
+
 ```bash
 npm install --global sitevision-cli
 ```
 
-## Usage
-
-The CLI must be run inside a Sitevision project directory (containing a `manifest.json`).
-
-### Interactive Mode
-
-Simply run `svc` to launch the interactive menu:
+## Quick start
 
 ```bash
+cd my-repo          # or cd into a single app
 svc
 ```
 
-On first run (or if setup is incomplete), the CLI will:
-
-1. Check if `node_modules` exists and offer to run `npm install` if missing
-2. Check if dev properties are configured and offer to set them up if missing
-3. Check if you have setup signing credentials and offer to do so if missing
-4. Display project information
-5. Show the main menu
-
-Use arrow keys to navigate and Enter to select:
-
-- **Dev** - Start development server with watch mode
-- **Dev (Signed)** - Development with automatic signing before each deploy
-- **Build** - Build a dist bundle
-- **Sign** - Sign built dist bundle
-- **Deploy** - Deploy to configured development environment
-- **Deploy (Force)** - Force deploy (overwrite existing)
-- **Deploy Production** - Deploy signed app to configured production environment
-- **Info** - Show project info
-- **Exit**
-
-### Direct Commands
-
-You can also run commands directly:
-
-#### Development
-
-```bash
-# Start development server with watch mode
-svc dev
-
-# Start development server with automatic signing
-svc dev --signed
-```
-
-#### Building
+1. Pick an app in the navigator and press `Enter`. (In a new repo the shell
+   opens on **Workspace settings** first.)
+2. Press `2` for the **Config** tab and fill in domain, site name, addon name,
+   username and auth method. Each field saves on `Enter`.
+3. Press `i` to install dependencies if needed, then `d` to start dev: build on
+   every change and deploy. Output is in the **Log** tab (`4`).
+
+For production: switch environment with `E`, press `b` to build, `s` to sign
+and `p` to deploy and activate.
+
+## The shell
+
+| Key             | Action                                              |
+| --------------- | --------------------------------------------------- |
+| `d` / `w`       | Dev (build + deploy on change) / Watch (build only) |
+| `b` / `s`       | Build / Sign                                        |
+| `p` / `P`       | Deploy / force deploy to the active environment     |
+| `a`             | Versions: list and activate uploaded versions       |
+| `E`             | Switch environment                                  |
+| `e` / `y` / `i` | Config tab / sync `package.json` / `npm install`    |
+| `l`             | Log in again                                        |
+| `K`             | Stop running tasks                                  |
+| `1`–`4`         | Overview · Config · Versions · Log                  |
+| `/`             | Command palette                                     |
+| `,`             | Settings (language, intro animation)                |
+| `Tab` / `Esc`   | Switch pane / back                                  |
+| `q`             | Quit                                                |
+
+In the navigator, typing filters the app list; action keys work once `Enter` or
+`Tab` has moved focus to the content pane. The bottom bar always shows the keys
+that apply. `svc --minimal` gives a compact layout for small panes.
+
+## Commands
 
 ```bash
-# Build the application for production
-svc build
+svc                                   # interactive shell
+svc build                             # build to dist/<id>.zip
+svc sign                              # sign to dist/<id>-signed.zip
+svc deploy [--force]                  # deploy the zip
+svc deploy --production [--activate]  # deploy the signed zip
+svc dev [--signed]                    # build + deploy on change
+svc watch [--signed]                  # build on change, no deploy
+svc info                              # project information
 ```
 
-#### Signing
-
-```bash
-# Sign the app for production deployment
-svc sign
-```
-
-#### Deployment
-
-```bash
-# Deploy to development server
-svc deploy
-
-# Force deploy (overwrite existing)
-svc deploy --force
-
-# Deploy to production (requires signed app)
-svc deploy --production
-```
-
-#### Setup
-
-```bash
-# Configure signing credentials
-svc setup-signing
-```
-
-#### Project Info
-
-```bash
-# Show project information and configuration
-svc info
-```
+Direct commands use the base environment. `--token` and `--cookie` pass an
+OAuth2 token or session cookie for one run.
 
 ## Configuration
 
-### Development Properties (`.dev_properties.json`)
-
-Create this file in your project root for deployment configuration:
+`.dev_properties.json` is your local config and the main source; keep it out of
+git. Shared values are committed in `package.json` and act as defaults
+underneath it:
 
 ```json
 {
-	"domain": "your-site.sitevision.se",
-	"siteName": "YourSite",
-	"addonName": "your-addon",
-	"username": "your-email@example.com",
-	"useHTTPForDevDeploy": false,
-	"signingUsername": "your-developer-account@example.com",
-	"certificateName": "optional-certificate-name"
+	"developmentDomain": "acme-use.sitevision-cloud.se",
+	"siteName": "Intranet",
+	"addonName": "my-addon",
+	"svc": {
+		"authMethod": "oauth2",
+		"environments": {"prod": {"domain": "acme.sitevision-cloud.se"}}
+	}
 }
 ```
 
-### Password storage
+`username`, `signingUsername` and `certificateName` are user-specific and only
+live in `.dev_properties.json`. `y` copies shared values from
+`.dev_properties.json` into `package.json`. In a workspace, shared values go in
+the root `package.json` and each app's `package.json` only needs `addonName`.
+
+## Authentication in short
 
-Passwords are stored in the OS-native secret store (macOS Keychain, Windows
-Credential Manager, Linux libsecret) under the `sitevision-cli` service —
-never in `.dev_properties.json`. Run `svc` and complete the setup form (or
-enter the password when prompted at deploy/sign time and toggle "save to
-keychain") to populate it.
+There are two separate credentials:
 
-If an existing `.dev_properties.json` contains a plaintext `password` field,
-the CLI offers to migrate it to the keychain on next launch and strip the
-field from the file. The migration prompt only appears in interactive mode
-(plain `svc`) — if you only ever invoke commands directly (`svc deploy`,
-`svc dev`), run `svc` once to migrate.
+- **Deploy**: your account on the site. `authMethod` is `basic` (password),
+  `oauth2` (browser login against the site's OAuth2 provider, refreshed
+  silently afterwards) or `cookie` (log in with SSO in a Chrome window, the
+  session is captured).
+- **Signing**: your developer.sitevision.se account, always username and
+  password.
 
-For CI / headless use, set `SITEVISION_DEPLOY_PASSWORD` and/or
-`SITEVISION_SIGNING_PASSWORD` — these take precedence over the keychain and
-are never written anywhere.
+Everything secret goes in the OS keychain under `sitevision-cli`. For CI, set
+`SITEVISION_DEPLOY_PASSWORD`, `SITEVISION_SIGNING_PASSWORD`,
+`SITEVISION_ACCESS_TOKEN` or `SITEVISION_SESSION_COOKIE`.
 
-### Signing Credentials
+OAuth2 needs a client registered on the site with the redirect URI
+`http://127.0.0.1:8137/callback`. The [user guide](docs/user-guide.md#5-authentication)
+covers the setup, the pitfalls, and which method works with which command.
 
-Signing credentials are used to sign apps via developer.sitevision.se:
+## Development
 
-- `signingUsername` - Your developer.sitevision.se account
-- `certificateName` - Optional, if you have multiple certificates
+```bash
+npm install
+npm run build   # tsc → dist/
+npm test        # prettier, xo, ava
+```
 
-The signing password is prompted on first use, with an option to save it to
-the OS keychain for future runs.
+Releasing: see [RELEASING.md](RELEASING.md).
 
 ## License