create-opentray 0.19.0 → 0.20.0

package/README.md

@@ -1,7 +1,10 @@
+<p align="center"><img src="./assets/create-opentray-logo.png" alt="create-opentray logo" width="180"></p>
+
 # create-opentray
 
 Turn any start command that serves HTTP locally into an OpenTray-hosted
-desktop app — through a browser wizard, without writing OpenTray code.
+desktop app — through a browser wizard or fully non-interactively, without
+writing OpenTray code.
 
 ```bash
 npx create-opentray
@@ -9,149 +12,148 @@ npx create-opentray
 
 Requires Node >= 20 (native `sharp` icon pipeline).
 
-## What it does
-
-1. Starts a token-guarded WebUI (React + shadcn/ui) on `127.0.0.1` and opens
-   your browser.
-2. You paste a start command (e.g. `npx somecommand start --xx`). It runs
-   immediately in a **real interactive terminal** inside a Chrome-style tabs
-   panel: prompts, TUI output, and keystrokes all work.
-3. Confirmed HTTP services (TCP listener owned by the command's process tree
-   **and** answering an HTTP probe) each open an iframe tab automatically —
-   newly sniffed tabs take focus — and stay alive across switches. The tab
-   strip sits above the context toolbar; on service tabs it shows an editable
-   URL with back/forward/reload backed by a per-tab history. The terminal tab's status bar shows cursor position,
-   selection range, and clickable service entries that jump to the matching
-   iframe tab by hostname.
-4. Auto-derived defaults (scraped title, derived appId) are shown as
-   **input placeholders** — an empty field means "use the default"; edits win
-   over later scrapes. The icon row is a square file picker plus scraped
-   candidates: every icon the page declares (SVG, apple-touch-icon, sized
-   PNG sets, /favicon.ico) is collected, measured by true pixel clarity,
-   deduplicated perceptually, and ranked; clicking a candidate (or uploading
-   a local image) selects it, and the clearest candidate is the default.
-5. 高级选项 — the settings button beside the command bar opens an accordion:
-   - 命令选项: 参数输入模式 (string vs 数组/argv — array mode commits ONE argv
-     element per tag, verbatim, never splitting strings), 工作目录 (cwd;
-     default is the USER_HOME directory, displayed in full — relative paths
-     resolve from there), and 环境变量 (env overlay; also persisted into the
-     generated app).
-   - 应用选项: the tray-icon picker (defaults to the app icon choice; solid
-     black/white silhouettes derived from every candidate) and the two
-     generated-app window options 显示启动终端 / 显示地址栏 (both default off).
-   Service ports are NEVER hard-bound: the form has no manual port input, and
-   the generated app resolves its address exclusively by sniffing the
-   command's owned listening ports (HTTP-verified) at runtime.
-6. 确定创建 freezes the resolved identity, shows a confirmation dialog, then
-   确认生成 runs the pipeline with live logs: scaffold → icon generation →
-   dependency install → first launch → (macOS) stable bundle verification.
-7. Success offers 打开应用 plus a platform pinning hint (Windows taskbar /
-   macOS Dock).
-
-## CLI
+## Command tree
 
-```
-create-opentray [targetDir] [--no-open] [--port <n>] [--pm npm|pnpm|bun]
-                [--skip-install] [--force]
+```text
+create-opentray                        # WebUI wizard (compatibility default)
+create-opentray web [--port <n>] [--no-open]
+create-opentray create [options]       # non-interactive creation
+create-opentray app list|edit|copy|export|uninstall
+create-opentray skill [list|read]      # packaged English AI skill
 ```
 
-- `--no-open` — print the wizard URL instead of opening a browser.
-- `--pm` — force the package manager used for the generated project.
-- `--skip-install` — scaffold without installing dependencies.
-- `--force` — allow materializing into a non-empty directory.
+Every command accepts `--json` for a machine-readable typed result on stdout
+(progress and diagnostics then use stderr only).
 
-## Generated project
+## Non-interactive create
 
-Projects default to `~/.opentray/create/<name>/` (stable per app — re-running
-the wizard for the same command regenerates the same location and never
-pollutes the invocation directory). Pass a positional argument to place the
-project elsewhere. When the target directory already exists, the wizard
-warns in 高级选项 and offers 强制覆盖, which CLEARS the directory and
-regenerates it (equivalent to `--force`; the generated tree is fully
-wizard-owned and regenerable).
+```bash
+npx create-opentray create \
+  --app-id app.local.mytool \
+  --app-name "My Tool" \
+  --exec npm --arg run --arg dev \
+  --cwd /path/to/project \
+  --app-icon https://example.com/logo.png \
+  --tray-icon ./tray.png \
+  --pm npm
+```
 
