@lardexx/arenacode 2.5.3 → 2.5.5

package/README.md

@@ -16,16 +16,20 @@ you ──▶ arenacode CLI ──▶ arena-bridge ──▶ agent
 ## Install
 
 ```bash
-npm install -g arenacode
-arenacode --version           # 2.5.2
+npm install -g @lardexx/arenacode
+arenacode --version           # 2.5.2 (the bridge protocol version this client speaks)
 ```
 
 Or without installing:
 
 ```bash
-npx arenacode ask "list the files in my folder"
+npx @lardexx/arenacode ask "list the files in my folder"
 ```
 
+Published as [`@lardexx/arenacode`](https://www.npmjs.com/package/@lardexx/arenacode) — the bare name `arenacode`
+is blocked by npm's similarity check against the existing `arena-code` package, so the scope is required. The
+command is plain `arenacode` in every case.
+
 Requires Node.js 18 or newer. No runtime dependencies.
 
 ## Terminal UI
@@ -36,7 +40,9 @@ rebuilt from opencode 1.19.5's own source (`packages/tui/src/component/prompt`,
 `logo.tsx`, `theme/assets/*.json`) and checked against frames captured from the installed binary in a pty.
 
 ```bash
-arenacode            # opens the TUI (the default when stdout is a terminal)
+arenacode            # opens the TUI on a terminal; on the very first run it asks for URL + key first
+arenacode ui         # same thing, explicitly
+arenacode chat       # the plain line-by-line client, if you really want one
 ```
 
 Home screen — two-tone block wordmark, centred prompt, tips, folder and version in the footer:
@@ -275,8 +281,14 @@ SCENARIO=approve node test/tui.js   # TUI, terminal card confirmation
 SCENARIO=plan node test/tui.js      # TUI, plan approval
 node test/tui.js      # TUI: drives the real pty, checks the rendered frames
 node tools/frame2html.js /tmp/tui-frames.raw docs/tui-preview.html --match done   # frame -> HTML snapshot
+python3 tools/ansi2png.py /tmp/tui-frames.raw docs/tui-session.png --match done    # frame -> PNG snapshot
+BIN=arenacode tools/e2e-installed.sh   # the *installed* package against a real bridge
 ```
 
+`tools/e2e-installed.sh` runs whatever `arenacode` is on `PATH` (or `BIN=…`) against a fresh bridge and a fake
+agent, types a request into the TUI through a pty, and prints the agent's report plus the final screen — the check
+that the published tarball, not just the working tree, drives the bridge.
+
 The integration test spins up `bridge_server.py` from a private copy, runs a fake agent that claims the task,
 then checks that the CLI answered the `local-fs` / `local-exec` cards with the right payloads, applied the file
 write, rendered the timeline and bound the API key to the device.

package/docs/PUBLISHING.md

@@ -1,65 +1,62 @@
 # Publishing
 
-The package is ready: `arenacode@2.5.2`, 23 files, ~60 kB tarball, no runtime dependencies.
+**Live:** [`@lardexx/arenacode@2.5.5`](https://www.npmjs.com/package/@lardexx/arenacode) — 34 files, 226 kB tarball,
+no runtime dependencies. The command stays `arenacode`.
+
+2.5.5 fixes `main()` defaulting the subcommand to `chat`, which sent every bare `arenacode` to the line CLI and
+made the TUI unreachable without typing `ui`; a bare invocation now opens the interface, and on first run the
+interface asks for URL + key instead of printing a dead-end notice.
+
+2.5.4 made the hints launch-aware: run through npx and every message prints the command you can actually paste
+(`npx @lardexx/arenacode init`), plus the one-line way to get the bare `arenacode` command.
 
 ```bash
