@avantf/dsh-plugin-base 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qunqi.ff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# @avantf/dsh-plugin-base
+
+给 DSH 插件用的基础包，把三件容易各写一遍的事收在一起：**启动期资源预装**、**宿主兼容门禁**、
+**一组与 DSH 无关的共享工具**。
+
+- **运行期零依赖**：`dependencies` 为空，源码里连 `zod` 都不 import。
+- 唯一一条 peer 是 `zod`（`>=4.4.3 <5`），由宿主 / 上层提供，好让调用方、本包与宿主解析到**同一份**
+  `zod` —— 两份物理副本的 schema 身份不同，strict codec 会因此判不兼容。
+- 要求 **Node.js ≥ 22**。
+
+## 主要功能
+
+### 1. 资源预装（声明式 provisioner）
+
+调用方只写一份清单，其余交给框架：
+
+```
+声明 → 探测 → 获取 → 校验 → 报告
+```
+
+- 已经在盘上 / PATH 上的直接用，不重复下载；
+- 需要安装的由框架下载、校验完整性、**原子落盘**（同目录临时文件 + rename；跨进程一把族根锁）；
+- 每一项给出 `present / installed / skipped / failed`，失败带稳定 `code`；
+- 三种内置资源种类：`npm-package`、`binary-archive`、`model-cache`。新的种类 = 一个新的 provider，
+  核心不动；
+- 策略可配：离线、镜像、每项的并发与超时、启动预算、下载总闸。
+
+### 2. 宿主兼容门禁
+
+在挂载之前判断"当前宿主能不能跑这段代码"，语义是**只有被证实的不兼容才拒绝**：
+
+- 调用方交出自己真实的 contribution 与契约（服务、工具、方法、wire schema），由探针在**真实宿主**上验；
+- 说不清只是一条备注，版本差异只是警告，**绝不抛错**；
+- `compatReport(verdict, words)` 把裁决渲染成一份报告：**结构归本包，措辞归调用方**；
+- `registerMegaphone` 在拒绝加载的路径上留一条用户可见的命令（那时它是唯一的信息渠道）；
+- `verifyRegisteredFaces` 在挂载后复查"声明的每个 schema / 工具真的注册上了"（只告警）。
+
+### 3. 共享工具（kit）
+
+与 DSH 无关的纯逻辑，调用方在运行时复用：
+
+| 工具 | 作用 |
+| --- | --- |
+| `PromptFiles` | "缺失或空白就写入默认、有内容则逐字读回"的用户可编辑文本文件层（含崩溃残留的死临时文件清理） |
+| `createPluginLogger` | 带统一前缀、可镜像到宿主 logger 的 logger |
+| `familyHome` / `familyToolsDir` / `familyModelsDir` / `resolveDataHome` / `expandHome` | 家族根与数据根解析：**⑤ 显式 → ④ 环境变量 → ② 配置值 → 默认**，一律传**具名 slot** |
+| `strictCodec` / `endpointId` / `fieldSymbol` / `resultSymbol` | 组装 Typert wire 描述符的几行约定 |
+
+### 4. 接口世代
+
+`.` 上的导出构成本包的**接口**，由世代号冻结：
+
+- `INTERFACE_VERSION`（正整数）+ `api/interface-vN.json` 快照（该代的值名与类型名，随源码在仓库里，
+  不进产物）；
+- `checkInterface(required, module)`：把"调用方构建时所对的世代"与"运行时加载到的本包报告的世代"
+  比一比，返回 `ok` / `incompatible` / `cannot-tell`。纯函数、**双向**、读属性有守卫（取属性就抛的
+  对象读成"没报"）、**永不抛**；
+- `readInterfaceRequirement(url)`：读调用方产物里烘着的那条记录 `{ baseVersion, interfaceVersion }`；
+  缺失或畸形返回 `undefined`（"没烘"），不抛；
+- 拿到 `incompatible` 时的建议动作是**降级**（不使用本包的共享能力）而不是拒绝挂载 —— 本包只把裁决与
+  一句话的 `reason` 交出去，怎么处理由调用方决定。
+
+## 怎么用
+
+### 安装
+
+```bash
+npm install @avantf/dsh-plugin-base
+```
+
+### 预装资源
+
+```ts
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { Provisioner } from '@avantf/dsh-plugin-base'
+
+const home = join(homedir(), '.avantf', 'env')
+
+const provisioner: Provisioner = framework.createProvisioner({ home, logger })
+provisioner.register(framework.npmPackageProvider())
+provisioner.register(framework.binaryArchiveProvider())
+provisioner.register(framework.modelCacheProvider())
+provisioner.declare(manifest)
+
+// 挂载前必须就绪的项：阻塞等待
+await provisioner.ensure({ only: ['my-plugin:compat'], deadlineMs: 30_000 })
+
+// 其余项（含 background）后台预装，到达终态时回调
+void provisioner.ensure({
+  onSettled: entry => {
+    if (entry.id === 'my-plugin:model' && entry.action === 'installed') useModel()
+    if (entry.action === 'failed') logger.warn(`${entry.id}: ${entry.code}`)
+  },
+})
+```
+
+### 写清单
+
+```jsonc
+{
+  "plugin": "my-plugin",
+  "items": [
+    {
+      "id": "my-plugin:compat",
+      "kind": "npm-package",
+      "spec": { "name": "@scope/compat", "range": "^1.0.0" },
+      "target": { "root": "runtime" },
+      "startup": "blocking",
+      "schemaVersion": 1
+    },
+    {
+      "id": "my-plugin:tool",
+      "kind": "binary-archive",
+      "spec": {
+        "id": "tool", "version": "1.2.3",
+        "packs": { "linux-x64": { "url": "https://…/tool.tar.gz", "sha256": "<hex>" } }
+      },
+      "target": { "root": "tools" },
+      "onMissing": { "atStartup": "degrade", "atUse": "error" },
+      "schemaVersion": 1
+    },
+    {
+      "id": "my-plugin:model",
+      "kind": "model-cache",
+      "spec": { "repo": "org/name", "revision": "main", "layout": "flat", "files": ["config.json"] },
+      "target": { "root": "models" },
+      "startup": "background",
+      "schemaVersion": 1
+    }
+  ]
+}
+```
+
+- `startup`：`blocking`（缺省，`ensure` 等它）或 `background`（派发后不占启动预算）。
+- `onMissing.atStartup`：`degrade`（缺了也继续）/ `refuse`；`onMissing.atUse`：`degrade` / `error`。
+- `needs`：同一清单内其它 item 的 id。
+
+`model-cache` 的 `spec.layout` 决定文件怎么落盘：
+
+| layout | 落盘形态 | 谁读 |
+| --- | --- | --- |
+| `hub`（缺省） | `<root>/models--<org>--<name>/{blobs,refs,snapshots/<sha>/<file>}` 的内容寻址快照树 | 认这套缓存形状的客户端 |
+| `flat` | `<root>/<org>/<name>/<file>`，文件直接可读；revision 记录与 blob 在 `<root>/.envinit/` 侧车目录 | 直接按 `<repo>/<file>` 路径读取的运行时 |
+
+两种布局共用同一套 revision 解析、文件列表、模型 hub 端点、内容寻址 blob 与原子落盘；`config.json`
+在两种布局里都必需，`spec.requiredFiles` 在其上追加。已经落位但内容不对的条目（旧残留、指向错误 blob
+的链接、同名目录）会在下次落位时被换成指向正确 blob 的链接。
+
+`probe` 只做廉价的存在性判断（存在、不是目录、大小 > 0），不联网、不改盘；`verify` 才证明内容：
+`hub` 逐项核对链接目标、blob 名与内容哈希；`flat` 按侧车记录里的 sha256 逐项核对（只有文件名的旧记录
+仍然接受，不会把装好的树判成未安装）。落位与完成标记在同一把族根锁内完成。
+
+> **只增不减**：受管的模型数据不会回收。`blobs` 与 `snapshots` 永不删除，换一个 revision 就会再存一份；
+> `experimental().prune()` 只是打一条告警的 no-op。
+
+`endpoint` 默认是内置的模型 hub；`policy.mirrors.model` 可给一组镜像端点（按序尝试、内置端点兜底），
+`spec.endpoint` 优先于镜像。显式给出空白的 `endpoint`、非法的 `revision`（空、`.`、`..`、绝对路径、
+反斜杠、控制字符）都会报 `invalid-option`。
+
+```ts
+framework.createProvisioner({
+  home,
+  logger,
+  policy: { mirrors: { archive: [], model: ['https://mirror.example'] } },
+})
+```
+
+清单可以离线检查：
+
+```bash
+provision lint manifest.json
+```
+
+### 取用就绪资源
+
+```ts
+const state = provisioner.resolve('my-plugin:tool')
+if (state.state === 'ready') {
+  const entry = state.handle.dir      // 可用入口目录（归档：可执行文件所在目录）
+  const env = state.handle.env        // PATH 等环境增量
+}
+```
+
+`resolve()` 的五个状态：`ready` / `pending` / `failed` / `skipped` / `missing`。`ensure()` 返回的报告里
+`ok` **不**把"还在后台装"算成失败。
+
+### 跑兼容门禁
+
+```ts
+import { compatReport, gatherEvidence, verdictOf } from '@avantf/dsh-plugin-base'
+
+const verdict = verdictOf(gatherEvidence(ctx, spec))
+if (!verdict.load) {
+  log.error(compatReport(verdict, {
+    heading: '插件未加载：与当前宿主的兼容性检查未通过。',
+    warningsLabel: '风险提示：',
+    warnings: verdict.warnings,
+    fix: '升级宿主，或按本插件声明的版本重建。',
+    logPointer: prefix => `完整诊断见日志里 ${prefix} 开头的行。`,
+  }))
+}
+```
+
+### 取用共享工具
+
+```ts
+import { PromptFiles, createPluginLogger } from '@avantf/dsh-plugin-base'
+
+const log = createPluginLogger({ prefix: '@scope/my-plugin' })
+const files = new PromptFiles({ dir: join(dataHome, 'prompts'), logger: log })
+  .load([{ file: 'my-plugin-prompt.md', fallback: '内置默认正文\n' }])
+// files[0].text —— 用户写的正文（逐字），或刚写下的默认正文
+```
+
+### 运行时装载（`./bootstrap`）
+
+如果调用方要在**运行时**装载本包（而不是让它出现在自己的 import 图里），本包提供零依赖的
+`./bootstrap`：解析本包在哪 → 校验版本落在给定区间 → 动态 `import()`。它**不安装任何东西**，
+失败只返回 `undefined` 并给出原因。
+
+```ts
+import { loadFramework, readDependencyRange } from '@avantf/dsh-plugin-base/bootstrap'
+
+const range = await readDependencyRange(import.meta.url)   // 调用方自己声明的区间
+const framework = await loadFramework<typeof import('@avantf/dsh-plugin-base')>({ logger })
+if (framework === undefined) {
+  logger.warn('本包不可用，按自己的默认路径继续')
+} else {
+  // 用 framework.xxx
+}
+```
+
+有打包步骤时，本包提供构建预设把 `./bootstrap` 内联进产物、并断言产物里没有本包的静态引用：
+
+```ts
+import { envinitPreset, assertEnvinitArtifacts, assertEnvinitPresetChecks } from '@avantf/dsh-plugin-base/preset'
+
+const preset = envinitPreset({ external: [/* 自己的外部名白名单 */] })
+assertEnvinitPresetChecks(preset.checks)
+// bundler：external 用 preset.external，内联 preset.noExternal；产物写出后再断言：
+assertEnvinitPresetChecks(assertEnvinitArtifacts({
+  artifacts: ['dist/plugin.js'],
+  clientArtifacts: ['dist/client.js'],
+}))
+```
+
+### 写 provider（可选）
+
+新增资源种类 = 新增一个 provider（不动核心）。provider 是实现五个动作的 npm 包：
+
+```ts
+import type { Provider } from '@avantf/dsh-plugin-base'
+
+export const myProvider: Provider = {
+  id: '@scope/my-provider',
+  kinds: ['@scope/my-kind'],
+  identify: item => ({ name: '…', range: '…' }),
+  probe: async (item, ctx) => ({ found: false }),          // 只读、不联网
+  plan: () => ({ action: 'install' }),                     // 纯函数
+  targetDir: (_item, ref) => `${ref.name}/${ref.segment}`, // 安全相对路径
+  install: async (item, ctx) => ctx.publish(await ctx.stage(), { name: '…', version: '…' }),
+  verify: async (item, resolved, ctx) => { /* 证明能用 */ },
+}
+```
+
+用一致性套件跑一遍再发布：
+
+```ts
+import { assertProviderConformance, runProviderConformance } from '@avantf/dsh-plugin-base/conformance'
+
+const report = await runProviderConformance({ provider: myProvider, items: [...], packageName: '@scope/my-provider' })
+assertProviderConformance(report)
+```
+
+## 边界（不做的事）
+
+- **不做包管理器**：不推导传递依赖、不生成 lockfile、不做版本求解；每个 item 自包含。
+- **不接管原生模块**：`binding.gyp` / `*.node` / 依赖 `postinstall` 的包会被识别并拒绝。
+- **不跳过校验**：npm 包核对 `dist.integrity`，归档核对 `sha256`。
+- **不做进程内预热**：让文件在盘上是框架的事，读进内存是调用方自己的事。
+
+## 版本承诺
+
+- 承诺稳定的接口是 `.` 上的导出（值 + 类型）与 `./preset` / `./conformance` / `./bootstrap` 三个子路径；
+  `./internal` 是内部件，不承诺稳定。
+- **接口与包版本是两条轴**：接口换代只升 `INTERFACE_VERSION` 并新增 `api/interface-vN.json`；包版本是
+  普通 semver，只表达包自身（行为变更 minor、修复 patch）。
+- 顺序敏感的参数一律传**具名对象**（如 `resolveDataHome({ explicit, env, configured })`）；可观察的文案
+  由调用方给（如 `compatReport` 的 `words`）。
+
+## 开发
+
+```bash
+pnpm check          # 类型检查 + 测试
+pnpm build          # tsc → dist/
+pnpm pack           # 打包到 release/ 并断言产物
+pnpm release:check  # 发布门禁：typecheck → build → test → pack
+```
+
+## 许可
+
+MIT

