@woosau/dsh-custom-env 0.1.6 → 0.1.9

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/env-row-select.d.ts

@@ -0,0 +1,36 @@
+/** Pure helpers for Environment row multi-select and KEY=VALUE copy. */
+/** Ctrl (Windows/Linux) or Meta (macOS) — required for click-to-toggle selection. */
+export declare function isSelectionEditKey(event: {
+    ctrlKey: boolean;
+    metaKey: boolean;
+}): boolean;
+/**
+ * Inclusive id span between two anchors in list order.
+ * @param ordered - Selectable row ids in display order.
+ * @param from - Range start id.
+ * @param to - Range end id.
+ * @returns Ordered ids from the earlier index through the later; empty if either id is missing.
+ */
+export declare function rangeIds(ordered: readonly string[], from: string, to: string): string[];
+/** Drop the browser text selection (not row selection). */
+export declare function clearDomTextSelection(): void;
+/** True when the focused input/textarea has a non-empty character range. */
+export declare function hasFocusedInputTextSelection(): boolean;
+/**
+ * Build clipboard text for selected rows in list order.
+ * @param selectedIds - Selected row ids.
+ * @param orderedIds - Display order (saved then pending).
+ * @param drafts - Current name/value drafts by id.
+ * @returns `NAME=VALUE` lines, or empty when nothing usable.
+ */
+export declare function selectedEnvCopyText(selectedIds: ReadonlySet<string>, orderedIds: readonly string[], drafts: Readonly<Record<string, {
+    name: string;
+    value: string;
+}>>): string;
+/**
+ * Resolve the env row under a client point, if any.
+ * @param clientX - Viewport X.
+ * @param clientY - Viewport Y.
+ * @returns `data-env-row` id, or undefined.
+ */
+export declare function rowIdFromPoint(clientX: number, clientY: number): string | undefined;

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/client/parse-env-paste.d.ts

@@ -0,0 +1,21 @@
+/** Parse clipboard text into environment name/value pairs for Settings paste. */
+/** One parsed assignment from a paste. */
+export interface ParsedEnvPair {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * Parse multiline `NAME=VALUE` paste text into pairs.
+ * Trims lines and spaces around `=`; splits on the first `=`; skips blanks and invalid names.
+ * Duplicate names in one paste keep the last value.
+ * @param text - Clipboard text.
+ * @returns Ordered unique pairs (last duplicate wins).
+ */
+export declare function parseEnvPaste(text: string): ParsedEnvPair[];
+/**
+ * Format pairs for clipboard copy (one `NAME=VALUE` per line).
+ * Skips empty names. Does not trim values beyond what the caller provides.
+ * @param pairs - Ordered name/value pairs.
+ * @returns Clipboard text; empty string when no usable pairs.
+ */
+export declare function formatEnvCopy(pairs: readonly ParsedEnvPair[]): 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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@woosau/dsh-custom-env",
   "description": "DSH plugin: manage $DSH_HOME/.env from Settings",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",