crisp-tui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 solcreek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+# crisp-tui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+access. Both profile-based and 1Password sessions use its JSON interface;
+this project has no separate HTTP or Socket.IO implementation.
+
+## 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.
+
+```sh
+npm install -g crisp-tui
+crisp-tui --demo
+```
+
+For a Crisp workspace, use `crisp-tui --read-only --profile sandbox --poll 0`
+with a crispctl profile configured, or `crisp-tui live --item 'Crisp development'` with
+1Password. `crisp-tui check --item 'Crisp development'` runs a bounded read-only
+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.
+
+## Run from source
+
+Requires Bun 1.4.2 or newer on macOS or Linux. Demo mode needs no credentials.
+
+```sh
+git clone https://github.com/solcreek/crisp-tui.git
+cd crisp-tui
+bun install
+bun run demo
+```
+
+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 screen
+```
+
+The draft appears in the composer. Review it and press Enter to send. Demo
+messages and drafts disappear on exit. Live mode never falls back to demo data.
+
+## Read real data with 1Password
+
+With `op` connected to the unlocked 1Password desktop app, create an item with
+`API Identifier`, `API Key` and `website_id` fields. Choose its name explicitly:
+
+```sh
+bun run live:check --item 'Crisp development'       # connection + rendering check
+bun run live:readonly --item 'Crisp development'    # interactive read-only TUI
+```
+
+`--website UUID` optionally overrides the item's website ID.
+The credential fields are passed to crispctl through the child environment; no
+config file, token file or customer-data capture is written. Errors omit raw
+API response bodies and headers. The check prints website ID, counts,
+message types and command names, without customer names or message text.
+
+The session passes both `--read-only` and `CRISPCTL_READ_ONLY=1` to crispctl.
+Its REST layer rejects non-GET/HEAD requests, and its listener only subscribes to
+events. The TUI adapter also rejects
+reply/note, resolve/reopen and mark-read before any HTTP request. The TUI displays
+`READ ONLY` and hides its composer; agent drafts are disabled too. Automatic
+polling is off in this mode: RTM events trigger refreshes, and Ctrl+R refreshes
+manually. Opening a conversation does not mark it read.
+
+`live:check` normally uses three REST commands: the first conversation page,
+details of the first conversation, and its messages (one if the inbox is empty).
+With `--rtm-timeout N`, it additionally listens until an event is received or the
+deadline expires. It never sends a test message to generate that event.
+
+For a crispctl-backed TUI, the same client/UI protection is available as:
+
+```sh
+bun run dev --read-only --profile sandbox --poll 0
+```
+
+The flag applies to that TUI instance. The independent `cli` bridge retains
+crispctl's own capabilities. To control the 1Password TUI, use `ctl` with
+`--profile onepassword-readonly --website UUID` (or the same
+`CRISP_TUI_SOCKET` override).
+
+## Website token setup
+
+This TUI uses **website tokens**. As specified in the
+[Crisp website token documentation](https://docs.crisp.chat/guides/rest-api/authentication/website-token/),
+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:
+
+```sh
+npm install -g crispctl@0.2.0
+```
+
+Alternatively, build [crisp-cli from source](https://github.com/solcreek/crisp-cli#install)
+in an adjacent checkout. For the read/write workflow below, configure a sandbox
+profile using environment variables in your shell. Use a development workspace
+for write testing, or the GET-only workflow above when inspecting real data.
+
+```sh
+export CRISP_IDENTIFIER='your-website-token-identifier'
+export CRISP_KEY='your-website-token-key'
+export CRISP_WEBSITE_ID='your-sandbox-website-id'
+export CRISP_TIER=website
+
+bun run src/index.ts cli auth set --profile sandbox
+bun run dev --profile sandbox
+```
+
+The TUI defaults to `sandbox` (or `CRISPCTL_PROFILE`) and checks `auth show`
+before starting. This is a local configuration check, not an API authentication
+probe. It requires `tier=website`, identifier, key and website ID. An API error
+appears in the status bar. The active website ID is visible in the header.
+
+All crispctl config and environment precedence still applies, including
+`CRISPCTL_CONFIG` and `CRISPCTL_*` credential overrides. `--website ID` is forwarded
+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
+`../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
+are spawned as argument arrays, never shell strings.
+
+## Human workflow
+
+The inbox supports paged conversations, server-side search, messages, text and
+file-link display, replies, internal notes, resolve/reopen and explicit mark read.
+Opening or polling a conversation does not mark it read. Drafts and reply/note
+mode are kept separately for each conversation during this process.
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift+Tab | Cycle inbox, messages, composer |
+| ↑↓ / j k | Select inbox row or scroll messages |
+| Enter in inbox | Open conversation |
+| Click inbox row | Open conversation |
+| / in inbox/messages | Search; Enter submits; empty search returns to all |
+| [ / ] in inbox/messages | Previous / next inbox page |
+| Enter in composer | Send reply or internal note |
+| Shift+Enter / Alt+Enter / Ctrl+J | Newline |
+| Ctrl+N | Toggle reply / internal note |
+| Ctrl+E | Resolve / reopen active conversation |
+| Ctrl+U | Mark active conversation read |
+| Ctrl+R | Refresh inbox and active conversation |
+| Esc | Focus inbox |
+| Ctrl+C | Quit |
+
+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.
+
+## Agent workflow
+
+Direct API operations work without a TUI. This is a verbatim bridge to crispctl;
+pass its profile and `--json` flags explicitly:
+
+```sh
+bun run src/index.ts cli conversations list --profile sandbox --json
+bun run src/index.ts cli messages list SESSION --profile sandbox --json
+bun run src/index.ts cli reply SESSION --text 'Hello!' --profile sandbox --json
+bun run src/index.ts cli assign SESSION --user OPERATOR_ID --profile sandbox --json
+bun run src/index.ts cli segments SESSION --set billing,followup --profile sandbox --json
+```
+
+All other crispctl commands are available through `cli`, including people,
+operators, resolve and reopen. Direct write commands act immediately.
+
+The control commands work against the running TUI:
+
+```sh
+bun run src/index.ts ctl state
+bun run src/index.ts ctl conversations
+bun run src/index.ts ctl messages
+bun run src/index.ts ctl goto SESSION
+bun run src/index.ts ctl draft SESSION 'Proposed reply'
+bun run src/index.ts ctl draft SESSION 'Internal context' --note
+bun run src/index.ts ctl draft SESSION 'Revised draft' --replace
+bun run src/index.ts ctl refresh
+bun run src/index.ts ctl screen
+```
+
+`state` includes protocol version, source, current page/query, 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
+successful control results are JSON; errors are JSON on stderr. Exit codes are
+0 success, 1 operation error, 2 usage error, 3 no running TUI. `cli` preserves
+crispctl's own output and exit code.
+
+`draft` never sends or replaces an existing nonempty draft without `--replace`.
+It switches to the target conversation and focuses the composer. There is no
+control-socket send method; direct automated writes belong to crispctl.
+
+### Control protocol
+
+Unix socket in `/tmp/crisp-tui-<uid>/<profile-and-website-hash>.sock`.
+Directory mode 0700, socket mode 0600. One TUI per socket; stale sockets are
+recovered. Override with `CRISP_TUI_SOCKET` in both processes, using a
+private parent directory. Demo and live share the selected profile socket, so
+inspect `state.source` before acting. Processes using different config files
+under the same profile name should use different socket overrides.
+
+One newline-delimited JSON request per connection:
+
+```json
+{"id":1,"method":"draft","params":{"session":"session_demo_1","text":"Hello","note":false}}
+```
+
+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.
+
+## Refresh and current boundaries
+
+The TUI starts `crispctl listen --json --read-only` and subscribes to message
+send/receive/update/removal and conversation-state events. The header shows
+`RTM live`, connecting, reconnecting or error. Crispctl handles endpoint discovery,
+Socket.IO authentication and reconnects. The TUI coalesces event bursts into REST
+refreshes, at most once every five seconds, and refreshes after authentication to
+reconcile changes missed during a disconnected interval. This is event-triggered
+REST reconciliation, not a local cache of every event.
+
+Profile-based sessions also poll every 60 seconds by default. `--poll 0` disables
+that periodic polling; it does not disable RTM. `--poll N` accepts at least 30
+seconds. Polling failures back off exponentially to 15 minutes. A normal refresh
+makes three REST requests. A quiet TUI polling every 60 seconds uses approximately
+4,320 requests/day, with additional calls for RTM-triggered refreshes, searches
+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
+subprocesses and local sockets; they never read 1Password or contact Crisp.
+Real read-only checks are separate, explicitly invoked commands.
+
+## Verification and binary
+
+```sh
+bun run typecheck
+bun test
+bun run build
+./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.
+Tests exercise the UI with OpenTUI's
+headless renderer, send failures, concurrent navigation, draft isolation,
+subprocess argument handling and the Unix control protocol.
+
+## Development data and license
+
+Demo contacts, email addresses and test credentials are synthetic. Tests do not
+load 1Password, use a real Crisp profile or contact the Crisp API. Build outputs,
+local environment files, logs and captures are excluded from version control.
+Use synthetic data when sharing screenshots, test fixtures and bug reports.
+
+MIT — see [LICENSE](LICENSE). This is an independent community project.

package/bin/crisp-tui.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+// Register Solid's client runtime before loading the precompiled application.
+import "@opentui/solid/preload"
+await import("../dist/cli.js")