@qilin-agent/package-manifest 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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.i18n.yaml

@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/package-manifest/README.md
+/:
+  en: 8cffb2f57844db66
+  zh: 20b158511886ac50
+/qilin-agent-package-manifest:
+  en: 93ae335bbcdc4643
+  zh: 834b62ac963d8fda
+/qilin-agent-package-manifest/summary:
+  en: 11c2d869ff7a57d5
+  zh: 6460dfd74b550431
+/qilin-agent-package-manifest/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 1db86285abf6c499
+/qilin-agent-package-manifest/use-this-package:
+  en: d43690593d62123d
+  zh: 9969f7c83dc4aecb
+/qilin-agent-package-manifest/understand-the-implementation:
+  en: 41ec449dee927f04
+  zh: a60e0740a2a4034e
+/qilin-agent-package-manifest/further-exploration:
+  en: 56a77c4f61a7391b
+  zh: 1372cfa0389d12c8
+/qilin-agent-package-manifest/model-experience:
+  en: 0b5aaa4787068a57
+  zh: bdb5dabe0b33ff9d
+/qilin-agent-package-manifest/model-experience/kv-cache-effect:
+  en: 2ed74a2a33958543
+  zh: 7d63c3a3801bef13
+/qilin-agent-package-manifest/known-limitations-and-deferred-work:
+  en: f2e2f7b819e823ef
+  zh: 142b576757481f4d
+/qilin-agent-package-manifest/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+---
+description: "Shared TypeScript declarations for package identity, runtime requirements, and DSH plugin metadata."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/package-manifest
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `QilinPackageManifest` for package metadata, `QilinManifest` for the public fields under `qilin`, and member types such as `QilinClientManifest` for one domain. Each reader owns JSON parsing, validation, and default resolution.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Import from the package root. Use a development dependency when only checking your own source; use a production dependency if your published declarations reference these types.
+
+```ts
+import type { QilinClientManifest, QilinPackageManifest } from '@qilin-agent/package-manifest'
+
+const client: QilinClientManifest = { platform: 'web' }
+const manifest: QilinPackageManifest = {
+  name: 'example-qilin-plugin',
+  version: '1.0.0',
+  engines: { node: '>=24', qilin: '0.1.5-alpha.1' },
+  qilin: {
+    manifestVersion: 1,
+    bundle: { patch: './cordis.patch.yml' },
+    client,
+  },
+}
+```
+
+`QilinPackageManifest` describes the package.json fields used by DSH, with required `name` and `version`; it is not an exhaustive npm schema. Local profile readers use `Partial<QilinPackageManifest>` because profiles need no published version. `QilinManifest` describes only public author fields under `qilin`. TypeScript checks the example and erases `import type`; these interfaces do not parse JSON or write a file.
+
+The following metadata fields are optional. Omitting them leaves the format version or compatible host versions undeclared; readers do not infer defaults.
+
+| Field | Meaning |
+|---|---|
+| `qilin.manifestVersion` | Manifest format identifier; the declared format is `1`, independent of the npm package version and Session format version. |
+| `engines.qilin` | Author-declared compatible DSH versions as a SemVer range, including exact prerelease versions. This field sits beside `engines.node` and `engines.npm`; an engines object may omit `qilin`. |
+
+Public composition declarations are defined in [`src/types.ts`](src/types.ts). Internal `configTrees`, `sessionFormatMigration`, and generated `moduleFallback` metadata remain owned by their image-packer, catalog, and launcher readers; the public types do not expose them.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The package root only re-exports declarations from [`src/types.ts`](src/types.ts).
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Profile launcher](../../boot/app-boot/README.md#profiles) — manifest loading and composition.
+- [Public package metadata](../../../.agents/notes/implemented/architecture/2026-09-10-public-package-manifest.md) — field placement and reader ownership.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package only exports types.
+
+#### KV Cache effect
+
+Type declarations add no model input, so provider cache reuse is unaffected.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Static typing only.** Consumers read and validate the JSON fields they use, then adapt the shared declarations to their runtime data. The package supplies no parser, getter helpers, file checks, or defaults.
+- **Compatibility is declarative.** Current installers and loaders do not enforce `qilin.manifestVersion` or `engines.qilin`; declaring a range does not reject incompatible hosts or validate SemVer syntax.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,101 @@
+---
+description: "包身份、运行时要求和 DSH 插件元数据的共享 TypeScript 声明。"
+kind: "package-library"
+---
+
+# @qilin-agent/package-manifest
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `QilinPackageManifest` 描述包元数据、`QilinManifest` 描述 `qilin` 下的公共字段，以及 `QilinClientManifest` 等成员类型描述单个领域。各读取方负责 JSON 解析、校验和默认值解析。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+从包根导入类型。仅检查自己的源码时使用开发依赖；若发布的声明文件引用这些类型，则使用生产依赖。
+
+```ts
+import type { QilinClientManifest, QilinPackageManifest } from '@qilin-agent/package-manifest'
+
+const client: QilinClientManifest = { platform: 'web' }
+const manifest: QilinPackageManifest = {
+  name: 'example-qilin-plugin',
+  version: '1.0.0',
+  engines: { node: '>=24', qilin: '0.1.5-alpha.1' },
+  qilin: {
+    manifestVersion: 1,
+    bundle: { patch: './cordis.patch.yml' },
+    client,
+  },
+}
+```
+
+`QilinPackageManifest` 描述 DSH 使用的 package.json 字段，其中 `name` 和 `version` 必填；它不是完整的 npm schema（模式）。本地 profile 读取方使用 `Partial<QilinPackageManifest>`，因为 profile 无需发布版本。`QilinManifest` 仅描述 `qilin` 下的公共作者字段。TypeScript 检查示例并删除 `import type`；这些接口不解析 JSON，也不写入文件。
+
+以下元数据字段均可选。省略时，格式版本或兼容的宿主版本保持未声明状态；读取方不推断默认值。
+
+| 字段 | 含义 |
+|---|---|
+| `qilin.manifestVersion` | manifest（元数据清单）格式标识；声明的格式为 `1`，独立于 npm 包版本和 Session 格式版本。 |
+| `engines.qilin` | 作者声明的兼容 DSH 版本，使用 SemVer 范围，也可填写精确的预发布版本。此字段与 `engines.node`、`engines.npm` 并列；engines 对象可省略 `qilin`。 |
+
+公共组合声明定义在 [`src/types.ts`](src/types.ts) 中。内部 `configTrees`、`sessionFormatMigration` 和生成的 `moduleFallback` 元数据分别由镜像打包器、目录生成器和启动器读取方拥有；公共类型不暴露这些字段。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+包根仅重新导出 [`src/types.ts`](src/types.ts) 中的声明。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Profile 启动器](../../boot/app-boot/README.zh.md#profiles)——manifest 加载与组合。
+- [公共包元数据](../../../.agents/notes/implemented/architecture/2026-09-10-public-package-manifest.zh.md)——字段位置与读取方归属。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本包仅导出类型。
+
+#### KV Cache 影响
+
+类型声明不增加模型输入，因此不影响提供方的缓存复用。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅提供静态类型。** 消费方读取并校验所需的 JSON 字段，再将共享声明适配为运行时数据。本包不提供解析器、getter helper、文件检查或默认值。
+- **兼容性仅作声明。** 当前安装器和加载器不强制检查 `qilin.manifestVersion` 或 `engines.qilin`；声明范围不会拒绝不兼容的宿主，也不会校验 SemVer 语法。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public package manifest types, with no runtime exports.
+ * @module @qilin-agent/package-manifest
+ */
+export type { LocalizedText, PluginLocalizedMeta, QilinBundleManifest, QilinClientManifest, QilinEnginesManifest, QilinManifest, QilinPackageManifest, QilinProfileAudience, QilinProfileManifest, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared declarations for the package.json fields used by QiLin plugin authors.
+ * Each reader owns JSON validation and resolved defaults.
+ * @module @qilin-agent/package-manifest/types
+ */
+/** Package identity and metadata; local profile readers may accept a partial declaration. */
+export interface QilinPackageManifest {
+    /** Published npm package name. */
+    name: string;
+    /** Published npm package version. */
+    version: string;
+    /** Package summary for discovery and display. */
+    description?: string;
+    /** Prevent npm publication, for example for local profile projects. */
+    private?: boolean;
+    /** Packages installed alongside this package. */
+    dependencies?: Record<string, string>;
+    /** Compatible versions of packages supplied by the consuming project. */
+    peerDependencies?: Record<string, string>;
+    /** Runtime requirements; declared compatibility is advisory until a reader enforces it. */
+    engines?: QilinEnginesManifest;
+    /** QiLin-specific author declarations. */
+    qilin?: QilinManifest;
+}
+/** Public author fields under `package.json.qilin`; a package may declare several roles. */
+export interface QilinManifest {
+    /** Manifest format version, independent of the npm package and Session format versions. */
+    manifestVersion?: 1;
+    /** Bundle metadata consumed by the profile launcher. */
+    bundle?: QilinBundleManifest;
+    /** Profile metadata consumed by the profile launcher. */
+    profile?: QilinProfileManifest;
+    /** Client module loading and build metadata. */
+    client?: QilinClientManifest;
+}
+/** Runtime version requirements under `package.json.engines`. */
+export interface QilinEnginesManifest {
+    /** Compatible QiLin versions as a SemVer range, including an exact version. */
+    qilin?: string;
+    /** Compatible Node.js versions. */
+    node?: string;
+    /** Compatible npm versions. */
+    npm?: string;
+    /** Requirements for additional runtimes or package managers. */
+    [engine: string]: string | undefined;
+}
+/** The configuration layer exported by a bundle package. */
+export interface QilinBundleManifest {
+    /** Patch file path relative to the declaring package root. */
+    patch: string;
+}
+/** The bundle composition declared by a profile directory. */
+export interface QilinProfileManifest {
+    /** Ordered bundle layer list, using installed package names. */
+    bundles?: string[];
+    /**
+     * Presentation choice recorded for a bundle's UI, keyed by package name; a
+     * name the record omits reads as `both`. Only a release that still offered
+     * the choice wrote one: app-boot reads an entry as the profile's own claim on
+     * a layer the shipped template no longer supplies, and the engine composition
+     * keeps every bundle regardless of the value.
+     */
+    audiences?: Record<string, QilinProfileAudience>;
+}
+/** The workbench surfaces a bundle's UI presents on; the engine composition is presentation-independent. */
+export type QilinProfileAudience = 'general' | 'coding' | 'both';
+/** Literal text or translations indexed by lowercase language id, with a required English fallback. */
+export type LocalizedText = string | {
+    readonly en: string;
+    readonly [locale: string]: string;
+};
+/** Validated plugin display fields and diagnostics from exported locales, manifests, or icon files. */
+export interface PluginLocalizedMeta {
+    /** Display title; omission preserves the consumer's technical-name fallback. */
+    readonly title?: LocalizedText;
+    /** Display introduction after locale and package-field fallback. */
+    readonly description?: LocalizedText;
+    /** Base64 image data URL read from the manifest's icon file; render as an image, not inline markup. */
+    readonly icon?: string;
+    /** Unmodified local metadata diagnostic; the plugin remains manageable. */
+    readonly error?: string;
+}
+/** Client module declaration read by client-modules and the client build. */
+export interface QilinClientManifest {
+    /** Client platform identifier; the Web consumer selects `web`. */
+    platform: string;
+    /** Informational package-name dependencies, not Cordis service injection. */
+    inject?: string[];
+    /** Boot phase-one registration barrier; absent means the shared application batch. */
+    immediately?: boolean;
+    /**
+     * Exact module-table requests beyond the implicit client baseline, including
+     * subpaths such as `<pkg>/client`; absent means baseline externals only.
+     * Type-only imports are erased and create no module request.
+     */
+    external?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@qilin-agent/package-manifest",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Shared type declarations for package.json.qilin configuration fields",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/util/package-manifest"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }