@deepseek-ai/dsh-app-boot 0.1.2-alpha.5 → 0.1.3-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
-README.md: a9ed535c2662237229e0702dcf41eae4f93af5df
-README.zh.md: 4f7688f7db5060bb1bf00ca5d091ca4ad16466ea
+README.md: e6afceaebf7fc94f5a6d708639de128cb9005d72
+README.zh.md: a98be1fd5d0624f971af5d0ce5a81fdc0cafab54

package/README.md

@@ -45,15 +45,19 @@ With that entry point, success looks like a running app with every plugin active
 <a id="profiles"></a>
 ### Profiles
 
+Import profile and bundle declaration types from [`@deepseek-ai/dsh-package-manifest`](../../util/package-manifest/README.md). App-boot owns profile loading, JSON validation, and resolved runtime data.
+
 A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles, its own `cordis.patch.yml`, and `patchReload: live | startup`; omitted reload policy keeps the historical `live` default for custom profiles. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh plugin` creates custom profiles, and a missing bundle or one without a patch declaration fails startup loudly.
 
 Your machine-local preferences also live in the Harness home:
 
-- **`.env`** — your ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. Variables that decide how the process starts (`PATH`, proxies, `DSH_*`, `XDG_*` and similar) are rejected from files: export them instead. For a non-product bin that just wants one directory's `.env`, a missing file is fine and an unloadable one prints one labelled warning line.
+- **`.env`** — your ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. Variables that decide how the process starts (`PATH`, `DSH_*`, `XDG_*` and similar) are rejected from files: export them instead. The four proxy names (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) are accepted from the Harness-home file only, never from the invoking directory's, which arrives with a clone. For a non-product bin that just wants one directory's `.env`, a missing file is fine and an unloadable one prints one labelled warning line.
 - **`cordis.patch.yml`** — your tweak layer, applied after every bundle layer (per-profile first, then the home-level file, which therefore outranks it): replace one entry's whole config (restating the fields you keep), insert new entries, or interpolate `!!js` expressions at boot. A patch naming an entry that does not exist prints a stderr warning; an empty or comments-only file fails boot — disable the layer with `[]` instead.
 
 Profiles with `patchReload: live` watch both user patch files: a valid edit recomposes without restart, while a rejected edit leaves the last good app running. A `startup` profile installs neither those watchers nor the launcher's watch-only HMR fallback.
 
+Inserted plugin names may be absolute filesystem paths, file URLs, or package specifiers. Patch loading converts absolute paths and patch-relative `./` or `../` paths to file URLs within `insert` rows and their nested groups; existing-entry name assertions and replacement `config` values remain literal.
+
 ### Previewing the effective configuration
 
 Before you boot, you can print the exact configuration the app will mount: the dump shows the composed entry list with `!!js` expressions verbatim, grouped under comments naming each source file and the patch layers that changed it, as one loadable YAML document. Patches that match no row are reported with their layer label; a missing, unparsable, or invalid config fails the dump.
@@ -124,7 +128,7 @@ Indirectly, through the loaded plugin tree, which alone contributes model contex
 
 #### KV Cache effect
 
-Boot itself invalidates nothing in the request prefix. A consumer that calls `addHarnessSourceSection` places one short line near the system prompt's head, before per-request content, so it does not invalidate the cache across turns; any other request-prefix change is owned by the named consumer.
+Boot itself changes no request prefix. `addHarnessSourceSection` places its source path after first-party reusable instructions, so different checkouts leave those preceding bytes unchanged when tools and configuration match. Provider cache reuse is not guaranteed.
 
 ## Known Limitations and Deferred Work
 

package/README.zh.md

@@ -45,15 +45,19 @@ const ctx = await boot('dsh', resolveConfigPath(argv[2], process.env.DSH_SNAPSHO
 <a id="profiles"></a>
 ### Profile
 
+Profile 与 bundle 的声明类型从 [`@deepseek-ai/dsh-package-manifest`](../../util/package-manifest/README.zh.md) 导入。App-boot 负责 profile 加载、JSON 校验和解析后的运行时数据。
+
 profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装 bundle、自身 `cordis.patch.yml` 与 `patchReload: live | startup` 组成；自定义 profile 省略 reload 策略时保留历史 `live` 默认值。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立 bundle，其他模板保留 base 加模式 bundle 的栈。`dsh plugin` 创建自定义 profile；缺失 bundle 或未声明 patch 的 bundle 会让启动明确失败。
 
 你的机器本地偏好同样位于 harness home 中：
 
-- **`.env`**——你的普通环境层：调用目录的文件优先于 harness home 的文件，两者都低于继承环境。决定进程如何启动的变量（`PATH`、代理、`DSH_*`、`XDG_*` 等）会被文件拒绝：请改为导出。对于只想加载某个目录 `.env` 的非产品 bin，文件缺失不影响启动，文件无法加载时输出一行带标签的警告。
+- **`.env`**——你的普通环境层：调用目录的文件优先于 harness home 的文件，两者都低于继承环境。决定进程如何启动的变量（`PATH`、`DSH_*`、`XDG_*` 等）会被文件拒绝：请改为导出。四个代理名（`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY`）只从 harness home 的文件接受，绝不从调用目录的文件接受——后者随 clone 一起到来。对于只想加载某个目录 `.env` 的非产品 bin，文件缺失不影响启动，文件无法加载时输出一行带标签的警告。
 - **`cordis.patch.yml`**——你的 tweak 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：替换某个条目的整个 config（重述你要保留的字段）、插入新条目，或在启动时插值 `!!js` 表达式。patch 指定的条目不存在时输出 stderr 警告；空文件或仅含注释的文件会导致启动失败——如需禁用该层，请改用 `[]`。
 
 带 `patchReload: live` 的 profile 会监视两份用户 patch 文件：有效编辑无需重启即可重新组合，被拒绝的编辑则让最后一个可用应用继续运行。`startup` profile 既不安装这些监视器，也不安装 launcher 的仅监视 HMR 回退。
 
+插入条目的插件名可以是绝对文件系统路径、文件 URL 或包标识符。patch 加载会把 `insert` 条目及其嵌套分组中的绝对路径以及相对于 patch 文件的 `./` 或 `../` 路径转换为文件 URL；对已有条目名称的断言及替换用的 `config` 值保持原样。
+
 ### 预览生效配置
 
 启动前，你可以打印应用将挂载的确切配置：dump 会以 `!!js` 表达式原样展示组合后的条目列表，并按注释分组标明每个源文件及其 patch 层，输出是一份可加载的 YAML 文档。未匹配到任何行的 patch 会连同其层标签一起报告；配置缺失、无法解析或字段无效都会使 dump 失败。
@@ -124,7 +128,7 @@ profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`head
 
 #### KV Cache 影响
 