package/dist/artifact.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Build-time artifact scanning.
+ * @module artifact
+ */
+/** The framework package name. */
+export declare const FRAMEWORK_PACKAGE = "@avantf/dsh-plugin-base";
+/** The one subpath a plugin build must inline rather than externalise. */
+export declare const BOOTSTRAP_SUBPATH = "@avantf/dsh-plugin-base/bootstrap";
+/** How a specifier was referenced, when it really is a module reference. */
+export type FrameworkImportKind = 'static' | 'side-effect' | 'dynamic' | 'require';
+export interface FrameworkImportRef {
+    readonly specifier: string;
+    readonly kind: FrameworkImportKind;
+    /** True for `@avantf/dsh-plugin-base/bootstrap` and anything under it. */
+    readonly bootstrap: boolean;
+    /** Byte offset of the specifier in the scanned text. */
+    readonly index: number;
+}
+/** True for the bootstrap subpath. */
+export declare function isBootstrapSpecifier(specifier: string): boolean;
+/** Control-plane literals of the framework's own implementation; counted once {@link MIN_INLINING_BEACONS} distinct names appear. */
+export declare const FRAMEWORK_INLINING_BEACONS: readonly string[];
+/** How many distinct beacons count as "the framework was inlined". */
+export declare const MIN_INLINING_BEACONS = 3;
+/** The inlining beacons present in one artifact. */
+export declare function findInliningBeacons(text: string): readonly string[];
+/** Every framework module reference in one emitted artifact, in source order. */
+export declare function findFrameworkImports(text: string): readonly FrameworkImportRef[];
+//# sourceMappingURL=artifact.d.ts.map

