dsh-ntr 0.2.1 → 0.3.0

package/lib/types/update.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Host-side built-in update for dsh-ntr.
+ *
+ * The plugin NEVER downloads a package, swaps files, or restarts itself. The
+ * harness plugin manager owns installation (profile bookkeeping, npm, the
+ * restart contract); this module only asks it what is installed, asks an npm
+ * registry what is published, and delegates the install back to the manager.
+ * Every method therefore reports a {@link PluginUpdateState} instead of
+ * throwing; version syntax is validated at the RPC boundary (`impl.ts`).
+ */
+import type { PluginUpdateState } from './protocol.ts';
+/** The npm package this plugin is published as, and the bundle name to look for. */
+export declare const UPDATE_PACKAGE = "dsh-ntr";
+/** npm's public registry; the only base a private `resolved` may be widened to. */
+export declare const NPM_PUBLIC_REGISTRY = "https://registry.npmjs.org";
+/**
+ * Structural view of one row from the harness plugin manager's
+ * `listBundles()`. Deliberately local: importing the host package would tie
+ * this module to a runtime version it must merely probe structurally.
+ */
+export interface UpdateBundleInfo {
+    name: string;
+    installed: boolean;
+    removable?: boolean;
+    enabled?: boolean;
+    version?: string;
+    source?: string;
+    readOnlyReason?: string;
+    error?: {
+        code?: string;
+        message?: string;
+        diagnostic?: string;
+    };
+}
+/** Structural view of `pluginManager.registries()`. */
+export interface UpdateRegistryPlan {
+    registry?: string | null;
+    fallbackRegistries?: readonly string[];
+    resolved?: string | null;
+}
+/** Structural view of the manager's `installBundle()` / `removeBundle()` result (a ChangeResult). */
+export interface UpdateInstallResult {
+    application?: string;
+    version?: string;
+    error?: {
+        code?: string;
+        message?: string;
+        diagnostic?: string;
+    };
+}
+/** The plugin-manager face this service needs. Every member is probed, never assumed. */
+export interface UpdateManagerLike {
+    listBundles?(): Promise<readonly UpdateBundleInfo[]>;
+    registries?(): Promise<UpdateRegistryPlan>;
+    installBundle?(spec: string, options?: {
+        enabled?: boolean;
+        registry?: string;
+    }): Promise<UpdateInstallResult | undefined>;
+    /**
+     * Native-update half of the harness: `installBundle` refuses to replace an
+     * already-installed bundle while HMR holds it, so the host removes first.
+     * Optional — older hosts cannot install at all and answer `already-installed`.
+     */
+    removeBundle?(name: string): Promise<UpdateInstallResult | undefined>;
+}
+/**
+ * The shared eligibility verdict. `ok` carries the disk version (when the host
+ * reports one); the failure arm is already a full state, so check/apply can
+ * return it verbatim.
+ */
+export type BundleEligibility = {
+    ok: true;
+    installed?: string;
+} | {
+    ok: false;
+    state: PluginUpdateState;
+};
+/**
+ * Whether a `listBundles().source` value names a registry-resolvable version
+ * spec — the only install shape this updater may replace. The test is positive
+ * on purpose: link/file/git/workspace/URL/tarball/relative forms all carry a
+ * `:` / `/` / `\` or start with `.`, so they fall out without an ever-growing
+ * blacklist (a new source scheme must not become silently updatable).
+ */
+export declare function isRegistrySpec(source: string): boolean;
+/**
+ * Compare two semver strings (build metadata ignored, prerelease precedence per
+ * semver §11). Malformed segments count as `0`, so the function never throws on
+ * a value read off a registry.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Turn the manager's registry plan into the ordered list this service will
+ * actually query, following the host's privacy rule: a *private* `resolved`
+ * registry must not be widened with the shared fallback chain.
+ *
+ * - No configured registry: query `resolved`; append fallbacks only when it is
+ *   npm's public registry or one of the fallbacks themselves.
+ * - Configured registry: query it first, then `resolved` under the same
+ *   condition, then the fallbacks.
+ *
+ * http(s) only (a private http registry is legitimate), trailing slashes
+ * normalized, duplicates dropped. A base that carries credentials in its URL is
+ * skipped: a bare GET cannot replay `.npmrc` auth, so it could only fail with a
+ * 401 that reads as "unreachable".
+ */
+export declare function registryPlan(plan: UpdateRegistryPlan): string[];
+/**
+ * Pick the version an update should offer.
+ *
+ * `dist-tags.latest` leads when it is a stable release newer than `current`
+ * (that is the line npm itself blesses). Otherwise the highest stable,
+ * non-deprecated published version wins — a lagging `latest` tag must not hide
+ * a newer release. When nothing is newer, the stable `latest` tag is still
+ * returned so the UI can say "you are on the latest release".
+ */
+export declare function pickUpdateTarget(packument: unknown, current: string): {
+    version?: string;
+    publishedAt?: string;
+};
+/**
+ * Pure eligibility matrix, shared by check and apply.
+ *
+ * `undefined` means the manager (or one of its methods) is unavailable; an
+ * empty list means the manager answered but does not carry this plugin.
+ */
+export declare function bundleEligibility(bundles: readonly UpdateBundleInfo[] | undefined, currentVersion: string): BundleEligibility;
+export interface UpdateServiceOptions {
+    resolveManager(): UpdateManagerLike | undefined;
+    currentVersion: string;
+    isBusy(): boolean;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * Update checks and installs, memoized per registry base.
+ *
+ * Caching exists because the settings page polls: a 10-minute window keeps the
+ * check honest without turning every mount into a registry round trip. Apply
+ * clears the cache so the next check sees the freshly installed version.
+ */
+export declare class UpdateService {
+    private readonly resolveManager;
+    private readonly currentVersion;
+    private readonly isBusy;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly cache;
+    private applying;
+    /** Registry that answered the last `available` check, passed through to apply. */
+    private lastTarget?;
+    constructor(options: UpdateServiceOptions);
+    /** The manager surface plus the disk-version verdict, or a ready-to-return failure state. */
+    private eligibility;
+    private fetchTarget;
+    /** One registry's packument, via the 10-minute cache. Throws when unreachable. */
+    private targetFor;
+    /**
+     * Ask the manager's registry chain what is published; never installs.
+     *
+     * A mirror may lag behind the rest of the chain, so a base that only knows
+     * the running (or an older) release does not end the walk — the next base
+     * gets its turn. `busy` is deliberately not checked here: reading a registry
+     * costs no ACP work, and the settings card should still be able to say what
+     * is out there while a turn runs.
+     */
+    check(): Promise<PluginUpdateState>;
+    /**
+     * Install one exact version through the harness plugin manager.
+     *
+     * Re-entry while an install is running answers `applying` instead of
+     * stacking a second npm operation; the install itself is the host's job.
+     *
+     * With HMR alive the manager refuses to replace a bundle already in the
+     * profile (`already-installed`), so the host's own update semantics are
+     * remove-then-install. That is NOT self-replacement: a human gesture started
+     * it, the manager still performs every file operation, and it unloads the
+     * live module first — exactly what the host does for any bundle update. If
+     * the reinstall fails, the previous version is put back through the same
+     * `installBundle` path.
+     */
+    apply(version: string): Promise<PluginUpdateState>;
+}