+- `--arg` is repeatable; each value is ONE exact argv element — never a shell
+  string (`&&` stays a literal argument).
+- Icon sources: local files, `http(s)` URLs, or `data:` URLs. The CLI never
+  scrapes names or favicons.
+- `--config <file>` loads a complete v1 document; explicit flags override
+  only their named fields.
+- `--dry-run` prints the plan without mutating anything.
+- `--force` replaces only a VERIFIED create-opentray payload — it never
+  adopts or clears a user directory.
+- `--no-image-smoothing` renders icons with nearest-neighbor sampling
+  (pixel-art safe: enlarged app/tray icons keep hard edges).
+- `--developer-mode` admits WebView DevTools in the generated app (default
+  off; it means nothing else).
+- `--window <WxH>` sets the window size (default 1200x800).
+
+## The v1 registry layout
+
+```text
+~/.opentray/create/<encoded-app-id>/
+  create-opentray.json      # the SOLE editable authority (schemaVersion 1)
+  app/                      # generated payload (managed dir, or a link)
+  app-icon.<ext>            # committed icon snapshots (hash-verified)
+  tray-icon.<ext>
 ```
-<project>/
-  package.json          deps: opentray, @opentray/ext-webview (+ @lydell/node-pty
-                        when the startup terminal is enabled)
-  opentray.app.json     frozen identity, command vector, service port, window size,
-                        tray icon, shell options
-  main.mjs              entry: supervises the command, owns tray + windows
-  app-shell-server.mjs  local shell host (only when a shell option is enabled):
-                        serves app-shell/ + SSE state + terminal input
-  app-shell/            prebuilt shell UI pages (terminal.html, browse.html)
-  app-icon/             generated ICNS/ICO/Linux PNGs + app-icon.json manifest
-                        + tray-icon.png (always, when any icon source exists)
-
-Icon composition: the wizard analyzes the chosen foreground (alpha-weighted
-luminance + opaque coverage, read at full size so no resampling padding
-skews the reading) and composites it — ORIGINAL pixels preserved, never
-recolored — over one of three backgrounds: light art → black, dark art →
-white, fully-opaque art → transparent. Live preview, auto/manual selection,
-and a 50–95% foreground scale control. Every composition is clipped to the
-squircle alpha carried by the bundled backgrounds (including the transparent
-one), which rounds the composite's corners on macOS. For macOS the ENTIRE tile
-(background + art) is scaled to 824 and centered on the transparent 1024
-canvas — Dock icons since Big Sur carry those margins — while Windows/Linux
-use the full-bleed 1024. The tray icon stays on the raw source.
-  README.md
+
+`create-opentray.json` is the only file you edit: identity/name, exact
+command vector (executable/args/cwd/env), package manager, icon resource
+references with content hashes and provenance, icon-rendering options
+(including `imageSmoothingEnabled`), window options, and `developerMode`.
+Generated files are derived output and are regenerated on every apply.
+
+Key rules:
+
+- **appId is immutable** — a new identity is `app copy`, never an edit.
+- **The registry root is fixed** at `~/.opentray/create/`.
+- **Snapshots are stable** — URL-fetched icons are committed locally; later
+  URL drift never changes an existing registration.
+- **Breaking boundary**: projects identified only by the older
+  `opentray.app.json` marker are not discovered, listed, or migrated.
+
+## Managing applications
+
+```bash
+npx create-opentray app list
+npx create-opentray app edit app.local.mytool --app-name "Renamed" --force
+npx create-opentray app copy app.local.mytool --new-app-id app.local.tool2
+npx create-opentray app export app.local.mytool --format sh -o make.sh
+npx create-opentray app uninstall app.local.mytool
 ```
 
-The entry spawns the recorded command (output → `app.log`), waits for the
-service port via TCP, then calls `createTray` with the frozen `appId`,
-`appName`, generated `appIcon`, an optional tray icon, and an explicit absolute
-`appLaunch` vector, and opens an `appMode: true` WebView window on the service
-URL. Quit lives in the tray menu.
-
-### Shell options (dedicated windows)
-
-- 显示启动终端 — the command runs through a PTY and a DEDICATED terminal
-  window opens: command bar on top, the same ghostty renderer the wizard uses,
-  status bar with cursor, size, and live listened ports (detached ports are
-  marked). Input flows back through the shell server.
-- 显示地址栏 — every service window renders as an address-bar wrapper: the bar
-  sits above the service iframe and navigation is managed through the Web
-  Navigation API (same-origin `?url=` pseudo-routes are intercepted so only
-  the iframe moves; a history fallback covers engines without the API). With
-  the option off, service windows open the service URL directly.
-- Every listened HTTP port owned by the command opens its own window
-  automatically; when a port stops listening, its window title becomes
-  `AppName (detached)` and reverts when the port returns.
-- Generated entries always launch with Node even when the wizard ran under Bun
-  (the native PTY transport requires a Node host).
+- `app list` reports health: `healthy`, `invalid-config`,
+  `incompatible-version`, `missing-payload`, `broken-link`, or `running`,
+  with registration and payload paths.
+- A running instance blocks edits/uninstalls with a typed `app_running`
+  result until `--stop-running` is passed. Processes are terminated only
+  when the recorded PID, ownership token, and start fingerprint still match;
+  a reused PID is refused, never killed.
+- `app uninstall` retains a linked external target unless `--purge-target`
+  explicitly authorizes deletion after revalidation. macOS Dock pins and
+  Windows taskbar pins are user-managed.
+
+## Export
+
+`app export` produces a complete recreation artifact:
+
+- `--format command` — exact argv command line (uploads embed as data URLs
+  only with `--force-copy`).
+- `--format sh` / `--format ps1` — self-contained scripts (LF / CRLF);
+  uploaded icon bytes are embedded and reconstructed into a temp file before
+  invocation.
+- Any environment entry makes complete export require `--acknowledge-env`.
+  create-opentray never guesses which values are sensitive — it always asks
+  once, and never echoes env values in ordinary output.
+
+## WebUI wizard
+
+`create-opentray` (or `create-opentray web`) starts a token-guarded WebUI on
+`127.0.0.1` and opens your browser: paste a start command, watch it run in a
+real interactive terminal, confirmed HTTP services open as tabs, and
+identity/icon defaults are suggested from the served page (every suggestion
+is a placeholder you can override). The wizard speaks the same Core as the
+CLI, so both produce identical plans.
+
+## Generated project
+
+The entry (`main.mjs`) spawns the recorded command (output → `app.log`),
+continuously discovers the command's OWNED HTTP listening ports (foreign
+listeners such as browser DevTools sockets are never adopted), hosts each
+verified port in an application-mode WebView window, and owns the tray
+session (Quit lives in the tray menu). Optional startup-terminal and
+address-bar shells are available through the wizard's advanced options.
 
 ## Platform notes
 
