@open-mercato/cli 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

package/src/lib/cli-bootstrap-mode.ts

@@ -0,0 +1,31 @@
+export type CliBootstrapMode = 'none' | 'dev-supervisor' | 'full'
+
+const BOOTSTRAP_FREE_COMMANDS = new Set([
+  'generate',
+  'module',
+  'deploy',
+  'db',
+  'init',
+  'agentic:init',
+  'telemetry',
+  'eject',
+  'test',
+  'test:integration',
+  'test:integration:coverage',
+  'test:integration:spec-coverage',
+  'test:ephemeral',
+  'test:integration:interactive',
+  'umes:list',
+  'umes:inspect',
+  'umes:check',
+  'help',
+  '--help',
+  '-h',
+])
+
+export function resolveCliBootstrapMode(argv: readonly string[]): CliBootstrapMode {
+  const [, , first, second] = argv
+  if (!first || BOOTSTRAP_FREE_COMMANDS.has(first)) return 'none'
+  if (first === 'server' && second === 'dev') return 'dev-supervisor'
+  return 'full'
+}

package/src/lib/dev-supervisor-manifest.ts

@@ -0,0 +1,142 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
+
+export const DEV_SUPERVISOR_MANIFEST_FILE = 'dev-supervisor.generated.json'
+export const DEV_SUPERVISOR_MANIFEST_VERSION = 1
+
+export type DevSupervisorWorkerDescriptor = Pick<
+  ModuleWorker,
+  'id' | 'moduleId' | 'queue' | 'concurrency'
+>
+
+export type DevSupervisorSchedulerStartStatus =
+  | 'ok'
+  | 'missing-module'
+  | 'missing-cli'
+  | 'missing-command'
+
+export type DevSupervisorManifest = {
+  version: typeof DEV_SUPERVISOR_MANIFEST_VERSION
+  workers: DevSupervisorWorkerDescriptor[]
+  schedulerStartStatus: DevSupervisorSchedulerStartStatus
+  requiresFullBootstrap: boolean
+}
+
+let registeredManifest: DevSupervisorManifest | null = null
+
+function manifestError(filePath: string, detail: string): Error {
+  return new Error(
+    `Invalid generated dev supervisor manifest at ${filePath}: ${detail}. ` +
+      'Run `yarn generate` and retry.',
+  )
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function parseWorkerDescriptor(
+  value: unknown,
+  index: number,
+  filePath: string,
+): DevSupervisorWorkerDescriptor {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw manifestError(filePath, `workers[${index}] must be an object`)
+  }
+
+  const worker = value as Record<string, unknown>
+  if (!isNonEmptyString(worker.id)) {
+    throw manifestError(filePath, `workers[${index}].id must be a non-empty string`)
+  }
+  if (!isNonEmptyString(worker.queue)) {
+    throw manifestError(filePath, `workers[${index}].queue must be a non-empty string`)
+  }
+  if (typeof worker.concurrency !== 'number' || !Number.isFinite(worker.concurrency)) {
+    throw manifestError(filePath, `workers[${index}].concurrency must be a finite number`)
+  }
+  if (worker.moduleId !== undefined && !isNonEmptyString(worker.moduleId)) {
+    throw manifestError(filePath, `workers[${index}].moduleId must be a non-empty string when present`)
+  }
+
+  return {
+    id: worker.id,
+    ...(worker.moduleId === undefined ? {} : { moduleId: worker.moduleId }),
+    queue: worker.queue,
+    concurrency: worker.concurrency,
+  }
+}
+
+function parseManifest(value: unknown, filePath: string): DevSupervisorManifest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw manifestError(filePath, 'root value must be an object')
+  }
+
+  const manifest = value as Record<string, unknown>
+  if (manifest.version !== DEV_SUPERVISOR_MANIFEST_VERSION) {
+    throw manifestError(
+      filePath,
+      `unsupported version ${String(manifest.version)} (expected ${DEV_SUPERVISOR_MANIFEST_VERSION})`,
+    )
+  }
+  if (!Array.isArray(manifest.workers)) {
+    throw manifestError(filePath, 'workers must be an array')
+  }
+
+  const schedulerStartStatus = manifest.schedulerStartStatus
+  if (
+    schedulerStartStatus !== 'ok' &&
+    schedulerStartStatus !== 'missing-module' &&
+    schedulerStartStatus !== 'missing-cli' &&
+    schedulerStartStatus !== 'missing-command'
+  ) {
+    throw manifestError(filePath, 'schedulerStartStatus is invalid')
+  }
+
+  return {
+    version: DEV_SUPERVISOR_MANIFEST_VERSION,
+    workers: manifest.workers.map((worker, index) => parseWorkerDescriptor(worker, index, filePath)),
+    schedulerStartStatus,
+    // Version-1 manifests produced before this safety marker existed cannot
+    // prove that worker/CLI overrides were accounted for. Preserve the old
+    // full-bootstrap behavior until `yarn generate` writes an explicit false.
+    requiresFullBootstrap: manifest.requiresFullBootstrap !== false,
+  }
+}
+
+export function canUseLightweightDevSupervisor(manifest: DevSupervisorManifest): boolean {
+  return manifest.requiresFullBootstrap === false
+}
+
+export function loadDevSupervisorManifest(appDir: string): DevSupervisorManifest {
+  const filePath = path.join(appDir, '.mercato', 'generated', DEV_SUPERVISOR_MANIFEST_FILE)
+  let source: string
+  try {
+    source = fs.readFileSync(filePath, 'utf8')
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw manifestError(filePath, `file could not be read (${detail})`)
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(source)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw manifestError(filePath, `JSON could not be parsed (${detail})`)
+  }
+
+  return parseManifest(parsed, filePath)
+}
+
+export function registerDevSupervisorManifest(manifest: DevSupervisorManifest): void {
+  registeredManifest = manifest
+}
+
+export function getRegisteredDevSupervisorManifest(): DevSupervisorManifest | null {
+  return registeredManifest
+}
+
+export function resetDevSupervisorManifestForTests(): void {
+  registeredManifest = null
+}

