@omochi-ui/utils 0.1.2 → 0.2.0

package/README.md

@@ -1,202 +1,65 @@
-# @omochi-ui/utils
-
-Publish command controls, development observations, and agent-created A2UI
-surfaces through the existing Omochi gateway. Requires a Unix-like environment,
-like the discovery transport. Build with `bun install && bun run build` from the
-repository root.
-
-## Turn a command into a button
-
-```sh
-bun run omochi-utils button --service-id build --name "Build" -- bun run build
-# In another terminal:
-bun run omochi-ui hub
-```
-
-Open the hub's printed URL, then use **Add view** to add `Build · main` to a
-dashboard. The command runs only when clicked. The surface shows live combined
-stdout/stderr, running status and the exit code. Only one execution can run at
-a time, including when multiple browsers are connected. After completion or a
-startup failure the button can be used again.
-
-```sh
-bun run omochi-utils button --name "Tests" --cwd /path/to/project -- bun run test
-bun run omochi-utils button --name "Pipeline" -- sh -c 'printf hello | wc -c'
-```
-
-Arguments after `--` are passed literally without a shell. Commands inherit the
-environment and current directory unless `--cwd` is supplied; stdin is closed.
-Output keeps the latest 64 KiB, marks truncation, and resets on each run. It is
-displayed as literal code, not interpreted as Markdown. Ctrl+C or SIGTERM stops
-child process groups (TERM, then KILL within one second) and retracts the service.
-
-## Watch a command
-
-```sh
-bun run omochi-utils watch --interval 2s -- git status --short
-bun run omochi-utils watch --diff --on-change --history 10 -- bun run test
-bun run omochi-utils watch --timeout 30s --cwd /path/to/project -- command args
-```
-
-`watch` runs immediately, waits for the command to finish, then waits for the
-interval before running again. Runs never overlap. The surface can pause future
-runs, resume immediately, or run once now. `--timeout` stops a hung process group.
-`--diff` shows the current output and a line diff from the previous run;
-`--on-change` suppresses completed updates whose output and exit result are
-unchanged. `--history N` retains 1–100 short execution records without retaining
-old full output.
-
-## Control a long-running process
-
-```sh
-bun run omochi-utils process --name "Dev server" -- bun run dev
-bun run omochi-utils process --restart on-failure --restart-delay 2s -- worker
-```
-
-Processes start only when **Start** is clicked. The surface provides **Stop** and
-**Restart**, retains the latest 64 KiB of logs across restarts, and records exit
-reasons. `--restart` accepts `never` (the default), `on-failure`, or `always`.
-Manual stops and CLI shutdown never trigger automatic restart.
-
-## Follow a log file or stdin
-
-```sh
-bun run omochi-utils tail --lines 200 ./logs/api.log
-journalctl -f | bun run omochi-utils stream --name "System log"
-```
-
-`tail` waits if the path does not exist and follows the name across truncation
-and log rotation, like `tail -F`. It treats the file as UTF-8 and never writes to
-it. `stream` displays stdin as UTF-8. When stdin reaches EOF, it leaves the final
-surface visible until SIGINT or SIGTERM instead of exiting immediately.
-
-## Monitor HTTP
-
-```sh
-bun run omochi-utils http http://127.0.0.1:3000/health
-bun run omochi-utils http --interval 30s --timeout 5s \
-  --expect-status 200 --expect-body '"ready":true' https://example.test/health
-```
-
-`http` sends non-overlapping GET requests and provides the same pause, resume,
-and run-now controls as `watch`. It shows status, latency, final URL, content
-type, size, consecutive failures, and health transitions. The default expected
-status is 200–299. Text responses are shown up to 64 KiB; JSON media types are
-parsed and pretty-printed. Binary response bodies are not displayed. For custom
-methods, headers, authentication, or request bodies, use `watch -- curl ...`.
-
-## Let an agent publish surfaces over MCP
-
-Configure a stdio MCP server in your agent. For a source checkout, point Node to
-the absolute path of the built CLI:
-
-```json
-{
-  "mcpServers": {
-    "omochi": {
-      "command": "bun",
-      "args": ["/absolute/path/to/omochi-ui/packages/utils/bin/omochi-utils.js", "mcp", "--name", "Agent"]
-    }
-  }
-}
-```
-
-The process publishes through `UnixSocketServerTransport`; an existing gateway
-discovers it automatically. Start `omochi-ui hub` separately to view surfaces.
-The agent, gateway and hub must share the same user and `XDG_RUNTIME_DIR` for
-local discovery. Existing SSH/paired-gateway routing works without changes.
-
-| Tool | Arguments | Result |
-| --- | --- | --- |
-| `publish_messages` | `messages`: nonempty A2UI v0.9 message array | `accepted`, `serviceId`, `surfaceIds` |
-| `list_surfaces` | none | `serviceId`, `surfaceIds` |
-| `read_events` | `after` (default 0), `timeoutMs` (default 0, max 30000) | `events`, `nextCursor`, `dropped`, `closed` |
-
-`publish_messages` accepts standard `createSurface`, `updateComponents`,
-`updateDataModel`, and `deleteSurface` messages. It validates the entire batch
-against the current state before sending anything. Errors report the failing
-array index, leaving the published state intact. Concurrent calls are serialized.
-Use surface-local IDs; gateway/hub prefixes are applied by the existing routers.
-Validation checks wire shape and surface lifecycle; catalog-specific component
-validation is still performed by the renderer.
-
-For example, pass this to `publish_messages` to publish an interactive form:
-
-```json
-{
-  "messages": [
-    {
-      "version": "v0.9",
-      "createSurface": {
-        "surfaceId": "main",
-        "catalogId": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json",
-        "sendDataModel": true
-      }
-    },
-    {
-      "version": "v0.9",
-      "updateComponents": {
-        "surfaceId": "main",
-        "components": [
-          { "id": "root", "component": "Column", "children": ["title", "request", "submit"] },
-          { "id": "title", "component": "Text", "text": "What should we build?" },
-          { "id": "request", "component": "TextField", "label": "Request", "value": { "path": "/request" } },
-          { "id": "submit", "component": "Button", "child": "label", "action": { "event": { "name": "submit", "context": { "request": { "path": "/request" } } } } },
-          { "id": "label", "component": "Text", "text": "Send" }
-        ]
-      }
-    },
-    { "version": "v0.9", "updateDataModel": { "surfaceId": "main", "path": "/", "value": { "request": "" } } }
-  ]
-}
-```
-
-Call `read_events` with `{ "after": 0, "timeoutMs": 30000 }`. Each returned event
-contains `sequence`, `receivedAt` (ISO timestamp), and the original A2UI client
-`message`, including `action.context` and any client data model metadata. The
-example's submitted text is in `message.action.context.request`. Respond by
-publishing another message batch:
-
-```json
-{
-  "messages": [{
-    "version": "v0.9",
-    "updateComponents": {
-      "surfaceId": "main",
-      "components": [{ "id": "title", "component": "Text", "text": "Working…" }]
-    }
-  }]
-}
-```
-
-Use the returned `nextCursor` as `after` for the next read. Reads do not consume
-events, so retrying a cursor is safe. The latest 1,000 events are retained;
-`dropped` reports how many events since the requested cursor have expired. A
-timeout returns an empty array. Pending reads support MCP cancellation and are
-woken on shutdown. Button clicks do not automatically wake an idle agent: it
-must call `read_events`. These tools do not execute shell commands or callbacks.
-
-To remove a surface, publish
-`{"version":"v0.9","deleteSurface":{"surfaceId":"main"}}`.
-There is no persistence: stdin EOF, SIGINT or SIGTERM closes the MCP server and
-retracts its service. A gateway connecting later receives current surface state.
-
-## Shared options and lifetime
-
-All subcommands accept `--service-id ID` and `--name NAME`. IDs default to a
-unique `utils-<uuid>`; use an explicit stable ID if saving a dashboard layout.
-Starting a second process with a live ID fails without replacing the first.
-Durations accept `ms`, `s`, and `m` suffixes. Each process has its own surfaces
-and event buffer. Service registration does not start the gateway or
-automatically place panels on a dashboard.
-
-Use `bun run omochi-utils --help` for usage. No new TCP listener, dashboard API,
-or transport protocol is introduced. Runtime directory permissions and existing
-gateway access controls apply to these services as to other Omochi apps.
-
-## Tests
-
-`bun run build` then `bun run --filter @omochi-ui/utils test`
-runs command execution, watch/diff, process restart, tail/stream, HTTP, shutdown,
-event cursor, stdio MCP, and gateway integration tests. Temporary runtime
-directories keep tests separate from real services.
+# Omochi native services
+
+The archive contains omochi-ui and omochi-utils for the target in manifest.json.
+The production dashboard is embedded. Neither binary requires Bun, Node.js,
+Python or Rust at runtime. Applications launched by them need their own runtime.
+
+Verify the archive against its .sha256 file, extract it, and install both binaries:
+
+    ./install.sh                       # $HOME/.local/bin
+    ./install.sh /your/preferred/bin   # optional destination
+    omochi-ui hub
+
+The default dashboard is http://127.0.0.1:5555. Keep this loopback default.
+Use omochi-ui up omochi.toml for compositions, and omochi-utils --help for utility
+modes. dev bridges application stdio to the separate developer preview frontend;
+the Vite developer preview is not included in this archive.
+
+## Pairing
+
+On the gateway machine:
+
+    omochi-ui gateway --remote --pair --name workstation
+
+Import its invitation on the hub PC:
+
+    omochi-ui pair --name workstation
+    # Paste the invitation on stdin, then Ctrl+D.
+    omochi-ui hub
+
+Possession of an invitation grants access. It expires after 180 seconds and admits
+one hub; keep it private. Registered gateways connect automatically without IP
+input. --offline disables public discovery and relays while retaining LAN mDNS
+and direct connections.
+
+Online development uses n0 public discovery and relays. For a project relay, use
+the same --relay https://your-relay.example option on remote gateway, pair and hub
+commands. This archive does not provision a relay. The source repository includes host
+configuration and monitoring templates in deploy/relay.
+
+status reports registered gateway connection attempts and failures from the running
+hub (use --port if the hub has a non-default port). It does not initialize state.
+
+trust list shows peers. trust forget NAME_OR_ENDPOINT_ID waits for live processes
+to destroy revoked connections. An acknowledgement failure remains an error even
+though the trust removal is already durable.
+
+## Breaking upgrade
+
+Stop old gateways/hubs first. SDK APIs and manifests are unchanged; gateway wire
+protocol and NodeIds are new. Pair devices again and recreate saved dashboards.
+Native state lives at $XDG_CONFIG_HOME/omochi/rust-v1 or
+$HOME/.config/omochi/rust-v1. Legacy state is left untouched.
+
+Linux binaries use their build runner's libc; choose an OS/architecture-compatible
+archive and libc, or build from source. This script does not codesign or notarize
+macOS binaries.
+
+## Registry distributions
+
+Native releases also prepare npm `@omochi-ui/cli` and `@omochi-ui/utils` under
+the existing package names, using exact-version platform binary dependencies.
+The npm launcher needs Node.js 22+; the native archives above do not. Published
+Cargo sources can be installed with `cargo install omochi-cli --locked` and
+`cargo install omochi-utils --locked`. The existing `omochi-ui` crate remains the SDK.
+See docs/native-releasing.md in the repository for release setup and migration.

