@mearl/preset 3.0.0-beta.8 → 3.0.0

package/README.en.md

@@ -0,0 +1,108 @@
+# @mearl/preset
+
+[简体中文](README.md) | [English](README.en.md)
+
+Use a Preset to distribute a configured set of Mearl capabilities, Skills, and Providers. This package resolves the manifest and prepares the resources that browser and Node hosts use.
+
+See the [capability model](../../docs/capability-model.en.md) for 3.x declarations, configuration, catalogs, and object storage. Contributions infer supported targets; optional Preset `targets` selects a subset. Operations and logins belong to packages; configuration overrides belong to Presets and users.
+
+See [browser bundles](../../docs/browser-bundles.en.md) for preparation and local storage, and [browser Presets](../../docs/browser-presets.en.md) for atomic activation and App implementation mappings. Both are exported through `@mearl/preset/bundles`.
+
+Browser and Node share one inheritance resolution and resource download; see [complete resource preparation](../../docs/preset-preparation.en.md). `preparePreset` returns the full exact graph and a compatible browser projection. Node module selection reuses the same bytes. Preparation executes no code and installs no external environment.
+
+The main entry shares preset validation and inheritance resolution across browsers and Node, without filesystem, network, credential, or browser permission side effects. Callers supply manifest loading. Optional `@mearl/preset/bundles` provides resource validation, bounded downloads, and explicitly invoked browser-local storage; see [browser bundles](../../docs/browser-bundles.en.md).
+
+```ts
+import { resolvePreset, mergePresetDefaults } from '@mearl/preset';
+
+const preset = await resolvePreset('https://example.com/presets/team.json', {
+  mearlApiVersion: '1.0.0',
+  async load(source) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Preset load failed: ${response.status}`);
+    return response.json();
+  },
+});
+
+const effectiveSettings = mergePresetDefaults(preset.defaults, userSettings);
+```
+
+Loaders check source policy, response size, redirects, authentication, and cancellation; the example only demonstrates the contract. Browser loaders should restrict URLs according to product source policies. The resolver does not automatically trust HTTP(S)/file URLs.
+
+See [Node capabilities](../../docs/node-capabilities.en.md) for module snapshots and host loading contracts.
+
+## Manifest
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "team",
+  "version": "1.0.0",
+  "extends": { "source": "../base/preset.json", "version": "^1" },
+  "requires": { "mearlApi": "^1" },
+  "packages": {
+    "capture": { "source": "./capture/package.json", "targets": ["browser"] },
+    "unused": { "enabled": false }
+  },
+  "skills": {},
+  "providers": {},
+  "defaults": { "simulation": { "app": "sample" } },
+  "permissions": { "origins": ["https://*.example.com/*"] }
+}
+```
+
+- Single inheritance, at most 32 levels; cycles and unmet parent version/API requirements are rejected. `version` is exact semver; component `version` is a version requirement, with concrete installation versions resolved by installers.
+- packages, skills, and providers merge by ID; child fields override the same ID, while arrays replace entirely. Enabled entries must ultimately have a source; `enabled:false` retains a disabled declaration.
+- Component `dependsOn` references IDs of the same component type. The final inherited graph checks missing, disabled, and cyclic dependencies. This does not establish runtime compatibility or completed installation.
+- source resolves relative to the declaring manifest. A child changing only the version does not alter an inherited source's base URL.
+- Skills may declare up to 16 previous sources in `migrateFrom`, resolved relative to the declaring manifest. Children replace the whole list; an empty array clears it. Installers migrate only with a matching source receipt, valid Skill identity, and setup ownership of all associated plugins. Manual registrations, shared manual aliases, and other sources remain and report conflicts. Source matching still checks refs strictly.
+- defaults recursively merges objects; arrays, scalars, and null replace values. User overrides are saved separately and applied to the resolved result.
+- Permissions are aggregated and deduplicated as requirements only; browser installers obtain actual authorization separately.
+- appProfiles maps App IDs to implementation identifiers. Later capability catalogs verify profile existence and package executability; the resolver does not claim simulation validation.
+- Results retain the exact parent-to-child version chain and each component's latest declaration source. Loading failures do not produce partial success.
+- Unknown fields, non-JSON configuration, and prototype-pollution keys are rejected. Total manifests are limited to 256 Ki UTF-16 code units; defaults nesting to 32 levels.
+
+This package owns generic manifest parsing, validation, and resource graphs, without installation or UI. Browser hosts and setup own full installation, preset lock persistence, permissions, registration, and activation; see the [installation host](../../docs/preset-installation.en.md). Bundle-local storage transactionally replaces validated snapshots.
+
+The Skill manager's optional `readSources(scope, cwd)` returns manager-verified source receipts matching setup's `TrackedSkillSource`. CLI and Native installation status share this reader. Managers persist, validate, and invalidate their supplementary records; public hosts still verify sources, refs, manifest identity, and managed ownership. Without it, the standard Skills lockfile is read.
+
+## Tool catalogs
+
+Presets can register additional installable tool catalogs through `defaults.extension.toolCatalogs`:
+
+```json
+{
+  "defaults": {
+    "extension": {
+      "toolCatalogs": {
+        "team": {
+          "url": "https://tools.example.com/toolbox.json",
+          "label": "Team"
+        }
+      }
+    }
+  }
+}
+```
+
+Use absolute HTTPS URLs (loopback HTTP is allowed for local development), with at most 16 catalogs. Use stable IDs; child presets can override only `url` or `label`, or disable a parent catalog with `enabled: false`. The official catalog always remains first; `official` is reserved. Declare cross-origin domains in `permissions.origins` and obtain access through the existing authorization flow.
+
+Catalog JSON shares the official structure, limited to 256 entries and 256 KiB:
+
+```json
+{
+  "tools": [{
+    "id": "plugin:team-tool",
+    "plugin": "team-tool",
+    "repository": "example/skills",
+    "skill": "team-tool",
+    "title": "Team tool",
+    "description": "A tool for the team",
+    "icon": "wrench"
+  }]
+}
+```
+
+`repository` also supports HTTPS/SSH Git sources and pinned refs such as `git@code.example.com:team/skills.git#release/v3`, passed unchanged to the preset-selected Skills manager. Manifests reject shell arguments, credentials, and local paths, and execute no embedded code. Listing tools does not install them.
+
+Sources load concurrently and cache independently. Retry refreshes the current catalog; failure retains its cache without blocking other sources. Identical plugin IDs and sources deduplicate. Conflicting repositories or Skills for one ID retain the higher-priority catalog and report a conflict. Lower-priority install buttons wait for earlier catalogs to finish checking, so load order cannot change installation targets. Replaced or disabled catalogs and late responses do not remain in the current list.