-cd arenacode-cli
-npm publish --dry-run     # + arenacode@2.5.2
+npm install -g @lardexx/arenacode     # then: arenacode
+npx @lardexx/arenacode                # or one-shot
 ```
 
-## Status of the publish attempt
+## Why the scoped name
 
-| Attempt | Result |
-|---|---|
-| `npm whoami` with the supplied token | ✅ authenticated as `lardexx` |
-| `npm view arenacode version` | ✅ 404 → the name `arenacode` is free |
-| `npm publish` (unscoped `arenacode`) | ❌ `403 Forbidden — You may not perform that action with these credentials.` |
-| `npm publish` (`@lardexx/arenacode`, public) | ❌ same 403 |
+The bare name is taken twice over:
 
-A 403 on PUT with a token that authenticates fine means the token itself is not allowed to write. Three usual
-causes, in order of likelihood:
+1. `arenacode-cli` already exists (an unrelated package).
+2. `npm publish arenacode` is rejected even though the name is unclaimed:
+   `403 Package name too similar to existing package arena-code` — npm's similarity filter, not a permission problem.
 
-1. **The token is read-only.** Granular tokens have a *Permissions → Read and write* switch; the default in some
-   flows is read-only. Create a new one with **Read and write** and package access **All packages**.
-2. **The token is restricted to existing packages.** A granular token limited to a selection of packages cannot
-   create a *new* package name: pick “All packages”.
-3. **The account requires 2FA for publishing.** Then `npm publish --otp=<code>` (or an interactive
-   `npm login` + `npm publish`) is needed; automation tokens must be created with the *bypass 2FA* option.
+npm itself suggests the escape hatch in that error: publish under a scope. Hence `@lardexx/arenacode`.
 
-## Commands
+## The run that worked
 
-```bash
-# A. with a fresh token that can write
-npm login                                    # or: npm config set //registry.npmjs.org/:_authToken=<token>
-npm publish                                   # unscoped: arenacode
+| Attempt | Result |
+|---|---|
+| `npm whoami` with the first token | ✅ `lardexx` |
+| `npm publish` (unscoped `arenacode`) | ❌ `E403 … You may not perform that action with these credentials` (read-only token) |
+| `npm publish` with the second token | ❌ `EOTP … requires a one-time password` (write token, 2FA enforced) |
+| `npm publish` with the third token (2FA bypass) | ❌ `403 … Package name too similar to existing package arena-code` |
+| `npm publish --access public` as `@lardexx/arenacode` | ⚠️ `202 Accepted` → a `0.0.0-stage` **placeholder** appeared (`"stub": true`), the real version was staged |
+| re-publish the same version | ❌ `409 Cannot publish over previously staged version "2.5.2"` |
+| `npm stage list` / `stage approve` | ❌ "No staged versions" / `stage-id must be a valid UUID` — nothing to approve from the CLI |
+| **bump to 2.5.3 and publish** | ✅ `+ @lardexx/arenacode@2.5.3`, `dist-tags.latest = 2.5.3` after ~2 min of async processing |
+| 2.5.4 (npx-aware hints) | ✅ same path, again ~1–2 min of async processing before it appeared |
 
-# B. with the tarball
-npm publish arenacode-2.5.2.tgz
+Two lessons for next time:
 
-# C. under your scope (always available to your account)
-node -e "const p=require('./package.json');p.name='@lardexx/arenacode';p.publishConfig={access:'public'};require('fs').writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')"
-npm publish --access public
-```
+* a new scoped package may land asynchronously — the registry answers `202 Accepted`, shows a `0.0.0-stage` stub and
+  needs a couple of minutes before `https://registry.npmjs.org/<pkg>` returns 200. Poll it before assuming failure;
+* a version that was ever staged cannot be republished, so bump the version instead of retrying it.
 
-The `bin` stays `arenacode` in all three cases, so the installed command is the same:
+## Publishing a new version
 
 ```bash
-npx arenacode          # or npx @lardexx/arenacode
+cd arenacode-cli
+npm version patch --no-git-tag-version     # 2.5.3 → 2.5.4
+npm test && node test/tui.js               # CLI + TUI suites
+npm pack                                   # inspect the tarball first
+npm publish --access public                # needs a Read+write, All-packages, 2FA-bypass token
 ```
 
