@harborclient/sdk 0.4.3

package/dist/runtime/index.js

@@ -0,0 +1,43 @@
+import { setHostReact, requireHostReact } from './reactHost.js';
+
+/**
+ * Installs the HarborClient renderer React instance for plugin JSX and hooks.
+ *
+ * Call once at the start of `activate(hc)` before registering UI contributions.
+ *
+ * @param {typeof import('react')} react - React namespace from `hc.react`.
+ */
+export function installReact(react) {
+  setHostReact(react);
+}
+
+/**
+ * Creates a React component from a factory that receives the host React namespace.
+ *
+ * Useful when you need hooks or createElement in the same module as activate()
+ * without importing React directly.
+ *
+ * @template {Record<string, unknown>} P
+ * @param {(react: typeof import('react')) => import('react').ComponentType<P>} factory
+ * @returns {import('react').ComponentType<P>}
+ */
+export function createPluginComponent(factory) {
+  /** @type {import('react').ComponentType<P> | null} */
+  let Component = null;
+
+  /**
+   * Lazily builds the component on first render after installReact().
+   *
+   * @param {P} props - Component props.
+   * @returns {import('react').ReactElement | null}
+   */
+  function PluginComponent(props) {
+    if (Component == null) {
+      Component = factory(requireHostReact());
+    }
+    const react = requireHostReact();
+    return react.createElement(Component, props);
+  }
+
+  return PluginComponent;
+}

package/dist/runtime/jsx-dev-runtime.d.ts

@@ -0,0 +1,12 @@
+import type * as React from 'react';
+
+export { Fragment } from './jsx-runtime';
+
+/**
+ * Development JSX runtime entry; delegates to the production jsx helper.
+ */
+export function jsxDEV(
+  type: React.ElementType,
+  props: Record<string, unknown> | null | undefined,
+  key?: string | number
+): React.ReactElement;

package/dist/runtime/jsx-dev-runtime.js

@@ -0,0 +1,15 @@
+import { Fragment, jsx } from './jsx-runtime.js';
+
+export { Fragment };
+
+/**
+ * Development JSX transform entry; delegates to the production jsx helper.
+ *
+ * @param {import('react').ElementType} type - Element type or Fragment sentinel.
+ * @param {Record<string, unknown> | null | undefined} props - Element props.
+ * @param {string | number | undefined} key - React key when provided by the compiler.
+ * @returns {import('react').ReactElement}
+ */
+export function jsxDEV(type, props, key) {
+  return jsx(type, props, key);
+}

package/dist/runtime/jsx-runtime.d.ts

@@ -0,0 +1,35 @@
+import type * as React from 'react';
+
+/**
+ * Sentinel value compiled from JSX fragments; resolved to host React.Fragment at runtime.
+ */
+export declare const Fragment: unique symbol;
+
+/**
+ * Automatic JSX runtime entry used when `jsxImportSource` is `@harborclient/sdk`.
+ */
+export function jsx(
+  type: React.ElementType,
+  props: Record<string, unknown> | null | undefined,
+  key?: string | number
+): React.ReactElement;
+
+/**
+ * Automatic JSX runtime entry for elements with multiple children.
+ */
+export function jsxs(
+  type: React.ElementType,
+  props: Record<string, unknown> | null | undefined,
+  key?: string | number
+): React.ReactElement;
+
+export namespace JSX {
+  interface Element extends React.JSX.Element { }
+  interface ElementClass extends React.JSX.ElementClass { }
+  interface ElementAttributesProperty extends React.JSX.ElementAttributesProperty { }
+  interface ElementChildrenAttribute extends React.JSX.ElementChildrenAttribute { }
+  type LibraryManagedAttributes<C, P> = React.JSX.LibraryManagedAttributes<C, P>;
+  interface IntrinsicAttributes extends React.JSX.IntrinsicAttributes { }
+  interface IntrinsicClassAttributes<T> extends React.JSX.IntrinsicClassAttributes<T> { }
+  interface IntrinsicElements extends React.JSX.IntrinsicElements { }
+}

package/dist/runtime/jsx-runtime.js

