@ossy/cli 1.16.10 → 1.17.3

package/README.md

@@ -18,95 +18,180 @@ ossy <command> --help
 
 For one-off use without installing, you can still run `npx @ossy/cli <command>`.
 
-## Commands
+## How the CLI is organized
 
-| Command | Description |
-|---------|-------------|
-| `init [dir]` | Scaffold a new Ossy app (default: current directory) |
-| `build` | Production build |
-| `publish` | Queue a container deployment via `@ossy/deployment-tools` (**temporary**; see below), then upload `resourceTemplates` and **site build artifacts** (S3 presign + CMS resource) when `workspaceId` is set |
-| `cms upload` | Upload resource templates only (same API as publish’s upload step) |
-| `cms validate` | Validate ossy config and resource templates |
+The contract for everything the platform can do is the **SDK action POJO** in [`@ossy/sdk`](../sdk) (`{ id, endpoint, method, payload }`). The CLI is one channel onto that catalog, organized in three layers:
 
-## App: build
+1. **Local utilities** — no API call, or per-machine state. `auth`, `workspace`, `app init`, `app build`, `app validate`.
+2. **Action dispatcher** — `call <action.id>` invokes any action in the SDK catalog. New endpoints added to the SDK are callable from the terminal with no extra CLI wiring.
+3. **High-level workflows** — verbs that wrap one or more actions and add value the dispatcher doesn't (reading `src/config.js`, formatting output for CI, multi-step pipelines). Each workflow's docs name the underlying action(s) so you can drop down to `ossy call` if you outgrow the verb.
+
+| Layer | Command | Description |
+|-------|---------|-------------|
+| Local | `auth login \| logout \| status` | Save / delete / inspect the Ossy API token under `~/.config/ossy/credentials.json` |
+| Local | `workspace use <id> \| list \| current` | Manage the active workspace (saved to `~/.config/ossy/config.json`) |
+| Local | `app init [dir]` | Scaffold a new Ossy app (default: current directory) |
+| Local | `app build` | Production build of the app in the current directory |
+| Local | `app validate` | Validate `src/config.js` (`workspaceId`, `resourceTemplates`) without calling the API |
+| Dispatcher | `call <action.id>` | Invoke any Ossy SDK action by id (`ossy call --help` for the full catalog) |
+| Workflow | `app upload` | Read `resourceTemplates` from `src/config.js` and call `workspaces.import-resource-templates` |
+| Workflow | `app publish` | Upload resource templates and `build/` to the CMS (combines `app upload` + `upload-dir`) |
+| Workflow | `upload-dir <dir> <location>` | Recursively mirror a local directory into the CMS (mkdir + upload per file) |
+| Workflow | `registry ecr-push-credentials` | Call `registry.ecr-push-credentials`, format for `docker login` or GitHub Actions |
+
+If you need an endpoint that no verb wraps, reach for `ossy call` — it's the universal channel.
+
+## Auth and active workspace
+
+Once installed, the recommended flow is to log in once and pick an active workspace; subsequent commands inherit those:
 
 ```bash
-ossy build
+ossy auth login                      # paste your Ossy API token
+ossy workspace list                  # see workspaces you can access
+ossy workspace use <workspace-id>    # set the active one
+ossy auth status                     # confirm
 ```
 
-Options: e.g. `--config` for `src/config.js`. See `packages/app/README.md` for app build behavior.
+Credentials live in `~/.config/ossy/credentials.json` (`chmod 600`); the active workspace lives in `~/.config/ossy/config.json`. Both honor `XDG_CONFIG_HOME`.
 
-## Publish (container / website)
+Resolution order for every command that needs auth:
+1. `--authentication` / `-a` flag
+2. `OSSY_API_KEY` env var
+3. Saved credentials
 
