@gapi/gcli 1.8.246 → 1.8.248

package/AGENTS.md

@@ -92,6 +92,10 @@ This repo is documentation-driven. With every change:
 3. **Skills / AGENTS.md** - learned something non-obvious, or a workflow
    bit you? Update the owning skill (`.agents/skills/<name>/SKILL.md`) or
    this file in the same change.
+4. **User docs + What's new** - a change users can see or do also updates
+   gql-fission's public docs page (`gql-fission/src/docs/<slug>.md`) and adds a
+   line to `gql-fission/src/app/changelog/releases.ts`. Skill:
+   `user-docs-and-changelog` in gql-fission.
 
 Before working on an existing feature: `node scripts/changelog.mjs render
 --feature <slug>` + its feature doc. That is where "how to test" and "how

package/README-CLI.md

@@ -79,6 +79,9 @@ Commands:
   workflow:runs [options]                              List a workflow runs, newest first
   workflow:status [options]                            Show a run: its step events, error and output (--follow until it ends)
   workflow:cancel [options]                            Cancel a running run
+  workflow:trigger:add [options]                       Start runs from an HTTP URL (--http; the JSON body is the input) or a schedule (--cron). Needs Fission 1.26+ on the cluster
+  workflow:trigger:list [options]                      List a workflow HTTP and schedule triggers
+  workflow:trigger:remove [options]                    Remove a workflow trigger
   help [command]                                       display help for command
 
 --- Subcommand: login ---
@@ -1134,3 +1137,43 @@ Options:
   -n, --name <name>        Workflow name
   -r, --run <run>          Run name (see workflow:runs)
   -h, --help               display help for command
+
+--- Subcommand: workflow:trigger:add ---
+Usage: gcli workflow:trigger:add [options]
+
+Start runs from an HTTP URL (--http; the JSON body is the input) or a schedule (--cron). Needs Fission 1.26+ on the cluster
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  --http                   An HTTP trigger: <router>/<project>/workflows/<path>
+  --path <path>            HTTP path under /workflows/ (default: the workflow
+                           name)
+  --method <methods>       HTTP methods, comma separated (default POST)
+  --cron <schedule>        A schedule: "@every 1h", "0 9 * * 1-5", "@daily"
+                           (UTC)
+  -i, --input <json>       Schedule: the input of every run (default {})
+  --input-file <file>      Schedule: read the run input from a JSON file
+  -h, --help               display help for command
+
+--- Subcommand: workflow:trigger:list ---
+Usage: gcli workflow:trigger:list [options]
+
+List a workflow HTTP and schedule triggers
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -h, --help               display help for command
+
+--- Subcommand: workflow:trigger:remove ---
+Usage: gcli workflow:trigger:remove [options]
+
+Remove a workflow trigger
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -t, --trigger <trigger>  Trigger id, path or schedule (see
+                           workflow:trigger:list)
+  -h, --help               display help for command

package/README.md

@@ -211,6 +211,27 @@ Steps that remove capacity or release the load balancer's IP (going back to
 `singleNode: true`, `loadBalancer: false`) are skipped unless you pass
 `--yes`. Nodes and the load balancer are billed per started hour.
 
+#### Virtual clusters
+
+A virtual cluster has its own Kubernetes API and Fission but no servers: it
+runs in one namespace of the shared Lambforge cluster, or of one of your
+private clusters, and is ready in about two minutes. Everything else
+(environments, lambdas, `--clusterName`, `cluster:kubeconfig`,
+`cluster:teardown`) works the same as for a private cluster; scaling and
+load balancer commands don't apply.
+
+```bash
+gcli cluster:create --virtual --name dev                  # on the shared cluster
+gcli cluster:create --virtual --name stage --host prod    # on your private cluster "prod"
+```
+
+```yaml
+cluster:
+  name: dev
+  provider: vcluster
+  host: prod          # optional - omitted = the shared cluster
+```
+
 ### RabbitMQ Brokers
 
 A project may have several RabbitMQ brokers, each optionally scoped to one of its private clusters.