-启动本身不会使请求前缀中的任何内容失效。消费方调用 `addHarnessSourceSection` 时，会在系统提示词靠前位置、逐请求内容之前添加一行短文本，因此不会使跨轮次缓存失效；请求前缀的其他任何变化均由相应的具名消费方负责。
+启动本身不改变请求前缀。`addHarnessSourceSection` 将源码路径放在第一方可复用指令之后，因此工具与配置一致时，不同 checkout 不会改变前置字节。不保证提供方复用缓存。
 
 ## 已知限制与延期工作
 

package/lib/index.js

@@ -989,8 +989,22 @@ const BOOTSTRAP_PREFIXES = [
 	"BASH_FUNC_"
 ];
 /**
+* The bootstrap names the Harness-home `.env` alone may set. A proxy chooses the route every
+* request takes, so the invoking directory's file — which arrives with a clone — keeps refusing
+* them; the home file is the user's own, and `DSH_HOME` is itself bootstrap-only, so no `.env` can
+* relocate this exemption. The CA and TLS names in the same group stay refused everywhere: they
+* change what is trusted, not where traffic goes.
+*/
+const HOME_LAYER_PROXY_NAMES = new Set([
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"ALL_PROXY",
+	"NO_PROXY"
+]);
+/**
 * Whether a variable may come only from the inherited process environment
-* because it changes process, runtime, VCS, or network bootstrap.
+* because it changes process, runtime, VCS, or network bootstrap. The Harness-home
+* file is additionally allowed {@link HOME_LAYER_PROXY_NAMES}.
 * @param name - the variable name.
 * @returns true when only the inherited environment may supply it.
 */