-Publishes a site by sending a deployment request to your platform queue (same as `npx @ossy/deployment-tools deployment deploy`). Run from the **website package** directory (where `src/config.js` lives) so domain/platform can be read automatically.
+Resolution order for the workspace id (when a command isn't reading it from `src/config.js`):
+1. `--workspace-id` / `-w` flag
+2. `OSSY_WORKSPACE_ID` env var
+3. Saved active workspace
 
-### Temporary: no execution of `src/config.js` for CMS steps
+So existing CI scripts that set `OSSY_API_KEY` keep working unchanged; you only need `ossy auth login` for interactive use.
 
-After deploy succeeds, **`publish`** still needs **`workspaceId`**, **`apiUrl`** (optional, for absolute URLs), and **`resourceTemplates`** from `src/config.js`. Those values are **not** loaded with `import()` anymore: running the real config in plain Node would execute imports such as `@ossy/themes`, which are only meant to be resolved during **`ossy build`** (Rollup).
+## Generic dispatcher: `ossy call`
 
-Instead, the CLI uses a **temporary** pipeline:
+`ossy call` invokes any Ossy API action by id. The action catalog comes from `@ossy/sdk`, so any new endpoint added to the SDK is callable from the terminal with no extra wiring.
 
-- **`workspaceId`** and **`apiUrl`** — read with **string-literal regexes** (same idea as deploy hints).
-- **`resourceTemplates`** — parsed with **`@babel/parser`** from `export default { … }` when that array is **JSON-like literals only** (no function calls, variables, spreads, or template literals in that subtree).
+```bash
+# Discover what's available
+ossy call --help                                  # full catalog, grouped by domain
+ossy call resources.create --help                 # one action's method, endpoint, default payload
 
-If `resourceTemplates` cannot be extracted, template upload is skipped. This is a **stopgap** until publish is driven by build output or platform events (see **Future direction**).
+# Read calls
+ossy call workspaces.get-current
+ossy call resources.list --search 'location=/docs'
 
-### Future direction (planned)
+# Write calls — flag names map to payload keys (--first-name -> firstName)
+ossy call resources.create-directory --location /docs --name images
+ossy call workspaces.invite-user --email teammate@example.com
 
-The explicit **`deployment deploy`** step (SQS / deployment queue from **`@ossy/deployment-tools`**) is **intended to go away**: the platform should **react to a website upload / artifact event** (e.g. after the container image or site bundle is published) and roll out without the CLI calling deploy. When that exists, **`publish`** can shrink to CMS-only steps (resource templates + site artifacts), or those can move to separate workflows entirely. Treat the current **deploy + follow-ups** combo as **temporary** coupling.
+# Use --json for nested or non-string payloads
+ossy call resources.update-content --id res_abc --json '{"content":{"title":"Hi"}}'
 
----
+# Upload a file: --file fills name/type/size as defaults, then PUTs the bytes
+# when the response carries content.uploadUrl (works for resources.upload,
+# resources.upload-named-version, etc.)
+ossy call resources.upload --location /docs --file ./hero.jpg
+ossy call resources.upload-named-version --id res_abc --name medium --file ./hero.jpg
 
-### Authentication
+# Per-call overrides (otherwise resolved from `ossy auth login` / `ossy workspace use`)
+ossy call workspaces.get-all -a <jwt> --api-url http://localhost:3001/api/v0
+```
+
+Output is JSON pretty-printed to stdout on success. Errors go to stderr with a non-zero exit. Add `--raw` to get the response body verbatim (useful for piping non-JSON responses).
+
+`--file <path>` is a shortcut for upload-style actions: the CLI stats the file, fills `name`/`type`/`size` *as defaults* (any explicit `--name` / `--type` / `--size` flag wins), and after the dispatch it PUTs the bytes to `result.content.uploadUrl` with the right `Content-Type`/`Content-Length`. If the response doesn't include an upload URL, the bytes are skipped and a warning is printed.
+
+## App: build
+
+```bash
+ossy app build
+```
+
+Options: e.g. `--config` for `src/config.js`. See `packages/app/README.md` for app build behavior.
 
-**`publish`** requires **`--authentication` / `-a`** or **`OSSY_API_KEY`**: the **Ossy API JWT** (workspace API token). That same value is used for post-deploy CMS calls (resource templates, site artifacts).
+## App: publish
 
-Container deploys assume **Amazon ECR** in **`deployments.json`** (`registry` like `123456789012.dkr.ecr.eu-north-1.amazonaws.com`, **`image`** unchanged). The **worker** always pulls with **IAM** (`aws ecr get-login-password`); nothing in the queue carries a registry password. For **`docker push` from CI**, call **`POST /api/v0/registry/ecr/push-credentials`** with the same JWT and **`workspaceId`**, then **`docker login`** / **`docker push`**.
+Publishes a website: uploads resource templates to the CMS and mirrors the `build/` folder to a CMS location. Run from the **website package** directory (where `src/config.js` lives) so config values are read automatically.
 
 ```bash
 cd packages/my-website
-export OSSY_API_KEY=<ossy-api-jwt>   # or pass --authentication <ossy-api-jwt>
+npm run build                          # produce build/ first
+ossy app publish                       # reads src/config.js, uploads templates + build/
+```
+
+**This is a two-step workflow:**
+1. Upload resource templates → `POST /resource-templates` (same as `app upload`).
+2. Upload `build/` to the CMS → `resources.create-directory` + `resources.upload` per file (same as `upload-dir`), mirrored to `/sites/{domain}` by default.
+
+### Config extraction
+
+`publish` reads `workspaceId`, `apiUrl`, `domain`, and `resourceTemplates` from `src/config.js` **without executing** it (static regex + Babel AST parse), so imports like `@ossy/themes` that only resolve under Rollup are never run.
+
+If `resourceTemplates` cannot be extracted, the template upload step is skipped silently.
 
-ossy publish \
-  --platforms-path ../infrastructure/platforms.json \
-  --deployments-path "../infrastructure/deployments/**/*.json"
+### Authentication
+
+Requires `--authentication` / `-a` or `OSSY_API_KEY`: an Ossy API JWT (workspace API token).
+
+```bash
+cd packages/my-website
+export OSSY_API_KEY=<ossy-api-jwt>
+npm run build
+ossy app publish
+# or with explicit options:
+ossy app publish \
+  --config src/config.js \
+  --build-dir ./build \
+  --build-dest /sites/my-site.se
 ```
 
-**Non-ECR container registries** are not supported; container rows in **`deployments.json`** must use **ECR** and a **`registry`** endpoint as described above.
+### Options
 
-API and worker packages can use the same pattern: a minimal **`src/config.js`** with string-literal **`domain`** (and optional **`platform`**) matching **`deployments.json`**, then run **`publish`** from **`packages/api`** or **`packages/worker`** with **`--skip-resource-templates`** and **`--skip-site-artifacts`** (no website `workspaceId` / `build/` flow).
+| Flag | Description |
+|------|-------------|
+| `-a, --authentication` | Ossy API JWT (or `OSSY_API_KEY`, or `ossy auth login`) |
+| `-c, --config` | Path to `src/config.js` (default: `./src/config.js`) |
+| `--build-dir` | Override build directory (default: `<package>/build`) |
+| `--build-dest` | Override remote CMS location (default: `/sites/{domain}`) |
+| `--skip-resource-templates` | Skip the resource template upload step |
+| `--api-url` | API base URL (or `OSSY_API_URL`; relative `apiUrl` in config is ignored) |
 
-- **`--domain` / `--platform`** — Optional if `src/config.js` contains string literals `domain: '…'` and `platform: '…'` (or `targetDeploymentPlatform`).
-- **`--config`** — Path to another `config.js` if not `./src/config.js`.
-- If `platform` is omitted but `domain` is set (from flags or config), it is inferred from `deployments.json` when that domain appears under exactly one `targetDeploymentPlatform`.
-- **`--all`** — Runs `deployment deploy-all` for the platform; requires `--platform` or `platform` in config.
-- **Resource templates** — After a successful deploy, the CLI reads **`workspaceId`** / **`resourceTemplates`** from `./src/config.js` (or `--config`) using the **static extraction** described above (not `import()`). If **`workspaceId`** is set and **`resourceTemplates`** is a non-empty array, they are **POST**ed to **`{api}/resource-templates`** with the **`workspaceId`** header (same as the CMS). Skipped when **`--skip-resource-templates`** is set, or when `workspaceId` / `resourceTemplates` are missing or not extractable.
-- **Site artifacts** — Uses the same **static `workspaceId` / `apiUrl` extraction** as resource templates. If **`workspaceId`** is set and **`build/`** exists next to `src/` (i.e. run **`npm run build`** first), the CLI calls **`/site-artifacts/presign-batch`**, **PUT**s each file to S3, then **`/site-artifacts/commit-batch`** so a **`@ossy/platform/site-artifact-batch`** resource is created in the CMS. Skipped with **`--skip-site-artifacts`**, when there is no **`build/`**, or when **`workspaceId`** is missing. Override the build output directory with **`--site-artifacts-build-dir`** (absolute or cwd-relative).
-- **`--api-url`** — Optional API base for CMS calls (e.g. `https://api.ossy.se/api/v0`). Otherwise **`OSSY_API_URL`**, else an **absolute** `apiUrl` from config, else `https://api.ossy.se/api/v0`. Relative app `apiUrl` values (e.g. `/@ossy`) are ignored unless you pass **`--api-url`** or set **`OSSY_API_URL`**.
+### CI example
 
-Requires network access so `npx` can run `@ossy/deployment-tools`.
+```yaml
+- name: Publish
+  run: |
+    npm run build
+    npx --yes @ossy/cli app publish \
+      --authentication ${{ secrets.OSSY_API_KEY }}
+```
 
-## CMS: upload
+## App: upload
 
 Upload resource templates to your workspace so they can be used in the UI.
 
-Prefer **`--authentication` / `-a`** for the **Ossy API JWT** (same as **`publish`**); it matches **`OSSY_API_KEY`** in CI.
+Wraps the SDK action **`workspaces.import-resource-templates`** and adds: reading `resourceTemplates` and `workspaceId` from `src/config.js` (so you don't have to inline the templates JSON yourself). If you already have the templates as a JSON object, the equivalent dispatcher call is:
 
 ```bash
-ossy cms upload --authentication <ossy-api-jwt> --config src/config.js
+ossy call workspaces.import-resource-templates --json '{"templates":[…]}'
+```
+
+Prefer **`--authentication` / `-a`** for the **Ossy API JWT** (same as **`app publish`**); it matches **`OSSY_API_KEY`** in CI.
+
+```bash
+ossy app upload --authentication <ossy-api-jwt> --config src/config.js
 # optional: --api-url https://api.ossy.se/api/v0  (or set OSSY_API_URL)
 # In CI you may omit --authentication when OSSY_API_KEY is set
 ```
 
-When **`--config`** is omitted, **`./src/config.js`** is used if it exists (same as **`publish`**).
+When **`--config`** is omitted, **`./src/config.js`** is used if it exists (same as **`app publish`**).
 
 ### Config consistency
 
-- **App** (`build`), **CMS** (`cms upload` / `cms validate`), and **publish** all use **`--config`** (`-c`) for the app / workspace config file (`src/config.js` by default when present).
+- **App** (`build`), **app** (`app upload` / `app validate` / `app publish`), and **upload-dir** all use **`--config`** (`-c`) for the app / workspace config file (`src/config.js` by default when present).
 
 ### Workflow example
 
-Prefer **`publish`** so deploy and template upload run together (see **Publish** above). For template-only updates, `cms upload` still works.
+Prefer **`app publish`** so templates and build files are uploaded together. For template-only updates, `app upload` still works.
 
 ```yaml
 name: "[CMS] Upload resource templates"
@@ -125,17 +210,17 @@ jobs:
           node-version: "16"
       - name: Upload
         run: |
-          npx --yes @ossy/cli cms upload \
+          npx --yes @ossy/cli app upload \
             --authentication ${{ secrets.OSSY_API_KEY }} \
             --config src/config.js
 ```
 
-### cms validate
+### app validate
 
 Validate an ossy config file before uploading:
 
 ```bash
-ossy cms validate --config src/config.js
+ossy app validate --config src/config.js
 ```
 
 When **`--config`** is omitted, **`./src/config.js`** is used if it exists.
@@ -148,13 +233,70 @@ When **`--config`** is omitted, **`./src/config.js`** is used if it exists.
 | --config, -c | App config (`workspaceId`, `resourceTemplates`, …) | Optional if `./src/config.js` exists |
 | --api-url | API base URL for upload (`…/api/v0`) | No |
 
-## init
+## Upload a directory
+
+Recursively mirrors a local directory tree into the Ossy CMS, preserving the folder structure.
+
+```bash
+ossy upload-dir ./public /my-folder
+```
+
+This:
+1. Walks the local tree and collects all subdirectories (breadth-first) and files.
+2. Creates each remote directory with `resources.create-directory` (parents before children; already-existing directories are skipped silently).
+3. Uploads each file with `resources.upload` + S3 presigned PUT, in the same order they were discovered.
+4. Logs per-item progress and prints a summary at the end.
+
+Per-item errors are logged and skipped — the command continues to the next item and exits non-zero when any item failed.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Print what would happen without making any API calls |
+| `-a, --authentication` | Ossy API JWT (or `OSSY_API_KEY`, or `ossy auth login`) |
+| `-w, --workspace-id` | Workspace id (or `OSSY_WORKSPACE_ID`, or `ossy workspace use`) |
+| `--api-url` | Override the API base URL |
+
+**Examples:**
+
+```bash
+# Preview before committing
+ossy upload-dir ./public /my-folder --dry-run
+
+# Upload into a nested location
+ossy upload-dir ./assets /projects/2026/assets
+
+# Point at a local API
+ossy upload-dir ./public /my-folder --api-url http://localhost:3001/api/v0
+```
+
+## Registry: ecr-push-credentials
+
+Fetch a short-lived ECR password so CI can `docker login` and `docker push` to the workspace's ECR registry.
+
+Wraps the SDK action **`registry.ecr-push-credentials`** and adds: response validation, JSON pretty-printing, and a `--format github-actions` mode that writes `registry`/`username`/`password`/`expires_at` to `$GITHUB_OUTPUT` and emits `::add-mask::<password>` so the secret never appears in logs.
+
+```bash
+ossy registry ecr-push-credentials                      # JSON to stdout
+ossy registry ecr-push-credentials --format github-actions   # writes to $GITHUB_OUTPUT
+```
+
+Auth and workspace are resolved from the usual chain (`-a` flag → `OSSY_API_KEY` → saved credentials; `-w` flag → `OSSY_WORKSPACE_ID` → saved active workspace). The plain dispatcher equivalent is:
+
+```bash
+ossy call registry.ecr-push-credentials
+```
+
+…but you lose the GitHub Actions output formatting and the `::add-mask::` line, so prefer the verb in CI.
+
+## App: init
 
 Scaffold a new Ossy app:
 
 ```bash
-ossy init
-ossy init my-app
+ossy app init
+ossy app init my-app
 ```
 
 Creates `src/home.page.jsx`, `src/config.js`, and `package.json` (if missing).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/cli",
-  "version": "1.16.10",
+  "version": "1.17.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ossy-se/packages.git"
@@ -20,7 +20,8 @@
   },
   "dependencies": {
     "@babel/parser": "^7.28.6",
-    "@ossy/app": "^1.16.10",
+    "@ossy/app": "^1.17.3",
+    "@ossy/sdk": "^1.17.3",
     "arg": "^5.0.2",
     "glob": "^10.3.10"
   },
@@ -32,5 +33,5 @@
     "/src",
     "README.md"
   ],
