@gapi/gcli 1.8.237 → 1.8.238

package/.agents/skills/changelog/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: changelog
+description: Record every code change as a feature-keyed changelog fragment in docs/changelog.d/ (node scripts/changelog.mjs new) and keep the feature's living doc in docs/features/ current. Use after ANY change to source, schema, config or behavior, and whenever you need the history of a feature to debug or extend it (node scripts/changelog.mjs render --feature <f>). Never edit docs/CHANGELOG.md directly.
+---
+
+# Feature changelog discipline
+
+Two artifacts per feature, kept in the SAME commit as the change:
+
+| Artifact | Holds | Edited how |
+|---|---|---|
+| `docs/features/<feature>.md` | Current state: what it does, architecture, files, config, how to test, how to debug, known limits | Updated in place - it must always describe what is true NOW |
+| `docs/changelog.d/YYYY-MM-DD-<feature>-<slug>.md` | One change: what changed, how to test it, where to look when it breaks, what was verified | New file per change, never edited after merge |
+
+`docs/CHANGELOG.md` is the archive - only `node scripts/changelog.mjs compact`
+writes it (on the default branch, in its own commit).
+
+## Workflow
+
+```bash
+node scripts/changelog.mjs features                         # existing feature slugs - reuse one
+node scripts/changelog.mjs new local-ai-runners "model visibility per runner" --type feat
+$EDITOR docs/changelog.d/2026-10-11-local-ai-runners-model-visibility-per-runner.md
+$EDITOR docs/features/local-ai-runners.md             # bring the living doc up to date
+node scripts/changelog.mjs check                            # must print OK
+git add docs/ <changed files> && git commit
+```
+
+Starting work on an existing feature? Read its history first:
+
+```bash
+node scripts/changelog.mjs render --feature local-ai-runners
+```
+
+## Rules
+
+- **Feature slug**: kebab-case, shared across the Lambforge repos
+  (gql-fission, graphql-server, graphql-server-lambdas,
+  graphql-server-functions, gcli) - a cross-repo feature uses the same slug
+  in every repo it touches, and each repo's fragment mentions the others.
+  `repo` is for changes owned by no feature (setup, tooling, deps).
+- **New feature** = new `docs/features/<feature>.md` (outline in
+  `docs/features/README.md`) + a row in that README's index. `check` fails
+  without the doc.
+- **Every entry has Test, Debug and Verification lines.** Test = how anyone
+  can re-test it later. Debug = where to look when it breaks (log prefixes,
+  collections, flags, failure modes). Verification = what YOU ran and saw.
+- Say what is now true, not what you did ("runners heartbeat every 30s",
+  not "edited connection.ts").
+- One entry per logical change; several changes in a day = several files.
+- Add `**Commit:** <hash>` when writing an entry after the fact.
+- Not needed for: typo-only doc edits, scratch work, release/version bumps.
+
+## Compaction
+
+When `docs/changelog.d/` grows past ~20 files, on the default branch:
+`node scripts/changelog.mjs compact` then
+`git commit -m "docs(changelog): compact N entries"`. Never urgent;
+`render --feature` reads fragments and archive alike.