@@ -0,0 +1,30 @@
+import { requireHostReact } from './reactHost.js';
+
+/**
+ * Sentinel value compiled from JSX fragments; resolved to host React.Fragment at runtime.
+ */
+export const Fragment = Symbol.for('@harborclient/sdk.Fragment');
+
+/**
+ * Builds a React element using the installed host React instance.
+ *
+ * @param {import('react').ElementType} type - Element type or Fragment sentinel.
+ * @param {Record<string, unknown> | null | undefined} props - Element props.
+ * @param {string | number | undefined} key - React key when provided by the compiler.
+ * @returns {import('react').ReactElement}
+ */
+function build(type, props, key) {
+  const react = requireHostReact();
+  const elementType = type === Fragment ? react.Fragment : type;
+  const { children, ...rest } = props ?? {};
+  if (key !== undefined) {
+    rest.key = key;
+  }
+  return react.createElement(elementType, rest, children);
+}
+
+/** @type {typeof import('react/jsx-runtime').jsx} */
+export const jsx = build;
+
+/** @type {typeof import('react/jsx-runtime').jsxs} */
+export const jsxs = build;

package/dist/runtime/react.d.ts

@@ -0,0 +1 @@
+export { useState, useEffect, useCallback, useMemo, useRef, useSyncExternalStore } from 'react';

package/dist/runtime/react.js

@@ -0,0 +1,46 @@
+import { requireHostReact } from './reactHost.js';
+
+/**
+ * Returns a hook from the installed host React instance.
+ *
+ * @param {keyof typeof import('react')} name - Hook name on the React namespace.
+ * @returns {unknown} Hook function from host React.
+ */
+function hook(name) {
+  const react = requireHostReact();
+  const fn = react[name];
+  if (typeof fn !== 'function') {
+    throw new Error(`React hook "${String(name)}" is not available on hc.react.`);
+  }
+  return fn;
+}
+
+/** @type {typeof import('react').useState} */
+export function useState(initialState) {
+  return hook('useState')(initialState);
+}
+
+/** @type {typeof import('react').useEffect} */
+export function useEffect(effect, deps) {
+  return hook('useEffect')(effect, deps);
+}
+
+/** @type {typeof import('react').useCallback} */
+export function useCallback(callback, deps) {
+  return hook('useCallback')(callback, deps);
+}
+
+/** @type {typeof import('react').useMemo} */
+export function useMemo(factory, deps) {
+  return hook('useMemo')(factory, deps);
+}
+
+/** @type {typeof import('react').useRef} */
+export function useRef(initialValue) {
+  return hook('useRef')(initialValue);
+}
+
+/** @type {typeof import('react').useSyncExternalStore} */
+export function useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) {
+  return hook('useSyncExternalStore')(subscribe, getSnapshot, getServerSnapshot);
+}

package/dist/runtime/reactHost.js

@@ -0,0 +1,26 @@
+/** @type {typeof import('react') | null} */
+let hostReact = null;
+
+/**
+ * Installs the HarborClient renderer React instance for plugin JSX and hooks.
+ *
+ * @param {typeof import('react')} react - React namespace from `hc.react`.
+ */
+export function setHostReact(react) {
+  hostReact = react;
+}
+
+/**
+ * Returns the installed host React instance.
+ *
+ * @returns {typeof import('react')} Host React namespace.
+ * @throws {Error} When {@link setHostReact} has not been called yet.
+ */
+export function requireHostReact() {
+  if (hostReact == null) {
+    throw new Error(
+      'Plugin React host is not installed. Call installReact(hc.react) at the start of activate().'
+    );
+  }
+  return hostReact;
+}

package/dist/runtime/store.d.ts

@@ -0,0 +1,19 @@
+import type { Disposable } from '../types.js';
+/**
+ * Creates a module-level external store compatible with React `useSyncExternalStore`.
+ *
+ * @param initial - Initial snapshot value.
+ */
+export declare function createExternalStore<T>(initial: T): {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => T;
+    setState: (next: T) => void;
+};
+/**
+ * Starts an interval and returns a disposable that clears it on deactivation.
+ *
+ * @param callback - Function invoked on each tick.
+ * @param intervalMs - Interval in milliseconds.
+ */
+export declare function setIntervalDisposable(callback: () => void, intervalMs: number): Disposable;
+//# sourceMappingURL=store.d.ts.map