-  "gitHead": "5821b2cea64c9ca0ece35d65a463006852abf167"
+  "gitHead": "f96e3c98e87f9a19b92f7eab0d54e4de12509007"
 }

package/src/{cms → app}/cli.js

@@ -1,12 +1,16 @@
 import { readFileSync, existsSync } from 'fs'
 import { pathToFileURL } from 'url'
 import arg from 'arg'
+import { build } from '@ossy/app'
 import { logInfo, logError } from '../log.js'
 import { resolveAppConfigPath } from '../resolve-app-config-path.js'
+import { getAuth } from '../state.js'
+import { init } from '../init/cli.js'
 import {
   postResourceTemplates,
   resolveApiBaseUrlForUpload,
 } from './upload-resource-templates.js'
+import { publish } from './publish.js'
 
 const resolveConfigImport = (filePath) =>
   filePath.endsWith('json')
@@ -22,14 +26,13 @@ const upload = (options) => {
     '--api-url': String,
   }, { argv: options })
 
-  const token =
-    parsedArgs['--authentication'] || process.env.OSSY_API_KEY
+  const token = getAuth({ flag: parsedArgs['--authentication'] })
   const apiUrlFlag = parsedArgs['--api-url']
 
   if (!token) {
     logError({
       message:
-        '[@ossy/cli] No token provided. Use --authentication / -a or set OSSY_API_KEY',
+        '[@ossy/cli] No token provided. Use --authentication / -a, set OSSY_API_KEY, or run `ossy auth login`.',
     })
     process.exit(1)
   }
