@woosau/dsh-custom-env 0.0.0-stage → 0.1.0

package/lib/types/cli-path/resolve-expected.d.ts

@@ -0,0 +1,24 @@
+/** Infer the CLI launcher this Host process should expose on PATH. */
+/** Resolved expected CLI locations, or a reason when resolution fails. */
+export interface ExpectedCli {
+    /** Absolute path of the launcher file (`dsh` / `dsh.cmd`). */
+    readonly launcher: string;
+    /** Directory that should appear on PATH (Windows) or be the symlink target's directory. */
+    readonly directory: string;
+    /** How the expectation was derived. */
+    readonly kind: 'electron-resources' | 'argv' | 'walk';
+}
+/** Inputs for tests; defaults to the live process. */
+export interface ResolveExpectedOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly execPath?: string;
+    readonly argv?: readonly string[];
+    readonly electronRunAsNode?: string | undefined;
+    readonly exists?: (path: string) => boolean;
+}
+/**
+ * Infer the expected dsh launcher from how this Host was started.
+ * @param options - optional process overrides for tests.
+ * @returns expected locations, or `undefined` when unknown.
+ */
+export declare function resolveExpectedCli(options?: ResolveExpectedOptions): ExpectedCli | undefined;

package/lib/types/cli-path/status.d.ts

@@ -0,0 +1,32 @@
+/** Compose CLI PATH status for the settings UI. */
+import { type ActiveCli } from './inspect-active.ts';
+import { type ExpectedCli } from './resolve-expected.ts';
+/** Snapshot returned by `customEnv/cliStatus` and `cliInstall`. */
+export interface CliStatus {
+    /** Host platform. */
+    readonly platform: NodeJS.Platform;
+    /** First `dsh` found on the user environment PATH, if any. */
+    readonly activePath: string | null;
+    /** Expected launcher for this Host, if resolved. */
+    readonly expectedPath: string | null;
+    /** Expected bin directory (Windows PATH entry). */
+    readonly expectedDirectory: string | null;
+    /** Whether active matches expected. */
+    readonly matches: boolean;
+    /** Whether the Install button should be shown. */
+    readonly canInstall: boolean;
+    /** Why install is unavailable or paths could not be resolved. */
+    readonly reason: string | null;
+}
+/** Optional overrides for tests / Windows registry inspect. */
+export interface BuildCliStatusOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly expected?: ExpectedCli | undefined;
+    readonly active?: ActiveCli;
+    readonly resolveFailedReason?: string;
+}
+/**
+ * Build a status object from expected + active probes.
+ * @param options - optional overrides.
+ */
+export declare function buildCliStatus(options?: BuildCliStatusOptions): CliStatus;

package/lib/types/cli-path/windows.d.ts

@@ -0,0 +1,26 @@
+/** Windows: inspect / install dsh onto the user PATH via adapted command-path.ps1. */
+/** State returned by the PowerShell worker. */
+export interface WindowsCommandState {
+    readonly fingerprint: string;
+    readonly directory: string;
+    readonly activeCommand?: string;
+    readonly available: boolean;
+    readonly managed: boolean;
+}
+declare class WindowsCommandError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Resolve the packaged `scripts/command-path.ps1` next to this module's package root.
+ * Works for `lib/index.js` (bundled) and source layouts.
+ */
+export declare function commandPathScript(fromUrl?: string): string;
+/**
+ * Run inspect or install against the user PATH.
+ * @param operation - `inspect` or `install`.
+ * @param directory - absolute directory containing `dsh.cmd`.
+ * @param expected - fingerprint from a prior inspect (required for install).
+ */
+export declare function runWindowsCommandPath(operation: 'inspect' | 'install', directory: string, expected?: string): Promise<WindowsCommandState>;
+export { WindowsCommandError };

package/lib/types/client/EnvSettingsSection.d.ts

