@open-mercato/cli 0.6.8-develop.6964.1.36b364cfd8 → 0.6.8-develop.6971.1.20c09ca9ea

package/dist/agentic/cursor/hooks/gate-evidence.mjs

@@ -0,0 +1,181 @@
+/**
+ * Record validation-gate outcomes, and refuse to finish on unverified source changes (Cursor).
+ *
+ * Mirrors the claude-code hook: `record` on `afterShellExecution`, `check` on `stop`.
+ *
+ * Cursor's `afterShellExecution` payload documents `command`, `output`, `duration`, and
+ * `sandbox` — no exit code — so the outcome is inferred from output text rather than read.
+ * Blocking contract: exit 2 blocks, exit 0 proceeds, other codes fail open.
+ */
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/**
+ * Extracts every gate a shell command ran.
+ *
+ * Quoted spans are blanked first: `git commit -m "run tsc --noEmit"` names a gate without
+ * running one, and its zero exit status would otherwise be recorded as a green typecheck.
+ */
+export function matchGates(command) {
+  const executable = command.replace(/'[^']*'|"[^"]*"/g, ' ')
+  const found = new Set()
+  const named = [
+    ['typecheck', /\b(?:yarn|npm run|pnpm)\s+typecheck\b|\btsc\b[^&|;]*--noEmit/],
+    ['lint', /\b(?:yarn|npm run|pnpm)\s+lint\b|\beslint\b/],
+    ['test', /\b(?:yarn|npm run|pnpm)\s+test\b|\bjest\b/],
+    ['build', /\b(?:yarn|npm run|pnpm)\s+build\b|\bnext build\b/],
+    ['generate', /\b(?:yarn|npm run|pnpm)\s+generate\b|\bmercato\s+generate\b/],
+  ]
+  for (const [gate, pattern] of named) {
+    if (pattern.test(executable)) found.add(gate)
+  }
+  return [...found]
+}
+
+/**
+ * Whether a command's outcome can be attributed to the gates it names.
+ *
+ * A pipeline reports its LAST stage's status, and `;` / `||` break the link the same way.
+ * `&&` does not: it short-circuits, so a failure still belongs to a gate that ran.
+ */
+export function isAttributableGateCommand(command) {
+  return !/[|;\n]/.test(command)
+}
+
+/** See the claude-code hook. */
+export function nextSessionState(previous, sessionId, startedAt) {
+  if (!sessionId) {
+    return previous.sessionStartedAt ? previous : { ...previous, sessionStartedAt: startedAt }
+  }
+  if (previous.sessionId === sessionId && previous.sessionStartedAt) return previous
+  return { sessionId, sessionStartedAt: startedAt }
+}
+
+/** See the claude-code hook: an absent typecheck record does not block on its own. */
+export function shouldBlock({ newestSrcMtimeMs, sessionStartedAtMs, lastGreenTypecheckMs }) {
+  if (newestSrcMtimeMs === null) return false
+  if (newestSrcMtimeMs < sessionStartedAtMs) return false
+  if (lastGreenTypecheckMs === null) return true
+  return newestSrcMtimeMs > lastGreenTypecheckMs
+}
+
+/**
+ * Infers a gate outcome from its output, because this host reports no exit code.
+ *
+ * Returns 1 (failure) for empty output and for any failure signature. The bias is
+ * deliberate: over-reporting failure costs one re-run, under-reporting it records a pass
+ * that never happened — the property this hook exists to remove. `No tests found` is a
+ * failure here for the same reason it is not a pass in the harness rules.
+ */
+export function inferExitCode(output) {
+  if (typeof output !== 'string' || output.trim() === '') return 1
+  const failureSignatures = [
+    /\berror\s+TS\d+/i, /FATAL ERROR/i, /heap out of memory/i,
+    /\bTests?:\s+\d+\s+failed/i, /\bfail(ed|ing)\b/i, /\bERROR\b/,
+    /exited \(\d+\)/, /command not found/i, /No tests found/i,
+  ]
+  return failureSignatures.some((pattern) => pattern.test(output)) ? 1 : 0
+}
+
+const STATE_RELATIVE_PATH = '.ai/.gate-state.json'
+const WATCHED_ROOT = 'src'
+
+function projectDir() {
+  return process.env.CURSOR_PROJECT_DIR || resolve('.')
+}
+
+function statePath() { return join(projectDir(), STATE_RELATIVE_PATH) }
+
+function readState() {
+  try { return JSON.parse(readFileSync(statePath(), 'utf8')) } catch { return {} }
+}
+
+function writeState(state) {
+  try {
+    mkdirSync(join(projectDir(), '.ai'), { recursive: true })
+    writeFileSync(statePath(), `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+  } catch {
+    // A hook must never fail the turn over its own bookkeeping.
+  }
+}
+
+function newestMtimeMs(dir) {
+  let newest = null
+  const walk = (current) => {
+    let entries
+    try { entries = readdirSync(current) } catch { return }
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry.startsWith('.')) continue
+      const full = join(current, entry)
+      let stats
+      try { stats = statSync(full) } catch { continue }
+      if (stats.isDirectory()) walk(full)
+      else if (newest === null || stats.mtimeMs > newest) newest = stats.mtimeMs
+    }
+  }
+  walk(dir)
+  return newest
+}
+
+function readStdin() {
+  return new Promise((done) => {
+    let raw = ''
+    if (process.stdin.isTTY) { done(''); return }
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk) => { raw += chunk })
+    process.stdin.on('end', () => done(raw))
+    process.stdin.on('error', () => done(''))
+  })
+}
+
+async function main() {
+  const mode = process.argv[2] === 'check' ? 'check' : 'record'
+  const raw = await readStdin()
+
+  let data = {}
+  if (raw.trim()) {
+    try { data = JSON.parse(raw) } catch { process.exit(0) }
+  }
+
+  const previous = readState()
+  const now = new Date()
+  const state = nextSessionState(previous, data.session_id ?? null, now.toISOString())
+  if (state !== previous) writeState(state)
+
+  if (mode === 'record') {
+    const command = data.command ?? data.tool_input?.command
+    if (!command) process.exit(0)
+    const gates = matchGates(command)
+    if (!gates.length) process.exit(0)
+    if (!isAttributableGateCommand(command)) process.exit(0)
+    const exitCode = inferExitCode(data.output ?? '')
+    state.gates = state.gates ?? {}
+    for (const gate of gates) {
+      state.gates[gate] = { exitCode, finishedAt: now.toISOString() }
+    }
+    writeState(state)
+    process.exit(0)
+  }
+
+  if (data.stop_hook_active) process.exit(0)
+
+  const typecheck = state.gates?.typecheck
+  const blocked = shouldBlock({
+    newestSrcMtimeMs: newestMtimeMs(join(projectDir(), WATCHED_ROOT)),
+    sessionStartedAtMs: Date.parse(state.sessionStartedAt ?? now.toISOString()),
+    lastGreenTypecheckMs: typecheck && typecheck.exitCode === 0 ? Date.parse(typecheck.finishedAt) : null,
+  })
+  if (!blocked) process.exit(0)
+
+  process.stderr.write([
+    `Source under ${WATCHED_ROOT}/ changed this session and has not passed a typecheck since.`,
+    '',
+    'Run `yarn typecheck` and report its exit status before finishing.',
+    'If it genuinely fails and you cannot fix it, report the failure to the user.',
+    '',
+  ].join('\n'))
+  process.exit(2)
+}
+
+const invokedDirectly = process.argv[1] && process.argv[1].endsWith('gate-evidence.mjs')
+if (invokedDirectly) await main()

package/dist/agentic/cursor/hooks.json

@@ -5,6 +5,16 @@
       "command": "node",
       "args": [".cursor/hooks/entity-migration-check.mjs"],
       "description": "Check if entity edit requires a database migration"
+    },
+    "afterShellExecution": {
+      "command": "node",
+      "args": [".cursor/hooks/gate-evidence.mjs", "record"],
+      "description": "Record validation-gate outcomes so a gate cannot be claimed without running"
+    },
+    "stop": {
+      "command": "node",
+      "args": [".cursor/hooks/gate-evidence.mjs", "check"],
+      "description": "Block finishing when src/ changed without a passing typecheck since"
     }
   }
 }

package/dist/agentic/guides/framework-contracts.md

@@ -0,0 +1,82 @@
+# Installed Framework Contracts
+
+Use this digest after app call sites and generated facts identify a named framework contract. Links are read-only version evidence: never edit or enumerate `node_modules`. If a question is unanswered, invoke `om-framework-context` for only that contract.
+
+## Command handler and registry
+
+[`CommandHandler`](../../node_modules/@open-mercato/shared/src/lib/commands/types.ts) has a stable `id` and one required operation, `execute(input, ctx)`. Its optional lifecycle is deliberately split:
+
+- `prepare(input, ctx)` captures the before snapshot before execution.
+- `execute(input, ctx)` performs the durable operation and returns the public result.
+- `captureAfter(input, result, ctx)` can capture the after snapshot.
+- `buildLog({ input, result, ctx, snapshots })` returns action-log metadata; returning `null` or `skipLog` suppresses a normal log entry.
+- `undo({ input, ctx, logEntry })` and `redo(...)` are only valid when the handler owns a reversible contract. Undo payload is stored under `commandPayload`, not `logEntry.payload`; use the shared undo extractor.
+
+`CommandRuntimeContext` carries authentication, selected organization scope, the DI container, optional request and sync origin, bulk-import suppression, and an optional `transactionalEm`. A handler must preserve this scope and reuse `transactionalEm` when supplied instead of opening an independent transaction.
+
+[The command registry and `registerCommand`](../../node_modules/@open-mercato/shared/src/lib/commands/registry.ts) own handler discovery. Register through the normal `commands.ts` discovery surface. IDs are global and stable: duplicates throw outside development; development permits HMR replacement. Never silently replace a production ID or call registry internals from a module.
+
+## Atomic CRUD command writes
+
+[`runCrudCommandWrite`](../../node_modules/@open-mercato/shared/src/lib/commands/runCrudCommandWrite.ts) is the command-owned persistence seam for CRUD-backed handlers. It:
+
+It resolves or reuses an entity manager; passes all phases through transactional-by-default `withAtomicFlush`; applies custom fields after durable phases; and emits configured CRUD/index side effects from `sideEffect()`.
+
+Every phase must use the callback's entity manager. Set `transaction: false` only when an enclosing transaction already provides the atomic boundary. `sideEffect()` must return the final entity and stable identifiers after phases have completed. Commands using this helper own generic event/reindex emission; their route must not repeat it.
+
+## `makeCrudRoute`
+
+[`makeCrudRoute`](../../node_modules/@open-mercato/shared/src/lib/crud/factory.ts) is the installed HTTP factory. Its `metadata.GET/POST/PUT/DELETE` gates authentication, immutable feature requirements, and rate limits per method. The factory also retains tenant/organization selection checks, interceptors, mutation guards, synchronous before/after lifecycle subscribers, response shaping, command operation headers, and errors. Command-backed actions extend that envelope; they do not replace it.
+
+ORM defaults are `id`, `organizationId`, `tenantId`, and `deletedAt`; `null` disables an automatic field. Do not disable scope merely because a handler checks it too. With the specialized read-only `omitAutomaticTenantOrgScope`, `buildFilters` must encode all visibility and fail closed; update/delete scoping remains automatic.
+
+### List sequence
+
+- The list zod schema parses query parameters; before interceptors may rewrite it, followed by another parse.
+- `hooks.beforeList(validatedQuery, ctx)` runs after rewriting and before the query. Resolve request-specific state through `ctx`, never module-global mutable state.
+- `list.transformItem(item)` is a synchronous per-row projection. On the Query Engine path it runs before custom-field decoration, translation overlay, and response enrichment. It must not perform async I/O.
+- `hooks.afterList(payload, { ...ctx, query })` receives the mutable response payload on cache, query-engine, ORM-fallback, export, and empty-result branches. Response enrichers configured by `enrichers.entityId` run after `afterList`; after interceptors also remain part of the factory response pipeline.
+
+Keep entity/enricher IDs and list fields, filters, sorting, joins, and export settings stable. `buildFilters` may be async; `transformItem` may not. Query Engine options do not apply when the route omits `entityId` or `fields`.
+
+### Command-backed mutations
+
+`actions.create`, `actions.update`, and `actions.delete` select the command path by stable `commandId`. An action may map validated input, add log metadata, choose response/status, and provide resource identity. The command performs persistence and asynchronous generic CRUD side effects. The factory still performs:
+
+- route authentication and selected-scope rejection;
+- request interceptors and schema validation;
+- synchronous lifecycle events and mutation guards;
+- command-bus execution and action-log operation headers;
+- response interceptors, guard success callbacks, and cache invalidation.
+
+Thus commands own the asynchronous configured CRUD event/index work, not the factory's synchronous lifecycle. The factory deliberately does not double-emit the command's generic event.
+
+## Typed module events
+
+[`createModuleEvents`](../../node_modules/@open-mercato/shared/src/modules/events/factory.ts) adds `module` to definitions, registers IDs for runtime validation, and returns typed `eventsConfig.emit`. The emitted ID must be declared by that configuration.
+
+`eventsConfig.emit(eventId, payload, options)` delegates immediately to the bootstrapped event bus. It does not begin, join, or wait for a database transaction. Calling it before commit can publish an event for a write that later rolls back. Emit by call order only after the durable write succeeds, or use the post-write flow supplied by `runCrudCommandWrite`/the Data Engine. `clientBroadcast` and `portalBroadcast` are declaration flags, not transaction controls.
+
+## Optimistic locking
+
+[Command optimistic-lock helpers](../../node_modules/@open-mercato/shared/src/lib/crud/optimistic-lock-command.ts) normalize an explicit expected version or request header and compare it with actual `updated_at`. `assertOptimisticLock` does nothing when the token is absent or locking is disabled, and throws the shared 409 conflict on mismatch.
+
+`expected_updated_at` is an app convention, not inferred. Validate and pass it as `expected`; load and assert inside the mutation transaction. Return `updated_at`/`updatedAt` so the UI can send the version.
+
+## Defensive JSON reads
+
+[`readJsonSafe`](../../node_modules/@open-mercato/shared/src/lib/http/readJsonSafe.ts) accepts a `Request`, `Response`, or string and returns the supplied fallback for empty/invalid JSON. It is not schema validation: narrow or zod-parse its result.
+
+## Data Engine ORM operations
+
+[The Data Engine](../../node_modules/@open-mercato/shared/src/lib/data/engine.ts) provides `createOrmEntity`, `updateOrmEntity`, and `deleteOrmEntity` for generic ORM-backed mutation seams:
+
+- `createOrmEntity({ entity, data })` creates, persists, and flushes, then returns the entity.
+- `updateOrmEntity({ entity, where, apply })` loads one matching entity, returns `null` when absent, applies the callback, flushes, and returns the entity.
+- `deleteOrmEntity({ entity, where, soft, softDeleteField })` loads one matching entity, returns `null` when absent, then soft-deletes or removes and flushes.
+
+These helpers do not derive tenant/organization scope or automatically emit. The caller owns complete `where` scope and create fields. `markOrmEntityChange` queues event/index work, `flushOrmEntityChanges` drains it, and `emitOrmEntityEvent` emits directly. Drain only after the durable write; suppressed indexing must be rebuilt.
+
+## Escalation rule
+
+Start here, then the one exact linked file. If unanswered, invoke `om-framework-context` with a narrow query and report the installed version and limitation. Never copy a private implementation detail into an app contract.