@groundfloorcloud/cli 0.1.0

package/README.md

@@ -0,0 +1,201 @@
+# `@groundfloorcloud/cli` (`gf`)
+
+A small, Vercel/`gh`-style CLI to log a developer into the Groundfloor
+Control Plane and reuse that session while building locally (in Cursor,
+scripts, or any app). It works like `vercel login`: run `gf login` once, the
+browser opens, you sign in, and the session is cached and auto-refreshed.
+
+The Control Plane never issues its own login tokens — it validates identity
+provider Bearer JWTs. So `gf` obtains tokens from Groundfloor's managed IdP
+(OAuth 2.0 Authorization Code + PKCE) and hands you a valid
+`Authorization: Bearer ...` token for CP and Coderunner APIs. Your Portal user
+is created just-in-time on the first call.
+
+## Install
+
+```bash
+npm i -g @groundfloorcloud/cli
+gf login
+```
+
+Or without a global install:
+
+```bash
+npx @groundfloorcloud/cli login
+```
+
+### From this monorepo
+
+```bash
+npm install
+npm run build --workspace=@groundfloorcloud/cli
+npm link --workspace=@groundfloorcloud/cli   # then: gf --help
+```
+
+## Quick start
+
+```bash
+gf login                  # browser sign-in, caches ~/.groundfloor/auth.json
+gf whoami                 # shows identity and verifies CP accepts the token
+gf workspaces             # list your workspaces
+gf workspaces use <uuid>  # set a default workspace
+gf coderunner ls          # list coderunners in the default workspace
+```
+
+Use the session from any local app or shell:
+
+```bash
+eval "$(gf env)"          # exports GROUNDFLOOR_TOKEN, CONTROLPLANE_URL, ...
+curl -H "Authorization: Bearer $(gf token)" \
+  "$CONTROLPLANE_URL/v1/workspaces" | jq .
+```
+
+In Cursor, run `gf login` once, then `gf token` / `gf env` whenever you (or an
+agent) need a fresh token to call CP APIs during development.
+
+## Deploying a coderunner (D-061)
+
+**Coderunner is the deploy path.** Do not create an App to run functions/jobs/services —
+`POST …/apps` with `app_kind=coderunner` is rejected. Use `gf deploy`, Control Plane
+`/coderunners` APIs, or the `@groundfloor/coderunner-mcp` MCP server.
+
+`gf deploy` packages your code and runs the full lifecycle: create the
+coderunner if it does not exist, upload a new version, wait for the build,
+deploy, **poll deployment until Completed**, and print IDs/URL.
+
+```bash
+# Deploy the current folder (zips the working tree, honoring .gitignore)
+gf deploy
+
+# Deploy a remote git/bitbucket repo (upload description includes git_sha=…)
+gf deploy --git https://github.com/me/my-fn.git --ref main
+
+# Override target + resources + env
+gf deploy --name my-fn --runtime python --cpu 250m --memory 256Mi \
+  -e API_KEY=secret -e STAGE=dev
+
+# Bind a newly created coderunner as a helper of an App (optional)
+gf deploy --app-id <app-uuid>
+```
+
+**Server push-to-deploy:** connect a repo on the coderunner **Git source** card
+(or `PUT …/coderunners/{id}/git-source`). Point GitHub/Gitea at
+`POST /v1/webhooks/git/{source_id}` with the returned webhook secret. Private
+repos use a workspace Secret named in `secret_key`. App creation is not required.
+
+How the target is chosen:
+
+- `--coderunner <id>` deploys into that exact coderunner.
+- Otherwise the name comes from `--name`, then `groundfloor.json`, then the
+  folder/repo name; its slug is matched against existing coderunners. A match is
+  reused; otherwise a new coderunner is created (optionally with `--app-id`).
+
+Runtime is auto-detected when not given (`package.json` -> node,
+`requirements.txt`/`pyproject.toml` -> python), defaulting to python.
+
+### Optional `groundfloor.json`
+
+Drop a `groundfloor.json` in your project root to set defaults (CLI flags still
+win):
+
+```json
+{
+  "name": "my-fn",
+  "runtime": "python",
+  "workloadType": "function",
+  "cpu": "250m",
+  "memory": "256Mi",
+  "env": { "STAGE": "dev" }
+}
+```
+
+### Useful flags
+
+| Flag | Description |
+|------|-------------|
+| `-w, --workspace <id>` | Workspace override (else the default from `gf workspaces use`). |
+| `-p, --path <dir>` | Local directory to package (default: cwd). |
+| `--git <url>` / `--ref <ref>` | Clone and deploy a remote repo at a branch/tag/commit. |
+| `--subdir <dir>` | Package a subdirectory of the source. |
+| `--runtime <r>` | `python` \| `node` \| `dotnet-script`. |
+| `--workload-type <t>` | `function` \| `service` \| `job` \| `schedule`. |
+| `--cpu` / `--memory` | Resource requests, e.g. `250m` / `256Mi`. |
+| `-e, --env KEY=VALUE` | Deployment env var (repeatable). |
+| `-m, --message <text>` | Version description. |
+| `--skip-deploy` | Upload a new version but do not deploy it. |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gf login [--device]` | Browser PKCE login (or device-code flow with `--device`). |
+| `gf logout` | Clear the cached session. |
+| `gf whoami` | Show identity and verify the CP session end-to-end. |
+| `gf token` | Print a fresh (auto-refreshed) access token to stdout. |
+| `gf env` | Print `export ...` lines for `eval "$(gf env)"`. |
+| `gf workspaces` (`ws`) | List workspaces; `gf workspaces use <id>` sets the default. |
+| `gf coderunner ls` (`cr ls`) | List coderunners in the default (or `--workspace`) workspace. |
+| `gf coderunner status -c <id\|slug>` | Status + current deployment JSON. |
+| `gf coderunner run -c <id\|slug> [--payload '{}']` | Smoke invoke a deployed function/job. |
+| `gf deploy` | Package code (local folder or `--git` repo) and deploy it as a coderunner. |
+
+### MCP (agents)
+
+See [`packages/coderunner-mcp/README.md`](../coderunner-mcp/README.md) and
+[`docs/plans/apps-and-coderunner.md`](../../docs/plans/apps-and-coderunner.md) Phase 1.
+
+## Configuration
+
+Settings resolve with precedence: command flags > environment > config file >
+built-in dev defaults.
+
+| Setting | Flag | Env | Default |
+|---------|------|-----|---------|
+| IdP issuer | `--issuer` | `GROUNDFLOOR_ISSUER` | `https://auth.dev.groundfloor.cloud/realms/groundfloor_dev` |
+| OIDC client id | `--client-id` | `GROUNDFLOOR_CLIENT_ID` | `groundfloor-cli` |
+| Control Plane URL | `--api-url` | `GROUNDFLOOR_API_URL` | `http://localhost:8088` |
+| Default workspace | (via `gf workspaces use`) | `GROUNDFLOOR_WORKSPACE_ID` | (none) |
+
+State is stored under `~/.groundfloor/`:
+
+- `auth.json` — cached tokens (chmod `600`).
+- `config.json` — non-secret defaults (issuer, client id, api url, workspace).
+
+`gf login --issuer ... --client-id ... --api-url ...` persists those values so
+later commands match the login.
+
+## Identity provider setup (one-time)
+
+`gf` needs a **public** OIDC client (default id `groundfloor-cli`) with:
+
+- Standard Flow enabled, PKCE method `S256`.
+- Valid redirect URIs covering the loopback callback. The CLI redirects to
+  `http://127.0.0.1:<port>/callback`, so configure **both**:
+  - `http://127.0.0.1/*`
+  - `http://localhost/*`
+- Optionally, OAuth 2.0 Device Authorization Grant enabled for `gf login --device`.
+
+Then add the client id to the Control Plane `KEYCLOAK_AUDIENCE`
+(see `.env.example`) so its tokens verify. The CLI user still needs workspace
+membership in the Portal for workspace-scoped routes.
+
+### Redirect URI mismatch ("Invalid parameter: redirect_uri")
+
+This means the client's Valid Redirect URIs do not match the loopback URL the
+CLI sends. Options:
+
+- Ensure the client lists `http://127.0.0.1/*` (the CLI defaults to `127.0.0.1`).
+- If your IdP only matches `localhost`, run `gf login --redirect-host localhost`.
+- If wildcard/port matching is restrictive, pin an exact URI: register
+  `http://127.0.0.1:8976/callback` on the client and run
+  `gf login --redirect-port 8976`.
+
+## Scope
+
+- Phase 1: authenticated developer session (`gf login` + token reuse).
+- Phase 2: `gf deploy` for local folders and remote git/bitbucket repos. The CLI
+  packages the code into a ZIP and drives the Control Plane create -> upload ->
+  build -> deploy lifecycle (upstream Code Runner is ZIP-based).
+
+Server-side push-to-deploy (Control Plane pulling from git via webhooks) is a
+possible future enhancement and is not part of this CLI.