@@ -0,0 +1,20 @@
+/** Settings section: `$DSH_HOME/.env` editor + global `dsh` path. */
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { CliStatus, EnvSnapshot } from '../types.ts';
+import type { EnvSettingsKey } from './locales.ts';
+export interface EnvSettingsInjected {
+    readonly load: () => Promise<EnvSnapshot>;
+    /** Create (`id === ""`) or update/rename one row by stable id. */
+    readonly upsert: (id: string, name: string, value: string) => Promise<EnvSnapshot>;
+    readonly remove: (id: string) => Promise<EnvSnapshot>;
+    readonly restore: (id: string) => Promise<EnvSnapshot>;
+    readonly cliStatus: () => Promise<CliStatus>;
+    readonly cliInstall: () => Promise<CliStatus>;
+}
+export type EnvSettingsSectionProps = PropsRuntime<'settings.section'> & PropsLocale<'settings.env'> & InjectFace<EnvSettingsInjected>;
+/**
+ * Render the environment settings page.
+ * @param props - locale `t` and Host remote callbacks.
+ */
+export declare function EnvSettingsSection({ t, load, upsert, remove, restore, cliStatus, cliInstall, }: EnvSettingsSectionProps): any;
+export type { EnvSettingsKey };

package/lib/types/client/index.d.ts

@@ -0,0 +1,17 @@
+/** Browser entry for `$DSH_HOME/.env` settings. */
+import type { Context } from '@deepseek-ai/cordis';
+export { inject } from './mount.ts';
+export type { EnvSettingsKey } from './locales.ts';
+export type { EnvSettingsInjected, EnvSettingsSectionProps } from './EnvSettingsSection.tsx';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Environment variables settings copy. */
+        'settings.env': import('./locales.ts').EnvSettingsKey;
+    }
+}
+/**
+ * Mount the environment settings page and its Remote methods.
+ * @param ctx - browser plugin context.
+ * @returns disposer joining UI and Remote withdrawal.
+ */
+export declare function apply(ctx: Context): Promise<() => Promise<void>>;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,9 @@
+/** Locale dictionaries for the environment-variables settings section. */
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "settings.env";
+/** Keys in the environment settings dictionaries. */
+export type EnvSettingsKey = 'nav' | 'title' | 'empty' | 'name' | 'value' | 'actions' | 'confirm' | 'cancel' | 'remove' | 'removeConfirmTitle' | 'removeConfirm' | 'restore' | 'close' | 'namePlaceholder' | 'valuePlaceholder' | 'loading' | 'error' | 'invalidName' | 'restartRequired' | 'cliTitle' | 'cliActiveMissing' | 'cliInstall' | 'cliMacConflict' | 'cliInstallError' | 'cliReasonUnresolved' | 'cliReasonUnsupported';
+/** English copy. */
+export declare const en: Record<EnvSettingsKey, string>;
+/** Chinese copy. */
+export declare const zh: Record<EnvSettingsKey, string>;

package/lib/types/client/mount.d.ts

@@ -0,0 +1,11 @@
+/** Mount Remote contribution and the settings.section page. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+export declare const inject: readonly ["remote", "slots", "locale"];
+/**
+ * Mount the custom-env Remote and settings UI.
+ * @param ctx - Client plugin lifetime.
+ * @param contribution - generated controller Remote definitions.
+ * @returns disposer that removes both contributions.
+ */
+export declare function mountCustomEnv(ctx: Context, contribution: TypertRemoteContribution): Promise<() => Promise<void>>;

package/lib/types/env-file.d.ts

