@open-mercato/cli 0.6.7-develop.6685.1.77c0a5591b → 0.6.7-develop.6687.1.46a258e592

package/src/lib/__tests__/agentic-setup.ownership.test.ts

@@ -0,0 +1,380 @@
+import { createHash } from 'node:crypto'
+import {
+  mkdtempSync,
+  mkdirSync,
+  readdirSync,
+  existsSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { applyHarnessUpdate, runAgenticSetup } from '../agentic-setup'
+
+type ManifestEntry = {
+  path: string
+  sha256: string
+  source: string
+  userEditable: boolean
+}
+
+function write(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, content)
+}
+
+function hash(content: string): string {
+  return createHash('sha256').update(content).digest('hex')
+}
+
+function entry(path: string, content: string): ManifestEntry {
+  return {
+    path,
+    sha256: hash(content),
+    source: 'generated',
+    userEditable: false,
+  }
+}
+
+function writeManifest(root: string, files: ManifestEntry[]): string {
+  const path = join(root, '.ai', 'harness', 'manifest.json')
+  write(
+    path,
+    `${JSON.stringify({ version: 1, generator: 'open-mercato-agentic', files }, null, 2)}\n`,
+  )
+  return path
+}
+
+describe('applyHarnessUpdate', () => {
+  let tempRoot: string
+  let targetDir: string
+  let stagingDir: string
+
+  beforeEach(() => {
+    tempRoot = mkdtempSync(join(tmpdir(), 'agentic-ownership-'))
+    targetDir = join(tempRoot, 'app')
+    stagingDir = join(tempRoot, 'candidate')
+    mkdirSync(targetDir, { recursive: true })
+    mkdirSync(stagingDir, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('updates unchanged owned files while preserving modified and unknown files', () => {
+    const oldUnchanged = 'old generated content\n'
+    const oldExpectedModified = 'old generated editable content\n'
+    const userModified = 'user customization\n'
+    const unknownUserContent = 'private local skill\n'
+    const oldMissing = 'previously generated then deleted\n'
+
+    write(join(targetDir, '.ai', 'owned-unchanged.md'), oldUnchanged)
+    write(join(targetDir, '.ai', 'owned-modified.md'), userModified)
+    write(join(targetDir, '.ai', 'unknown-collision.md'), unknownUserContent)
+    write(join(targetDir, '.ai', 'skills', 'custom-local', 'SKILL.md'), 'keep me\n')
+    writeManifest(targetDir, [
+      entry('.ai/owned-unchanged.md', oldUnchanged),
+      entry('.ai/owned-modified.md', oldExpectedModified),
+      entry('.ai/missing-owned.md', oldMissing),
+    ])
+
+    const nextFiles = new Map<string, string>([
+      ['.ai/owned-unchanged.md', 'new generated content\n'],
+      ['.ai/owned-modified.md', 'new generated editable content\n'],
+      ['.ai/unknown-collision.md', 'new generated collision\n'],
+      ['.ai/missing-owned.md', 'recreated generated content\n'],
+    ])
+    for (const [relativePath, content] of nextFiles) {
+      write(join(stagingDir, relativePath), content)
+    }
+    writeManifest(
+      stagingDir,
+      [...nextFiles].map(([relativePath, content]) => entry(relativePath, content)),
+    )
+
+    const conflicts = applyHarnessUpdate(targetDir, stagingDir)
+
+    expect(conflicts).toEqual([
+      { path: '.ai/owned-modified.md', candidate: '.ai/owned-modified.md.incoming' },
+      { path: '.ai/unknown-collision.md', candidate: '.ai/unknown-collision.md.incoming' },
+    ])
+    expect(readFileSync(join(targetDir, '.ai', 'owned-unchanged.md'), 'utf8')).toBe(
+      nextFiles.get('.ai/owned-unchanged.md'),
+    )
+    expect(readFileSync(join(targetDir, '.ai', 'owned-modified.md'), 'utf8')).toBe(userModified)
+    expect(readFileSync(join(targetDir, '.ai', 'owned-modified.md.incoming'), 'utf8')).toBe(
+      nextFiles.get('.ai/owned-modified.md'),
+    )
+    expect(readFileSync(join(targetDir, '.ai', 'unknown-collision.md'), 'utf8')).toBe(
+      unknownUserContent,
+    )
+    expect(readFileSync(join(targetDir, '.ai', 'unknown-collision.md.incoming'), 'utf8')).toBe(
+      nextFiles.get('.ai/unknown-collision.md'),
+    )
+    expect(readFileSync(join(targetDir, '.ai', 'missing-owned.md'), 'utf8')).toBe(
+      nextFiles.get('.ai/missing-owned.md'),
+    )
+    expect(readFileSync(join(targetDir, '.ai', 'skills', 'custom-local', 'SKILL.md'), 'utf8')).toBe(
+      'keep me\n',
+    )
+    expect(readFileSync(join(targetDir, '.ai', 'harness', 'manifest.json'), 'utf8')).toBe(
+      readFileSync(join(stagingDir, '.ai', 'harness', 'manifest.json'), 'utf8'),
+    )
+  })
+
+  it('never overwrites a user-edited incoming candidate on a later update', () => {
+    const userFile = 'user-owned harness\n'
+    const firstCandidate = 'first generated candidate\n'
+    const secondCandidate = 'second generated candidate\n'
+    write(join(targetDir, '.ai', 'owned.md'), userFile)
+    writeManifest(targetDir, [entry('.ai/owned.md', 'original generated file\n')])
+    write(join(stagingDir, '.ai', 'owned.md'), firstCandidate)
+    writeManifest(stagingDir, [entry('.ai/owned.md', firstCandidate)])
+
+    expect(applyHarnessUpdate(targetDir, stagingDir)).toEqual([
+      { path: '.ai/owned.md', candidate: '.ai/owned.md.incoming' },
+    ])
+    write(join(targetDir, '.ai', 'owned.md.incoming'), 'user edited the candidate\n')
+    write(join(stagingDir, '.ai', 'owned.md'), secondCandidate)
+    writeManifest(stagingDir, [entry('.ai/owned.md', secondCandidate)])
+
+    expect(applyHarnessUpdate(targetDir, stagingDir)).toEqual([
+      { path: '.ai/owned.md', candidate: '.ai/owned.md.incoming.2' },
+    ])
+    expect(readFileSync(join(targetDir, '.ai', 'owned.md'), 'utf8')).toBe(userFile)
+    expect(readFileSync(join(targetDir, '.ai', 'owned.md.incoming'), 'utf8')).toBe('user edited the candidate\n')
+    expect(readFileSync(join(targetDir, '.ai', 'owned.md.incoming.2'), 'utf8')).toBe(secondCandidate)
+  })
+
+  it('removes retired owned files but preserves modified retired assets with ownership', () => {
+    const unchanged = '.claude/generated.json'
+    const modified = 'CLAUDE.md'
+    write(join(targetDir, unchanged), 'old generated setting\n')
+    write(join(targetDir, modified), 'locally edited instructions\n')
+    writeManifest(targetDir, [
+      entry(unchanged, 'old generated setting\n'),
+      entry(modified, 'old generated instructions\n'),
+    ])
+    writeManifest(stagingDir, [])
+
+    expect(applyHarnessUpdate(targetDir, stagingDir)).toEqual([
+      { path: modified, candidate: null },
+    ])
+    expect(existsSync(join(targetDir, unchanged))).toBe(false)
+    expect(readFileSync(join(targetDir, modified), 'utf8')).toBe('locally edited instructions\n')
+    const manifest = JSON.parse(readFileSync(join(targetDir, '.ai', 'harness', 'manifest.json'), 'utf8')) as {
+      files: ManifestEntry[]
+    }
+    expect(manifest.files.map((item) => item.path)).toEqual([modified])
+  })
+
+  it('leaves the prior manifest and app files untouched when candidate validation fails', () => {
+    write(join(targetDir, '.ai', 'owned.md'), 'old\n')
+    const oldManifestPath = writeManifest(targetDir, [entry('.ai/owned.md', 'old\n')])
+    const oldManifest = readFileSync(oldManifestPath, 'utf8')
+    writeManifest(stagingDir, [entry('.ai/missing-candidate.md', 'not written\n')])
+
+    expect(() => applyHarnessUpdate(targetDir, stagingDir)).toThrow(
+      'Generated harness candidate is invalid for ".ai/missing-candidate.md".',
+    )
+    expect(readFileSync(join(targetDir, '.ai', 'owned.md'), 'utf8')).toBe('old\n')
+    expect(readFileSync(oldManifestPath, 'utf8')).toBe(oldManifest)
+  })
+
+  it('rejects manifest paths that escape the app root before publishing', () => {
+    const oldManifestPath = writeManifest(targetDir, [])
+    const oldManifest = readFileSync(oldManifestPath, 'utf8')
+    writeManifest(stagingDir, [entry('../escape.md', 'escape\n')])
+
+    expect(() => applyHarnessUpdate(targetDir, stagingDir)).toThrow(
+      'Generated harness candidate is invalid for "../escape.md".',
+    )
+    expect(readFileSync(oldManifestPath, 'utf8')).toBe(oldManifest)
+  })
+
+  it('rejects a symlinked managed ancestor without writing outside the app', () => {
+    if (process.platform === 'win32') return
+    const outsideDir = join(tempRoot, 'outside')
+    mkdirSync(join(outsideDir, 'harness'), { recursive: true })
+    write(join(outsideDir, 'sentinel.txt'), 'outside sentinel\n')
+    write(
+      join(outsideDir, 'harness', 'manifest.json'),
+      `${JSON.stringify({ version: 1, generator: 'outside', files: [] }, null, 2)}\n`,
+    )
+    const nextContent = 'must stay inside the app\n'
+    write(join(stagingDir, '.ai', 'owned.md'), nextContent)
+    writeManifest(stagingDir, [entry('.ai/owned.md', nextContent)])
+    symlinkSync(outsideDir, join(targetDir, '.ai'), 'dir')
+
+    expect(() => applyHarnessUpdate(targetDir, stagingDir)).toThrow(
+      'Harness-managed path contains a symbolic-link component',
+    )
+    expect(readFileSync(join(outsideDir, 'sentinel.txt'), 'utf8')).toBe('outside sentinel\n')
+    expect(existsSync(join(outsideDir, 'owned.md'))).toBe(false)
+    expect(readdirSync(outsideDir).sort()).toEqual(['harness', 'sentinel.txt'])
+  })
+})
+
+describe('runAgenticSetup ownership modes', () => {
+  let appDir: string
+  let previousSkipExternal: string | undefined
+
+  beforeEach(() => {
+    appDir = mkdtempSync(join(tmpdir(), 'agentic-setup-app-'))
+    write(
+      join(appDir, 'src', 'modules.ts'),
+      "export const enabledModules: Array<{ id: string }> = []\n",
+    )
+    previousSkipExternal = process.env.OM_SKIP_EXTERNAL_SKILLS
+    process.env.OM_SKIP_EXTERNAL_SKILLS = '1'
+    jest.spyOn(console, 'log').mockImplementation()
+    jest.spyOn(console, 'warn').mockImplementation()
+  })
+
+  afterEach(() => {
+    if (previousSkipExternal === undefined) delete process.env.OM_SKIP_EXTERNAL_SKILLS
+    else process.env.OM_SKIP_EXTERNAL_SKILLS = previousSkipExternal
+    jest.restoreAllMocks()
+    rmSync(appDir, { recursive: true, force: true })
+  })
+
+  it('preserves local edits, recreates missing owned files, and reports incoming candidates', async () => {
+    const ask = async () => ''
+    await runAgenticSetup(appDir, ask, { tool: 'codex' })
+    const originalGuide = readFileSync(join(appDir, '.ai', 'guides', 'architecture.md'), 'utf8')
+    write(join(appDir, 'AGENTS.md'), '# My local harness rules\n')
+    write(join(appDir, '.ai', 'skills', 'my-private-skill', 'SKILL.md'), '# Private\n')
+    rmSync(join(appDir, '.ai', 'guides', 'architecture.md'))
+
+    await runAgenticSetup(appDir, ask, { tool: 'codex', updateHarness: true })
+
+    expect(readFileSync(join(appDir, 'AGENTS.md'), 'utf8')).toBe('# My local harness rules\n')
+    expect(readFileSync(join(appDir, 'AGENTS.md.incoming'), 'utf8')).toContain(
+      '<!-- CODEX_ENFORCEMENT_RULES_START -->',
+    )
+    expect(readFileSync(join(appDir, '.ai', 'guides', 'architecture.md'), 'utf8')).toBe(originalGuide)
+    expect(readFileSync(join(appDir, '.ai', 'skills', 'my-private-skill', 'SKILL.md'), 'utf8')).toBe(
+      '# Private\n',
+    )
+    expect(existsSync(join(appDir, '.ai', 'harness', 'manifest.json'))).toBe(true)
+    if (process.platform !== 'win32') {
+      expect(statSync(join(appDir, 'scripts', 'install-skills.sh')).mode & 0o111).not.toBe(0)
+    }
+  })
+
+  it('keeps force semantics by replacing exact generated targets', async () => {
+    const ask = async () => ''
+    await runAgenticSetup(appDir, ask, { tool: 'codex' })
+    write(join(appDir, 'AGENTS.md'), '# My local harness rules\n')
+
+    await runAgenticSetup(appDir, ask, { tool: 'codex', force: true })
+
+    expect(readFileSync(join(appDir, 'AGENTS.md'), 'utf8')).toContain(
+      '<!-- CODEX_ENFORCEMENT_RULES_START -->',
+    )
+    expect(existsSync(join(appDir, 'AGENTS.md.incoming'))).toBe(false)
+  })
+
+  it.each([
+    ['top-level .ai', '.ai'],
+    ['top-level scripts', 'scripts'],
+    ['nested guides', join('.ai', 'guides')],
+  ])('rejects a symlinked %s destination on initial setup before writing outside the app', async (_label, linkedRelative) => {
+    if (process.platform === 'win32') return
+    const targetDir = join(appDir, linkedRelative.replaceAll('/', '-'))
+    const outsideDir = join(appDir, `outside-initial-${linkedRelative.replaceAll('/', '-')}`)
+    write(
+      join(targetDir, 'src', 'modules.ts'),
+      "export const enabledModules: Array<{ id: string }> = []\n",
+    )
+    write(join(outsideDir, 'sentinel.txt'), 'outside sentinel\n')
+    const linkedPath = join(targetDir, linkedRelative)
+    mkdirSync(dirname(linkedPath), { recursive: true })
+    symlinkSync(outsideDir, linkedPath, 'dir')
+
+    await expect(runAgenticSetup(targetDir, async () => '', { tool: 'codex' })).rejects.toThrow(
+      'Harness-managed path contains a symbolic-link component',
+    )
+    expect(readFileSync(join(outsideDir, 'sentinel.txt'), 'utf8')).toBe('outside sentinel\n')
+    expect(readdirSync(outsideDir)).toEqual(['sentinel.txt'])
+    expect(existsSync(join(targetDir, 'AGENTS.md'))).toBe(false)
+  })
+
+  it.each([
+    ['top-level .ai', '.ai'],
+    ['top-level scripts', 'scripts'],
+    ['nested guides', join('.ai', 'guides')],
+  ])('rejects a symlinked %s destination on forced setup before writing outside the app', async (_label, linkedRelative) => {
+    if (process.platform === 'win32') return
+    const targetDir = join(appDir, `force-${linkedRelative.replaceAll('/', '-')}`)
+    const outsideDir = join(appDir, `outside-force-${linkedRelative.replaceAll('/', '-')}`)
+    write(
+      join(targetDir, 'src', 'modules.ts'),
+      "export const enabledModules: Array<{ id: string }> = []\n",
+    )
+    await runAgenticSetup(targetDir, async () => '', { tool: 'codex' })
+    const originalAgents = readFileSync(join(targetDir, 'AGENTS.md'), 'utf8')
+    write(join(outsideDir, 'sentinel.txt'), 'outside sentinel\n')
+    const linkedPath = join(targetDir, linkedRelative)
+    rmSync(linkedPath, { recursive: true, force: true })
+    mkdirSync(dirname(linkedPath), { recursive: true })
+    symlinkSync(outsideDir, linkedPath, 'dir')
+
+    await expect(
+      runAgenticSetup(targetDir, async () => '', { tool: 'codex', force: true }),
+    ).rejects.toThrow('Harness-managed path contains a symbolic-link component')
+    expect(readFileSync(join(outsideDir, 'sentinel.txt'), 'utf8')).toBe('outside sentinel\n')
+    expect(readdirSync(outsideDir)).toEqual(['sentinel.txt'])
+    expect(readFileSync(join(targetDir, 'AGENTS.md'), 'utf8')).toBe(originalAgents)
+  })
+
+  it('updates the harness without crashing when src/modules.ts is missing', async () => {
+    rmSync(join(appDir, 'src', 'modules.ts'))
+
+    await expect(runAgenticSetup(appDir, async () => '', {
+      tool: 'codex',
+      updateHarness: true,
+    })).resolves.toBeUndefined()
+
+    expect(existsSync(join(appDir, 'src', 'modules.ts'))).toBe(false)
+    expect(existsSync(join(appDir, '.ai', 'harness', 'manifest.json'))).toBe(true)
+  })
+
+  it('removes unmodified tool-specific assets when switching tools', async () => {
+    const ask = async () => ''
+    await runAgenticSetup(appDir, ask, { tool: 'claude-code' })
+    expect(existsSync(join(appDir, 'CLAUDE.md'))).toBe(true)
+    expect(existsSync(join(appDir, '.claude', 'settings.json'))).toBe(true)
+
+    await runAgenticSetup(appDir, ask, { tool: 'codex', updateHarness: true })
+
+    expect(existsSync(join(appDir, 'CLAUDE.md'))).toBe(false)
+    expect(existsSync(join(appDir, '.claude', 'settings.json'))).toBe(false)
+    expect(existsSync(join(appDir, '.codex', 'mcp.json.example'))).toBe(true)
+  })
+
+  it('preserves the persisted tool selection on a bare harness update without prompting', async () => {
+    const initialAsk = async () => ''
+    await runAgenticSetup(appDir, initialAsk, { tool: 'claude-code,codex' })
+    const ask = jest.fn(async () => {
+      throw new Error('bare update must not prompt for a new tool selection')
+    })
+
+    await runAgenticSetup(appDir, ask, { updateHarness: true })
+
+    expect(ask).not.toHaveBeenCalled()
+    expect(existsSync(join(appDir, 'CLAUDE.md'))).toBe(true)
+    expect(existsSync(join(appDir, '.claude', 'settings.json'))).toBe(true)
+    expect(existsSync(join(appDir, '.codex', 'mcp.json.example'))).toBe(true)
+    expect(existsSync(join(appDir, '.cursor', 'hooks.json'))).toBe(false)
+    const tiers = JSON.parse(readFileSync(join(appDir, '.ai', 'skills', 'tiers.json'), 'utf8')) as {
+      agents?: { ignore?: string[] }
+    }
+    expect(tiers.agents?.ignore).toEqual(['cursor'])
+  })
+})

package/src/lib/__tests__/injection-widget-id-validation.test.ts

@@ -0,0 +1,184 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createInjectionWidgetsExtension } from '../generators/extensions/injection-widgets'
+import type { ModuleScanContext } from '../generators/extension'
+
+// A widget's `metadata.id` and the `widgetId` that mounts it are two hand-typed literals in two
+// different files. Nothing linked them, so a typo in either failed silently — the widget was never
+// mounted, or the table entry resolved to nothing. These cases drive the real scan → generate seam
+// (real filesystem fixtures, real AST extraction) and assert the reconciliation warnings.
+
+let tmpRoot: string
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'om-injection-widgets-'))
+})
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true })
+  jest.restoreAllMocks()
+})
+
+function widgetSource(id: string): string {
+  return [
+    "import type { InjectionWidgetModule } from '@open-mercato/shared/modules/widgets/injection'",
+    "import Impl from './widget.client'",
+    '',
+    'const widget: InjectionWidgetModule = {',
+    '  metadata: {',
+    `    id: '${id}',`,
+    "    title: 'Fixture widget',",
+    '  },',
+    '  Widget: Impl,',
+    '}',
+    '',
+    'export default widget',
+  ].join('\n')
+}
+
+function tableSource(widgetIds: string[]): string {
+  const entries = widgetIds
+    .map((id, index) => `  'detail:fixture:tab${index}': [{ widgetId: '${id}', kind: 'tab' }],`)
+    .join('\n')
+  return [
+    "import type { ModuleInjectionTable } from '@open-mercato/shared/modules/widgets/injection'",
+    '',
+    'export const injectionTable: ModuleInjectionTable = {',
+    entries,
+    '}',
+    '',
+    'export default injectionTable',
+  ].join('\n')
+}
+
+/**
+ * Lays out one module on disk in the shape the scanner expects and returns a scan context for it.
+ * `declaredIds` each get `widgets/injection/<name>/widget.ts`; `referencedIds` go into the module's
+ * `widgets/injection-table.ts` (omitted entirely when the list is empty).
+ */
+function makeModule(moduleId: string, declaredIds: string[], referencedIds: string[]): ModuleScanContext {
+  const base = path.join(tmpRoot, moduleId)
+  const injectionDir = path.join(base, 'widgets', 'injection')
+  fs.mkdirSync(injectionDir, { recursive: true })
+
+  declaredIds.forEach((id, index) => {
+    const dir = path.join(injectionDir, `w${index}`)
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(path.join(dir, 'widget.ts'), widgetSource(id))
+  })
+
+  const tablePath = path.join(base, 'widgets', 'injection-table.ts')
+  if (referencedIds.length > 0) fs.writeFileSync(tablePath, tableSource(referencedIds))
+
+  const roots = { appBase: base, pkgBase: base }
+  return {
+    moduleId,
+    roots,
+    imps: { appBase: `@fixture/${moduleId}`, pkgBase: `@fixture/${moduleId}` },
+    importIdRef: { value: 0 },
+    sharedImports: [],
+    resolveModuleFile: (() =>
+      referencedIds.length > 0
+        ? { absolutePath: tablePath, importPath: `@fixture/${moduleId}/widgets/injection-table` }
+        : null) as unknown as ModuleScanContext['resolveModuleFile'],
+    resolveFirstModuleFile: (() => null) as unknown as ModuleScanContext['resolveFirstModuleFile'],
+    processStandaloneConfig: () => null,
+    sanitizeGeneratedModuleSpecifier: (importPath: string) => importPath,
+  }
+}
+
+function runGenerate(contexts: ModuleScanContext[]): string[] {
+  const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+  const extension = createInjectionWidgetsExtension()
+  for (const ctx of contexts) extension.scanModule(ctx)
+  extension.generateOutput()
+  return warn.mock.calls.map((call) => String(call[0]))
+}
+
+describe('injection widget id reconciliation at generate time', () => {
+  it('stays silent when every declared widget is referenced and vice versa', () => {
+    const warnings = runGenerate([makeModule('alpha', ['alpha.one', 'alpha.two'], ['alpha.one', 'alpha.two'])])
+
+    expect(warnings).toEqual([])
+  })
+
+  it('warns when an injection table references a widget id nothing declares', () => {
+    const warnings = runGenerate([makeModule('alpha', ['alpha.one'], ['alpha.one', 'alpha.typo'])])
+
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0]).toContain('alpha.typo')
+    expect(warnings[0]).toContain('references widget id')
+    expect(warnings[0]).toContain('alpha')
+  })
+
+  it('stays silent about a declared widget that no table references', () => {
+    // The mirror check is deliberately not implemented: `extractInjectionTableWidgetIds` reads only
+    // statically-analyzable literals, so a table built by composition or computation exposes no ids
+    // and every widget in such a module would be reported as unreferenced. Pinned so the omission is
+    // a decision rather than an oversight.
+    const warnings = runGenerate([makeModule('alpha', ['alpha.one', 'alpha.orphan'], ['alpha.one'])])
+
+    expect(warnings).toEqual([])
+  })
+
+  it('reports only the unresolvable reference when the two sides disagree entirely', () => {
+    const warnings = runGenerate([makeModule('alpha', ['alpha.declared'], ['alpha.referenced'])])
+
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0]).toContain('alpha.referenced')
+  })
+
+  it('does not warn about a table assembled by composition, whose ids are invisible statically', () => {
+    // Mirrors the real `example` module: `cond ? { ...a, ...b } : a`. The extractor sees no ids, so
+    // there is nothing to reconcile — and critically, no false warning.
+    const base = path.join(tmpRoot, 'composed')
+    fs.mkdirSync(path.join(base, 'widgets', 'injection', 'w0'), { recursive: true })
+    fs.writeFileSync(path.join(base, 'widgets', 'injection', 'w0', 'widget.ts'), widgetSource('composed.one'))
+    const tablePath = path.join(base, 'widgets', 'injection-table.ts')
+    fs.writeFileSync(
+      tablePath,
+      [
+        "import type { ModuleInjectionTable } from '@open-mercato/shared/modules/widgets/injection'",
+        "const a: ModuleInjectionTable = { 'detail:x:tab': [{ widgetId: 'composed.one' }] }",
+        "const b: ModuleInjectionTable = { 'detail:y:tab': [{ widgetId: 'composed.two' }] }",
+        'export const injectionTable: ModuleInjectionTable = process.env.FLAG ? { ...a, ...b } : a',
+        'export default injectionTable',
+      ].join('\n'),
+    )
+
+    const ctx: ModuleScanContext = {
+      ...makeModule('composed', [], []),
+      resolveModuleFile: (() => ({
+        absolutePath: tablePath,
+        importPath: '@fixture/composed/widgets/injection-table',
+      })) as unknown as ModuleScanContext['resolveModuleFile'],
+    }
+
+    expect(runGenerate([ctx])).toEqual([])
+  })
+
+  it('accepts a table in one module referencing a widget declared in another', () => {
+    const warnings = runGenerate([
+      makeModule('alpha', ['alpha.shared'], []),
+      makeModule('beta', [], ['alpha.shared']),
+    ])
+
+    expect(warnings).toEqual([])
+  })
+
+  it('does not warn for the single-widget id inference', () => {
+    // A lone widget whose metadata.id cannot be extracted adopts the table's single id; that
+    // convenience path must not then report itself as a mismatch.
+    const ctx = makeModule('gamma', [], ['gamma.inferred'])
+    const dir = path.join(tmpRoot, 'gamma', 'widgets', 'injection', 'solo')
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(path.join(dir, 'widget.ts'), 'export default { Widget: () => null }\n')
+
+    expect(runGenerate([ctx])).toEqual([])
+  })
+
+  it('stays silent for a module with no injection widgets and no table', () => {
+    expect(runGenerate([makeModule('delta', [], [])])).toEqual([])
+  })
+})

