@gapi/gcli 1.8.237 → 1.8.239

package/docs/changelog.d/2026-10-11-repo-ai-ready-package-setup-agents-md-skills-feature-changelog.md

@@ -0,0 +1,18 @@
+## 2026-10-11 - repo: AI-ready package setup - AGENTS.md, skills, feature-keyed changelog
+
+**Feature:** repo · **Type:** repo
+
+- `AGENTS.md` (canonical guide for this package) + thin `CLAUDE.md`;
+  skills in `.agents/skills/` (`cluster-targeting` moved there, new
+  `gcli-command`, `local-ai-runners`, `changelog`) with `.claude/skills`
+  symlink; feature-keyed changelog (`docs/changelog.d/`,
+  `scripts/changelog.mjs`) and `docs/features/`.
+- `README.md`: new "Local AI Models (Ollama runner)" section.
+  `README-CLI.md` regenerated from `--all-help` - it was missing the cron,
+  cluster, rabbitmq, plugin and `lambda:package` commands.
+- `jest.config.js` maps the tsconfig path aliases (`~/`, `@introspection/`,
+  `@commands/`) - specs importing command code could not resolve before.
+- **Test:** `node scripts/changelog.mjs check`; `npx jest --coverage=false`.
+- **Debug:** spec fails with "Cannot find module '~/...'" -> the
+  `moduleNameMapper` was lost.
+- **Verification:** `check` OK; jest 27/27.

package/docs/changelog.d/2026-10-11-repo-tests-workflow-runs-lint-and-tests-on-every-branch-push.md

@@ -0,0 +1,18 @@
+## 2026-10-11 - repo: Tests workflow runs lint and tests on every branch push
+
+**Feature:** repo · **Type:** tooling
+
+- New `.github/workflows/tests.yml` at the gapi repo root ("Tests"): on
+  every push to a non-master branch (skippable with `[ci-skip]`), Node 24,
+  `npx @rxdi/bolt install`, `npm run lint`, `npm test` across all
+  workspaces; dependencies cached by `yarn.lock` + package manifests. Same
+  shape as graphql-server's Tests / graphql-server-lambdas' Specs. Before,
+  lint/test only ran in Publish - after the merge to master.
+- **Test:** push a branch -> the "Tests" check appears on the PR. Locally,
+  from the gapi root: `npm run lint && npm test`.
+- **Debug:** a red Tests run names the workspace in its log prefix
+  (`(@gapi/gcli) $ npm test ...`); reproduce with the same root command or
+  `npm test` inside that package.
+- **Verification:** locally from the root: lint exit 0 (all 14 eslint
+  workspaces), tests exit 0 (@gapi/ac 1/1, @gapi/cli-builder 1/1,
+  @gapi/gcli 27/27); workflow YAML parsed with js-yaml.

package/docs/changelog.d/README.md

@@ -0,0 +1,51 @@
+# Changelog fragments (by feature)
+
+One file per change: `YYYY-MM-DD-<feature>-<slug>.md`, each a complete entry
+in the template below. Create one with
+
+    node scripts/changelog.mjs new <feature> "<summary>" [--type feat|fix|perf|refactor|test|docs|tooling|repo]
+
+fill in every `<...>` placeholder, run `node scripts/changelog.mjs check`, and
+commit it **together with the change**.
+
+The tool is plain Node (>= 18, no dependencies - runs in any Node
+container, no Python needed); `npm run changelog -- <command> ...` is an
+alias.
+
+Why this shape:
+
+- **Fragments, not one file** - two branches prepending to the same
+  `CHANGELOG.md` conflict on every rebase; two new files never do.
+  `docs/CHANGELOG.md` is the archive and is written only by
+  `node scripts/changelog.mjs compact` (default branch, own commit).
+- **Keyed by feature** - every entry names its feature (`**Feature:**`), and
+  each feature has a living doc in `docs/features/<feature>.md` (`check`
+  enforces it). `node scripts/changelog.mjs render --feature <f>` prints the whole
+  history of one feature, archive included - the starting point when you
+  need to debug or extend it later. `node scripts/changelog.mjs features` lists
+  them all.
+- **Test / Debug / Verification are mandatory** - an entry records how to
+  test the change and where to look when it breaks, not just what changed.
+
+Use the feature `repo` for changes that belong to no single feature (repo
+setup, tooling, dependency bumps). The same feature slug is used across the
+Lambforge repos (gql-fission, graphql-server, graphql-server-lambdas,
+graphql-server-functions, gcli), so a cross-repo feature reads the same
+everywhere.
+
+## Template
+
+```markdown
+## YYYY-MM-DD - <feature>: <one-line summary>
+
+**Feature:** <feature> · **Type:** feat | fix | perf | refactor | test | docs | tooling | repo
+
+- What is now true and why - one bullet per logical change; name the
+  files/modules that own it. Mention the sibling-repo halves of a
+  cross-repo change.
+- **Test:** the specs/commands to run and what passing looks like; manual
+  steps if there is no automated coverage.
+- **Debug:** where to look when it breaks - log prefixes, collections,
+  env flags, likely failure modes and their symptoms.
+- **Verification:** what was actually run for this change and its result.
+```

package/docs/features/README.md

