infra-kit 0.1.105 → 0.1.107

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "infra-kit",
   "type": "module",
-  "version": "0.1.105",
+  "version": "0.1.107",
   "description": "infra-kit",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/commands/.omc/state/sessions/afc6290b-40d3-4bef-b3b6-14484c034ab9/pre-tool-advisory-throttle.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1781510589151,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    },
+    "466399dafa2d20f60587180bad0a07358eb7f2bce724df0ff682f038ad33f5ad": {
+      "last_emitted_at_ms": 1781510561764,
+      "message": "Read multiple files in parallel when possible for faster analysis."
+    }
+  },
+  "updated_at": "2026-06-15T08:03:09.151Z"
+}

package/src/commands/doctor/__tests__/agent-files.test.ts

@@ -0,0 +1,110 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { writeAgentFiles } from 'src/commands/init/agent-files'
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
+
+import { checkAgentFiles } from '../doctor'
+
+vi.mock('src/lib/git-utils', () => {
+  return {
+    getProjectRoot: vi.fn(),
+    getRepoName: vi.fn(),
+  }
+})
+
+const writeFile = (filePath: string, content: string): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content, 'utf-8')
+}
+
+const withTmpRepo = async (fn: (tmp: string) => Promise<void>, opts: { repo?: boolean } = {}): Promise<void> => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'infra-kit-doctor-agents-test-'))
+
+  vi.mocked(getProjectRoot).mockResolvedValue(tmp)
+  vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
+
+  if (opts.repo !== false) {
+    writeFile(path.join(tmp, 'infra-kit.json'), '{"environments":["dev"]}\n')
+  }
+
+  try {
+    await fn(tmp)
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+const statusOf = (checks: { name: string; status: string }[], name: string): string | undefined => {
+  return checks.find((c) => {
+    return c.name === name
+  })?.status
+}
+
+describe('checkAgentFiles', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns no checks outside an infra-kit repo (never crashes)', async () => {
+    await withTmpRepo(
+      async () => {
+        await expect(checkAgentFiles()).resolves.toEqual([])
+      },
+      { repo: false },
+    )
+  })
+
+  it('passes all three checks right after init runs the agent-files step', async () => {
+    await withTmpRepo(async () => {
+      await writeAgentFiles()
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, 'AGENTS.md block')).toBe('pass')
+      expect(statusOf(checks, 'CLAUDE.md import')).toBe('pass')
+      expect(statusOf(checks, '.cursor/rules block')).toBe('pass')
+    })
+  })
+
+  it('flags AGENTS.md present but CLAUDE.md import removed', async () => {
+    await withTmpRepo(async (tmp) => {
+      await writeAgentFiles()
+      // User deletes CLAUDE.md (drops the @AGENTS.md import) but keeps AGENTS.md.
+      fs.rmSync(path.join(tmp, 'CLAUDE.md'))
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, 'AGENTS.md block')).toBe('pass')
+      expect(statusOf(checks, 'CLAUDE.md import')).toBe('fail')
+    })
+  })
+
+  it('flags a missing .cursor/rules block', async () => {
+    await withTmpRepo(async (tmp) => {
+      await writeAgentFiles()
+      fs.rmSync(path.join(tmp, '.cursor', 'rules', 'infra-kit.mdc'))
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, '.cursor/rules block')).toBe('fail')
+    })
+  })
+
+  it('flags a missing AGENTS.md block', async () => {
+    await withTmpRepo(async (tmp) => {
+      await writeAgentFiles()
+      fs.rmSync(path.join(tmp, 'AGENTS.md'))
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, 'AGENTS.md block')).toBe('fail')
+    })
+  })
+})

package/src/commands/doctor/doctor.ts

@@ -4,10 +4,17 @@ import path from 'node:path'
 import { z } from 'zod'
 import { $ } from 'zx'
 
+import {
+  AGENTS_IMPORT_END,
+  AGENTS_IMPORT_START,
+  AGENTS_MARKER_END,
+  AGENTS_MARKER_START,
+} from 'src/commands/init/agent-files'
 import { MARKER_END, MARKER_START, buildShellBlock } from 'src/commands/init/init'
 import { getProjectRoot } from 'src/lib/git-utils/git-utils'
 import { getInfraKitConfig, getInfraKitConfigPaths, resetInfraKitConfigCache } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