@@ -0,0 +1,40 @@
+/** Line-oriented `$DSH_HOME/.env` read/write helpers. */
+/** Name/value pair before Host baseline classification. */
+export interface RawEnvEntry {
+    readonly name: string;
+    readonly value: string;
+}
+/** Absolute path of `$DSH_HOME/.env`. */
+export declare function envFilePath(): string;
+/**
+ * Read non-empty writable entries from `$DSH_HOME/.env`.
+ * @returns Variable map, or `{}` when absent / empty.
+ */
+export declare function loadEnvMap(): Readonly<Record<string, string>>;
+/**
+ * List writable entries in `.env` file order (new keys stay at the end).
+ * @returns Path, existence, and ordered entries.
+ */
+export declare function listEnvEntries(): {
+    path: string;
+    exists: boolean;
+    entries: RawEnvEntry[];
+};
+/**
+ * Write `name=value` in place of `replaceName` (keeps order), or append when missing.
+ * Use the same name for both to update; different names to rename in place.
+ * @param replaceName - line to replace.
+ * @param name - name to store.
+ * @param value - non-empty value.
+ */
+export declare function writeEnvEntry(replaceName: string, name: string, value: string): void;
+/** Create or replace one key (append when new). */
+export declare function upsertEnvEntry(name: string, value: string): void;
+/** Rename one key in place (keeps file order). */
+export declare function renameEnvEntry(from: string, to: string, value: string): void;
+/**
+ * Remove one key from `$DSH_HOME/.env` when present.
+ * @param name - variable name.
+ * @returns true when a line was removed.
+ */
+export declare function removeEnvEntry(name: string): boolean;

package/lib/types/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Host service: load `$DSH_HOME/.env` into process.env and expose CRUD remotes.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { envFilePath } from './env-file.ts';
+import { type CliStatus, type EnvSnapshot } from './types.ts';
+export type { BaselineRow, CliStatus, EnvEntry, EnvSnapshot } from './types.ts';
+export { classifyEntry } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        customEnv: CustomEnvController;
+    }
+}
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        'custom-env/invalid-name': {
+            readonly name: string;
+        };
+        'custom-env/invalid-value': {
+            readonly name: string;
+        };
+        'custom-env/cli-install-failed': {
+            readonly code: string;
+        };
+        'custom-env/restore-failed': {
+            readonly name: string;
+        };
+    }
+}
+/** Host remote for `$DSH_HOME/.env` CRUD with live Host/OS sync. */
+export default class CustomEnvController extends TypertRemoteService {
+    private readonly baselineById;
+    private readonly idByName;
+    private readonly nameById;
+    private idSeq;
+    constructor(ctx: Context);
+    private allocId;
+    private bind;
+    private unbind;
+    private requireName;
+    /** Persist `name=value` replacing `from` in place; sync process.env / OS. */
+    private commit;
+    /** @returns path, existence, and file-ordered entries. */
+    list(): Promise<EnvSnapshot>;
+    /**
+     * Create or update one row. Empty `id` creates; otherwise keeps that baseline id across renames.
+     * @param id - row id, or `""` for a new row.
+     * @param name - variable name.
+     * @param value - non-empty value.
+     */
+    upsert(id: string, name: string, value: string): Promise<EnvSnapshot>;
+    /** @param id - row id from list(). */
+    deleteEntry(id: string): Promise<EnvSnapshot>;
+    /** Restore Host-start original name+value, or delete if added after start. */
+    restore(id: string): Promise<EnvSnapshot>;
+    cliStatus(): Promise<CliStatus>;
+    cliInstall(): Promise<CliStatus>;
+}
+export { envFilePath };

package/lib/types/names.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Names and prefixes that must not be written through `$DSH_HOME/.env`
+ * (mirrors app-boot bootstrap rejection).
+ */
+/**
+ * Whether a variable may come only from the inherited process environment.
+ * @param name - candidate variable name.
+ * @returns true when `.env` must not set this name.
+ */
+export declare function isBootstrapOnly(name: string): boolean;
+/**
+ * Whether `name` is a writable non-bootstrap environment key.
+ * @param name - candidate variable name.
+ * @returns true when the key may be stored in `$DSH_HOME/.env`.
+ */
+export declare function isWritableEnvName(name: string): boolean;

package/lib/types/os-user-env/index.d.ts

