@mrclrchtr/supi-antigravity 6.4.0

package/CLAUDE.md

@@ -0,0 +1,21 @@
+# CLAUDE.md
+
+## Scope
+
+`@mrclrchtr/supi-antigravity` owns the `antigravity_run` PI tool, Antigravity CLI availability, the Isolated Antigravity Home, Consultation Workspace, evidence classification, and Conversation Handle state.
+
+## Design rules
+
+- Keep the Model Catalogue immutable until the next session start or reload.
+- Register `antigravity_run` only after `agy` version and curated-model discovery succeeds.
+- Use the Isolated Antigravity Home for every Antigravity process. On macOS, create and unlock its private keychain, exposed as the login keychain, before starting `agy`. Do not copy the normal Antigravity profile, credentials, or PI provider environment.
+- Spawn `agy` directly with an argument array. Keep stdout, stderr, tool parameters, tool output, and transcript data bounded and out of PI state.
+- Treat the Inspection Permission Set as an Antigravity policy, not an operating-system sandbox. Project hooks and accepted `read_url(*)` targets remain explicit limitations.
+- Keep new and follow-up inputs exact-one. Follow-ups inherit model and workspace from their Conversation Handle.
+- Reject same-handle overlap before process startup. Retire a handle only after a follow-up has acquired it and started process work.
+- Build model-visible result content in `tool/antigravity_run/result.ts`; renderers use structured details and never parse result content for chrome.
+- Keep sources and workspace paths bounded. Distinguish observed references from claimed references.
+
+## Verification
+
+Use focused tests and typechecking while changing this package. Then run `pnpm verify:ai` and package staging checks before completion. The live probe requires an explicit `SUPI_ANTIGRAVITY_LIVE=1` variable and must not run in normal tests or CI.

package/CONTEXT.md

@@ -0,0 +1,53 @@
+# supi-antigravity
+
+Runs bounded Antigravity tasks from PI while keeping workspace exposure and observed evidence explicit.
+
+## Language
+
+**Antigravity Run**:
+One bounded request to Antigravity that returns one answer and execution evidence. It is external to PI and is not a PI Agent Run.
+_Avoid_: Agent Run, child session, Antigravity session
+
+**Workspace Access**:
+The caller's decision to expose the current PI workspace to an Antigravity Run. A run without Workspace Access uses the Consultation Workspace.
+_Avoid_: consult mode, explore mode, repository mode
+
+**Consultation Workspace**:
+A package-managed empty project that lets an Antigravity Run operate without access to the current PI workspace. Its stable project identity supports user-owned Antigravity permissions without a global permission change.
+_Avoid_: temporary workspace, sandbox, current workspace
+
+**Web Capability**:
+Antigravity's permission-controlled ability to retrieve external sources during an Antigravity Run. SuPi exposes and observes this capability but does not grant it.
+_Avoid_: SuPi web search, automatic web access, web mode
+
+**Isolated Antigravity Home**:
+The package-owned Antigravity profile that keeps configuration, authentication, customizations, and conversation state separate from the user's normal Antigravity profile. On macOS, it also owns a private keychain exposed as the login keychain for Antigravity credentials. It is stable across Antigravity Runs so Conversation Handles can continue.
+_Avoid_: user home, temporary home, sandbox
+
+**Inspection Permission Set**:
+The rules in the Isolated Antigravity Home that allow external reads and deny known file, command, MCP, and browser-actuation paths. It limits Antigravity tools but is not an operating-system sandbox, and project-local hooks remain outside this guarantee.
+_Avoid_: read-only mode, safe mode, SuPi permissions
+
+**Model Catalogue**:
+The package-owned model choices that are also available to the current Antigravity account. A new Antigravity Run selects one catalogue entry explicitly.
+_Avoid_: all Antigravity models, PI model list, default model
+
+**Observed Evidence**:
+Bounded execution facts derived from Antigravity tool events and validated result references. Model claims alone are not Observed Evidence.
+_Avoid_: claimed evidence, answer citations, raw event stream
+
+**Web Evidence**:
+Observed Evidence that contains successful web tool activity and at least one validated source URL.
+_Avoid_: source list, cited answer, web claim
+
+**Workspace Evidence**:
+Observed Evidence that contains successful workspace inspection activity and validated workspace-relative paths.
+_Avoid_: code claim, file list, exploration output
+
+**Conversation Handle**:
+An opaque SuPi identifier for one Antigravity conversation that retains its original model and Workspace Access. A handle can continue only the conversation that `supi-antigravity` observed and recorded.
+_Avoid_: conversation ID, session ID, resume token
+
+**Walking Skeleton**:
+The smallest production-shaped `supi-antigravity` package that can complete and verify one Antigravity Run through its intended PI tool interface. It is retained and hardened rather than discarded as prototype code.
+_Avoid_: throwaway prototype, experiment, complete package