+import { hasManagedBlock } from 'src/lib/managed-block'
 import { defineMcpTool, textContent } from 'src/types'
 
 interface CheckResult {
@@ -196,11 +203,67 @@ const checkRtkConfigured = async (): Promise<CheckResult> => {
   }
 }
 
+/**
+ * Check that the repo agent-instruction files managed by `infra-kit init` exist:
+ * the `AGENTS.md` block, the `@AGENTS.md` import region in `CLAUDE.md`, and the
+ * `.cursor/rules` block. Presence only. Repo-gated: returns no checks when run
+ * outside an infra-kit repo so doctor never crashes there.
+ */
+export const checkAgentFiles = async (): Promise<CheckResult[]> => {
+  let mainConfigPath: string
+
+  try {
+    mainConfigPath = (await getInfraKitConfigPaths()).main
+  } catch {
+    return []
+  }
+
+  if (!fs.existsSync(mainConfigPath)) return []
+
+  const root = path.dirname(mainConfigPath)
+
+  const blockPresent = (relPath: string, start: string, end: string): boolean => {
+    const filePath = path.join(root, relPath)
+    const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : ''
+
+    return hasManagedBlock(content, start, end)
+  }
+
+  const entries = [
+    {
+      name: 'AGENTS.md block',
+      present: blockPresent('AGENTS.md', AGENTS_MARKER_START, AGENTS_MARKER_END),
+      okMessage: 'AGENTS.md block present',
+      missingMessage: 'infra-kit block missing from AGENTS.md. Run: infra-kit init',
+    },
+    {
+      name: 'CLAUDE.md import',
+      present: blockPresent('CLAUDE.md', AGENTS_IMPORT_START, AGENTS_IMPORT_END),
+      okMessage: 'CLAUDE.md imports @AGENTS.md',
+      missingMessage: '@AGENTS.md import block missing from CLAUDE.md. Run: infra-kit init',
+    },
+    {
+      name: '.cursor/rules block',
+      present: blockPresent(path.join('.cursor', 'rules', 'infra-kit.mdc'), AGENTS_MARKER_START, AGENTS_MARKER_END),
+      okMessage: '.cursor/rules/infra-kit.mdc block present',
+      missingMessage: '.cursor/rules/infra-kit.mdc block missing. Run: infra-kit init',
+    },
+  ]
+
+  return entries.map((entry): CheckResult => {
+    return {
+      name: entry.name,
+      status: entry.present ? 'pass' : 'fail',
+      message: entry.present ? entry.okMessage : entry.missingMessage,
+    }
+  })
+}
+
 /**
  * Check installation and authentication status of gh, doppler, aws, and rtk CLIs
  */
 export const doctor = async () => {
-  const checks: CheckResult[] = await Promise.all([
+  const baseChecks: CheckResult[] = await Promise.all([
     checkCommand(
       'gh installed',
       ['gh', '--version'],
@@ -251,6 +314,8 @@ export const doctor = async () => {
     checkUserOverridePath(),
   ])
 
+  const checks: CheckResult[] = [...baseChecks, ...(await checkAgentFiles())]
+
   logger.info('Doctor check results:\n')
 
   for (const check of checks) {

package/src/commands/init/__tests__/agent-files.test.ts

@@ -0,0 +1,147 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
+
+import { AGENTS_IMPORT_START, AGENTS_MARKER_END, AGENTS_MARKER_START, writeAgentFiles } from '../agent-files'
+
+vi.mock('src/lib/git-utils', () => {
+  return {
+    getProjectRoot: vi.fn(),
+    getRepoName: vi.fn(),
+  }
+})
+
+const writeFile = (filePath: string, content: string): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content, 'utf-8')
+}
+
+/** A tmp dir that is a "valid repo" (has infra-kit.json) unless `repo: false`. */
+const withTmpRepo = async (fn: (tmp: string) => Promise<void>, opts: { repo?: boolean } = {}): Promise<void> => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'infra-kit-agents-test-'))
+
+  vi.mocked(getProjectRoot).mockResolvedValue(tmp)
+  vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
+
+  if (opts.repo !== false) {
+    writeFile(path.join(tmp, 'infra-kit.json'), '{"environments":["dev"]}\n')
+  }
+
+  try {
+    await fn(tmp)
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+describe('writeAgentFiles', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('creates AGENTS.md, the CLAUDE.md import, and the .cursor rule on a fresh repo', async () => {
+    await withTmpRepo(async (tmp) => {
+      const result = await writeAgentFiles()
+
+      expect(result.skipped).toBe(false)
+      expect(result.root).toBe(tmp)
+
+      const agents = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')
+
+      expect(agents).toContain(AGENTS_MARKER_START)
+      expect(agents).toContain(AGENTS_MARKER_END)
+      expect(agents).toContain('<!-- infra-kit:version ')
+
+      const claude = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8')
+
+      expect(claude).toContain(AGENTS_IMPORT_START)
+      expect(claude).toContain('@AGENTS.md')
+
+      const cursor = fs.readFileSync(path.join(tmp, '.cursor', 'rules', 'infra-kit.mdc'), 'utf-8')
+
+      expect(cursor).toContain('alwaysApply: true')
+      expect(cursor).toContain(AGENTS_MARKER_START)
+    })
+  })
+
+  it('preserves existing hand-authored CLAUDE.md content verbatim (ticket conventions)', async () => {
+    await withTmpRepo(async (tmp) => {
+      const claudePath = path.join(tmp, 'CLAUDE.md')
+      const userContent = '# CLAUDE.md\n\n## Ticket Naming Convention\n\n- `[FE]` — frontend\n- `[BE]` — backend\n'
+
+      writeFile(claudePath, userContent)
+
+      await writeAgentFiles()
+
+      const updated = fs.readFileSync(claudePath, 'utf-8')
+
+      expect(updated).toContain('## Ticket Naming Convention')
+      expect(updated).toContain('`[FE]` — frontend')
+      expect(updated).toContain(AGENTS_IMPORT_START)
+    })
+  })
+
+  it('is idempotent — a second run does not duplicate the block', async () => {
+    await withTmpRepo(async (tmp) => {
+      await writeAgentFiles()
+      const first = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')
+
+      const second = await writeAgentFiles()
+      const after = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')
+
+      expect(after).toBe(first)
+      expect(after.match(new RegExp(AGENTS_MARKER_START, 'g'))?.length).toBe(1)
+      expect(
+        second.written.every((w) => {
+          return w.action === 'unchanged'
+        }),
+      ).toBe(true)
+    })
+  })
+
+  it('is a no-op outside an infra-kit repo (no infra-kit.json)', async () => {
+    await withTmpRepo(
+      async (tmp) => {
+        const result = await writeAgentFiles()
+
+        expect(result.skipped).toBe(true)
+        expect(result.root).toBeNull()
+        expect(fs.existsSync(path.join(tmp, 'AGENTS.md'))).toBe(false)
+      },
+      { repo: false },
+    )
+  })
+
+  it('refuses to write through a symlinked AGENTS.md', async () => {
+    await withTmpRepo(async (tmp) => {
+      const realTarget = path.join(tmp, 'elsewhere.md')
+
+      writeFile(realTarget, 'sensitive')
+      fs.symlinkSync(realTarget, path.join(tmp, 'AGENTS.md'))
+
+      await expect(writeAgentFiles()).rejects.toThrow(/symlink/)
+    })
+  })
+
+  it('backs up an existing AGENTS.md before overwriting', async () => {
+    await withTmpRepo(async (tmp) => {
+      writeFile(path.join(tmp, 'AGENTS.md'), 'previous content without markers\n')
+
+      await writeAgentFiles()
+
+      const backups = fs.readdirSync(tmp).filter((f) => {
+        return f.startsWith('AGENTS.md.backup.')
+      })
+
+      expect(backups.length).toBe(1)
+      expect(fs.readFileSync(path.join(tmp, backups[0]!), 'utf-8')).toContain('previous content without markers')
+    })
+  })
+})

package/src/commands/init/agent-files.ts

@@ -0,0 +1,199 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { getInfraKitConfigPaths } from 'src/lib/infra-kit-config'
+import { logger } from 'src/lib/logger'
+import { hasManagedBlock, upsertManagedBlock } from 'src/lib/managed-block'
+
+import packageJson from '../../../package.json' with { type: 'json' }
+
+/** Markers for the generated guidance block (HTML comments — invisible in rendered markdown). */
+export const AGENTS_MARKER_START = '<!-- infra-kit:begin -->'
+export const AGENTS_MARKER_END = '<!-- infra-kit:end -->'
+/** The version line lives on its own line (OMC `OMC:VERSION:` precedent) so the markers stay constant-matchable. */
+const AGENTS_VERSION_PREFIX = '<!-- infra-kit:version '
+
+/** Separate marker pair for the small `@AGENTS.md` import region injected into CLAUDE.md. */
+export const AGENTS_IMPORT_START = '<!-- infra-kit:import:begin -->'
+export const AGENTS_IMPORT_END = '<!-- infra-kit:import:end -->'
+
+const AGENTS_FILE = 'AGENTS.md'
+const CLAUDE_FILE = 'CLAUDE.md'
+const CURSOR_RULE_REL = path.join('.cursor', 'rules', 'infra-kit.mdc')
+
+const CURSOR_FRONTMATTER = [
+  '---',
+  'description: infra-kit CLI usage and conventions',
+  'alwaysApply: true',
+  '---',
+  '',
+].join('\n')
+
+export type WriteAction = 'created' | 'updated' | 'unchanged'
+
+export interface AgentFileWrite {
+  path: string
+  action: WriteAction
+}
+
+export interface WriteAgentFilesResult {
+  /** True when run outside an infra-kit repo (no `infra-kit.json` at the git root). */
+  skipped: boolean
+  /** Repo root the files were written under, or null when skipped. */
+  root: string | null
+  written: AgentFileWrite[]
+}
+
+/** The version comment line, e.g. `<!-- infra-kit:version 0.1.105 -->`. */
+const buildVersionLine = (version: string): string => {
+  return `${AGENTS_VERSION_PREFIX}${version} -->`
+}
+
+/**
+ * The generated guidance body (without the surrounding markers). Describes the
+ * infra-kit CLI surface so any AI agent working in the repo learns it. Curated
+ * from the real command set; the version line records which CLI version generated it.
+ */
+const buildAgentsBody = (version: string): string => {
+  return [
+    buildVersionLine(version),
+    '',
+    '# infra-kit',
+    '',
+    'This repository uses the **infra-kit** CLI for environment, worktree, and release workflows.',
+    'This block is generated by `infra-kit init` — edit text *outside* the markers, never inside.',
+    '',
+    '## Commands (`ik` = `pnpm exec infra-kit`)',
+    '',
+    '- `ik env-load -c <config>` / `ik env-clear` / `ik env-status` — load, clear, or inspect Doppler env vars for a config (e.g. `dev`). Source the returned file to apply.',
+    '- `ik worktrees-add` / `worktrees-list` / `worktrees-open` / `worktrees-remove` / `worktrees-sync` — manage release and feature git worktrees.',
+    '- `ik release-create` / `release-list` / `release-deploy-all` / `release-deploy-selected` / `release-deliver` / `release-desc-edit` — release-branch and deploy flow.',
+    '- `ik merge-dev` — merge the dev branch into every release branch.',
+    '- `ik audit` — audit packages against `infra-kit.config.ts` rules.',
+    '- `ik doctor` — check gh / doppler / aws / rtk install + auth and repo setup.',
+    '- `ik init` — (re)install shell integration and regenerate these agent-instruction files.',
+    '',
+    '## Conventions',
+    '',
+    '- Tickets are prefixed by area: `[FE]` frontend, `[BE]` backend, `[DO]` DevOps/infra, `[APP]` mobile app, `[IDEA]` proposal, `[ROOT]` cross-cutting. Pick the single dominant area.',
+    '- Environment variables are managed through Doppler via `ik env-load` — never commit secrets.',
+  ].join('\n')
+}
+
+const assertNotSymlink = (filePath: string): void => {
+  if (fs.existsSync(filePath) && fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new Error(`Refusing to write ${filePath} because the destination is a symlink`)
+  }
+}
+
+/**
+ * Write `nextContent` to `filePath` with OMC-style safety: refuse symlinks,
+ * back up the prior file with a timestamp before overwriting, and skip the
+ * write entirely when nothing changed (keeps re-runs churn-free).
+ */
+const writeManaged = (filePath: string, nextContent: string): WriteAction => {
+  assertNotSymlink(filePath)
+
+  const existed = fs.existsSync(filePath)
+  const previous = existed ? fs.readFileSync(filePath, 'utf-8') : null
+
+  if (previous === nextContent) return 'unchanged'
+
+  if (existed) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+
+    fs.copyFileSync(filePath, `${filePath}.backup.${stamp}`)
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, nextContent, 'utf-8')
+
+  return existed ? 'updated' : 'created'
+}
+
+const readOr = (filePath: string, fallback: string): string => {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : fallback
+}
+
+const assertBlockPresent = (filePath: string, start: string, end: string): void => {
+  const content = fs.readFileSync(filePath, 'utf-8')
+
+  if (!hasManagedBlock(content, start, end)) {
+    throw new Error(`Post-write validation failed: managed block missing from ${filePath}`)
+  }
+}
+
+/**
+ * Generate (or refresh) the repo agent-instruction files: the `AGENTS.md`
+ * guidance block, a managed `@AGENTS.md` import region in `CLAUDE.md`
+ * (preserving existing content), and a `.cursor/rules` rule file. Repo-gated:
+ * a no-op outside an infra-kit repo. Idempotent and non-destructive.
+ *
+ * @example
+ * await writeAgentFiles()
+ * // INFO: Agent-instruction files synced (infra-kit 0.1.105)
+ */
+export const writeAgentFiles = async (): Promise<WriteAgentFilesResult> => {
+  let mainConfigPath: string
+
+  try {
+    mainConfigPath = (await getInfraKitConfigPaths()).main
+  } catch {
+    logger.info('Skipped agent-instruction files — not inside an infra-kit repo')
+
+    return { skipped: true, root: null, written: [] }
+  }
+
+  if (!fs.existsSync(mainConfigPath)) {
+    logger.info('Skipped agent-instruction files — no infra-kit.json at the repo root')
+
+    return { skipped: true, root: null, written: [] }
+  }
+
+  const root = path.dirname(mainConfigPath)
+  const version = packageJson.version
+  const body = buildAgentsBody(version)
+
+  const agentsPath = path.join(root, AGENTS_FILE)
+  const claudePath = path.join(root, CLAUDE_FILE)
+  const cursorPath = path.join(root, CURSOR_RULE_REL)
+
+  const agentsContent = upsertManagedBlock({
+    content: readOr(agentsPath, ''),
+    body,
+    startMarker: AGENTS_MARKER_START,
+    endMarker: AGENTS_MARKER_END,
+  })
+
+  const claudeContent = upsertManagedBlock({
+    content: readOr(claudePath, ''),
+    body: `@${AGENTS_FILE}`,
+    startMarker: AGENTS_IMPORT_START,
+    endMarker: AGENTS_IMPORT_END,
+  })
+
+  const cursorContent = upsertManagedBlock({
+    content: readOr(cursorPath, CURSOR_FRONTMATTER),
+    body,
+    startMarker: AGENTS_MARKER_START,
+    endMarker: AGENTS_MARKER_END,
+  })
+
+  const written: AgentFileWrite[] = [
+    { path: agentsPath, action: writeManaged(agentsPath, agentsContent) },
+    { path: claudePath, action: writeManaged(claudePath, claudeContent) },
+    { path: cursorPath, action: writeManaged(cursorPath, cursorContent) },
+  ]
+
+  assertBlockPresent(agentsPath, AGENTS_MARKER_START, AGENTS_MARKER_END)
+  assertBlockPresent(claudePath, AGENTS_IMPORT_START, AGENTS_IMPORT_END)
+  assertBlockPresent(cursorPath, AGENTS_MARKER_START, AGENTS_MARKER_END)
+
+  for (const file of written) {
+    logger.info(`  ${file.action.padEnd(9)} ${path.relative(root, file.path)}`)
+  }
+
+  logger.info(`Agent-instruction files synced (infra-kit ${version})`)
+
+  return { skipped: false, root, written }
+}

package/src/commands/init/index.ts

@@ -1 +1,8 @@
+export {
+  AGENTS_IMPORT_END,
+  AGENTS_IMPORT_START,
+  AGENTS_MARKER_END,
+  AGENTS_MARKER_START,
+  writeAgentFiles,
+} from './agent-files'
 export { init } from './init'