@chatcode/cco-market 1.45.1

package/lib/types/updates.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Update detection: per-plugin comparison of what the profile has against
+ * the source of truth — git HEAD for github installs, the npm latest
+ * dist-tag for registry installs — with a TTL cache.
+ */
+import { type Channel } from './channels.ts';
+export interface UpdateStatus {
+    kind: 'github' | 'npm' | 'linked';
+    version: string | null;
+    current: string | null;
+    latest: string | null;
+    /**
+     * A NEWER version exists. Forwards only, always — every caller reads it
+     * as "there is an upgrade" and labels a button accordingly.
+     */
+    updateAvailable: boolean;
+    /** Taking this update replaces a local package source with its matched online release. */
+    restoreRequired?: boolean;
+    /** Independent, explicit source switch offered for verified legacy Git installs. */
+    sourceMigration?: {
+        kind: 'git-to-npm';
+        repo: string;
+        target: string;
+    };
+    /**
+     * The version this package's channel points at, when it differs from what
+     * is installed and is NOT newer.
+     *
+     * A separate field rather than a second meaning for `updateAvailable`,
+     * which was tried and leaked immediately: the market page has three
+     * consumers of that flag (the header banner, "update all", the row
+     * button) and all three announced a DOWNGRADE as "a new version is
+     * available". One field, one meaning; a caller that has not been taught
+     * about channel switches simply does not offer one.
+     *
+     * Only a channel-following package can be in this state, and it is the
+     * state that used to be unreachable: picking "stable" while a prerelease
+     * was installed compared 1.13.1 against 1.14.0-beta.1, found nothing
+     * newer, and answered "up to date" — so there was no way back off a
+     * channel the user had just left.
+     */
+    channelSwitch?: string;
+}
+/**
+ * Semver precedence: negative / 0 / positive like a comparator, or null when
+ * either side isn't a plain semver version. Build metadata is ignored, a
+ * release outranks any prerelease of the same core, and prerelease
+ * identifiers compare numerically when both are numeric (so `rc.10` > `rc.9`).
+ */
+export declare function compareVersions(a: string, b: string): number | null;
+/**
+ * True only when the registry's `latest` is semantically HIGHER than what the
+ * profile has (#64 by @ZeroOrigin64). A plain `!==` also fires when a
+ * package's `latest` dist-tag is left pointing at an OLDER release than the
+ * pinned install — clicking "update" then rewrote the exact pin to `@latest`
+ * and downgraded the profile until it no longer booted.
+ *
+ * Undecidable inputs (missing or non-semver versions) report no update:
+ * without a direction we cannot promise the "update" isn't a downgrade.
+ */
+export declare function isUpgrade(installed: string | null, latest: string | null): boolean;
+/** Drop the cached listing (after a successful install/update/uninstall). */
+export declare function invalidateUpdates(): void;
+/**
+ * Point update checks at a registry. Called when the download region
+ * resolves and whenever it changes.
+ *
+ * Dropping the cache is the load-bearing half. A mirror can lag the official
+ * registry by minutes, so answers gathered from one are not answers from the
+ * other — keeping them across a switch would report a version this registry
+ * cannot yet serve.
+ */
+export declare function setUpdateRegistry(base: string): void;
+/**
+ * Evidence check behind the "wait a day" stale diagnosis (#45): whether the
+ * package's CURRENT latest release was published recently enough to sit
+ * inside pnpm's default fresh-release window. pnpm's silent hold leaves no
+ * trace in its output, so the publish time is the only verifiable signal.
+ * @returns true/false when the npm time metadata answers, null when it
+ *   can't be determined (offline, unpublished, non-npm) — callers must NOT
+ *   claim the safety wait on null.
+ */
+export declare function latestPublishedRecently(name: string, windowMs?: number): Promise<boolean | null>;
+/** The registry's current `latest` version for a package, or null when it can't be read. */
+/**
+ * The version a channel subscriber should be offered: the newest build in
+ * the set that channel is willing to receive.
+ *
+ * A channel is a SET, not a tag. Someone on beta has not stopped accepting
+ * releases — they accept releases and prereleases — so beta means
+ * {latest, beta} and dev means {latest, beta, dev}. Reading it as one tag
+ * gets a real case wrong: once 1.14.0 ships, `beta` still points at
+ * 1.14.0-beta.1 until the next prerelease is cut, and following that tag
+ * literally would walk a subscriber BACKWARDS onto a build their channel
+ * has already moved past.
+ *
+ * The nesting is also what makes a channel leavable. Going backwards is
+ * only ever offered when the user narrows the set — picking stable while a
+ * prerelease is installed drops `beta` out of it, so the answer becomes
+ * `latest` and the market can finally offer the way back. That case used to
+ * be unreachable: comparing 1.13.1 against an installed 1.14.0-beta.1 found
+ * nothing newer and answered "up to date", so the control the user had just
+ * used appeared to do nothing.
+ *
+ * @param stable - the `latest` version, already fetched by the caller.
+ */
+export declare function versionOnChannel(name: string, channel: Channel, stable: string | null): Promise<string | null>;
+export declare function fetchNpmLatest(name: string): Promise<string | null>;
+/** Per-plugin update checks; a failed check reports no update rather than failing the listing. */
+export declare function checkUpdates(profile: string, force?: boolean, explicitDir?: string, 
+/**
+ * Packages that follow a release channel instead of plain `latest`. Only
+ * ever the market itself: opting into early builds is volunteering to try
+ * THIS plugin early, not a licence to pull every other author's
+ * unreleased work.
+ */
+channelFor?: ReadonlyMap<string, Channel>, 
+/**
+ * Curated npm sources for `file:` installs that were matched to the market
+ * catalog. `link:` workspaces remain development sources and are never
+ * opted into online updates.
+ */
+onlineSourceFor?: ReadonlyMap<string, string>): Promise<Record<string, UpdateStatus>>;

