@open-mercato/starter 0.6.5

package/src/infra.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Hybrid infra lifecycle: OpenCode + postgres/redis/meilisearch containers.
+// Preferred entry: `yarn om infra up|down` (or npx @open-mercato/starter).
+// Direct usage: node packages/starter/src/infra.mjs up [--profile <name>]
+//               node packages/starter/src/infra.mjs down [--volumes --yes]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { detectDocker, resolveRepoRoot, runCompose } from './compose.mjs'
+
+export function ensureMcpSharedDir(repoRoot) {
+  // Pre-create the bind-mount source so dockerd never creates it root-owned
+  // on native Linux (which would break host-side key provisioning).
+  fs.mkdirSync(path.join(repoRoot, '.mercato', 'mcp-shared'), { recursive: true })
+}
+
+export function infraUp(repoRooot, { profiles = [] } = {}) {
+  const repoRoot = repoRooot ?? resolveRepoRoot()
+  ensureMcpSharedDir(repoRoot)
+  const upArgs = []
+  for (const profile of profiles) {
+    upArgs.push('--profile', profile)
+  }
+  // --wait blocks on the postgres/redis/meilisearch healthchecks; opencode has
+  // no healthcheck here and counts as started immediately (its entrypoint
+  // waits for the host MCP server on its own). The opencode image is obtained
+  // beforehand (base pull + thin local build, see steps.mjs
+  // ensureOpencodeImage) — this file never builds.
+  upArgs.push('up', '-d', '--wait')
+  return runCompose(repoRoot, upArgs).status ?? 1
+}
+
+export function infraDown(repoRoot, { volumes = false } = {}) {
+  return runCompose(repoRoot ?? resolveRepoRoot(), ['down', ...(volumes ? ['--volumes'] : [])]).status ?? 1
+}
+
+function main() {
+  const args = process.argv.slice(2)
+  const action = args[0]
+  const repoRoot = resolveRepoRoot()
+  if (!repoRoot) {
+    console.error('❌ No Open Mercato checkout found above the current directory.')
+    process.exit(2)
+  }
+
+  const docker = detectDocker()
+  if (!docker.ok) {
+    console.error(`❌ Docker is not available (${docker.reason}).`)
+    console.error('   Install/start Docker Desktop, Rancher Desktop, or a native engine with the compose v2 plugin, then re-run.')
+    process.exit(2)
+  }
+
+  if (action === 'up') {
+    const profiles = []
+    for (let index = 1; index < args.length; index++) {
+      if (args[index] === '--profile' && args[index + 1]) {
+        profiles.push(args[index + 1])
+        index++
+      }
+    }
+    const status = infraUp(repoRoot, { build: !args.includes('--no-build'), profiles })
+    if (status === 0) {
+      console.log('')
+      console.log('✅ Infra containers are up (opencode :4096, postgres :5432, redis :6379, meilisearch :7700).')
+      console.log('   Next: yarn dev (starts the app and the MCP server on this machine)')
+    }
+    process.exit(status)
+  }
+
+  if (action === 'down') {
+    const volumes = args.includes('--volumes')
+    if (volumes && !args.includes('--yes')) {
+      console.error('❌ --volumes DELETES all database/search data. Re-run with --yes to confirm.')
+      process.exit(1)
+    }
+    process.exit(infraDown(repoRoot, { volumes }))
+  }
+
+  console.error('Usage: yarn om infra <up|down> [--profile <name>] [--volumes --yes]')
+  process.exit(1)
+}
+
+const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isDirectRun) main()

package/src/providers.mjs

