@alfe.ai/integrations 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -913,9 +913,11 @@ declare class HermesApplier implements RuntimeApplier {
   readonly runtime = "hermes";
   private home;
   private trackingPath;
+  /** `~/.hermes/config.yaml` — read-merge-written on removal (no `config unset`). */
+  private configYamlPath;
   private configSetRetries;
   private configSetRetryDelayMs;
-  /** Serializes all `hermes config` writes so they never interleave. */
+  /** Serializes all config mutations (CLI `set` + config.yaml delete) so they never interleave. */
   private configSetQueue;
   constructor(options?: HermesApplierOptions);
   /**
@@ -929,8 +931,9 @@ declare class HermesApplier implements RuntimeApplier {
   /**
    * Remove config previously applied by an integration.
    *
-   * Reads the tracking file to find which keys this integration set, then
-   * removes each via `hermes config unset`. Clears the tracking entry.
+   * Reads the tracking file to find which dotted keys this integration set, then
+   * DELETES each from `~/.hermes/config.yaml` via a read-merge-write (there is no
+   * `hermes config unset` verb — see the file header). Clears the tracking entry.
    */
   removeConfig(integrationId: string): Promise<void>;
   /**
@@ -967,21 +970,25 @@ declare class HermesApplier implements RuntimeApplier {
   /** Convenience: `hermes config set <args>`, serialized + retried. */
   private runConfigSet;
   /**
-   * Unset a single config key. The unset verb is isolated HERE so there is one
-   * place to change if the spike proves `hermes config unset` is unavailable.
-   *
-   * FALLBACK (do NOT pre-build): if `hermes config unset` does not exist, the
-   * substitute is `hermes config set <key> ""` (clear the value) or a
-   * read-merge-write of config.yaml. Not implemented now — `unset` is the
-   * documented verb; confirm in the Phase-0 spike before adding a fallback.
-   * TODO(phase-0 spike): confirm `hermes config unset <key>` exists.
-   */
-  private unsetConfigKey;
-  /**
-   * Run `hermes config <args>` (set/unset), serialized against every other
-   * config write and retried with backoff. Throws an Error whose (scrubbed)
-   * message includes stderr after retries are exhausted, so the real cause
-   * propagates to the integration errorMessage without leaking the value.
+   * Delete a set of dotted config keys from `~/.hermes/config.yaml`. There is no
+   * `hermes config unset` verb (see file header), so removal is a read-merge-write
+   * of the YAML via the Document API — preserving user-authored keys, comments,
+   * and formatting. Serialized against every other config mutation on the same
+   * queue so a delete can't interleave with an in-flight `hermes config set`.
+   */
+  private deleteConfigKeys;
+  /**
+   * Synchronous config.yaml read-merge-write: parse the doc, delete each dotted
+   * key (`model.base_url` → `deleteIn(['model','base_url'])`), and write back only
+   * if the text actually changed. No-op if config.yaml doesn't exist yet.
+   */
+  private deleteConfigKeysSync;
+  /**
+   * Run `hermes config <args>` (only `set` is used — removal goes via
+   * {@link deleteConfigKeys}), serialized against every other config mutation and
+   * retried with backoff. Throws an Error whose (scrubbed) message includes stderr
+   * after retries are exhausted, so the real cause propagates to the integration
+   * errorMessage without leaking the value.
    */
   private runConfigCommand;
   private readTracking;

package/dist/index.js

@@ -2193,11 +2193,17 @@ var OpenClawApplier = class {
 * HermesApplier — applies integration config (and, later, native plugins) to
 * the Hermes runtime (Nous Research's Python agent).
 *
-* Hermes config lives in `~/.hermes/config.yaml` (YAML) and is mutated via the
-* `hermes config set/unset <dotted.key> <value>` CLI — we never write the YAML
-* file directly (mirrors the OpenClaw rule of letting the runtime own its own
-* config format). Per-integration contributions are tracked in a separate file
-* (`~/.hermes/.alfe-integrations.json`) so removal is precise.
+* Hermes config lives in `~/.hermes/config.yaml` (YAML). We APPLY config via the
+* `hermes config set <dotted.key> <value>` CLI (letting the runtime own its
+* write path, mirroring the OpenClaw rule). REMOVAL is different: `hermes config
+* unset` does NOT exist — CONFIRMED against Hermes source, whose `config`
+* subcommands are only show/set/edit/path/env-path/check/migrate. So teardown is
+* a config.yaml read-merge-write that deletes the Alfe-applied dotted keys via
+* the `yaml` Document API (`parseDocument` + `deleteIn`), preserving
+* user-authored keys, comments, and formatting (the same approach
+* `hermes-mcp-sync.ts` uses for `mcp_servers`). Per-integration contributions are
+* tracked in a separate file (`~/.hermes/.alfe-integrations.json`) so we know
+* exactly which keys to delete.
 *
 * Scope (Phase 1, MCP-first hybrid):
 *  - config: SUPPORTED — consumes `installs.runtimes.hermes.config` (the AI-proxy
@@ -2243,9 +2249,9 @@ function stringifyConfigValue(value) {
 	return typeof value === "string" ? value : JSON.stringify(value);
 }
 /**
-* Describe a `config set/unset` target WITHOUT leaking values. The value
-* argument can be a secret (`model.api_key`), so it must never reach the
-* integration's user-facing `errorMessage`. Keep only the program + verb + key.
+* Describe a `config set` target WITHOUT leaking values. The value argument can
+* be a secret (`model.api_key`), so it must never reach the integration's
+* user-facing `errorMessage`. Keep only the program + verb + key.
 */
 function redactConfigTarget(args) {
 	return `hermes config ${args.slice(0, 2).join(" ")}`.trim();
@@ -2270,13 +2276,16 @@ var HermesApplier = class {
 	runtime = "hermes";
 	home;
 	trackingPath;
+	/** `~/.hermes/config.yaml` — read-merge-written on removal (no `config unset`). */
+	configYamlPath;
 	configSetRetries;
 	configSetRetryDelayMs;
-	/** Serializes all `hermes config` writes so they never interleave. */
+	/** Serializes all config mutations (CLI `set` + config.yaml delete) so they never interleave. */
 	configSetQueue = Promise.resolve();
 	constructor(options = {}) {
 		this.home = options.home ?? options.workspace ?? DEFAULT_HERMES_HOME$1;
 		this.trackingPath = options.configPath ?? join(this.home, ".alfe-integrations.json");
+		this.configYamlPath = join(this.home, "config.yaml");
 		this.configSetRetries = options.configSetRetries ?? CONFIG_SET_RETRIES;
 		this.configSetRetryDelayMs = options.configSetRetryDelayMs ?? CONFIG_SET_RETRY_DELAY_MS;
 	}
@@ -2311,8 +2320,9 @@ var HermesApplier = class {
 	/**
 	* Remove config previously applied by an integration.
 	*
-	* Reads the tracking file to find which keys this integration set, then
-	* removes each via `hermes config unset`. Clears the tracking entry.
+	* Reads the tracking file to find which dotted keys this integration set, then
+	* DELETES each from `~/.hermes/config.yaml` via a read-merge-write (there is no
+	* `hermes config unset` verb — see the file header). Clears the tracking entry.
 	*/
 	async removeConfig(integrationId) {
 		const tracking = this.readTracking();
@@ -2320,13 +2330,13 @@ var HermesApplier = class {
 		if (!(integrationId in integrations)) return;
 		const integrationConfig = integrations[integrationId];
 		const { leaves } = partitionEntries(flattenConfig(integrationConfig));
-		for (const { path } of leaves) try {
-			await this.unsetConfigKey(path);
+		try {
+			await this.deleteConfigKeys(leaves.map(({ path }) => path));
 		} catch (err) {
 			log$2.warn({
 				err: err instanceof Error ? err.message : String(err),
-				key: path
-			}, "Failed to unset config via hermes config unset");
+				integrationId
+			}, "Failed to delete Alfe config keys from ~/.hermes/config.yaml");
 		}
 		tracking._integrations = Object.fromEntries(Object.entries(integrations).filter(([key]) => key !== integrationId));
 		this.writeTracking(tracking);
@@ -2410,23 +2420,40 @@ var HermesApplier = class {
 		return this.runConfigCommand(["set", ...setArgs]);
 	}
 	/**
-	* Unset a single config key. The unset verb is isolated HERE so there is one
-	* place to change if the spike proves `hermes config unset` is unavailable.
-	*
-	* FALLBACK (do NOT pre-build): if `hermes config unset` does not exist, the
-	* substitute is `hermes config set <key> ""` (clear the value) or a
-	* read-merge-write of config.yaml. Not implemented now — `unset` is the
-	* documented verb; confirm in the Phase-0 spike before adding a fallback.
-	* TODO(phase-0 spike): confirm `hermes config unset <key>` exists.
+	* Delete a set of dotted config keys from `~/.hermes/config.yaml`. There is no
+	* `hermes config unset` verb (see file header), so removal is a read-merge-write
+	* of the YAML via the Document API — preserving user-authored keys, comments,
+	* and formatting. Serialized against every other config mutation on the same
+	* queue so a delete can't interleave with an in-flight `hermes config set`.
+	*/
+	deleteConfigKeys(paths) {
+		const run = () => {
+			this.deleteConfigKeysSync(paths);
+			return Promise.resolve();
+		};
+		const result = this.configSetQueue.then(run, run);
+		this.configSetQueue = result.catch(() => void 0);
+		return result;
+	}
+	/**
+	* Synchronous config.yaml read-merge-write: parse the doc, delete each dotted
+	* key (`model.base_url` → `deleteIn(['model','base_url'])`), and write back only
+	* if the text actually changed. No-op if config.yaml doesn't exist yet.
 	*/
-	unsetConfigKey(key) {
-		return this.runConfigCommand(["unset", key]);
+	deleteConfigKeysSync(paths) {
+		if (paths.length === 0 || !existsSync(this.configYamlPath)) return;
+		const doc = parseDocument(readFileSync(this.configYamlPath, "utf-8"));
+		const before = doc.toString();
+		for (const path of paths) doc.deleteIn(path.split("."));
+		const after = doc.toString();
+		if (before !== after) writeFileSync(this.configYamlPath, after, "utf-8");
 	}
 	/**
-	* Run `hermes config <args>` (set/unset), serialized against every other
-	* config write and retried with backoff. Throws an Error whose (scrubbed)
-	* message includes stderr after retries are exhausted, so the real cause
-	* propagates to the integration errorMessage without leaking the value.
+	* Run `hermes config <args>` (only `set` is used — removal goes via
+	* {@link deleteConfigKeys}), serialized against every other config mutation and
+	* retried with backoff. Throws an Error whose (scrubbed) message includes stderr
+	* after retries are exhausted, so the real cause propagates to the integration
+	* errorMessage without leaking the value.
 	*/
 	runConfigCommand(args) {
 		const run = async () => {
@@ -2502,15 +2529,13 @@ var HermesApplier = class {
 const log$1 = createLogger("HermesMcpSync");
 const DEFAULT_HERMES_HOME = join(homedir(), ".hermes");
 /**
-* SPIKE-PENDING SEAM #1 — `${VAR}` interpolation from `~/.hermes/.env`.
-*
-* We inject `ALFE_API_KEY=${ALFE_API_KEY}` into every Alfe-owned stdio server's
-* env and put the real value in `~/.hermes/.env`. This assumes Hermes
-* interpolates `${VAR}` references in `mcp_servers.<id>.env` from `.env` at spawn
-* time. TODO(phase-0 spike): confirm. If Hermes does NOT interpolate, the
-* fallback (NOT built here) is to write the literal `ALFE_API_KEY` VALUE inline
-* into each `mcp_servers.<id>.env` and skip the `.env` file entirely — change
-* `withAlfeApiKey()` + `ensureEnvApiKey()` together in that one case.
+* SEAM #1 — `${VAR}` interpolation from `~/.hermes/.env`. CONFIRMED (Hermes
+* source `config.py:5790` `_expand_env_vars`): Hermes loads `~/.hermes/.env` via
+* dotenv into `os.environ`, then recursively expands `${VAR}` refs across the
+* ENTIRE merged config — including `mcp_servers.<id>.env.*` (and `model.api_key`
+* / `model.base_url`). So injecting `ALFE_API_KEY=${ALFE_API_KEY}` into every
+* Alfe-owned stdio server's env and writing the real value to `~/.hermes/.env`
+* resolves at spawn time. The inline-literal fallback is therefore not needed.
 */
 const ALFE_API_KEY_ENV_REF = "${ALFE_API_KEY}";
 const DEFAULT_DEBOUNCE_MS = 250;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",