weaver — the Ink CLI

A self-contained terminal client for the Weaver cloud (12-serving-and-cli.md §7). Ink (React for CLIs) screens over @wildidea/weaver-cloud:

• Login — username prompt (security v1 = username string only), persisted.
• StoryList — resume a story or begin a new one.
• Interview — The Weaver's session-zero script (13-interview.md, verbatim, small-caps register): greeting → two-of-three domain selection → the chosen domains' axis questions (each declinable → open) → length (always) → the 8-question self-portrait battery → startStory.
• Reader — drives advance({ onPatch }) through the §3 block-map reducer (src/render/patchReducer.ts): the page materializes as dimmed glyph shapes and resolves into words; choices appear when the page settles.
• History — ←/→ page browser over served pages.

Usage

weaver                     # begin or resume a story
weaver update              # update to the latest published version (live check)
weaver autoupdate on|off   # toggle auto-update on start
weaver --version           # print the installed version

weaver keeps itself current opt-in. The first time a run finds a newer version, weaver asks you in-app — Always update automatically (turns autoupdate on), Update this time only (updates now, asks again next time), or No thanks (turns autoupdate off, notify-only from then on). After that first answer it never asks again. On start it does a cached (~/.weaver/ update-check.json, 24h TTL) registry check off the critical path; once you have opted out it only notifies you when a newer version exists. Turn on auto-install with weaver autoupdate on (persisted in config.json) or WEAVER_AUTO_UPDATE=on for one run — the CLI then npm install -g @wildidea/weaver@latest and re-execs onto the new bundle (no sudo: global installs land in your nvm prefix). Disable the whole thing at runtime with WEAVER_AUTO_UPDATE=off. Dev builds (0.0.0-dev) never self-update.

Run (dev)

npm install          # links @wildidea/weaver-cloud via file:../../weaver-cloud/client/cloud
npm start            # tsx src/index.tsx

The client lib is a file: link — build it first if its lib/ is stale (cd ../../weaver-cloud/client/cloud && npm run build).

Checks & tests

npm run check        # tsc + eslint
npm test             # node:test via tsx (patchReducer + InterviewSpec assembly)

Config

~/.weaver/config.json:

{
  "username": "hiebj",
  "baseUrl": "https://api.weaver.cx",
  "genBaseUrl": "https://weaver.cx"
}

• baseUrl — buffered REST (API Gateway). Default https://api.weaver.cx.
• genBaseUrl — streaming surface (CloudFront /gen/*). Defaults to baseUrl when a custom baseUrl is set, else https://weaver.cx.
• username is written by the Login screen.

The client identity is compiled in: x-weaver-client-key from WEAVER_CLIENT_KEY at build time (dev default weaver-dev-client-key — a soft gate by design, 12 §6) and x-weaver-client-version from the package version. In dev (npm start) both read the environment directly.

Telemetry

Weaver sends anonymous usage telemetry to CloudWatch RUM — a per-run session with coarse (IP-derived) geography, screen views, errors, and story milestones. It carries a first-party random install id (minted in config.json), never your account name, hostname, or file paths. Disable it entirely with:

WEAVER_TELEMETRY=off

Dev builds (npm start, or any build with no RUM ids baked in) are silent by default. The ids are resolved at build time from SSM /weaver-rum/* (env → .env → SSM), same seam as the client key; absent ⇒ disabled.

Build

WEAVER_CLIENT_KEY=<the shared key> npm run build

scripts/build.ts esbuild-bundles everything — the client lib, ink, react — into dist/weaver.js (ESM, node ≥ 20, shebang). npm consumers never touch CodeArtifact, which is why all deps (including the file: link) live in devDependencies: the published artifact has zero runtime dependencies.

Publish (user-gated — do not run from automation)

1. cd ../../weaver-cloud/client/cloud && npm run build (fresh client lib).
2. npm version patch (bumps the compiled-in client version).
3. WEAVER_CLIENT_KEY=$(aws secretsmanager get-secret-value --secret-id weaver/client-key --query SecretString --output text --profile weaver) npm publish --access public (prepublishOnly runs check + test + build).