package/src/lib/agentic-init.ts

@@ -5,6 +5,7 @@ import { createInterface } from 'node:readline'
 interface AgenticInitOptions {
   tool?: string
   force?: boolean
+  updateHarness?: boolean
 }
 
 const TOOL_EXISTING_FILES: Record<string, string[]> = {
@@ -27,6 +28,8 @@ function parseArgs(args: string[]): AgenticInitOptions {
     const arg = args[i]
     if (arg === '--force' || arg === '-f') {
       options.force = true
+    } else if (arg === '--update-harness') {
+      options.updateHarness = true
     } else if (arg.startsWith('--tool=')) {
       options.tool = arg.slice('--tool='.length)
     } else if (arg === '--tool') {
@@ -59,6 +62,11 @@ export async function runAgenticInit(args: string[]): Promise<number> {
   const targetDir = resolve('.')
   const options = parseArgs(args)
 
+  if (options.force && options.updateHarness) {
+    console.error('❌  --force and --update-harness are mutually exclusive')
+    return 1
+  }
+
   // Validate this is an Open Mercato app directory
   if (!existsSync(join(targetDir, 'src', 'modules.ts'))) {
     console.error('❌  Not an Open Mercato app directory (src/modules.ts not found)')
@@ -66,7 +74,7 @@ export async function runAgenticInit(args: string[]): Promise<number> {
   }
 
   // Check if agentic files already exist and warn unless --force
-  if (!options.force) {
+  if (!options.force && !options.updateHarness) {
     const existingFiles = resolveRelevantAgenticFiles(options.tool)
       .filter((relativePath) => existsSync(join(targetDir, relativePath)))
 
@@ -77,7 +85,7 @@ export async function runAgenticInit(args: string[]): Promise<number> {
         console.log(`   • ${f}`)
       }
       console.log('')
-      console.log('Run with --force to regenerate from current templates.')
+      console.log('Run with --update-harness to preserve local edits, or --force to replace generated files.')
       console.log('')
       return 0
     }
@@ -92,7 +100,11 @@ export async function runAgenticInit(args: string[]): Promise<number> {
   const ask = (q: string) => new Promise<string>((res) => rl.question(q, (a) => res(a.trim())))
 
   try {
-    await runAgenticSetup(targetDir, ask, { tool: options.tool, force: options.force })
+    await runAgenticSetup(targetDir, ask, {
+      tool: options.tool,
+      force: options.force,
+      updateHarness: options.updateHarness,
+    })
   } finally {
     rl.close()
   }