dsh-plugin-update 0.2.0 → 0.3.1

package/dist/host.d.ts

@@ -0,0 +1,129 @@
+import { type PhoneAction, type UpdateConfigInput } from './config.js';
+import type { EnvironmentKind, ReleaseChannel } from './ports.js';
+import { type UpdateQueueState } from './queue.js';
+export { buildPhoneName, buildPhoneNames, resolveUpdateConfig } from './config.js';
+export type { PhoneAction, UpdateConfigInput } from './config.js';
+export { parseEventListManifest, checkEventFields, checkEventCounts } from './gate.js';
+export type { GateEventLevel, GateEventKind, GateEventEntry, GateEventCounts, GateEventList, GateFieldCheck, GateCountCheck } from './gate.js';
+export { containingPackage, defaultHomeDir, profileNameValid, registrySpec, resolveTargetPackage } from './reader.js';
+export { COPY_BUDGET_CHARS, DETAIL_MAX_CHARS, DIAG_DROP_ORDER, DIAG_INLINE_BUDGET_BYTES, DIAG_NEVER_DROP_KEYS, ENDORSED_REGISTRY_HOSTS, KNOWN_GAP_FILE_URL_PREFIX, REDACTED_PATH, REDACTED_SECRET, REDACTION_RULE_NAMES, diagByteLength, enforceDiagBudget, resolveRegistryHost, sanitizeDetail, sanitizeForCopy, truncateToWordBoundary, } from './redaction.js';
+export type { DiagDropKey, RedactionRuleName } from './redaction.js';
+export { DIAG_ACTIONS, DIAG_KEYS, DIAG_KNOWN_TYPES, DIAG_STAGE_EXPECT, DIAG_STAGES, DIAG_VERSION, buildDiag, deriveAction, deriveRouteMethod, deriveStage, enforceBudget as enforceDiagBudgetForPhone, } from './diag.js';
+export type { DiagAction, DiagInput, DiagObject, DiagStage } from './diag.js';
+export { CHANGELOG_ALL_CATEGORIES, CHANGELOG_FILENAME, CHANGELOG_FOLDED, CHANGELOG_MAX_BULLETS_PER_SECTION, CHANGELOG_MAX_BULLET_CHARS, CHANGELOG_MAX_CHARS, CHANGELOG_MAX_ENTRIES, CHANGELOG_MUST_SHOW, CHANGELOG_NEUTRAL_HINT, CHANGELOG_NEUTRAL_LINE, changelogForUpdate, hasVisibleSections, isUnreleasedVersion, parseChangelog, renderChangelogHTML, renderChangelogNeutral, renderChangelogSection, selectChangelogEntries, } from './changelog.js';
+export type { ChangelogCategory, ChangelogEntry } from './changelog.js';
+export { CHANGELOG_DEFAULT_REGISTRY, CHANGELOG_FETCH_MAX_BYTES, CHANGELOG_TAR_MAX_BYTES, CHANGELOG_TARBALL_MAX_BYTES, extractChangelogFromTar, fetchReleaseChangelogText, readInstalledChangelogText, } from './changelog-io.js';
+export type { ReleaseChangelogRef } from './changelog-io.js';
+export { createUpdateDiskPorts, createUpdateExecutor, pathsForUpdate, resolveCliEntry } from './store.js';
+export { SKIPPED_FILE } from './config.js';
+export { addSkipped, clearSkipped, createSkipDiskPorts, isVersionSkipped, MAX_SKIPPED_ENTRIES, normalizeSkipped, skipKey, type SkippedVersionEntry, } from './store.js';
+export { compareReleaseVersions, isPrereleaseVersion, isVersionAllowedInChannel, validReleaseVersion, validVersion, compareVersions, } from './service.js';
+export type { ReleaseChannel } from './ports.js';
+export { createUpdateQueuePorts, queuePathsForUpdate, QUEUE_DIR_SEGMENT, QUEUE_FILE, QUEUE_LOCK_FILE, QUEUE_LOCK_STALE_MS, } from './store.js';
+export { QUEUE_INTENT_TTL_MS, cancelEnqueuedInQueue, emptyQueueState, enqueueInQueue, isHeadOfQueue, normalizeQueueState, pruneExpiredIntents, queuePositionOf, releaseOwnerInQueue, setOwnerIfFree, visibleQueueFor, } from './queue.js';
+export type { QueuedEntry, QueueOwner, UpdateQueueState, VisibleQueue } from './queue.js';
+/**
+ * 宿主种类按能力判定，顺序固定（写死是为了将来宿主形态收敛时行为可预测）：
+ *   1. 有 `desktopProfiles` 服务 → `desktop`（第三方 Desktop，launcher 在 Loader entry 挂载前注册）；
+ *   2. 否则有 `pluginManager.installBundle`、且使用范围名恰是命令行明确封禁的 `desktop`
+ *      → `desktop-manager`（官方桌面版：命令行那条对这个使用范围一定失败）；
+ *   3. 其余 → `cli`。
+ *
+ * 第 2 条不是拿名字猜宿主身份，而是用**命令行自己的拒绝规则**判断这条路封没封：
+ * `dsh` 在 boot 与 plugin 子命令都按名字（大小写不敏感）拒绝 `--profile desktop`，
+ * 唯一豁免是桌面自带的 CLI 载体。名字由调用方按 resolveProfileName 的同一口径给出；
+ * 不传名字时只认第 1、3 条，绝不猜。
+ */
+export declare function detectEnvironmentKind(ctx: unknown, profileName?: string | null): EnvironmentKind;
+export interface ReaderOverrides {
+    env?: Record<string, string | undefined>;
+    osHome?: string;
+    runningVersion?: string;
+    profileDir?: string;
+    profileName?: string | null;
+    homeDir?: string;
+    environmentKind?: EnvironmentKind;
+    ctx?: unknown;
+    fetchImpl?: (url: string, init?: Record<string, unknown>) => Promise<never>;
+    now?: () => number;
+    /**
+     * 编号发生器（测试与特殊宿主可换）。
+     * **契约：同一个使用范围（同一队列文件）内，注入值必须全局唯一** —— 队列的拥有者账本按
+     * (pluginId, jobId) 认人；若给多个目标注入同一个编号，会被记串（#27 里一个夹具就这么撞过）。
+     * 生产走 randomUUID，不会撞；写测试夹具时请按目标派生（如 'id-' + key + '-' + n）。
+     */
+    randomId?: () => string;
+    nodeVersion?: string;
+    targetPackageName?: string;
+    registryUrl?: string;
+    checkTimeoutMs?: number;
+    confirmationTtlMs?: number;
+    installTimeoutMs?: number;
+    /** 版本通道：默认走配置的通道，显式覆盖供测试与特殊宿主用（#16）。 */
+    releaseChannel?: ReleaseChannel;
+    /** 队列意向有效期毫秒：默认 10 分钟（#15），须为有限大于 0 的数才生效，否则走默认。 */
+    queueTtlMs?: number;
+    /** 跨插件队列的显式假件（测试用；给了 readQueue + writeQueue 即不走真实队列目录，#15）。 */
+    readQueue?: () => UpdateQueueState | Promise<UpdateQueueState>;
+    writeQueue?: (state: UpdateQueueState) => void | Promise<void>;
+    /**
+     * 抢全局锁的显式覆盖（测试与特殊宿主用）。
+     * 第三参是**锁陈旧判据的时限**，与安装时限同源——阈值只由这一处决定，别再让覆盖实现自己拍一个；
+     * 不接这个参数的旧实现行为一字不变（TS 允许少接参数）。
+     */
+    tryAcquireGlobalLock?: (lockId: string, pluginId: string, opts?: {
+        timeoutMs?: number;
+    }) => boolean | Promise<boolean>;
+    releaseGlobalLock?: (lockId: string) => void | Promise<void>;
+    readInstalled?: () => Promise<import('./ports.js').EnvironmentView>;
+    readJob?: () => Promise<import('./ports.js').UpdateJob | null>;
+    writeJob?: (job: import('./ports.js').UpdateJob | null) => Promise<void>;
+    tryAcquireLock?: (lockId: string) => boolean | Promise<boolean>;
+    releaseLock?: (lockId: string) => void | Promise<void>;
+    backupJob?: (job: import('./ports.js').UpdateJob) => void | Promise<void>;
+    runInstall?: (args: {
+        version: string;
+        profileName: string | null;
+        environmentKind: EnvironmentKind;
+    }) => any;
+    subprocess?: unknown;
+    desktopPnpm?: unknown;
+    desktopProfiles?: unknown;
+    /** 官方桌面版进程内的插件管理器（显式覆盖用；不传就从 ctx 现取）。 */
+    pluginManager?: unknown;
+    runtimeExecutable?: string;
+    runtimeExecArgs?: string[];
+    cliEntry?: string;
+    /** 显式目标包目录：优先于按包名自动解析（hoisted、多副本、开发态链接等场景的逃生口）。 */
+    targetPackageDir?: string;
+}
+/**
+ * 面板要的一栏「装到哪个使用范围」：只回**使用范围名**与宿主种类，绝不回目录路径。
+ * 为什么重要：同一个插件在 web / desktop 两个使用范围里各装一份，更新必须落到当前这一份；
+ * 面板把这栏显示出来，用户才知道自己点的是哪个范围的更新（也才能对上 `--profile` 那一段）。
+ * 走 includeEnv 选填（与 includeQueue 同一套口径）：老调用不带这个参数，回包形状一字不变。
+ */
+export interface PhoneEnvView {
+    profileName: string | null;
+    environmentKind: string | null;
+}
+type LogCtx = {
+    fire: (level: string, event: string, fields: Record<string, unknown>) => void;
+} | null;
+export interface HostUpdate {
+    phoneNames: Record<PhoneAction, string>;
+    handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
+}
+/**
+ * 建宿主更新能力：一次调用得到该插件的一组电话名与处理器（调用方负责注册进自己的电话表）。
+ * 配置只经函数入参注入（冻结写法，第 11 条），插件标识必填，其余可选。
+ */
+export declare function createHostUpdate(deps: {
+    ctx?: unknown;
+    logCtx?: LogCtx;
+    desktopPnpm?: unknown;
+    pluginManager?: unknown;
+    readerOverrides?: ReaderOverrides;
+} | undefined, configInput: UpdateConfigInput): HostUpdate;
+/** 测试与门禁复位单例（正常运行不调用，规格 #591 第 6 条保留）。 */
+export declare function __resetSharedUpdateReaderForTests(): void;