@woosau/dsh-custom-env 0.1.8 → 0.1.10

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

@@ -1,13 +1,17 @@
 /** 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 { CliStatus, EnvGroup, 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 upsert: (id: string, name: string, value: string, groupId?: string) => Promise<EnvSnapshot>;
     readonly remove: (id: string) => Promise<EnvSnapshot>;
     readonly restore: (id: string) => Promise<EnvSnapshot>;
+    readonly moveEntry: (id: string, groupId: string) => Promise<EnvSnapshot>;
+    readonly createGroup: (title: string) => Promise<EnvGroup>;
+    readonly renameGroup: (id: string, title: string) => Promise<EnvGroup>;
+    readonly deleteGroup: (id: string, moveToDefault: boolean) => Promise<EnvSnapshot>;
     readonly cliStatus: () => Promise<CliStatus>;
     readonly cliInstall: () => Promise<CliStatus>;
 }
@@ -16,5 +20,5 @@ export type EnvSettingsSectionProps = PropsRuntime<'settings.section'> & PropsLo
  * 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 declare function EnvSettingsSection({ t, load, upsert, remove, restore, moveEntry, createGroup, renameGroup, deleteGroup, cliStatus, cliInstall, }: EnvSettingsSectionProps): any;
 export type { EnvSettingsKey };

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

@@ -5,7 +5,6 @@ export declare const NS: "settings.env";
 export declare const zh: {
     'panel.nav': string;
     'panel.title': string;
-    'panel.empty': string;
     'panel.loading': string;
     'field.name': string;
     'field.value': string;
@@ -19,6 +18,16 @@ export declare const zh: {
     'action.removeConfirm': string;
     'action.restore': string;
     'action.close': string;
+    'action.moveGroup': string;
+    'action.createGroup': string;
+    'action.renameGroup': string;
+    'action.deleteGroup': string;
+    'action.deleteGroupTitle': string;
+    'action.deleteGroupConfirm': string;
+    'action.deleteGroupMove': string;
+    'action.groupTitle': string;
+    'action.groupTitlePlaceholder': string;
+    'group.defaultTitle': string;
     'status.restartRequired': string;
     'cli.title': string;
     'cli.activeMissing': string;
@@ -27,6 +36,7 @@ export declare const zh: {
     'error.generic': string;
     'error.invalidName': string;
     'error.invalidValue': string;
+    'error.invalidGroup': string;
     'error.restoreFailed': string;
     'error.cliInstall': string;
     'error.cliUnresolved': string;
@@ -38,7 +48,6 @@ export type EnvSettingsKey = keyof typeof zh;
 export declare const en: {
     'panel.nav': string;
     'panel.title': string;
-    'panel.empty': string;
     'panel.loading': string;
     'field.name': string;
     'field.value': string;
@@ -52,6 +61,16 @@ export declare const en: {
     'action.removeConfirm': string;
     'action.restore': string;
     'action.close': string;
+    'action.moveGroup': string;
+    'action.createGroup': string;
+    'action.renameGroup': string;
+    'action.deleteGroup': string;
+    'action.deleteGroupTitle': string;
+    'action.deleteGroupConfirm': string;
+    'action.deleteGroupMove': string;
+    'action.groupTitle': string;
+    'action.groupTitlePlaceholder': string;
+    'group.defaultTitle': string;
     'status.restartRequired': string;
     'cli.title': string;
     'cli.activeMissing': string;
@@ -60,6 +79,7 @@ export declare const en: {
     'error.generic': string;
     'error.invalidName': string;
     'error.invalidValue': string;
+    'error.invalidGroup': string;
     'error.restoreFailed': string;
     'error.cliInstall': string;
     'error.cliUnresolved': string;

package/lib/types/group-ids.d.ts

@@ -0,0 +1,5 @@
+/** Shared group id constants (safe for Host and Client bundles). */
+/** Stable id of the built-in default group. */
+export declare const DEFAULT_GROUP_ID = "default";
+/** Fixed title stored for the default group (UI may localize on display). */
+export declare const DEFAULT_GROUP_TITLE = "\u9ED8\u8BA4\u5206\u7EC4";