@@ -0,0 +1,33 @@
+# Features
+
+Living docs, one per feature (current state). The change history of a
+feature is in `docs/changelog.d/` - `node scripts/changelog.mjs render --feature <slug>`.
+
+## Writing a feature doc
+
+One file per feature, `docs/features/<feature>.md`, named by the same
+kebab-case slug the changelog uses (`node scripts/changelog.mjs features`). It
+describes what is true NOW - history goes in `docs/changelog.d/`
+(`node scripts/changelog.mjs render --feature <feature>`). Update it in the same
+commit as the change. A feature spanning several repos has ONE canonical doc
+(in the repo that owns most of it) and a short slice doc in each other repo
+that links to it.
+
+Outline (drop sections that don't apply):
+
+1. **Header** - status + date, feature slug, one paragraph: what the user gets.
+2. **How it works** - the flow, end to end; a small diagram if it helps.
+3. **Files** - where each part lives (path -> responsibility).
+4. **Config / limits** - env vars, timeouts, quotas, entitlements.
+5. **How to test** - exact commands/specs, plus manual steps for what has
+   no automated coverage.
+6. **How to debug** - symptom -> where to look (log prefixes, collections,
+   flags). This is the section future-you will need most.
+7. **Security model** - who can do what, what is validated where.
+8. **Known limits / next steps.**
+
+## Features
+
+| Feature | Doc | Notes |
+|---|---|---|
+| `local-ai-runners` | [local-ai-runners.md](local-ai-runners.md) | `runner:*` commands; canonical doc in graphql-server |

package/docs/features/local-ai-runners.md

@@ -0,0 +1,71 @@
+# Local AI runners - gcli slice
+
+**Feature slug:** `local-ai-runners` · canonical doc (architecture, protocol,
+security, debugging table):
+`graphql-server/docs/features/local-ai-runners.md`. This file covers only
+what lives in gcli.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `gcli runner:start [--name] [--token] [--ollama] [--wsUrl] [--reset]` | Connects this machine's Ollama to the chat. First run registers a runner with the `gcli login` session and saves it to `~/.graphql-server/runner.json` (0600); `--token` instead uses a token from Profile -> Local AI runners (headless machines); `--reset` forgets the saved runner and registers a new one. Runs until Ctrl+C, reconnecting with backoff (1s -> 30s). |
+| `gcli runner:list` | Your runners: online, last seen, models |
+| `gcli runner:models [--id] [--show a,b \| --all \| --none]` | Which models appear in the chat picker; no flag = list |
+| `gcli runner:delete [--id]` | Delete a runner and revoke its token (default: the saved one) |
+
+Endpoints: `--wsUrl` > `runner.json` > derived from the `gcli login` URL
+(`https://api.lambforge.com` -> `wss://api.lambforge.com/subscriptions`;
+`http://localhost:9004/...` -> `ws://localhost:9000/subscriptions`).
+Ollama: `--ollama` > `$OLLAMA_HOST` (scheme optional, `0.0.0.0` -> `127.0.0.1`)
+> `http://127.0.0.1:11434`. Requires Node >= 22 (global `WebSocket`).
+
+## Code
+
+`src/commands/runner/`:
+
+- `connection.ts` - `RunnerConnection`: subscriptions-transport-ws client
+  (`connection_init` with `{ runnerToken }`, subscription
+  `subscribeToRunnerRequests`, mutations `runnerHeartbeat` / `runnerRespond`
+  over the same socket), heartbeat every 30s (a failed heartbeat forces a
+  reconnect), request proxying to Ollama, `cancel` -> abort, `ping` every
+  30s while Ollama keeps a request queued. `FrameSender` numbers frames
+  (`seq`), merges consecutive chunks (<= 32KB) and sends batches every 50ms,
+  sequentially. `RunnerAuthError` = token refused -> exit 1 with a `--reset` hint.
+- `ollama.ts` - `ALLOWED_REQUESTS` (only `POST /v1/chat/completions`; the
+  backend has its own copy), `OllamaModels` (`/api/tags` + cached
+  `/api/show` per digest; drops models without the `completion` capability
+  and models `/api/show` answers 404/410 for - e.g. retired `:cloud`
+  models, cached so they aren't re-asked every heartbeat). Each heartbeat
+  also reads `/api/ps` and reports `runtimeContextLength` - the window a
+  LOADED model actually runs with (OLLAMA_CONTEXT_LENGTH / Ollama default).
+  The backend fits every request to it, because Ollama silently drops the
+  oldest messages of a prompt that is too long (see the canonical doc,
+  "Context window").
+- `config.ts` (saved runner, URL derivation), `start.ts`, `list.ts`,
+  `models.ts`, `delete.ts`, `index.ts` (command registration), `types.ts`.
+- `src/services/gql-client.ts` - `createLocalRunner`, `listLocalRunners`,
+  `setLocalRunnerModels`, `deleteLocalRunner` (through the gateway, with the
+  login session).
+
+## How to test
+
+```bash
+npx jest test/runner.spec.ts --coverage=false   # fake server socket + fake streaming Ollama
+npm run build && node release/index.js runner:start --help
+```
+
+`test/runner.spec.ts` plays both the Lambforge server (protocol replies) and
+Ollama (streamed body, multi-byte UTF-8 split across reads, held-open
+streams). Full end-to-end steps: the canonical doc's "How to test".
+
+`npm run build` rewrites the committed `release/index.js` - don't commit
+that from a feature branch unless you are releasing.
+
+## How to debug
+
+Runner log lines: `-> chat request (<model>)`, `<- <status> (<model>) in Ns`,
+`x  cancelled`, `x  <error>`, `Heartbeat failed: ...`, `Cannot reach Ollama
+at ...`. `Disconnected from Lambforge; reconnecting in Ns` = socket closed
+(backend restart, network). For the backend side and the symptom table see
+the canonical doc.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.237",
+  "version": "1.8.239",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"
   },
   "scripts": {
+    "changelog": "node scripts/changelog.mjs",
     "start": "gapi start --outDir release --outFile index.js",
     "patch": "npm run build && npm version patch && npm publish --update-readme --access public && npm run delete-dist",
     "delete-dist": "rm -rf dist",