@omochi-ui/utils 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,239 @@
+import path from "node:path";
+import { CommandButton } from "./button.js";
+import { HttpWatch } from "./http.js";
+import { CommandProcess } from "./process.js";
+import { Publisher } from "./publisher.js";
+import { InputStream } from "./stream.js";
+import { FileTail } from "./tail.js";
+import { CommandWatch } from "./watch.js";
+const HELP = `Usage:
+  omochi-utils button [--service-id ID] [--name NAME] [--cwd DIR] -- COMMAND [ARGS...]
+  omochi-utils watch [--interval 2s] [--timeout DURATION] [--diff] [--on-change] [--history N] [--cwd DIR] -- COMMAND [ARGS...]
+  omochi-utils process [--restart never|on-failure|always] [--restart-delay 1s] [--cwd DIR] -- COMMAND [ARGS...]
+  omochi-utils tail [--lines 100] [--service-id ID] [--name NAME] FILE
+  omochi-utils stream [--service-id ID] [--name NAME]
+  omochi-utils http [--interval 10s] [--timeout 10s] [--expect-status 200-299] [--expect-body TEXT] URL
+  omochi-utils mcp [--service-id ID] [--name NAME]
+
+Publish one development utility surface through the local Omochi gateway.
+Commands inherit the environment and run without an implicit shell.
+Durations accept ms, s, or m suffixes. Start omochi-ui hub separately.
+`;
+function parse(args) {
+    if (!args.length || ["--help", "-h", "help"].includes(args[0]))
+        return null;
+    const mode = args[0];
+    const rest = args.slice(1);
+    if (!["button", "watch", "process", "tail", "stream", "http", "mcp"].includes(mode))
+        throw new Error(`unknown command: ${mode}`);
+    if (rest.includes("--help") || rest.includes("-h"))
+        return null;
+    const common = { name: defaultName(mode) };
+    let cwd;
+    let intervalMs = mode === "http" ? 10_000 : 2_000;
+    let timeoutMs = mode === "http" ? 10_000 : undefined;
+    let diff = false;
+    let onChange = false;
+    let history;
+    let restart = "never";
+    let restartDelayMs = 1000;
+    let lines = 100;
+    let expectStatus = [200, 299];
+    let expectBody;
+    const positional = [];
+    let command = [];
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--") {
+            command = rest.slice(i + 1);
+            break;
+        }
+        const value = () => {
+            const found = rest[++i];
+            if (found === undefined)
+                throw new Error(`missing value for ${arg}`);
+            return found;
+        };
+        if (arg === "--service-id")
+            common.serviceId = value();
+        else if (arg === "--name")
+            common.name = value();
+        else if (arg === "--cwd" && ["button", "watch", "process"].includes(mode))
+            cwd = path.resolve(value());
+        else if (arg === "--interval" && ["watch", "http"].includes(mode))
+            intervalMs = parseDuration(value(), arg);
+        else if (arg === "--timeout" && ["watch", "http"].includes(mode))
+            timeoutMs = parseDuration(value(), arg);
+        else if (arg === "--diff" && mode === "watch")
+            diff = true;
+        else if (arg === "--on-change" && mode === "watch")
+            onChange = true;
+        else if (arg === "--history" && mode === "watch")
+            history = parseInteger(value(), arg, 1, 100);
+        else if (arg === "--restart" && mode === "process") {
+            const policy = value();
+            if (!["never", "on-failure", "always"].includes(policy))
+                throw new Error("--restart must be never, on-failure, or always");
+            restart = policy;
+        }
+        else if (arg === "--restart-delay" && mode === "process")
+            restartDelayMs = parseDuration(value(), arg);
+        else if (arg === "--lines" && mode === "tail")
+            lines = parseInteger(value(), arg, 1, Number.MAX_SAFE_INTEGER);
+        else if (arg === "--expect-status" && mode === "http")
+            expectStatus = parseStatus(value());
+        else if (arg === "--expect-body" && mode === "http")
+            expectBody = value();
+        else if (arg.startsWith("-"))
+            throw new Error(`unknown option: ${arg}`);
+        else
+            positional.push(arg);
+    }
+    if (["button", "watch", "process"].includes(mode)) {
+        if (!command.length)
+            throw new Error(`${mode} requires -- followed by a command`);
+        if (positional.length)
+            throw new Error(`unexpected argument: ${positional[0]}`);
+    }
+    else if (command.length || rest.includes("--"))
+        throw new Error(`${mode} does not accept a command after --`);
+    if (mode === "button")
+        return { ...common, mode, cwd, command };
+    if (mode === "watch")
+        return { ...common, mode, cwd, command, intervalMs, timeoutMs, diff, onChange, history };
+    if (mode === "process")
+        return { ...common, mode, cwd, command, restart, restartDelayMs };
+    if (mode === "tail") {
+        if (positional.length !== 1)
+            throw new Error("tail requires exactly one file path");
+        const filePath = path.resolve(positional[0]);
+        if (common.name === "Tail")
+            common.name = path.basename(filePath);
+        return { ...common, mode, path: filePath, lines };
+    }
+    if (mode === "stream") {
+        if (positional.length)
+            throw new Error(`unexpected argument: ${positional[0]}`);
+        return { ...common, mode };
+    }
+    if (mode === "http") {
+        if (positional.length !== 1)
+            throw new Error("http requires exactly one URL");
+        const url = new URL(positional[0]);
+        if (!["http:", "https:"].includes(url.protocol))
+            throw new Error("http URL must use http or https");
+        if (common.name === "HTTP")
+            common.name = url.host;
+        return { ...common, mode, url: url.toString(), intervalMs, timeoutMs: timeoutMs, expectStatus, expectBody };
+    }
+    if (positional.length)
+        throw new Error(`unexpected argument: ${positional[0]}`);
+    return { ...common, mode: "mcp" };
+}
+function defaultName(mode) {
+    return { button: "Command", watch: "Watch", process: "Process", tail: "Tail", stream: "Stream", http: "HTTP", mcp: "Agent" }[mode];
+}
+function parseDuration(value, option) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(value);
+    if (!match)
+        throw new Error(`${option} must be a positive duration such as 250ms, 2s, or 1m`);
+    const multiplier = match[2] === "ms" ? 1 : match[2] === "s" ? 1000 : 60_000;
+    const milliseconds = Number(match[1]) * multiplier;
+    if (!Number.isFinite(milliseconds) || milliseconds <= 0 || milliseconds > 2_147_483_647)
+        throw new Error(`${option} is out of range`);
+    const rounded = Math.round(milliseconds);
+    if (rounded <= 0)
+        throw new Error(`${option} is out of range`);
+    return rounded;
+}
+function parseInteger(value, option, minimum, maximum) {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number) || number < minimum || number > maximum)
+        throw new Error(`${option} must be an integer between ${minimum} and ${maximum}`);
+    return number;
+}
+function parseStatus(value) {
+    const match = /^(\d{3})(?:-(\d{3}))?$/.exec(value);
+    if (!match)
+        throw new Error("--expect-status must be a status code or range such as 200-299");
+    const minimum = Number(match[1]);
+    const maximum = Number(match[2] ?? match[1]);
+    if (minimum < 100 || maximum > 599 || minimum > maximum)
+        throw new Error("--expect-status must be an ordered range between 100 and 599");
+    return [minimum, maximum];
+}
+async function main() {
+    let options;
+    try {
+        options = parse(process.argv.slice(2));
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (!options) {
+        process.stdout.write(HELP);
+        return;
+    }
+    let publisher;
+    let utility;
+    let mcp;
+    let shutdown;
+    let stopped = false;
+    const close = () => {
+        stopped = true;
+        if (shutdown)
+            return shutdown;
+        shutdown = (async () => {
+            publisher?.events.close();
+            await utility?.close();
+            await publisher?.close();
+            await mcp?.close();
+        })();
+        return shutdown;
+    };
+    const stop = () => { void close().catch(reportError); };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+        publisher = await Publisher.open({ serviceId: options.serviceId, name: options.name });
+        if (stopped) {
+            await publisher.close();
+            return;
+        }
+        if (options.mode === "mcp") {
+            const { startMcp } = await import("./mcp.js");
+            process.stdin.once("end", stop);
+            mcp = await startMcp(publisher, stop);
+            if (stopped)
+                await mcp.close();
+        }
+        else {
+            if (options.mode === "button")
+                utility = new CommandButton(publisher, options);
+            if (options.mode === "watch")
+                utility = new CommandWatch(publisher, options);
+            if (options.mode === "process")
+                utility = new CommandProcess(publisher, options);
+            if (options.mode === "tail")
+                utility = new FileTail(publisher, options);
+            if (options.mode === "stream")
+                utility = new InputStream(publisher, options);
+            if (options.mode === "http")
+                utility = new HttpWatch(publisher, options);
+            await utility.start();
+        }
+        if (!stopped)
+            process.stderr.write(`Published service ${publisher.serviceId} (${options.name})\n`);
+    }
+    catch (error) {
+        reportError(error);
+        await close();
+    }
+}
+function reportError(error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}
+void main().catch(reportError);

