infra-kit 0.1.105 → 0.1.107

package/src/commands/init/init.ts

@@ -3,7 +3,9 @@ import os from 'node:os'
 import path from 'node:path'
 
 import { logger } from 'src/lib/logger'
+import { removeManagedBlock, upsertManagedBlock } from 'src/lib/managed-block'
 
+import { writeAgentFiles } from './agent-files'
 import { migrateLegacyConfig } from './migrate-config'
 
 export const MARKER_START = '# -- infra-kit:begin --'
@@ -55,16 +57,22 @@ const USER_GLOBAL_CONFIG_EXAMPLE = `// infra-kit user-global config — ~/.infra
  */
 export const init = async (): Promise<void> => {
   const zshrcPath = path.join(os.homedir(), '.zshrc')
-  const shellBlock = buildShellBlock()
 
-  if (fs.existsSync(zshrcPath)) {
-    const content = fs.readFileSync(zshrcPath, 'utf-8')
-    const cleaned = removeExistingBlock(content)
+  // Strip any prior block (current or legacy markers) anywhere in the file, then
+  // append a fresh block at end-of-file via the shared managed-block utility —
+  // the historical `removeExistingBlock` + append behavior, now centralized.
+  const existing = fs.existsSync(zshrcPath) ? removeExistingBlock(fs.readFileSync(zshrcPath, 'utf-8')) : ''
 
-    fs.writeFileSync(zshrcPath, cleaned)
-  }
+  const updated = upsertManagedBlock({
+    content: existing,
+    body: buildShellBody(),
+    startMarker: MARKER_START,
+    endMarker: MARKER_END,
+    placement: 'append-end',
+  })
+
+  fs.writeFileSync(zshrcPath, updated)
 
-  fs.appendFileSync(zshrcPath, `\n${shellBlock}\n`)
   logger.info(`Added infra-kit shell functions to ${zshrcPath}`)
 
   // Convert any legacy infra-kit.yml config layers to JSON before seeding, so a
@@ -73,6 +81,10 @@ export const init = async (): Promise<void> => {
 
   seedUserGlobalConfig()
 
+  // Best-effort, non-fatal, repo-gated: keep the agent-instruction files in sync
+  // with the CLI surface. A no-op outside an infra-kit repo.
+  await writeAgentFiles()
+
   logger.info('Run `source ~/.zshrc` or open a new terminal to activate.')
 }
 
@@ -125,28 +137,15 @@ const isBlockLine = (line: string): boolean => {
   )
 }
 
-const removeBetween = (content: string, start: string, end: string): string | null => {
-  const startIdx = content.indexOf(start)
-  const endIdx = content.indexOf(end)
-
-  if (startIdx === -1 || endIdx === -1) return null
-
-  // eslint-disable-next-line sonarjs/slow-regex
-  const before = content.slice(0, startIdx).replace(/\n+$/, '')
-  const after = content.slice(endIdx + end.length).replace(/^\n+/, '')
-
-  return before + (after ? `\n${after}` : '')
-}
-
 const removeExistingBlock = (content: string): string => {
   // 1. Current markers
-  const result = removeBetween(content, MARKER_START, MARKER_END)
+  const result = removeManagedBlock(content, MARKER_START, MARKER_END)
 
   if (result !== null) return result
 
   // 2. Legacy paired markers (# region / # endregion)
   for (const [start, end] of LEGACY_PAIRED) {
-    const legacyResult = removeBetween(content, start, end)
+    const legacyResult = removeManagedBlock(content, start, end)
 
     if (legacyResult !== null) return legacyResult
   }
@@ -171,11 +170,14 @@ const removeExistingBlock = (content: string): string => {
   return before + (remaining ? `\n${remaining}` : '')
 }
 
-export const buildShellBlock = (): string => {
+/**
+ * The inner shell-function lines (no markers). Composed into the full marked
+ * block by {@link buildShellBlock} and fed to `upsertManagedBlock` by `init()`.
+ */
+export const buildShellBody = (): string => {
   const runCmd = 'pnpm exec infra-kit'
 
   return [
-    MARKER_START,
     'zmodload zsh/stat 2>/dev/null',
     'zmodload zsh/datetime 2>/dev/null',
     // eslint-disable-next-line no-template-curly-in-string
@@ -223,6 +225,13 @@ export const buildShellBlock = (): string => {
     'if (( _INFRA_KIT_SHELL_STARTED > 0 )); then',
     '  add-zsh-hook precmd _infra_kit_autoload',
     'fi',
-    MARKER_END,
   ].join('\n')
 }
+
+/**
+ * The full marker-delimited shell block (`MARKER_START … MARKER_END`). Kept as
+ * a single composed string so `doctor`'s exact-match freshness check stays valid.
+ */
+export const buildShellBlock = (): string => {
+  return `${MARKER_START}\n${buildShellBody()}\n${MARKER_END}`
+}

package/src/entry/cli.ts

@@ -286,7 +286,7 @@ program
 
 program
   .command('init')
-  .description('Inject shell integration into your profile .zshrc')
+  .description('Inject shell integration into .zshrc and sync repo agent-instruction files')
   .action(async () => {
     await init()
   })

package/src/integrations/cmux/open-workspace-with-layout.ts

@@ -26,7 +26,7 @@ export const openCmuxWorkspaceWithLayout = async (args: OpenCmuxWorkspaceArgs):
   await $`cmux new-split down --workspace ${workspaceRef} --surface ${leftTopRef}`
 
   if (title) {
-    await $`cmux workspace rename --workspace ${workspaceRef} ${title}`
+    await $`cmux workspace rename --workspace ${workspaceRef} --title ${title}`
   }
 }
 

package/src/lib/managed-block/__tests__/managed-block.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+
+import { extractVersion, hasManagedBlock, removeManagedBlock, upsertManagedBlock } from '../managed-block'
+
+const START = '<!-- ik:begin -->'
+const END = '<!-- ik:end -->'
+
+describe('hasManagedBlock', () => {
+  it('detects a well-formed block', () => {
+    expect(hasManagedBlock(`x ${START} y ${END} z`, START, END)).toBe(true)
+  })
+
+  it('returns false when a marker is missing', () => {
+    expect(hasManagedBlock(`only ${START} here`, START, END)).toBe(false)
+  })
+
+  it('treats reversed markers (end before start) as absent', () => {
+    expect(hasManagedBlock(`${END} middle ${START}`, START, END)).toBe(false)
+  })
+})
+
+describe('removeManagedBlock', () => {
+  it('removes the block and preserves surrounding text', () => {
+    const content = `top\n${START}\nmid\n${END}\nbot`
+
+    expect(removeManagedBlock(content, START, END)).toBe('top\nbot')
+  })
+
+  it('returns null when no block is present', () => {
+    expect(removeManagedBlock('nothing here', START, END)).toBeNull()
+  })
+
+  it('returns null for reversed markers (guard)', () => {
+    expect(removeManagedBlock(`${END}\nx\n${START}`, START, END)).toBeNull()
+  })
+})
+
+describe('extractVersion', () => {
+  const PREFIX = '<!-- ik:version '
+
+  it('reads the version token after the prefix', () => {
+    expect(extractVersion('<!-- ik:version 0.1.105 -->', PREFIX)).toBe('0.1.105')
+  })
+
+  it('returns null when the prefix is absent', () => {
+    expect(extractVersion('no version here', PREFIX)).toBeNull()
+  })
+})
+
+describe('upsertManagedBlock', () => {
+  it('inserts into an empty file (replace-in-place default)', () => {
+    const result = upsertManagedBlock({ content: '', body: 'hello', startMarker: START, endMarker: END })
+
+    expect(result).toBe(`${START}\nhello\n${END}\n`)
+  })
+
+  it('inserts into an empty file (append-end)', () => {
+    const result = upsertManagedBlock({
+      content: '',
+      body: 'hello',
+      startMarker: START,
+      endMarker: END,
+      placement: 'append-end',
+    })
+
+    expect(result).toBe(`${START}\nhello\n${END}\n`)
+  })
+
+  it('replaces an existing block in place, keeping surrounding content verbatim', () => {
+    const content = `# top heading\n\n${START}\nold body\n${END}\n\n# bottom heading\n`
+    const result = upsertManagedBlock({ content, body: 'new body', startMarker: START, endMarker: END })
+
+    expect(result).toBe(`# top heading\n\n${START}\nnew body\n${END}\n\n# bottom heading\n`)
+  })
+
+  it('append-end relocates an existing mid-file block to end-of-file', () => {
+    const content = `intro\n\n${START}\nold\n${END}\n\nuser tail`
+    const result = upsertManagedBlock({
+      content,
+      body: 'fresh',
+      startMarker: START,
+      endMarker: END,
+      placement: 'append-end',
+    })
+
+    expect(result).toBe(`intro\nuser tail\n${START}\nfresh\n${END}\n`)
+  })
+
+  it('append-end lands the block at end-of-file when absent', () => {
+    const content = 'existing user content'
+    const result = upsertManagedBlock({
+      content,
+      body: 'b',
+      startMarker: START,
+      endMarker: END,
+      placement: 'append-end',
+    })
+
+    expect(result.endsWith(`${START}\nb\n${END}\n`)).toBe(true)
+    expect(result.startsWith('existing user content')).toBe(true)
+  })
+
+  it('is idempotent — re-running does not nest or duplicate blocks', () => {
+    const once = upsertManagedBlock({ content: 'pre\n', body: 'b', startMarker: START, endMarker: END })
+    const twice = upsertManagedBlock({ content: once, body: 'b', startMarker: START, endMarker: END })
+
+    expect(twice).toBe(once)
+    expect(twice.match(new RegExp(START, 'g'))?.length).toBe(1)
+  })
+
+  it('preserves content above and below across an update', () => {
+    const first = upsertManagedBlock({ content: 'ABOVE\n', body: 'v1', startMarker: START, endMarker: END })
+    const withTail = `${first}BELOW\n`
+    const updated = upsertManagedBlock({ content: withTail, body: 'v2', startMarker: START, endMarker: END })
+
+    expect(updated).toContain('ABOVE')
+    expect(updated).toContain('BELOW')
+    expect(updated).toContain('v2')
+    expect(updated).not.toContain('v1')
+  })
+})

