infra-kit 0.1.102 → 0.1.107

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/__tests__/migrate-config.test.ts

@@ -0,0 +1,160 @@
+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 AFTER the mock is declared so the module picks up the mocked dep.
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
+
+import { migrateLegacyConfig } from '../migrate-config'
+
+vi.mock('src/lib/git-utils', () => {
+  return {
+    getProjectRoot: vi.fn(),
+    getRepoName: vi.fn(),
+  }
+})
+
+const MAIN_YML = `environments:
+  - dev
+  - staging
+envManagement:
+  provider: doppler
+  config:
+    name: my-project
+`
+
+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>): Promise<void> => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'infra-kit-init-migrate-test-'))
+
+  vi.mocked(getProjectRoot).mockResolvedValue(tmp)
+  vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
+  const homedirSpy = vi.spyOn(os, 'homedir').mockReturnValue(tmp)
+
+  try {
+    await fn(tmp)
+  } finally {
+    homedirSpy.mockRestore()
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+describe('migrateLegacyConfig', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('converts a legacy infra-kit.yml to infra-kit.json and removes the .yml', async () => {
+    await withTmpRepo(async (tmp) => {
+      const ymlPath = path.join(tmp, 'infra-kit.yml')
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+
+      writeFile(ymlPath, MAIN_YML)
+
+      await migrateLegacyConfig()
+
+      expect(fs.existsSync(ymlPath)).toBe(false)
+      expect(fs.existsSync(jsonPath)).toBe(true)
+      expect(JSON.parse(fs.readFileSync(jsonPath, 'utf-8'))).toEqual({
+        environments: ['dev', 'staging'],
+        envManagement: { provider: 'doppler', config: { name: 'my-project' } },
+      })
+    })
+  })
+
+  it('is an idempotent no-op when the config is already JSON', async () => {
+    await withTmpRepo(async (tmp) => {
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+      const json = '{"environments":["dev"],"envManagement":{"provider":"doppler","config":{"name":"p"}}}'
+
+      writeFile(jsonPath, json)
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      expect(fs.readFileSync(jsonPath, 'utf-8')).toBe(json)
+    })
+  })
+
+  it('warns and skips (does not throw or overwrite) when both .yml and .json exist', async () => {
+    await withTmpRepo(async (tmp) => {
+      const ymlPath = path.join(tmp, 'infra-kit.yml')
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+      const existingJson = '{"environments":["keep"],"envManagement":{"provider":"doppler","config":{"name":"keep"}}}'
+
+      writeFile(ymlPath, MAIN_YML)
+      writeFile(jsonPath, existingJson)
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      // Conflict left untouched — no overwrite, .yml preserved.
+      expect(fs.existsSync(ymlPath)).toBe(true)
+      expect(fs.readFileSync(jsonPath, 'utf-8')).toBe(existingJson)
+    })
+  })
+
+  it('skips an invalid layer but still converts a valid sibling layer (non-fatal, per-layer)', async () => {
+    await withTmpRepo(async (tmp) => {
+      const mainYml = path.join(tmp, 'infra-kit.yml')
+      const mainJson = path.join(tmp, 'infra-kit.json')
+      const userGlobalYml = path.join(tmp, '.infra-kit', 'config.yml')
+      const userGlobalJson = path.join(tmp, '.infra-kit', 'config.json')
+
+      writeFile(mainYml, MAIN_YML)
+      // Invalid override: environments present but empty (min(1) fails).
+      writeFile(userGlobalYml, 'environments: []\n')
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      // Valid main layer converted…
+      expect(fs.existsSync(mainYml)).toBe(false)
+      expect(fs.existsSync(mainJson)).toBe(true)
+      // …invalid user-global layer left as-is (no JSON written).
+      expect(fs.existsSync(userGlobalYml)).toBe(true)
+      expect(fs.existsSync(userGlobalJson)).toBe(false)
+    })
+  })
+
+  it('warns and skips a malformed .yml without throwing', async () => {
+    await withTmpRepo(async (tmp) => {
+      const ymlPath = path.join(tmp, 'infra-kit.yml')
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+
+      // Unparseable YAML (bad indentation / flow) — yaml.parse throws.
+      writeFile(ymlPath, 'environments: [dev\n  : : :\n')
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      expect(fs.existsSync(ymlPath)).toBe(true)
+      expect(fs.existsSync(jsonPath)).toBe(false)
+    })
+  })
+
+  it('converts all three merge-chain layers in one run', async () => {
+    await withTmpRepo(async (tmp) => {
+      const projectName = path.basename(tmp)
+      const mainYml = path.join(tmp, 'infra-kit.yml')
+      const userGlobalYml = path.join(tmp, '.infra-kit', 'config.yml')
+      const userProjectYml = path.join(tmp, '.infra-kit', 'projects', projectName, 'infra-kit.yml')
+
+      writeFile(mainYml, MAIN_YML)
+      writeFile(userGlobalYml, 'worktrees:\n  openInCmux: true\n')
+      writeFile(userProjectYml, 'worktrees:\n  openInGithubDesktop: false\n')
+
+      await migrateLegacyConfig()
+
+      for (const yml of [mainYml, userGlobalYml, userProjectYml]) {
+        expect(fs.existsSync(yml)).toBe(false)
+        expect(fs.existsSync(yml.replace(/\.yml$/, '.json'))).toBe(true)
+      }
+    })
+  })
+})

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'