package/dist/runtime/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/runtime/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG;IAClD,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC,CAAC;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B,CAkBA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAO1F"}

package/dist/runtime/store.js

@@ -0,0 +1,38 @@
+/**
+ * Creates a module-level external store compatible with React `useSyncExternalStore`.
+ *
+ * @param initial - Initial snapshot value.
+ */
+export function createExternalStore(initial) {
+    let state = initial;
+    const listeners = new Set();
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot: () => state,
+        setState: (next) => {
+            state = next;
+            for (const listener of listeners) {
+                listener();
+            }
+        }
+    };
+}
+/**
+ * Starts an interval and returns a disposable that clears it on deactivation.
+ *
+ * @param callback - Function invoked on each tick.
+ * @param intervalMs - Interval in milliseconds.
+ */
+export function setIntervalDisposable(callback, intervalMs) {
+    const timer = setInterval(callback, intervalMs);
+    return {
+        dispose: () => {
+            clearInterval(timer);
+        }
+    };
+}

package/dist/runtime/store.ts

@@ -0,0 +1,45 @@
+import type { Disposable } from '../types.js';
+
+/**
+ * Creates a module-level external store compatible with React `useSyncExternalStore`.
+ *
+ * @param initial - Initial snapshot value.
+ */
+export function createExternalStore<T>(initial: T): {
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => T;
+  setState: (next: T) => void;
+} {
+  let state = initial;
+  const listeners = new Set<() => void>();
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot: () => state,
+    setState: (next) => {
+      state = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    }
+  };
+}
+
+/**
+ * Starts an interval and returns a disposable that clears it on deactivation.
+ *
+ * @param callback - Function invoked on each tick.
+ * @param intervalMs - Interval in milliseconds.
+ */
+export function setIntervalDisposable(callback: () => void, intervalMs: number): Disposable {
+  const timer = setInterval(callback, intervalMs);
+  return {
+    dispose: () => {
+      clearInterval(timer);
+    }
+  };
+}

package/dist/runtime-utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Creates a new unique id string.
+ *
+ * Uses `crypto.randomUUID` when available (renderer); falls back for the SES main runtime.
+ *
+ * @param prefix - Optional prefix when falling back from randomUUID.
+ */
+export declare function randomId(prefix?: string): string;
+/**
+ * Returns the UTF-8 byte length of a string without relying on TextEncoder.
+ *
+ * Safe in the SES plugin main runtime where only `hc`, `console`, `Date`, and `Math`
+ * globals are available.
+ *
+ * @param value - String to measure.
+ */
+export declare function byteLength(value: string): number;
+/**
+ * Truncates a string to a maximum UTF-8 byte length without TextEncoder.
+ *
+ * @param value - String to truncate.
+ * @param maxBytes - Maximum UTF-8 bytes to retain.
+ */
+export declare function truncateToBytes(value: string, maxBytes: number): string;
+/**
+ * Truncates a body string to the configured byte limit with an optional suffix.
+ *
+ * @param body - Raw body text.
+ * @param maxBytes - Maximum UTF-8 bytes to retain.
+ * @param suffix - Optional suffix appended when truncated.
+ */
+export declare function truncateBody(body: string, maxBytes: number, suffix?: string): {
+    body: string;
+    truncated: boolean;
+};
+//# sourceMappingURL=runtime-utils.d.ts.map

package/dist/runtime-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-utils.d.ts","sourceRoot":"","sources":["../src/runtime-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAO,GAAG,MAAM,CAK9C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmBhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+BvE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAsD,GAC3D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAQtC"}

package/dist/runtime-utils.js