@@ -150,19 +153,22 @@ const validate = (options) => {
 }
 
 const subcommands = {
+  init: (options) => init(options),
+  build: async (options) => { await build(options) },
   upload,
   validate,
+  publish: (options) => publish(options),
 }
 
-export const handler = ([subcommand, ...options]) => {
+export const handler = async ([subcommand, ...options]) => {
   if (!subcommand) {
-    logError({ message: '[@ossy/cli] cms: no subcommand. Use: ossy cms upload | validate' })
+    logError({ message: '[@ossy/cli] app: no subcommand. Use: ossy app init | build | upload | validate | publish' })
     process.exit(1)
   }
   const fn = subcommands[subcommand]
   if (!fn) {
-    logError({ message: `[@ossy/cli] cms: unknown subcommand "${subcommand}". Use: ossy cms upload | validate` })
+    logError({ message: `[@ossy/cli] app: unknown subcommand "${subcommand}". Use: ossy app init | build | upload | validate | publish` })
     process.exit(1)
   }
-  fn(options)
+  await fn(options)
 }

package/src/{publish/load-website-config.js → app/load-config.js}

@@ -1,7 +1,6 @@
 import { readFileSync } from 'fs'
 import { resolve } from 'path'
 import { parse } from '@babel/parser'
-import { pathToFileURL } from 'url'
 
 /** @returns {unknown | undefined} `undefined` if the AST cannot be reduced to JSON-like data */
 function astNodeToLiteralValue (node) {
@@ -58,7 +57,7 @@ function astNodeToLiteralValue (node) {
 
 /**
  * Reads `resourceTemplates` from `export default { ... }` when it is a literal array
- * (no imports, calls, or templates). Matches typical OSSY website configs.
+ * (no imports, calls, or templates). Matches typical Ossy website configs.
  *
  * @param {string} source
  * @returns {unknown[] | undefined}
@@ -98,16 +97,13 @@ function extractResourceTemplatesFromSource (source) {
 }
 
 /**
- * Reads fields needed for `ossy publish` follow-up steps **without executing** `config.js`.
- * Avoids resolving imports such as `@ossy/themes` in CI (publish runs after deploy, outside Rollup).
- *
- * **Temporary** — prefer a build-time `publish-meta.json` or platform events once deploy is decoupled
- * from the CLI; see `packages/cli/README.md` → *Publish* → *Temporary: no execution of src/config.js*.
+ * Reads fields from `src/config.js` **without executing** it.
+ * Avoids resolving imports such as `@ossy/themes` in CI.
  *
  * @param {string} configPath Absolute or cwd-relative path to `src/config.js`
- * @returns {{ workspaceId?: string, apiUrl?: string, resourceTemplates?: unknown[] }}
+ * @returns {{ workspaceId?: string, apiUrl?: string, domain?: string, resourceTemplates?: unknown[] }}
  */
-export function readPublishFieldsFromWebsiteConfig (configPath) {
+export function readAppConfig (configPath) {
   const abs = resolve(configPath)
   const source = readFileSync(abs, 'utf8')
 
@@ -126,17 +122,7 @@ export function readPublishFieldsFromWebsiteConfig (configPath) {
   return {
     workspaceId: pickString('workspaceId'),
     apiUrl: pickString('apiUrl'),
+    domain: pickString('domain'),
     resourceTemplates,
   }
 }
-
-/**
- * @deprecated Prefer {@link readPublishFieldsFromWebsiteConfig} for publish — dynamic import
- * runs all side effects and `import`s in config (e.g. `@ossy/themes`), which breaks in plain Node.
- * @param {string} configPath Absolute or cwd-relative path to config file
- */
-export async function loadWebsiteConfig (configPath) {
-  const abs = resolve(configPath)
-  const mod = await import(pathToFileURL(abs).href)
-  return mod.default ?? mod
-}