infra-kit 0.1.114 → 0.1.117

package/src/lib/command-catalog/__tests__/__snapshots__/command-catalog.test.ts.snap

@@ -0,0 +1,212 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`command catalog — MCP exposure policy > matches the golden MCP tools/list surface (names + schema shape) 1`] = `
+[
+  {
+    "input": [
+      "all",
+      "root",
+    ],
+    "name": "audit",
+    "output": [
+      "allPassed",
+      "packages",
+    ],
+  },
+  {
+    "input": [],
+    "name": "env-clear",
+    "output": [
+      "filePath",
+      "unsetStatements",
+      "variableCount",
+    ],
+  },
+  {
+    "input": [],
+    "name": "env-list",
+    "output": [
+      "configs",
+      "project",
+    ],
+  },
+  {
+    "input": [
+      "config",
+    ],
+    "name": "env-load",
+    "output": [
+      "config",
+      "filePath",
+      "project",
+      "variableCount",
+    ],
+  },
+  {
+    "input": [],
+    "name": "env-status",
+    "output": [
+      "autoLoaded",
+      "cleared",
+      "sessionConfig",
+      "sessionId",
+      "sessionLoadedAt",
+      "sessionLoadedCount",
+      "sessionProject",
+      "sessionTotalCount",
+    ],
+  },
+  {
+    "input": [
+      "all",
+    ],
+    "name": "gh-merge-dev",
+    "output": [
+      "failedBranches",
+      "failedMerges",
+      "successfulMerges",
+      "totalBranches",
+    ],
+  },
+  {
+    "input": [
+      "env",
+      "skipTerraform",
+      "version",
+    ],
+    "name": "gh-release-deploy-all",
+    "output": [
+      "environment",
+      "releaseBranch",
+      "skipTerraformDeploy",
+      "success",
+      "version",
+    ],
+  },
+  {
+    "input": [
+      "env",
+      "services",
+      "skipTerraform",
+      "version",
+    ],
+    "name": "gh-release-deploy-selected",
+    "output": [
+      "environment",
+      "releaseBranch",
+      "services",
+      "skipTerraformDeploy",
+      "success",
+      "version",
+    ],
+  },
+  {
+    "input": [],
+    "name": "gh-release-list",
+    "output": [
+      "count",
+      "releases",
+    ],
+  },
+  {
+    "input": [
+      "releases",
+    ],
+    "name": "release-create",
+    "output": [
+      "createdBranches",
+      "failedReleases",
+      "failureCount",
+      "releases",
+      "successCount",
+    ],
+  },
+  {
+    "input": [
+      "description",
+      "version",
+    ],
+    "name": "release-desc-edit",
+    "output": [
+      "branch",
+      "changed",
+      "jiraVersionUrl",
+      "newDescription",
+      "previousDescription",
+      "version",
+    ],
+  },
+  {
+    "input": [],
+    "name": "vendor-check",
+    "output": [
+      "added",
+      "fileCount",
+      "modified",
+      "ok",
+      "removed",
+      "status",
+    ],
+  },
+  {
+    "input": [
+      "repos",
+    ],
+    "name": "vendor-diff",
+    "output": [
+      "drifted",
+      "entries",
+      "ok",
+    ],
+  },
+  {
+    "input": [],
+    "name": "version",
+    "output": [
+      "version",
+    ],
+  },
+  {
+    "input": [
+      "all",
+      "cmux",
+      "cursor",
+      "githubDesktop",
+      "ide",
+      "versions",
+    ],
+    "name": "worktrees-add",
+    "output": [
+      "count",
+      "createdWorktrees",
+    ],
+  },
+  {
+    "input": [],
+    "name": "worktrees-list",
+    "output": [
+      "count",
+      "worktrees",
+    ],
+  },
+  {
+    "input": [],
+    "name": "worktrees-reload",
+    "output": [
+      "closedCmux",
+      "ideFoldersAdded",
+      "ideFoldersRemoved",
+      "ideProviders",
+      "openedCmux",
+    ],
+  },
+  {
+    "input": [],
+    "name": "worktrees-sync",
+    "output": [
+      "count",
+      "removedWorktrees",
+    ],
+  },
+]
+`;