package/bin/omochi-utils.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const manifest = require('../package.json');
+const platform = `${process.platform}-${process.arch}`;
+const dependency = manifest.nativePlatforms[platform];
+function fail(message) { console.error(`[${manifest.name}] ${message}`); process.exit(1); }
+if (!dependency) fail(`Unsupported platform ${platform}. Use a supported Linux/glibc or macOS build.`);
+if (process.platform === 'linux' && !process.report?.getReport().header.glibcVersionRuntime) {
+  fail('The prebuilt Linux binary requires glibc. On musl, build with cargo install instead.');
+}
+let binary;
+try {
+  const installed = require.resolve(`${dependency}/package.json`);
+  const native = require(installed);
+  if (native.version !== manifest.version) fail(`Binary version mismatch: expected ${manifest.version}, found ${native.version}. Reinstall the package.`);
+  binary = path.join(path.dirname(installed), 'bin', manifest.nativeBinary);
+} catch {
+  fail(`Missing ${dependency}@${manifest.version}. Reinstall with optional dependencies enabled (npm install --include=optional).`);
+}
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+const handlers = new Map();
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  const handler = () => child.kill(signal);
+  handlers.set(signal, handler);
+  process.on(signal, handler);
+}
+child.once('error', error => fail(`Cannot start ${binary}: ${error.message}`));
+child.once('exit', (code, signal) => {
+  for (const [name, handler] of handlers) process.removeListener(name, handler);
+  if (signal) process.kill(process.pid, signal);
+  else process.exitCode = code ?? 1;
+});

