@uxnan/shared 0.0.3-alpha.20260702 → 0.0.4-alpha.20260703

package/README.md

@@ -52,8 +52,9 @@ flowchart TB
 | JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32008`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
 | Streaming | `StreamNotification` enum + param types (`TurnStartedParams`, `MessageDeltaParams`, `ThinkingDeltaParams`, `ContentBlockParams`, `TurnCompletedParams`, `TurnUsage`, `TurnErrorParams`, `TurnAbortedParams`, `ModelResolvedParams`) |
 | E2EE | handshake messages (`clientHello` / `serverHello` / `clientAuth` / `ready`), `buildHandshakeTranscript`, `SecureEnvelope`, `PairingPayload` v2 (`relay` optional + `hosts: string[]`) with `Base64(utf8(JSON))` QR encoding |
-| Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust, approval |
+| Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), approval |
 | Agents | `IAgentAdapter` (with `respondApproval`, `listModels`, `nativeSessionId`, `SendTurnOptions { threadId, turnId, text, service?, effort?, options?, attachments?, cwd?, accessMode? }`), `AgentModel` (incl. `version?`, `isDefault?`, `options?`, `contextWindow?`, `isLatestAlias?`), `AgentCapabilities` (incl. `images`, `approvals`, `reportsContextUsage`), `AgentConfig` (cwd, agentId, model, plus optional `binaryPath`/`extraArgs`) |
+| Version | `compareVersions` / `isNewerVersion` — dependency-free SemVer precedence (used by the bridge's npm update check) |
 | Validation | Ajv validators for requests, responses, envelopes, pairing payload, push payloads |
 
 ## Usage

package/dist/src/index.d.ts

@@ -14,6 +14,7 @@ export * from './e2ee/pairing-payload.js';
 export * from './agents/agent-capabilities.js';
 export * from './agents/agent-config.js';
 export * from './agents/agent-adapter.js';
+export * from './version/compare.js';
 export * from './notifications/push-payload.js';
 export * from './models/thread.js';
 export * from './models/git.js';

package/dist/src/index.js

@@ -17,6 +17,8 @@ export * from './e2ee/pairing-payload.js';
 export * from './agents/agent-capabilities.js';
 export * from './agents/agent-config.js';
 export * from './agents/agent-adapter.js';
+// Version
+export * from './version/compare.js';
 // Notifications
 export * from './notifications/push-payload.js';
 // Models

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAE/B,WAAW;AACX,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,OAAO;AACP,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAE1C,SAAS;AACT,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAE1C,gBAAgB;AAChB,cAAc,iCAAiC,CAAC;AAEhD,SAAS;AACT,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAErC,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAE/B,WAAW;AACX,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,OAAO;AACP,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAE1C,SAAS;AACT,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAE1C,UAAU;AACV,cAAc,sBAAsB,CAAC;AAErC,gBAAgB;AAChB,cAAc,iCAAiC,CAAC;AAEhD,SAAS;AACT,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAErC,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,qCAAqC,CAAC"}

package/dist/src/models/session.d.ts

@@ -25,4 +25,16 @@ export interface BridgeStatus {
     activeSessions: number;
     platform: NodeJS.Platform | string;
     uptimeMs: number;
+    /**
+     * Latest bridge version published to npm (dist-tag `alpha`), as discovered by
+     * the bridge's own background update check. Absent when the check hasn't run
+     * yet or couldn't reach the registry (offline) — never blocks status.
+     */
+    latestVersion?: string;
+    /**
+     * True when {@link latestVersion} is strictly newer than {@link version}
+     * (SemVer precedence). Lets the phone show a "bridge update available" hint
+     * without querying npm itself. Absent/false when unknown or up to date.
+     */
+    updateAvailable?: boolean;
 }

package/dist/src/version/compare.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Semantic-version comparison shared across the ecosystem.
+ *
+ * Uxnan versions follow SemVer with a date-stamped prerelease, e.g.
+ * `0.0.3-alpha.20260702` (and, on mobile, an optional `+<build>` metadata
+ * suffix). This implements SemVer 2.0.0 precedence (§11) closely enough for
+ * those formats — enough for the bridge to decide "is the published version
+ * newer than mine?" without pulling in a `semver` dependency.
+ *
+ * Build metadata (`+...`) is ignored for precedence, per the spec.
+ */
+/**
+ * Compare two SemVer strings. Returns `-1` if `a < b`, `1` if `a > b`, `0` if
+ * they are precedence-equal. Unparseable inputs sort as *lower* than any
+ * parseable version (and equal to each other), so a garbage/absent version
+ * never masquerades as "newer".
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * True when `candidate` is a strictly newer version than `current`. Used to
+ * decide whether to announce an available update. A candidate that is absent or
+ * unparseable is never treated as newer.
+ */
+export declare function isNewerVersion(candidate: string | undefined | null, current: string): boolean;

package/dist/src/version/compare.js

@@ -0,0 +1,116 @@
+/**
+ * Semantic-version comparison shared across the ecosystem.
+ *
+ * Uxnan versions follow SemVer with a date-stamped prerelease, e.g.
+ * `0.0.3-alpha.20260702` (and, on mobile, an optional `+<build>` metadata
+ * suffix). This implements SemVer 2.0.0 precedence (§11) closely enough for
+ * those formats — enough for the bridge to decide "is the published version
+ * newer than mine?" without pulling in a `semver` dependency.
+ *
+ * Build metadata (`+...`) is ignored for precedence, per the spec.
+ */
+/** Parse `MAJOR.MINOR.PATCH[-prerelease][+build]`, or `null` if unparseable. */
+function parseVersion(version) {
+    const trimmed = version.trim();
+    if (!trimmed)
+        return null;
+    // Strip build metadata (everything from the first `+`), which never affects
+    // precedence.
+    const noBuild = trimmed.split('+', 1)[0];
+    const dashIndex = noBuild.indexOf('-');
+    const core = dashIndex === -1 ? noBuild : noBuild.slice(0, dashIndex);
+    const prereleaseRaw = dashIndex === -1 ? '' : noBuild.slice(dashIndex + 1);
+    const coreParts = core.split('.');
+    if (coreParts.length !== 3)
+        return null;
+    const major = Number(coreParts[0]);
+    const minor = Number(coreParts[1]);
+    const patch = Number(coreParts[2]);
+    if (!Number.isInteger(major) ||
+        !Number.isInteger(minor) ||
+        !Number.isInteger(patch) ||
+        major < 0 ||
+        minor < 0 ||
+        patch < 0) {
+        return null;
+    }
+    const prerelease = prereleaseRaw.length > 0 ? prereleaseRaw.split('.') : [];
+    return { major, minor, patch, prerelease };
+}
+/** Numeric identifiers are all-digits (SemVer §9). */
+function isNumericIdentifier(id) {
+    return id.length > 0 && /^[0-9]+$/.test(id);
+}
+/** Compare two prerelease identifier lists per SemVer §11. */
+function comparePrerelease(a, b) {
+    // A release with no prerelease outranks one that has a prerelease.
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1; // `a` is stable, `b` is prerelease → a > b
+    if (b.length === 0)
+        return -1;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const idA = a[i];
+        const idB = b[i];
+        if (idA === idB)
+            continue;
+        const numA = isNumericIdentifier(idA);
+        const numB = isNumericIdentifier(idB);
+        if (numA && numB) {
+            const diff = Number(idA) - Number(idB);
+            if (diff !== 0)
+                return diff < 0 ? -1 : 1;
+        }
+        else if (numA) {
+            return -1; // numeric identifiers have lower precedence than alphanumeric
+        }
+        else if (numB) {
+            return 1;
+        }
+        else {
+            return idA < idB ? -1 : 1; // lexical ASCII order
+        }
+    }
+    // All shared identifiers equal → the longer set has higher precedence.
+    if (a.length === b.length)
+        return 0;
+    return a.length < b.length ? -1 : 1;
+}
+/**
+ * Compare two SemVer strings. Returns `-1` if `a < b`, `1` if `a > b`, `0` if
+ * they are precedence-equal. Unparseable inputs sort as *lower* than any
+ * parseable version (and equal to each other), so a garbage/absent version
+ * never masquerades as "newer".
+ */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa && !pb)
+        return 0;
+    if (!pa)
+        return -1;
+    if (!pb)
+        return 1;
+    if (pa.major !== pb.major)
+        return pa.major < pb.major ? -1 : 1;
+    if (pa.minor !== pb.minor)
+        return pa.minor < pb.minor ? -1 : 1;
+    if (pa.patch !== pb.patch)
+        return pa.patch < pb.patch ? -1 : 1;
+    return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+/**
+ * True when `candidate` is a strictly newer version than `current`. Used to
+ * decide whether to announce an available update. A candidate that is absent or
+ * unparseable is never treated as newer.
+ */
+export function isNewerVersion(candidate, current) {
+    if (!candidate)
+        return false;
+    if (parseVersion(candidate) === null)
+        return false;
+    return compareVersions(candidate, current) > 0;
+}
+//# sourceMappingURL=compare.js.map

package/dist/src/version/compare.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxnan/shared",
-  "version": "0.0.3-alpha.20260702",
+  "version": "0.0.4-alpha.20260703",
   "description": "Shared JSON-RPC and E2EE contracts for the Uxnan ecosystem (bridge, relay, mobile).",
   "license": "MPL-2.0",
   "author": "Luis Donaldo Gamas Vazquez",