package/src/lib/command-catalog/__tests__/command-catalog.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from 'vitest'
+
+import { commandCatalog, getExposedMcpTools, getMenuGroupCommands } from '../command-catalog'
+
+// The exact MCP tool surface that was hand-listed in src/mcp/tools/index.ts
+// before the catalog refactor. The catalog must keep this byte-for-byte.
+const EXPECTED_EXPOSED_TOOLS = [
+  'env-status',
+  'env-list',
+  'env-load',
+  'env-clear',
+  'gh-merge-dev',
+  'release-create',
+  'release-desc-edit',
+  'gh-release-deploy-all',
+  'gh-release-deploy-selected',
+  'gh-release-list',
+  'audit',
+  'vendor-check',
+  'vendor-diff',
+  'version',
+  'worktrees-add',
+  'worktrees-list',
+  'worktrees-reload',
+  'worktrees-sync',
+]
+
+// Deliberately NOT exposed as MCP tools (mutating / host-inspecting / irreversible).
+// release-deliver (prod delivery + admin-merge) and worktrees-remove (rm -rf) are
+// CLI-only by design.
+const EXPECTED_UNEXPOSED_WITH_TOOL = [
+  'doctor',
+  'vendor-sync',
+  'vendor-manifest',
+  'gh-release-deliver',
+  'worktrees-remove',
+]
+
+describe('command catalog — MCP exposure policy', () => {
+  it('exposes exactly the expected 18 MCP tools (set-equal, order-independent)', () => {
+    const exposedNames = getExposedMcpTools()
+      .map((tool) => {
+        return tool.name
+      })
+      .sort()
+
+    expect(exposedNames).toEqual([...EXPECTED_EXPOSED_TOOLS].sort())
+    expect(exposedNames).toHaveLength(18)
+  })
+
+  it('never exposes the irreversible release-deliver / worktrees-remove tools', () => {
+    const exposedNames = new Set(
+      getExposedMcpTools().map((tool) => {
+        return tool.name
+      }),
+    )
+
+    expect(exposedNames.has('gh-release-deliver')).toBe(false)
+    expect(exposedNames.has('worktrees-remove')).toBe(false)
+  })
+
+  it('keeps doctor, vendor-sync and vendor-manifest UNEXPOSED even though they have tools', () => {
+    const exposedNames = new Set(
+      getExposedMcpTools().map((tool) => {
+        return tool.name
+      }),
+    )
+
+    for (const unexposed of EXPECTED_UNEXPOSED_WITH_TOOL) {
+      const entry = commandCatalog.find((candidate) => {
+        return candidate.mcpTool?.name === unexposed
+      })
+
+      expect(entry, `catalog should carry a tool for ${unexposed}`).toBeDefined()
+      expect(entry?.mcpExposed, `${unexposed} must stay unexposed`).toBe(false)
+      expect(exposedNames.has(unexposed), `${unexposed} must not be registered`).toBe(false)
+    }
+  })
+
+  it('every exposed entry carries a tool, and every entry with mcpExposed=true has one', () => {
+    for (const entry of commandCatalog) {
+      if (entry.mcpExposed) {
+        expect(entry.mcpTool, `${entry.cliName} is exposed but has no tool`).not.toBeNull()
+      }
+    }
+  })
+
+  it('mcpTool name matches a stable identifier (no duplicate registrations)', () => {
+    const names = getExposedMcpTools().map((tool) => {
+      return tool.name
+    })
+
+    expect(new Set(names).size).toBe(names.length)
+  })
+
+  // Golden snapshot of the registered MCP surface: tool name + input/output
+  // schema field names. Locks names AND schema shape so any accidental change to
+  // the exposed tools/list fails CI (the "tools/list identical" guardrail).
+  it('matches the golden MCP tools/list surface (names + schema shape)', () => {
+    const surface = getExposedMcpTools()
+      .map((tool) => {
+        return {
+          name: tool.name,
+          input: Object.keys(tool.inputSchema).sort(),
+          output: Object.keys(tool.outputSchema).sort(),
+        }
+      })
+      .sort((a, b) => {
+        return a.name.localeCompare(b.name)
+      })
+
+    expect(surface).toMatchSnapshot()
+  })
+})
+
+describe('command catalog — CLI/MCP name parity', () => {
+  // The authoritative (cliName -> mcpName) map. Divergences are INTENTIONAL and
+  // grandfathered here (the `gh-` prefix on release tools). Any new accidental
+  // divergence — or a typo that renames an MCP tool — fails this test.
+  const EXPECTED_PARITY: Record<string, string> = {
+    'merge-dev': 'gh-merge-dev',
+    'release-list': 'gh-release-list',
+    'release-create': 'release-create',
+    'release-desc-edit': 'release-desc-edit',
+    'release-deploy-all': 'gh-release-deploy-all',
+    'release-deploy-selected': 'gh-release-deploy-selected',
+    'release-deliver': 'gh-release-deliver',
+    'worktrees-add': 'worktrees-add',
+    'worktrees-list': 'worktrees-list',
+    'worktrees-reload': 'worktrees-reload',
+    'worktrees-remove': 'worktrees-remove',
+    'worktrees-sync': 'worktrees-sync',
+    audit: 'audit',
+    doctor: 'doctor',
+    version: 'version',
+    'env-status': 'env-status',
+    'env-list': 'env-list',
+    'env-load': 'env-load',
+    'env-clear': 'env-clear',
+    'vendor-check': 'vendor-check',
+    'vendor-diff': 'vendor-diff',
+    'vendor-manifest': 'vendor-manifest',
+    'vendor-sync': 'vendor-sync',
+  }
+
+  it('every catalog entry with a tool matches its expected (cliName, mcpName) pair', () => {
+    const actualParity: Record<string, string> = {}
+
+    for (const entry of commandCatalog) {
+      if (entry.mcpTool) {
+        actualParity[entry.cliName] = entry.mcpTool.name
+      }
+    }
+
+    expect(actualParity).toEqual(EXPECTED_PARITY)
+  })
+})
+
+describe('command catalog — menu grouping', () => {
+  it('preserves the three menu groups in display order', () => {
+    expect(getMenuGroupCommands('release')).toEqual([
+      'merge-dev',
+      'release-list',
+      'release-create',
+      'release-desc-edit',
+      'release-deploy-all',
+      'release-deploy-selected',
+      'release-deliver',
+    ])
+
+    expect(getMenuGroupCommands('worktrees')).toEqual([
+      'worktrees-add',
+      'worktrees-list',
+      'worktrees-reload',
+      'worktrees-remove',
+      'worktrees-sync',
+    ])
+
+    expect(getMenuGroupCommands('environment')).toEqual([
+      'audit',
+      'vendor',
+      'vendor-config',
+      'doctor',
+      'init',
+      'version',
+      'config',
+      'env-status',
+      'env-list',
+      'env-load',
+      'env-clear',
+    ])
+  })
+})