package/lib/types/groups-store.d.ts

@@ -0,0 +1,73 @@
+/** Sidecar JSON for environment variable groups (UI / plugin metadata only). */
+import type { EnvGroup } from './types.ts';
+export { DEFAULT_GROUP_ID, DEFAULT_GROUP_TITLE } from './group-ids.ts';
+/** On-disk groups document. */
+export interface GroupsFile {
+    readonly version: 1;
+    readonly groups: readonly EnvGroup[];
+    /** entryId → groupId */
+    readonly membership: Readonly<Record<string, string>>;
+}
+/** Absolute path of `$DSH_HOME/.dsh-custom-env-groups.json`. */
+export declare function groupsFilePath(): string;
+/**
+ * Normalize arbitrary JSON into a valid groups file (always includes default).
+ * @param raw - Parsed JSON or undefined.
+ */
+export declare function normalizeGroupsFile(raw: unknown): GroupsFile;
+/** Read and normalize the groups sidecar (missing file → default only). */
+export declare function readGroupsFile(): GroupsFile;
+/** Persist a groups file under `$DSH_HOME`. */
+export declare function writeGroupsFile(file: GroupsFile): void;
+/**
+ * Drop membership keys that no longer exist as live row ids.
+ * @param file - Current groups file.
+ * @param liveIds - Row ids still present.
+ */
+export declare function pruneMembership(file: GroupsFile, liveIds: ReadonlySet<string>): GroupsFile;
+/**
+ * Resolve the group for a row id (missing → default).
+ * @param file - Groups file.
+ * @param entryId - Stable row id.
+ */
+export declare function resolveGroupId(file: GroupsFile, entryId: string): string;
+/**
+ * Assign a row to a group.
+ * @param file - Groups file.
+ * @param entryId - Row id.
+ * @param groupId - Target group (must exist, or default).
+ */
+export declare function setMembership(file: GroupsFile, entryId: string, groupId: string): GroupsFile;
+/** Remove one row from membership. */
+export declare function clearMembership(file: GroupsFile, entryId: string): GroupsFile;
+/** Remove many rows from membership. */
+export declare function clearMembershipMany(file: GroupsFile, entryIds: readonly string[]): GroupsFile;
+/**
+ * Append a custom group.
+ * @param file - Groups file.
+ * @param title - Non-empty display title.
+ */
+export declare function createGroup(file: GroupsFile, title: string): {
+    readonly file: GroupsFile;
+    readonly group: EnvGroup;
+};
+/**
+ * Rename a custom group (not default).
+ * @param file - Groups file.
+ * @param id - Group id.
+ * @param title - New title.
+ */
+export declare function renameGroup(file: GroupsFile, id: string, title: string): GroupsFile;
+/**
+ * Delete a custom group and either move or drop its membership keys.
+ * Does not delete `.env` values — caller handles variable deletion when needed.
+ * @param file - Groups file.
+ * @param id - Group id to remove.
+ * @param moveToDefault - When true, reassign members to default; else clear membership.
+ */
+export declare function deleteGroupMeta(file: GroupsFile, id: string, moveToDefault: boolean): {
+    readonly file: GroupsFile;
+    readonly memberIds: readonly string[];
+};
+/** Whether `groupId` exists in the file (including default). */
+export declare function hasGroup(file: GroupsFile, groupId: string): boolean;

package/lib/types/index.d.ts

@@ -4,9 +4,10 @@
 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, type EnvVarWrite } from './types.ts';
-export type { BaselineRow, CliStatus, EnvEntry, EnvSnapshot, EnvVarWrite } from './types.ts';
+import { type CliStatus, type DeleteGroupOptions, type EnvGroup, type EnvSnapshot, type EnvVarWrite } from './types.ts';
+export type { BaselineRow, CliStatus, DeleteGroupOptions, EnvEntry, EnvGroup, EnvSnapshot, EnvVarWrite, } from './types.ts';
 export { classifyEntry } from './types.ts';
