@deepseek-ai/dsh-plugin-manager 0.2.1-alpha.2 → 0.2.1-alpha.4

package/lib/types/patch.d.ts

@@ -1,9 +1,18 @@
-/** Replace the last matching override or append one after existing insertions.
- * @param filename Current profile patch file.
+import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
+import { type ProfileContext } from '@deepseek-ai/dsh-app-boot';
+/** Flatten only the groups addressable by the profile's patch composer.
+ * @param rows Composed top-level entries.
+ * @returns Entries in depth-first order.
+ */
+export declare function flatten(rows: EntryOptions[]): EntryOptions[];
+/** Replace the last matching override or append one after existing insertions. An override that holds only `id` and
+ * `disabled`, without anchors, is removed, or not appended, when the bundle layers and the remaining profile patches
+ * already give the entry the requested literal `disabled` value; home patches and launch overlays are not consulted.
+ * @param profile Profile whose patch file is edited and whose selected bundles supply the compared composition.
  * @param id Unique composition entry id.
  * @param name Module name used to match name-qualified overrides.
  * @param enabled Desired entry enablement.
  * @returns Whether the file changed.
  */
-export declare function writePluginEnabled(filename: string, id: string, name: string, enabled: boolean): Promise<boolean>;
+export declare function writePluginEnabled(profile: ProfileContext, id: string, name: string, enabled: boolean): Promise<boolean>;
 //# sourceMappingURL=patch.d.ts.map

package/lib/types/patch.js

@@ -1,16 +1,26 @@
-/** Comment-preserving profile plugin enablement edits. */
+/** Comment-preserving profile plugin enablement edits and the entry flattening they compare against. */
 import { readFile } from 'node:fs/promises';
-import { isMap, isSeq, parseDocument } from 'yaml';
-import { loadOptionalPatches } from '@deepseek-ai/dsh-app-boot';
+import { isMap, isNode, isScalar, isSeq, parseDocument } from 'yaml';
+import { composeEntries, loadOptionalPatches, readBundlePatches } from '@deepseek-ai/dsh-app-boot';
 import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
-/** Replace the last matching override or append one after existing insertions.
- * @param filename Current profile patch file.
+/** Flatten only the groups addressable by the profile's patch composer.
+ * @param rows Composed top-level entries.
+ * @returns Entries in depth-first order.
+ */
+export function flatten(rows) {
+    return rows.flatMap(row => [row, ...(row.group && Array.isArray(row.config) ? flatten(row.config) : [])]);
+}
+/** Replace the last matching override or append one after existing insertions. An override that holds only `id` and
+ * `disabled`, without anchors, is removed, or not appended, when the bundle layers and the remaining profile patches
+ * already give the entry the requested literal `disabled` value; home patches and launch overlays are not consulted.
+ * @param profile Profile whose patch file is edited and whose selected bundles supply the compared composition.
  * @param id Unique composition entry id.
  * @param name Module name used to match name-qualified overrides.
  * @param enabled Desired entry enablement.
  * @returns Whether the file changed.
  */