@@ -788,6 +809,24 @@ gcli workflow:validate -f order-flow.yaml
 gcli workflow:delete --name order-flow                        # also deletes its runs
 ```
 
+**Triggers** start runs without anyone calling `workflow:run` (Fission 1.26+
+on the workflow's cluster creates the run itself):
+
+```bash
+# An HTTP URL: every request starts a run, the JSON body is the run input,
+# the answer is 202 {"run": "..."}; default path = the workflow name, POST
+gcli workflow:trigger:add --name order-flow --http --path orders --method POST
+curl -X POST 'https://functions.lambforge.com/<projectId>/workflows/orders' -d '{"orderId": 42}'
+
+# A schedule (UTC) with a fixed run input
+gcli workflow:trigger:add --name nightly-report --cron "0 6 * * *" --input '{"scope": "all"}'
+
+gcli workflow:trigger:list --name order-flow
+gcli workflow:trigger:remove --name order-flow --trigger orders   # id, path or schedule
+```
+
+`workflow:runs` shows how each run started (`manual`, `http`, `schedule`).
+
 The file `workflow:get` / `workflow:generate` write (and `workflow:apply`
 reads) - a Fission `kind: Workflow` manifest or a bare `startAt` + `states`
 works too:

package/docs/changelog.d/2026-10-26-workflows-workflow-trigger-commands-for-http-and-schedule-triggers.md

@@ -0,0 +1,23 @@
+## 2026-10-26 - workflows: workflow:trigger commands for HTTP and schedule triggers
+
+**Feature:** workflows · **Type:** feat
+
+- `workflow:trigger:add` (`--http [--path] [--method]` or `--cron
+  "<schedule>" [-i | --input-file]`), `workflow:trigger:list`,
+  `workflow:trigger:remove -t <id | path | schedule | Fission name>`
+  (`src/commands/workflow/trigger-*.ts`), on the graphql-server-lambdas
+  `addWorkflowTrigger` / `removeWorkflowTrigger` (Fission 1.26+ fork
+  `workflow-triggers` creates the runs).
+- Option handling and output are pure (`triggers.ts`: `buildTriggerInput`,
+  `findTrigger`, `triggerRow`, `runSource`); `workflow:runs` gained a `by`
+  column (manual / http / schedule). `WorkflowFragment.triggers`,
+  `WorkflowRunFragment.triggerKind / triggerName`; client calls in
+  `gql-client.ts`.
+- README Workflows section + regenerated `README-CLI.md`.
+- **Test:** `npx jest --coverage=false test/workflow.spec.ts` (11 pass, 5 new).
+- **Debug:** `Workflow triggers need Fission 1.26 or newer on this cluster`
+  is the backend saying the cluster is too old; `Pass either --http or
+  --cron` is the option check.
+- **Verification:** gcli jest 114/114; tsc + eslint clean; the new
+  mutations and fragments validated against the local gateway schema;
+  not run against production (gcli login points at production).

package/docs/changelog.d/2026-10-27-virtual-clusters-cluster-create-virtual-and-provider-vcluster-in-cluster-appl.md

@@ -0,0 +1,18 @@
+## 2026-10-27 - virtual-clusters: cluster:create --virtual and provider vcluster in cluster:apply
+
+**Feature:** virtual-clusters · **Type:** feat
+
+- `cluster:create --virtual [--host <private-cluster-name>]` and, in the
+  `cluster:` section, `provider: vcluster` + `host:` (both read by
+  `cluster:create` and `cluster:apply`). The host is resolved by name
+  (`helpers/virtual-cluster.ts`); no host = the shared cluster.
+  `cluster:apply` only creates a virtual cluster - nothing else to reconcile;
+  `validateDesired` rejects node settings on it and `host` without it.
+- `GraphqlClienAPI.provisionProjectVirtualCluster` selects `routerUrl` and
+  `hostNamespace` itself (not in `ClusterFragment`, so older servers keep
+  working). Canonical doc: `graphql-server-functions/docs/features/virtual-clusters.md`.
+- **Test:** `npx jest --coverage=false test/cluster-apply`.
+- **Debug:** `No cluster named "<host>"` = the host name is not a live
+  cluster of the project (`gcli cluster:list`).
+- **Verification:** jest 118/118 (4 new), tsc + eslint clean. README-CLI.md
+  not regenerated (needs a build of release/index.js).

package/docs/features/README.md

@@ -36,3 +36,4 @@ Outline (drop sections that don't apply):
 | `dedicated-platform-cluster` | [dedicated-platform-cluster.md](dedicated-platform-cluster.md) | `cluster:status/health/scale/autoscale/...` commands; canonical doc in lambforge-agent |
 | `ci-token-scopes` | [ci-token-scopes.md](ci-token-scopes.md) | Which permission each command needs; `mq-trigger:*` commands; canonical doc in graphql-server |
 | `workflows` | [workflows.md](workflows.md) | `workflow:*` commands incl. AI drafts (`workflow:generate`); canonical doc in graphql-server-lambdas |
+| `virtual-clusters` | [virtual-clusters.md](virtual-clusters.md) | cluster:create --virtual, provider: vcluster (slice; canonical in graphql-server-functions) |

package/docs/features/virtual-clusters.md

@@ -0,0 +1,12 @@
+# Virtual clusters (slice)
+
+**Status:** built and tested end to end on minikube 2026-10-28, not deployed. Feature slug `virtual-clusters`.
+Canonical doc (how it works, test, debug, limits):
+[`graphql-server-functions/docs/features/virtual-clusters.md`](../../../../../graphql-server-functions/docs/features/virtual-clusters.md).
+
+Virtual clusters are vClusters (own Kubernetes API + Fission) on the shared
+cluster or one of the project's private clusters, `provider: 'vcluster'`.
+
+## This repo
+
+`gcli cluster:create --virtual [--host <private-cluster>]`; in `lambforge.yaml`: `cluster: { name: dev, provider: vcluster, host: prod }` for `cluster:create` / `cluster:apply` (no host = shared cluster; node settings are rejected). Code: `src/commands/cluster/helpers/virtual-cluster.ts`, `helpers/plan.ts`. Test: `npx jest --coverage=false test/cluster-apply`.

package/docs/features/workflows.md

@@ -17,9 +17,19 @@ the id with `listWorkflows`):
 | `workflow:validate -f file` | `validateWorkflow` (graph + lambdas on the cluster) |
 | `workflow:delete -n` | `deleteWorkflow` (runs too) |
 | `workflow:run -n [-i json \| --input-file] [--wait]` | `startWorkflowRun`; `--wait` polls `getWorkflowRun` every 2 s and prints each new event until the run is terminal |
-| `workflow:runs -n [-l]` | `listWorkflowRuns` |
+| `workflow:runs -n [-l]` | `listWorkflowRuns` (column `by`: manual / http / schedule, from `triggerKind`) |
 | `workflow:status -n -r run [--follow]` | `getWorkflowRun` (events, error, output) |
 | `workflow:cancel -n -r run` | `cancelWorkflowRun` |
+| `workflow:trigger:add -n (--http [--path] [--method a,b] \| --cron "<schedule>" [-i json \| --input-file])` | `addWorkflowTrigger`; prints the trigger and, for HTTP, a `curl` line |
+| `workflow:trigger:list -n` | the workflow's `triggers` (id, kind, URL or schedule, input) |
+| `workflow:trigger:remove -n -t <id \| path \| schedule \| Fission name>` | `removeWorkflowTrigger` |
+
+Triggers (2026-10-26) are HTTP URLs (`<router>/<projectId>/workflows/<path>`,
+the JSON body is the run input, 202 `{run}`) and schedules (cron, UTC, with a
+fixed input) that start runs. Fission 1.26+ (fork `workflow-triggers`) on the
+workflow's cluster creates the run. The option handling is pure and tested:
+`src/commands/workflow/triggers.ts` (`buildTriggerInput`, `findTrigger`,
+`triggerRow`, `runSource`).
 
 The workflow file (`definition.ts` `parseWorkflowFile`) accepts
 `workflow: {name, description, clusterId, definition}`, the same without the
@@ -37,7 +47,9 @@ USER-only in graphql-server-lambdas, so these commands need `gcli login`.
 `npx jest --coverage=false test/workflow.spec.ts`. Real: log in to a
 gateway whose project has `allowWorkflows`, then
 `gcli workflow:generate -d "..." -n demo --apply` and
-`gcli workflow:run -n demo --wait`.
+`gcli workflow:run -n demo --wait`; triggers:
+`gcli workflow:trigger:add -n demo --http`, then `curl -X POST <url> -d '{}'`
+and `gcli workflow:runs -n demo` shows the run `by` http.
 
 ## How to debug
 
@@ -47,3 +59,6 @@ gateway whose project has `allowWorkflows`, then
   `allowWorkflows`.
 - `Workflows are not enabled on this cluster`: the cluster runs Fission
   without `workflows.enabled` (canonical doc, Requires).
+- `Workflow triggers need Fission 1.26 or newer on this cluster`: the
+  cluster's Fission CRDs predate workflow triggers.
+- `Pass either --http or --cron`: exactly one of them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.246",
+  "version": "1.8.248",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"