@@ -1004,11 +1018,13 @@ function isBootstrapOnly(name) {
 * @param binName - the diagnostic prefix on the thrown error.
 * @param dir - the directory whose `.env` to read.
 * @param warn - sink for the one-line unreadable-file diagnostic.
+* @param home - the resolved Harness home; when `dir` is it, {@link HOME_LAYER_PROXY_NAMES} are accepted.
 * @returns the parsed entries, or `undefined` when the file is absent or unreadable.
-* @throws when the file declares a name {@link isBootstrapOnly} rejects.
+* @throws when the file declares a name {@link isBootstrapOnly} rejects and this layer may not set.
 */
-function readEnvLayer(binName, dir, warn) {
+function readEnvLayer(binName, dir, warn, home) {
 	const path = resolve(dir, ".env");
+	const isHome = resolve(dir) === home;
 	let content;
 	try {
 		content = readFileSync(path, "utf8");
@@ -1019,7 +1035,10 @@ function readEnvLayer(binName, dir, warn) {
 	const values = parseEnv(content);
 	for (const name of Object.keys(values)) {
 		if (!isBootstrapOnly(name)) continue;
-		throw new Error(`${binName}: ${path} sets "${name}", which only the launching environment may set (it decides how this process starts, where its code and instructions load from, or how it reaches the network); export ${name} instead of putting it in a .env file`);
+		const proxyName = HOME_LAYER_PROXY_NAMES.has(name.toUpperCase());
+		if (isHome && proxyName) continue;
+		const remedy = proxyName ? `export ${name}, or put it in ${resolve(home, ".env")}, which does not travel with a repository` : `export ${name} instead of putting it in a .env file`;
+		throw new Error(`${binName}: ${path} sets "${name}", which only the launching environment may set (it decides how this process starts, where its code and instructions load from, or how it reaches the network); ${remedy}`);
 	}
 	return {
 		path,
@@ -1035,13 +1054,13 @@ function readEnvLayer(binName, dir, warn) {
 * @param cwd - the invoking directory whose `.env` is the project layer.
 * @param warn - sink for the one-line misconfiguration diagnostics.
 * @returns this run's frozen environment snapshot.
-* @throws when either file declares a bootstrap-only variable.
+* @throws when either file declares a bootstrap-only variable, except {@link HOME_LAYER_PROXY_NAMES} in the Harness-home file.
 */
 function loadLayeredEnv(binName, cwd = process.cwd(), warn = (line) => void process.stderr.write(line)) {
 	const home = resolveDshHome();
 	const inherited = { ...process.env };
-	const project = readEnvLayer(binName, cwd, warn);
-	const user = home === resolve(cwd) ? void 0 : readEnvLayer(binName, home, warn);
+	const project = readEnvLayer(binName, cwd, warn, home);
+	const user = home === resolve(cwd) ? void 0 : readEnvLayer(binName, home, warn, home);
 	for (const layer of [project, user]) {
 		if (layer === void 0) continue;
 		for (const [name, value] of Object.entries(layer.values)) if (process.env[name] === void 0) process.env[name] = value;
@@ -1132,11 +1151,11 @@ function loadOverlayPatches(binName, file) {
 	}
 	return parsePatchList(binName, file, content, "overlay");
 }
-/** Resolve relative plugin paths in one patch file's `insert` rows without changing assertion names. */
+/** Convert inserted filesystem paths to file URLs, anchoring relative paths beside the patch; keep assertion names literal. */
 function anchorInsertedPluginNames(patches, file) {
 	const base = dirname(resolve(file));
 	const visit = (entry) => {
-		if (typeof entry.name === "string" && (entry.name.startsWith("./") || entry.name.startsWith("../"))) entry.name = pathToFileURL(resolve(base, entry.name)).href;
+		if (typeof entry.name === "string" && (isAbsolute(entry.name) || entry.name.startsWith("./") || entry.name.startsWith("../"))) entry.name = pathToFileURL(resolve(base, entry.name)).href;
 		if (entry.group && Array.isArray(entry.config)) entry.config.forEach(visit);
 	};
 	for (const patch of patches) patch.insert?.forEach(visit);
@@ -1518,9 +1537,10 @@ const HARNESS_SOURCE_SECTION = "harness:source";
 * explicitly distinguishing it from the task workspace and current working
 * directory. The self-referential `dsh-tool-cordis` toolset reads and edits this
 * checkout. Call once on the settled boot context ({@link boot}); the section
-* uses the shared first-party placement just after the harness identity opener
-* and before the deployment persona. A booted tree with no `systemPrompt` service has no prompt to
-* augment, so this is then a no-op that returns `undefined`. The section is
+* uses the shared first-party placement after reusable instructions
+* and before the Web surface and persona suffix. A booted tree with no
+* `systemPrompt` service has no prompt to augment, so this is then a no-op
+* that returns `undefined`. The section is
 * registered against the `systemPrompt` service's fiber, so a dev HMR reload of
 * that plugin drops it until the next boot.
 * @param ctx - the settled boot context whose global system prompt to augment.

package/lib/types/index.d.ts

@@ -16,7 +16,7 @@ declare module '@deepseek-ai/cordis' {
         dshHomePath?: typeof dshHomePath;
     }
 }
-export { composeEntries, DEFAULT_PROFILE_BUNDLES, DEFAULT_PROFILE_PATCH_RELOAD, healProfilesModuleFallback, initProfile, loadProfile, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PROFILES_DIR, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest, type DshBundleManifest, type DshManifestSection, type DshProfileManifest, type Profile, type ProfileLayer, type ProfileManifest, type ProfileModuleFallbackOptions, type ProfilePatchReload, type ProfileTemplate, } from './profile.ts';
+export { composeEntries, DEFAULT_PROFILE_BUNDLES, DEFAULT_PROFILE_PATCH_RELOAD, healProfilesModuleFallback, initProfile, loadProfile, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PROFILES_DIR, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest, type Profile, type ProfileLayer, type ProfileManifest, type ProfileModuleFallbackOptions, type ProfileTemplate, } from './profile.ts';
 /**
  * Resolve the config to boot. Replay swaps a `cordis.yml` basename for
  * `cordis.snapshot.yml` in the same directory; every other mode keeps the path.
@@ -44,7 +44,7 @@ export declare function loadEnv(binName: string, dir?: string, warn?: (line: str
  * @param cwd - the invoking directory whose `.env` is the project layer.
  * @param warn - sink for the one-line misconfiguration diagnostics.
  * @returns this run's frozen environment snapshot.
- * @throws when either file declares a bootstrap-only variable.
+ * @throws when either file declares a bootstrap-only variable, except {@link HOME_LAYER_PROXY_NAMES} in the Harness-home file.
  */
 export declare function loadLayeredEnv(binName: string, cwd?: string, warn?: (line: string) => void): LaunchEnvironmentSnapshot;
 /** Options for live user patch-layer reconciliation. */
@@ -254,9 +254,10 @@ export declare const HARNESS_SOURCE_SECTION = "harness:source";
  * explicitly distinguishing it from the task workspace and current working
  * directory. The self-referential `dsh-tool-cordis` toolset reads and edits this
  * checkout. Call once on the settled boot context ({@link boot}); the section
- * uses the shared first-party placement just after the harness identity opener
- * and before the deployment persona. A booted tree with no `systemPrompt` service has no prompt to
- * augment, so this is then a no-op that returns `undefined`. The section is
+ * uses the shared first-party placement after reusable instructions
+ * and before the Web surface and persona suffix. A booted tree with no
+ * `systemPrompt` service has no prompt to augment, so this is then a no-op
+ * that returns `undefined`. The section is
  * registered against the `systemPrompt` service's fiber, so a dev HMR reload of
  * that plugin drops it until the next boot.
  * @param ctx - the settled boot context whose global system prompt to augment.

package/lib/types/profile.d.ts

@@ -24,24 +24,11 @@
  */
 import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
 import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
+import type { DshManifest, ProfilePatchReload } from '@deepseek-ai/dsh-package-manifest';
 /** Directory under the Harness home holding every profile. */
 export declare const PROFILES_DIR = "profiles";
 /** The user patch layer inside a profile directory (hot-reloaded on long-lived surfaces). */
 export declare const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
-/** The bundle half of the `dsh` manifest section: what a bundle package exports. */
-export interface DshBundleManifest {
-    /** The patch layer this bundle exports, relative to its package root. */
-    patch: string;
-}
-/** The profile half of the `dsh` manifest section: what a profile directory composes. */
-export interface DshProfileManifest {
-    /** Ordered bundle layer list (package names). */
-    bundles?: string[];
-    /** Whether user patch files reload while this profile remains active. */
-    patchReload?: ProfilePatchReload;
-}
-/** User patch-file lifecycle selected by a profile. */
-export type ProfilePatchReload = 'live' | 'startup';
 /** Installation-owned defaults used when a shipped profile is first opened. */
 export interface ProfileTemplate {
     /** Ordered bundle layer list. */
@@ -49,22 +36,12 @@ export interface ProfileTemplate {
     /** User patch-file lifecycle for the generated profile. */
     patchReload: ProfilePatchReload;
 }
-/**
- * The profile-launcher slice of the `dsh`-owned package.json section. A
- * manifest may declare both roles; other consumers own additional keys.
- */
-export interface DshManifestSection {
-    /** Bundle metadata consumed by the profile launcher. */
-    bundle?: DshBundleManifest;
-    /** Profile metadata consumed by the profile launcher. */
-    profile?: DshProfileManifest;
-}
 /** The slice of package.json both profiles and bundles use. */
 export interface ProfileManifest {
     name?: string;
     dependencies?: Record<string, string>;
     peerDependencies?: Record<string, string>;
-    dsh?: DshManifestSection;
+    dsh?: DshManifest;
 }
 /** One resolved bundle layer of a profile. */
 export interface ProfileLayer {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-app-boot",
   "description": "Shared boot glue for the app bins: .env loading, fail-loud Loader guards, snapshot-aware config resolution, and the Loader boot sequence",
-  "version": "0.1.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -29,16 +29,17 @@
   "dependencies": {
     "js-yaml": "^4.2.0",
     "resolve.exports": "^2.0.3",
-    "@deepseek-ai/dsh-atomic-write": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-atomic-write": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-package-manifest": "^0.1.3-alpha.2"
   },
   "peerDependencies": {
+    "@deepseek-ai/cordis-plugin-group": "^1.0.2",
     "@deepseek-ai/cordis-plugin-hmr": "^1.0.17",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-home-paths": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.5",
-    "@deepseek-ai/cordis-plugin-group": "^1.0.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "peerDependenciesMeta": {
@@ -48,14 +49,14 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@deepseek-ai/cordis-plugin-group": "^1.0.2",
     "@deepseek-ai/cordis-plugin-hmr": "^1.0.17",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/cordis-plugin-group": "^1.0.2",
     "@deepseek-ai/cordis-plugin-timer": "^1.1.4",
-    "@deepseek-ai/dsh-home-paths": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.5",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-launch-environment": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }