@holokai/harbor-sdk 0.3.0 → 0.4.0

package/dist/build-inputs.json

@@ -0,0 +1,6 @@
+{
+  "package": "@holokai/harbor-sdk",
+  "version": "0.4.0",
+  "digest": "e3a9f0b4741dfff8a1d0639d90f6269367ca0af235911e7a3990696848563862",
+  "commit": "252a624bf9899c3976f10f48ce15ae5a206db18b"
+}

package/dist/package.d.ts

@@ -2,11 +2,10 @@
  * The package contract: what makes an npm package an extension Harbor can run, and the installed catalog a tree carries.
  * It imports nothing at run time, so Harbor's main process, the extension host and the build scripts all read it.
  */
+import type { DeclaredGrant } from './contract';
 import type { ExtensionManifest } from './manifest';
 /** The extension-to-host API version. A host runs only extensions that declare it. */
 export declare const EXTENSION_API_VERSION = 1;
-/** Packages a tree holds exactly once: host-provided contracts and shared sign-in state. */
-export declare const SINGLETON_PACKAGES: readonly ["@holokai/harbor-sdk", "@holokai/harbor-kit", "@holokai/harbor-google", "@holokai/harbor-microsoft", "@holokai/harbor-atlassian", "@holokai/harbor-relay"];
 /** The `harbor` field of a published package's package.json: which kind of package it is. */
 export type HarborPackageField = {
     type: 'extension';
@@ -14,6 +13,17 @@ export type HarborPackageField = {
 } | {
     type: 'library';
 };
+/**
+ * Whether a tree must hold exactly one copy of a package: the SDK and every library. A library carries what extensions
+ * share across package lines: the host-provided contracts, a connection's sign-in state, and error classes one
+ * package throws and another matches with `instanceof`. A second copy splits any of them.
+ */
+export declare function isSingletonPackage(metadata: {
+    name: string;
+    harbor?: {
+        type?: string;
+    };
+}): boolean;
 /** The package.json fields Harbor reads. */
 export interface ExtensionPackageMetadata {
     name: string;
@@ -33,7 +43,7 @@ export interface InstalledCatalogEntry {
     /** `pages/<name>/app.html` */
     page: string;
 }
-/** `tree/catalog.json`: what one installed tree holds. */
+/** `extension-release/catalog.json`: what one installed tree holds. */
 export interface InstalledCatalog {
     apiVersion: number;
     /** The SDK version installed in this tree. */
@@ -77,3 +87,150 @@ export declare function catalogFor(input: {
         manifest: unknown;
     }[];
 }): InstalledCatalog;
+/** The folder an installed tree lives in: the shipped tree, an installed set and a set's archive all hold one. */
+export declare const RELEASE_TREE_DIR = "extension-release";
+/** The release metadata file's name inside a tree, written last when the tree is staged. */
+export declare const RELEASE_METADATA_FILE = "release-metadata.json";
+/** `extension-release/release-metadata.json`: what a staged tree is and what it was built for. */
+export interface ReleaseMetadata {
+    /** A release set id, `shipped` for a tree staged from the pins, or `local` for one packed from the workspace. */
+    setId: string;
+    /** `<platform>-<arch>`, such as `darwin-arm64`. */
+    target: string;
+    apiVersion: number;
+    sdkVersion: string;
+    /** The Harbor-to-host IPC protocol of the tree's host (`EXTENSIONS_HEALTH.protocol`). */
+    hostProtocol: number;
+    /** Each extension's name and version. */
+    extensions: Record<string, string>;
+    /** The repository commit the tree was staged from. */
+    commit: string;
+    /** The sha256 of what the tree was staged from; a different value means the tree is stale. */
+    inputs: string;
+    /** A workspace tree's build digest of each package, by package name: which packages a restage replaces. */
+    packages?: Record<string, string>;
+    stagedAt: string;
+}
+/** Null for anything that is not release metadata with every field in shape. */
+export declare function parseReleaseMetadata(value: unknown): ReleaseMetadata | null;
+/** The targets a release set is built for: the released apps. A Linux build gets no runtime updates. */
+export declare const RELEASE_TARGETS: readonly ["darwin-arm64", "win32-x64"];
+export type ReleaseTarget = (typeof RELEASE_TARGETS)[number];
+/** The lanes a release manifest is published on. */
+export declare const RELEASE_LANES: readonly ["production", "beta"];
+export type ReleaseLane = (typeof RELEASE_LANES)[number];
+/** One extension a release set holds. */
+export interface ReleaseSetExtension {
+    version: string;
+    /** The provider decides the process, and so the shared sign-in, the extension runs in. */
+    provider: string;
+    grants: readonly DeclaredGrant[];
+}
+/** One target's archive of a release set. */
+export interface ReleaseArtifact {
+    /** Always `setArchiveKey(id, target)`: a manifest cannot point a download anywhere else. */
+    path: string;
+    /** `sha512-<base64>`, the form npm's integrity field uses. */
+    sha512: string;
+    bytes: number;
+}
+/** A set record: immutable, identical in the set's set.json and in every lane manifest that offers it. */
+export interface ReleaseSet {
+    /** `ext-YYYY-MM-DD-NNN`: the UTC date of the build and the next free number that day, so ids sort by age. */
+    id: string;
+    apiVersion: number;
+    sdkVersion: string;
+    hostProtocol: number;
+    minHarborVersion: string;
+    maxHarborVersion?: string;
+    /** The sha256 of the set's package-lock.json; every target build checks it before `npm ci`. */
+    lockfileSha256: string;
+    /** By extension name. */
+    extensions: Record<string, ReleaseSetExtension>;
+    /** By target. */
+    artifacts: Record<string, ReleaseArtifact>;
+}
+/** release-manifest.json for one lane, signed on its own. */
+export interface ReleaseManifest {
+    lane: ReleaseLane;
+    /** This lane's metadata version, raised by every publication; unrelated to set ids. */
+    sequence: number;
+    issuedAt: string;
+    /** Newest first; older sets stay listed for Harbor versions the newest does not fit. */
+    sets: ReleaseSet[];
+}
+/** The detached signature of a lane manifest: Ed25519 over exactly its served bytes. */
+export interface ReleaseSignature {
+    keyId: string;
+    /** base64 */
+    signature: string;
+}
+/** A lane's latest.json: an untrusted pointer to its newest manifest. The signed manifest's own sequence is trusted. */
+export interface LanePointer {
+    sequence: number;
+}
+/** Whether a value is a release set id: `ext-YYYY-MM-DD-NNN`. */
+export declare const isReleaseSetId: (value: unknown) => value is string;
+/** Whether set `a` is newer than set `b`. Set ids sort by age, so the later id is the newer set. */
+export declare const isNewerSetId: (a: string, b: string) => boolean;
+/** The store key of a set's archive for one target. */
+export declare const setArchiveKey: (id: string, target: string) => string;
+/** The store key of a set's one resolved closure. */
+export declare const setLockfileKey: (id: string) => string;
+/** The store key of a set's record. */
+export declare const setRecordKey: (id: string) => string;
+/** The store key of one lane manifest; the sequence is zero-padded to six digits. */
+export declare const laneManifestKey: (lane: ReleaseLane, sequence: number) => string;
+/** The store key of one lane manifest's signature. */
+export declare const laneSignatureKey: (lane: ReleaseLane, sequence: number) => string;
+/** The store key of a lane's pointer, the one object in the store that is replaced. */
+export declare const lanePointerKey: (lane: ReleaseLane) => string;
+/** A set record, or null when any field is out of shape. Only ReleaseSet's fields survive. */
+export declare function parseReleaseSet(value: unknown): ReleaseSet | null;
+/** A lane manifest, or null when it or any set it lists is out of shape, or it lists one set id twice. */
+export declare function parseReleaseManifest(value: unknown): ReleaseManifest | null;
+/** A lane manifest's signature file, or null when out of shape. */
+export declare function parseReleaseSignature(value: unknown): ReleaseSignature | null;
+/** A lane's latest.json, or null when out of shape. */
+export declare function parseLanePointer(value: unknown): LanePointer | null;
+/**
+ * Semver precedence of two versions: negative, zero or positive. A prerelease sorts before its release
+ * (`2.0.3-rc.1` < `2.0.3`). Throws on a value that is not `major.minor.patch[-prerelease]`.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Whether a version satisfies a caret range such as `^0.3.0`: at least the range's version, and below the next
+ * breaking one (`^1.2.3` < 2.0.0, `^0.3.0` < 0.4.0, `^0.0.3` < 0.0.4). A prerelease of that next breaking version is
+ * below it too. False for a range that is not a caret range.
+ */
+export declare function satisfiesCaret(version: string, range: string): boolean;
+/** Why a set cannot run here, by protocol alone. */
+export type Incompatibility = 'api_version' | 'sdk_version' | 'host_protocol' | 'harbor_version' | 'older_than_running' | 'no_artifact';
+/**
+ * The first reason, in the order of Incompatibility, a set cannot run here, or null when it can. An extension the
+ * running tree holds that the set leaves out is not judged here: that is the rollout policy's `removed_extension`.
+ */
+export declare function incompatibility(set: ReleaseSet, here: {
+    apiVersion: number;
+    /** A caret range, such as `^0.3.0`. */
+    sdkRange: string;
+    hostProtocols: readonly number[];
+    harborVersion: string;
+    target: string;
+    /** Each extension's name and version in the tree in force. */
+    running: Record<string, string>;
+}): Incompatibility | null;
+/** Why a release policy refuses a set that is protocol-compatible. */
+export type PolicyRefusal = 'new_extension' | 'removed_extension' | 'changes_provider' | 'organization';
+/** Rollout and organization policy, apart from protocol. */
+export interface ExtensionReleasePolicy {
+    /** The reason the set may not replace the running extensions, or null when it may. */
+    refusal(set: ReleaseSet, running: ReleaseSet['extensions']): PolicyRefusal | null;
+}
+/**
+ * The first-party default: a set that adds an extension, drops one the running tree holds, or moves one to another
+ * provider waits for an app release.
+ */
+export declare const FIRST_PARTY_ROLLOUT: ExtensionReleasePolicy;
+/** The grants of `declared` that `authorized` holds, by stable id; the rest are withheld. */
+export declare function authorizedGrants(declared: readonly DeclaredGrant[], authorized: readonly DeclaredGrant[]): DeclaredGrant[];

package/dist/package.js

@@ -2,14 +2,9 @@ import {createRequire as __harborCreateRequire} from 'node:module'; const requir
 
 // src/package.ts
 var EXTENSION_API_VERSION = 1;
-var SINGLETON_PACKAGES = [
-  "@holokai/harbor-sdk",
-  "@holokai/harbor-kit",
-  "@holokai/harbor-google",
-  "@holokai/harbor-microsoft",
-  "@holokai/harbor-atlassian",
-  "@holokai/harbor-relay"
-];
+function isSingletonPackage(metadata) {
+  return metadata.name === "@holokai/harbor-sdk" || metadata.harbor?.type === "library";
+}
 var CATALOG_FILE = "catalog.json";
 var NAME = /^[a-z][a-z0-9-]*$/;
 var VERSION_CORE = /^\d+\.\d+\.\d+$/;
@@ -119,13 +114,223 @@ function catalogFor(input) {
   extensions.sort((a, b) => a.name.localeCompare(b.name));
   return { apiVersion: EXTENSION_API_VERSION, sdkVersion: input.sdkVersion, releaseSet: input.releaseSet, extensions };
 }
+var RELEASE_TREE_DIR = "extension-release";
+var RELEASE_METADATA_FILE = "release-metadata.json";
+var SHA256 = /^[0-9a-f]{64}$/;
+var isNumber = (value) => typeof value === "number" && Number.isInteger(value);
+function parseReleaseMetadata(value) {
+  if (!isRecord(value)) return null;
+  const { setId, target, apiVersion, sdkVersion, hostProtocol, extensions, commit, inputs, packages, stagedAt } = value;
+  if (!isString(setId) || setId === "" || !isString(target) || !/^[a-z0-9]+-[a-z0-9]+$/.test(target)) return null;
+  if (!isNumber(apiVersion) || !isNumber(hostProtocol) || !isString(sdkVersion) || !isVersion(sdkVersion))
+    return null;
+  if (!isString(commit) || !isString(inputs) || !SHA256.test(inputs) || !isString(stagedAt)) return null;
+  if (!isRecord(extensions)) return null;
+  const versions = {};
+  for (const [name, version] of Object.entries(extensions)) {
+    if (!NAME.test(name) || !isString(version) || !isVersion(version)) return null;
+    versions[name] = version;
+  }
+  if (packages !== void 0 && !(isRecord(packages) && Object.values(packages).every((d) => isString(d) && SHA256.test(d)))) {
+    return null;
+  }
+  return {
+    setId,
+    target,
+    apiVersion,
+    sdkVersion,
+    hostProtocol,
+    extensions: versions,
+    commit,
+    inputs,
+    ...packages === void 0 ? {} : { packages: { ...packages } },
+    stagedAt
+  };
+}
+var RELEASE_TARGETS = ["darwin-arm64", "win32-x64"];
+var RELEASE_LANES = ["production", "beta"];
+var SET_ID = /^ext-\d{4}-\d{2}-\d{2}-\d{3}$/;
+var TARGET = /^[a-z0-9]+-[a-z0-9]+$/;
+var SHA512_INTEGRITY = /^sha512-[A-Za-z0-9+/]+={0,2}$/;
+var BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+var isPositiveInteger = (value) => isNumber(value) && value > 0;
+var isReleaseSetId = (value) => isString(value) && SET_ID.test(value);
+var isNewerSetId = (a, b) => a > b;
+var setArchiveKey = (id, target) => `extensions/sets/${id}/${id}-${target}.tar.gz`;
+var setLockfileKey = (id) => `extensions/sets/${id}/package-lock.json`;
+var setRecordKey = (id) => `extensions/sets/${id}/set.json`;
+var laneManifestKey = (lane, sequence) => `extensions/lanes/${lane}/manifests/${String(sequence).padStart(6, "0")}.json`;
+var laneSignatureKey = (lane, sequence) => `${laneManifestKey(lane, sequence)}.sig`;
+var lanePointerKey = (lane) => `extensions/lanes/${lane}/latest.json`;
+function parseSetExtension(value) {
+  if (!isRecord(value)) return null;
+  const { version, provider, grants } = value;
+  if (!isString(version) || !isVersion(version) || !isString(provider) || !NAME.test(provider)) return null;
+  if (!isStringArray(grants) || !grants.every((grant) => DECLARED_GRANTS.has(grant))) return null;
+  return { version, provider, grants: [...grants] };
+}
+function parseArtifact(value, id, target) {
+  if (!isRecord(value)) return null;
+  const { path, sha512, bytes } = value;
+  if (path !== setArchiveKey(id, target)) return null;
+  if (!isString(sha512) || !SHA512_INTEGRITY.test(sha512) || !isPositiveInteger(bytes)) return null;
+  return { path, sha512, bytes };
+}
+function parseReleaseSet(value) {
+  if (!isRecord(value)) return null;
+  const { id, apiVersion, sdkVersion, hostProtocol, minHarborVersion, maxHarborVersion, lockfileSha256 } = value;
+  if (!isReleaseSetId(id) || !isPositiveInteger(apiVersion) || !isPositiveInteger(hostProtocol)) return null;
+  if (!isString(sdkVersion) || !isVersion(sdkVersion)) return null;
+  if (!isString(minHarborVersion) || !isVersion(minHarborVersion)) return null;
+  if (maxHarborVersion !== void 0 && !(isString(maxHarborVersion) && isVersion(maxHarborVersion))) return null;
+  if (!isString(lockfileSha256) || !SHA256.test(lockfileSha256)) return null;
+  if (!isRecord(value.extensions) || !isRecord(value.artifacts)) return null;
+  const extensions = {};
+  for (const [name, raw] of Object.entries(value.extensions)) {
+    const extension = parseSetExtension(raw);
+    if (!NAME.test(name) || extension === null) return null;
+    extensions[name] = extension;
+  }
+  const artifacts = {};
+  for (const [target, raw] of Object.entries(value.artifacts)) {
+    const artifact = TARGET.test(target) ? parseArtifact(raw, id, target) : null;
+    if (artifact === null) return null;
+    artifacts[target] = artifact;
+  }
+  return {
+    id,
+    apiVersion,
+    sdkVersion,
+    hostProtocol,
+    minHarborVersion,
+    ...maxHarborVersion === void 0 ? {} : { maxHarborVersion },
+    lockfileSha256,
+    extensions,
+    artifacts
+  };
+}
+function parseReleaseManifest(value) {
+  if (!isRecord(value) || !Array.isArray(value.sets)) return null;
+  const { lane, sequence, issuedAt } = value;
+  if (!RELEASE_LANES.includes(lane) || !isPositiveInteger(sequence)) return null;
+  if (!isString(issuedAt) || issuedAt === "") return null;
+  const sets = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of value.sets) {
+    const set = parseReleaseSet(raw);
+    if (set === null || seen.has(set.id)) return null;
+    seen.add(set.id);
+    sets.push(set);
+  }
+  return { lane, sequence, issuedAt, sets };
+}
+function parseReleaseSignature(value) {
+  if (!isRecord(value)) return null;
+  const { keyId, signature } = value;
+  if (!isString(keyId) || keyId === "" || !isString(signature)) return null;
+  if (!BASE64.test(signature) || signature.length % 4 !== 0) return null;
+  return { keyId, signature };
+}
+function parseLanePointer(value) {
+  if (!isRecord(value) || !isPositiveInteger(value.sequence)) return null;
+  return { sequence: value.sequence };
+}
+function parseVersion(value) {
+  if (!isVersion(value)) return null;
+  const dash = value.indexOf("-");
+  const core = (dash === -1 ? value : value.slice(0, dash)).split(".").map(Number);
+  return { core, prerelease: dash === -1 ? [] : value.slice(dash + 1).split(".") };
+}
+function compareIdentifiers(a, b) {
+  const aNumeric = /^\d+$/.test(a);
+  const bNumeric = /^\d+$/.test(b);
+  if (aNumeric && bNumeric) return Number(a) - Number(b);
+  if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareParsed(a, b) {
+  for (let i = 0; i < 3; i++) {
+    const difference = a.core[i] - b.core[i];
+    if (difference !== 0) return Math.sign(difference);
+  }
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    return Math.sign(b.prerelease.length) - Math.sign(a.prerelease.length);
+  }
+  for (let i = 0; i < Math.min(a.prerelease.length, b.prerelease.length); i++) {
+    const difference = compareIdentifiers(a.prerelease[i], b.prerelease[i]);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return Math.sign(a.prerelease.length - b.prerelease.length);
+}
+function compareVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (left === null || right === null) throw new Error(`not a version: ${left === null ? a : b}`);
+  return compareParsed(left, right);
+}
+function satisfiesCaret(version, range) {
+  const floor = range.startsWith("^") ? parseVersion(range.slice(1)) : null;
+  const parsed = parseVersion(version);
+  if (floor === null || parsed === null || compareParsed(parsed, floor) < 0) return false;
+  const [major, minor, patch] = floor.core;
+  const ceiling = major > 0 ? [major + 1, 0, 0] : minor > 0 ? [0, minor + 1, 0] : [0, 0, patch + 1];
+  return compareParsed({ core: parsed.core, prerelease: [] }, { core: ceiling, prerelease: [] }) < 0;
+}
+function incompatibility(set, here) {
+  if (set.apiVersion !== here.apiVersion) return "api_version";
+  if (!satisfiesCaret(set.sdkVersion, here.sdkRange)) return "sdk_version";
+  if (!here.hostProtocols.includes(set.hostProtocol)) return "host_protocol";
+  if (compareVersions(here.harborVersion, set.minHarborVersion) < 0 || set.maxHarborVersion !== void 0 && compareVersions(here.harborVersion, set.maxHarborVersion) > 0) {
+    return "harbor_version";
+  }
+  for (const [name, version] of Object.entries(here.running)) {
+    const offered = set.extensions[name];
+    if (offered !== void 0 && compareVersions(offered.version, version) < 0) return "older_than_running";
+  }
+  if (set.artifacts[here.target] === void 0) return "no_artifact";
+  return null;
+}
+var FIRST_PARTY_ROLLOUT = {
+  refusal(set, running) {
+    if (Object.keys(set.extensions).some((name) => running[name] === void 0)) return "new_extension";
+    if (Object.keys(running).some((name) => set.extensions[name] === void 0)) return "removed_extension";
+    const moved = Object.entries(set.extensions).some(([name, ext]) => running[name]?.provider !== ext.provider);
+    return moved ? "changes_provider" : null;
+  }
+};
+function authorizedGrants(declared, authorized) {
+  const allowed = new Set(authorized);
+  return declared.filter((grant) => allowed.has(grant));
+}
 export {
   CATALOG_FILE,
   EXTENSION_API_VERSION,
-  SINGLETON_PACKAGES,
+  FIRST_PARTY_ROLLOUT,
+  RELEASE_LANES,
+  RELEASE_METADATA_FILE,
+  RELEASE_TARGETS,
+  RELEASE_TREE_DIR,
+  authorizedGrants,
   catalogFor,
+  compareVersions,
   entryPathOf,
+  incompatibility,
+  isNewerSetId,
+  isReleaseSetId,
+  isSingletonPackage,
+  laneManifestKey,
+  lanePointerKey,
+  laneSignatureKey,
   pagePathOf,
   parseExtensionManifest,
-  parseInstalledCatalog
+  parseInstalledCatalog,
+  parseLanePointer,
+  parseReleaseManifest,
+  parseReleaseMetadata,
+  parseReleaseSet,
+  parseReleaseSignature,
+  satisfiesCaret,
+  setArchiveKey,
+  setLockfileKey,
+  setRecordKey
 };

package/dist/runtime.d.ts

@@ -31,7 +31,7 @@ export declare const EXTENSIONS_ENV: {
     readonly connection: "EXTENSIONS_CONNECTION";
     /** The dev instance this server runs for. Its sign-in states name it, so the shared return reaches it. */
     readonly instance: "EXTENSIONS_INSTANCE";
-    /** The installed catalog the server loads its extensions from (`tree/catalog.json`). */
+    /** The installed catalog the server loads its extensions from (`extension-release/catalog.json`). */
     readonly catalog: "EXTENSIONS_CATALOG";
 };
 /**
@@ -57,10 +57,18 @@ export interface CatalogLoadedMessage {
     type: typeof EXTENSIONS_MESSAGE.catalogLoaded;
     loaded: string[];
     skipped: CatalogSkip[];
-    failed: {
-        name: string;
-        package: string;
-    }[];
+    failed: CatalogLoadFailure[];
+}
+/**
+ * One catalog entry the server did not run: its module did not import (`import`, with the error's class name in
+ * `error`), its default export is not an extension (`not_extension`), or its definition names another extension
+ * (`name`) or another sign-in provider (`provider`) than its catalog entry. The others in the catalog still run.
+ */
+export interface CatalogLoadFailure {
+    name: string;
+    package: string;
+    reason?: 'import' | 'not_extension' | 'name' | 'provider';
+    error?: string;
 }
 /** An extension's tool list changed, so harbor lists that extension's tools again. */
 export interface ToolsChangedMessage {

package/dist/runtime.js

@@ -18,7 +18,7 @@ var EXTENSIONS_ENV = {
   connection: "EXTENSIONS_CONNECTION",
   /** The dev instance this server runs for. Its sign-in states name it, so the shared return reaches it. */
   instance: "EXTENSIONS_INSTANCE",
-  /** The installed catalog the server loads its extensions from (`tree/catalog.json`). */
+  /** The installed catalog the server loads its extensions from (`extension-release/catalog.json`). */
   catalog: "EXTENSIONS_CATALOG"
 };
 var EXTENSIONS_MESSAGE = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holokai/harbor-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "The harbor extension to MCP Apps: the public contract a hosted view speaks, and a thin client over @modelcontextprotocol/ext-apps.",
   "exports": {