@woosau/dsh-custom-env 0.1.0 → 0.1.4

package/lib/typert.host.js

@@ -37,6 +37,33 @@ const upsert$parameter$2$schema = () => (upsert$parameter$2$schema$value ??= z.s
 let remove$parameter$0$schema$value
 const remove$parameter$0$schema = () => (remove$parameter$0$schema$value ??= z.string())
 
+let setVar$parameter$0$schema$value
+const setVar$parameter$0$schema = () => (setVar$parameter$0$schema$value ??= z.string())
+let setVar$parameter$1$schema$value
+const setVar$parameter$1$schema = () => (setVar$parameter$1$schema$value ??= z.string())
+
+let setVars$parameter$0$schema$value
+const setVars$parameter$0$schema = () => (setVars$parameter$0$schema$value ??= z.array(z.object({
+  name: z.string().readonly(),
+  value: z.string().readonly(),
+}).readonly()).readonly())
+
+let removeVar$parameter$0$schema$value
+const removeVar$parameter$0$schema = () => (removeVar$parameter$0$schema$value ??= z.string())
+
+let removeVars$parameter$0$schema$value
+const removeVars$parameter$0$schema = () => (removeVars$parameter$0$schema$value ??= z.array(z.string()).readonly())
+
+const envVarWriteJsonSchema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    value: { type: 'string' },
+  },
+  required: ['name', 'value'],
+  additionalProperties: false,
+}
+
 let restore$parameter$0$schema$value
 const restore$parameter$0$schema = () => (restore$parameter$0$schema$value ??= z.string())
 