package/src/lib/managed-block/index.ts

@@ -0,0 +1,8 @@
+export {
+  buildManagedBlock,
+  extractVersion,
+  hasManagedBlock,
+  removeManagedBlock,
+  upsertManagedBlock,
+} from './managed-block'
+export type { BlockPlacement, UpsertManagedBlockArgs } from './managed-block'

package/src/lib/managed-block/managed-block.ts

@@ -0,0 +1,145 @@
+/**
+ * Generic "managed block" helpers — a marker-delimited region a tool owns and
+ * rewrites idempotently while never touching content outside the markers.
+ *
+ * This is the same mechanism `infra-kit init` already uses for the `~/.zshrc`
+ * shell block (`# -- infra-kit:begin -- … # -- infra-kit:end --`), lifted here so
+ * it can be reused for the repo agent-instruction files (`AGENTS.md`,
+ * `CLAUDE.md` import region, `.cursor/rules`). It mirrors the design of OMC's
+ * `<!-- OMC:START --> … <!-- OMC:END -->` CLAUDE.md installer.
+ */
+
+/**
+ * Where a freshly upserted block lands relative to existing content.
+ *
+ * - `replace-in-place`: if the block already exists, rewrite it where it sits
+ *   (surrounding text untouched, verbatim); if absent, append it at end-of-file.
+ * - `append-end`: strip any existing block from wherever it is, then append the
+ *   fresh block at end-of-file (i.e. always relocate to the end). This preserves
+ *   the historical `~/.zshrc` behavior of `removeExistingBlock` + append.
+ */
+export type BlockPlacement = 'replace-in-place' | 'append-end'
+
+export interface UpsertManagedBlockArgs {
+  /** Existing file content (`''` for a new file). */
+  content: string
+  /** Inner body to place between the markers (WITHOUT the markers). */
+  body: string
+  startMarker: string
+  endMarker: string
+  /** Defaults to `replace-in-place`. */
+  placement?: BlockPlacement
+}
+
+/**
+ * Whether `content` contains a well-formed `start … end` block. A reversed pair
+ * (end before start) is treated as absent — the same guard `doctor.ts` applies
+ * to the zshrc block, ported here so corrupted markers never match.
+ *
+ * @example
+ * hasManagedBlock('a<!--s-->x<!--e-->b', '<!--s-->', '<!--e-->') // => true
+ * hasManagedBlock('<!--e--><!--s-->', '<!--s-->', '<!--e-->')    // => false (reversed)
+ */
+export const hasManagedBlock = (content: string, startMarker: string, endMarker: string): boolean => {
+  const startIdx = content.indexOf(startMarker)
+  const endIdx = content.indexOf(endMarker)
+
+  return startIdx !== -1 && endIdx !== -1 && endIdx >= startIdx
+}
+
+/**
+ * Remove the first complete `start … end` block, preserving surrounding text.
+ * Returns `null` when no well-formed block is present (no markers, or reversed),
+ * so callers can fall through to legacy-format handling — this matches the
+ * `string | null` contract of `init.ts`'s original `removeBetween`, with the
+ * added reversed-marker guard.
+ *
+ * @example
+ * removeManagedBlock('top\n<!--s-->mid<!--e-->\nbot', '<!--s-->', '<!--e-->')
+ * // => 'top\nbot'
+ */
+export const removeManagedBlock = (content: string, startMarker: string, endMarker: string): string | null => {
+  const startIdx = content.indexOf(startMarker)
+  const endIdx = content.indexOf(endMarker)
+
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null
+
+  // eslint-disable-next-line sonarjs/slow-regex
+  const before = content.slice(0, startIdx).replace(/\n+$/, '')
+  const after = content.slice(endIdx + endMarker.length).replace(/^\n+/, '')
+
+  return before + (after ? `\n${after}` : '')
+}
+
+/**
+ * Read the version token that follows `versionPrefix` (e.g.
+ * `'<!-- infra-kit:version '`). Returns the token up to the next whitespace or
+ * `>`, or `null` if the prefix is absent. Mirrors OMC's `OMC:VERSION:` line.
+ *
+ * @example
+ * extractVersion('<!-- infra-kit:version 0.1.105 -->', '<!-- infra-kit:version ')
+ * // => '0.1.105'
+ */
+export const extractVersion = (content: string, versionPrefix: string): string | null => {
+  const idx = content.indexOf(versionPrefix)
+
+  if (idx === -1) return null
+
+  const rest = content.slice(idx + versionPrefix.length)
+  const match = rest.match(/^([^\s>]+)/)
+
+  return match ? match[1]! : null
+}
+
+/**
+ * Compose a full block string: `start\n{body}\nend`. Kept identical in shape to
+ * the historical `buildShellBlock()` output so doctor's exact-match comparison
+ * stays valid.
+ */
+export const buildManagedBlock = (startMarker: string, body: string, endMarker: string): string => {
+  return `${startMarker}\n${body}\n${endMarker}`
+}
+
+/**
+ * Insert or update a managed block in `content`, preserving everything outside
+ * the markers. Idempotent: re-running with the same body yields the same block
+ * and never nests duplicates.
+ *
+ * @example
+ * // fresh file
+ * upsertManagedBlock({ content: '', body: 'hi', startMarker: '<!--s-->', endMarker: '<!--e-->' })
+ * // => '<!--s-->\nhi\n<!--e-->\n'
+ *
+ * @example
+ * // existing block replaced in place, surrounding text kept
+ * upsertManagedBlock({
+ *   content: 'top\n<!--s-->\nold\n<!--e-->\nbot',
+ *   body: 'new', startMarker: '<!--s-->', endMarker: '<!--e-->',
+ * })
+ * // => 'top\n<!--s-->\nnew\n<!--e-->\nbot'
+ */
+export const upsertManagedBlock = ({
+  content,
+  body,
+  startMarker,
+  endMarker,
+  placement = 'replace-in-place',
+}: UpsertManagedBlockArgs): string => {
+  const block = buildManagedBlock(startMarker, body, endMarker)
+  const present = hasManagedBlock(content, startMarker, endMarker)
+
+  if (placement === 'replace-in-place' && present) {
+    const startIdx = content.indexOf(startMarker)
+    const endIdx = content.indexOf(endMarker) + endMarker.length
+
+    return content.slice(0, startIdx) + block + content.slice(endIdx)
+  }
+
+  // append-end, or replace-in-place with no existing block: drop any stale block
+  // then append the fresh one at end-of-file.
+  const stripped = present ? (removeManagedBlock(content, startMarker, endMarker) ?? content) : content
+  // eslint-disable-next-line sonarjs/slow-regex
+  const base = stripped.replace(/\n+$/, '')
+
+  return base.length > 0 ? `${base}\n${block}\n` : `${block}\n`
+}