package/src/lib/generate-watch-events.ts

@@ -21,6 +21,8 @@ type WatchDirectory = (
 export type GenerateWatchChangeSignalOptions = {
   getWatchTargets: () => Promise<GenerateWatchTarget[]> | GenerateWatchTarget[]
   watchDirectory?: WatchDirectory
+  directoryExists?: (directory: string) => boolean
+  onSkippedDirectory?: (directory: string) => void
 }
 
 function targetKey(target: GenerateWatchTarget): string {
@@ -49,7 +51,9 @@ export function createGenerateWatchChangeSignal(
   options: GenerateWatchChangeSignalOptions,
 ): GenerateWatcherChangeSignal {
   const watchDirectory = options.watchDirectory ?? defaultWatchDirectory
+  const directoryExists = options.directoryExists ?? fs.existsSync
   const watchers = new Map<string, WatchHandle>()
+  let skippedDirectories = new Set<string>()
   let version = 0
   let pollingFallback = false
   let closed = false
@@ -70,6 +74,7 @@ export function createGenerateWatchChangeSignal(
 
   return {
     currentVersion: () => version,
+    hasSkippedTargets: () => skippedDirectories.size > 0,
     usesPollingFallback: () => pollingFallback,
     refresh: async () => {
       if (closed || pollingFallback) return
@@ -83,13 +88,22 @@ export function createGenerateWatchChangeSignal(
       }
 
       const normalizedTargets = new Map<string, GenerateWatchTarget>()
+      const nextSkippedDirectories = new Set<string>()
       for (const target of targets) {
         const normalized: GenerateWatchTarget = {
           ...target,
           directory: path.resolve(target.directory),
         }
+        if (!directoryExists(normalized.directory)) {
+          nextSkippedDirectories.add(normalized.directory)
+          if (!skippedDirectories.has(normalized.directory)) {
+            try { options.onSkippedDirectory?.(normalized.directory) } catch {}
+          }
+          continue
+        }
         normalizedTargets.set(targetKey(normalized), normalized)
       }
+      skippedDirectories = nextSkippedDirectories
 
       for (const [key, watcher] of watchers) {
         if (normalizedTargets.has(key)) continue

package/src/lib/generators/__tests__/activation-adapter-coverage.test.ts

@@ -0,0 +1,92 @@
+import {
+  ACTIVATION_ADAPTERS,
+  ALL_ACTIVATION_KINDS,
+  ALL_CONTRIBUTION_KINDS,
+  CONTRIBUTION_ACTIVATION_CLASSIFICATION,
+} from '../module-extension-facts'
+import type {
+  ModuleExtensionActivationKind,
+  ModuleExtensionContributionKind,
+} from '@open-mercato/shared/modules/widgets/extension-points'
+
+// Explicit expected inventories. Adding a UMES activation kind or contribution
+// kind to the shared union forces the typed Record in module-extension-facts.ts
+// to gain a key (compile-time gate) AND requires updating these lists (this
+// coverage gate), so an unclassified kind cannot ship silently.
+const EXPECTED_ACTIVATION_KINDS: ModuleExtensionActivationKind[] = [
+  'crud-response-enricher',
+  'query-enricher',
+  'mutation-guard',
+  'api-interceptor-bridge',
+  'command-interceptor-bridge',
+  'widget-injection-consumer',
+  'component-extension-consumer',
+  'dashboard-host-consumer',
+]
+
+const EXPECTED_CONTRIBUTION_KINDS: ModuleExtensionContributionKind[] = [
+  'widget',
+  'data-table',
+  'crud-form',
+  'component-override',
+  'response-enricher',
+  'api-interceptor',
+  'command-interceptor',
+  'mutation-guard',
+  'entity-extension',
+  'subscriber',
+  'browser-reaction',
+  'specialized-registry',
+  'module-override',
+]
+
+// Route/entity-bound contribution kinds MUST bind through an activation adapter —
+// never be silently classified as capability-only.
+const ROUTE_OR_ENTITY_BOUND_KINDS: ModuleExtensionContributionKind[] = [
+  'response-enricher',
+  'mutation-guard',
+  'api-interceptor',
+  'command-interceptor',
+]
+
+describe('activation adapter coverage', () => {
+  it('registers exactly the expected closed set of activation adapters', () => {
+    expect([...ALL_ACTIVATION_KINDS].sort()).toEqual([...EXPECTED_ACTIVATION_KINDS].sort())
+    expect(Object.keys(ACTIVATION_ADAPTERS).sort()).toEqual([...EXPECTED_ACTIVATION_KINDS].sort())
+  })
+
+  it('classifies exactly the expected closed set of contribution kinds', () => {
+    expect([...ALL_CONTRIBUTION_KINDS].sort()).toEqual([...EXPECTED_CONTRIBUTION_KINDS].sort())
+    expect(Object.keys(CONTRIBUTION_ACTIVATION_CLASSIFICATION).sort()).toEqual([...EXPECTED_CONTRIBUTION_KINDS].sort())
+  })
+
+  it('maps every contribution kind to a real adapter whose contributionKinds accept it, or to a tested capability-only classification', () => {
+    for (const kind of ALL_CONTRIBUTION_KINDS) {
+      const classification = CONTRIBUTION_ACTIVATION_CLASSIFICATION[kind]
+      if (classification === 'capability-only') {
+        expect(ROUTE_OR_ENTITY_BOUND_KINDS).not.toContain(kind)
+        continue
+      }
+      expect(classification.length).toBeGreaterThan(0)
+      for (const activationKind of classification) {
+        const adapter = ACTIVATION_ADAPTERS[activationKind]
+        expect(adapter).toBeDefined()
+        expect(adapter.contributionKinds).toContain(kind)
+      }
+    }
+  })
+
+  it('requires every route/entity-bound contribution kind to have an activation adapter (never capability-only)', () => {
+    for (const kind of ROUTE_OR_ENTITY_BOUND_KINDS) {
+      const classification = CONTRIBUTION_ACTIVATION_CLASSIFICATION[kind]
+      expect(classification).not.toBe('capability-only')
+    }
+  })
+
+  it('keeps a call-site-object adapter for every kind that distinguishes bound from capability-only by opt-in', () => {
+    const callSiteKinds = ALL_ACTIVATION_KINDS.filter((kind) => ACTIVATION_ADAPTERS[kind].mode === 'call-site-object')
+    // Enricher (response + query) and mutation-guard opt-ins are the only surfaces
+    // whose activation presence is NOT implied by mere host existence.
+    expect(callSiteKinds.sort()).toEqual(['crud-response-enricher', 'mutation-guard', 'query-enricher'])
+  })
+})

package/src/lib/generators/__tests__/entity-ids.test.ts

@@ -201,6 +201,38 @@ describe('generateEntityIds', () => {
     expect(registry).not.toContain("import * as sales_order from './entities/sales_order/index'")
   })
 
+  it('preserves every generated entity output mtime when the output bytes are unchanged', async () => {
+    const moduleEntry: ModuleEntry = { id: 'orders', from: '@open-mercato/core' }
+    const entitiesFile = path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'orders', 'data', 'entities.ts')
+    fs.mkdirSync(path.dirname(entitiesFile), { recursive: true })
+    fs.writeFileSync(entitiesFile, 'export class SalesOrder { id!: string; totalGross!: number }\n')
+
+    const resolver = createMockResolver(tmpDir, [moduleEntry])
+    const firstResult = await generateEntityIds({ resolver, quiet: true })
+    const outputDir = resolver.getOutputDir()
+    const generatedFiles = [
+      path.join(outputDir, 'entities.ids.generated.ts'),
+      path.join(outputDir, 'entity-fields-registry.ts'),
+      path.join(outputDir, 'entities', 'sales_order', 'index.ts'),
+    ]
+    const oldTime = new Date(Date.now() - 60_000)
+    for (const filePath of generatedFiles) {
+      fs.utimesSync(filePath, oldTime, oldTime)
+    }
+    const mtimesBefore = new Map(
+      generatedFiles.map((filePath) => [filePath, fs.statSync(filePath).mtimeMs]),
+    )
+
+    const secondResult = await generateEntityIds({ resolver, quiet: true })
+
+    expect(firstResult.filesWritten).toEqual(expect.arrayContaining(generatedFiles))
+    expect(secondResult.filesWritten).toEqual([])
+    expect(secondResult.filesUnchanged).toEqual(expect.arrayContaining(generatedFiles))
+    for (const filePath of generatedFiles) {
+      expect(fs.statSync(filePath).mtimeMs).toBe(mtimesBefore.get(filePath))
+    }
+  })
+
   it('reuses package generated entity metadata in standalone mode', async () => {
     const moduleEntry: ModuleEntry = { id: 'directory', from: '@open-mercato/core' }
     const packageRoot = path.join(tmpDir, 'node_modules', '@open-mercato', 'core')

package/src/lib/generators/__tests__/helpers/override-target-diagnostic-fixtures.ts

@@ -0,0 +1,150 @@
+import type { ModuleFactsJsonEntry } from '../../module-facts'
+import { getFrameworkOverrideHostOperations } from '../../module-extension-facts'
+import {
+  collectModuleOverrideTargets,
+  type ModuleOverrideTargetDiagnostic,
+  type ModuleOverrideTargetDiagnosticCode,
+  type ModuleOverrideTargetsResult,
+} from '../../module-override-targets'
+
+/**
+ * Real producers for every override-target diagnostic the projector can emit.
+ *
+ * The `factCoverage` ledger classifies four diagnostic codes as `negative-fixture`,
+ * which is a claim that a fixture really drives that code out of
+ * {@link collectModuleOverrideTargets}. These fixtures ARE that claim's evidence, and
+ * the coverage test asserts the produced set matches the ledger rows exactly — so a
+ * row can never name a fixture that does not exist, and a code no fixture reaches
+ * cannot be published as `negative-fixture`.
+ */
+
+export const FIXTURE_MODULE_ID = 'fixture'
+export const FIXTURE_SOURCE_ROOT = `node_modules/@open-mercato/core/src/modules/${FIXTURE_MODULE_ID}`
+
+export function fixtureFacts(overrides: Partial<ModuleFactsJsonEntry> = {}): ModuleFactsJsonEntry {
+  return {
+    title: 'Fixture',
+    description: null,
+    coreVersion: null,
+    sourcePackage: '@open-mercato/core',
+    sourceVersion: null,
+    sourceRoot: FIXTURE_SOURCE_ROOT,
+    entities: [],
+    events: [],
+    aclFeatures: [],
+    apiRoutes: [],
+    diTokens: [],
+    searchEntities: [],
+    hostTokens: { entityIds: [], tableIds: [] },
+    notifications: [],
+    cli: ['fixture:seed'],
+    backendPages: [],
+    frontendPages: [],
+    cliCommands: [{ command: 'fixture:seed', sourcePath: `${FIXTURE_SOURCE_ROOT}/cli.ts` }],
+    aiTools: [],
+    aiAgents: [],
+    ...overrides,
+  }
+}
+
+function fixtureWorkerFacts(): ModuleFactsJsonEntry {
+  return fixtureFacts({
+    ownedContracts: {
+      worker: [
+        {
+          kind: 'worker',
+          id: 'fixture.worker',
+          source: { sourcePath: `${FIXTURE_SOURCE_ROOT}/workers/fixture.ts`, line: 1 },
+        },
+      ],
+    },
+  })
+}
+
+/**
+ * The framework catalog's real declared operations, which the projector reads at
+ * import time. Tests derive their stub catalogs from this so a stub differs from
+ * production in exactly the one host under test.
+ */
+export function realCatalogOperations(): Record<string, string> {
+  return getFrameworkOverrideHostOperations()
+}
+
+export function catalogWithout(dottedHost: string): Record<string, string> {
+  const operations = realCatalogOperations()
+  delete operations[dottedHost]
+  return operations
+}
+
+export function catalogWith(dottedHost: string, operation: string): Record<string, string> {
+  return { ...realCatalogOperations(), [dottedHost]: operation }
+}
+
+/**
+ * Re-imports the projector against a stubbed framework catalog, so the two "no
+ * modes" causes reach the real `pushTarget` wiring instead of only the pure
+ * resolver. Every catalog host ships a valid operation today, so a stub is the only
+ * way to drive the unknown-domain/unknown-mode branches through production code.
+ */
+export function collectWithCatalogOperations(
+  hostOperations: Record<string, string>,
+  facts: ModuleFactsJsonEntry,
+): ModuleOverrideTargetsResult {
+  let result: ModuleOverrideTargetsResult | undefined
+  jest.isolateModules(() => {
+    jest.doMock('../../module-extension-facts', () => ({
+      ...jest.requireActual('../../module-extension-facts'),
+      getFrameworkOverrideHostOperations: () => hostOperations,
+    }))
+    const projector = require('../../module-override-targets') as typeof import('../../module-override-targets')
+    result = projector.collectModuleOverrideTargets(facts)
+  })
+  jest.dontMock('../../module-extension-facts')
+  if (!result) throw new Error('[internal] isolated override-target collection produced no result')
+  return result
+}
+
+export type OverrideTargetDiagnosticFixture = {
+  code: ModuleOverrideTargetDiagnosticCode
+  description: string
+  run: () => ModuleOverrideTargetDiagnostic[]
+}
+
+export const OVERRIDE_TARGET_DIAGNOSTIC_FIXTURES: OverrideTargetDiagnosticFixture[] = [
+  {
+    code: 'missing-source',
+    description: 'a cli command whose provenance cannot be proven',
+    run: () =>
+      collectModuleOverrideTargets(fixtureFacts({ cliCommands: [{ command: 'fixture:seed', sourcePath: null }] }))
+        .overrideTargetDiagnostics,
+  },
+  {
+    code: 'unsupported-dynamic-key',
+    description: 'an api route whose method the runtime cannot address',
+    run: () =>
+      collectModuleOverrideTargets(
+        fixtureFacts({
+          apiRoutes: [
+            {
+              path: '/fixture/items',
+              methods: ['FETCH'],
+              auth: {},
+              sourcePath: `${FIXTURE_SOURCE_ROOT}/api/items/route.ts`,
+            },
+          ],
+        }),
+      ).overrideTargetDiagnostics,
+  },
+  {
+    code: 'unknown-framework-domain',
+    description: 'the framework catalog does not describe the cli host at all',
+    run: () => collectWithCatalogOperations(catalogWithout('cli'), fixtureFacts()).overrideTargetDiagnostics,
+  },
+  {
+    code: 'unknown-framework-mode',
+    description: 'the framework catalog describes the workers host with an operation that is not a public mode',
+    run: () =>
+      collectWithCatalogOperations(catalogWith('workers', 'merge-deep'), fixtureWorkerFacts())
+        .overrideTargetDiagnostics,
+  },
+]