@@ -0,0 +1,13 @@
+/** OS user-environment sync for Windows and macOS (no-op elsewhere). */
+/**
+ * Persist entries into the current user's OS environment when supported.
+ * @param entries - Variable map to write.
+ */
+export declare function persistUserEnv(entries: Readonly<Record<string, string>>): void;
+/**
+ * Remove one key from the current user's OS environment when supported.
+ * @param name - Variable name to delete.
+ */
+export declare function removeUserEnv(name: string): void;
+export { persistWindowsUserEnv, removeWindowsUserEnv } from './windows.ts';
+export { persistMacosUserEnv, removeMacosUserEnv } from './macos.ts';

package/lib/types/os-user-env/macos.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Persist user environment variables on macOS via launchctl and a Login LaunchAgent.
+ */
+/**
+ * Set user-domain environment variables for new GUI sessions and refresh the Login Agent.
+ * @param entries - Variable map to persist.
+ * @param platform - Override for tests; defaults to `process.platform`.
+ */
+export declare function persistMacosUserEnv(entries: Readonly<Record<string, string>>, platform?: NodeJS.Platform): void;
+/**
+ * Unset one user-domain environment variable and refresh the Login Agent.
+ * @param name - Variable name to remove.
+ * @param platform - Override for tests; defaults to `process.platform`.
+ */
+export declare function removeMacosUserEnv(name: string, platform?: NodeJS.Platform): void;

package/lib/types/os-user-env/windows.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Persist or delete variables in the Windows user environment (HKCU\\Environment)
+ * via koffi + advapi32/user32 — same approach as the former in-tree custom-env.
+ */
+/** Win32 registry and broadcast calls used to publish user environment values. */
+export interface WindowsUserEnvBindings {
+    readonly openKey: (hKey: number, subKey: string, options: number, samDesired: number, result: [unknown]) => number;
+    readonly setValue: (hKey: unknown, valueName: string, reserved: number, type: number, data: Buffer, cbData: number) => number;
+    readonly deleteValue: (hKey: unknown, valueName: string) => number;
+    readonly closeKey: (hKey: unknown) => number;
+    readonly sendMessageTimeout: (hWnd: number, msg: number, wParam: number, lParam: string, flags: number, timeoutMs: number, result: [number]) => number;
+}
+/**
+ * Install FFI bindings for tests (skips loading koffi).
+ * @param next - Mock bindings, or `undefined` to clear the cache.
+ */
+export declare function setWindowsUserEnvBindingsForTests(next: WindowsUserEnvBindings | undefined): void;
+/**
+ * Encode a REG_SZ payload (UTF-16LE including trailing NUL).
+ * @param value - String to store.
+ * @returns Buffer accepted by RegSetValueExW.
+ */
+export declare function encodeRegSz(value: string): Buffer;
+/**
+ * Write entries into HKCU\\Environment and broadcast WM_SETTINGCHANGE.
+ * No-op on non-Windows hosts or when `entries` is empty.
+ * @param entries - Variable map to persist.
+ * @param platform - Override for tests; defaults to `process.platform`.
+ */
+export declare function persistWindowsUserEnv(entries: Readonly<Record<string, string>>, platform?: NodeJS.Platform): void;
+/**
+ * Delete one user environment value from HKCU\\Environment.
+ * Missing values are ignored.
+ * @param name - Variable name to remove.
+ * @param platform - Override for tests; defaults to `process.platform`.
+ */
+export declare function removeWindowsUserEnv(name: string, platform?: NodeJS.Platform): void;

package/lib/types/types.d.ts