package/.agents/skills/cluster-targeting/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: cluster-targeting
+description: Add or extend a gcli command that touches a project resource which can live on a private cluster (lambda, environment, logs, load-spec). Use when adding a new --clusterId/--clusterName flag, or when a command's resource lookup needs to disambiguate between the shared cluster and a private one.
+---
+
+# gcli: targeting the right cluster
+
+Lambforge projects can have private Talos/Hetzner clusters in addition to
+the implicit shared one (full backend architecture:
+`graphql-server-lambdas/docs/multi-cluster.md`). Every gcli command that
+creates, reads, updates, or deletes a cluster-scoped resource (lambdas,
+environments, logs, `load-spec.ts` manifests) needs to resolve which
+cluster it's targeting instead of assuming the shared one.
+
+## `resolveClusterId` — the one helper every command should use
+
+`src/helpers.ts`:
+
+```ts
+export function resolveClusterId(
+  projectId: string,
+  hint: { clusterId?: string | null; clusterName?: string | null },
+): Observable<string | undefined>
+```
+
+- `clusterId` wins when present (checked via `!= null`, **not** truthiness —
+  an explicit empty string is a deliberate "shared cluster only" signal on
+  some commands like `lambda:list`, and truthiness would silently treat
+  that the same as "not provided," changing existing behavior).
+- Otherwise, if `clusterName` is given, looks it up via
+  `GraphqlClienAPI.projectClusters(projectId)` and resolves to that
+  cluster's id — or throws a descriptive error naming
+  `cluster:list --project <id>` as the way to see what's available.
+- Neither given → resolves `undefined` (the shared cluster).
+
+**Every command that accepts `--clusterId` should also accept
+`--clusterName`** (clusterName is unique per project, so `clusterName +
+projectId` is just as unambiguous as `clusterId` — and far more readable in
+a hand-authored YAML manifest than a raw ObjectId). `clusterId` always wins
+when both are passed. Confirmed call sites: `environment:{create,get,update,
+delete}`, `lambda:{get,list,delete}`, `lambda:logs`/`logs:builder`,
+`lambda/helpers/load-spec.ts` (so a `load-spec.yaml` manifest can reference
+a cluster **by name**, keeping the file human-readable instead of full of
+raw ObjectIds — see that file for the exact YAML shape).
+
+## Adding a new cluster-scoped command/flag
+
+1. Add `--clusterId <id>` AND `--clusterName <name>` flags to the command.
+2. Call `resolveClusterId(projectId, { clusterId, clusterName })` before the
+   actual GraphQL call, and pass the resolved id through.
+3. If the underlying GraphQL resolver doesn't yet accept a `clusterId` hint
+   for this operation, that's a backend gap — see
+   graphql-server-lambdas' `multi-cluster-scoping` skill before assuming the
+   frontend-side fix alone is sufficient.
+
+## GraphQL layer specifics (different from gql-fission)
+
+gcli builds every GraphQL operation as an inline `gql` template string
+directly in `services/gql-client.ts` — there's no `.graphql` file + codegen
+pipeline like gql-fission's. Adding a field/operation here is a plain code
+edit to that file, not a "regenerate then hand-patch" dance. gcli keeps its
+own **separate, hand-maintained** copy of `@introspection/index.ts` — a
+type added on the backend still needs to be added here by hand; it is not
+shared with or generated from gql-fission's copy.
+
+## Testing
+
+`jest.config.js` has no `moduleNameMapper` for the `~/` tsconfig path alias
+— new test files must use relative imports (e.g. `'../src/helpers'`), not
+`'~/helpers'`, or the test silently fails to resolve the module.

package/.agents/skills/gcli-command/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: gcli-command
+description: Add or change a gcli command (commander registration, lazy action modules, GraphqlClienAPI calls through the gateway, Logger output, tests, build/release, regenerating README-CLI.md). USE BEFORE adding a `gcli <area>:<verb>` command or a new API call in src/services/gql-client.ts.
+---
+
+# Adding a gcli command
+
+## Shape
+
+```
+src/commands/<area>/index.ts     registerXCommands(program): .command('<area>:<verb>')
+                                 .description(...).option(...)
+                                 .action(lazy(() => import('./<verb>').then(m => m.default)))
+src/commands/<area>/<verb>.ts    export default (cmd: { ...options }) => Promise<...>
+src/commands/index.ts            add registerXCommands to `commands`
+```
+
+- Actions are lazy-imported - keep heavy imports inside the action module.
+- Return a promise (`lastValueFrom(observable)` for rxjs flows); throw an
+  `Error` with an actionable message (`Run gcli login first`, `--id ...`).
+- Output via `Logger` (`src/services/log.ts`: log/info/warn/error/table).
+
+## API calls
+
+`GraphqlClienAPI.query<T>({ query: gql`...`, variables })` in
+`src/services/gql-client.ts`: POSTs to the `gcli login` URL with the stored
+Firebase token (auto-refreshed after 30 min) - i.e. through the federation
+gateway as the logged-in user. Selection sets are plain strings in
+`src/services/types/*.fragment.ts`. Response types: `@introspection/index`
+(regenerated with `npm run introspect` against a live gateway) or a local
+interface next to the command (as `commands/runner/types.ts`).
+
+Login state lives in `~/.graphql-server/` (`token`, `refresh`, `url`, `key`,
+`project`, ...; paths in `src/types.ts`). A command needing its own state
+adds a path there (the runner stores `runner.json`, mode 0600).
+
+Project/cluster-scoped commands: `parseProjectId(cmd.project)`,
+`resolveClusterId` in `src/helpers.ts`; see the `cluster-targeting` skill.
+
+## Tests, build, docs
+
+```bash
+npx jest --coverage=false            # test/*.spec.ts; jest maps ~/ @introspection/ @commands/
+npx tsc --noEmit -p .
+npx eslint --fix <files>
+npm run build                        # esbuild -> release/index.js (committed!)
+node release/index.js <area>:<verb> --help
+```
+
+- Mock the API in specs: `jest.mock('../src/services/gql-client', ...)`.
+- `release/index.js` is committed and rewritten by every build - don't
+  commit it from a feature branch unless releasing (`git checkout -- release/index.js`).
+- `README-CLI.md` is generated: `node release/index.js --all-help > README-CLI.md`
+  after a build. User-facing docs: a section in `README.md`.
+- Changelog fragment + feature doc (`changelog` skill).