package/dist/command.d.ts

@@ -0,0 +1,28 @@
+export interface CommandOptions {
+    command: string[];
+    cwd?: string;
+    onData?: (chunk: string) => void;
+}
+export interface CommandResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error;
+    timedOut: boolean;
+    durationMs: number;
+}
+export declare class ManagedCommand {
+    private readonly options;
+    private child?;
+    private readonly processGroups;
+    private running?;
+    private termination?;
+    private timedOut;
+    private timeout?;
+    constructor(options: CommandOptions);
+    get active(): boolean;
+    start(timeoutMs?: number): Promise<CommandResult>;
+    stop(): Promise<void>;
+    close(): Promise<void>;
+    private signalGroups;
+}
+export declare function describeResult(result: CommandResult): string;

package/dist/command.js

@@ -0,0 +1,110 @@
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+export class ManagedCommand {
+    options;
+    child;
+    processGroups = new Set();
+    running;
+    termination;
+    timedOut = false;
+    timeout;
+    constructor(options) {
+        this.options = options;
+        if (!options.command.length)
+            throw new Error("a command is required after --");
+    }
+    get active() { return this.running !== undefined; }
+    start(timeoutMs) {
+        if (this.running)
+            throw new Error("command is already running");
+        this.timedOut = false;
+        this.termination = undefined;
+        const [command, ...args] = this.options.command;
+        const startedAt = performance.now();
+        const child = spawn(command, args, {
+            cwd: this.options.cwd,
+            env: process.env,
+            shell: false,
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        this.child = child;
+        if (child.pid !== undefined)
+            this.processGroups.add(child.pid);
+        let spawnError;
+        child.once("error", (error) => { spawnError = error; });
+        for (const stream of [child.stdout, child.stderr]) {
+            stream.setEncoding("utf8");
+            stream.on("data", (chunk) => this.options.onData?.(chunk));
+        }
+        this.running = new Promise((resolve) => {
+            child.once("close", (code, signal) => {
+                clearTimeout(this.timeout);
+                if (child.pid !== undefined) {
+                    try {
+                        process.kill(-child.pid, 0);
+                    }
+                    catch (error) {
+                        if (error.code === "ESRCH")
+                            this.processGroups.delete(child.pid);
+                    }
+                }
+                const result = { code, signal, error: spawnError, timedOut: this.timedOut, durationMs: performance.now() - startedAt };
+                this.child = undefined;
+                this.running = undefined;
+                resolve(result);
+            });
+        });
+        if (timeoutMs !== undefined) {
+            this.timeout = setTimeout(() => {
+                this.timedOut = true;
+                void this.stop();
+            }, timeoutMs);
+        }
+        return this.running;
+    }
+    stop() {
+        if (!this.running && !this.processGroups.size)
+            return Promise.resolve();
+        if (this.termination)
+            return this.termination;
+        const running = this.running;
+        this.termination = (async () => {
+            this.signalGroups("SIGTERM");
+            if (running)
+                await Promise.race([running, delay(1000)]);
+            else
+                await delay(1000);
+            this.signalGroups("SIGKILL");
+            if (running)
+                await running;
+        })();
+        return this.termination;
+    }
+    close() {
+        clearTimeout(this.timeout);
+        return this.stop();
+    }
+    signalGroups(signal) {
+        for (const group of this.processGroups) {
+            try {
+                process.kill(-group, signal);
+            }
+            catch (error) {
+                if (error.code === "ESRCH")
+                    this.processGroups.delete(group);
+                else
+                    this.child?.kill(signal);
+            }
+        }
+    }
+}
+export function describeResult(result) {
+    if (result.error)
+        return `Failed to start: ${result.error.message}`;
+    if (result.timedOut)
+        return "Timed out";
+    if (result.signal)
+        return `Stopped by ${result.signal}`;
+    return `Exited with code ${result.code}`;
+}

package/dist/events.d.ts

@@ -0,0 +1,23 @@
+import type { JsonObject } from "@omochi-ui/sdk";
+export interface SurfaceEvent {
+    sequence: number;
+    receivedAt: string;
+    message: JsonObject;
+}
+/** A cursor is a sequence number, not an acknowledgement: reads are repeatable. */
+export declare class EventBuffer {
+    private readonly capacity;
+    private readonly events;
+    private readonly waiters;
+    private sequence;
+    private closed;
+    constructor(capacity?: number);
+    push(message: JsonObject): void;
+    read(after?: number, timeoutMs?: number, signal?: AbortSignal): Promise<{
+        events: SurfaceEvent[];
+        nextCursor: number;
+        dropped: number;
+        closed: boolean;
+    }>;
+    close(): void;
+}

package/dist/events.js

@@ -0,0 +1,54 @@
+/** A cursor is a sequence number, not an acknowledgement: reads are repeatable. */
+export class EventBuffer {
+    capacity;
+    events = [];
+    waiters = new Set();
+    sequence = 0;
+    closed = false;
+    constructor(capacity = 1000) {
+        this.capacity = capacity;
+    }
+    push(message) {
+        if (this.closed)
+            return;
+        this.events.push({ sequence: ++this.sequence, receivedAt: new Date().toISOString(), message: structuredClone(message) });
+        if (this.events.length > this.capacity)
+            this.events.shift();
+        for (const wake of this.waiters)
+            wake();
+    }
+    async read(after = 0, timeoutMs = 0, signal) {
+        if (!Number.isSafeInteger(after) || after < 0 || after > this.sequence)
+            throw new Error("after must be an existing cursor (or 0)");
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 30_000)
+            throw new Error("timeoutMs must be between 0 and 30000");
+        signal?.throwIfAborted();
+        if (!this.closed && this.sequence === after && timeoutMs > 0) {
+            await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    this.waiters.delete(wake);
+                    signal?.removeEventListener("abort", abort);
+                };
+                const wake = () => { cleanup(); resolve(); };
+                const abort = () => { cleanup(); reject(signal?.reason ?? new Error("cancelled")); };
+                const timer = setTimeout(wake, timeoutMs);
+                this.waiters.add(wake);
+                signal?.addEventListener("abort", abort, { once: true });
+            });
+        }
+        signal?.throwIfAborted();
+        const oldest = this.events[0]?.sequence ?? this.sequence + 1;
+        return {
+            events: structuredClone(this.events.filter((event) => event.sequence > after)),
+            nextCursor: this.sequence,
+            dropped: Math.max(0, oldest - after - 1),
+            closed: this.closed,
+        };
+    }
+    close() {
+        this.closed = true;
+        for (const wake of this.waiters)
+            wake();
+    }
+}