@@ -0,0 +1,44 @@
+/** Session types and Host-start baseline classification. */
+export type EnvEntryKind = 'unchanged' | 'modified' | 'added';
+/** Host-start original name and value for one row id. */
+export interface BaselineRow {
+    readonly name: string;
+    readonly value: string;
+}
+/** One editable environment variable row. */
+export interface EnvEntry {
+    /** Stable row id; survives renames. */
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly kind: EnvEntryKind;
+    /** Host-start original value when `kind === 'modified'`; otherwise `null`. */
+    readonly previous: string | null;
+}
+/** Snapshot returned by `customEnv/list`. */
+export interface EnvSnapshot {
+    readonly path: string;
+    readonly exists: boolean;
+    readonly entries: readonly EnvEntry[];
+}
+/** Snapshot returned by `customEnv/cliStatus` and `cliInstall`. */
+export interface CliStatus {
+    readonly platform: string;
+    readonly activePath: string | null;
+    readonly expectedPath: string | null;
+    readonly expectedDirectory: string | null;
+    readonly matches: boolean;
+    readonly canInstall: boolean;
+    readonly reason: string | null;
+}
+/**
+ * Classify one row against the Host-start baseline by stable id.
+ * @param id - row id.
+ * @param name - current file name.
+ * @param value - current file value.
+ * @param baselineById - Host-start originals.
+ */
+export declare function classifyEntry(id: string, name: string, value: string, baselineById: ReadonlyMap<string, BaselineRow>): {
+    readonly kind: EnvEntryKind;
+    readonly previous: string | null;
+};

package/locale/en.json

@@ -0,0 +1,4 @@
+{
+  "meta.title": "Environment variables",
+  "meta.description": "Edit $DSH_HOME/.env, sync Host/OS user environment, and install the dsh CLI for this Host on Windows/macOS."
+}

package/locale/zh.json

@@ -0,0 +1,4 @@
+{
+  "meta.title": "环境变量",
+  "meta.description": "编辑 $DSH_HOME/.env，同步 Host/操作系统用户环境，并在 Windows/macOS 为本 Host 安装 dsh CLI。"
+}

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@woosau/dsh-custom-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "DSH plugin: manage $DSH_HOME/.env from Settings, sync Host process.env and Windows/macOS user environment",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ]
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ownduck/dsh-custom-env.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ownduck/dsh-custom-env/issues"
+  },
+  "homepage": "https://github.com/ownduck/dsh-custom-env#readme",
+  "engines": {
+    "dsh": ">=0.2.0",
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=0.2.0",
+    "@deepseek-ai/dsh-home-paths": ">=0.2.0",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.2.0"
+  },
+  "dependencies": {
+    "koffi": "3.1.1",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "locale/*.json",
+    "cordis.patch.yml",
+    "scripts/command-path.ps1",
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "test": "node ./scripts/run-tests.mjs"
+  }
+}

package/scripts/command-path.ps1