package/package.json

@@ -1,37 +1,35 @@
 {
   "name": "@omochi-ui/utils",
-  "version": "0.1.2",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
+  "version": "0.2.0",
+  "description": "Native Omochi utils",
+  "files": [
+    "bin"
+  ],
   "engines": {
-    "bun": ">=1.4.3"
+    "node": ">=22"
   },
-  "description": "Publish development utilities and agent-created A2UI surfaces to Omochi",
-  "license": "Apache-2.0",
-  "type": "module",
   "bin": {
-    "omochi-utils": "./bin/omochi-utils.js"
+    "omochi-utils": "./bin/omochi-utils.cjs"
   },
-  "files": [
-    "bin",
-    "dist"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.31.0",
-    "diff": "^9.0.0",
-    "@omochi-ui/core": "0.1.2",
-    "@omochi-ui/sdk": "0.1.2",
-    "zod": "^4.0.0"
+  "nativeBinary": "omochi-utils",
+  "nativePlatforms": {
+    "linux-x64": "@omochi-ui/native-linux-x64",
+    "linux-arm64": "@omochi-ui/native-linux-arm64",
+    "darwin-x64": "@omochi-ui/native-darwin-x64",
+    "darwin-arm64": "@omochi-ui/native-darwin-arm64"
+  },
+  "optionalDependencies": {
+    "@omochi-ui/native-linux-x64": "0.2.0",
+    "@omochi-ui/native-linux-arm64": "0.2.0",
+    "@omochi-ui/native-darwin-x64": "0.2.0",
+    "@omochi-ui/native-darwin-arm64": "0.2.0"
   },
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/omochi-ui/omochi.git",
-    "directory": "packages/utils"
+    "url": "https://github.com/omochi-ui/omochi.git"
   },
-  "homepage": "https://github.com/omochi-ui/omochi#readme",
-  "bugs": {
-    "url": "https://github.com/omochi-ui/omochi/issues"
+  "publishConfig": {
+    "access": "public"
   }
 }

package/bin/omochi-utils.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env bun
-import '../dist/cli.js';

package/dist/button.d.ts

@@ -1,20 +0,0 @@
-import { type UI } from "@omochi-ui/sdk";
-import { Publisher } from "./publisher.js";
-import { UtilitySurface } from "./surface.js";
-export interface ButtonOptions {
-    command: string[];
-    cwd?: string;
-    name: string;
-}
-export declare class CommandButton extends UtilitySurface {
-    private readonly output;
-    private readonly runner;
-    private running;
-    private status;
-    private closePromise?;
-    constructor(publisher: Publisher, options: ButtonOptions);
-    protected build(ui: UI): void;
-    protected onAction(name: string): void;
-    close(): Promise<void>;
-    private run;
-}

package/dist/button.js

@@ -1,51 +0,0 @@
-import { Action } from "@omochi-ui/sdk";
-import { ManagedCommand, describeResult } from "./command.js";
-import { OutputBuffer, fenced } from "./output.js";
-import { UtilitySurface } from "./surface.js";
-export class CommandButton extends UtilitySurface {
-    output = new OutputBuffer();
-    runner;
-    running = false;
-    status = "Ready";
-    closePromise;
-    constructor(publisher, options) {
-        super(publisher, options.name);
-        this.runner = new ManagedCommand({
-            command: options.command,
-            cwd: options.cwd,
-            onData: (chunk) => {
-                this.output.append(chunk);
-                this.scheduleRender();
-            },
-        });
-    }
-    build(ui) {
-        ui.text(this.name, { key: "title", variant: "h3" });
-        if (!this.running)
-            ui.button("Run", new Action("run").call(null), { key: "run", variant: "primary" });
-        ui.text(this.status, { key: "status" });
-        ui.text(fenced(this.output.text, this.output.truncated), { key: "output" });
-    }
-    onAction(name) {
-        if (name !== "run" || this.running || this.closing)
-            return;
-        void this.run();
-    }
-    close() {
-        if (this.closePromise)
-            return this.closePromise;
-        this.closeSurface();
-        this.closePromise = this.runner.close();
-        return this.closePromise;
-    }
-    async run() {
-        this.running = true;
-        this.output.reset();
-        this.status = "Running…";
-        this.scheduleRender();
-        const result = await this.runner.start();
-        this.running = false;
-        this.status = describeResult(result);
-        this.scheduleRender();
-    }
-}

package/dist/cli.d.ts

@@ -1 +0,0 @@
-export {};