package/dist/http-body.d.ts

@@ -0,0 +1,16 @@
+/** Internal streaming matcher; retains only the overlap needed by the next chunk. */
+export declare class BodyMatcher {
+    private readonly expected?;
+    private readonly decoder;
+    private matchTail;
+    matched: boolean;
+    constructor(expected?: string | undefined);
+    write(value: Uint8Array): void;
+    finish(): void;
+    private match;
+}
+export declare function readText(response: Response, limit: number, expected?: string): Promise<{
+    text: string;
+    truncated: boolean;
+    expectedMatched: boolean;
+}>;

package/dist/http-body.js

@@ -0,0 +1,59 @@
+import { StringDecoder } from "node:string_decoder";
+/** Internal streaming matcher; retains only the overlap needed by the next chunk. */
+export class BodyMatcher {
+    expected;
+    decoder = new TextDecoder();
+    matchTail = "";
+    matched;
+    constructor(expected) {
+        this.expected = expected;
+        this.matched = expected === undefined || expected === "";
+    }
+    write(value) {
+        if (!this.matched)
+            this.match(this.decoder.decode(value, { stream: true }));
+    }
+    finish() {
+        if (!this.matched)
+            this.match(this.decoder.decode());
+    }
+    match(decoded) {
+        const expected = this.expected;
+        const searchable = this.matchTail + decoded;
+        this.matched = searchable.includes(expected);
+        this.matchTail = !this.matched && expected.length > 1 ? searchable.slice(-(expected.length - 1)) : "";
+    }
+}
+export async function readText(response, limit, expected) {
+    if (!response.body)
+        return { text: "", truncated: false, expectedMatched: expected === undefined || expected === "" };
+    const reader = response.body.getReader();
+    const chunks = [];
+    const matcher = new BodyMatcher(expected);
+    let visibleLength = 0;
+    let totalLength = 0;
+    let truncated = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            matcher.finish();
+            break;
+        }
+        totalLength += value.length;
+        if (visibleLength < limit) {
+            const visible = value.subarray(0, Math.min(value.length, limit - visibleLength));
+            chunks.push(visible);
+            visibleLength += visible.length;
+        }
+        matcher.write(value);
+        if (totalLength > limit) {
+            truncated = true;
+            if (expected === undefined || matcher.matched) {
+                await reader.cancel();
+                break;
+            }
+        }
+    }
+    const visible = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), visibleLength);
+    return { text: new StringDecoder("utf8").write(visible), truncated, expectedMatched: matcher.matched };
+}

package/dist/http.d.ts

@@ -0,0 +1,32 @@
+import { type UI } from "@omochi-ui/sdk";
+import { Publisher } from "./publisher.js";
+import { UtilitySurface } from "./surface.js";
+export interface HttpOptions {
+    url: string;
+    name: string;
+    intervalMs: number;
+    timeoutMs: number;
+    expectStatus: readonly [number, number];
+    expectBody?: string;
+    fetch?: typeof fetch;
+}
+export declare class HttpWatch extends UtilitySurface {
+    private readonly options;
+    private readonly fetcher;
+    private readonly body;
+    private interval?;
+    private controller?;
+    private running;
+    private paused;
+    private status;
+    private metadata;
+    private consecutiveFailures;
+    private lastHealthy?;
+    private transition;
+    constructor(publisher: Publisher, options: HttpOptions);
+    start(): Promise<void>;
+    protected build(ui: UI): void;
+    protected onAction(name: string): void;
+    close(): Promise<void>;
+    private run;
+}