+export { DEFAULT_GROUP_ID, DEFAULT_GROUP_TITLE } from './group-ids.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         customEnv: CustomEnvController;
@@ -20,6 +21,9 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         'custom-env/invalid-value': {
             readonly name: string;
         };
+        'custom-env/invalid-group': {
+            readonly group: string;
+        };
         'custom-env/cli-install-failed': {
             readonly code: string;
         };
@@ -39,34 +43,41 @@ export default class CustomEnvController extends TypertRemoteService {
     private bind;
     private unbind;
     private requireName;
+    private loadGroups;
+    private saveGroups;
+    private requireGroup;
     /**
      * Write `name=value` replacing `from` in place; sync process.env / OS.
      * Empty values create missing keys only, unless `forceEmpty` (restore).
      */
     private commit;
-    /** @returns path, existence, and file-ordered entries. */
+    /** @returns path, existence, groups, 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 - value (empty creates only when missing; Settings UI may still reject empty drafts).
+     * @param groupId - required for create semantics (`id === ""`, defaults to `default`);
+     *   on update, omit to keep membership, or pass to reassign (same as `moveEntry`).
      */
-    upsert(id: string, name: string, value: string): Promise<EnvSnapshot>;
+    upsert(id: string, name: string, value: string, groupId?: string): Promise<EnvSnapshot>;
     /**
      * Create or replace many variables by name (plugin-facing).
      * Non-empty values always write; empty values create missing keys only and do not
      * clear existing `$DSH_HOME/.env` or OS user values. One file rewrite; last
      * duplicate name wins. Invalid names reject the whole batch.
-     * @param entries - name/value pairs.
+     * @param entries - name/value pairs; optional `group` assigns membership when set.
+     *   Omitted `group`: new names → `default`; existing names keep their group.
      */
     setVars(entries: readonly EnvVarWrite[]): Promise<void>;
     /**
      * Create or replace one variable by name (plugin-facing).
      * @param name - writable variable name.
      * @param value - non-empty always stores; `""` writes `NAME=` only when the key is absent.
+     * @param group - optional group id; when omitted, new names use `default` and existing keep theirs.
      */
-    setVar(name: string, value: string): Promise<void>;
+    setVar(name: string, value: string, group?: string): Promise<void>;
     /**
      * Remove many variables by name (plugin-facing).
      * @param names - writable variable names.
@@ -83,6 +94,29 @@ export default class CustomEnvController extends TypertRemoteService {
     deleteEntry(id: string): Promise<EnvSnapshot>;
     /** Restore Host-start original name+value, or delete if added after start. */
     restore(id: string): Promise<EnvSnapshot>;
+    /**
+     * Create a custom group.
+     * @param title - Non-empty display title.
+     */
+    createGroup(title: string): Promise<EnvGroup>;
+    /**
+     * Rename a custom group (not the default group).
+     * @param id - Group id.
+     * @param title - New title.
+     */
+    renameGroup(id: string, title: string): Promise<EnvGroup>;
+    /**
+     * Delete a custom group.
+     * @param id - Group id (not `default`).
+     * @param options - When `moveToDefault` is false, member variables are removed from `.env`.
+     */
+    deleteGroup(id: string, options: DeleteGroupOptions): Promise<EnvSnapshot>;
+    /**
+     * Move one row into another group.
+     * @param id - Row id.
+     * @param groupId - Target group id.
+     */
+    moveEntry(id: string, groupId: string): Promise<EnvSnapshot>;
     cliStatus(): Promise<CliStatus>;
     cliInstall(): Promise<CliStatus>;
 }