package/.agents/skills/local-ai-runners/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: local-ai-runners
+description: Work on the gcli local AI runner (runner:start/list/models/delete) - the subscriptions-transport-ws client that bridges a user's Ollama to the Lambforge chat. USE when the runner won't connect, drops requests, or before changing src/commands/runner/**.
+---
+
+# gcli local AI runner
+
+Slice doc: `docs/features/local-ai-runners.md`. Canonical (protocol,
+security, symptom table): `graphql-server/docs/features/local-ai-runners.md`.
+
+## Invariants
+
+- Outbound only: one WebSocket to `/subscriptions`
+  (`connectionParams.runnerToken`); subscription + mutations share it.
+  Never connect to RabbitMQ or open a port.
+- `ALLOWED_REQUESTS` (`ollama.ts`) mirrors the backend's
+  `RUNNER_ALLOWED_PATHS` - only `POST /v1/chat/completions`. Change both or
+  neither.
+- Every response frame of a request gets the next `seq`; batches are sent
+  sequentially (`FrameSender`). The backend re-orders, but don't rely on it.
+- A request queued in Ollama sends `ping` every 30s, or the backend's 10-min
+  idle timeout kills it (spawned agent workers queue on one GPU).
+- Socket close aborts every in-flight Ollama request; a refused token is
+  fatal (`RunnerAuthError`), everything else reconnects with backoff.
+- Global `WebSocket` -> Node >= 22.
+
+## Run it against a dev stack
+
+```bash
+gcli login --url http://localhost:9004/graphql ...      # dev gateway
+npm run build && node release/index.js runner:start      # ws://localhost:9000/subscriptions derived
+node release/index.js runner:models --show qwen3.8:27b   # keep the picker short
+```
+
+## Tests
+
+`npx jest test/runner.spec.ts --coverage=false` - `FakeServer` plays the
+Lambforge socket (acks, operation replies, pushes requests), `fakeOllama`
+plays Ollama (tags/show/streamed body, optional hold). Add a case there for
+any protocol change.

package/.claude/README.md

@@ -0,0 +1,33 @@
+# .claude/ - Claude Code configuration for this repo
+
+| Path | Committed? | Purpose |
+|---|---|---|
+| `skills` | yes (symlink) | -> `../.agents/skills`, the single source of truth for project skills. Edit skills THERE. |
+| `settings.json` | yes, if present | Team-wide baseline (permissions, hooks) |
+| `settings.local.json` | no (gitignored) | Your personal overrides for this repo |
+| `worktrees/`, `scheduled_tasks.lock` | no (gitignored) | Ephemeral Claude Code state |
+
+Related at the repo root: `AGENTS.md` (the canonical agent guide - tool
+agnostic, read by other agents/editors too), `CLAUDE.md` (a thin loader that
+imports AGENTS.md), `.mcp.json` (project MCP servers, if present).
+
+## How settings layer
+
+`~/.claude/settings.json` (you, all projects) -> `.claude/settings.json`
+(this repo, team) -> `.claude/settings.local.json` (this repo, just you).
+Scalars: later wins. Permission arrays merge, and a `deny` in any layer
+beats an `allow` elsewhere - so you can always tighten locally:
+
+```json
+{ "permissions": { "ask": ["Bash(git push*)"], "deny": ["Read(./.env)"] } }
+```
+
+## Skills
+
+A skill is `.agents/skills/<name>/SKILL.md`: YAML frontmatter (`name`,
+`description` - the description is what decides when it auto-loads, so say
+WHEN to use it) and then the checklist. Invoke with `/<name>`. When a
+workflow proves itself or bites someone, update or add a skill in the same
+change - same rule as docs.
+
+Reference: https://docs.claude.com/en/docs/claude-code/settings

package/AGENTS.md

@@ -0,0 +1,105 @@
+# gcli - agent & teammate guide (start here)
+
+`@gapi/gcli`, the Lambforge platform CLI (package `gapi/packages/gcli` in the
+`gapi` monorepo): login, projects, lambdas (create/update/logs/test, specs,
+`lambforge.yaml`), environments, private clusters, RabbitMQ, plugins, the
+MCP proxy, the esbuild-based `build`/`start`, and the local AI runner
+(`runner:*`). TypeScript, commander, rxjs; bundled by esbuild into
+`release/index.js` (also shipped as a Node SEA binary).
+
+## The Lambforge platform (sibling repos)
+
+Lambforge is a serverless-on-Kubernetes platform (lambdas on a Fission fork,
+private Talos clusters, AI chat/agents, billing). The repos live side by
+side in `reactive-solutions/`; each has its own `AGENTS.md`.
+
+| Repo | Role |
+|---|---|
+| `gql-fission` | Frontend SPA (Lit + @rxdi/@rhtml, Parcel, Apollo) - talks only to the gateway (+ `/subscriptions` WS) |
+| `graphql-server-federated` | Apollo federation gateway (dev :9004): verifies Firebase/CI tokens, forwards the user as a `user` header, composes subgraphs at startup |
+| `graphql-server` | Main subgraph: users, teams, projects, billing, AI chat & agents, MCP server, local AI runners; hosts `/subscriptions` (dev :9000, RabbitMQ pub/sub) |
+| `graphql-server-lambdas` | Lambdas/Fission, environments, secrets/configs, RabbitMQ, plugins, private clusters (multi-cluster), Atlas connector |
+| `graphql-server-functions` | Monorepo of Fission lambdas: cluster-provisioner, billing/cost scrapers, invoices, code-runner, gateway-federation, mcp, ... |
+| `gapi/packages/gcli` | `gcli` CLI: login, lambdas, environments, clusters, MCP proxy, local AI runner |
+| `graphql-server-common` | Shared Mongoose models (`@stradivario/graphql-server-models`) |
+
+**Cross-repo features use one feature slug everywhere** (e.g.
+`local-ai-runners`): one canonical `docs/features/<slug>.md` in the repo
+that owns most of it, a short slice doc in each other repo, and a changelog
+fragment in every repo the change touches.
+
+## Project skills (`.agents/skills/`, mirrored at `.claude/skills`)
+
+| Skill | Owns |
+|---|---|
+| `gcli-command` | Adding a command: registration, lazy actions, `GraphqlClienAPI`, tests, build/release, regenerating `README-CLI.md` |
+| `cluster-targeting` | Commands touching resources that can live on a private cluster (`--clusterId/--clusterName`) |
+| `local-ai-runners` | `runner:*` - the outbound WS client bridging a user's Ollama to the chat |
+| `changelog` | Feature-keyed changelog fragments + feature docs |
+
+## Documentation map
+
+| You need... | Read |
+|---|---|
+| User guide (every command, `lambforge.yaml`, MCP, build) | [`README.md`](README.md) |
+| Generated `--all-help` output | [`README-CLI.md`](README-CLI.md) (regenerate, don't edit) |
+| Features (current state) | [`docs/features/README.md`](docs/features/README.md) |
+| Change history of a feature | `node scripts/changelog.mjs render --feature <slug>` |
+| Local AI runner (slice; canonical in graphql-server) | [`docs/features/local-ai-runners.md`](docs/features/local-ai-runners.md) |
+| Claude Code config in this package | [`.claude/README.md`](.claude/README.md) |
+
+## Key patterns
+
+- Commands: `src/commands/<area>/index.ts` registers `<area>:<verb>` with a
+  lazy `import('./<verb>')` action; register the area in
+  `src/commands/index.ts`.
+- API: `GraphqlClienAPI.query` (`src/services/gql-client.ts`) talks to the
+  gateway as the `gcli login` user (token refreshed after 30 min). Login
+  state: `~/.graphql-server/` (paths in `src/types.ts`).
+- `release/index.js` is COMMITTED and rewritten by every `npm run build` -
+  restore it (`git checkout -- release/index.js`) unless you are releasing.
+- `README-CLI.md` = `node release/index.js --all-help` output.
+
+## Running & testing
+
+```bash
+npx jest --coverage=false        # test/*.spec.ts (jest maps ~/, @introspection/, @commands/)
+npx tsc --noEmit -p .
+npx eslint --fix <files>
+npm run build                    # -> release/index.js
+node release/index.js <command> --help
+npm run patch                    # release: build, version bump, publish
+```
+
+CI (repo root `.github/workflows/`): **Tests** runs on every push to a
+non-master branch - `npx @rxdi/bolt install`, then `npm run lint` and
+`npm test` across all gapi workspaces (gcli included). **Publish** repeats
+lint/test on master before publishing; **Release GCLI Binary** builds the
+SEA binary on `v*` tags. Reproduce Tests locally from the repo root:
+`npm run lint && npm test`.
+
+## Docs, skills and changelog - same change, every time
+
+This repo is documentation-driven. With every change:
+
+1. **Changelog fragment** - `node scripts/changelog.mjs new <feature> "<summary>"`
+   -> fill in what changed + **Test** + **Debug** + **Verification** ->
+   `node scripts/changelog.mjs check`. Never edit `docs/CHANGELOG.md` (archive).
+   Details: the `changelog` skill, `docs/changelog.d/README.md`.
+2. **Feature doc** - keep `docs/features/<feature>.md` true (new feature =
+   new doc + a row in `docs/features/README.md`).
+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.
+
+Before working on an existing feature: `node scripts/changelog.mjs render
+--feature <slug>` + its feature doc. That is where "how to test" and "how
+to debug" live.
+
+## Pitfalls
+
+- `gcli login` overwrites `~/.graphql-server/url`: logging into a dev
+  gateway points every later command (and `runner:start`) at dev.
+- Jest needs the `moduleNameMapper` in `jest.config.js` for the `~/` alias -
+  without it any spec importing command code fails to resolve.
+- `runner:start` needs Node >= 22 (global `WebSocket`).

package/CLAUDE.md

@@ -0,0 +1,20 @@
+# Claude Code entry point
+
+The canonical agent/teammate guide is AGENTS.md - imported below so it loads
+into every session automatically. AGENTS.md (not this file) is where content
+lives: it is the tool-agnostic standard that other agents and editors read
+too. Keep this file a thin loader; never duplicate guidance here.
+
+@AGENTS.md
+
+## Claude-specific notes
+
+- Project skills auto-load from `.claude/skills` (a symlink to
+  `.agents/skills` - edit skills THERE, one source of truth). Invoke with
+  `/<name>`; the table is in AGENTS.md.
+- Documentation-driven: every change ships with a changelog fragment
+  (`node scripts/changelog.mjs new <feature> "<summary>"`, then `check`) and an
+  up-to-date `docs/features/<feature>.md`. Learned something non-obvious?
+  Update the owning skill or AGENTS.md in the same change.
+- Before touching an existing feature, read its history:
+  `node scripts/changelog.mjs render --feature <slug>`.