@@ -0,0 +1,189 @@
+import fs from 'node:fs'
+import readline from 'node:readline'
+
+import { addEnvValue, readEnvValue, setEnvValue } from './env-file.mjs'
+import { secretFingerprint } from './secrets.mjs'
+
+// Every OM-supported chat provider (from apps/mercato/.env.example). This is
+// the SINGLE copy — the hand-synced PowerShell duplicate died with the old
+// Windows launcher. Embedding-only providers (Mistral, Cohere, AWS Bedrock)
+// are excluded — the assistant needs a chat model.
+export const LLM_PROVIDERS = [
+  { provider: 'openai', label: 'OpenAI', keyEnv: 'OPENAI_API_KEY', baseUrlEnv: 'OPENAI_BASE_URL', keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. gpt-5-mini' },
+  { provider: 'anthropic', label: 'Anthropic (Claude)', keyEnv: 'ANTHROPIC_API_KEY', baseUrlEnv: null, keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. claude-haiku-4-5-20251001' },
+  { provider: 'google', label: 'Google Gemini', keyEnv: 'GOOGLE_GENERATIVE_AI_API_KEY', baseUrlEnv: null, keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. gemini-3-flash' },
+  { provider: 'azure', label: 'Azure OpenAI / AI Foundry', keyEnv: 'AZURE_OPENAI_API_KEY', baseUrlEnv: 'AZURE_OPENAI_BASE_URL', keyRequired: true, baseUrlRequired: true, baseUrl: '', modelRequired: true, modelHint: 'your Azure deployment name' },
+  { provider: 'openrouter', label: 'OpenRouter (gateway)', keyEnv: 'OPENROUTER_API_KEY', baseUrlEnv: 'OPENROUTER_BASE_URL', keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. meta-llama/llama-3.3-70b-instruct' },
+  { provider: 'deepinfra', label: 'DeepInfra', keyEnv: 'DEEPINFRA_API_KEY', baseUrlEnv: 'DEEPINFRA_BASE_URL', keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. zai-org/GLM-5.1' },
+  { provider: 'groq', label: 'Groq', keyEnv: 'GROQ_API_KEY', baseUrlEnv: 'GROQ_BASE_URL', keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. llama-3.3-70b-versatile' },
+  { provider: 'together', label: 'Together AI', keyEnv: 'TOGETHER_API_KEY', baseUrlEnv: 'TOGETHER_BASE_URL', keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. meta-llama/Llama-3.3-70B-Instruct-Turbo' },
+  { provider: 'fireworks', label: 'Fireworks AI', keyEnv: 'FIREWORKS_API_KEY', baseUrlEnv: 'FIREWORKS_BASE_URL', keyRequired: true, baseUrlRequired: false, baseUrl: '', modelRequired: false, modelHint: 'e.g. accounts/fireworks/models/llama-v3p3-70b-instruct' },
+  { provider: 'litellm', label: 'LiteLLM (self-hosted proxy)', keyEnv: 'LITELLM_API_KEY', baseUrlEnv: 'LITELLM_BASE_URL', keyRequired: true, baseUrlRequired: true, baseUrl: '', modelRequired: true, modelHint: 'model name as configured in your proxy' },
+  { provider: 'ollama', label: 'Ollama (local)', keyEnv: 'OLLAMA_API_KEY', baseUrlEnv: 'OLLAMA_BASE_URL', keyRequired: false, baseUrlRequired: true, baseUrl: 'http://host.docker.internal:11434/v1', modelRequired: true, modelHint: 'e.g. llama3.3' },
+  { provider: 'lm-studio', label: 'LM Studio (local)', keyEnv: 'LM_STUDIO_API_KEY', baseUrlEnv: 'LM_STUDIO_BASE_URL', keyRequired: false, baseUrlRequired: true, baseUrl: 'http://host.docker.internal:1234/v1', modelRequired: true, modelHint: 'the loaded model id' },
+]
+
+function applyProviderConfig(rootEnv, entry, { key = '', baseUrl = '', model = '' }, log) {
+  if (key.trim()) {
+    if (addEnvValue(rootEnv, entry.keyEnv, key.trim(), { replaceEmpty: true })) {
+      log(`  set ${entry.keyEnv} (${secretFingerprint(key.trim())})`)
+    }
+  }
+  if (entry.baseUrlEnv && baseUrl.trim()) {
+    if (addEnvValue(rootEnv, entry.baseUrlEnv, baseUrl.trim(), { replaceEmpty: true })) {
+      log(`  set ${entry.baseUrlEnv}=${baseUrl.trim()}`)
+    }
+  }
+  if (addEnvValue(rootEnv, 'OM_AI_PROVIDER', entry.provider, { replaceEmpty: true })) {
+    log(`  set OM_AI_PROVIDER=${entry.provider}`)
+  }
+  if (model.trim()) {
+    if (addEnvValue(rootEnv, 'OM_AI_MODEL', model.trim(), { replaceEmpty: true })) {
+      log(`  set OM_AI_MODEL=${model.trim()}`)
+    }
+  }
+}
+
+// The root .env is the starter's source of truth for AI provider config: it
+// feeds the compose interpolation for the opencode container. The host app
+// only loads apps/mercato/.env, so the chosen provider must be mirrored there
+// too or the app keeps the .env.example defaults (provider 'openai' with an
+// empty key) and the selection silently "does not persist". Provider/model are
+// overwritten to converge on the root value; API keys and base URLs only fill
+// empty placeholders so a manually rotated app key is never clobbered.
+export function syncProviderConfigToAppEnv(files, log = console.log) {
+  if (!files.appEnv || !fs.existsSync(files.appEnv)) return
+  const provider = readEnvValue(files.rootEnv, 'OM_AI_PROVIDER')?.trim()
+  if (!provider) return
+  const entry = LLM_PROVIDERS.find((candidate) => candidate.provider === provider)
+  const overwriteKeys = ['OM_AI_PROVIDER', 'OM_AI_MODEL']
+  const fillKeys = entry ? [entry.keyEnv, ...(entry.baseUrlEnv ? [entry.baseUrlEnv] : [])] : []
+
+  for (const key of overwriteKeys) {
+    const value = readEnvValue(files.rootEnv, key)?.trim()
+    if (!value) continue
+    if (readEnvValue(files.appEnv, key)?.trim() === value) continue
+    setEnvValue(files.appEnv, key, value)
+    log(`  synced ${key} into apps/mercato/.env`)
+  }
+  for (const key of fillKeys) {
+    const value = readEnvValue(files.rootEnv, key)?.trim()
+    if (!value) continue
+    if (addEnvValue(files.appEnv, key, value, { replaceEmpty: true })) {
+      log(`  synced ${key} into apps/mercato/.env`)
+    }
+  }
+}
+
+function normalizeEnvTargets(rootEnvOrFiles) {
+  if (typeof rootEnvOrFiles === 'string') return { rootEnv: rootEnvOrFiles, appEnv: null }
+  return { rootEnv: rootEnvOrFiles.rootEnv, appEnv: rootEnvOrFiles.appEnv ?? null }
+}
+
+// Returns 'configured' | 'skipped' | 'failed'. Mirrors the semantics of the
+// Windows launcher's Invoke-LlmProviderPrompt: OM_AI_PROVIDER or an existing
+// key in .env means "already configured"; a key in the ambient environment is
+// persisted without prompting; otherwise prompt interactively unless
+// skip/non-interactive flags are set. Accepts the root .env path, or
+// { rootEnv, appEnv } to also keep the app env in sync (see
+// syncProviderConfigToAppEnv).
+export async function ensureLlmProvider(rootEnvOrFiles, { skipPrompt = false, nonInteractive = false, log = console.log, warn = console.warn } = {}) {
+  const files = normalizeEnvTargets(rootEnvOrFiles)
+  const rootEnv = files.rootEnv
+  const configuredProvider = readEnvValue(rootEnv, 'OM_AI_PROVIDER')
+  if (configuredProvider && configuredProvider.trim()) {
+    log(`AI already configured: provider '${configuredProvider.trim()}' (from .env)`)
+    syncProviderConfigToAppEnv(files, log)
+    return 'configured'
+  }
+
+  for (const entry of LLM_PROVIDERS) {
+    const fromFile = readEnvValue(rootEnv, entry.keyEnv)
+    if (fromFile && fromFile.trim()) {
+      log(`AI already configured: ${entry.label}`)
+      applyProviderConfig(rootEnv, entry, { key: '' }, log)
+      syncProviderConfigToAppEnv(files, log)
+      return 'configured'
+    }
+    const fromEnv = process.env[entry.keyEnv]
+    if (fromEnv && fromEnv.trim()) {
+      const baseFromEnv = entry.baseUrlEnv ? process.env[entry.baseUrlEnv] ?? '' : ''
+      applyProviderConfig(rootEnv, entry, { key: fromEnv, baseUrl: baseFromEnv }, log)
+      log(`AI configured from environment: ${entry.label}`)
+      syncProviderConfigToAppEnv(files, log)
+      return 'configured'
+    }
+  }
+
+  if (skipPrompt) {
+    warn('LLM prompt skipped with no provider key — AI chat will not work until you set a provider (e.g. OPENAI_API_KEY) in .env and restart the opencode container.')
+    return 'skipped'
+  }
+  if (nonInteractive || !process.stdin.isTTY) {
+    warn('No LLM provider API key found. Set a provider key (e.g. OPENAI_API_KEY) in the environment or .env, or pass --skip-llm-prompt to proceed without AI.')
+    return 'failed'
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const ask = (question) => new Promise((resolve) => rl.question(question, resolve))
+
+  try {
+    console.log('')
+    console.log('The AI assistant (OpenCode + MCP) needs one LLM provider to power the Cmd+K agent.')
+    console.log('Setup requires one to continue. (Ctrl+C aborts; re-run later with --skip-llm-prompt to configure it in .env yourself.)')
+
+    while (true) {
+      console.log('')
+      LLM_PROVIDERS.forEach((entry, index) => {
+        console.log(`  [${String(index + 1).padStart(2)}] ${entry.label}`)
+      })
+      const choice = await ask(`Choose a provider [1-${LLM_PROVIDERS.length}]: `)
+      const index = Number.parseInt(choice, 10)
+      if (!Number.isInteger(index) || index < 1 || index > LLM_PROVIDERS.length) {
+        console.log(`Please enter a number between 1 and ${LLM_PROVIDERS.length}.`)
+        continue
+      }
+      const selected = LLM_PROVIDERS[index - 1]
+
+      let key = ''
+      if (selected.keyRequired) {
+        key = (await ask(`Paste your ${selected.label} API key: `)).trim()
+        if (!key) {
+          console.log('A key is required for this provider. Try again.')
+          continue
+        }
+      } else {
+        key = (await ask(`${selected.label} API key (optional for local servers — press Enter to skip): `)).trim()
+      }
+
+      let baseUrl = ''
+      if (selected.baseUrlEnv) {
+        const promptText = selected.baseUrlRequired
+          ? (selected.baseUrl ? `${selected.label} base URL [${selected.baseUrl}]: ` : `${selected.label} base URL (required): `)
+          : `${selected.label} base URL (optional — press Enter for the provider default): `
+        const entered = (await ask(promptText)).trim()
+        baseUrl = entered || selected.baseUrl
+        if (selected.baseUrlRequired && !baseUrl) {
+          console.log('This provider requires a base URL. Try again.')
+          continue
+        }
+      }
+
+      const modelPrompt = selected.modelRequired
+        ? `${selected.label} model (${selected.modelHint}) (required): `
+        : `${selected.label} model (${selected.modelHint}) (optional — press Enter for the default): `
+      const model = (await ask(modelPrompt)).trim()
+      if (selected.modelRequired && !model) {
+        console.log('This provider needs a model/deployment id. Try again.')
+        continue
+      }
+
+      applyProviderConfig(rootEnv, selected, { key, baseUrl, model }, log)
+      log(`AI provider configured: ${selected.label}`)
+      syncProviderConfigToAppEnv(files, log)
+      return 'configured'
+    }
+  } finally {
+    rl.close()
+  }
+}

package/src/secrets.mjs

@@ -0,0 +1,11 @@
+import crypto from 'node:crypto'
+
+export function secretHex(bytes = 32) {
+  return crypto.randomBytes(bytes).toString('hex')
+}
+
+export function secretFingerprint(value) {
+  if (!value) return 'empty'
+  const digest = crypto.createHash('sha256').update(value).digest('hex')
+  return `sha256:${digest.slice(0, 12)}`
+}

package/src/spawn.mjs

@@ -0,0 +1,89 @@
+// Windows-aware spawn resolution, mirroring scripts/dev-spawn-utils.mjs (the
+// repo-wide hardening against cmd.exe argument injection) without its
+// cross-spawn dependency - this package must stay stdlib-only so it runs from
+// a fresh clone and via npx.
+//
+// yarn/npm/corepack are .cmd shims on Windows and Node >= 18.20 refuses to
+// spawn those without a shell. Going through cmd.exe means every byte of the
+// command line is metacharacter territory, so:
+//   * commands and args are validated (control chars always; %, !, and cmd
+//     metacharacters when a shell is involved)
+//   * args with whitespace are double-quoted
+// Anything that fails validation aborts the spawn instead of degrading into
+// an injectable command line.
+
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+
+const PROCESS_VALUE_UNSAFE_CHAR_PATTERN = /[\u0000-\u001f\u007f]/
+const WINDOWS_CMD_UNSAFE_CHAR_PATTERN = /[\u0000-\u001f\u007f%!^&|<>"]/
+
+const WINDOWS_SHELL_COMMANDS = new Set(['yarn', 'npm', 'corepack', 'npx'])
+
+function isWindowsShellCommand(command) {
+  return WINDOWS_SHELL_COMMANDS.has(command) || /\.(cmd|bat)$/i.test(command)
+}
+
+function assertProcessSafeValue(value, label) {
+  const stringValue = String(value)
+  if (PROCESS_VALUE_UNSAFE_CHAR_PATTERN.test(stringValue)) {
+    throw new Error(label + ' contains unsupported control characters.')
+  }
+  return stringValue
+}
+
+function assertWindowsCmdSafeValue(value, label) {
+  const stringValue = assertProcessSafeValue(value, label)
+  if (WINDOWS_CMD_UNSAFE_CHAR_PATTERN.test(stringValue)) {
+    throw new Error(label + ' contains unsupported characters for Windows command execution.')
+  }
+  return stringValue
+}
+
+function quoteForCmd(value) {
+  return /\s/.test(value) ? '"' + value + '"' : value
+}
+
+// cmd.exe decodes batch files with the code page the console had when the
+// cmd process started — never as UTF-8. Yarn Berry writes its temp PATH
+// wrappers and install-script shims (%TEMP%\xfs-*\*.cmd) as UTF-8 with
+// absolute paths, so under an OEM code page (e.g. 852 on Polish systems) a
+// checkout beneath a non-ASCII profile path turns into mojibake and every
+// wrapped spawn — including native-module builds during `yarn install` —
+// dies with MODULE_NOT_FOUND. Switching the console to UTF-8 before the
+// first child spawn makes every descendant cmd.exe decode those wrappers
+// correctly. Best-effort by design: no console (detached/CI) or a missing
+// chcp.com must never block the starter.
+export function ensureWindowsUtf8Console(options = {}) {
+  const platform = options.platform ?? process.platform
+  if (platform !== 'win32') return false
+  const spawnSyncImpl = options.spawnSyncImpl ?? spawnSync
+  const chcpPath = path.join(options.systemRoot ?? process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'chcp.com')
+  try {
+    // No windowsHide here: CREATE_NO_WINDOW would give chcp.com a throwaway
+    // console instead of the one every later child inherits.
+    const result = spawnSyncImpl(chcpPath, ['65001'], { stdio: 'ignore' })
+    return result?.status === 0
+  } catch {
+    return false
+  }
+}
+
+export function resolveSpawnCommand(command, commandArgs = [], options = {}) {
+  const platform = options.platform ?? process.platform
+  const safeCommand = assertProcessSafeValue(command, 'Process command')
+  const safeArgs = commandArgs.map((arg, index) => assertProcessSafeValue(arg, 'Process argument #' + (index + 1)))
+
+  const needsShell = platform === 'win32' && isWindowsShellCommand(safeCommand)
+  if (!needsShell) {
+    return { command: safeCommand, args: safeArgs, spawnOptions: {} }
+  }
+
+  // Everything is validated against cmd metacharacters and pre-quoted here, so
+  // hand cmd.exe ONE finished command line. Passing an args array alongside
+  // shell:true would make Node concatenate it unescaped (deprecated as DEP0190
+  // since Node 24 — the warning lands on stderr, which PowerShell paints red).
+  const cmdSafeCommand = quoteForCmd(assertWindowsCmdSafeValue(safeCommand, 'Windows command'))
+  const cmdSafeArgs = safeArgs.map((arg, index) => quoteForCmd(assertWindowsCmdSafeValue(arg, 'Windows command argument #' + (index + 1))))
+  return { command: [cmdSafeCommand, ...cmdSafeArgs].join(' '), args: [], spawnOptions: { shell: true } }
+}