@garretapp/sdk 0.1.0

package/dist/host.js

@@ -0,0 +1,246 @@
+import { GarretError } from './chunk-ENIDFSMM.js';
+export { GarretError } from './chunk-ENIDFSMM.js';
+import { spawn } from 'child_process';
+import { accessSync, constants, writeFileSync, renameSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { delimiter, join } from 'path';
+import { randomBytes, createCipheriv, createDecipheriv } from 'crypto';
+
+var port = globalThis.process?.parentPort;
+function send(msg) {
+  port?.postMessage(msg);
+}
+var STREAM_RUNTIME = /* @__PURE__ */ Symbol("garret.stream");
+function isStream(v) {
+  return typeof v === "object" && v !== null && STREAM_RUNTIME in v;
+}
+function defineHost(factory) {
+  const children = /* @__PURE__ */ new Set();
+  const disposers = [];
+  const streams = /* @__PURE__ */ new Map();
+  let disposed = false;
+  const scrubbedEnv = (base) => {
+    const env = {};
+    for (const [k, v] of Object.entries(base)) if (!k.startsWith("GARRET_")) env[k] = v;
+    return env;
+  };
+  const track = (child) => {
+    children.add(child);
+    child.on("exit", () => children.delete(child));
+    const r = child;
+    r.text = () => new Promise((resolve, reject) => {
+      let out = "";
+      child.stdout?.on("data", (d) => out += d.toString());
+      child.on("error", reject);
+      child.on("close", () => resolve(out));
+    });
+    return r;
+  };
+  const ctx = {
+    emit: (channel, payload) => send({ t: "event", channel, payload }),
+    stream: (fn) => ({ [STREAM_RUNTIME]: fn }),
+    // Scrub GARRET_* from the FINAL merged env, always — a caller-supplied opts.env must never
+    // reopen the leak (the vault key would otherwise reach adb/scrcpy/shells the author didn't write).
+    spawn: (argv, opts) => track(
+      spawn(argv[0], argv.slice(1), {
+        ...opts,
+        shell: false,
+        env: scrubbedEnv({ ...process.env, ...opts?.env ?? {} })
+      })
+    ),
+    spawnShell: (command, opts) => track(spawn(command, { ...opts, shell: true, env: scrubbedEnv({ ...process.env, ...opts?.env ?? {} }) })),
+    resolveBinary,
+    storage: makeStorage(dataDir),
+    secrets: makeSecrets(dataDir, secretKey),
+    // Pack-shared store only when the host was launched with GARRET_PACK_SHARED_DIR (pack declares `shared`).
+    shared: process.env.GARRET_PACK_SHARED_DIR ? { storage: makeStorage(sharedDir), secrets: makeSecrets(sharedDir, sharedSecretKey) } : void 0,
+    fetch: (...a) => fetch(...a),
+    onDispose: (cb) => disposers.push(cb),
+    log: (...args) => console.error("[host]", ...args)
+  };
+  async function runDispose() {
+    if (disposed) return;
+    disposed = true;
+    for (const ac of streams.values()) ac.abort();
+    for (const cb of disposers) {
+      try {
+        await cb();
+      } catch {
+      }
+    }
+    for (const c of children) c.kill();
+    process.exit(0);
+  }
+  function driveStream(id, fn) {
+    const ac = new AbortController();
+    streams.set(id, ac);
+    const done = (final) => {
+      if (!streams.has(id)) return;
+      streams.delete(id);
+      final();
+    };
+    const out = {
+      push: (chunk) => streams.has(id) && send({ t: "chunk", id, data: chunk }),
+      end: (result) => done(() => send({ t: "stream_end", id, result })),
+      error: (err) => done(() => send({ t: "stream_err", id, ...wireError(err) }))
+    };
+    Promise.resolve().then(() => fn(out, ac.signal)).catch((err) => out.error(err));
+  }
+  async function handleCall(id, method, args) {
+    const methods = ready;
+    const fn = methods?.[method];
+    if (typeof fn !== "function") {
+      return send({ t: "err", id, code: "BAD_ARGS", message: `unknown method: ${method}` });
+    }
+    try {
+      const result = await fn(args);
+      if (isStream(result)) driveStream(id, result[STREAM_RUNTIME]);
+      else send({ t: "res", id, result });
+    } catch (err) {
+      send({ t: "err", id, ...wireError(err) });
+    }
+  }
+  let ready;
+  port?.on("message", (e) => {
+    const msg = e.data;
+    if (!msg || typeof msg !== "object") return;
+    switch (msg.t) {
+      case "req":
+      case "stream_start":
+        void handleCall(msg.id, msg.method, msg.args);
+        break;
+      case "cancel":
+        streams.get(msg.id)?.abort();
+        streams.delete(msg.id);
+        break;
+      case "dispose":
+        void runDispose();
+        break;
+    }
+  });
+  process.on("SIGTERM", () => void runDispose());
+  Promise.resolve().then(() => factory(ctx)).then((methods) => {
+    ready = methods;
+    send({ t: "ready" });
+  }).catch((err) => {
+    console.error("[host] factory failed during startup:", err);
+    process.exit(1);
+  });
+}
+function wireError(err) {
+  if (err instanceof GarretError) return { code: err.code, message: err.message, hint: err.hint };
+  if (err instanceof Error && err.name === "AbortError") return { code: "CANCELLED", message: err.message };
+  return { code: "INTERNAL", message: err instanceof Error ? err.message : String(err) };
+}
+var PROBE = {
+  darwin: ["/opt/homebrew/bin", "/usr/local/bin", "/opt/homebrew/sbin"],
+  linux: ["/usr/local/bin", "/usr/bin", "/snap/bin", `${process.env.HOME}/.local/bin`],
+  win32: [`${process.env.LOCALAPPDATA}\\Microsoft\\WinGet\\Packages`, "C:\\ProgramData\\chocolatey\\bin"]
+};
+async function resolveBinary(name, opts) {
+  const platform = process.platform;
+  const exe = platform === "win32" ? `${name}.exe` : name;
+  const dirs = [...process.env.PATH?.split(delimiter) ?? [], ...PROBE[platform] ?? []];
+  for (const dir of dirs) {
+    if (!dir || dir.includes("undefined")) continue;
+    const full = join(dir, exe);
+    try {
+      accessSync(full, constants.X_OK);
+      return full;
+    } catch {
+    }
+  }
+  throw new GarretError("BINARY_NOT_FOUND", `${name} not found on PATH`, {
+    hint: opts?.hint ?? `install ${name} via your package manager`
+  });
+}
+function dirFromEnv(name) {
+  const dir = process.env[name];
+  if (!dir) throw new GarretError("UNAVAILABLE", "storage/secrets unavailable (no data dir)");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+var dataDir = () => dirFromEnv("GARRET_EXT_DATA_DIR");
+var sharedDir = () => dirFromEnv("GARRET_PACK_SHARED_DIR");
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeJsonAtomic(file, obj) {
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify(obj));
+  renameSync(tmp, file);
+}
+function makeChain() {
+  let chain = Promise.resolve();
+  return (fn) => {
+    const next = chain.then(fn, fn);
+    chain = next.catch(() => void 0);
+    return next;
+  };
+}
+function makeStorage(dir) {
+  const queue = makeChain();
+  const file = () => join(dir(), "storage.json");
+  return {
+    get: async (key) => readJson(file())[key],
+    set: (key, value) => queue(() => {
+      const f = file();
+      const all = readJson(f);
+      all[key] = value;
+      writeJsonAtomic(f, all);
+    }),
+    delete: (key) => queue(() => {
+      const f = file();
+      const all = readJson(f);
+      delete all[key];
+      writeJsonAtomic(f, all);
+    }),
+    keys: async () => Object.keys(readJson(file())),
+    clear: () => queue(() => writeJsonAtomic(file(), {}))
+  };
+}
+function keyFromEnv(name) {
+  const hex = process.env[name];
+  if (!hex) throw new GarretError("UNAVAILABLE", "secrets unavailable on this platform");
+  return Buffer.from(hex, "hex");
+}
+var secretKey = () => keyFromEnv("GARRET_EXT_SECRET_KEY");
+var sharedSecretKey = () => keyFromEnv("GARRET_PACK_SHARED_KEY");
+function makeSecrets(dir, getKey) {
+  const queue = makeChain();
+  const file = () => join(dir(), "secrets.json");
+  return {
+    get: async (key) => {
+      const box = readJson(file())[key];
+      if (!box) return void 0;
+      const decipher = createDecipheriv("aes-256-gcm", getKey(), Buffer.from(box.iv, "base64"));
+      decipher.setAuthTag(Buffer.from(box.tag, "base64"));
+      try {
+        return decipher.update(Buffer.from(box.ct, "base64")).toString("utf8") + decipher.final("utf8");
+      } catch {
+        throw new GarretError("INTERNAL", `secret "${key}" failed to decrypt`);
+      }
+    },
+    set: (key, value) => queue(() => {
+      const iv = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", getKey(), iv);
+      const ct = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+      const box = { v: 1, iv: iv.toString("base64"), tag: cipher.getAuthTag().toString("base64"), ct: ct.toString("base64") };
+      const f = file();
+      const all = readJson(f);
+      all[key] = box;
+      writeJsonAtomic(f, all);
+    }),
+    delete: (key) => queue(() => {
+      const f = file();
+      const all = readJson(f);
+      delete all[key];
+      writeJsonAtomic(f, all);
+    })
+  };
+}
+
+export { defineHost };

package/dist/index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+// src/errors.ts
+var GarretError = class _GarretError extends Error {
+  code;
+  hint;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "GarretError";
+    this.code = code;
+    this.hint = options?.hint;
+    Object.setPrototypeOf(this, _GarretError.prototype);
+  }
+};
+function garretErrorFromWire(code, message, hint) {
+  const known = [
+    "BINARY_NOT_FOUND",
+    "NOT_FOUND",
+    "PERMISSION",
+    "UNAVAILABLE",
+    "BAD_ARGS",
+    "TIMEOUT",
+    "CANCELLED",
+    "NETWORK",
+    "INTERNAL"
+  ];
+  const c = known.includes(code) ? code : "INTERNAL";
+  return new GarretError(c, message, hint ? { hint } : void 0);
+}
+
+// src/argv.ts
+function parseArgv(command) {
+  const out = [];
+  let cur = "";
+  let has = false;
+  let quote = null;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else if (c === "\\" && quote === '"' && i + 1 < command.length) cur += command[++i];
+      else cur += c;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+      has = true;
+    } else if (c === " " || c === "	" || c === "\n") {
+      if (has) {
+        out.push(cur);
+        cur = "";
+        has = false;
+      }
+    } else {
+      cur += c;
+      has = true;
+    }
+  }
+  if (has) out.push(cur);
+  return out;
+}
+
+// src/types.ts
+function defineManifest(manifest) {
+  return manifest;
+}
+function defineConfig(schema) {
+  return schema;
+}
+
+// src/protocol.ts
+var ACTIVE_CHANNEL = "$active";
+
+exports.ACTIVE_CHANNEL = ACTIVE_CHANNEL;
+exports.GarretError = GarretError;
+exports.defineConfig = defineConfig;
+exports.defineManifest = defineManifest;
+exports.garretErrorFromWire = garretErrorFromWire;
+exports.parseArgv = parseArgv;