@@ -126,7 +153,7 @@ const $remote = createTypertRemoteInfo({
         },
         {
           name: 'value',
-          description: 'non-empty value.',
+          description: 'value (empty string allowed).',
           source: 'json',
           codec: {
             mode: 'strict',
@@ -145,6 +172,121 @@ const $remote = createTypertRemoteInfo({
       },
       sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
     },
+    'customEnv/setVars': {
+      service: 'customEnv',
+      description: 'Create or replace many variables by name in one rewrite. Empty values write NAME=.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'entries',
+          description: 'name/value pairs (last duplicate name wins).',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'readonly EnvVarWrite[]',
+            create: setVars$parameter$0$schema,
+            jsonSchema: { type: 'array', items: envVarWriteJsonSchema },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'void',
+        create: () => z.undefined(),
+        description: 'no return value.',
+        jsonSchema: { type: 'null' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
+    'customEnv/setVar': {
+      service: 'customEnv',
+      description: 'Create or replace one variable by name. Empty value writes NAME=.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'name',
+          description: 'writable variable name.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'string',
+            create: setVar$parameter$0$schema,
+            jsonSchema: { type: 'string' },
+          },
+        },
+        {
+          name: 'value',
+          description: 'value to store (empty string allowed).',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'string',
+            create: setVar$parameter$1$schema,
+            jsonSchema: { type: 'string' },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'void',
+        create: () => z.undefined(),
+        description: 'no return value.',
+        jsonSchema: { type: 'null' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
+    'customEnv/removeVars': {
+      service: 'customEnv',
+      description: 'Remove many variables by name from the file, Host, and OS user environment.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'names',
+          description: 'writable variable names.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'readonly string[]',
+            create: removeVars$parameter$0$schema,
+            jsonSchema: { type: 'array', items: { type: 'string' } },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'number',
+        create: () => z.number(),
+        description: 'number of .env lines removed.',
+        jsonSchema: { type: 'number' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
+    'customEnv/removeVar': {
+      service: 'customEnv',
+      description: 'Remove one variable by name from the file, Host, and OS user environment.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'name',
+          description: 'writable variable name.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'string',
+            create: removeVar$parameter$0$schema,
+            jsonSchema: { type: 'string' },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'boolean',
+        create: () => z.boolean(),
+        description: 'true when a .env line was removed.',
+        jsonSchema: { type: 'boolean' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
     'customEnv/deleteEntry': {
       service: 'customEnv',
       description: 'Delete one entry from the file, Host, and OS user environment.',
@@ -257,6 +399,34 @@ export const TYPERT = {
             summary: 'Create or update one row by id.',
             jsDoc: '/** Create (`id === ""`) or update/rename one row. */',
           },
+          {
+            kind: 'method',
+            name: 'setVars',
+            signature: "@Remote('setVars') async setVars(entries: readonly EnvVarWrite[]): Promise<void>",
+            summary: 'Create or replace many variables by name (empty values allowed).',
+            jsDoc: '/** Create or replace many variables by name. Empty values allowed. */',
+          },
+          {
+            kind: 'method',
+            name: 'setVar',
+            signature: "@Remote('setVar') async setVar(name: string, value: string): Promise<void>",
+            summary: 'Create or replace one variable by name (empty value allowed).',
+            jsDoc: '/** Create or replace one variable by name. Empty value allowed. */',
+          },
+          {
+            kind: 'method',
+            name: 'removeVars',
+            signature: "@Remote('removeVars') async removeVars(names: readonly string[]): Promise<number>",
+            summary: 'Remove many variables by name.',
+            jsDoc: '/** Remove many variables by name. Returns how many lines were removed. */',
+          },
+          {
+            kind: 'method',
+            name: 'removeVar',
+            signature: "@Remote('removeVar') async removeVar(name: string): Promise<boolean>",
+            summary: 'Remove one variable by name.',
+            jsDoc: '/** Remove one variable by name. Returns whether a line was removed. */',
+          },
           {
             kind: 'method',
             name: 'deleteEntry',

package/lib/typert.remote-client.js

@@ -37,6 +37,33 @@ const upsert$parameter$2$schema = () => (upsert$parameter$2$schema$value ??= z.s
 let remove$parameter$0$schema$value
 const remove$parameter$0$schema = () => (remove$parameter$0$schema$value ??= z.string())
 
+let setVar$parameter$0$schema$value
+const setVar$parameter$0$schema = () => (setVar$parameter$0$schema$value ??= z.string())
+let setVar$parameter$1$schema$value
+const setVar$parameter$1$schema = () => (setVar$parameter$1$schema$value ??= z.string())
+
+let setVars$parameter$0$schema$value
+const setVars$parameter$0$schema = () => (setVars$parameter$0$schema$value ??= z.array(z.object({
+  name: z.string().readonly(),
+  value: z.string().readonly(),
+}).readonly()).readonly())
+
+let removeVar$parameter$0$schema$value
+const removeVar$parameter$0$schema = () => (removeVar$parameter$0$schema$value ??= z.string())
+
+let removeVars$parameter$0$schema$value
+const removeVars$parameter$0$schema = () => (removeVars$parameter$0$schema$value ??= z.array(z.string()).readonly())
+
+const envVarWriteJsonSchema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    value: { type: 'string' },
+  },
+  required: ['name', 'value'],
+  additionalProperties: false,
+}
+
 let restore$parameter$0$schema$value
 const restore$parameter$0$schema = () => (restore$parameter$0$schema$value ??= z.string())
 
@@ -126,7 +153,7 @@ export const TYPERT_REMOTE = createTypertRemoteInfo({
         },
         {
           name: 'value',
-          description: 'non-empty value.',
+          description: 'value (empty string allowed).',
           source: 'json',
           codec: {
             mode: 'strict',
@@ -145,6 +172,121 @@ export const TYPERT_REMOTE = createTypertRemoteInfo({
       },
       sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
     },
+    'customEnv/setVars': {
+      service: 'customEnv',
+      description: 'Create or replace many variables by name in one rewrite. Empty values write NAME=.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'entries',
+          description: 'name/value pairs (last duplicate name wins).',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'readonly EnvVarWrite[]',
+            create: setVars$parameter$0$schema,
+            jsonSchema: { type: 'array', items: envVarWriteJsonSchema },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'void',
+        create: () => z.undefined(),
+        description: 'no return value.',
+        jsonSchema: { type: 'null' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
+    'customEnv/setVar': {
+      service: 'customEnv',
+      description: 'Create or replace one variable by name. Empty value writes NAME=.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'name',
+          description: 'writable variable name.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'string',
+            create: setVar$parameter$0$schema,
+            jsonSchema: { type: 'string' },
+          },
+        },
+        {
+          name: 'value',
+          description: 'value to store (empty string allowed).',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'string',
+            create: setVar$parameter$1$schema,
+            jsonSchema: { type: 'string' },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'void',
+        create: () => z.undefined(),
+        description: 'no return value.',
+        jsonSchema: { type: 'null' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
+    'customEnv/removeVars': {
+      service: 'customEnv',
+      description: 'Remove many variables by name from the file, Host, and OS user environment.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'names',
+          description: 'writable variable names.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'readonly string[]',
+            create: removeVars$parameter$0$schema,
+            jsonSchema: { type: 'array', items: { type: 'string' } },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'number',
+        create: () => z.number(),
+        description: 'number of .env lines removed.',
+        jsonSchema: { type: 'number' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
+    'customEnv/removeVar': {
+      service: 'customEnv',
+      description: 'Remove one variable by name from the file, Host, and OS user environment.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'name',
+          description: 'writable variable name.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: 'string',
+            create: removeVar$parameter$0$schema,
+            jsonSchema: { type: 'string' },
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: 'boolean',
+        create: () => z.boolean(),
+        description: 'true when a .env line was removed.',
+        jsonSchema: { type: 'boolean' },
+      },
+      sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+    },
     'customEnv/deleteEntry': {
       service: 'customEnv',
       description: 'Delete one entry from the file, Host, and OS user environment.',

package/lib/types/client/format-remote-error.d.ts

@@ -0,0 +1,10 @@
+/** Map Host Remote failures to settings.env locale strings. */
+import type { EnvSettingsKey } from './locales.ts';
+type Translate = (key: EnvSettingsKey) => string;
+/**
+ * Localize a caught Remote failure for the settings section.
+ * @param error - thrown value from inject call helpers.
+ * @param t - bound settings.env translator.
+ */
+export declare function formatRemoteError(error: unknown, t: Translate): string;
+export {};

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

@@ -1,9 +1,67 @@
-/** Locale dictionaries for the environment-variables settings section. */
+/** `settings.env` namespace dictionaries for the environment 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>;
+export declare const NS: "settings.env";
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'panel.nav': string;
+    'panel.title': string;
+    'panel.empty': string;
+    'panel.loading': string;
+    'field.name': string;
+    'field.value': string;
+    'field.actions': string;
+    'field.namePlaceholder': string;
+    'field.valuePlaceholder': string;
+    'action.confirm': string;
+    'action.cancel': string;
+    'action.remove': string;
+    'action.removeConfirmTitle': string;
+    'action.removeConfirm': string;
+    'action.restore': string;
+    'action.close': string;
+    'status.restartRequired': string;
+    'cli.title': string;
+    'cli.activeMissing': string;
+    'cli.install': string;
+    'cli.macConflict': string;
+    'error.generic': string;
+    'error.invalidName': string;
+    'error.invalidValue': string;
+    'error.restoreFailed': string;
+    'error.cliInstall': string;
+    'error.cliUnresolved': string;
+    'error.cliUnsupported': string;
+};
+/** The settings.env namespace key union. */
+export type EnvSettingsKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'panel.nav': string;
+    'panel.title': string;
+    'panel.empty': string;
+    'panel.loading': string;
+    'field.name': string;
+    'field.value': string;
+    'field.actions': string;
+    'field.namePlaceholder': string;
+    'field.valuePlaceholder': string;
+    'action.confirm': string;
+    'action.cancel': string;
+    'action.remove': string;
+    'action.removeConfirmTitle': string;
+    'action.removeConfirm': string;
+    'action.restore': string;
+    'action.close': string;
+    'status.restartRequired': string;
+    'cli.title': string;
+    'cli.activeMissing': string;
+    'cli.install': string;
+    'cli.macConflict': string;
+    'error.generic': string;
+    'error.invalidName': string;
+    'error.invalidValue': string;
+    'error.restoreFailed': string;
+    'error.cliInstall': string;
+    'error.cliUnresolved': string;
+    'error.cliUnsupported': string;
+};

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

@@ -7,10 +7,10 @@ export interface RawEnvEntry {
 /** Absolute path of `$DSH_HOME/.env`. */
 export declare function envFilePath(): string;
 /**
- * Read non-empty writable entries from `$DSH_HOME/.env`.
+ * Read writable entries from `$DSH_HOME/.env` (empty values included).
  * @returns Variable map, or `{}` when absent / empty.
  */
-export declare function loadEnvMap(): Readonly<Record<string, string>>;
+export declare function readEnvMap(): Readonly<Record<string, string>>;
 /**
  * List writable entries in `.env` file order (new keys stay at the end).
  * @returns Path, existence, and ordered entries.
@@ -20,18 +20,66 @@ export declare function listEnvEntries(): {
     exists: boolean;
     entries: RawEnvEntry[];
 };
+/** Options for empty-value write policy. */
+export interface WriteEnvOptions {
+    /**
+     * When true, empty values always create/replace.
+     * When false (default), empty values only create a missing key; existing keys
+     * in `$DSH_HOME/.env` or the OS user environment are left unchanged.
+     */
+    readonly forceEmpty?: boolean;
+}
+/**
+ * Whether `name` already exists in `$DSH_HOME/.env` or the OS user environment.
+ * Presence counts even when the current value is empty.
+ * @param name - Variable name.
+ * @returns true when a same-named entry is already present.
+ */
+export declare function hasEnvKey(name: string): boolean;
+/**
+ * Drop empty writes that would clobber an existing key (unless `forceEmpty`).
+ * Non-empty values always pass; last duplicate name wins.
+ * @param entries - Candidate writes.
+ * @param options - Empty-value policy.
+ * @returns Entries that should be applied.
+ */
+export declare function selectEnvWrites(entries: readonly {
+    readonly name: string;
+    readonly value: string;
+}[], options?: WriteEnvOptions): 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.
+ * Create or replace many keys in one file rewrite (last duplicate name wins).
+ * Existing keys keep file order; new keys append in input order.
+ * Empty values write `NAME=` only when the key is absent (unless `forceEmpty`).
+ * @param entries - name/value pairs.
+ * @param options - Empty-value policy.
+ * @returns Entries actually written (may be empty when all empty writes were skipped).
+ */
+export declare function writeEnvEntries(entries: readonly {
+    readonly name: string;
+    readonly value: string;
+}[], options?: WriteEnvOptions): RawEnvEntry[];
+/**
+ * Create or replace one key (append when new). Honors empty-skip unless `forceEmpty`.
+ * @param name - Variable name.
+ * @param value - Value to store.
+ * @param options - Empty-value policy.
+ * @returns true when the file was rewritten.
+ */
+export declare function writeEnvEntry(name: string, value: string, options?: WriteEnvOptions): boolean;
+/**
+ * Rename one key in place (keeps file order) and always write `value`.
+ * @param from - Existing name.
+ * @param to - New name.
+ * @param value - Value to store.
  */
-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 many keys from `$DSH_HOME/.env` in one rewrite.
+ * @param names - variable names (all must be writable).
+ * @returns number of assignment lines removed.
+ */
+export declare function removeEnvEntries(names: readonly string[]): number;
 /**
  * Remove one key from `$DSH_HOME/.env` when present.
  * @param name - variable name.

package/lib/types/index.d.ts

@@ -4,8 +4,8 @@
 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';
+import { type CliStatus, type EnvSnapshot, type EnvVarWrite } from './types.ts';
+export type { BaselineRow, CliStatus, EnvEntry, EnvSnapshot, EnvVarWrite } from './types.ts';
 export { classifyEntry } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -39,7 +39,10 @@ export default class CustomEnvController extends TypertRemoteService {
     private bind;
     private unbind;
     private requireName;
-    /** Persist `name=value` replacing `from` in place; sync process.env / OS. */
+    /**
+     * 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. */
     list(): Promise<EnvSnapshot>;
@@ -47,9 +50,35 @@ export default class CustomEnvController extends TypertRemoteService {
      * 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.
+     * @param value - value (empty creates only when missing; Settings UI may still reject empty drafts).
      */
     upsert(id: string, name: string, value: 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.
+     */
+    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.
+     */
+    setVar(name: string, value: string): Promise<void>;
+    /**
+     * Remove many variables by name (plugin-facing).
+     * @param names - writable variable names.
+     * @returns number of `.env` lines removed.
+     */
+    removeVars(names: readonly string[]): Promise<number>;
+    /**
+     * Remove one variable by name (plugin-facing).
+     * @param name - writable variable name.
+     * @returns true when a `.env` line was removed.
+     */
+    removeVar(name: string): Promise<boolean>;
     /** @param id - row id from list(). */
     deleteEntry(id: string): Promise<EnvSnapshot>;
     /** Restore Host-start original name+value, or delete if added after start. */

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

@@ -1,13 +1,24 @@
 /** OS user-environment sync for Windows and macOS (no-op elsewhere). */
 /**
- * Persist entries into the current user's OS environment when supported.
+ * Whether `name` already exists in the OS user environment (Windows HKCU or macOS user domain).
+ * @param name - Variable name.
+ * @returns true when present (value may be empty); false on unsupported platforms.
+ */
+export declare function hasUserEnv(name: string): boolean;
+/**
+ * Write 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;
+export declare function writeUserEnv(entries: Readonly<Record<string, string>>): void;
+/**
+ * Remove many keys from the current user's OS environment when supported.
+ * @param names - Variable names to delete.
+ */
+export declare function removeUserEnvs(names: readonly 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';
+export { hasWindowsUserEnv, removeWindowsUserEnv, removeWindowsUserEnvs, writeWindowsUserEnv, } from './windows.ts';
+export { hasMacosUserEnv, removeMacosUserEnv, removeMacosUserEnvs, writeMacosUserEnv, } from './macos.ts';

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

@@ -1,12 +1,26 @@
 /**
  * Persist user environment variables on macOS via launchctl and a Login LaunchAgent.
  */
+/**
+ * Whether `name` is present in this process's macOS user-env tracking
+ * (`process.env` or the in-memory LaunchAgent cache).
+ * @param name - Variable name.
+ * @param platform - Override for tests; defaults to `process.platform`.
+ * @returns true when the name is already managed/visible.
+ */
+export declare function hasMacosUserEnv(name: string, platform?: NodeJS.Platform): boolean;
 /**
  * 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;
+export declare function writeMacosUserEnv(entries: Readonly<Record<string, string>>, platform?: NodeJS.Platform): void;
+/**
+ * Unset many user-domain environment variables and refresh the Login Agent once.
+ * @param names - Variable names to remove.
+ * @param platform - Override for tests; defaults to `process.platform`.
+ */
+export declare function removeMacosUserEnvs(names: readonly string[], platform?: NodeJS.Platform): void;
 /**
  * Unset one user-domain environment variable and refresh the Login Agent.
  * @param name - Variable name to remove.