-export async function writePluginEnabled(filename, id, name, enabled) {
+export async function writePluginEnabled(profile, id, name, enabled) {
+    const filename = profile.patchPath;
     let text;
     try {
         text = await readFile(filename, 'utf8');
@@ -28,7 +38,8 @@ export async function writePluginEnabled(filename, id, name, enabled) {
         throw error;
     if (!isSeq(document.contents))
         throw new Error('Profile patch must be a YAML sequence');
-    loadOptionalPatches('dsh', filename);
+    const patches = loadOptionalPatches('dsh', filename) ?? [];
+    const bundlePatches = readBundlePatches('dsh', profile);
     const items = document.contents.items;
     const target = items.findLast((item, index) => {
         if (!isMap(item) || document.getIn([index, 'id']) !== id || item.has('insert'))
@@ -36,12 +47,39 @@ export async function writePluginEnabled(filename, id, name, enabled) {
         const expectedName = document.getIn([index, 'name']);
         return !expectedName || expectedName === name;
     });
+    // Compares the entry's own literal `disabled`; a `!!js` value never matches, so its override is kept.
+    const implied = (index) => {
+        const row = flatten(composeEntries([[...bundlePatches, ...patches.toSpliced(index, 1)]])).findLast(entry => entry.id === id);
+        return row !== undefined && (row.disabled ?? false) === !enabled;
+    };
     if (isMap(target)) {
-        if (document.getIn([items.indexOf(target), 'disabled']) === !enabled)
+        const index = items.indexOf(target);
+        // A removed anchor would leave later aliases unresolved.
+        const onlySwitch = target.anchor === undefined && target.items.every(pair => isScalar(pair.key) && isScalar(pair.value)
+            && pair.key.anchor === undefined && pair.value.anchor === undefined && (pair.key.value === 'id' || pair.key.value === 'disabled'));
+        if (onlySwitch && implied(index)) {
+            document.deleteIn([index]);
+            // The comment above the removed override can be the file header, so it moves to the following item, above an
+            // emptied sequence, or after the remaining items.
+            const comment = target.commentBefore;
+            const next = items[index];
+            if (comment && isNode(next))
+                next.commentBefore = next.commentBefore ? `${comment}\n${next.commentBefore}` : comment;
+            else if (comment && items.length === 0)
+                document.contents.commentBefore = comment;
+            else if (comment)
+                document.comment = document.comment ? `${comment}\n${document.comment}` : comment;
+        }
+        else if (document.getIn([index, 'disabled']) === !enabled) {
             return false;
-        document.setIn([items.indexOf(target), 'disabled'], !enabled);
+        }
+        else {
+            document.setIn([index, 'disabled'], !enabled);
+        }
     }
     else {
+        if (implied(items.length))
+            return false;
         document.add({ id, disabled: !enabled });
     }
     await writeFileAtomic(filename, String(document), { mode: 0o600 });

package/lib/types/tools.js

@@ -3,6 +3,68 @@ import { assertNever } from '@deepseek-ai/dsh-util-values';
 import { approveEscalation } from '@deepseek-ai/dsh-sandbox';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { getDshRuntimeVersion } from '@deepseek-ai/dsh-app-boot';
+/** What the model does next for each refusal the manager reports. */
+const ERROR_STEPS = {
+    'management-required': 'This entry belongs to plugin management itself and cannot be changed.',
+    'unaddressable': 'This entry has no unique profile patch target; tell the user to edit the profile patch file directly.',
+    'unknown-plugin': 'Call list_plugins and retry with an exact entryId.',
+    'invalid-spec': 'Retry with an npm package name, a git URL, a tarball URL, or an absolute local directory.',
+    'already-installed': 'The package is already installed; to install another version, call remove_bundle first, then install_bundle again.',
+    'ambiguous-install': 'The dependency change named no single package; call list_bundles to see what was installed.',
+    'not-bundle': 'The package declares no dsh.bundle and cannot be managed as a plugin; install a DSH plugin bundle instead.',
+    'not-removable': 'Call list_bundles; only bundles marked removable can be removed.',
+    'stop-profile': 'This profile runs without HMR; tell the user to stop DSH and run `dsh plugin --profile <profile> remove <bundle>`.',
+    'bundle-in-use': 'Call list_plugins, disable the entries from other layers that still use this bundle, then retry.',
+    'stale-approval': 'Call install_bundle again without approvedBuilds to read the current pendingBuilds.',
+    'incompatible-version': 'Install a version compatible with the running DSH. A version exemption needs the user\'s explicit acceptance of crash and data-loss risk.',
+    'operation-error': 'Report the diagnostic to the user; retry only after its cause is addressed.',
+};
+/** What the model does next for each package-manager failure. */
+const FAILURE_STEPS = {
+    'pnpm-missing': 'pnpm is not available to DSH; tell the user to install pnpm.',
+    'timeout': 'Retry, or retry with another registry.',
+    'not-found': 'Check the package name and version with the user, then retry.',
+    'no-matching-version': 'Retry with a published version.',
+    'network': 'Retry later or pass another registry.',
+    'disk-full': 'Tell the user to free disk space, then retry.',
+    'permission': 'Tell the user DSH cannot write the profile directory; retry after they fix its permissions.',
+    'build-blocked': 'Ask the user whether to allow the install scripts of the packages in pendingBuilds; if they approve, retry with approvedBuilds.',
+};
+/** Why a change waits for a restart, as the model tells the user. */
+const RESTART_STEPS = {
+    'no-hmr': 'this profile applies changes only at startup',
+    'package-moved': 'an installed package now resolves to another directory, or the change replaces a package the DSH installation provides; remove a package before installing it from another location',
+    'host-module': 'the change reaches modules DSH itself loaded',
+    'unmanaged-plugin': 'the change reaches a plugin running outside the plugin list',
+    'module-comparison': 'DSH could not compare loaded plugins with their files',
+};
+/**
+ * The model-facing result of a change: the manager's result plus the next step its outcome calls for.
+ * @param result The manager's result.
+ * @returns The result with `nextStep` when it is not plainly applied.
+ */
+function withNextStep(result) {
+    switch (result.application) {
+        case 'applied':
+            return result;
+        case 'cancelled':
+            return { ...result, nextStep: 'The installation was cancelled and its files restored; nothing changed.' };
+        case 'overridden':
+            return { ...result, nextStep: 'Saved, but a higher-priority layer such as the agent preset overrides it; tell the user it is not in effect.' };
+        case 'restart-required': {
+            const reason = result.restartReason === undefined ? '' : `: ${RESTART_STEPS[result.restartReason]}`;
+            return { ...result, nextStep: `Tell the user to restart DSH to apply this change${reason}.` };
+        }
+        case 'failed': {
+            const code = result.error?.code ?? 'operation-error';
+            // A refusal code is more specific than the package manager's failure kind.
+            const kind = code === 'operation-error' ? result.packageResult?.kind : undefined;
+            return { ...result, nextStep: (kind === undefined ? undefined : FAILURE_STEPS[kind]) ?? ERROR_STEPS[code] };
+        }
+        /* v8 ignore next -- ChangeResult.application is a closed union */
+        default: return assertNever(result.application);
+    }
+}
 /** Required services for the management tool. */
 export const inject = ['tools', 'pluginManager', 'sandboxPolicy'];
 /** Register one management tool for discovery and the four persistent actions.
@@ -11,7 +73,7 @@ export const inject = ['tools', 'pluginManager', 'sandboxPolicy'];
 export function apply(ctx) {
     ctx.tools.register(defineTool({
         name: 'plugin_manager',
-        description: 'List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart. Incompatible DSH peer dependencies block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.',
+        description: 'List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately, including upgrades of installed packages; a change result that is not applied carries nextStep, which says what to do or tell the user. Unmet DSH version requirements (engines.dsh, else DSH peer dependencies) block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.',
         parameters: {
             action: { type: 'string', required: true, enum: ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle', 'list_version_exemptions', 'set_version_exemption'], description: 'Management operation.' },
             target: { type: 'string', description: 'Plugin entry id, bundle package name, or installation spec, according to action. For an Official catalog entry, pass list_bundles installTarget.spec to install_bundle.' },
@@ -43,7 +105,7 @@ export function apply(ctx) {
                     if (args.target === undefined || args.runtimeVersion === undefined || args.enabled === undefined) {
                         throw new Error('target package-name@version, runtimeVersion, and enabled are required');
                     }
-                    return JSON.stringify(await manager.setVersionExemption(args.target, args.runtimeVersion, args.enabled, args.acceptRisk));
+                    return JSON.stringify(withNextStep(await manager.setVersionExemption(args.target, args.runtimeVersion, args.enabled, args.acceptRisk)));
                 case 'list_plugins':
                 case 'list_bundles': {
                     const offset = args.offset ?? 0;
@@ -62,22 +124,22 @@ export function apply(ctx) {
                 case 'set_bundle': {
                     if (args.target === undefined || args.enabled === undefined)
                         throw new Error('target and enabled are required');
-                    return JSON.stringify(await (args.action === 'set_plugin'
+                    return JSON.stringify(withNextStep(await (args.action === 'set_plugin'
                         ? manager.setPluginEnabled(args.target, args.enabled)
-                        : manager.setBundleEnabled(args.target, args.enabled)));
+                        : manager.setBundleEnabled(args.target, args.enabled))));
                 }
                 case 'install_bundle':
                     if (args.target === undefined)
                         throw new Error('target package spec is required');
-                    return JSON.stringify(await manager.installBundle(args.target, {
+                    return JSON.stringify(withNextStep(await manager.installBundle(args.target, {
                         ...args.enabled === undefined ? {} : { enabled: args.enabled },
                         ...args.approvedBuilds === undefined ? {} : { approvedBuilds: args.approvedBuilds },
                         ...args.registry === undefined ? {} : { registry: args.registry },
-                    }));
+                    })));
                 case 'remove_bundle':
                     if (args.target === undefined)
                         throw new Error('target bundle name is required');
-                    return JSON.stringify(await manager.removeBundle(args.target));
+                    return JSON.stringify(withNextStep(await manager.removeBundle(args.target)));
                 /* v8 ignore next -- tool JSON validation rejects actions outside the declared enum */
                 default: return assertNever(args.action);
             }

package/lib/types/types.d.ts

@@ -6,21 +6,29 @@ export type { PluginEntryId } from '@deepseek-ai/dsh-host-plugin-inventory/types
 import type { PluginEntryId } from '@deepseek-ai/dsh-host-plugin-inventory/types';
 /** Reasons a profile control cannot modify its target. */
 export type ReadOnlyReason = 'management-required' | 'unaddressable';
-/** A package whose declared DSH peers reject the running DSH version, without an exemption for the exact pair. */
+/** A package whose declared DSH requirements reject the running DSH version, without an exemption for the exact pair. */
 export interface IncompatiblePlugin {
     name: string;
     version: string;
     runtimeVersion: string;
-    /** Only the DSH peer ranges the running version does not satisfy. */
-    peers: Record<string, string>;
+    /** Only the requirements the running version does not satisfy, keyed `engines.dsh` or by DSH peer package name. */
+    requirements: Record<string, string>;
 }
 /** Localizable management failure and optional external diagnostic. */
 export interface ManagementError {
-    code: ReadOnlyReason | 'unknown-plugin' | 'invalid-spec' | 'ambiguous-install' | 'not-bundle' | 'not-removable' | 'stop-profile' | 'bundle-in-use' | 'stale-approval' | 'incompatible-version' | 'operation-error';
+    code: ReadOnlyReason | 'unknown-plugin' | 'invalid-spec' | 'already-installed' | 'ambiguous-install' | 'not-bundle' | 'not-removable' | 'stop-profile' | 'bundle-in-use' | 'stale-approval' | 'incompatible-version' | 'operation-error';
     diagnostic?: string;
     /** Present with `incompatible-version`: the packages the running DSH version rejects. */
     incompatible?: IncompatiblePlugin[];
 }
+/**
+ * Why a change waits for the next start: `no-hmr` profiles apply changes only at startup; `package-moved` changes map an
+ * installed package to another directory without removing it first, or change or locally override a package the DSH
+ * installation provides; `host-module` changes reach
+ * modules the running process itself imports; `unmanaged-plugin` changes reach a plugin running outside a Loader entry;
+ * `module-comparison` means loaded modules could not be compared with disk.
+ */
+export type RestartReason = 'no-hmr' | 'package-moved' | 'host-module' | 'unmanaged-plugin' | 'module-comparison';
 /** One running-profile entry and its persistent control availability. */
 export type PluginInfo = PluginInventoryEntry & ({
     patchId: string;
@@ -108,6 +116,8 @@ export interface ChangeResult {
     changed: boolean;
     /** `cancelled` is an installation the caller stopped, its files restored. */
     application: 'applied' | 'restart-required' | 'overridden' | 'failed' | 'cancelled';
+    /** Present with `restart-required`: why the change takes effect only at the next start. */
+    restartReason?: RestartReason;
     /** Last attempted step; successful installation can proceed to enablement. */
     stage: 'install' | 'enable' | 'remove';
     target: string;

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "plugin-manager"
+  }
+}

package/locale/tools/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "plugin-manager/tools"
+  }
+}

package/locale/tools/zh.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "插件管理工具"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "插件管理服务",
+    "description": "管理当前运行配置中的插件与插件包，支持安装、移除和启停。"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-plugin-manager",
   "description": "Current-profile plugin and bundle management shared by dsh CLI, Web and agent tools",
-  "version": "0.2.1-alpha.2",
+  "version": "0.2.1-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -43,9 +43,13 @@
     "./tools": {
       "types": "./lib/types/tools.d.ts",
       "default": "./lib/types/tools.js"
-    }
+    },
+    "./tools/locale/*.json": "./locale/tools/*.json",
+    "./locale/*.json": "./locale/*.json"
   },
   "files": [
+    "locale/*.json",
+    "locale/tools/*.json",
     "lib/index.js",
     "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
@@ -56,26 +60,26 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.2",
-    "@deepseek-ai/schemastery": "~3.18.5-alpha.1",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.4",
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.2",
     "execa": "^10.0.1",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3",
-    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.2"
+    "zod": "4.4.3",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.4"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.1",
-    "@deepseek-ai/dsh-host-plugin-inventory": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-hmr": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-brand": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.2"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.2",
+    "@deepseek-ai/dsh-host-plugin-inventory": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-hmr": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-brand": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.4"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-hmr": {
@@ -87,22 +91,22 @@
   },
   "devDependencies": {
     "chokidar": "^4.0.3",
-    "@deepseek-ai/dsh-package-manifest": "0.2.1-alpha.2",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.1",
-    "@deepseek-ai/dsh-host-plugin-inventory": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-hmr": "0.2.1-alpha.2",
-    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.1",
-    "@deepseek-ai/dsh-brand": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.2"
+    "@deepseek-ai/dsh-package-manifest": "0.2.1-alpha.4",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.2",
+    "@deepseek-ai/dsh-host-plugin-inventory": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-hmr": "0.2.1-alpha.4",
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2",
+    "@deepseek-ai/dsh-brand": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.4"
   }
 }