@avantf/dsh-plugin-base 0.3.1

package/dist/types.d.ts

@@ -0,0 +1,431 @@
+/**
+ * The public data model.
+ * @module types
+ */
+import type { ProvisionCode } from './errors.js';
+/** The kinds the framework ships providers for; these names are reserved.
+ *  @stable */
+export type BuiltinKind = 'npm-package' | 'binary-archive' | 'model-cache';
+/** A kind is a namespaced string; third-party kinds must carry a prefix.
+ *  @stable */
+export type Kind = BuiltinKind | (string & {});
+/** What to do at mount time when the item is not ready.
+ *  @stable */
+export type AtStartup = 'degrade' | 'refuse';
+/** What to do when the item is used and is not ready.
+ *  @stable */
+export type AtUse = 'degrade' | 'error';
+/** Whether `ensure()` waits for an item at mount. Default `'blocking'`. */
+export type Startup = 'blocking' | 'background';
+/** Per-item strictness; each field defaults on its own, and an illegal value falls back per field.
+ *  @stable */
+export interface OnMissing {
+    readonly atStartup?: AtStartup;
+    readonly atUse?: AtUse;
+}
+/** Mirrors are split by distribution network.
+ *  @stable */
+export interface MirrorPolicy {
+    readonly archive: readonly string[];
+    readonly npm?: readonly string[];
+    /** Endpoints for `model-cache` items, tried before the built-in default endpoint. */
+    readonly model?: readonly string[];
+}
+/** Framework-known per-item policy; provider-private keys must be namespaced.
+ *  @stable */
+export interface ItemPolicy {
+    readonly mirrors?: MirrorPolicy;
+    readonly concurrency?: number;
+    readonly timeoutMs?: number;
+    readonly platforms?: readonly string[];
+    readonly [providerScopedKey: string]: unknown;
+}
+/** One resource a plugin needs; `target.root` is relative to `home` and carries no version.
+ *   @stable */
+export interface ProvisionItem {
+    /** Stable, plugin-namespaced item id. */
+    readonly id: string;
+    readonly kind: Kind;
+    /** Interpreted by the provider for this kind (npm range, packs, repository revision, …). */
+    readonly spec: unknown;
+    readonly target: {
+        readonly root: string;
+    };
+    readonly onMissing?: OnMissing;
+    /** Wait for it at mount, or dispatch it and report later. Default `'blocking'`. */
+    readonly startup?: Startup;
+    /** Other items in the **same** plugin this one needs first. */
+    readonly needs?: readonly string[];
+    readonly policy?: ItemPolicy;
+    /** Descriptor version. */
+    readonly schemaVersion: number;
+}
+/** What a plugin declares at startup.
+ *   @stable */
+export interface Manifest {
+    /** Plugin namespace; must match the item id prefix. */
+    readonly plugin: string;
+    readonly items: readonly ProvisionItem[];
+    readonly requires?: {
+        readonly capabilities?: readonly string[];
+        readonly providers?: readonly {
+            readonly package: string;
+            readonly kinds: readonly string[];
+        }[];
+    };
+}
+/** @stable */
+export type ResourceSource = 'resolved' | 'managed' | 'installed' | 'system' | 'explicit';
+/** A ready resource: where it is, what it is, and what env it contributes.
+ *   @stable */
+export interface ResourceHandle {
+    readonly id: string;
+    /** Normalised resource key `kind+name` — one half of the row identity. */
+    readonly key: string;
+    readonly kind: Kind;
+    readonly version?: string;
+    readonly source: ResourceSource;
+    /** The usable entry directory (npm: `<versionDir>/node_modules/<name>`). */
+    readonly dir: string;
+    /** Environment a child process needs (PATH, …). */
+    readonly env: Readonly<Record<string, string>>;
+}
+/** The five states `resolve()` can answer with.
+ *   @stable */
+export type ResourceState = {
+    readonly state: 'ready';
+    readonly handle: ResourceHandle;
+} | {
+    readonly state: 'pending';
+    readonly since: number;
+} | {
+    readonly state: 'failed';
+    readonly code: ProvisionCode;
+    readonly detail?: string;
+    readonly retryAfter?: number;
+} | {
+    readonly state: 'skipped';
+    readonly code: ProvisionCode;
+    readonly detail?: string;
+} | {
+    readonly state: 'missing';
+};
+/** @stable */
+export type PlanAction = 'present' | 'install' | 'skip' | 'unknown';
+/** @stable */
+export type ReportAction = 'present' | 'installed' | 'skipped' | 'failed';
+/** @stable */
+export interface PlanEntry {
+    readonly key: string;
+    readonly action: PlanAction;
+    readonly version?: string;
+    readonly source?: ResourceSource;
+    readonly urls?: readonly string[];
+}
+/** @stable */
+export interface Plan {
+    readonly entries: readonly PlanEntry[];
+    readonly offline: boolean;
+}
+/** @stable */
+export interface PlanOptions {
+    readonly only?: readonly string[];
+    readonly offline?: boolean;
+}
+/** @stable */
+export interface EnsureOptions {
+    readonly only?: readonly string[];
+    readonly offline?: boolean;
+    readonly signal?: AbortSignal;
+    /** This call's startup budget, overriding `policy.deadlineMs` for the call. */
+    readonly deadlineMs?: number;
+    /** Called **once per item** when it reaches a terminal state, with the same line the report
+     *  carries; a throw is logged and ignored. */
+    readonly onSettled?: (entry: ProvisionReportEntry) => void;
+    /** Byte-level progress from this call's installs, forwarded to `InstallContext.onProgress`. */
+    readonly onProgress?: (event: ProgressEvent) => void;
+}
+/** @stable */
+export interface ProvisionReportEntry {
+    readonly plugin: string;
+    readonly id: string;
+    readonly key: string;
+    readonly action: ReportAction;
+    readonly source: ResourceSource;
+    readonly version?: string;
+    readonly ms: number;
+    readonly code?: ProvisionCode;
+    readonly reason?: string;
+}
+/** @stable */
+export interface ProvisionReport {
+    readonly entries: readonly ProvisionReportEntry[];
+    readonly ok: boolean;
+}
+/** One row of `status()`; the row identity is `key × version`.
+ *   @stable */
+export interface ProvisionStatus {
+    readonly key: string;
+    /** Part of the row identity; the empty string until a version has been resolved. */
+    readonly version: string;
+    readonly items: readonly string[];
+    readonly plugins: readonly string[];
+    readonly state: ResourceState;
+    readonly source?: ResourceSource;
+    readonly updatedAt: number;
+    readonly lastError?: {
+        readonly code: ProvisionCode;
+        readonly detail?: string;
+        readonly retryAfter?: number;
+    };
+}
+/** Late-arrival and reporting notifications; the union narrows on `type`.
+ *   @stable */
+export type ProvisionEvent = {
+    readonly type: 'availability';
+    readonly key: string;
+    readonly state: ResourceState;
+} | {
+    readonly type: 'report';
+    readonly key: string;
+    readonly entry: ProvisionReportEntry;
+};
+/** @stable */
+export interface ProvisionPolicy {
+    /** Whether automatic download is allowed: overall, or per-kind override. Default `true`. */
+    readonly autoDownload?: boolean | Partial<Record<string, boolean>>;
+    /** Maps a kind to the provider that claims it; the only way to lift a `provider/conflict`. */
+    readonly kindProviders?: Readonly<Record<string, string>>;
+    readonly mirrors?: MirrorPolicy;
+    readonly packumentMirrors?: readonly string[];
+    /** Startup critical-path budget in ms. Default 15 000. */
+    readonly deadlineMs?: number;
+    readonly quotaBytes?: number;
+    /** Grace period before `.trash` entries may be removed. Default 7 days. */
+    readonly trashGraceMs?: number;
+    readonly gc?: 'off' | 'background';
+    /** Offline/preloaded source directories. */
+    readonly preloaded?: readonly string[];
+}
+/** @stable */
+export interface ProvisionLogger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+/** Byte-level progress, only on request.
+ *  @experimental */
+export interface ProgressEvent {
+    readonly key: string;
+    readonly phase: 'download' | 'extract';
+    readonly loaded: number;
+    readonly total?: number;
+}
+/** @stable */
+export interface Disposable {
+    dispose(): void;
+}
+/** Data-plane IO. Every mutation goes through this seam.
+ *   @stable */
+export interface ProvisionFs {
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    /** Same-directory temp file + rename; metadata such as `install.json` must use it. */
+    atomicWrite(path: string, data: Uint8Array): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    readdir(path: string): Promise<readonly string[]>;
+    stat(path: string): Promise<{
+        size: number;
+        mtimeMs: number;
+        isDirectory: boolean;
+        mode: number;
+    } | undefined>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    /** The link target when `path` is a symlink, else `undefined`. */
+    readlink(path: string): Promise<string | undefined>;
+    copyFile(from: string, to: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+/** Control-plane mutual exclusion; the default is `<home>/.envinit/.lock`.
+ *   @stable */
+export interface ProvisionLock {
+    acquire(path: string, options: {
+        timeoutMs: number;
+        staleMs: number;
+    }): Promise<Disposable>;
+}
+/** @stable */
+export interface ProvisionerOptions {
+    /** Family root. Default `~/.avantf/env`. */
+    readonly home?: string;
+    /** Built-in layout name. Default `v1`. */
+    readonly layout?: string;
+    /** The framework range this plugin declared (`peerDependencies`, read with
+     *  `readDependencyRange`); an unsatisfied range skips every declared item. */
+    readonly envinitRange?: string;
+    readonly policy?: ProvisionPolicy;
+    readonly logger: ProvisionLogger;
+    readonly fetch?: typeof fetch;
+    readonly fs?: ProvisionFs;
+    readonly lock?: ProvisionLock;
+    readonly clock?: () => number;
+}
+/** The resource identity a provider assigns to an item; the core rejects a provider-supplied key.
+ *  @stable */
+export interface ResourceIdentity {
+    readonly name: string;
+    /** The selection range/fingerprint, when the kind has one (npm range, repository revision, …). */
+    readonly range?: string;
+}
+/** @stable */
+export type ProbeResult = {
+    readonly found: true;
+    readonly version?: string;
+    readonly dir: string;
+    readonly source: ResourceSource;
+    /** Environment additions for the handle (a managed binary's PATH). */
+    readonly env?: Readonly<Record<string, string>>;
+} | {
+    readonly found: false;
+};
+/** @stable */
+export interface PublishMeta {
+    readonly name: string;
+    readonly version: string;
+    readonly integrity?: string;
+    readonly tarball?: string;
+    readonly source?: ResourceSource;
+    /** The executable's path relative to the version directory (archive kinds). */
+    readonly entry?: string;
+    /** The usable entry **directory**, relative to the version directory (npm: `node_modules/<name>`). */
+    readonly entryDir?: string;
+}
+/** What a completed install published: the version directory plus its identity.
+ *  @stable */
+export interface Resolved {
+    /** The normalised resource key; filled by the core, so a provider that does not publish may omit it. */
+    readonly key?: string;
+    readonly name: string;
+    readonly version: string;
+    /** The **version directory** (published unit). */
+    readonly dir: string;
+    /** The usable entry directory. */
+    readonly entryDir: string;
+    readonly integrity?: string;
+    readonly source: ResourceSource;
+    /** Environment additions for the handle (a managed binary's PATH). */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/** @stable */
+export interface ProviderContext {
+    readonly home: string;
+    readonly logger: ProvisionLogger;
+    readonly policy: ProvisionPolicy;
+    /** The data-plane seam the core uses. */
+    readonly fs: ProvisionFs;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    /** The core's control-plane lock, so a provider that places files itself can serialise. */
+    readonly lock?: ProvisionLock;
+}
+/** Providers never hold the publish lock: download outside, publish through the core.
+ *   @stable */
+export interface InstallContext extends ProviderContext {
+    /** A fresh staging directory under `<home>/.envinit/.tmp/`. */
+    stage(): Promise<string>;
+    /** Core writes `install.json` here, then renames the staging tree to the version directory. */
+    publish(staging: string, meta: PublishMeta): Promise<Resolved>;
+    onProgress?(event: ProgressEvent): void;
+}
+/** A provider's plan for one item; the core wraps it into a {@link PlanEntry}.
+ *   @stable */
+export interface ProviderPlan {
+    readonly action: PlanAction;
+    readonly version?: string;
+    readonly urls?: readonly string[];
+}
+/** @stable */
+export interface Provider {
+    /** Provider identity; a third-party provider must use its npm package name. */
+    readonly id: string;
+    /** Kinds it claims; third-party kinds must be namespaced. */
+    readonly kinds: readonly string[];
+    /** The resource identity used to build the normalised key. */
+    identify(item: ProvisionItem): ResourceIdentity;
+    /** Cheap presence/version check. Never downloads, never mutates. */
+    probe(item: ProvisionItem, ctx: ProviderContext): Promise<ProbeResult>;
+    /** What would be done, as data (pure; no disk, no network). */
+    plan(item: ProvisionItem, ctx: ProviderContext): ProviderPlan | Promise<ProviderPlan>;
+    /** The **version directory** relative path under `item.target.root` (safe, no `..`). */
+    targetDir(item: ProvisionItem, ref: {
+        readonly name: string;
+        readonly version: string;
+        readonly segment: string;
+    }): string;
+    /** Download/extract outside the lock and publish through `ctx.publish()`. */
+    install(item: ProvisionItem, ctx: InstallContext): Promise<Resolved>;
+    /** Prove the result is usable; the core quarantines the directory when this throws. */
+    verify(item: ProvisionItem, resolved: Resolved, ctx: ProviderContext): Promise<void>;
+}
+/** What the core writes into every version directory.
+ *   @stable */
+export interface InstallManifest {
+    readonly schemaVersion: number;
+    readonly name: string;
+    readonly version: string;
+    readonly dir: string;
+    readonly integrity?: string;
+    readonly tarball?: string;
+    readonly entry?: string;
+    /** The usable entry directory relative to the version directory (npm: `node_modules/<name>`). */
+    readonly entryDir?: string;
+    readonly installed_at: string;
+    readonly source: ResourceSource;
+    readonly layout: string;
+}
+/** What to keep when reclaiming versions.
+ *  @experimental */
+export interface PrunePolicy {
+    /** Keep the newest N versions per resource. */
+    readonly keepVersions?: number;
+    /** Keep versions younger than M days. */
+    readonly keepDays?: number;
+    /** Family-root quota, counting `.trash`. Same name and meaning as `ProvisionPolicy.quotaBytes`. */
+    readonly quotaBytes?: number;
+    /** Reclaim versions nothing currently declares. Off by default. */
+    readonly orphan?: boolean;
+}
+/** What a prune moved aside; `movedBytes` is the moved amount, not the released amount.
+ *  @experimental */
+export interface PruneReport {
+    readonly moved: readonly string[];
+    readonly skipped: readonly string[];
+    readonly movedBytes: number;
+}
+/** Experimental members; reaching them requires `experimental()`.
+ *  @experimental */
+export interface ProvisionerExperimental {
+    /** No-op in this build: reclamation is not implemented, so it warns and reports nothing. */
+    prune(policy?: PrunePolicy): Promise<PruneReport>;
+    on(event: 'availability' | 'report', listener: (event: ProvisionEvent) => void): Disposable;
+}
+/** The composition root; every member here is **stable**. Experimental members live on
+ *  {@link ProvisionerExperimental}. */
+export interface Provisioner {
+    register(provider: Provider): Disposable;
+    declare(manifest: Manifest): void;
+    plan(options?: PlanOptions): Promise<Plan>;
+    ensure(options?: EnsureOptions): Promise<ProvisionReport>;
+    resolve(itemId: string): ResourceState;
+    status(): readonly ProvisionStatus[];
+    repair(itemId: string): Promise<ProvisionReport>;
+    experimental(): ProvisionerExperimental;
+    /** Abort work still in flight and drop subscriptions; the instance is not reused. */
+    dispose(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/zip.d.ts

@@ -0,0 +1,8 @@
+import type { ProvisionFs } from './types.js';
+export interface ZipExtractOptions {
+    /** Drop this many leading path segments. */
+    readonly strip?: number;
+}
+/** Extract an in-memory zip into `destination`, rejecting any traversal attempt. */
+export declare function extractZip(archive: Uint8Array, destination: string, fs: ProvisionFs, options?: ZipExtractOptions): Promise<void>;
+//# sourceMappingURL=zip.d.ts.map

package/dist/zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../src/zip.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA+F7C,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,oFAAoF;AACpF,wBAAsB,UAAU,CAC9B,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,WAAW,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/zip.js

@@ -0,0 +1,109 @@
+/**
+ * A minimal zero-dependency `zip` reader (stored + deflate) with path-traversal checks.
+ * @module zip
+ */
+import { dirname, join } from 'node:path';
+import { inflateRawSync } from 'node:zlib';
+import { ProvisionError } from './errors.js';
+import { safeEntryPath } from './tar.js';
+/** Hard cap for one decompressed entry. */
+const MAX_UNPACKED_BYTES = 1024 * 1024 * 1024;
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+const ZIP64_MARKER = 0xffffffff;
+function readU16(bytes, offset) {
+    return (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8);
+}
+function readU32(bytes, offset) {
+    return ((bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8) | ((bytes[offset + 2] ?? 0) << 16) | ((bytes[offset + 3] ?? 0) << 24)) >>> 0;
+}
+/** Locate the end-of-central-directory record, scanning back over a possible comment. */
+function findEndOfCentralDirectory(bytes) {
+    const earliest = Math.max(0, bytes.length - 65_557);
+    for (let offset = bytes.length - 22; offset >= earliest; offset -= 1) {
+        if (readU32(bytes, offset) === EOCD_SIGNATURE)
+            return offset;
+    }
+    throw new ProvisionError('extract/failed', 'zip 缺少中央目录记录（不是有效的 zip？）');
+}
+function readCentralDirectory(bytes) {
+    const eocd = findEndOfCentralDirectory(bytes);
+    const count = readU16(bytes, eocd + 10);
+    const directorySize = readU32(bytes, eocd + 12);
+    const directoryOffset = readU32(bytes, eocd + 16);
+    if (directoryOffset === ZIP64_MARKER || directorySize === ZIP64_MARKER) {
+        throw new ProvisionError('extract/failed', '不支持 ZIP64 归档');
+    }
+    const entries = [];
+    let cursor = directoryOffset;
+    for (let index = 0; index < count; index += 1) {
+        if (readU32(bytes, cursor) !== CENTRAL_SIGNATURE) {
+            throw new ProvisionError('extract/failed', `zip 中央目录第 ${String(index)} 条签名不对`);
+        }
+        const method = readU16(bytes, cursor + 10);
+        const compressedSize = readU32(bytes, cursor + 20);
+        const uncompressedSize = readU32(bytes, cursor + 24);
+        const nameLength = readU16(bytes, cursor + 28);
+        const extraLength = readU16(bytes, cursor + 30);
+        const commentLength = readU16(bytes, cursor + 32);
+        const localOffset = readU32(bytes, cursor + 42);
+        const name = new TextDecoder().decode(bytes.subarray(cursor + 46, cursor + 46 + nameLength));
+        if (compressedSize === ZIP64_MARKER || uncompressedSize === ZIP64_MARKER) {
+            throw new ProvisionError('extract/failed', `不支持 ZIP64 条目：${name}`);
+        }
+        entries.push({ name, method, compressedSize, uncompressedSize, localOffset });
+        cursor += 46 + nameLength + extraLength + commentLength;
+    }
+    return entries;
+}
+/** Read one entry's bytes, following its local header for the actual data offset. */
+function readEntry(bytes, entry) {
+    const local = entry.localOffset;
+    if (readU32(bytes, local) !== LOCAL_SIGNATURE) {
+        throw new ProvisionError('extract/failed', `zip 本地头签名不对：${entry.name}`);
+    }
+    const nameLength = readU16(bytes, local + 26);
+    const extraLength = readU16(bytes, local + 28);
+    const start = local + 30 + nameLength + extraLength;
+    const end = start + entry.compressedSize;
+    const raw = bytes.subarray(start, end);
+    if (entry.method === 0)
+        return raw;
+    if (entry.method === 8) {
+        try {
+            const inflated = new Uint8Array(inflateRawSync(raw, { maxOutputLength: MAX_UNPACKED_BYTES }));
+            // The inflated size must equal the declared uncompressed size.
+            if (inflated.byteLength !== entry.uncompressedSize) {
+                throw new ProvisionError('extract/failed', `zip 条目 ${entry.name} 的实际大小 ${String(inflated.byteLength)} 与头部声明 ${String(entry.uncompressedSize)} 不符`);
+            }
+            return inflated;
+        }
+        catch (error) {
+            throw new ProvisionError('extract/failed', `zip 解压失败：${entry.name}（${error instanceof Error ? error.message : String(error)}）`);
+        }
+    }
+    throw new ProvisionError('extract/failed', `不支持的 zip 压缩方法 ${String(entry.method)}：${entry.name}`);
+}
+/** Extract an in-memory zip into `destination`, rejecting any traversal attempt. */
+export async function extractZip(archive, destination, fs, options = {}) {
+    await fs.mkdir(destination);
+    for (const entry of readCentralDirectory(archive)) {
+        const relative = safeEntryPath(entry.name);
+        if (relative === undefined)
+            continue;
+        const parts = relative.split('/');
+        const strip = options.strip ?? 0;
+        if (parts.length <= strip)
+            continue;
+        const stripped = parts.slice(strip).join('/');
+        const target = join(destination, ...stripped.split('/'));
+        if (entry.name.endsWith('/')) {
+            await fs.mkdir(target);
+            continue;
+        }
+        await fs.mkdir(dirname(target));
+        await fs.writeFile(target, readEntry(archive, entry));
+    }
+}
+//# sourceMappingURL=zip.js.map

package/dist/zip.js.map

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