-- **Objective terminal transport**: the preview runs through
-  [@lydell/node-pty](https://github.com/lydell/node-pty) (prebuilt per-platform
-  binaries; no compiler needed) and is rendered by
-  [ghostty-web](https://github.com/coder/ghostty-web). The backend forwards the
-  PTY binding's chunks verbatim — no re-decoding, no analysis; the renderer
-  owns every escape sequence. Invalid bytes are replaced with U+FFFD *inside
-  the PTY binding* (its documented text-channel contract, shared with every
-  node-pty consumer); the wizard adds no interpretation on top.
-- The optional PTY dependency degrades to a read-only pipe mode with a visible
-  notice when it cannot load; the wizard itself keeps working.
-- **Runtime-native PTY backends**: under Bun the terminal attaches through
-  the built-in `Bun.Terminal` + `Bun.spawn({ terminal })` (no native npm
-  dependency, fully interactive — verified output, stdin echo, resize, and
-  exit codes on Bun 1.3.14). Under Node it uses prebuilt `@lydell/node-pty`.
-  Both transport the PTY's chunks verbatim. Only when neither backend exists
-  (Node without the optional dependency, or a Bun older than 1.2.19) does the
-  preview degrade to read-only pipes with a visible notice.
-- The Run button becomes an Interrupt button while the preview process is
-  alive and returns to Run when the process exits — including when it is
-  killed outside the wizard.
-- The generated app runs the command supervised but headless (output goes to
-  `app.log`); commands that require an interactive TTY at runtime are not
-  supported inside the generated app.
 - macOS: the stable `.app` bundle is materialized by the OpenTray runtime on
-  first launch; 打开应用 uses `open <bundle>.app` (cold launch via the launch
-  descriptor, warm reopen focuses the retained window). Pin it to the Dock.
-- Windows: the appMode window participates in the taskbar/Alt-Tab; pin it from
-  the taskbar. Persistent shortcut generation is not provided yet.
-- Linux: taskbar pinning depends on the desktop environment; `.desktop`
-  generation is not provided yet.
+  first launch; pin it to the Dock (removing a pin is manual).
+- Windows: directory links use junctions (or symlinks when permitted);
+  failure is a typed error, never a silent copy. The appMode window joins
+  the taskbar/Alt-Tab. Native acceptance runs on Windows agents —
+  non-Windows fixtures are preparatory evidence only.
+- Linux: taskbar pinning depends on the desktop environment.
+
+## AI skill
+
+The package ships an English AI skill (`skill/`) readable without any
+network access:
+
+```bash
+npx create-opentray skill                 # read SKILL.md
+npx create-opentray skill list references # list one directory
+npx create-opentray skill read SKILL.md   # read any packaged file
+```
+
+Skill access is read-only and contained: absolute paths, `..` traversal, NUL
+bytes, and symlink escapes are rejected before any filesystem read, and the
+output is always the canonical English tree regardless of host locale.
 
 ## Programmatic use
 
@@ -159,5 +161,6 @@ URL. Quit lives in the tray menu.
 import { createWizardSession, deriveDefaultAppId } from "create-opentray";
 ```
 
-See the package's TypeScript definitions (dist/index.d.mts) for the full surface (wizard session, server,
-discovery, scraping, launch-vector resolution, scaffold, materialize).
+See the package's TypeScript definitions (dist/index.d.mts) for the full
+surface (wizard session, server, discovery, scraping, launch-vector
+resolution, scaffold, materialize).