package/src/lib/command-catalog/command-catalog.ts

@@ -0,0 +1,141 @@
+import type { z } from 'zod'
+
+import { auditMcpTool } from 'src/commands/audit'
+import { doctorMcpTool } from 'src/commands/doctor'
+import { envClearMcpTool } from 'src/commands/env-clear'
+import { envListMcpTool } from 'src/commands/env-list'
+import { envLoadMcpTool } from 'src/commands/env-load'
+import { envStatusMcpTool } from 'src/commands/env-status'
+import { ghMergeDevMcpTool } from 'src/commands/gh-merge-dev'
+import { ghReleaseDeliverMcpTool } from 'src/commands/gh-release-deliver'
+import { ghReleaseDeployAllMcpTool } from 'src/commands/gh-release-deploy-all'
+import { ghReleaseDeploySelectedMcpTool } from 'src/commands/gh-release-deploy-selected'
+import { ghReleaseListMcpTool } from 'src/commands/gh-release-list'
+import { releaseCreateMcpTool } from 'src/commands/release-create'
+import { releaseDescEditMcpTool } from 'src/commands/release-desc-edit'
+import { vendorCheckMcpTool } from 'src/commands/vendor-check'
+import { vendorDiffMcpTool } from 'src/commands/vendor-diff'
+import { vendorManifestMcpTool } from 'src/commands/vendor-manifest'
+import { vendorSyncMcpTool } from 'src/commands/vendor-sync'
+import { versionMcpTool } from 'src/commands/version'
+import { worktreesAddMcpTool } from 'src/commands/worktrees-add'
+import { worktreesListMcpTool } from 'src/commands/worktrees-list'
+import { worktreesReloadMcpTool } from 'src/commands/worktrees-reload'
+import { worktreesRemoveMcpTool } from 'src/commands/worktrees-remove'
+import { worktreesSyncMcpTool } from 'src/commands/worktrees-sync'
+import type { ToolsExecutionResult } from 'src/types'
+
+/**
+ * Registration-facing shape of an MCP tool. The concrete `*McpTool` definitions
+ * are generic over their Zod input/output shapes (and invariant), so they cannot
+ * share one precise `McpTool<...>` element type in an array. This widened, non-
+ * generic view exposes exactly what registration needs and every concrete tool
+ * assigns to it. Matches the loose handler typing already used in tool-handler.
+ */
+export interface CatalogMcpTool {
+  name: string
+  description: string
+  inputSchema: z.ZodRawShape
+  outputSchema: z.ZodRawShape
+  // Heterogeneous tool params; loose `any` mirrors the existing tool-handler typing.
+  handler: (params: any) => Promise<ToolsExecutionResult>
+}
+
+/**
+ * Single source of truth for the CLI command surface. It consolidates what used
+ * to live in three hand-maintained places (the MCP `tools[]` array and the
+ * three no-arg-menu name arrays) into one list, so they can no longer drift.
+ *
+ * It does NOT replace Commander's `.command().option()` wiring in entry/cli.ts —
+ * that stays the source of truth for argument parsing. This catalog only carries
+ * cross-surface metadata: the canonical names, which menu group a command shows
+ * in, and whether the command is exposed as an MCP tool.
+ */
+
+/** Top-level menu group for the no-arg interactive picker (null = not shown). */
+export type MenuGroup = 'release' | 'worktrees' | 'environment'
+
+export interface CommandCatalogEntry {
+  /** CLI command name as registered in Commander (flat form, e.g. `merge-dev`). */
+  cliName: string
+  /** Menu group, or null for subcommands not shown at the top level. */
+  menuGroup: MenuGroup | null
+  /** The co-located MCP tool, or null for CLI-only commands (init/config/vendor group). */
+  mcpTool: CatalogMcpTool | null
+  /**
+   * Whether the command is registered as an MCP tool. Explicit allowlist:
+   * `doctor`, `vendor-sync`, and `vendor-manifest` are deliberately UNEXPOSED
+   * (vendor-sync/manifest mutate consumer repos; doctor is host-inspecting), so
+   * they must never become agent-callable by accident.
+   */
+  mcpExposed: boolean
+}
+
+/**
+ * Authored in no-arg-menu display order so the interactive picker derives
+ * directly from this list (see entry/cli.ts). MCP registration filters this
+ * list by `mcpExposed`; MCP tool order is not contractual (clients address
+ * tools by name), so the registration order need not match the array order.
+ */
+export const commandCatalog: CommandCatalogEntry[] = [
+  // --- Release Management (menu group) ---
+  { cliName: 'merge-dev', menuGroup: 'release', mcpTool: ghMergeDevMcpTool, mcpExposed: true },
+  { cliName: 'release-list', menuGroup: 'release', mcpTool: ghReleaseListMcpTool, mcpExposed: true },
+  { cliName: 'release-create', menuGroup: 'release', mcpTool: releaseCreateMcpTool, mcpExposed: true },
+  { cliName: 'release-desc-edit', menuGroup: 'release', mcpTool: releaseDescEditMcpTool, mcpExposed: true },
+  { cliName: 'release-deploy-all', menuGroup: 'release', mcpTool: ghReleaseDeployAllMcpTool, mcpExposed: true },
+  {
+    cliName: 'release-deploy-selected',
+    menuGroup: 'release',
+    mcpTool: ghReleaseDeploySelectedMcpTool,
+    mcpExposed: true,
+  },
+  // release-deliver does prod delivery + admin-merge — genuinely irreversible,
+  // so it is CLI-only by design (mirrors the vendor-sync/manifest rationale).
+  { cliName: 'release-deliver', menuGroup: 'release', mcpTool: ghReleaseDeliverMcpTool, mcpExposed: false },
+
+  // --- Worktrees (menu group) ---
+  { cliName: 'worktrees-add', menuGroup: 'worktrees', mcpTool: worktreesAddMcpTool, mcpExposed: true },
+  { cliName: 'worktrees-list', menuGroup: 'worktrees', mcpTool: worktreesListMcpTool, mcpExposed: true },
+  { cliName: 'worktrees-reload', menuGroup: 'worktrees', mcpTool: worktreesReloadMcpTool, mcpExposed: true },
+  // worktrees-remove runs rm -rf on worktree dirs — genuinely irreversible, so
+  // it is CLI-only by design (mirrors the vendor-sync/manifest rationale).
+  { cliName: 'worktrees-remove', menuGroup: 'worktrees', mcpTool: worktreesRemoveMcpTool, mcpExposed: false },
+  { cliName: 'worktrees-sync', menuGroup: 'worktrees', mcpTool: worktreesSyncMcpTool, mcpExposed: true },
+
+  // --- Environment (menu group) ---
+  { cliName: 'audit', menuGroup: 'environment', mcpTool: auditMcpTool, mcpExposed: true },
+  { cliName: 'vendor', menuGroup: 'environment', mcpTool: null, mcpExposed: false },
+  { cliName: 'vendor-config', menuGroup: 'environment', mcpTool: null, mcpExposed: false },
+  { cliName: 'doctor', menuGroup: 'environment', mcpTool: doctorMcpTool, mcpExposed: false },
+  { cliName: 'init', menuGroup: 'environment', mcpTool: null, mcpExposed: false },
+  { cliName: 'version', menuGroup: 'environment', mcpTool: versionMcpTool, mcpExposed: true },
+  { cliName: 'config', menuGroup: 'environment', mcpTool: null, mcpExposed: false },
+  { cliName: 'env-status', menuGroup: 'environment', mcpTool: envStatusMcpTool, mcpExposed: true },
+  { cliName: 'env-list', menuGroup: 'environment', mcpTool: envListMcpTool, mcpExposed: true },
+  { cliName: 'env-load', menuGroup: 'environment', mcpTool: envLoadMcpTool, mcpExposed: true },
+  { cliName: 'env-clear', menuGroup: 'environment', mcpTool: envClearMcpTool, mcpExposed: true },
+  // Internal shell-startup trigger; hidden from the menu and never an MCP tool
+  // (it can't apply env to a shell — only the zsh integration sources the file).
+  { cliName: 'env-autoload', menuGroup: null, mcpTool: null, mcpExposed: false },
+
+  // --- vendor subcommands (not top-level menu items; MCP tools where applicable) ---
+  { cliName: 'vendor-check', menuGroup: null, mcpTool: vendorCheckMcpTool, mcpExposed: true },
+  { cliName: 'vendor-diff', menuGroup: null, mcpTool: vendorDiffMcpTool, mcpExposed: true },
+  { cliName: 'vendor-manifest', menuGroup: null, mcpTool: vendorManifestMcpTool, mcpExposed: false },
+  { cliName: 'vendor-sync', menuGroup: null, mcpTool: vendorSyncMcpTool, mcpExposed: false },
+]
+
+/** The MCP tools to register: catalog entries that are exposed and carry a tool. */
+export const getExposedMcpTools = (): CatalogMcpTool[] => {
+  return commandCatalog.flatMap((entry) => {
+    return entry.mcpExposed && entry.mcpTool ? [entry.mcpTool] : []
+  })
+}
+
+/** CLI command names for a menu group, in catalog (display) order. */
+export const getMenuGroupCommands = (group: MenuGroup): string[] => {
+  return commandCatalog.flatMap((entry) => {
+    return entry.menuGroup === group ? [entry.cliName] : []
+  })
+}