package/README.md

@@ -0,0 +1,75 @@
+# @mrclrchtr/supi-antigravity
+
+`@mrclrchtr/supi-antigravity` adds the beta `antigravity_run` tool to Pi. It runs bounded Antigravity consultations with an explicit Model Catalogue, optional current-workspace access, controlled web use, and observed evidence.
+
+## Install
+
+```bash
+pi install npm:@mrclrchtr/supi-antigravity
+```
+
+The package is not part of the recommended or full SuPi installer. Install it only when you want the Antigravity integration.
+
+Run `/reload` after installation.
+
+## First sign-in
+
+The package never uses the normal Antigravity profile. It creates an Isolated Antigravity Home under the Pi agent directory and a stable empty Consultation Workspace.
+
+Before the tool can appear, Pi shows a command like this:
+
+```bash
+cd "<consultation-workspace>" &&
+HOME="<isolated-home>" AGY_CLI_DISABLE_AUTO_UPDATE=true agy
+```
+
+On macOS, the package also creates and unlocks a private keychain inside the Isolated Antigravity Home. This avoids the macOS warning about a missing default keychain without prompting for the normal keychain password. Run the command, sign in, exit Antigravity, and reload Pi. The installed `agy` version must be at least `1.1.24`.
+
+If macOS displays `antigravity.` in the warning, the final `.` is sentence punctuation. It is not part of a keychain name.
+
+## `antigravity_run`
+
+A new run has this shape:
+
+```json
+{
+  "prompt": "Explain this API design.",
+  "new": {
+    "workspace": false,
+    "model": "gemini-3.8-flash-low"
+  }
+}
+```
+
+Set `workspace` to `true` to expose the current PI workspace. Set it to `false` to use the empty Consultation Workspace. A follow-up must use exactly one returned Conversation Handle:
+
+```json
+{
+  "prompt": "Now compare the alternatives.",
+  "continue": { "handle": "agy_..." }
+}
+```
+
+Follow-ups keep the original model and workspace. A handle is opaque, branch-aware, and retired after a started follow-up fails or is canceled.
+
+The result reports web use, workspace use, observed and claimed references, warnings, token use, and the Conversation Handle. Antigravity can return a claimed reference without producing matching tool activity; SuPi labels it as claimed instead of observed.
+
+## Security limits
+
+The Isolated Antigravity Home enforces an Inspection Permission Set. It allows `read_url(*)` and denies file writes, commands, unsandboxed actions, MCP, and URL execution. These rules are not an operating-system sandbox.
+
+For workspace runs, project-local hooks can run commands, read the Antigravity transcript, and cause side effects outside these permission rules. SuPi probes hook state before the paid process and warns when hooks are active or unknown.
+
+`read_url(*)` can reach local, private-network, and link-local endpoints that Antigravity accepts. It does not enforce public-internet-only access.
+
+Use `/supi-settings` to disable the tool. Disabling it skips availability checks and removes `antigravity_run` from the active tool list.
+
+## Live probe
+
+The live probe is opt-in and never runs during normal tests or CI:
+
+```bash
+SUPI_ANTIGRAVITY_LIVE=1 pnpm exec jiti packages/supi-antigravity/scripts/live-probe.ts
+```
+
+It uses the isolated profile and checks web evidence, follow-up context, workspace evidence, and byte-identical fixture state.