-## Checklist before publishing
-
-- [x] `npm pack --dry-run` clean, no stray files (`test/`, `tools/` are excluded by the `files` field)
-- [x] `npm test` green (bridge + fake agent + CLI)
-- [x] `node test/tui.js` green (real pty, rendered frames)
-- [x] `LICENSE` (MIT), `README.md`, `docs/`
-- [ ] version policy: `2.5.2` tracks the ArenaCode client it ports; use `2.5.3`/`2.6.0` afterwards, and keep the
-      client number in `src/config.js` (`VERSION`) in sync
+`publishConfig.access = public` is already in `package.json`, and `files` ships only `bin/`, `src/`, `docs/`,
+`README.md`, `LICENSE` — 34 files, ~226 kB.
 
-## After publishing
-
-```bash
-npm view arenacode version dist.tarball
-npm install -g arenacode
-arenacode doctor
-```
+The `VERSION` shown by the CLI is the **bridge protocol version** (2.5.2) and is deliberately separate from the
+package version: the client keeps speaking the same protocol as `arena-bridge` 2.5.2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lardexx/arenacode",
-  "version": "2.5.3",
+  "version": "2.5.5",
   "description": "Terminal client for ArenaCode: talks to an arena-bridge, streams the Agent Mode timeline, and runs local commands and file operations on your PC. Node port of the ArenaCode desktop client.",
   "license": "MIT",
   "type": "commonjs",

package/src/cli.js

@@ -15,6 +15,21 @@ const { c, write, ask, banner, truncate, indentLines } = require('./ui');
 
 const AGENT_PROMPT_FILE = path.join(__dirname, 'prompts', 'agent-prompt.md');
 