package/lib/types/os-user-env/write-user-env-child.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Spawn a child to persist OS user env without blocking the Host.
+ * Sets `ELECTRON_RUN_AS_NODE` so Desktop's Electron binary runs the script as Node.
+ */
+import { type ChildProcess } from 'node:child_process';
+/**
+ * Start a child that writes `entries` into the OS user environment.
+ * @param entries - Variable map to persist.
+ * @returns The child process, or `undefined` when the bundled script is missing.
+ */
+export declare function startWriteUserEnvChild(entries: Readonly<Record<string, string>>): ChildProcess | undefined;

package/lib/types/os-user-env/write-user-env.child.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Child-process entry: read JSON env entries from stdin and persist to the OS user env.
+ */
+export {};

package/lib/types/types.d.ts

@@ -5,12 +5,19 @@ export interface BaselineRow {
     readonly name: string;
     readonly value: string;
 }
+/** One settings grouping for environment rows (UI / plugin metadata only). */
+export interface EnvGroup {
+    readonly id: string;
+    readonly title: string;
+}
 /** One editable environment variable row. */
 export interface EnvEntry {
     /** Stable row id; survives renames. */
     readonly id: string;
     readonly name: string;
     readonly value: string;
+    /** Group id from the groups sidecar; defaults to `default`. */
+    readonly groupId: string;
     readonly kind: EnvEntryKind;
     /** Host-start original value when `kind === 'modified'`; otherwise `null`. */
     readonly previous: string | null;
@@ -19,12 +26,27 @@ export interface EnvEntry {
 export interface EnvSnapshot {
     readonly path: string;
     readonly exists: boolean;
+    readonly groups: readonly EnvGroup[];
     readonly entries: readonly EnvEntry[];
 }
 /** One name/value pair for plugin-facing `setVar` / `setVars`. */
 export interface EnvVarWrite {
     readonly name: string;
     readonly value: string;
+    /**
+     * Target group id.
+     * When set, membership is assigned to that group.
+     * When omitted, new names use `default` and existing names keep their group.
+     */
+    readonly group?: string;
+}
+/** Options for `customEnv/deleteGroup`. */
+export interface DeleteGroupOptions {
+    /**
+     * When true, move member rows into the default group.
+     * When false, delete those variables from `.env` as well.
+     */
+    readonly moveToDefault: boolean;
 }
 /** Snapshot returned by `customEnv/cliStatus` and `cliInstall`. */
 export interface CliStatus {

package/lib/write-user-env.child.js

@@ -0,0 +1,158 @@
+// src/os-user-env/macos.ts
+import { mkdirSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+var AGENT_LABEL = "ai.dsh.custom-env";
+var AGENT_DIR = () => join(homedir(), "Library", "LaunchAgents");
+var AGENT_PATH = () => join(AGENT_DIR(), `${AGENT_LABEL}.plist`);
+var cached;
+function escapeXml(value) {
+  return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/"/gu, "&quot;");
+}
+function buildPlist(entries) {
+  const pairs = Object.entries(entries).map(([key, value]) => `    <key>${escapeXml(key)}</key>
+    <string>${escapeXml(value)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${AGENT_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/true</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+${pairs}
+  </dict>
+</dict>
+</plist>
+`;
+}
+function launchctl(args) {
+  const result = spawnSync("launchctl", args, { encoding: "utf8" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new Error(`custom-env: launchctl ${args.join(" ")} failed${detail === "" ? "" : `: ${detail}`}`);
+  }
+}
+function ensureCache() {
+  if (cached !== void 0) return cached;
+  cached = {};
+  return cached;
+}
+function writeAgent(entries) {
+  const path = AGENT_PATH();
+  if (Object.keys(entries).length === 0) {
+    if (existsSync(path)) {
+      try {
+        launchctl(["unload", path]);
+      } catch (_error) {
+      }
+      unlinkSync(path);
+    }
+    return;
+  }
+  mkdirSync(AGENT_DIR(), { recursive: true });
+  writeFileSync(path, buildPlist(entries), "utf8");
+  try {
+    launchctl(["unload", path]);
+  } catch (_error) {
+  }
+  launchctl(["load", path]);
+}
+function writeMacosUserEnv(entries, platform = process.platform) {
+  if (platform !== "darwin") return;
+  const pairs = Object.entries(entries);
+  if (pairs.length === 0) return;
+  const map = ensureCache();
+  for (const [name, value] of pairs) {
+    map[name] = value;
+    launchctl(["setenv", name, value]);
+  }
+  writeAgent(map);
+}
+
+// src/os-user-env/windows.ts
+import { createRequire } from "node:module";
+var HKEY_CURRENT_USER = 2147483649;
+var KEY_SET_VALUE = 2;
+var REG_SZ = 1;
+var ERROR_SUCCESS = 0;
+var bindings;
+function loadBindings() {
+  if (bindings !== void 0) return bindings;
+  const require2 = createRequire(import.meta.url);
+  const koffi = require2("koffi");
+  const advapi32 = koffi.load("advapi32.dll");
+  bindings = {
+    openKey: advapi32.func(
+      "long __stdcall RegOpenKeyExW(uintptr_t hKey, const char16_t *subKey, uint32_t options, uint32_t samDesired, _Out_ void **result)"
+    ),
+    queryValue: advapi32.func(
+      "long __stdcall RegQueryValueExW(void *hKey, const char16_t *valueName, void *reserved, _Inout_ uint32_t *type, uint8_t *data, _Inout_ uint32_t *cbData)"
+    ),
+    setValue: advapi32.func(
+      "long __stdcall RegSetValueExW(void *hKey, const char16_t *valueName, uint32_t reserved, uint32_t type, const uint8_t *data, uint32_t cbData)"
+    ),
+    deleteValue: advapi32.func(
+      "long __stdcall RegDeleteValueW(void *hKey, const char16_t *valueName)"
+    ),
+    closeKey: advapi32.func("long __stdcall RegCloseKey(void *hKey)")
+  };
+  return bindings;
+}
+function encodeRegSz(value) {
+  return Buffer.from(`${value}\0`, "utf16le");
+}
+function writeWindowsUserEnv(entries, platform = process.platform) {
+  if (platform !== "win32") return;
+  const pairs = Object.entries(entries);
+  if (pairs.length === 0) return;
+  const api = loadBindings();
+  const keySlot = [null];
+  const openStatus = api.openKey(HKEY_CURRENT_USER, "Environment", 0, KEY_SET_VALUE, keySlot);
+  if (openStatus !== ERROR_SUCCESS) {
+    throw new Error(`custom-env: RegOpenKeyExW failed (Win32 ${openStatus})`);
+  }
+  const hKey = keySlot[0];
+  try {
+    for (const [name, value] of pairs) {
+      const data = encodeRegSz(value);
+      const status = api.setValue(hKey, name, 0, REG_SZ, data, data.length);
+      if (status !== ERROR_SUCCESS) {
+        throw new Error(`custom-env: RegSetValueExW(${name}) failed (Win32 ${status})`);
+      }
+    }
+  } finally {
+    api.closeKey(hKey);
+  }
+}
+
+// src/os-user-env/index.ts
+function writeUserEnv(entries) {
+  writeWindowsUserEnv(entries);
+  writeMacosUserEnv(entries);
+}
+
+// src/os-user-env/write-user-env.child.ts
+var chunks = [];
+for await (const chunk of process.stdin) {
+  chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+}
+var raw = Buffer.concat(chunks).toString("utf8").trim();
+if (raw === "") process.exit(0);
+try {
+  const entries = JSON.parse(raw);
+  writeUserEnv(entries);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`custom-env child: ${message}
+`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@woosau/dsh-custom-env",
   "description": "DSH plugin: manage $DSH_HOME/.env from Settings",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -72,6 +72,7 @@
     "cordis.patch.yml",
     "scripts/command-path.ps1",
     "lib/index.js",
+    "lib/write-user-env.child.js",
     "lib/client.js",
     "lib/types/**/*.d.ts",
     "lib/typert.host.js",