package/docs/adr/0001-use-an-isolated-antigravity-home.md

@@ -0,0 +1,5 @@
+# Use an Isolated Antigravity Home
+
+Antigravity Runs use a stable Isolated Antigravity Home under PI agent state instead of the user's normal Antigravity profile or a new home for each run. This lets `supi-antigravity` enforce its Inspection Permission Set and exclude global customizations without changing user settings, while stable conversation state supports Conversation Handles; the trade-off is one separate sign-in and explicit manual cleanup.
+
+On macOS, `agy` uses the system keychain for authentication. An isolated `HOME` has no default keychain until the package creates one. The package creates a package-owned `antigravity.keychain-db` with an empty password and exposes it as `Library/Keychains/login.keychain-db` through a symlink. It unlocks this private keychain before each `agy` process, without prompting for a password. It does not copy or use the normal profile's keychain.

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -0,0 +1,118 @@
+<div align="center">
+  <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-core">
+    <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-core/assets/social-preview.png" alt="SuPi Core" width="100%">
+  </a>
+</div>
+
+# @mrclrchtr/supi-core
+
+[![GitHub stars](https://img.shields.io/github/stars/mrclrchtr/supi)](https://github.com/mrclrchtr/supi/stargazers)
+
+Shared infrastructure for SuPi extensions.
+
+This is a **pure library** — it does not register any pi commands or tools. The `/supi-settings` command is now available through `@mrclrchtr/supi-settings`.
+
+## Install
+
+```bash
+pnpm add @mrclrchtr/supi-core
+```
+
+## Package surfaces
+
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
+
+## What you get from the API
+
+### Config helpers
+
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `replaceSupiConfigSection()` — replace one nested section while preserving other sections
+- `removeSupiConfigKey()` — remove a key or override
+
+Config file locations:
+
+- global: `~/.pi/agent/supi/config.json`
+- project: `.pi/supi/config.json`
+
+### Settings helpers
+
+- `registerSettings(pi, module)` — register one canonical asynchronous settings module
+- `defineConfigSettings(options)` — adapt a fixed SuPi config section to that module interface
+- settings registry helpers and types for the `@mrclrchtr/supi-settings` configuration surface
+
+### Context helpers
+
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
+- optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
+
+### Report helpers
+
+- `clampReportWidth()` — enforce a minimum readable report width
+- `formatReportTitle()` / `formatSectionHeader()` — shared themed headers
+- `formatDimLine()` / `formatKeyValueLine()` — common summary rows
+- `formatOverflowHint()` — consistent preview-overflow hints
+- `wrapReportText()` — ANSI-aware wrapped report blocks with optional indentation
+
+## Example
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  defineConfigSettings,
+  loadSupiConfig,
+  registerSettings,
+  wrapExtensionContext,
+} from "@mrclrchtr/supi-core/api";
+
+export default function myExtension(pi: ExtensionAPI) {
+  const defaults = { enabled: true };
+  const config = loadSupiConfig("my-extension", process.cwd(), defaults);
+
+  registerSettings(
+    pi,
+    defineConfigSettings({
+      id: "my-extension",
+      label: "My Extension",
+      section: "my-extension",
+      defaults,
+      fields: [
+        {
+          kind: "boolean" as const,
+          key: "enabled",
+          label: "Enabled",
+        },
+      ],
+    }),
+  );
+
+  const message = wrapExtensionContext("my-extension", "hello", {
+    enabled: config.enabled,
+  });
+  void message;
+}
+```
+
+## Source
+
+- `src/api.ts` — exported library surface
+- `src/config.ts` — shared config loading and writing
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
+- `src/settings/` — settings registry, schema, scope resolution, and persistence
+- `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@mrclrchtr/supi-core",
+  "version": "6.4.0",
+  "description": "Shared settings, configuration, reporting, and session infrastructure",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git",
+    "directory": "packages/supi-core"
+  },
+  "homepage": "https://github.com/mrclrchtr/supi/tree/main/packages/supi-core#readme",
+  "bugs": {
+    "url": "https://github.com/mrclrchtr/supi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "supi",
+    "extension-utils",
+    "settings",
+    "configuration"
+  ],
+  "type": "module",
+  "files": [
+    "src/**/*.ts",
+    "!__tests__"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "25.9.5",
+    "vitest": "4.1.11"
+  },
+  "main": "src/api.ts",
+  "exports": {
+    "./api": "./src/api.ts",
+    "./config": "./src/config.ts",
+    "./context": "./src/context.ts",
+    "./debug": "./src/debug.ts",
+    "./evidence-badge": "./src/evidence-badge.ts",
+    "./footer-registry": "./src/footer-registry.ts",
+    "./llm": "./src/llm.ts",
+    "./model-selection": "./src/model-selection.ts",
+    "./package.json": "./package.json",
+    "./path": "./src/path.ts",
+    "./project": "./src/project.ts",
+    "./prompt-surface": "./src/prompt-surface.ts",
+    "./report": "./src/report.ts",
+    "./session": "./src/session.ts",
+    "./settings": "./src/settings.ts",
+    "./spinner-frames": "./src/spinner-frames.ts",
+    "./status-spinner": "./src/status-spinner.ts",
+    "./terminal": "./src/terminal.ts"
+  }
+}

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -0,0 +1,40 @@
+// supi-core — shared infrastructure for SuPi extensions.
+// Provides XML context tag wrapping, unified config, prompt-surface resolution,
+// and shared settings, reporting, and session utilities.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
+
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./context.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./debug.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./evidence-badge.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./footer-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./llm.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./model-selection.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./prompt-surface.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./session.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./spinner-frames.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./status-spinner.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";