+/**
+ * How this process was started, so the hints it prints are commands the user can actually paste.
+ * `npx @lardexx/arenacode …` never puts `arenacode` on PATH, and on Windows that reads as
+ * "not recognized as an internal or external command".
+ */
+const SELF = (() => {
+  const agent = process.env.npm_config_user_agent || '';
+  const viaNpx = /\bnpm\/.*\bexec\b|\bnpx\b/.test(agent) || process.env.npm_lifecycle_event === 'npx';
+  if (!viaNpx) return 'arenacode';
+  return process.platform === 'win32' ? 'npx @lardexx/arenacode' : 'npx @lardexx/arenacode';
+})();
+const INSTALL_HINT = process.platform === 'win32'
+  ? 'npm install -g @lardexx/arenacode   (then reopen the terminal)'
+  : 'npm install -g @lardexx/arenacode';
+
 const MODE_LINES = {
   agent:
     '[ArenaCode mode: agent]\n' +
@@ -103,7 +118,8 @@ function requireUrl(ctx) {
   if (ctx.url) return true;
   write('');
   write(c.red('  no bridge URL configured.'));
-  write(`  ${c.gray('run:')} arenacode init        ${c.gray('or')}  arenacode config set url https://your-bridge.tunnl.gg`);
+  write(`  ${c.gray('run:')} ${SELF} init        ${c.gray('or')}  ${SELF} config set url https://your-bridge.tunnl.gg`);
+  if (SELF !== 'arenacode') write(`  ${c.gray('to get the bare command:')} ${INSTALL_HINT}`);
   return false;
 }
 
@@ -113,7 +129,7 @@ async function ensureAuth(ctx) {
   const reason = (res.json && (res.json.error || res.json.hint)) || `HTTP ${res.status}`;
   write(c.red(`  auth failed: ${reason}`));
   if (res.status === 403) write(c.gray('  this API key is bound to another PC: on the bridge run  keys unbind <ID>'));
-  if (res.status === 401) write(c.gray('  check the API key: arenacode config set key <API key>'));
+  if (res.status === 401) write(c.gray(`  check the API key: ${SELF} config set key <API key>`));
   return false;
 }
 
@@ -121,7 +137,7 @@ async function ensureAuth(ctx) {
 // commands
 // --------------------------------------------------------------------------- //
 
-async function cmdInit(flags) {
+async function cmdInit(flags, { tail = true } = {}) {
   banner(VERSION);
   const cfg = readConfig();
   write(c.gray(`  config file: ${configPath()}`));
@@ -144,8 +160,10 @@ async function cmdInit(flags) {
   const auth = await bridge.authCheck();
   if (auth.status === 200) write(`  ${c.green('✓')} API key accepted`);
   else write(c.red(`  ✗ API key rejected: ${(auth.json && auth.json.error) || auth.status}`));
-  write('');
-  write(`  ${c.gray('try:')} arenacode ask "list the files in my folder"`);
+  if (tail) {
+    write('');
+    write(`  ${c.gray('try:')} arenacode ask "list the files in my folder"`);
+  }
   return 0;
 }
 
@@ -166,7 +184,7 @@ function cmdConfig(positional, flags) {
     const name = key;
     const val = rest.join(' ');
     if (!name || val === '') {
-      write('usage: arenacode config set <url|key|folder|lang|mode|pc_access> <value>');
+      write(`usage: ${SELF} config set <url|key|folder|lang|mode|pc_access> <value>`);
       return 2;
     }
     const patch = {};
@@ -186,7 +204,7 @@ function cmdConfig(positional, flags) {
     write(`  ${c.green('✓')} config removed`);
     return 0;
   }
-  write('usage: arenacode config [show|path|set <key> <value>|clear]');
+  write(`usage: ${SELF} config [show|path|set <key> <value>|clear]`);
   return 2;
 }
 
@@ -337,13 +355,25 @@ async function cmdAsk(positional, flags) {
 
 /** Full-screen TUI (opencode-style): timeline, input box, dialogs, local cards. */
 async function cmdUi(flags) {
-  const ctx = context(flags);
-  if (!requireUrl(ctx)) return 1;
+  let ctx = context(flags);
   if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    if (!requireUrl(ctx)) return 1;
     write(c.red('  the TUI needs an interactive terminal.'));
     write(c.gray('  inside a script or a pipe use: arenacode ask "…" or arenacode chat'));
     return 1;
   }
+
+  // First run: `arenacode` (or `arenacode ui`) opens the setup here instead of printing two lines
+  // and quitting — the interface is what the user came for, the questions are just the way in.
+  if (!ctx.url) {
+    write('');
+    write(`  ${c.bold('first run')} ${c.gray('· bridge URL and API key (Enter keeps the value in brackets)')}`);
+    write('');
+    await cmdInit(flags, { tail: false });
+    write('');
+    ctx = context(flags);
+    if (!ctx.url) return 1;   // setup was abandoned: nothing to open
+  }
   const { App } = require('./tui/app');
   const app = new App({
     url: ctx.url,
@@ -621,6 +651,10 @@ async function cmdHandshake(flags) {
 function help() {
   banner(VERSION);
   write(`  ${c.bold('usage')}  arenacode <command> [options]`);
+  if (SELF !== 'arenacode') {
+    write(`         ${c.gray('you are running it through npx — every command can be prefixed the same way,')}`);
+    write(`         ${c.gray(`or install it once: ${INSTALL_HINT}`)}`);
+  }
   write('');
   write(`  ${c.cyan('setup')}`);
   write(`    init                       configure URL + API key, test the connection`);
@@ -663,7 +697,10 @@ function help() {
 
 async function main(argv) {
   const { flags, positional } = parseArgs(argv);
-  const [command = 'chat', ...rest] = positional;
+  // No default here: a bare `arenacode` must be distinguishable from `arenacode chat`, because only
+  // the bare form opens the TUI. Defaulting to 'chat' sent every plain invocation to the line CLI.
+  const [first = undefined, ...rest] = positional;
+  const command = first;
 
   if (flags.version || command === 'version') {
     write(VERSION);
@@ -704,13 +741,16 @@ async function main(argv) {
     case 'handshake':
       return cmdHandshake(flags);
     default:
+      if (command === undefined) {
+        // bare invocation: the interface, when there is a terminal to draw it on
+        if (process.stdout.isTTY && process.stdin.isTTY) return cmdUi(flags);
+        help();
+        return 0;
+      }
       if (command.startsWith('-')) {
         // `arenacode "instruction"` convenience form
         return cmdAsk(positional, flags);
       }
-      if ((command === 'chat' || command === undefined) && process.stdout.isTTY && process.stdin.isTTY) {
-        return cmdUi(flags);
-      }
       write(c.red(`  unknown command: ${command}`));
       help();
       return 2;