package/dist/index.d.cts

@@ -0,0 +1,15 @@
+export { C as Capability, a as ConfigField, b as ConfigFieldType, c as ConfigSchema, E as EventMap, G as GarretError, d as GarretErrorCode, e as GarretErrorOptions, H as HostClient, M as Manifest, S as Stream, f as StreamCall, g as defineConfig, h as defineManifest, i as garretErrorFromWire } from './types-BxSYAH_H.cjs';
+export { A as ACTIVE_CHANNEL, C as CallId, T as Transport, W as WireMessage } from './protocol-Do0BJdeE.cjs';
+
+/**
+ * Split a command string into an argv array, honoring single/double quotes and backslash escapes
+ * (inside double quotes). Dependency-free — for command-runner-style widgets where the user types a
+ * command and you pass the result to `ctx.spawn(argv)` (which is array-only, no shell). NOT a full
+ * shell parser: no pipes, redirects, globbing, or variable expansion.
+ *
+ *   parseArgv('echo "hello world"')  → ['echo', 'hello world']
+ *   parseArgv("git commit -m 'a b'") → ['git', 'commit', '-m', 'a b']
+ */
+declare function parseArgv(command: string): string[];
+
+export { parseArgv };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { C as Capability, a as ConfigField, b as ConfigFieldType, c as ConfigSchema, E as EventMap, G as GarretError, d as GarretErrorCode, e as GarretErrorOptions, H as HostClient, M as Manifest, S as Stream, f as StreamCall, g as defineConfig, h as defineManifest, i as garretErrorFromWire } from './types-BxSYAH_H.js';
+export { A as ACTIVE_CHANNEL, C as CallId, T as Transport, W as WireMessage } from './protocol-Do0BJdeE.js';
+
+/**
+ * Split a command string into an argv array, honoring single/double quotes and backslash escapes
+ * (inside double quotes). Dependency-free — for command-runner-style widgets where the user types a
+ * command and you pass the result to `ctx.spawn(argv)` (which is array-only, no shell). NOT a full
+ * shell parser: no pipes, redirects, globbing, or variable expansion.
+ *
+ *   parseArgv('echo "hello world"')  → ['echo', 'hello world']
+ *   parseArgv("git commit -m 'a b'") → ['git', 'commit', '-m', 'a b']
+ */
+declare function parseArgv(command: string): string[];
+
+export { parseArgv };