package/lib/types/verify.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Post-install activation verification (P0-2): what "installed" actually
+ * means for a package in a dsh profile.
+ *
+ * Two sources of truth, in strict order of authority:
+ *
+ * 1. The LOADER INVENTORY (observed): whatever the loader is running right
+ *    now is live, full stop. A plain library with no `dsh` field can be
+ *    loaded by name from someone else's bundle patch — the official
+ *    dsh-base patch loads `@deepseek-ai/dsh-tools`, which has no `dsh`
+ *    field at all — so no manifest check may overrule it (#135).
+ * 2. The profile manifest (inferred): `<profile>/package.json` →
+ *    `dsh.profile.bundles`, what the dsh CLI reconciled. This predicts what
+ *    the NEXT boot will load, and is the only evidence available for a
+ *    package that is not currently running.
+ *
+ * State taxonomy (IMPROVEMENT-PLAN P0-2):
+ *   live    – running in the current composition (hot mount or loader entry)
+ *   restart – installed and will activate on the next boot, but not live now
+ *   inert   – installed but not a profile-layer plugin (plain dependency, or
+ *             client-only — the market shim-mounts those at boot)
+ *   broken  – would fail to load: listed as a bundle without a dsh surface,
+ *             or a declared entry artifact that is missing
+ *   missing – not present in node_modules
+ */
+export type ActivationState = 'live' | 'restart' | 'inert' | 'broken' | 'missing' | 'disabled';
+export interface ActivationResult {
+    state: ActivationState;
+    /** Bilingual, user-facing explanations (zh / en joined with " / "). */
+    reasons: string[];
+    /** True when the package is in the profile's `dsh.profile.bundles`. */
+    bundle: boolean;
+    /** True when the package is live in the running composition. */
+    hot: boolean;
+}
+export declare function verifyActivation(profile: string, name: string, live?: ReadonlySet<string>, explicitDir?: string, isDisabled?: boolean): ActivationResult;
+/**
+ * Correct a post-UPDATE verdict for a plugin that was already running.
+ *
+ * `verifyActivation` answers "is this name in the live loader inventory".
+ * That is the right question after an install and the wrong one after an
+ * update: the plugin was already live, so the answer stays "live" while the
+ * process keeps serving the module it imported at boot. Replacing files under
+ * a running composition does not re-import anything.
+ *
+ * Measured on a real host rather than reasoned about — updating the market
+ * from 1.11.3 to 1.12.2 left `/dsh-market/status` reporting 1.11.3 with an
+ * unchanged boot id, while the update route called it hot-loaded in the same
+ * response. The browser half genuinely does refresh (the host re-serves the
+ * client bundle from disk), which is what makes the wrong verdict credible:
+ * the UI visibly becomes the new version while the server half does not.
+ *
+ * Only a plugin that was ALREADY live is affected. One that was missing,
+ * broken or disabled beforehand has nothing loaded to shadow the new build,
+ * so its fresh mount really does run the new code.
+ *
+ * Client-only packages are excluded for the same reason from the other end:
+ * they have no host half to go stale, and the browser fetches their bundle
+ * from disk on the next page load. Telling their users to restart would be
+ * #156 again, in a narrower place — see `hasHostHalf`.
+ * @param result the verdict computed from the loader inventory
+ * @param hostHalfWasLive whether a HOST half was live BEFORE the replacement
+ */
+export declare function activationAfterReplace(result: ActivationResult, hostHalfWasLive: boolean): ActivationResult;
+/**
+ * Whether a package has a host (Node) half at all.
+ *
+ * A `dsh.client`-only package — themes, skins, most pure-UI plugins — runs
+ * no server code: the market shim-mounts it so the loader has a live row,
+ * and the browser re-fetches its bundle from disk on the next page load. An
+ * update to one takes effect on refresh, with no restart to ask for.
+ */
+export declare function hasHostHalf(profile: string, name: string, explicitDir?: string): boolean;
+/**
+ * The client bundle path a package's `exports["./client"]` names, relative
+ * to the package root — or `null` when it cannot be resolved CONFIDENTLY.
+ *
+ * Returning null is the important half. This feeds a post-install check
+ * whose only job is to catch a corrupt bundle, and a resolver that guessed
+ * wrong would report a healthy plugin as broken — worse than the silence it
+ * replaces. So every shape this does not fully understand resolves to null
+ * and the check simply does not run: unresolvable is not evidence of damage.
+ *
+ * Handles the two shapes real plugins ship: a plain string, and a
+ * conditional object. For the object, only `browser` and `default` are
+ * consulted — those are the conditions the host's client loader actually
+ * activates; `import`/`require` describe a Node resolution this file is not
+ * modelling, and picking one of those could name a different artifact.
+ * Nested conditions recurse; anything else (arrays, non-relative targets)
+ * gives up.
+ */
+export declare function clientBundlePath(exportsField: unknown, depth?: number): string | null;
+/** What a bundle check concluded. `ok` covers "fine" AND "could not tell". */
+export interface BundleCheck {
+    ok: boolean;
+    /** Populated only when the file was found AND failed to parse. */
+    reason: string | null;
+}
+/**
+ * Every installed plugin whose client bundle will not parse (#222 by
+ * @MicroMilo).
+ *
+ * The per-package check above only ever looked at what an operation added,
+ * which misses the failure that was actually reported: pnpm re-extracts the
+ * WHOLE tree on any install, so updating one plugin can restore another
+ * plugin's pristine — and broken — bundle, or fail to re-apply a patch that
+ * was holding it together. The damage then surfaces at the next boot as
+ * "failed to load plugins", with nothing connecting it to the install that
+ * caused it.
+ *
+ * Cheap enough to run on every operation: 0.40ms per plugin including the
+ * read (measured on a 385KB bundle), so a 30-plugin profile costs ~12ms
+ * against an install that takes seconds.
+ *
+ * Silent on ESM bundles, like the per-package check it calls — see there for
+ * why. Widening the sweep is exactly what would have turned that one false
+ * "corrupt" into one per ESM plugin in the profile.
+ *
+ * Callers compare a before-list with an after-list rather than reporting
+ * this one directly — a profile can carry a broken bundle indefinitely, and
+ * re-reporting a problem the user already had would put them in front of
+ * something this operation did not cause and cannot undo.
+ */
+export declare function brokenClientBundles(profile: string, explicitDir?: string): {
+    name: string;
+    reason: string;
+}[];
+/** Bundles broken after an operation that were intact before it. */
+export declare function newlyBrokenBundles(before: readonly {
+    name: string;
+    reason: string;
+}[], after: readonly {
+    name: string;
+    reason: string;
+}[]): {
+    name: string;
+    reason: string;
+}[];
+export declare function checkClientBundle(profile: string, name: string, explicitDir?: string): BundleCheck;

package/lib/update-api-v1.js

@@ -0,0 +1,215 @@
+/**
+ * Stable, versioned contract for plugin-owned update surfaces.
+ *
+ * The market UI has richer internal response shapes that evolve with its UI.
+ * Third-party plugins must not depend on those shapes, so this module owns the
+ * small JSON envelope exposed under `/dsh-market/api/v1`.
+ */
+export const UPDATE_API_V1_SCHEMA = 'dsh-market/update-api/v1';
+export const MAX_UPDATE_OPERATIONS_V1 = 50;
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}
+function bool(value) {
+    return value === true;
+}
+function failureCode(status, body) {
+    const explicit = text(body.failureCode);
+    if (explicit === 'DOWNGRADE_DETECTED' || explicit === 'RESOLVED_VERSION_MISMATCH')
+        return explicit;
+    if (body.agentsBusy === true)
+        return 'AGENTS_RUNNING';
+    if (body.busy === true || status === 409)
+        return 'OPERATION_BUSY';
+    if (body.stale === true && body.staleReason === 'release-age')
+        return 'RELEASE_TOO_FRESH';
+    if (body.stale === true)
+        return 'VERSION_UNCHANGED';
+    if (body.timedOut === true)
+        return 'UPDATE_TIMEOUT';
+    if (status === 403)
+        return 'UPDATE_FORBIDDEN';
+    if (status === 400)
+        return 'UPDATE_REJECTED';
+    return 'UPDATE_FAILED';
+}
+function failureOf(status, body) {
+    const code = failureCode(status, body);
+    const message = text(body.error)
+        ?? text(body.stderr)
+        ?? text(body.stdout)
+        ?? `update failed with HTTP ${String(status)}`;
+    return {
+        code,
+        message: message.slice(-1200),
+        retryable: code === 'AGENTS_RUNNING'
+            || code === 'OPERATION_BUSY'
+            || code === 'RELEASE_TOO_FRESH'
+            || code === 'VERSION_UNCHANGED'
+            || code === 'RESOLVED_VERSION_MISMATCH'
+            || code === 'UPDATE_TIMEOUT',
+    };
+}
+function activationState(body, packageName) {
+    const activations = record(body.activation);
+    const activation = activations === null ? null : record(activations[packageName]);
+    return activation === null ? null : text(activation.state);
+}
+function rollbackIdOf(body) {
+    const compatibility = record(body.compatibility);
+    return compatibility === null ? null : text(compatibility.rollbackId);
+}
+function progressView(progress) {
+    if (progress === undefined) {
+        return {
+            phase: null,
+            done: 0,
+            total: null,
+            percent: null,
+            currentPackage: null,
+            detail: null,
+            downloaded: null,
+            size: null,
+        };
+    }
+    const percent = progress.total !== null && progress.total > 0
+        ? Math.min(100, Math.round(progress.done / progress.total * 100))
+        : null;
+    return {
+        phase: progress.phase,
+        done: progress.done,
+        total: progress.total,
+        percent,
+        currentPackage: progress.currentPackage,
+        detail: text(progress.lastLine) ?? text(progress.error),
+        downloaded: progress.downloaded,
+        size: progress.size,
+    };
+}
+/** Process-local operation registry. A boot id scopes ids across restarts. */
+export class UpdateOperationStoreV1 {
+    bootId;
+    now;
+    maxOperations;
+    sequence = 0;
+    operations = new Map();
+    activeId = null;
+    constructor(bootId, now = Date.now, maxOperations = MAX_UPDATE_OPERATIONS_V1) {
+        this.bootId = bootId;
+        this.now = now;
+        this.maxOperations = maxOperations;
+    }
+    hasActive() {
+        return this.activeId !== null;
+    }
+    create(packageName, beforeVersion) {
+        const operationId = `${this.bootId}-update-${String(++this.sequence)}`;
+        const createdAt = this.now();
+        const operation = {
+            schema: UPDATE_API_V1_SCHEMA,
+            operationId,
+            kind: 'update',
+            packageName,
+            state: 'queued',
+            createdAt,
+            startedAt: null,
+            finishedAt: null,
+            beforeVersion,
+            installedVersion: beforeVersion,
+            progress: progressView(),
+            outcome: {
+                refreshRequired: false,
+                restartRequired: false,
+                rollback: { available: false, state: 'unavailable', detail: null },
+            },
+            failure: null,
+            legacyRollbackId: null,
+        };
+        this.operations.set(operationId, operation);
+        this.activeId = operationId;
+        while (this.operations.size > this.maxOperations) {
+            const oldestId = this.operations.keys().next().value;
+            if (oldestId === undefined || oldestId === this.activeId)
+                break;
+            this.operations.delete(oldestId);
+        }
+        return this.snapshot(operation);
+    }
+    start(operationId) {
+        const operation = this.operations.get(operationId);
+        if (operation === undefined)
+            return;
+        operation.state = 'running';
+        operation.startedAt = this.now();
+        this.activeId = operationId;
+    }
+    finish(operationId, status, payload, installedVersion) {
+        const operation = this.operations.get(operationId);
+        if (operation === undefined)
+            return null;
+        const body = record(payload) ?? {};
+        const cancelled = bool(body.cancelled);
+        const ok = status >= 200 && status < 300 && bool(body.ok) && !cancelled;
+        operation.state = cancelled ? 'cancelled' : ok ? 'succeeded' : 'failed';
+        operation.finishedAt = this.now();
+        operation.installedVersion = installedVersion;
+        operation.failure = ok || cancelled ? null : failureOf(status, body);
+        const activation = activationState(body, operation.packageName);
+        operation.outcome.restartRequired = activation === 'restart';
+        operation.outcome.refreshRequired = bool(body.needsRefresh)
+            || (activation === 'live' && body.hot === true);
+        operation.legacyRollbackId = rollbackIdOf(body);
+        if (operation.legacyRollbackId !== null) {
+            operation.outcome.rollback.available = true;
+            operation.outcome.rollback.state = 'available';
+        }
+        if (this.activeId === operationId)
+            this.activeId = null;
+        return this.snapshot(operation);
+    }
+    beginRollback(operationId) {
+        const operation = this.operations.get(operationId);
+        if (operation?.legacyRollbackId === null || operation?.legacyRollbackId === undefined)
+            return null;
+        operation.outcome.rollback.state = 'running';
+        operation.outcome.rollback.detail = null;
+        return operation.legacyRollbackId;
+    }
+    finishRollback(operationId, status, payload, installedVersion) {
+        const operation = this.operations.get(operationId);
+        if (operation === undefined)
+            return null;
+        const body = record(payload) ?? {};
+        const ok = status >= 200 && status < 300 && body.rolledBack === true;
+        // The rollback endpoint supplies a fresh disk read. Keep the argument
+        // optional so existing store consumers retain source compatibility.
+        if (installedVersion !== undefined)
+            operation.installedVersion = installedVersion;
+        operation.outcome.rollback.available = !ok && status !== 400;
+        operation.outcome.rollback.state = ok ? 'succeeded' : 'failed';
+        operation.outcome.rollback.detail = ok ? null : text(body.error) ?? `rollback failed with HTTP ${String(status)}`;
+        if (ok) {
+            operation.state = 'rolled-back';
+            operation.outcome.restartRequired = true;
+        }
+        return this.snapshot(operation);
+    }
+    get(operationId, progress) {
+        const operation = this.operations.get(operationId);
+        if (operation === undefined)
+            return null;
+        const view = this.snapshot(operation);
+        if (this.activeId === operationId && operation.state === 'running')
+            view.progress = progressView(progress);
+        return view;
+    }
+    snapshot(operation) {
+        const { legacyRollbackId: _legacyRollbackId, ...view } = operation;
+        return structuredClone(view);
+    }
+}