package/src/lib/command-catalog/index.ts

@@ -0,0 +1,2 @@
+export { commandCatalog, getExposedMcpTools, getMenuGroupCommands } from './command-catalog'
+export type { CommandCatalogEntry, MenuGroup } from './command-catalog'

package/src/lib/command-echo/__tests__/command-echo.test.ts

@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { logger } from 'src/lib/logger'
+
+import { commandEcho } from '../command-echo'
+
+vi.mock('src/lib/logger', () => {
+  return { logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }
+})
+
+const infoMock = vi.mocked(logger.info)
+
+// The single printed argument, or undefined when print() emitted nothing.
+const printedLine = (): string | undefined => {
+  return infoMock.mock.calls[0]?.[0] as string | undefined
+}
+
+beforeEach(() => {
+  commandEcho.reset()
+  infoMock.mockClear()
+})
+
+describe('commandEcho.print', () => {
+  it('emits nothing when the command was not interactive', () => {
+    commandEcho.start('release-create')
+    commandEcho.addOption('--yes', true)
+
+    commandEcho.print()
+
+    expect(infoMock).not.toHaveBeenCalled()
+  })
+
+  it('emits nothing when interactive but no options were recorded', () => {
+    commandEcho.start('release-create')
+    commandEcho.setInteractive()
+
+    commandEcho.print()
+
+    expect(infoMock).not.toHaveBeenCalled()
+  })
+
+  it('renders a boolean true option as a bare flag and omits boolean false', () => {
+    commandEcho.start('release-create')
+    commandEcho.setInteractive()
+    commandEcho.addOption('--yes', true)
+    commandEcho.addOption('--all', false)
+
+    commandEcho.print()
+
+    const line = printedLine()
+
+    expect(line).toContain('--yes')
+    expect(line).not.toContain('--all')
+  })
+
+  it('quotes a string option value', () => {
+    commandEcho.start('release-create')
+    commandEcho.setInteractive()
+    commandEcho.addOption('--release', 'checkout-redesign:regular:Q3 work')
+
+    commandEcho.print()
+
+    expect(printedLine()).toContain('--release "checkout-redesign:regular:Q3 work"')
+  })
+
+  it('joins and quotes an array option value', () => {
+    commandEcho.start('gh-merge-dev')
+    commandEcho.setInteractive()
+    commandEcho.addOption('--versions', ['1.2.5', '1.3.0'])
+
+    commandEcho.print()
+
+    expect(printedLine()).toContain('--versions "1.2.5, 1.3.0"')
+  })
+
+  it('formats the full equivalent command and round-trips the release description', () => {
+    commandEcho.start('release-create')
+    commandEcho.setInteractive()
+    commandEcho.addOption('--release', 'sponsored-banners-scroll-fix:regular:Fix scroll bug in results pages')
+    commandEcho.addOption('--yes', true)
+
+    commandEcho.print()
+
+    expect(printedLine()).toBe(
+      '📟 Equivalent command: \npnpm exec infra-kit release-create --release "sponsored-banners-scroll-fix:regular:Fix scroll bug in results pages" --yes\n',
+    )
+  })
+
+  it('preserves option order and drops false-valued flags from the middle', () => {
+    commandEcho.start('release-create')
+    commandEcho.setInteractive()
+    commandEcho.addOption('--release', 'one')
+    commandEcho.addOption('--all', false)
+    commandEcho.addOption('--yes', true)
+
+    commandEcho.print()
+
+    expect(printedLine()).toBe('📟 Equivalent command: \npnpm exec infra-kit release-create --release "one" --yes\n')
+  })
+})
+
+describe('commandEcho lifecycle', () => {
+  it('start() clears options and interactive state from a prior command', () => {
+    commandEcho.start('release-create')
+    commandEcho.setInteractive()
+    commandEcho.addOption('--release', 'stale')
+
+    commandEcho.start('worktrees-add')
+    commandEcho.addOption('--versions', ['1.0.0'])
+
+    commandEcho.print()
+
+    // start() reset isInteractive to false, so print() stays silent.
+    expect(infoMock).not.toHaveBeenCalled()
+  })
+
+  it('reset() clears all state so a later print() emits nothing', () => {
+    commandEcho.start('release-create')
+    commandEcho.setInteractive()
+    commandEcho.addOption('--yes', true)
+
+    commandEcho.reset()
+    commandEcho.print()
+
+    expect(infoMock).not.toHaveBeenCalled()
+  })
+})