@@ -0,0 +1,101 @@
+/**
+ * Creates a new unique id string.
+ *
+ * Uses `crypto.randomUUID` when available (renderer); falls back for the SES main runtime.
+ *
+ * @param prefix - Optional prefix when falling back from randomUUID.
+ */
+export function randomId(prefix = 'id') {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+ * Returns the UTF-8 byte length of a string without relying on TextEncoder.
+ *
+ * Safe in the SES plugin main runtime where only `hc`, `console`, `Date`, and `Math`
+ * globals are available.
+ *
+ * @param value - String to measure.
+ */
+export function byteLength(value) {
+    if (typeof TextEncoder !== 'undefined') {
+        return new TextEncoder().encode(value).length;
+    }
+    let bytes = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x7f) {
+            bytes += 1;
+        }
+        else if (code <= 0x7ff) {
+            bytes += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            bytes += 4;
+            index += 1;
+        }
+        else {
+            bytes += 3;
+        }
+    }
+    return bytes;
+}
+/**
+ * Truncates a string to a maximum UTF-8 byte length without TextEncoder.
+ *
+ * @param value - String to truncate.
+ * @param maxBytes - Maximum UTF-8 bytes to retain.
+ */
+export function truncateToBytes(value, maxBytes) {
+    if (typeof TextEncoder !== 'undefined') {
+        const encoded = new TextEncoder().encode(value);
+        if (encoded.length <= maxBytes) {
+            return value;
+        }
+        return new TextDecoder().decode(encoded.slice(0, maxBytes));
+    }
+    let bytes = 0;
+    let index = 0;
+    for (; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        let charBytes;
+        if (code <= 0x7f) {
+            charBytes = 1;
+        }
+        else if (code <= 0x7ff) {
+            charBytes = 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            charBytes = 4;
+        }
+        else {
+            charBytes = 3;
+        }
+        if (bytes + charBytes > maxBytes) {
+            break;
+        }
+        bytes += charBytes;
+        if (charBytes === 4) {
+            index += 1;
+        }
+    }
+    return value.slice(0, index);
+}
+/**
+ * Truncates a body string to the configured byte limit with an optional suffix.
+ *
+ * @param body - Raw body text.
+ * @param maxBytes - Maximum UTF-8 bytes to retain.
+ * @param suffix - Optional suffix appended when truncated.
+ */
+export function truncateBody(body, maxBytes, suffix = `\n\n[truncated — body exceeded ${maxBytes} bytes]`) {
+    if (byteLength(body) <= maxBytes) {
+        return { body, truncated: false };
+    }
+    return {
+        body: `${truncateToBytes(body, maxBytes)}${suffix}`,
+        truncated: true
+    };
+}

package/dist/runtime-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-utils.test.d.ts.map

package/dist/runtime-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-utils.test.d.ts","sourceRoot":"","sources":["../src/runtime-utils.test.ts"],"names":[],"mappings":""}

