@poping/yome 0.0.3 → 0.0.5

package/dist/mesh/thread-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-stream.js","sourceRoot":"","sources":["../../src/mesh/thread-stream.ts"],"names":[],"mappings":"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"}

package/dist/mesh/ticket.d.ts

@@ -0,0 +1,33 @@
+import type { WsTicketResponse } from './types.js';
+export declare class MintTicketError extends Error {
+    code: string;
+    httpStatus?: number | undefined;
+    constructor(message: string, code: string, httpStatus?: number | undefined);
+}
+/**
+ * Request a fresh WS ticket. The caller is responsible for caching
+ * (TicketCache below). Throws MintTicketError on any failure.
+ */
+export declare function mintWsTicket(opts?: {
+    hubBase?: string;
+    fetcher?: typeof fetch;
+    cliVersion?: string;
+}): Promise<WsTicketResponse>;
+/**
+ * Tiny in-memory cache that proactively refreshes the ticket before it
+ * expires. Owned by the long-running mesh daemon process. NOT persisted
+ * to disk — short-lived JWTs are deliberately ephemeral.
+ *
+ * Refresh strategy: re-mint when ≤ 60s remains. PartyKit only checks
+ * the JWT at WS handshake time (not per message), so we don't strictly
+ * need to refresh during a live connection — but we cache for reconnects.
+ */
+export declare class TicketCache {
+    private mintFn;
+    private current;
+    private expiresAtMs;
+    private inflight;
+    constructor(mintFn?: () => Promise<WsTicketResponse>);
+    get(): Promise<WsTicketResponse>;
+    invalidate(): void;
+}

package/dist/mesh/ticket.js