package/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -0,0 +1,232 @@
+// Shared config system for SuPi extensions.
+//
+// Global config: ~/.pi/agent/supi/config.json
+// Project config: .pi/supi/config.json (relative to cwd)
+// Resolution: hardcoded defaults ← global ← project
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+
+const GLOBAL_CONFIG_DIR = `${CONFIG_DIR_NAME}/agent/supi`;
+const PROJECT_CONFIG_DIR = `${CONFIG_DIR_NAME}/supi`;
+const CONFIG_FILE = "config.json";
+
+function getGlobalConfigPath(homeDir?: string): string {
+  return path.join(homeDir ?? os.homedir(), GLOBAL_CONFIG_DIR, CONFIG_FILE);
+}
+
+function getProjectConfigPath(cwd: string): string {
+  return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
+}
+
+/** Return the SuPi config file path for one scope. */
+export function getSupiConfigPath(
+  scope: "global" | "project",
+  cwd: string,
+  options?: SupiConfigOptions,
+): string {
+  return scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(cwd);
+}
+
+export function readJsonFile(filePath: string): Record<string, unknown> | null {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    // ENOENT or permission error — silent, file may not exist
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // biome-ignore lint/suspicious/noConsole: deliberate config parse warning
+    console.warn(`[supi-core] Failed to parse config file, ignoring: ${filePath}`);
+    return null;
+  }
+
+  if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+    return parsed as Record<string, unknown>;
+  }
+
+  // biome-ignore lint/suspicious/noConsole: deliberate config parse warning
+  console.warn(`[supi-core] Config file root is not an object, ignoring: ${filePath}`);
+  return null;
+}
+
+function shallowMerge<T>(base: T, ...overrides: Array<Record<string, unknown> | null>): T {
+  let result = { ...base };
+  for (const override of overrides) {
+    if (!override) continue;
+    result = { ...result, ...override };
+  }
+  return result;
+}
+
+export interface SupiConfigOptions {
+  homeDir?: string;
+}
+
+/**
+ * Load and merge config for a given extension section.
+ *
+ * Resolution order: defaults ← global ← project
+ */
+export function loadSupiConfig<T>(
+  section: string,
+  cwd: string,
+  defaults: T,
+  options?: SupiConfigOptions,
+): T {
+  const globalConfig = readJsonFile(getGlobalConfigPath(options?.homeDir));
+  const projectConfig = readJsonFile(getProjectConfigPath(cwd));
+
+  const globalSection = extractSection(globalConfig, section);
+  const projectSection = extractSection(projectConfig, section);
+
+  return shallowMerge(defaults, globalSection, projectSection);
+}
+
+/**
+ * Load config for a single scope only.
+ *
+ * Resolution order: defaults ← selected scope
+ *
+ * This is useful for settings UIs that need to show the raw values stored in
+ * one scope, rather than the effective merged config.
+ */
+export function loadSupiConfigForScope<T>(
+  section: string,
+  cwd: string,
+  defaults: T,
+  options: { scope: "global" | "project" } & SupiConfigOptions,
+): T {
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
+
+  const scopedSection = extractSection(config, section);
+  return shallowMerge(defaults, scopedSection);
+}
+
+/** Load the raw object for one config section and one scope. */
+export function loadSupiConfigSectionForScope(
+  section: string,
+  cwd: string,
+  options: { scope: "global" | "project" } & SupiConfigOptions,
+): Record<string, unknown> | null {
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
+  return extractSection(config, section);
+}
+
+export interface SupiConfigLocation {
+  section: string;
+  scope: "global" | "project";
+  cwd: string;
+}
+
+/**
+ * Write config values for a given extension section.
+ */
+export function writeSupiConfig(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const existing = readJsonFile(configPath) ?? {};
+  existing[loc.section] = {
+    ...((existing[loc.section] as Record<string, unknown>) ?? {}),
+    ...value,
+  };
+
+  fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * Replace one complete config section while preserving other sections.
+ *
+ * This is useful for nested settings that must remove stale keys as part of
+ * one update. An empty section is removed from the config file.
+ */
+export function replaceSupiConfigSection(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+  const existing = readJsonFile(configPath) ?? {};
+
+  if (Object.keys(value).length > 0) existing[loc.section] = value;
+  else delete existing[loc.section];
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+  if (content) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, "utf-8");
+    return;
+  }
+
+  try {
+    fs.unlinkSync(configPath);
+  } catch {
+    // File may not exist.
+  }
+}
+
+/**
+ * Remove a key from a config section.
+ * Used by `interval default` to remove the project override.
+ */
+export function removeSupiConfigKey(
+  loc: SupiConfigLocation,
+  key: string,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+
+  const existing = readJsonFile(configPath);
+  if (!existing) return;
+
+  const sectionData = existing[loc.section] as Record<string, unknown> | undefined;
+  if (!sectionData) return;
+
+  delete sectionData[key];
+
+  if (Object.keys(sectionData).length === 0) {
+    delete existing[loc.section];
+  }
+
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+
+  if (content) {
+    // Directory guaranteed to exist since we just read from it
+    fs.writeFileSync(configPath, content, "utf-8");
+  } else {
+    try {
+      fs.unlinkSync(configPath);
+    } catch {
+      // File may not exist
+    }
+  }
+}
+
+function extractSection(
+  config: Record<string, unknown> | null,
+  section: string,
+): Record<string, unknown> | null {
+  if (!config) return null;
+  const data = config[section];
+  if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+    return data as Record<string, unknown>;
+  }
+  return null;
+}