@@ -0,0 +1,150 @@
+<# Per-user PATH ownership for dsh-custom-env (not DeepSeekHarness Desktop). #>
+function Invoke-DshCommandPath {
+    param([hashtable]$Request, [string]$EnvironmentKey, [string]$OwnerKey, [string]$MachinePath, [string]$MutexName)
+    $ErrorActionPreference = 'Stop'
+    function Fail([string]$Code, [string]$Message) {
+        $error = [InvalidOperationException]::new($Message)
+        $error.Data['code'] = $Code
+        throw $error
+    }
+    function Comparable([string]$Path) {
+        $expanded = [Environment]::ExpandEnvironmentVariables($Path.Trim().Trim('"'))
+        try {
+            if (-not [IO.Path]::IsPathRooted($expanded)) { return $expanded }
+            return [IO.Path]::GetFullPath($expanded).TrimEnd('\','/').ToUpperInvariant()
+        } catch {
+            # Invalid user PATH entries cannot identify the managed directory.
+            return $expanded
+        }
+    }
+    $directory = [string]$Request.directory
+    if (-not [IO.Path]::IsPathRooted($directory) -or $directory.Contains(';') -or $directory.Contains([char]0)) {
+        Fail 'EUNSUPPORTED' 'The command directory cannot be represented in PATH.'
+    }
+    $directory = [IO.Path]::GetFullPath($directory)
+    if ($Request.operation -notin @('inspect','install','remove')) { Fail 'EINVAL' 'Unknown command operation.' }
+    $mutex = [Threading.Mutex]::new($false, $MutexName)
+    $locked = $false
+    try {
+        try { $locked = $mutex.WaitOne(5000) } catch [Threading.AbandonedMutexException] { $locked = $true }
+        if (-not $locked) { Fail 'EBUSY' 'Another command-management operation is running.' }
+        $environment = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($EnvironmentKey)
+        $owner = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($OwnerKey)
+        try {
+            $raw = if ($environment) { $environment.GetValue('Path', $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) } else { $null }
+            if ($null -ne $raw -and $raw -isnot [string]) { Fail 'EUNSUPPORTED' 'The user PATH value is not a string.' }
+            $kind = if ($null -ne $raw) { $environment.GetValueKind('Path') } else { [Microsoft.Win32.RegistryValueKind]::ExpandString }
+            $owned = if ($owner) { $owner.GetValue('Directory', $null) } else { $null }
+            $wasAbsent = if ($owner) { $owner.GetValue('PathWasAbsent', 0) -eq 1 } else { $false }
+            $retained = if ($owner) { [int]$owner.GetValue('RetainedEntries', 0) } else { 0 }
+        } finally {
+            if ($environment) { $environment.Dispose() }
+            if ($owner) { $owner.Dispose() }
+        }
+        $snapshot = [ordered]@{ path=$raw; kind=[string]$kind; owned=$owned; absent=$wasAbsent; retained=$retained; directory=$directory; machine=$MachinePath }
+        $sha = [Security.Cryptography.SHA256]::Create()
+        try { $fingerprint = ([BitConverter]::ToString($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes(($snapshot | ConvertTo-Json -Compress))))).Replace('-','').ToLowerInvariant() }
+        finally { $sha.Dispose() }
+        if ($Request.operation -ne 'inspect' -and $Request.expected -ne $fingerprint) { Fail 'ESTALE' 'PATH changed after confirmation.' }
+        $parts = if ($null -eq $raw) { @() } else { @($raw.Split(';')) }
+        $current = Comparable $directory
+        $old = if ($owned) { Comparable ([string]$owned) } else { $null }
+        $kept = $parts
+        if ($old -and ($Request.operation -eq 'install' -or ($Request.operation -eq 'remove' -and $old -eq $current))) {
+            $ownedMatches = @($parts | Where-Object { $_ -ceq $owned }).Count
+            if ($ownedMatches -gt $retained) {
+                $index = [Array]::IndexOf($parts, $owned)
+                $kept = @(); for ($i = 0; $i -lt $parts.Count; $i++) { if ($i -ne $index) { $kept += $parts[$i] } }
+            }
+        }
+        if ($Request.operation -eq 'install') {
+            if (-not (Test-Path -LiteralPath (Join-Path $directory 'dsh.cmd') -PathType Leaf)) { Fail 'ENOENT' 'The installed launcher is unavailable.' }
+            $next = (@($directory) + $kept) -join ';'
+            $environment = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey($EnvironmentKey)
+            $owner = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey($OwnerKey)
+            try {
+                $environment.SetValue('Path', $next, $kind)
+                $owner.SetValue('Directory', $directory, [Microsoft.Win32.RegistryValueKind]::String)
+                $absent = ($null -eq $raw) -or ($owned -and $wasAbsent)
+                $owner.SetValue('PathWasAbsent', [int]$absent, [Microsoft.Win32.RegistryValueKind]::DWord)
+                $owner.SetValue('RetainedEntries', @($kept | Where-Object { $_ -ceq $directory }).Count, [Microsoft.Win32.RegistryValueKind]::DWord)
+            } finally { $environment.Dispose(); $owner.Dispose() }
+            $raw = $next
+            $owned = $directory
+        } elseif ($Request.operation -eq 'remove') {
+            if ($kept.Count -ne $parts.Count) {
+                $environment = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey($EnvironmentKey)
+                try {
+                    if ($kept.Count -eq 0 -and $wasAbsent) { $environment.DeleteValue('Path', $false); $raw = $null }
+                    else { $raw = $kept -join ';'; $environment.SetValue('Path', $raw, $kind) }
+                } finally { $environment.Dispose() }
+            }
+            $owner = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($OwnerKey, $true)
+            if ($owner -and $old -eq $current) {
+                try { $owner.DeleteValue('Directory', $false); $owner.DeleteValue('PathWasAbsent', $false); $owner.DeleteValue('RetainedEntries', $false) }
+                finally { $owner.Dispose() }
+                $owned = $null
+            } elseif ($owner) {
+                $owner.Dispose()
+            }
+        }
+        $active = $null
+        foreach ($part in (($MachinePath + ';' + [string]$raw).Split(';'))) {
+            $path = [Environment]::ExpandEnvironmentVariables($part.Trim().Trim('"'))
+            try { $rooted = [IO.Path]::IsPathRooted($path) } catch { continue }
+            if (-not $rooted) { continue }
+            $extensions = if ($env:PATHEXT) { @($env:PATHEXT.Split(';')) } else { @('.com','.exe','.bat','.cmd') }
+            foreach ($extension in (@('.ps1') + $extensions)) {
+                try {
+                    $candidate = Join-Path $path ('dsh' + $extension)
+                    if (Test-Path -LiteralPath $candidate -PathType Leaf) { $active = $candidate; break }
+                } catch {
+                    # Invalid or unavailable PATH candidates do not prevent checking later entries.
+                    continue
+                }
+            }
+            if ($active) { break }
+        }
+        $onPath = @(([string]$raw).Split(';') | Where-Object { (Comparable $_) -eq $current }).Count -gt 0
+        return [ordered]@{ fingerprint=$fingerprint; directory=$directory; ownedDirectory=$owned; managed=([bool]$owned -and (Comparable ([string]$owned)) -eq $current); activeCommand=$active; available=($onPath -and (Test-Path -LiteralPath (Join-Path $directory 'dsh.cmd') -PathType Leaf)) }
+    } finally {
+        if ($locked) { $mutex.ReleaseMutex() }
+        $mutex.Dispose()
+    }
+}
+
+function Send-DshCommandEnvironmentChange {
+    try {
+        if (-not ('CustomEnvCommandEnvironment' -as [type])) {
+            Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class CustomEnvCommandEnvironment { [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern IntPtr SendMessageTimeout(IntPtr h, uint m, IntPtr w, string l, uint f, uint t, out IntPtr r); }'
+        }
+        $ignored = [IntPtr]::Zero
+        [void][CustomEnvCommandEnvironment]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [IntPtr]::Zero, 'Environment', 2, 2000, [ref]$ignored)
+    } catch {
+        # The PATH write is committed. A failed notification only delays other processes observing it.
+        return
+    }
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    $ErrorActionPreference = 'Stop'
+    [Console]::InputEncoding = [Text.UTF8Encoding]::new($false)
+    [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+    try {
+        $inputValue = [Console]::In.ReadToEnd() | ConvertFrom-Json
+        $request = @{ operation=$inputValue.operation; directory=$inputValue.directory; expected=$inputValue.expected }
+        $machine = [Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment')
+        try { $machinePath = [string]$machine.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) }
+        finally { $machine.Dispose() }
+        $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+        $state = Invoke-DshCommandPath -Request $request -EnvironmentKey 'Environment' -OwnerKey 'Software\dsh-custom-env\Command' -MachinePath $machinePath -MutexName ('Global\dsh-custom-env.Command.' + $sid)
+        if ($request.operation -ne 'inspect') {
+            Send-DshCommandEnvironmentChange
+        }
+        @{ ok=$true; state=$state } | ConvertTo-Json -Compress -Depth 5
+    } catch {
+        $code = if ($_.Exception.Data['code']) { $_.Exception.Data['code'] } else { 'EIO' }
+        @{ ok=$false; code=$code; message=$_.Exception.Message } | ConvertTo-Json -Compress
+        exit 1
+    }
+}