package/dist/runtime-utils.test.js

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it, jest } from '@jest/globals';
+import { byteLength, randomId, truncateBody, truncateToBytes } from './runtime-utils.js';
+const originalTextEncoder = globalThis.TextEncoder;
+const originalCrypto = globalThis.crypto;
+afterEach(() => {
+    globalThis.TextEncoder = originalTextEncoder;
+    globalThis.crypto = originalCrypto;
+    jest.restoreAllMocks();
+});
+function withoutTextEncoder(run) {
+    // @ts-expect-error — exercise manual UTF-8 fallback used in SES main runtime
+    globalThis.TextEncoder = undefined;
+    return run();
+}
+describe('randomId', () => {
+    it('returns a UUID when crypto.randomUUID is available', () => {
+        const spy = jest
+            .spyOn(globalThis.crypto, 'randomUUID')
+            .mockReturnValue('00000000-0000-4000-8000-000000000000');
+        expect(randomId()).toBe('00000000-0000-4000-8000-000000000000');
+        spy.mockRestore();
+    });
+    it('falls back to a prefixed id when randomUUID is unavailable', () => {
+        // @ts-expect-error — exercise SES main-runtime fallback
+        globalThis.crypto = undefined;
+        expect(randomId('req')).toMatch(/^req-\d+-[a-z0-9]+$/);
+    });
+    it('uses the default prefix in the fallback path', () => {
+        // @ts-expect-error — exercise SES main-runtime fallback
+        globalThis.crypto = undefined;
+        expect(randomId()).toMatch(/^id-\d+-[a-z0-9]+$/);
+    });
+});
+describe('byteLength', () => {
+    it('counts ASCII as one byte per character', () => {
+        expect(byteLength('abc')).toBe(3);
+        expect(byteLength('')).toBe(0);
+    });
+    it('counts two-byte UTF-8 characters', () => {
+        expect(byteLength('é')).toBe(2);
+    });
+    it('counts three-byte UTF-8 characters', () => {
+        expect(byteLength('中')).toBe(3);
+    });
+    it('counts surrogate pairs as four bytes', () => {
+        expect(byteLength('😀')).toBe(4);
+    });
+    it('matches TextEncoder when the manual fallback is used', () => {
+        const samples = ['plain', 'é', '中', '😀', 'mix é 中 😀'];
+        for (const sample of samples) {
+            const encodedLength = new originalTextEncoder().encode(sample).length;
+            withoutTextEncoder(() => {
+                expect(byteLength(sample)).toBe(encodedLength);
+            });
+        }
+    });
+});
+describe('truncateToBytes', () => {
+    it('returns the original string when it fits', () => {
+        expect(truncateToBytes('hello', 10)).toBe('hello');
+        expect(truncateToBytes('é', 2)).toBe('é');
+    });
+    it('truncates multibyte text without splitting code units', () => {
+        expect(truncateToBytes('éé', 2)).toBe('é');
+        expect(truncateToBytes('abc', 2)).toBe('ab');
+    });
+    it('returns an empty string when maxBytes is zero', () => {
+        expect(truncateToBytes('hello', 0)).toBe('');
+    });
+    it('excludes an incomplete surrogate pair in the manual fallback', () => {
+        withoutTextEncoder(() => {
+            expect(truncateToBytes('a😀b', 2)).toBe('a');
+        });
+    });
+    it('does not split multibyte characters in the manual fallback', () => {
+        withoutTextEncoder(() => {
+            expect(truncateToBytes('mix é end', 5)).toBe('mix ');
+            expect(truncateToBytes('中文字', 3)).toBe('中');
+        });
+    });
+});
+describe('truncateBody', () => {
+    it('returns the body unchanged when within the byte limit', () => {
+        expect(truncateBody('{"ok":true}', 100)).toEqual({
+            body: '{"ok":true}',
+            truncated: false
+        });
+    });
+    it('truncates and appends the default suffix when over the limit', () => {
+        const body = 'x'.repeat(20);
+        const maxBytes = 10;
+        const result = truncateBody(body, maxBytes);
+        expect(result.truncated).toBe(true);
+        expect(result.body.endsWith(`[truncated — body exceeded ${maxBytes} bytes]`)).toBe(true);
+        expect(byteLength(result.body.replace(/\n\n\[truncated — body exceeded \d+ bytes\]$/, ''))).toBeLessThanOrEqual(maxBytes);
+    });
+    it('uses a custom suffix when provided', () => {
+        const result = truncateBody('0123456789', 5, '…');
+        expect(result).toEqual({
+            body: '01234…',
+            truncated: true
+        });
+    });
+});

package/dist/signing/canonical.d.ts

@@ -0,0 +1,27 @@
+import type { PluginFileHash, PluginSignaturePayload } from './types.js';
+/**
+ * Builds the canonical signing payload object from manifest identity and file hashes.
+ *
+ * @param pluginId - Plugin manifest id.
+ * @param pluginVersion - Plugin manifest version.
+ * @param files - Sorted plugin file inventory.
+ * @param keyId - Optional signing key label.
+ */
+export declare function buildSignaturePayload(pluginId: string, pluginVersion: string, files: PluginFileHash[], keyId?: string): PluginSignaturePayload;
+/**
+ * Serializes a signing payload to canonical JSON bytes for Ed25519 signing.
+ *
+ * @param payload - Unsigned signature payload.
+ */
+export declare function canonicalizeSignaturePayload(payload: PluginSignaturePayload): Buffer;
+/**
+ * Parses and validates a signature.json object read from disk.
+ *
+ * @param raw - Parsed JSON value.
+ * @returns Validated signature file contents.
+ * @throws When the payload shape is invalid.
+ */
+export declare function parsePluginSignatureFile(raw: unknown): PluginSignaturePayload & {
+    signature: string;
+};
+//# sourceMappingURL=canonical.d.ts.map

package/dist/signing/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/signing/canonical.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAGzE;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,cAAc,EAAE,EACvB,KAAK,CAAC,EAAE,MAAM,GACb,sBAAsB,CAcxB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAEpF;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,GACX,sBAAsB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CA2DhD"}