package/src/lib/constants/constants.ts

@@ -10,6 +10,19 @@ export const INFRA_KIT_SESSION_VAR = 'INFRA_KIT_SESSION'
 export const INFRA_KIT_ENV_CONFIG_VAR = 'INFRA_KIT_ENV_CONFIG'
 export const INFRA_KIT_ENV_PROJECT_VAR = 'INFRA_KIT_ENV_PROJECT'
 export const INFRA_KIT_ENV_LOADED_AT_VAR = 'INFRA_KIT_ENV_LOADED_AT'
+/**
+ * Marker exported into env-load.sh ONLY when the load was triggered automatically
+ * (see lib/env-autoload). Its presence is the sole signal distinguishing an
+ * auto-loaded env from a deliberate manual `env-load`, so auto-load never
+ * clobbers a manual choice. A manual load unsets it.
+ */
+export const INFRA_KIT_ENV_AUTOLOADED_VAR = 'INFRA_KIT_ENV_AUTOLOADED'
+/**
+ * Suppression sentinel exported by env-clear. While set in a shell, cli-invocation
+ * auto-load stays silent (a deliberate clear must not be immediately re-loaded).
+ * Lifted by a manual `env-load` or a new shell.
+ */
+export const INFRA_KIT_ENV_CLEARED_VAR = 'INFRA_KIT_ENV_CLEARED'
 
 /**
  * Matches a line of the form `KEY=...` where KEY is an env-var identifier