nolo-cli 0.1.45 → 0.1.47

package/README.md

@@ -1,145 +1,299 @@
-# nolo-cli
+# @nolo/cli
 
-Local-first agent automation for open-source maintainers.
+Agent-first terminal client for Nolo.
 
-[![npm version](https://img.shields.io/npm/v/nolo-cli.svg)](https://www.npmjs.com/package/nolo-cli)
-[![npm downloads](https://img.shields.io/npm/dm/nolo-cli.svg)](https://www.npmjs.com/package/nolo-cli)
-[![test](https://github.com/nolotus/nolo-cli/actions/workflows/test.yml/badge.svg)](https://github.com/nolotus/nolo-cli/actions/workflows/test.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+`nolo` should be understood as the terminal workspace for Nolo agents. The
+existing command mode still wraps repo scripts, but the product direction is a
+TUI-first experience similar to Claude Code / Codex CLI:
 
-`nolo-cli` is a Bun-powered command-line and TUI client for running local and
-remote AI agents around real repository maintenance. It focuses on practical
-open-source maintainer workflows: Codex-assisted review, issue triage, release
-smoke checks, docs updates, runtime diagnostics, and automation-friendly JSON
-commands.
+- open `nolo` and work inside a persistent Agent session;
+- chat with an Agent;
+- inspect and manage that Agent's dialogs, docs, tables, skills, and spaces;
+- run internal ops/doctor agents with the same mental model;
+- use non-interactive commands and `--json` for automation.
 
-The project is moving toward a no-login, bring-your-own-key local mode:
+The current MVP uses a dependency-free readline workspace. It is intentionally
+small: status line, text input, lightweight slash commands, and script-backed
+Agent chat. A richer Ink UI can replace the rendering layer later without
+changing the session model.
 
-- `nolo run "review this repository"` runs a local Codex-style agent in the
-  current repository without requiring a Nolo account.
-- Authenticated Nolo workflows remain available for synced agents, dialogs,
-  docs, tables, and machine-bound automation.
-- The desktop direction is local-first by default: users should be able to run
-  with their own OpenAI, Anthropic, OpenRouter, Codex CLI, Qoder, or other
-  provider credentials without depending on hosted Nolo infrastructure.
+Inside `nolo`, normal text continues the current dialog after the first agent
+reply. Use `/new` when you want a clean dialog. Response token details stay
+hidden by default; set `NOLO_SHOW_USAGE=1` when debugging usage.
 
-The npm package is published as `nolo-cli`:
+Nolo is intentionally not trying to copy coding-only CLIs one-for-one. Claude
+Code, Codex CLI, and Copilot CLI are strongest when a developer is already
+inside a codebase. Nolo's CLI should sit between ordinary users and developers:
+one assistant by default, with specialist agents, docs, tables, dialogs, and
+synced workspace data one slash command away.
+
+## Usage
 
 ```bash
 npm install -g nolo-cli
 nolo
+
+# see which install you are running
 nolo doctor
 nolo --version
+
+# no Nolo login required: runs the local Codex CLI in the current directory
 nolo run "review this repository"
+
+# update later from your shell
+nolo update
 ```
 
-## Why This Matters
+Inside the TUI, run:
 
-Open-source maintainers are increasingly using coding agents for issue triage,
-pull-request review, release checks, documentation, and repository maintenance.
-Those workflows need more than a single chat box: they need repeatable command
-entry points, local runtime checks, scoped shell permissions, structured
-task/dialog history, release smoke checks, and automation-friendly output.
+```text
+/update
+```
 
-`nolo-cli` is aimed at that layer. It is designed to make agent-maintainer
-workflows inspectable and scriptable, while keeping local runtime boundaries
-clear.
+The published npm package runs on plain Node.js (no Bun required). The
+shipped entry is a bundled `index.js` with a `#!/usr/bin/env node` shebang.
 
-## Maintainer Workflows
+For local maintainer workflows, `nolo run "..."` does not require a Nolo
+account. It resolves to the built-in `local-codex` agent, runs in the current
+working directory, and uses the local Codex CLI installation. This is intended
+for repository-local review, triage, and release-check tasks.
 
-The project is built around ongoing maintainer duties that can be reviewed,
-tested, and improved in public:
+Remote Nolo records and synced workflows still require a token:
 
-- **Pull request review:** run local Codex or another CLI agent against a diff,
-  ask for risk-focused review, and keep the review prompt reproducible.
-- **Issue triage:** classify bug reports, installation failures, runtime
-  provider issues, and docs gaps into actionable labels.
-- **Release management:** run doctor checks, smoke checks, changelog review,
-  and package verification before publishing.
-- **Security review:** keep shell, machine connector, BYOK provider, and token
-  boundaries explicit so contributors can reason about local access.
+```bash
+NOLO_SERVER=https://nolo.chat AUTH_TOKEN=<token> nolo
+```
 
-See [MAINTAINER_WORKFLOWS.md](./MAINTAINER_WORKFLOWS.md) for concrete command
-patterns and [OPEN_SOURCE_BOUNDARY.md](./OPEN_SOURCE_BOUNDARY.md) for what is
-being opened versus intentionally kept private.
+Or save a local profile once:
 
-## Public Source
+```bash
+nolo login --server https://nolo.chat
+nolo whoami
+nolo
+```
+
+By default, `nolo login` opens the Nolo website and waits for browser
+authorization. In SSH or browserless environments, use:
+
+```bash
+nolo login --no-browser
+```
+
+Then open the printed URL on a logged-in browser. Automation can still save a
+token directly:
 
-The first reusable source modules are now mirrored in this repository:
+```bash
+nolo login --server https://nolo.chat --token <token>
+```
 
-- [`src/localRun.ts`](./src/localRun.ts) documents and tests the no-login local
-  run contract for `nolo run` and `nolo chat`.
-- [`src/providerConfig.ts`](./src/providerConfig.ts) documents the BYOK
-  provider credential boundary: public config stores environment variable
-  references, not raw API keys.
-- [`src/runtimeBoundary.ts`](./src/runtimeBoundary.ts) documents the local
-  runtime boundary for no-login CLI and desktop flows: local provider
-  credentials, workspace-scoped shell policy, local persistence, and no remote
-  sync by default.
-- [`src/localRun.test.ts`](./src/localRun.test.ts) verifies that shorthand runs
-  use local Codex without requiring Nolo auth, while explicit agent runs remain
-  distinct.
+Local repo development should use `nolo login` or an explicit `AUTH_TOKEN` for
+agent runs.
 
-Run the public tests with:
+Inside the TUI, `/update` is the shortcut for the same global `nolo update`
+command.
 
 ```bash
-bun test src
-```
-
-Current public source status:
-
-| Area | Public evidence |
-| --- | --- |
-| No-login local run | `src/localRun.ts`, `src/localRun.test.ts`, passing GitHub Actions |
-| BYOK provider boundary | `src/providerConfig.ts`, `src/providerConfig.test.ts`, PR #8 |
-| Local runtime boundary | `src/runtimeBoundary.ts`, `src/runtimeBoundary.test.ts`, PR #8 |
-| Release management | `RELEASE_CHECKLIST.md`, issue #9 |
-| Source mirror safety | `OPEN_SOURCE_BOUNDARY.md`, `SOURCE_MIRROR_CHECKLIST.md`, issues #1 and #5 |
-
-## Project Status
-
-This repository is the public OSS entry point for the CLI project. The package
-is actively maintained and has frequent releases on npm. As of June 2026,
-`nolo-cli` source is prepared for version `0.1.45`; npm reports about 3.5k
-downloads for the last-month window ending 2026-06-02. Version `0.1.44` was
-published from the public `nolotus/nolo-cli` GitHub Actions npm workflow, and
-`0.1.45` should be published from the same public workflow after review.
-
-The current implementation is developed in a broader private monorepo because
-it shares product infrastructure with Nolo. Public source mirroring is being
-managed in a staged way so that reusable CLI, local runtime, provider adapter,
-desktop local-mode, docs, tests, and maintainer workflow code can be opened
-without exposing private product records, credentials, production operations,
-billing systems, or user-data paths.
-
-See [OPEN_SOURCE_STATUS.md](./OPEN_SOURCE_STATUS.md) and
-[ROADMAP.md](./ROADMAP.md) for the public-source migration plan.
-
-## Maintenance Scope
-
-The public maintenance scope for this project is:
-
-- Agent-first terminal and TUI workflows for OSS maintainers.
-- No-login local agent runs in the current repository.
-- BYOK provider configuration for CLI and desktop local mode.
-- Local-first agent runtime boundaries and scoped shell permissions.
-- Runtime doctor, release smoke-check, and package verification workflows.
-- Optional authenticated commands for synced Nolo agents, dialogs, docs, tables,
-  and machine connectors.
-
-## Links
-
-- npm package: https://www.npmjs.com/package/nolo-cli
-- Nolo: https://nolo.chat
-- Maintainer workflows: [MAINTAINER_WORKFLOWS.md](./MAINTAINER_WORKFLOWS.md)
-- Open-source boundary: [OPEN_SOURCE_BOUNDARY.md](./OPEN_SOURCE_BOUNDARY.md)
-- Open-source status: [OPEN_SOURCE_STATUS.md](./OPEN_SOURCE_STATUS.md)
-- Roadmap: [ROADMAP.md](./ROADMAP.md)
-- BYOK provider setup: [docs/provider-setup.md](./docs/provider-setup.md)
-- Desktop local mode: [docs/desktop-local-mode.md](./docs/desktop-local-mode.md)
-- Release checklist: [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md)
-- Source mirror checklist: [SOURCE_MIRROR_CHECKLIST.md](./SOURCE_MIRROR_CHECKLIST.md)
-
-## License
-
-MIT
+nolo --help
+nolo doctor
+nolo update
+nolo
+nolo run "review this repository"
+nolo chat "triage the failing tests"
+nolo chat
+nolo connect
+nolo connect --watch
+nolo connect --daemon
+nolo daemon --server-url https://api.nolo.chat --machine-key sk_machine_xxx
+nolo machine status
+nolo run "summarize my latest agent dialogs"
+nolo doc create --title "Trip Notes" --body "hello" --sync local,us --dry-run
+nolo doc create --title "Proxy Notes" --description "Windows setup" --body-file ./proxy.md --sync local,main,us --allow-secrets
+nolo skill-doc create --title "Agent Query Skill" --description "Inspect recent agent dialogs" --body-file ./skill.md --sync local,main,us
+nolo space read 01KKY77TT0DA9NY7TNW3R7255N --content-key page-user-id --brief
+nolo agent list --json
+nolo agent bind-current agent-user-1-agent-1
+nolo agent runtime-doctor agent-user-1-agent-1
+nolo agent smoke-current agent-user-1-agent-1 --msg "ping"
+nolo chat --agent agent-pub-01APPBUILDER00000001YAII3I --msg "你好"
+```
+
+For document creation, prefer the CLI over direct scripts. Use `nolo doc create`
+for ordinary pages and `nolo skill-doc create` for skill-backed pages. Both
+support `--sync`, `--dry-run`, `--json`, and `--allow-secrets`, and both write
+for the current auth token user rather than a demo bootstrap user.
+
+Experimental machine connector commands:
+
+```bash
+nolo connect          # send one machine heartbeat
+nolo connect --watch  # keep this terminal process online with periodic heartbeats
+nolo connect --ws     # keep a live connector websocket for bound agent runs
+nolo connect --daemon # start connect --ws silently in the background
+nolo daemon --server-url https://api.nolo.chat --machine-key sk_machine_xxx
+nolo machine status   # list machines registered to the current profile
+```
+
+These commands only register machine presence and runtime capabilities today.
+They do not expose shell, file-write, or raw local LLM endpoints.
+
+Run a Slock-style connector command:
+
+```bash
+nolo daemon --server-url https://api.nolo.chat --machine-key sk_machine_xxx
+```
+
+Future published package shape:
+
+```bash
+npx @nolo/daemon@latest --server-url https://api.nolo.chat --machine-key sk_machine_xxx
+```
+
+The daemon registers this computer, reports local CLI capabilities, keeps a live
+websocket open, and executes bound CLI agents on this computer. Agents bind to a
+machine, not to a workspace or project folder.
+
+Bind an agent to the current machine:
+
+```bash
+nolo agent bind-current <agentKey>
+```
+
+The agent keeps its own CLI settings. The binding only records which connected
+machine must be online when that agent runs.
+
+Run a one-command connector smoke test:
+
+```bash
+nolo agent runtime-doctor <agentKey>
+nolo agent smoke-current <agentKey> --msg "ping"
+```
+
+`runtime-doctor` checks whether the agent is a CLI agent and whether the current
+machine has the required CLI capability. `smoke-current` heartbeats the current
+machine, binds the agent to it, opens a temporary connector websocket, calls
+`/api/agent/run`, and prints the returned dialog id/content.
+
+## Product Shape
+
+The preferred command model is Agent-first:
+
+```bash
+nolo agent list
+nolo agent switch <agent>
+nolo agent read <agent>
+nolo agent update <agent> --model gpt-5.4 --cli-provider codex --api-source cli
+nolo agent run <agent> "检查最近失败任务"
+nolo agent run frontend-implementer --msg "修一个小的通知弹窗 CSS 问题"
+nolo agent list --space <space>
+nolo dialog list
+nolo dialog list --space <space>
+nolo dialog read <dialog>
+nolo dialog delete <dialog...> --yes
+nolo doc list --agent <agent>
+nolo table query --table meta-0e95801d90-NOLOTASKBOARD --limit 20
+nolo table query --table meta-0e95801d90-NOLOTASKBOARD --columns '["title","status","owner","priority","codeStatus"]' --no-base-fields --output items
+nolo table update-row --table meta-0e95801d90-NOLOTASKBOARD --row 01ROWID --changes '{"status":"已完成"}'
+nolo table add-column --table meta-0e95801d90-NOLOTASKBOARD --schema-write-ok --name "blockedBy" --label "Blocked By"
+```
+
+`agent list` and `dialog list` use global server candidates for the current CLI
+profile: the selected `--server` / `NOLO_SERVER` plus known Nolo cluster peers.
+List commands merge tombstones so a newer delete on one server hides older live
+records from another.
+
+Delete commands fan out wider by default: the selected server, cluster peers,
+`READ_DIALOG_BASE`, and the local dev API origin. That means `nolo dialog delete`
+and script helpers such as `deleteRecord()` / `deleteAgentRecords()` delete on
+`nolo.chat`, `us.nolo.chat`, and local dev when present—not just the current
+`BASE_URL`. Dialog, doc, skill-doc, space, and agent public-record deletes all
+use this multi-server path; each server applies the normal tombstone/cascade
+behavior for that record type.
+
+`nolo table add-column` mutates table schema metadata, so it requires
+`--schema-write-ok` and should be run serially per table. Row-level table writes
+do not require this flag.
+
+For agent config inspection and small config mutations, prefer the CLI-native
+commands instead of ad hoc scripts:
+
+- `nolo agent list` is CLI-native and prefers the local cache, then degrades to
+  remote query when the local LevelDB cache is unavailable or locked.
+- `nolo agent read <agent>` reads local cached agent records first, then falls
+  back to remote fetch + local cache refresh across known server candidates.
+- if the local LevelDB cache is unavailable or locked, `nolo agent read`
+  degrades to remote-only lookup instead of hard-failing on the local DB.
+- `nolo agent update <agent> ...` is CLI-native and supports small targeted
+  updates such as `--model`, `--cli-provider`, `--api-source`, and repeated
+  `--field key=value`.
+
+Account ownership matters for private agent maintenance. Default new tests,
+validation dialogs, task-board writes, machine-bound agent runs, and
+user-visible results should write to the current operator account
+`0e95801d90`. The legacy
+`b2e06f801f` / platform-demo account still owns older public/shared records, but
+it is being retired as the default write target. Use `nolo agent read`,
+`nolo agent update`, and repo-native helpers as the normal entrypoints; only
+owner-only operations that explicitly target legacy records should use the
+maintained platform-demo token from `scripts/testUtils.ts` or a regenerated
+token from `scripts/generateToken.ts`. Do not copy token strings into docs,
+logs, or prompts.
+
+Inside the current TUI, examples of supported slash commands include:
+`/agent`, `/agents`, `/switch`, `/context` (alias `/ctx`), `/dialog`, `/doc`,
+`/help`, `/new`, `/customize`, `/login`, `/profile`, `/version`, `/quit`
+(alias `/exit`), and `/update` (which maps to `nolo update`).
+
+Future product-direction examples for the broader TUI command model:
+
+```text
+/agent list
+/agent switch ops
+/dialog open latest
+/doc list
+/table query builtin-dialog-probe-runs
+```
+
+See [`docs/nolo-cli-tui.md`](../../docs/nolo-cli-tui.md) for the product and
+technical direction.
+
+## Building for Publish
+
+The CLI is developed in a monorepo with workspace dependencies (`ai` and
+`connector-experimental`). To generate a publish-safe package that can be
+installed via npm outside the monorepo:
+
+```bash
+bun run build:publish
+```
+
+This creates a `dist/` directory with:
+- A single bundled `index.js` (esbuild, `platform: node`, ESM) with a
+  `#!/usr/bin/env node` shebang, runnable on plain Node.js without Bun
+- Workspace dependencies inlined into the bundle
+- A modified package.json with workspace dependencies stripped, `bin.nolo`
+  pointing at `index.js`, and only `index.js` + `README.md` in `files`
+
+The `dist/` directory is the publish-safe artifact consumed by the CI npm
+publish workflow:
+
+```bash
+bun ./scripts/release/prepareCliPublishPackage.ts --out-dir .tmp/nolo-cli-publish
+cd .tmp/nolo-cli-publish
+npm pack
+```
+
+For this repository, the default release path for `nolo-cli` is the GitHub
+Actions workflow [`.github/workflows/cli-npm-publish.yml`](../../.github/workflows/cli-npm-publish.yml).
+Use local `npm pack` or tarball-based `npm install -g` as preflight verification.
+Do not treat manual local `npm publish` as the normal release route unless you
+are intentionally debugging the CI publish lane.
+
+Key differences between repo-local and published versions:
+- **Repo-local**: Runs from source (`packages/cli/index.ts`) under Bun
+  (`bun ./packages/cli/index.ts`, `bun test`) with workspace dependencies
+  resolved by the monorepo
+- **Published**: Runs from the bundled `dist/index.js` under plain Node.js with
+  workspace dependencies inlined and npm packages declared as `dependencies`
+
+Repo-local development still uses Bun (`bun test`, `bun ./packages/cli/index.ts`);
+only the shipped/published runtime is Bun-free.