@@ -0,0 +1,127 @@
+// PAT → short-lived WS ticket exchange.
+//
+// We hold a long-lived opaque `yome_token` (from `yome login`) on disk
+// and use it to mint short-lived JWTs that PartyKit can verify with the
+// existing Supabase-JWT HS256 path. This is the same pattern GitHub
+// CLI / Vercel CLI / Supabase CLI use: never put a service-grade JWT
+// or refresh_token on disk; only ever hold a revocable PAT.
+//
+// See cli/MIGRATION.md "Auth design" for the full rationale.
+import { readAuthState } from '../yomeSkills/auth.js';
+import { getHubBase } from '../yomeSkills/login.js';
+import { getOrCreateDeviceId, safeHostname, currentPlatform } from './device-id.js';
+const TICKET_ENDPOINT_PATH = '/api/cli/mesh/ws-ticket';
+/** Stable User-Agent for hub logs. */
+function userAgent() {
+    // Bumping is fine; this is a label, not a contract.
+    return `yome-cli/0.x mesh/1 ${currentPlatform()}`;
+}
+export class MintTicketError extends Error {
+    code;
+    httpStatus;
+    constructor(message, code, httpStatus) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.name = 'MintTicketError';
+    }
+}
+/**
+ * Request a fresh WS ticket. The caller is responsible for caching
+ * (TicketCache below). Throws MintTicketError on any failure.
+ */
+export async function mintWsTicket(opts = {}) {
+    const auth = readAuthState();
+    if (!auth?.yome_token) {
+        throw new MintTicketError('Not logged in. Run `yome login` first.', 'not_logged_in');
+    }
+    const hubBase = (opts.hubBase ?? getHubBase()).replace(/\/+$/, '');
+    const fetcher = opts.fetcher ?? fetch;
+    const body = {
+        deviceId: getOrCreateDeviceId(),
+        hostname: safeHostname(),
+        platform: currentPlatform(),
+        cliVersion: opts.cliVersion,
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 30_000);
+    let resp;
+    try {
+        resp = await fetcher(`${hubBase}${TICKET_ENDPOINT_PATH}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${auth.yome_token}`,
+                'User-Agent': userAgent(),
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new MintTicketError(`Network error contacting hub: ${err.message}`, 'network');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let json;
+    try {
+        json = await resp.json();
+    }
+    catch {
+        throw new MintTicketError(`Hub returned non-JSON (HTTP ${resp.status}).`, 'bad_response', resp.status);
+    }
+    if (!resp.ok || !json.ok) {
+        const e = json;
+        throw new MintTicketError(e.error ?? `Hub rejected ticket request (HTTP ${resp.status}).`, e.code ?? 'hub_error', resp.status);
+    }
+    const ok = json;
+    if (!ok.ws_token || !ok.userId || !ok.partykit_host) {
+        throw new MintTicketError('Hub response missing required fields (ws_token / userId / partykit_host).', 'bad_response', resp.status);
+    }
+    return ok;
+}
+/**
+ * Tiny in-memory cache that proactively refreshes the ticket before it
+ * expires. Owned by the long-running mesh daemon process. NOT persisted
+ * to disk — short-lived JWTs are deliberately ephemeral.
+ *
+ * Refresh strategy: re-mint when ≤ 60s remains. PartyKit only checks
+ * the JWT at WS handshake time (not per message), so we don't strictly
+ * need to refresh during a live connection — but we cache for reconnects.
+ */
+export class TicketCache {
+    mintFn;
+    current = null;
+    expiresAtMs = 0;
+    inflight = null;
+    constructor(mintFn = mintWsTicket) {
+        this.mintFn = mintFn;
+    }
+    async get() {
+        const now = Date.now();
+        const safetyWindowMs = 60_000;
+        if (this.current && now < this.expiresAtMs - safetyWindowMs) {
+            return this.current;
+        }
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = (async () => {
+            const fresh = await this.mintFn();
+            this.current = fresh;
+            this.expiresAtMs = Date.now() + fresh.expires_in * 1000;
+            return fresh;
+        })();
+        try {
+            return await this.inflight;
+        }
+        finally {
+            this.inflight = null;
+        }
+    }
+    invalidate() {
+        this.current = null;
+        this.expiresAtMs = 0;
+    }
+}
+//# sourceMappingURL=ticket.js.map

package/dist/mesh/ticket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket.js","sourceRoot":"","sources":["../../src/mesh/ticket.ts"],"names":[],"mappings":"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"}

package/dist/mesh/types.d.ts

@@ -0,0 +1,83 @@
+export type CommandDomain = 'bash' | 'fs' | 'git' | 'docker' | 'k8s' | 'systemd' | 'pkg' | 'log' | 'net' | 'svc' | 'cal' | 'rem' | 'note' | 'xl' | 'ppt' | 'doc' | 'kn' | 'num' | 'pg' | 'web' | 'mind' | 'term' | 'lark' | 'ps' | 'sp' | 'notif' | 'chat' | 'app' | 'cur' | 'cap' | 'wf' | 'watch';
+export interface WsDeviceRegister {
+    type: 'mesh:register';
+    hostname: string;
+    model: string;
+    capabilities: string[];
+    installedApps: string[];
+    alias?: string;
+    deviceDescription?: string;
+}
+export interface WsDeviceUpdate {
+    type: 'mesh:update-device';
+    deviceId?: string;
+    alias?: string;
+    deviceDescription?: string;
+}
+export interface WsHeartbeat {
+    type: 'mesh:heartbeat';
+    deviceId: string;
+}
+export interface WsRpcResponse {
+    type: 'rpc:cal-response';
+    requestId: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export type WsClientFrame = WsDeviceRegister | WsDeviceUpdate | WsHeartbeat | WsRpcResponse;
+export interface WsConnected {
+    type: 'connected';
+    clientType: 'ios' | 'mac' | 'web' | 'desktop';
+    userId: string;
+}
+export interface WsRpcRequest {
+    type: 'rpc:cal-request';
+    requestId: string;
+    command: string;
+    parsed: {
+        domain: CommandDomain;
+        action: string;
+        args: Record<string, string>;
+    };
+}
+export interface WsDeviceUpdated {
+    type: 'device-updated';
+    devices: Array<{
+        deviceId: string;
+        userId: string;
+        hostname: string;
+        model: string;
+        status: 'online' | 'busy' | 'offline';
+        capabilities: string[];
+        installedApps: string[];
+        currentTask?: string;
+        lastHeartbeat: number;
+        alias?: string;
+        deviceDescription?: string;
+    }>;
+}
+export type WsServerFrame = WsConnected | WsRpcRequest | WsDeviceUpdated | {
+    type: string;
+    [k: string]: unknown;
+};
+export interface WsTicketRequest {
+    deviceId: string;
+    hostname: string;
+    platform: 'linux' | 'darwin' | 'win32' | string;
+    /** Optional cli version string for hub-side analytics. */
+    cliVersion?: string;
+}
+export interface WsTicketResponse {
+    ok: boolean;
+    /** Short-lived JWT (HS256 by Supabase JWT secret), sub=userId, aud=partykit. */
+    ws_token: string;
+    /** Seconds until ws_token expires. */
+    expires_in: number;
+    userId: string;
+    deviceId: string;
+    /** Host + room hint. e.g. "yome.party.yome.work". Room id is userId. */
+    partykit_host: string;
+    error?: string;
+    code?: string;
+}

package/dist/mesh/types.js

@@ -0,0 +1,9 @@
+// Mesh wire-protocol types.
+//
+// Mirror of the relevant subset of `Server/agent/types.ts` so that
+// cli ↔ PartyKit speak the same JSON frames as iOS / macOS already do.
+// Kept manually-maintained (not generated) because cli is a separate npm
+// package and we want this protocol surface to be stable + reviewable as
+// part of the cli PR.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mesh/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mesh/types.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,EAAE;AACF,mEAAmE;AACnE,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,sBAAsB"}

package/dist/skills/runner/dispatcher.d.ts

@@ -29,18 +29,79 @@ export interface DispatchResult {
     stderr: string;
     exitCode: number;
 }
+export declare const NAMED_COLORS: Record<string, [number, number, number]>;
+export interface ColorParseFailure {
+    input: string;
+    reason: string;
+}
+/**
+ * Parse a color spec into an AppleScript RGB literal `{r, g, b}`.
+ *
+ * Accepted forms (case- and whitespace-insensitive):
+ *   • `#RRGGBB` or bare `RRGGBB`
+ *   • `R,G,B`  with each channel in 0..255
+ *   • Named color from NAMED_COLORS (CSS-ish + CN aliases)
+ *
+ * Returns `{ ok: true, literal }` on success, or `{ ok: false, error }` with
+ * a precise reason on failure. Callers MUST surface the error rather than
+ * silently emitting an empty literal — silent fallbacks were the root cause
+ * of the historical "bg disappeared from the format result" class of bugs.
+ */
+export type ColorParseResult = {
+    ok: true;
+    literal: string;
+    rgb: [number, number, number];
+} | {
+    ok: false;
+    error: ColorParseFailure;
+};
+export declare function parseColor(input: string): ColorParseResult;
 /**
- * Parse `red` | `#003366` | `003366` | `0, 51, 102` into an AppleScript
- * RGB literal `{r, g, b}`. Returns null if the input doesn't match any of
- * those three forms — callers should treat null as "user gave a bad color".
+ * Back-compat wrapper that returns the literal or null. New code should use
+ * `parseColor()` so the failure reason can be surfaced to the user.
  */
 export declare function parseColorToAppleScriptRGB(input: string): string | null;
+/**
+ * `--type` alias → AppleScript `MsoAutoShapeType` enum literal. Unknown
+ * aliases degrade to `autoshape rectangle` so the template never emits
+ * broken AppleScript.
+ */
+export declare function parseAutoshapeToAppleScript(input: string): string;
 /**
  * `--align` parser → AppleScript `paragraph align ...` enum.
  * Defaults silently to `paragraph align left` for unknown values; that
  * matches the Swift bridge behaviour and avoids breaking the script render.
  */
 export declare function parseAlignToAppleScript(input: string): string;
+export interface RenderError {
+    arg: string;
+    filter?: string;
+    reason: string;
+}
+export interface RenderResult {
+    source: string;
+    errors: RenderError[];
+}
+/**
+ * Render an AppleScript template.
+ *
+ * Two failure modes exist:
+ *  - "soft": the filter accepts any input and just renders something
+ *    (`json`, `posix`, `bool`, `as_int`, `align`, `autoshape`). These never
+ *    populate `errors`.
+ *  - "hard": the filter validates input and can reject it (`rgb`). When
+ *    rejected we emit a syntactically VALID placeholder (`missing value`)
+ *    so the rendered AppleScript still parses, AND we record the error
+ *    in `errors[]`. The dispatcher checks `errors` BEFORE running osascript
+ *    and refuses to run with a structured message — no more silent failure
+ *    where `bg=深蓝` quietly emitted broken AppleScript.
+ *
+ * `{{name}}` / `{{name|filter}}` is the substitution syntax.
+ * `{{#if name}}…{{/if}}` is the conditional block (greedy, not nestable).
+ * Substitution happens AFTER conditionals, so a `{{#if bg}}…{{bg|rgb}}…{{/if}}`
+ * block whose `bg` was stripped never reaches the filter.
+ */
+export declare function renderTemplate(tpl: string, ctx: Record<string, string | boolean | number | null>): RenderResult;
 export declare function loadMacosBackend(skillDir: string): MacosBackendManifest | null;
 /**
  * Run an action on a macOS-backed skill. Returns the osascript outcome
@@ -55,3 +116,13 @@ export interface MergedBatchOptions {
     keepGoing: boolean;
 }
 export declare function dispatchMacosBatchMerged(skillDir: string, entries: MergedBatchEntry[], opts: MergedBatchOptions): Promise<DispatchResult>;
+/**
+ * Demux the "<okList>|<failList>" convention used by partial-success-aware
+ * AppleScript templates (xl/ppt/doc `fmt`, `cf`, …). Returns null when the
+ * payload doesn't look like that shape — callers should treat null as
+ * "ordinary opaque message, leave it alone".
+ */
+export declare function parsePartialOkFail(msg: string): {
+    ok: string;
+    fail: string;
+} | null;