package/dist/index.js

@@ -0,0 +1,37 @@
+export { defineConfig, defineManifest } from './chunk-RZJO3X6O.js';
+export { GarretError, garretErrorFromWire } from './chunk-ENIDFSMM.js';
+
+// src/argv.ts
+function parseArgv(command) {
+  const out = [];
+  let cur = "";
+  let has = false;
+  let quote = null;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else if (c === "\\" && quote === '"' && i + 1 < command.length) cur += command[++i];
+      else cur += c;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+      has = true;
+    } else if (c === " " || c === "	" || c === "\n") {
+      if (has) {
+        out.push(cur);
+        cur = "";
+        has = false;
+      }
+    } else {
+      cur += c;
+      has = true;
+    }
+  }
+  if (has) out.push(cur);
+  return out;
+}
+
+// src/protocol.ts
+var ACTIVE_CHANNEL = "$active";
+
+export { ACTIVE_CHANNEL, parseArgv };

package/dist/platform-CZHtdUK0.d.ts

@@ -0,0 +1,154 @@
+import { T as Transport } from './protocol-Do0BJdeE.js';
+
+/**
+ * Platform capabilities — the Garret-brokered surface available to a widget UI in BOTH tiers
+ * (`useGarret()`). Every call is enforced in Garret's main process against the manifest's declared
+ * capabilities. The concrete implementation is injected by the preload as `window.__garret` (U3);
+ * outside Garret (dev in a browser) a fallback reports `inGarret === false` and throws on use.
+ */
+interface ServiceStatus {
+    connected: boolean;
+}
+interface ServiceClient {
+    /** Connection state is async (the account is connected in Garret's Settings, brokered by main). */
+    status(): Promise<ServiceStatus>;
+    query<R = unknown>(method: string, params?: Record<string, unknown>): Promise<R>;
+}
+interface StorageApi {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+interface SecretsApi {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** What `g.fetch` resolves to. NOT a DOM `Response` — a Response can't cross the contextBridge from
+ *  the preload, so Garret hands back this serializable shape (primitive fields + body readers). */
+interface GarretResponse {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** The pack-shared store (only usable when the pack manifest declares `shared`): one namespace across
+ *  all the pack's widgets — e.g. a single credential set for a multi-widget service pack. */
+interface SharedApi {
+    storage: StorageApi;
+    secrets: SecretsApi;
+}
+/** Options for opening a floating sibling surface. All fields optional; sizes in px. */
+interface SurfaceOpenOptions {
+    /** initial props delivered to the opened surface as `g.props`; structured-cloned, so each surface
+     *  gets its own isolated copy (mutations are local). Must be structured-cloneable (no functions). */
+    props?: Record<string, unknown>;
+    title?: string;
+    size?: {
+        w: number;
+        h: number;
+    };
+    /** default true — the window stays above normal windows while you work. */
+    alwaysOnTop?: boolean;
+    /** singleton: a repeat open with the same key focuses the existing window instead of spawning. */
+    key?: string;
+}
+/** A handle to a floating surface window opened via `g.surfaces.open`. */
+interface SurfaceHandle {
+    readonly id: string;
+    close(): Promise<boolean>;
+    focus(): Promise<boolean>;
+    /** Resolves when the window closes — by the user, `close()`, or its opener being removed. */
+    closed(): Promise<void>;
+    onClose(cb: () => void): () => void;
+}
+/** Controls for the surface window THIS UI runs in (no-op for a board-placed widget). */
+interface WindowControls {
+    /** Lock the window's aspect ratio (width/height); `0` clears it. Use once you know your content
+     *  size — e.g. a mirror sets the device's ratio after the first video frame.
+     *
+     *  `inset` reserves guest-drawn chrome (px) that is EXCLUDED from the aspect-locked area, so the
+     *  ratio applies to your content, not the whole window — e.g. a fixed 48px side toolbar passes
+     *  `{ width: 48 }` and the remaining area keeps `ratio`. Combined with the host's own titlebar. */
+    setAspectRatio(ratio: number, inset?: {
+        width?: number;
+        height?: number;
+    }): void;
+    /** Resize the window (px). */
+    resize(width: number, height: number): void;
+    /** Close this surface window (for a frameless surface's own close button). */
+    close(): void;
+}
+interface SurfaceApi {
+    /** Open a sibling surface (declared in this package's manifest) as a floating, focusable window.
+     *  Rejects with an Error (message from Garret) if denied — e.g. missing `windows` capability,
+     *  unknown surface, or the concurrent-window limit. */
+    open(surfaceId: string, opts?: SurfaceOpenOptions): Promise<SurfaceHandle>;
+    /** Observe closes of this opener's surfaces by instanceId. Unlike a handle's `onClose`/`closed()`
+     *  (scoped to the current context), this SURVIVES an opener reload — re-subscribe on mount for
+     *  reload-durable close tracking. */
+    onClosed(cb: (instanceId: string) => void): () => void;
+}
+interface GarretPlatform {
+    /** per-extension (shared across placements), atomic + key-merged. */
+    storage: StorageApi;
+    /** per-placement (isolated) — safe for cursors/state that mustn't clobber other instances. */
+    instanceStorage: StorageApi;
+    secrets: SecretsApi;
+    /** Brokered HTTPS fetch (capability `network:<host>` / `network:*`). Resolves to a GarretResponse
+     *  (a Response-like shape — see the type), not a DOM Response. */
+    fetch(url: string, init?: RequestInit): Promise<GarretResponse>;
+    /** Pack-shared store — present only when the pack declares `shared`; otherwise its calls reject. */
+    shared: SharedApi;
+    service<T extends ServiceClient = ServiceClient>(id: string): T;
+    notify(title: string, body?: string): void;
+    openExternal(url: string): Promise<boolean>;
+    clipboard: {
+        readText(): Promise<string>;
+        writeText(value: string): Promise<void>;
+    };
+    /** false when the board is ambient/idle — pause rAF/animations, throttle polling. */
+    active: boolean;
+    onActiveChange(cb: (active: boolean) => void): () => void;
+    /** The host (frame ⋯→Settings) asks this widget to open its own config UI. */
+    onOpenSettings(cb: () => void): () => void;
+    /** Open sibling surfaces (same package) as floating windows. Requires the `windows` capability. */
+    surfaces: SurfaceApi;
+    /** Controls for this UI's own surface window (no-op for a board-placed widget). */
+    window: WindowControls;
+    /** Fires once the runtime has bound, with this surface's launch props (`{}` for the board surface).
+     *  Fires immediately if already ready. Props arrive via the callback — NOT a live getter — because
+     *  a getter would be frozen at contextBridge exposure time (before bind). Use `useProps()` in React. */
+    onReady(cb: (props: Record<string, unknown>) => void): () => void;
+    /** false in a plain browser (dev) — render a "run inside Garret" state instead of a blank UI. */
+    inGarret: boolean;
+}
+/** What the preload injects. Extends the platform with the wiring the SDK runtimes need. */
+interface GarretRuntime extends GarretPlatform {
+    instanceId: string;
+    /** the per-widget host bridge; null for web widgets (no host). */
+    hostTransport: Transport | null;
+    config: {
+        get(): unknown;
+        /** replace=false → shallow merge (patch); true → full replace. */
+        set(value: unknown, replace?: boolean): void;
+        subscribe(cb: (config: unknown) => void): () => void;
+    };
+}
+declare global {
+    interface Window {
+        __garret?: GarretRuntime;
+    }
+}
+declare function getRuntime(): GarretRuntime | undefined;
+declare function getHostTransport(): Transport | null;
+declare function getInstanceId(): string;
+/** The platform capabilities. Real inside Garret; a fail-loud fallback in a plain browser. */
+declare function getGarret(): GarretPlatform;
+
+export { type GarretPlatform as G, type SurfaceApi as S, type WindowControls as W, type SurfaceHandle as a, type SurfaceOpenOptions as b, type GarretRuntime as c, type SecretsApi as d, type ServiceClient as e, type StorageApi as f, getGarret as g, getHostTransport as h, getInstanceId as i, getRuntime as j };