crisp-tui 0.1.0 → 0.2.0

package/README.md

@@ -1,18 +1,41 @@
 # crisp-tui
 
+[![CI](https://github.com/solcreek/crisp-tui/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/solcreek/crisp-tui/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/crisp-tui?logo=npm)](https://www.npmjs.com/package/crisp-tui)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Node.js: >=20](https://img.shields.io/badge/Node.js-%3E%3D20-5fa04e?logo=nodedotjs)](https://nodejs.org)
+
 Crisp support inbox built with OpenTUI, SolidJS and Bun. People use the TUI;
 agents use JSON commands and can prepare drafts in the same running screen.
-[crispctl](https://github.com/solcreek/crisp-cli) v0.2.0 provides all REST and RTM
+[crispctl](https://github.com/solcreek/crisp-cli) v0.3.1 provides all REST and RTM
 access. Both profile-based and 1Password sessions use its JSON interface;
 this project has no separate HTTP or Socket.IO implementation.
 
+![crisp-tui running in Ghostty on Omarchy, with an English demo conversation and an agent-prepared reply draft](docs/images/crisp-tui-omarchy.png)
+
+Running on Omarchy with the Tokyo Night theme. The agent-prepared draft is ready
+for human review; all contacts and messages shown are demo data.
+
 ## Install
 
-Requires [Bun](https://bun.sh) 1.4.2 or newer and Node.js 20 or newer on macOS or Linux.
-The npm package installs the `crisp-tui` command; Bun must also be on PATH.
+Requires Node.js 20 or newer on macOS or Linux (glibc), on arm64 or x64.
+**Bun is not required for npm/npx users.** npm installs the matching precompiled
+executable, including the Bun runtime and OpenTUI renderer, automatically.
+Windows and musl/Alpine are not currently supported.
+
+This distribution targets v0.2.0. Until it is published, npm's v0.1.0 still
+requires a separate Bun installation.
+
+Try the demo without a global installation:
 
 ```sh
-npm install -g crisp-tui
+npx crisp-tui@0.2.0 --demo
+```
+
+Or install the command:
+
+```sh
+npm install -g crisp-tui@0.2.0
 crisp-tui --demo
 ```
 
@@ -22,6 +45,8 @@ with a crispctl profile configured, or `crisp-tui live --item 'Crisp development
 connection check. Add `--rtm-timeout 60` to require RTM authentication and an
 actual event within 60 seconds. The npm package includes crispctl as a dependency.
 The following `bun run` examples are for a source checkout.
+Keep npm optional dependencies enabled; they carry the platform executable.
+Installation requires no lifecycle scripts or first-run download.
 
 ## Run from source
 
@@ -39,7 +64,7 @@ Demo mode is explicit, in-memory, and never contacts Crisp. In another terminal:
 ```sh
 bun run src/index.ts ctl state
 bun run src/index.ts ctl goto session_demo_2
-bun run src/index.ts ctl draft session_demo_2 '我來協助你確認設定。'
+bun run src/index.ts ctl draft session_demo_2 'Let me help you check your settings.'
 bun run src/index.ts ctl screen
 ```
 
@@ -94,10 +119,10 @@ requests use Basic auth with `identifier:key` and `X-Crisp-Tier: website`.
 The token belongs to one workspace. `crispctl` supplies these headers; this
 project never includes the secret in UI state or stores a second copy.
 
-The npm installation includes crispctl v0.2.0. To configure it separately on PATH:
+This source checkout uses crispctl v0.3.1. To configure it separately on PATH:
 
 ```sh
-npm install -g crispctl@0.2.0
+npm install -g crispctl@0.3.1
 ```
 
 Alternatively, build [crisp-cli from source](https://github.com/solcreek/crisp-cli#install)
@@ -125,7 +150,8 @@ All crispctl config and environment precedence still applies, including
 to crispctl. Select the same `--profile` / `--website` when issuing `ctl` commands.
 
 Executable lookup: `CRISPCTL_BIN` (one executable path, not a shell command),
-then the installed crispctl dependency, then `crispctl` on PATH, then
+then the npm launcher's bundled crispctl dependency, then the dependency resolved
+from a source checkout, then `crispctl` on PATH, then
 `../crisp-cli/dist/index.js` relative to this source
 checkout. The last option requires Node. A compiled TUI should use PATH or
 `CRISPCTL_BIN`. Credentials stay in the subprocess environment/config; commands
@@ -158,6 +184,8 @@ mode are kept separately for each conversation during this process.
 A failed send keeps the draft; writes are never retried automatically. A timeout
 can leave the send outcome unknown, so refresh before resending. Once a send is
 acknowledged, a failed follow-up refresh does not restore the draft.
+One-shot crispctl calls have a 30-second deadline; 1Password reads have a
+60-second deadline. Partial output from a timed-out process is discarded.
 
 ## Agent workflow
 
@@ -189,7 +217,8 @@ bun run src/index.ts ctl refresh
 bun run src/index.ts ctl screen
 ```
 
-`state` includes protocol version, source, current page/query, active conversation,
+`state` includes protocol version, source, current page/query, selected session,
+conversation-loading state, active conversation,
 loaded messages, per-session drafts and status. `messages` and `conversations`
 return the currently loaded page, without an API call. `screen` is a semantic
 text view of the loaded content, not an exact terminal screenshot. All other
@@ -217,8 +246,12 @@ One newline-delimited JSON request per connection:
 ```
 
 Response: `{"id":1,"ok":true,"result":…}` or
-`{"id":1,"ok":false,"error":"…"}`. Methods match `ctl` verbs. Screen-changing
-agent requests are serialized. No TCP server, daemon or MCP server is started.
+`{"id":1,"ok":false,"error":"…"}`. Methods match `ctl` verbs. Unknown parameters
+and invalid types are rejected. Screen-changing agent requests are serialized;
+local snapshots (`state`, `screen`, `conversations`, `messages`) remain available
+while a refresh or navigation waits on the API. CLI syntax, parameter validation
+and command permissions are defined together in `src/commands.ts`.
+No TCP server, daemon or MCP server is started.
 
 ## Refresh and current boundaries
 
@@ -240,24 +273,63 @@ and writes. Consider this alongside the website token's documented daily quota.
 Conversation history is the latest page exposed by crispctl; there is no older
 message pagination, background daemon, push notifications, attachment upload or
 preview, persisted drafts, or MCP in this first version. Assignment and segments
-are available via the CLI bridge. The default tests use demo data, fake
+are available via the CLI bridge. The default tests use demo data, isolated
 subprocesses and local sockets; they never read 1Password or contact Crisp.
+Contract tests run the installed crispctl against an in-memory HTTP interceptor
+with external network access disabled.
 Real read-only checks are separate, explicitly invoked commands.
 
 ## Verification and binary
 
 ```sh
 bun run typecheck
-bun test
 bun run build
+bun run test:coverage
+bun run test:package
 ./dist/crisp-tui-darwin-arm64 --demo  # filename follows OS / architecture
 ```
 
 The standalone binary embeds Bun and the TUI renderer and needs crispctl on PATH
-or `CRISPCTL_BIN`. The npm package includes crispctl and needs Bun and Node on PATH.
+or `CRISPCTL_BIN`. The npm package includes crispctl and its platform executable;
+only Node.js is needed on PATH. Bun 1.4.2 is a development/build requirement.
 Tests exercise the UI with OpenTUI's
 headless renderer, send failures, concurrent navigation, draft isolation,
-subprocess argument handling and the Unix control protocol.
+polling/RTM cleanup, subprocess argument handling and the Unix control protocol.
+CI checks source and compiled PTY workflows, then packs and installs the npm
+artifacts outside the checkout and runs their PTY workflows with Bun absent from
+PATH. A local test registry lets real `npm exec`/`npx` install the root package
+and choose the correct platform dependency automatically. Both installed and
+npx workflows exercise TUI startup, agent drafts, human send, shutdown and the
+crispctl bridge. The package check downloads dependencies from npm; Crisp API
+access is not required. CI runs on macOS/Linux arm64/x64 with Node.js 20 or 24.
+
+Coverage excludes test fixtures/helpers, checks for missing source files, and
+enforces overall 90% line and function thresholds from LCOV counts. CI uploads
+`coverage/lcov.info` for each platform. The report measures code executed within
+the test process; PTY subprocess coverage
+(including the thin `src/index.ts` entrypoint) is not merged into that percentage.
+The subprocess tests independently verify the executable behavior.
+
+### Publishing platform packages
+
+All five package versions must match. `bun run build:package` compiles and stages
+the host platform under `packages/<os>-<arch>/bin/`. `bun run test:package` produces
+verified tarballs in `dist/npm/`. CI uploads them as `npm-<os>-<arch>` artifacts.
+
+Use artifacts from one successful CI run for the release commit. Publish all four
+platform packages first, then the main package, so new npx installs can always
+find their binary. This requires npm publisher credentials; CI does not publish.
+
+```sh
+gh run download RUN_ID --pattern 'npm-*' --dir release-artifacts
+for platform in darwin-arm64 darwin-x64 linux-arm64 linux-x64; do
+  npm publish "release-artifacts/npm-$platform/crisp-tui-$platform-0.2.0.tgz" --access public
+done
+npm publish release-artifacts/npm-darwin-arm64/crisp-tui-0.2.0.tgz --access public
+```
+
+Do not publish platform packages directly from an unbuilt workspace. The root
+package's optional dependencies are pinned to the exact release version.
 
 ## Development data and license
 

package/bin/crisp-tui.js

@@ -1,4 +1,43 @@
-#!/usr/bin/env bun
-// Register Solid's client runtime before loading the precompiled application.
-import "@opentui/solid/preload"
-await import("../dist/cli.js")
+#!/usr/bin/env node
+import { spawn } from "node:child_process"
+import { createRequire } from "node:module"
+import { constants } from "node:os"
+
+const require = createRequire(import.meta.url)
+const pkg = require("../package.json")
+const platformPackage = `crisp-tui-${process.platform}-${process.arch}`
+try {
+  if (!Object.hasOwn(pkg.optionalDependencies, platformPackage)) {
+    throw new Error(`Unsupported platform: ${process.platform}/${process.arch}. crisp-tui supports macOS and Linux on x64 and arm64.`)
+  }
+  if (process.platform === "linux" && !process.report.getReport().header.glibcVersionRuntime) {
+    throw new Error("This crisp-tui package requires glibc on Linux; musl/Alpine is not supported yet.")
+  }
+  let executable
+  try {
+    const installed = require(`${platformPackage}/package.json`)
+    if (installed.version !== pkg.version) throw new Error("Version mismatch")
+    executable = require.resolve(`${platformPackage}/bin/crisp-tui`)
+  } catch {
+    throw new Error(`Missing ${platformPackage}@${pkg.version}. Reinstall crisp-tui with optional dependencies enabled (npm install --include=optional crisp-tui@${pkg.version}).`)
+  }
+  const child = spawn(executable, process.argv.slice(2), {
+    stdio: "inherit",
+    env: { ...process.env, CRISP_TUI_NODE: process.execPath, CRISP_TUI_CRISPCTL: require.resolve("crispctl/dist/index.js") },
+  })
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"]
+  const handlers = signals.map(signal => { const handler = () => child.kill(signal); process.on(signal, handler); return handler })
+  const cleanup = () => signals.forEach((signal, i) => process.off(signal, handlers[i]))
+  child.once("error", () => {
+    cleanup()
+    console.error(JSON.stringify({ ok: false, error: "Could not start the crisp-tui executable. Reinstall the package and check executable permissions." }))
+    process.exitCode = 1
+  })
+  child.once("exit", (code, signal) => {
+    cleanup()
+    process.exitCode = code ?? (128 + (constants.signals[signal] || 1))
+  })
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : "Could not start crisp-tui" }))
+  process.exitCode = 1
+}

package/package.json

@@ -1,15 +1,29 @@
 {
   "name": "crisp-tui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A terminal inbox for Crisp, with JSON control commands for agents",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/solcreek/crisp-tui.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solcreek/crisp-tui.git"
+  },
   "homepage": "https://github.com/solcreek/crisp-tui#readme",
-  "bugs": { "url": "https://github.com/solcreek/crisp-tui/issues" },
+  "bugs": {
+    "url": "https://github.com/solcreek/crisp-tui/issues"
+  },
   "type": "module",
-  "bin": { "crisp-tui": "bin/crisp-tui.js" },
-  "files": ["bin/crisp-tui.js", "dist/cli.js", "README.md", "LICENSE"],
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "bin": {
+    "crisp-tui": "bin/crisp-tui.js"
+  },
+  "files": [
+    "bin/crisp-tui.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
     "dev": "bun run src/index.ts",
     "demo": "bun run src/index.ts --demo",
@@ -17,16 +31,40 @@
     "live:check": "bun run scripts/live-readonly.ts --check",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "test:coverage": "bun test --coverage && bun run scripts/check-coverage.ts",
+    "test:package": "bun run scripts/test-package.ts",
     "build": "bun run scripts/build.ts",
     "build:package": "bun run scripts/build-package.ts",
-    "prepack": "bun run build:package"
+    "prepack": "bun run scripts/check-package.ts"
   },
   "dependencies": {
+    "crispctl": "0.3.1"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3",
     "@opentui/core": "0.5.12",
     "@opentui/solid": "0.5.12",
-    "crispctl": "0.2.0",
     "solid-js": "1.9.12"
   },
-  "devDependencies": { "@types/bun": "1.3.14", "typescript": "5.9.3" },
-  "engines": { "bun": ">=1.4.2" }
+  "engines": {
+    "node": ">=20"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "optionalDependencies": {
+    "crisp-tui-darwin-arm64": "0.2.0",
+    "crisp-tui-darwin-x64": "0.2.0",
+    "crisp-tui-linux-arm64": "0.2.0",
+    "crisp-tui-linux-x64": "0.2.0"
+  }
 }