package/README.md

@@ -1,5 +1,9 @@
 # @mearl/preset
 
+[简体中文](README.md) | [English](README.en.md)
+
+用 Preset 将一组配置好的 Mearl 能力、Skills 和 Providers 一起分发。本包负责解析清单，并为浏览器与 Node 宿主准备资源。
+
 3.x 的声明、配置、能力目录及对象存储设计见 [能力包模型](../../docs/capability-model.md)。包支持的位置从贡献推导，Preset 的可选 `targets` 仅选择启用子集；操作和登录定义归包，配置覆盖归 Preset 与用户。
 
 浏览器包的准备与本地存储见 [能力包](../../docs/browser-bundles.md)，整套原子激活与 App 实现映射见 [浏览器 Preset](../../docs/browser-presets.md)。这两类能力通过 `@mearl/preset/bundles` 导出。
@@ -54,7 +58,7 @@ Node 模块快照与宿主加载合同见 [Node 能力包](../../docs/node-capab
 - Skill 可声明 `migrateFrom` 旧来源列表（最多 16 项），相对地址按声明清单解析；子级整体覆盖，空数组清除。安装器仅在来源收据匹配旧来源、Skill 身份有效且所有关联插件均由 setup 托管时迁移。手动注册、共享的手动别名或其他来源保留并报告冲突；来源匹配仍严格检查 ref。
 - defaults 递归合并对象，数组、标量和 null 替换；用户覆盖单独保存，在解析结果上应用。
 - 权限汇总去重，结果仅表示需求；必须由浏览器安装器另行取得实际授权。
-- appProfiles 是 App ID 到实现标识的覆盖映射。具体档案是否存在、所需包是否可执行，由后续能力目录校验，解析器不宣称已验证模拟效果。
+- appProfiles 是 App ID 到实现标识的覆盖映射。具体端模拟配置是否存在、所需包是否可执行，由后续能力目录校验，解析器不宣称已验证模拟效果。
 - 结果保留父级到子级的确切版本链和各组件最近声明来源，加载失败不会生成部分成功的结果。
 - 拒绝未知字段、非 JSON 配置和原型污染键。清单总量不超过 256 Ki UTF-16 code units，defaults 最大嵌套 32 层。
 

package/dist/bundle.d.ts

@@ -48,7 +48,7 @@ export type BundleLoader = (source: string, options: BundleLoadOptions) => Promi
 export interface PrepareBundleOptions {
     load: BundleLoader;
     mearlApiVersion: string;
-    expectedId: string;
+    expectedId?: string;
     version?: string;
     signal?: AbortSignal;
 }

package/dist/bundle.js

@@ -186,7 +186,7 @@ export async function prepareBundle(source, options) {
         invalid('Expected a UTF-8 JSON manifest');
     }
     const manifest = validateBundleManifest(value, options.mearlApiVersion);
-    if (manifest.id !== options.expectedId)
+    if (options.expectedId !== undefined && manifest.id !== options.expectedId)
         invalid('Bundle identity does not match the requested package');
     if (options.version && !satisfies(manifest.version, options.version))
         throw new BundleError('BUNDLE_INCOMPATIBLE', 'Bundle version does not satisfy the requested range');

package/dist/bundleStore.js

@@ -292,9 +292,9 @@ export class BrowserBundleStore {
     /** Pins the verified selection while reading its package from the same IndexedDB snapshot. */
     async profileBinding(name) {
         const activation = await this.activePreset();
-        const target = activation?.preset.appProfiles[name];
-        if (!activation || !target)
+        if (!activation || !Object.hasOwn(activation.preset.appProfiles, name))
             return undefined;
+        const target = activation.preset.appProfiles[name];
         const id = target.split('/')[0];
         const database = await this.open();
         let objects = new Map();

package/dist/bundles.d.ts

@@ -3,6 +3,7 @@ export type { BundleManifest, PreparedBundle, BundleLoader, BundleLoadOptions, P
 export { selectExtensionContributions, validateExtensionContributions } from './extensionContributions.js';
 export type { ExtensionContributions } from './extensionContributions.js';
 export { createBundleFetchLoader } from './bundleFetch.js';
+export { parseProfileSource, resolveProfileSource } from './profileSource.js';
 export { BrowserBundleStore } from './bundleStore.js';
 export type { BrowserPresetInstallation } from './bundleStore.js';
 export { prepareBrowserPreset, presetRequiresBrowser, verifyBrowserPreset, verifyPreparedBrowserPreset } from './browserPreset.js';

package/dist/bundles.js

@@ -1,6 +1,7 @@
 export { BundleError, MAX_BUNDLE_BYTES, MAX_BUNDLE_MANIFEST_BYTES, MAX_BROWSER_STORAGE_BYTES, MAX_PAGE_RUNTIME_BYTES, MAX_REQUEST_UI_BYTES, bundleDigest, bundleSourceUrl, prepareBundle, readBundleJson, readBundleText, validateBundleManifest, verifyBundle, } from './bundle.js';
 export { selectExtensionContributions, validateExtensionContributions } from './extensionContributions.js';
 export { createBundleFetchLoader } from './bundleFetch.js';
+export { parseProfileSource, resolveProfileSource } from './profileSource.js';
 export { BrowserBundleStore } from './bundleStore.js';
 export { prepareBrowserPreset, presetRequiresBrowser, verifyBrowserPreset, verifyPreparedBrowserPreset } from './browserPreset.js';
 export { preparePreset, verifyPreset, verifyPreparedPreset } from './preset.js';

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { PresetError, validatePreset, clonePresetDefaults } from './manifest.js';
 export { mergePresetDefaults, resolvePreset } from './resolve.js';
 export type * from './types.js';
+export { parseSetupManagement, setupManagementCommand, setupRuntimeCompatible } from './management.js';
+export type { SetupManagement } from './management.js';
 export { prepareNodeBundleSnapshot, prepareCapabilitySnapshot, verifyCapabilitySnapshot, verifyCapabilityActivation, validateCapabilityConfig, resolveCapabilityConfig, MAX_CAPABILITY_SELECTION_BYTES } from './capabilitySnapshot.js';
 export type { CapabilitySelection, CapabilitySnapshot, CapabilityActivation } from './capabilitySnapshot.js';
 export { parseToolboxCatalogs } from './toolboxCatalogs.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { PresetError, validatePreset, clonePresetDefaults } from './manifest.js';
 export { mergePresetDefaults, resolvePreset } from './resolve.js';
+export { parseSetupManagement, setupManagementCommand, setupRuntimeCompatible } from './management.js';
 export { prepareNodeBundleSnapshot, prepareCapabilitySnapshot, verifyCapabilitySnapshot, verifyCapabilityActivation, validateCapabilityConfig, resolveCapabilityConfig, MAX_CAPABILITY_SELECTION_BYTES } from './capabilitySnapshot.js';
 export { parseToolboxCatalogs } from './toolboxCatalogs.js';

package/dist/management.d.ts

@@ -0,0 +1,10 @@
+export interface SetupManagement {
+    package: string;
+    version: string;
+    registry?: string;
+    runtime?: string;
+}
+/** Declarative installation guidance; never accepts commands, arguments or executable hooks. */
+export declare function parseSetupManagement(value: unknown): SetupManagement | undefined;
+export declare function setupManagementCommand(setup: SetupManagement): string;
+export declare function setupRuntimeCompatible(setup: SetupManagement, version: string, targetLine?: string): boolean;

package/dist/management.js

@@ -0,0 +1,36 @@
+import { valid, validRange, satisfies, subset } from 'semver';
+import { isJsonObject, PresetError } from './manifest.js';
+/** Declarative installation guidance; never accepts commands, arguments or executable hooks. */
+export function parseSetupManagement(value) {
+    if (value === undefined)
+        return;
+    const invalid = () => { throw new PresetError('PRESET_INVALID', 'Invalid defaults.management.setup declaration'); };
+    if (!isJsonObject(value) || Object.keys(value).some(key => key !== 'setup') || !isJsonObject(value.setup))
+        return invalid();
+    const setup = value.setup;
+    if (Object.keys(setup).some(key => !['package', 'version', 'registry', 'runtime'].includes(key)) ||
+        typeof setup.package !== 'string' || setup.package.length > 214 || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(setup.package) ||
+        typeof setup.version !== 'string' || setup.version.length > 64 || !(valid(setup.version) === setup.version || /^[a-z][a-z0-9.-]*$/.test(setup.version)))
+        return invalid();
+    if (setup.registry !== undefined) {
+        if (typeof setup.registry !== 'string' || setup.registry.length > 2048 || !/^https:\/\/[a-zA-Z0-9./:_-]+$/.test(setup.registry))
+            return invalid();
+        try {
+            const url = new URL(setup.registry);
+            if (!url.hostname || url.username || url.password || url.search || url.hash)
+                return invalid();
+        }
+        catch {
+            return invalid();
+        }
+    }
+    if (setup.runtime !== undefined && (typeof setup.runtime !== 'string' || setup.runtime.length > 128 || !validRange(setup.runtime)))
+        return invalid();
+    return { ...setup };
+}
+export function setupManagementCommand(setup) {
+    return `npx${setup.registry ? ` --registry=${setup.registry}` : ''} ${setup.package}@${setup.version}`;
+}
+export function setupRuntimeCompatible(setup, version, targetLine) {
+    return !setup.runtime || (satisfies(version, setup.runtime, { includePrerelease: true }) && (!targetLine || subset(targetLine, setup.runtime, { includePrerelease: true })));
+}

package/dist/profileSource.d.ts

@@ -0,0 +1,9 @@
+export declare function parseProfileSource(input: string): {
+    origin: string;
+    url: string;
+    github?: {
+        repository: string;
+        ref: string;
+    };
+};
+export declare function resolveProfileSource(input: string, fetcher?: typeof fetch): Promise<string>;

package/dist/profileSource.js

@@ -0,0 +1,44 @@
+import { BundleError } from './bundle.js';
+import { createBundleFetchLoader } from './bundleFetch.js';
+const githubReference = /^([A-Za-z0-9-]+)\/([A-Za-z0-9_.-]+)(?:@([A-Za-z0-9._/-]+))?$/;
+export function parseProfileSource(input) {
+    if (typeof input !== 'string' || input.length > 2048)
+        throw new BundleError('BUNDLE_INVALID', 'Invalid App profile source');
+    const match = githubReference.exec(input.trim());
+    if (match && match[2] !== '.' && match[2] !== '..') {
+        return {
+            origin: 'https://raw.githubusercontent.com',
+            url: input.trim(),
+            github: { repository: `${match[1]}/${match[2]}`, ref: match[3] ?? 'HEAD' },
+        };
+    }
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new BundleError('BUNDLE_INVALID', 'Use a GitHub owner/repo or an HTTPS bundle manifest URL');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.hash) {
+        throw new BundleError('BUNDLE_INVALID', 'App profile bundle URLs require HTTPS without credentials or a fragment');
+    }
+    return { origin: url.origin, url: url.href };
+}
+export async function resolveProfileSource(input, fetcher = fetch) {
+    const { url, github } = parseProfileSource(input);
+    if (!github)
+        return url;
+    const { repository, ref } = github;
+    let sha = ref;
+    if (!/^[a-f0-9]{40}$/.test(sha)) {
+        const load = createBundleFetchLoader({ fetch: fetcher });
+        const bytes = await load(`https://api.github.com/repos/${repository}/commits/${encodeURIComponent(ref)}`, {
+            maxBytes: 2 * 1024 * 1024,
+            signal: AbortSignal.timeout(10000),
+        });
+        sha = JSON.parse(new TextDecoder().decode(bytes)).sha;
+        if (typeof sha !== 'string' || !/^[a-f0-9]{40}$/.test(sha))
+            throw new BundleError('BUNDLE_INVALID', 'GitHub did not return a commit ID');
+    }
+    return `https://raw.githubusercontent.com/${repository}/${sha}/bundle.json`;
+}

package/dist/resolve.js

@@ -1,4 +1,5 @@
 import { parseToolboxCatalogs } from './toolboxCatalogs.js';
+import { parseSetupManagement } from './management.js';
 import { satisfies, valid } from 'semver';
 import { clonePresetDefaults, isJsonObject, PresetError, validatePreset } from './manifest.js';
 const kinds = ['packages', 'skills', 'providers'];
@@ -128,6 +129,7 @@ export async function resolvePreset(source, options) {
         return result;
     };
     const result = await load(sourceUrl(source));
+    parseSetupManagement(result.defaults.management);
     const extension = result.defaults.extension;
     if (isJsonObject(extension))
         parseToolboxCatalogs(extension.toolCatalogs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/preset",
-  "version": "3.0.0-beta.8",
+  "version": "3.0.0",
   "description": "Browser-compatible preset validation, inheritance and capability resolution for Mearl",
   "type": "module",
   "license": "Apache-2.0",
@@ -26,6 +26,7 @@
     }
   },
   "files": [
+    "README.en.md",
     "dist",
     "!dist/**/*.map",
     "installation-site.json"