package/dist/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kCAAkC;AAClC,eAAO,MAAM,iBAAiB,4BAA4B,CAAA;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,sCAAmC,CAAA;AAEjE,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAA;AAElF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,sCAAsC;AACtC,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,qIAAqI;AACrI,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAOvD,CAAA;AAED,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,oDAAoD;AACpD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEnE;AAgBD,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CAYhF"}

package/dist/artifact.js

@@ -0,0 +1,60 @@
+/**
+ * Build-time artifact scanning.
+ * @module artifact
+ */
+/** The framework package name. */
+export const FRAMEWORK_PACKAGE = '@avantf/dsh-plugin-base';
+/** The one subpath a plugin build must inline rather than externalise. */
+export const BOOTSTRAP_SUBPATH = `${FRAMEWORK_PACKAGE}/bootstrap`;
+/** True for the bootstrap subpath. */
+export function isBootstrapSpecifier(specifier) {
+    return specifier === BOOTSTRAP_SUBPATH || specifier.startsWith(`${BOOTSTRAP_SUBPATH}/`);
+}
+/** Control-plane literals of the framework's own implementation; counted once {@link MIN_INLINING_BEACONS} distinct names appear. */
+export const FRAMEWORK_INLINING_BEACONS = [
+    '.status.lock',
+    '.layout.json',
+    '.quarantine',
+    '.envinit',
+    'status.json',
+    'declared.json',
+];
+/** How many distinct beacons count as "the framework was inlined". */
+export const MIN_INLINING_BEACONS = 3;
+/** The inlining beacons present in one artifact. */
+export function findInliningBeacons(text) {
+    return FRAMEWORK_INLINING_BEACONS.filter(beacon => text.includes(beacon));
+}
+const ESCAPED_PACKAGE = FRAMEWORK_PACKAGE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const SPECIFIER = new RegExp(`(['"])(${ESCAPED_PACKAGE}(?:/[^'"]*)?)\\1`, 'g');
+const WINDOW = 40;
+/** Classify a specifier by the token in front of the literal. */
+function classify(prefix) {
+    const trimmed = prefix.trimEnd();
+    if (/(?:^|[^\w$])import\s*\($/.test(trimmed))
+        return 'dynamic';
+    if (/require\s*\($/.test(trimmed))
+        return 'require';
+    if (/(?:^|[^\w$])from$/.test(trimmed))
+        return 'static';
+    if (/(?:^|[^\w$])import$/.test(trimmed))
+        return 'side-effect';
+    return undefined;
+}
+/** Every framework module reference in one emitted artifact, in source order. */
+export function findFrameworkImports(text) {
+    const found = [];
+    SPECIFIER.lastIndex = 0;
+    for (let match = SPECIFIER.exec(text); match !== null; match = SPECIFIER.exec(text)) {
+        const specifier = match[2];
+        if (specifier === undefined)
+            continue;
+        const index = match.index;
+        const kind = classify(text.slice(Math.max(0, index - WINDOW), index));
+        if (kind === undefined)
+            continue;
+        found.push({ specifier, kind, bootstrap: isBootstrapSpecifier(specifier), index });
+    }
+    return found;
+}
+//# sourceMappingURL=artifact.js.map

package/dist/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kCAAkC;AAClC,MAAM,CAAC,MAAM,iBAAiB,GAAG,yBAAyB,CAAA;AAE1D,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,iBAAiB,YAAY,CAAA;AAcjE,sCAAsC;AACtC,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,SAAS,KAAK,iBAAiB,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,iBAAiB,GAAG,CAAC,CAAA;AACzF,CAAC;AAED,qIAAqI;AACrI,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,cAAc;IACd,cAAc;IACd,aAAa;IACb,UAAU;IACV,aAAa;IACb,eAAe;CAChB,CAAA;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAA;AAErC,oDAAoD;AACpD,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,0BAA0B,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;AAC3E,CAAC;AAED,MAAM,eAAe,GAAG,iBAAiB,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA;AAChF,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,UAAU,eAAe,kBAAkB,EAAE,GAAG,CAAC,CAAA;AAC9E,MAAM,MAAM,GAAG,EAAE,CAAA;AAEjB,iEAAiE;AACjE,SAAS,QAAQ,CAAC,MAAc;IAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAA;IAChC,IAAI,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAA;IAC9D,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAA;IACnD,IAAI,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,QAAQ,CAAA;IACtD,IAAI,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,aAAa,CAAA;IAC7D,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,SAAS,CAAC,SAAS,GAAG,CAAC,CAAA;IACvB,KAAK,IAAI,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpF,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QAC1B,IAAI,SAAS,KAAK,SAAS;YAAE,SAAQ;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;QACzB,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;QACrE,IAAI,IAAI,KAAK,SAAS;YAAE,SAAQ;QAChC,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,oBAAoB,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;IACpF,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/bootstrap.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Resolve the framework copy the caller's tree already has.
+ * @module bootstrap
+ */
+/** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
+export declare const VERSION = "0.3.1";
+/**
+ * The framework interval this bootstrap can launch.
+ *
+ * Kept equal to the plugins' peer range for the base: the plugin passes no override, so THIS is the
+ * runtime gate. It is a plain comparator interval, NOT a caret: the package version is ordinary
+ * semver again and no longer tracks the interface, so the interval stays as wide as the family's
+ * compatibility promise — `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can
+ * consume, and stops at the major that invented a new interface generation. The interface itself is
+ * the separate, runtime axis: a base inside this interval whose `INTERFACE_VERSION` differs is judged
+ * by the base's own gate (INTERFACE.md §1, §3), which degrades rather than refusing.
+ */
+export declare const supportedRange = ">=0.3.0 <1.0.0";
+/** Sink for the warnings that replace a throw. */
+export interface BootstrapLogger {
+    warn(message: string): void;
+    info?(message: string): void;
+}
+/** What {@link ensureFramework} needs to accept the resolved copy. */
+export interface EnsureFrameworkOptions {
+    readonly logger?: BootstrapLogger;
+    /** Override the baked {@link supportedRange}. */
+    readonly supportedRange?: string;
+}
+/** The framework copy the caller's tree resolves to. */
+export interface FrameworkLocation {
+    /** A `file://` URL ready for `import()`. */
+    readonly url: string;
+    readonly version: string;
+    readonly dir: string;
+    /** Always `resolved`: the package manager's copy. */
+    readonly source: 'resolved';
+}
+/**
+ * Report the framework copy this caller's tree resolves to, or `undefined` with a warning.
+ * Never throws and never installs anything.
+ *
+ * @param options - the logger and an optional interval override.
+ * @returns the located copy, or `undefined` when it is absent or outside the interval.
+ */
+export declare function ensureFramework(options: EnsureFrameworkOptions): Promise<FrameworkLocation | undefined>;
+/** `ensureFramework` + a dynamic `import()` of the located module; never throws. */
+export declare function loadFramework<T = unknown>(options: EnsureFrameworkOptions): Promise<T | undefined>;
+/**
+ * Read the range a plugin declares in the nearest `package.json`: walk up from `from`,
+ * preferring `peerDependencies` over `devDependencies`; `undefined` when none is found.
+ */
+export declare function readDependencyRange(from?: string): Promise<string | undefined>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,yFAAyF;AACzF,eAAO,MAAM,OAAO,UAAU,CAAA;AAC9B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAI9C,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,iDAAiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AA8LD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAoC7G;AAED,oFAAoF;AACpF,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAaxG;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuCnG"}