@aopslab/domain-cli-docman 0.1.4

package/src/main.ts

@@ -0,0 +1,1747 @@
+#!/usr/bin/env node
+import './env-bootstrap.js'
+import { DEFAULT_TENANT_AS_UUID_STRING, sanitizeUrl } from '@aopslab/xf-core'
+import type {
+  DocmanCliCommandDescriptor,
+  DocmanCliManifestArtifact,
+  DocmanCliProjection,
+} from '@aopslab/domain-tooling-docman'
+import type { DomainRequest, DomainRouteManifestEntry } from '@aopslab/domain-host-plugin-docman'
+import { createDocmanCliCommandSurface } from './command-surface.js'
+import {
+  DEFAULT_DOCMAN_SCOPE_ID,
+  applyDocmanRuntimeEnv,
+  getDefaultDocmanSqlitePath,
+  getDefaultDocmanSqliteRepoUrl,
+  inferDocmanRepoDialect,
+  readDocmanCliStoredConfig,
+  resolveDocmanRuntimeConfig,
+  writeDocmanCliStoredConfig,
+} from './config-host.js'
+import { applyDocmanPgSchema } from '@aopslab/domain-pg-bootstrap-docman'
+import type {
+  DocmanCliStoredConfig,
+  DocmanRuntimeMode,
+  LoadedDocmanCliStoredConfig,
+} from './config-host.js'
+import type { DocmanExecutionMode, DocmanOperationSpec, OptionValue, ParsedArgv, RuntimeContext } from './cli-types.js'
+import { buildDocmanHostRegistrationManifest } from './host-registration.js'
+import { ensureDocmanSqliteSchemaReady } from './sqlite-bootstrap.js'
+import { existsSync, readFileSync } from 'node:fs'
+import os from 'node:os'
+import { resolve } from 'node:path'
+type DocmanHostRuntime = {
+  plugin: {
+    manifest: {
+      routes: DomainRouteManifestEntry[]
+    }
+    execute: (input: {
+      request: DomainRequest
+      match: { route: DomainRouteManifestEntry; params: Record<string, string> }
+    }) => Promise<unknown>
+  }
+  routesByOperationId: ReadonlyMap<string, DomainRouteManifestEntry>
+}
+
+type DocmanCliRuntimeModules = {
+  tooling: typeof import('@aopslab/domain-tooling-docman')
+  hostPlugin: typeof import('@aopslab/domain-host-plugin-docman')
+}
+
+const AOPS_CONFIG_FILENAME = 'aops.config.json'
+const HOST_CONFIG_FILENAME = 'host.config.json'
+const DIRECT_OPERATION_COMMANDS = new Set(['op', 'operation', 'run'])
+const RESERVED_NON_OPERATION_COMMANDS = new Set(['help', 'tools', 'ops', 'manifest', 'tool', 'invoke', 'config', 'init', 'setup'])
+const GENERATED_OPERATION_JSON_ARGS = new Set(['input', 'data', 'patch', 'filter', 'options', 'config'])
+const HOST_CONFIG_ENV_KEYS = ['DOCMAN_CLI_HOST_CONFIG_PATH', 'HOST_NODE_CONFIG'] as const
+const DOCMAN_ENV_SANITIZE_KEYS = [
+  'TENANT_ID',
+  'DOCMAN_SCOPE_ID',
+  'AOPS_PG_URL',
+  'DOCMAN_REPO_URL',
+  'DOCMAN_PG_URL',
+  'DOCMAN_SQLITE_URL',
+  'DOCUMENT_REPO_URL',
+  'DOCUMENT_GROUP_REPO_URL',
+  'DOCUMENT_VERSION_REPO_URL',
+  'SECTION_REPO_URL',
+  'PAGE_REPO_URL',
+  'PAGE_VERSION_REPO_URL',
+  'DOCUMENT_SECTION_LINK_REPO_URL',
+  'SECTION_PAGE_LINK_REPO_URL',
+  'SNIPPET_REPO_URL',
+  'PAGE_SNIPPET_LINK_REPO_URL',
+  'EMBED_REPO_URL',
+  'PAGE_EMBED_LINK_REPO_URL',
+] as const
+
+let docmanCliRuntimeModulesPromise: Promise<DocmanCliRuntimeModules> | null = null
+let docmanHostRuntimePromise: Promise<DocmanHostRuntime> | null = null
+let docmanCliPackageVersionCache: string | null = null
+
+async function getDocmanCliRuntimeModules(): Promise<DocmanCliRuntimeModules> {
+  if (docmanCliRuntimeModulesPromise) return docmanCliRuntimeModulesPromise
+
+  docmanCliRuntimeModulesPromise = (async () => {
+    const [tooling, hostPlugin] = await Promise.all([
+      import('@aopslab/domain-tooling-docman'),
+      import('@aopslab/domain-host-plugin-docman'),
+    ])
+    return { tooling, hostPlugin }
+  })()
+
+  return docmanCliRuntimeModulesPromise
+}
+
+function normalizeOptionKey(raw: string): string {
+  return raw.trim().replace(/^--+/, '').toLowerCase()
+}
+
+function pushOptionValue(target: Record<string, OptionValue>, key: string, value: OptionValue): void {
+  const existing = target[key]
+  if (existing === undefined) {
+    target[key] = value
+    return
+  }
+  if (Array.isArray(existing)) {
+    existing.push(String(value))
+    target[key] = existing
+    return
+  }
+  target[key] = [String(existing), String(value)]
+}
+
+function parseArgv(argv: string[]): ParsedArgv {
+  const positionals: string[] = []
+  const options: Record<string, OptionValue> = {}
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+    if (token === '--') continue
+
+    if (!token.startsWith('--')) {
+      positionals.push(token)
+      continue
+    }
+
+    const eqAt = token.indexOf('=')
+    if (eqAt > -1) {
+      const key = normalizeOptionKey(token.slice(0, eqAt))
+      const value = token.slice(eqAt + 1)
+      pushOptionValue(options, key, value)
+      continue
+    }
+
+    const key = normalizeOptionKey(token)
+    const next = argv[index + 1]
+    if (!next || next.startsWith('--')) {
+      pushOptionValue(options, key, true)
+      continue
+    }
+    pushOptionValue(options, key, next)
+    index += 1
+  }
+
+  return { positionals, options }
+}
+
+function getOptionValue(parsed: ParsedArgv, key: string): OptionValue | undefined {
+  return parsed.options[key]
+}
+
+function getStringOption(parsed: ParsedArgv, key: string): string | undefined {
+  const value = getOptionValue(parsed, key)
+  if (Array.isArray(value)) {
+    const last = value[value.length - 1]
+    return String(last).trim() || undefined
+  }
+  if (value === undefined || value === null || value === true || value === false) return undefined
+  const normalized = String(value).trim()
+  return normalized.length > 0 ? normalized : undefined
+}
+
+function getBooleanFromString(value: string, fallback: boolean): boolean {
+  const normalized = String(value).trim().toLowerCase()
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false
+  return fallback
+}
+
+function getBooleanOption(parsed: ParsedArgv, key: string, fallback = false): boolean {
+  const value = getOptionValue(parsed, key)
+  if (value === undefined) return fallback
+  if (Array.isArray(value)) return getBooleanFromString(value[value.length - 1], fallback)
+  if (typeof value === 'boolean') return value
+  return getBooleanFromString(value, fallback)
+}
+
+function getBooleanFromEnv(keys: readonly string[], fallback = false): boolean {
+  for (const key of keys) {
+    const value = normalizeNonEmptyString(process.env[key])
+    if (!value) continue
+    return getBooleanFromString(value, fallback)
+  }
+  return fallback
+}
+
+function getScopeIdOption(parsed: ParsedArgv): string | undefined {
+  return getStringOption(parsed, 'scope-id') ?? getStringOption(parsed, 'workspace-id')
+}
+
+function normalizeDocmanScopeId(value: unknown): string | undefined {
+  const normalized = normalizeNonEmptyString(value)
+  if (!normalized) return undefined
+  return normalized.toLowerCase() === 'default' ? DEFAULT_DOCMAN_SCOPE_ID : normalized
+}
+
+function areHooksDisabled(parsed: ParsedArgv): boolean {
+  if (getOptionValue(parsed, 'no-hook') !== undefined) {
+    return getBooleanOption(parsed, 'no-hook', false)
+  }
+  return getBooleanFromEnv(['DOCMAN_CLI_NO_HOOK', 'DOCMAN_CLI_DISABLE_HOOKS'], false)
+}
+
+function requireStringOption(parsed: ParsedArgv, key: string, label: string): string {
+  const value = getStringOption(parsed, key)
+  if (!value) {
+    throw new Error(`missing_required_option:${label}`)
+  }
+  return value
+}
+
+function parseJsonInput(raw: unknown, label: string): unknown {
+  if (raw === undefined || raw === null) return undefined
+  if (typeof raw !== 'string') return raw
+  const trimmed = raw.trim()
+  if (!trimmed) return undefined
+  if (trimmed.startsWith('@')) {
+    const filePath = trimmed.slice(1).trim()
+    if (!filePath) throw new Error(`invalid_json_${label}`)
+    const content = readFileSync(filePath, 'utf8')
+    return JSON.parse(content)
+  }
+  return JSON.parse(trimmed)
+}
+
+function normalizeIdentifier(value: string): string {
+  return String(value ?? '').trim().toLowerCase().replace(/^\/+/, '')
+}
+
+function normalizeOperationIdentifier(raw: string): string {
+  const normalized = raw
+    .trim()
+    .toLowerCase()
+    .replace(/^\/+/, '')
+    .replace(/^operations\//, '')
+    .replace(/^api\/docman\/operations\//, '')
+    .replace(/\//g, '.')
+    .replace(/\.+/g, '.')
+  if (!normalized) return normalized
+  return normalized.startsWith('docman.') ? normalized : `docman.${normalized}`
+}
+
+function toKebabCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[_\s.]+/g, '-')
+    .toLowerCase()
+}
+
+function toOptionKeyCandidatesFromArgName(argName: string): string[] {
+  const kebab = toKebabCase(argName)
+  const compact = kebab.replace(/-/g, '')
+  const lowered = argName.toLowerCase()
+  return [...new Set([kebab, compact, lowered])]
+}
+
+function getOptionValueByAnyKey(parsed: ParsedArgv, keys: string[]): OptionValue | undefined {
+  for (const key of keys) {
+    const value = getOptionValue(parsed, key)
+    if (value !== undefined) return value
+  }
+  return undefined
+}
+
+function splitCsvStrings(values: string[]): string[] {
+  return values
+    .flatMap((value) => value.split(','))
+    .map((value) => value.trim())
+    .filter(Boolean)
+}
+
+function tryParseBooleanToken(value: string): boolean | undefined {
+  const normalized = value.trim().toLowerCase()
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false
+  return undefined
+}
+
+function shouldTreatAsArrayArg(argName: string): boolean {
+  return argName.endsWith('Ids') || argName.endsWith('Paths')
+}
+
+function coerceOperationArgValue(raw: OptionValue, argName: string): unknown {
+  if (typeof raw === 'boolean') return raw
+
+  const argKey = argName.trim().toLowerCase()
+  const asArray = Array.isArray(raw) ? raw.map((item) => String(item)) : null
+  if (asArray) {
+    if (shouldTreatAsArrayArg(argName)) return splitCsvStrings(asArray)
+    if (GENERATED_OPERATION_JSON_ARGS.has(argKey) && asArray.length > 0) {
+      return parseJsonInput(asArray[asArray.length - 1], argName)
+    }
+    return asArray.map((item) => {
+      const boolValue = tryParseBooleanToken(item)
+      return boolValue ?? item
+    })
+  }
+
+  const value = String(raw).trim()
+  if (!value) return value
+  if (GENERATED_OPERATION_JSON_ARGS.has(argKey)) {
+    return parseJsonInput(value, argName)
+  }
+  if (shouldTreatAsArrayArg(argName)) {
+    return splitCsvStrings([value])
+  }
+  const boolValue = tryParseBooleanToken(value)
+  if (boolValue !== undefined) return boolValue
+  return value
+}
+
+async function resolveOperationIdentifier(
+  rawIdentifier: string,
+  operationMap: ReadonlyMap<string, DocmanOperationSpec>,
+): Promise<string | null> {
+  const { tooling } = await getDocmanCliRuntimeModules()
+
+  const resolvedByToolId = tooling.resolveDocmanOperationIdByToolId(rawIdentifier, { refresh: true })
+  if (resolvedByToolId) {
+    const normalizedByToolId = normalizeOperationIdentifier(resolvedByToolId)
+    if (operationMap.has(normalizedByToolId)) return normalizedByToolId
+  }
+
+  const normalized = normalizeOperationIdentifier(rawIdentifier)
+  if (normalized && operationMap.has(normalized)) return normalized
+
+  const spec = tooling.getDocmanOperationSpecById(rawIdentifier, { refresh: true })
+  if (!spec) return null
+  const normalizedFromSpec = normalizeOperationIdentifier(spec.operationId)
+  return operationMap.has(normalizedFromSpec) ? normalizedFromSpec : null
+}
+
+async function resolveGeneratedOperationId(
+  parsed: ParsedArgv,
+  operationMap: ReadonlyMap<string, DocmanOperationSpec>,
+): Promise<string | null> {
+  const command = parsed.positionals[0]?.toLowerCase()
+  const subcommand = parsed.positionals[1]?.toLowerCase()
+  if (!command) return null
+
+  if (DIRECT_OPERATION_COMMANDS.has(command)) {
+    const identifier = parsed.positionals[1] ?? getStringOption(parsed, 'id')
+    if (!identifier) throw new Error('missing_required_option:<operation-id-or-tool-id>')
+    const resolved = await resolveOperationIdentifier(identifier, operationMap)
+    if (!resolved) throw new Error(`unknown_docman_operation_identifier:${identifier}`)
+    return resolved
+  }
+
+  if (RESERVED_NON_OPERATION_COMMANDS.has(command)) return null
+
+  if (command.includes('.')) {
+    const direct = await resolveOperationIdentifier(command, operationMap)
+    if (direct) return direct
+  }
+
+  if (subcommand) {
+    const nested = normalizeOperationIdentifier(`${command}.${subcommand}`)
+    if (operationMap.has(nested)) return nested
+  }
+
+  const topLevel = normalizeOperationIdentifier(command)
+  if (operationMap.has(topLevel)) return topLevel
+
+  return null
+}
+
+function buildGeneratedOperationInput(
+  operation: DocmanOperationSpec,
+  parsed: ParsedArgv,
+  runtime: RuntimeContext,
+): Record<string, unknown> {
+  const explicitInput = parseJsonInput(getStringOption(parsed, 'input'), 'input')
+  if (explicitInput !== undefined) {
+    if (!explicitInput || typeof explicitInput !== 'object' || Array.isArray(explicitInput)) {
+      throw new Error('invalid_json_input:expected_object')
+    }
+    return explicitInput as Record<string, unknown>
+  }
+
+  const input: Record<string, unknown> = {}
+  for (const arg of operation.args) {
+    const rawValue = getOptionValueByAnyKey(parsed, toOptionKeyCandidatesFromArgName(arg.name))
+    if (rawValue === undefined) {
+      if (arg.name === 'scopeId') {
+        input.scopeId = runtime.scopeId
+        continue
+      }
+      if (arg.name === 'workspaceId') {
+        input.workspaceId = runtime.workspaceId
+        continue
+      }
+      if (!arg.optional) {
+        throw new Error(`missing_required_option:--${toKebabCase(arg.name)}`)
+      }
+      continue
+    }
+    input[arg.name] = coerceOperationArgValue(rawValue, arg.name)
+  }
+  return input
+}
+
+function printJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value === undefined ? null : value, null, 2)}\n`)
+}
+
+function printVersion(): void {
+  process.stdout.write(`${getDocmanCliPackageVersion()}\n`)
+}
+
+function printHelpLines(lines: string[]): void {
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+function appendTextSection(target: string[], title: string, lines: string[]): void {
+  const normalized = lines.map((line) => String(line ?? '').trimEnd()).filter(Boolean)
+  if (normalized.length === 0) return
+  if (target.length > 0 && target[target.length - 1] !== '') target.push('')
+  target.push(`${title}:`)
+  for (const line of normalized) {
+    target.push(`  ${line}`)
+  }
+}
+
+function toStringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value
+    .map((entry) => String(entry ?? '').trim())
+    .filter(Boolean)
+}
+
+function renderCommandDescriptor(descriptor: DocmanCliCommandDescriptor): string[] {
+  const lines = [descriptor.title]
+  for (const section of descriptor.sections) {
+    appendTextSection(lines, section.title, section.lines)
+  }
+  return lines
+}
+
+function buildStandaloneInitHelpLines(): string[] {
+  return [
+    'docman init',
+    '',
+    'Purpose:',
+    '  Initialize standalone Docman runtime config for the local operator flow.',
+    '',
+    'Usage:',
+    '  docman init [--runtime-mode single-user] [--repo-url <url>] [--scope-id <id>] [--json]',
+    '',
+    'Notes:',
+    '  - Defaults to single-user mode.',
+    '  - Defaults repo URL to ~/.aops/docman.aops.sqlite.',
+    `  - Defaults scope id to global default scope ${DEFAULT_DOCMAN_SCOPE_ID}.`,
+    '  - Ensures SQLite schema readiness when the resolved repo dialect is SQLite.',
+  ]
+}
+
+function buildStandaloneSetupHelpLines(): string[] {
+  return [
+    'docman setup runtime',
+    '',
+    'Purpose:',
+    '  Update standalone Docman runtime storage and bootstrap state.',
+    '',
+    'Usage:',
+    '  docman setup runtime [--runtime-mode single-user|multi-user] [--repo-url <url>] [--scope-id <id>] [--json]',
+    '',
+    'Notes:',
+    '  - This command is rerunnable.',
+    '  - SQLite repos are bootstrapped automatically.',
+    '  - Desktop host reads the same persisted config owner as the CLI.',
+  ]
+}
+
+function findCommandDescriptorById(
+  projection: DocmanCliProjection,
+  id: string,
+): DocmanCliCommandDescriptor | null {
+  return projection.commandsById[id] ?? null
+}
+
+async function buildCliProjection(): Promise<DocmanCliProjection> {
+  const { tooling } = await getDocmanCliRuntimeModules()
+  return tooling.buildDocmanCliProjection({ refresh: true })
+}
+
+function toProjectionOperationId(operationId: string): string {
+  return normalizeOperationIdentifier(operationId).replace(/^docman\./, '')
+}
+
+function normalizeManifestHelpSubcommand(subcommand: string | undefined): string | undefined {
+  if (!subcommand) return undefined
+  if (subcommand === 'hrm') return 'host-registration'
+  if (subcommand === 'operations') return 'ops'
+  return subcommand
+}
+
+async function printHelp(): Promise<void> {
+  const projection = await buildCliProjection()
+  const descriptor = findCommandDescriptorById(projection, 'docman')
+  if (!descriptor) {
+    throw new Error('missing_cli_help_root')
+  }
+  const lines = renderCommandDescriptor(descriptor)
+  lines.push(
+    '',
+    'Standalone setup commands:',
+    '  docman init',
+    '  docman setup runtime',
+  )
+  printHelpLines(lines)
+}
+
+async function tryPrintCommandHelp(parsed: ParsedArgv): Promise<boolean> {
+  const command = parsed.positionals[0]?.toLowerCase()
+  const subcommand = normalizeManifestHelpSubcommand(parsed.positionals[1]?.toLowerCase())
+
+  if (!command) return false
+
+  const projection = await buildCliProjection()
+  const renderDescriptor = (id: string, trailingMessage?: string): boolean => {
+    const descriptor = findCommandDescriptorById(projection, id)
+    if (!descriptor) return false
+    const lines = renderCommandDescriptor(descriptor)
+    if (trailingMessage) {
+      lines.push('', trailingMessage)
+    }
+    printHelpLines(lines)
+    return true
+  }
+
+  if (command === 'version') return renderDescriptor('version')
+  if (command === 'init') {
+    printHelpLines(buildStandaloneInitHelpLines())
+    return true
+  }
+  if (command === 'setup') {
+    printHelpLines(buildStandaloneSetupHelpLines())
+    return true
+  }
+  if (command === 'config') {
+    if (subcommand === 'show') return renderDescriptor('config.show')
+    if (subcommand === 'set') return renderDescriptor('config.set')
+    return renderDescriptor('config')
+  }
+  if (command === 'manifest') {
+    if (!subcommand) return renderDescriptor('manifest')
+    if (subcommand === 'get') return renderDescriptor('manifest.get')
+    if (subcommand === 'show') return renderDescriptor('manifest.show')
+    if (subcommand === 'dcm') return renderDescriptor('manifest.dcm')
+    if (subcommand === 'routes') return renderDescriptor('manifest.routes')
+    if (subcommand === 'agent') return renderDescriptor('manifest.agent')
+    if (subcommand === 'cli') return renderDescriptor('manifest.cli')
+    if (subcommand === 'host-registration') return renderDescriptor('manifest.host-registration')
+    if (subcommand === 'ops') return renderDescriptor('manifest.ops')
+    return renderDescriptor('manifest')
+  }
+  if (command === 'tools') return renderDescriptor('tools')
+  if (command === 'ops') return renderDescriptor('ops')
+  if (command === 'tool' || command === 'invoke') {
+    const { tooling } = await getDocmanCliRuntimeModules()
+    const identifier = getStringOption(parsed, 'id')
+    if (!identifier) return renderDescriptor('tool')
+    const spec = tooling.getDocmanOperationSpecById(identifier, { refresh: true })
+    if (!spec) {
+      return renderDescriptor('tool', `Unknown tool or operation id: ${identifier}`)
+    }
+    return renderDescriptor(toProjectionOperationId(spec.operationId))
+  }
+  if (DIRECT_OPERATION_COMMANDS.has(command)) {
+    const { tooling } = await getDocmanCliRuntimeModules()
+    const identifier = parsed.positionals[1] ?? getStringOption(parsed, 'id')
+    if (!identifier) return renderDescriptor('op')
+    const spec = tooling.getDocmanOperationSpecById(identifier, { refresh: true })
+    if (!spec) {
+      return renderDescriptor('op', `Unknown operation or tool id: ${identifier}`)
+    }
+    return renderDescriptor(toProjectionOperationId(spec.operationId))
+  }
+
+  const { tooling } = await getDocmanCliRuntimeModules()
+  const operationSpecs = tooling.listDocmanToolingOperations({ refresh: true })
+  const operationMap = new Map(
+    operationSpecs.map((operation) => [normalizeOperationIdentifier(operation.operationId), operation]),
+  )
+  const resolvedOperationId = await resolveGeneratedOperationId(parsed, operationMap)
+  if (!resolvedOperationId) return false
+  return renderDescriptor(toProjectionOperationId(resolvedOperationId))
+}
+
+function normalizeNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const normalized = value.trim()
+  return normalized.length > 0 ? normalized : undefined
+}
+
+function normalizeRepoUrlValue(value: unknown): string | undefined {
+  const normalized = normalizeNonEmptyString(value)
+  if (!normalized) return undefined
+  return normalized.replace(/(?:\\r|\r)+$/g, '')
+}
+
+function normalizeRuntimeMode(value: unknown): DocmanRuntimeMode | undefined {
+  const normalized = normalizeNonEmptyString(value)?.toLowerCase()
+  if (!normalized) return undefined
+  if (normalized === 'single-user' || normalized === 'single_user' || normalized === 'single') {
+    return 'single-user'
+  }
+  if (normalized === 'multi-user' || normalized === 'multi_user' || normalized === 'multi') {
+    return 'multi-user'
+  }
+  return undefined
+}
+
+function getDocmanCliPackageVersion(): string {
+  if (docmanCliPackageVersionCache) return docmanCliPackageVersionCache
+
+  try {
+    const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
+      version?: unknown
+    }
+    docmanCliPackageVersionCache = normalizeNonEmptyString(packageJson.version) ?? '0.0.0'
+  } catch {
+    docmanCliPackageVersionCache = '0.0.0'
+  }
+
+  return docmanCliPackageVersionCache
+}
+
+function toRecord(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return {}
+  return input as Record<string, unknown>
+}
+
+function resolveHomeDirectory(processEnv: NodeJS.ProcessEnv): string {
+  const envHome =
+    normalizeNonEmptyString(processEnv.HOME)
+    ?? normalizeNonEmptyString(processEnv.USERPROFILE)
+  return resolve(envHome ?? os.homedir())
+}
+
+function resolveExecutionMode(): DocmanExecutionMode {
+  const configured = normalizeNonEmptyString(process.env.DOCMAN_CLI_EXECUTION_MODE)?.toLowerCase()
+  if (configured === 'tooling') return 'tooling'
+  return 'host'
+}
+
+function sanitizeBlankEnvValues(processEnv: NodeJS.ProcessEnv): void {
+  for (const key of DOCMAN_ENV_SANITIZE_KEYS) {
+    if (typeof processEnv[key] === 'string' && processEnv[key]?.trim() === '') {
+      delete processEnv[key]
+    }
+  }
+}
+
+function buildHostRequestContext(): DomainRequest['context'] {
+  const scopeId =
+    normalizeDocmanScopeId(process.env.DOCMAN_SCOPE_ID)
+    ?? normalizeDocmanScopeId(process.env.DOCMAN_WORKSPACE_ID)
+    ?? DEFAULT_DOCMAN_SCOPE_ID
+  return {
+    tenantId: normalizeNonEmptyString(process.env.TENANT_ID) ?? DEFAULT_TENANT_AS_UUID_STRING,
+    scopeId,
+    workspaceId: normalizeDocmanScopeId(process.env.DOCMAN_WORKSPACE_ID) ?? scopeId,
+    locale: normalizeNonEmptyString(process.env.DOCMAN_LOCALE) ?? 'tr',
+    fallbackLocale: normalizeNonEmptyString(process.env.DOCMAN_FALLBACK_LOCALE) ?? 'en',
+    principal: null,
+  }
+}
+
+function patternToPathSegments(pattern: string, params: Record<string, string>): string[] {
+  const raw = pattern.trim().replace(/^\/+|\/+$/g, '')
+  if (!raw) return []
+  const output: string[] = []
+  const segments = raw.split('/').map((segment) => segment.trim()).filter(Boolean)
+  for (const patternSegment of segments) {
+    if (patternSegment === '*') {
+      const splat = normalizeNonEmptyString(params.splat)
+      if (!splat) continue
+      output.push(...splat.split('/').map((part) => encodeURIComponent(part)))
+      continue
+    }
+    if (patternSegment.startsWith(':')) {
+      const key = patternSegment.slice(1).trim()
+      const value = normalizeNonEmptyString(params[key])
+      if (!key || !value) {
+        throw new Error(`missing_required_arg:${key || 'path'}`)
+      }
+      output.push(encodeURIComponent(value))
+      continue
+    }
+    output.push(patternSegment)
+  }
+  return output
+}
+
+function resolveRouteParams(route: DomainRouteManifestEntry, input: unknown): Record<string, string> {
+  const inputRecord = toRecord(input)
+  const pathParamCandidates = toRecord(inputRecord.pathParams)
+  const params: Record<string, string> = {}
+  const segments = route.pattern
+    .trim()
+    .replace(/^\/+|\/+$/g, '')
+    .split('/')
+    .map((segment: string) => segment.trim())
+    .filter(Boolean)
+
+  for (const segment of segments) {
+    if (segment === '*') {
+      const splatValue = normalizeNonEmptyString(pathParamCandidates.splat) ?? normalizeNonEmptyString(inputRecord.splat)
+      if (splatValue) params.splat = splatValue
+      continue
+    }
+    if (!segment.startsWith(':')) continue
+    const key = segment.slice(1).trim()
+    if (!key) continue
+    const value = normalizeNonEmptyString(pathParamCandidates[key]) ?? normalizeNonEmptyString(inputRecord[key])
+    if (!value) {
+      throw new Error(`missing_required_arg:${key}`)
+    }
+    params[key] = value
+  }
+
+  return params
+}
+
+function buildHostDomainRequest(
+  route: DomainRouteManifestEntry,
+  pathSegments: string[],
+  input: unknown,
+): DomainRequest {
+  const baseUrl = `https://docman-cli.local/api/docman${pathSegments.length > 0 ? `/${pathSegments.join('/')}` : ''}`
+  return {
+    method: route.method,
+    domain: 'docman',
+    path: pathSegments,
+    query: new URLSearchParams(),
+    body: input,
+    headers: new Headers(),
+    url: new URL(baseUrl),
+    context: buildHostRequestContext(),
+  }
+}
+
+async function getDocmanHostRuntime(): Promise<DocmanHostRuntime> {
+  if (docmanHostRuntimePromise) return docmanHostRuntimePromise
+
+  docmanHostRuntimePromise = (async () => {
+    const { hostPlugin } = await getDocmanCliRuntimeModules()
+    const plugin = hostPlugin.createDocmanPlugin({
+      defaultScopeId: normalizeNonEmptyString(process.env.DOCMAN_SCOPE_ID),
+    })
+    const routesByOperationId = new Map<string, DomainRouteManifestEntry>()
+    for (const route of plugin.manifest.routes) {
+      const normalizedOperationId = normalizeOperationIdentifier(route.operation)
+      if (!normalizedOperationId) continue
+      routesByOperationId.set(normalizedOperationId, route)
+    }
+    return { plugin, routesByOperationId }
+  })()
+
+  return docmanHostRuntimePromise
+}
+
+async function resolveOperationIdFromIdentifier(identifier: string): Promise<string | null> {
+  const { tooling } = await getDocmanCliRuntimeModules()
+  const normalizedDirect = normalizeOperationIdentifier(identifier)
+  const directSpec = tooling.getDocmanOperationSpecById(normalizedDirect || identifier, { refresh: true })
+  if (directSpec) return normalizeOperationIdentifier(directSpec.operationId)
+
+  const resolvedByAlias = tooling.resolveDocmanOperationIdByToolId(identifier, { refresh: true })
+  if (resolvedByAlias) return normalizeOperationIdentifier(resolvedByAlias)
+
+  return null
+}
+
+async function runDocmanOperationById(operationId: string, input: unknown = {}): Promise<unknown> {
+  const { tooling } = await getDocmanCliRuntimeModules()
+  if (resolveExecutionMode() === 'tooling') {
+    return tooling.runDocmanOperationById(operationId, input, { refresh: true })
+  }
+
+  const runtime = await getDocmanHostRuntime()
+  const normalizedOperationId = normalizeOperationIdentifier(operationId)
+  const route = runtime.routesByOperationId.get(normalizedOperationId)
+  if (!route) {
+    return tooling.runDocmanOperationById(operationId, input, { refresh: true })
+  }
+
+  const params = resolveRouteParams(route, input)
+  const path = patternToPathSegments(route.pattern, params)
+  const request = buildHostDomainRequest(route, path, input)
+  return runtime.plugin.execute({
+    request,
+    match: { route, params },
+  })
+}
+
+async function runDocmanToolById(identifier: string, input: unknown = {}): Promise<unknown> {
+  const { tooling } = await getDocmanCliRuntimeModules()
+  if (resolveExecutionMode() === 'tooling') {
+    return tooling.runDocmanToolById(identifier, input, { refresh: true })
+  }
+  const operationId = await resolveOperationIdFromIdentifier(identifier)
+  if (!operationId) {
+    return tooling.runDocmanToolById(identifier, input, { refresh: true })
+  }
+  return runDocmanOperationById(operationId, input)
+}
+
+function resolveOptionalHostConfigPath(
+  parsed: ParsedArgv,
+  processEnv: NodeJS.ProcessEnv,
+  storedConfig: DocmanCliStoredConfig,
+): string | null {
+  const optionPathRaw = normalizeNonEmptyString(getStringOption(parsed, 'host-config'))
+  if (optionPathRaw) {
+    const resolvedOptionPath = resolve(optionPathRaw)
+    if (existsSync(resolvedOptionPath)) return resolvedOptionPath
+    const candidateFile = resolvedOptionPath.toLowerCase().endsWith('.json')
+      ? resolvedOptionPath
+      : resolve(resolvedOptionPath, HOST_CONFIG_FILENAME)
+    if (existsSync(candidateFile)) return candidateFile
+    throw new Error(`host_config_not_found:${optionPathRaw}`)
+  }
+
+  for (const envKey of HOST_CONFIG_ENV_KEYS) {
+    const envValue = normalizeNonEmptyString(processEnv[envKey])
+    if (!envValue) continue
+    const resolvedEnvPath = resolve(envValue)
+    if (existsSync(resolvedEnvPath)) return resolvedEnvPath
+    const candidateFile = resolvedEnvPath.toLowerCase().endsWith('.json')
+      ? resolvedEnvPath
+      : resolve(resolvedEnvPath, HOST_CONFIG_FILENAME)
+    if (existsSync(candidateFile)) return candidateFile
+  }
+
+  const storedPathRaw = normalizeNonEmptyString(storedConfig.hostConfigPath)
+  if (storedPathRaw) {
+    const resolvedStoredPath = resolve(storedPathRaw)
+    if (existsSync(resolvedStoredPath)) return resolvedStoredPath
+    const candidateFile = resolvedStoredPath.toLowerCase().endsWith('.json')
+      ? resolvedStoredPath
+      : resolve(resolvedStoredPath, HOST_CONFIG_FILENAME)
+    if (existsSync(candidateFile)) return candidateFile
+  }
+
+  const localCandidate = resolve(process.cwd(), HOST_CONFIG_FILENAME)
+  if (existsSync(localCandidate)) return localCandidate
+  return null
+}
+
+function resolveConfigBindingValue(binding: unknown, processEnv: NodeJS.ProcessEnv): string | undefined {
+  const direct = normalizeNonEmptyString(binding)
+  if (direct) return direct
+
+  const bindingRecord = toRecord(binding)
+  const fromEnv = normalizeNonEmptyString(bindingRecord.fromEnv)
+  if (fromEnv) {
+    const envValue = normalizeNonEmptyString(processEnv[fromEnv])
+    if (envValue) return envValue
+  }
+  return normalizeNonEmptyString(bindingRecord.value) ?? normalizeNonEmptyString(bindingRecord.default)
+}
+
+function applyOptionalHostRuntimeEnv(
+  parsed: ParsedArgv,
+  processEnv: NodeJS.ProcessEnv,
+  storedConfig: DocmanCliStoredConfig,
+): void {
+  const hostConfigPath = resolveOptionalHostConfigPath(parsed, processEnv, storedConfig)
+  if (!hostConfigPath) return
+
+  let config: Record<string, unknown> = {}
+  try {
+    config = toRecord(JSON.parse(readFileSync(hostConfigPath, 'utf8')))
+  } catch (error) {
+    throw new Error(`host_config_parse_failed:${hostConfigPath}:${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  const runtimeEnv = toRecord(toRecord(config.runtime).env)
+  for (const [targetKeyRaw, binding] of Object.entries(runtimeEnv)) {
+    const targetKey = targetKeyRaw.trim()
+    if (!targetKey) continue
+    if (targetKey.toUpperCase() === 'DOCMAN_REPO_URL') {
+      continue
+    }
+    const resolved = resolveConfigBindingValue(binding, processEnv)
+    if (resolved !== undefined) {
+      process.env[targetKey] = resolved
+    }
+  }
+}
+
+function resolveAopsConfigFilePath(processEnv: NodeJS.ProcessEnv): string {
+  const configPathRaw = processEnv.AOPS_CLI_CONFIG_PATH ?? processEnv.AGENT_OPS_CONFIG_PATH
+  const configPath = typeof configPathRaw === 'string' ? configPathRaw.trim() : ''
+
+  if (configPath.length > 0) {
+    const resolvedPath = resolve(configPath)
+    if (resolvedPath.toLowerCase().endsWith('.json')) {
+      return resolvedPath
+    }
+    return resolve(resolvedPath, AOPS_CONFIG_FILENAME)
+  }
+
+  return resolve(resolveHomeDirectory(processEnv), '.aops', AOPS_CONFIG_FILENAME)
+}
+
+function readAopsConfig(processEnv: NodeJS.ProcessEnv): Record<string, unknown> {
+  const configPath = resolveAopsConfigFilePath(processEnv)
+  if (!existsSync(configPath)) return {}
+  try {
+    const content = readFileSync(configPath, 'utf8')
+    return toRecord(JSON.parse(content))
+  } catch {
+    return {}
+  }
+}
+
+function resolveConfiguredDocmanRepoUrl(processEnv: NodeJS.ProcessEnv): string | undefined {
+  const config = readAopsConfig(processEnv)
+
+  const topLevel =
+    normalizeRepoUrlValue(config.docmanPgUrl) ??
+    normalizeRepoUrlValue(config.docmanSqliteUrl) ??
+    normalizeRepoUrlValue(config.docmanRepoUrl) ??
+    normalizeRepoUrlValue(config.DOCMAN_PG_URL) ??
+    normalizeRepoUrlValue(config.DOCMAN_SQLITE_URL) ??
+    normalizeRepoUrlValue(config.DOCMAN_REPO_URL)
+  if (topLevel) return topLevel
+
+  const docmanConfig = toRecord(config.docman)
+  const docmanLevel =
+    normalizeRepoUrlValue(docmanConfig.pgUrl) ??
+    normalizeRepoUrlValue(docmanConfig.sqliteUrl) ??
+    normalizeRepoUrlValue(docmanConfig.repoUrl) ??
+    normalizeRepoUrlValue(docmanConfig.repositoryUrl) ??
+    normalizeRepoUrlValue(docmanConfig.dbUrl)
+  if (docmanLevel) return docmanLevel
+
+  const runtimeEnv = toRecord(toRecord(config.runtime).env)
+  const runtimeValue =
+    resolveConfigBindingValue(runtimeEnv.DOCMAN_PG_URL, processEnv) ??
+    resolveConfigBindingValue(runtimeEnv.DOCMAN_SQLITE_URL, processEnv) ??
+    resolveConfigBindingValue(runtimeEnv.DOCMAN_REPO_URL, processEnv)
+  if (runtimeValue) return runtimeValue
+
+  const envSection = toRecord(config.env)
+  return normalizeRepoUrlValue(resolveConfigBindingValue(envSection.DOCMAN_PG_URL, processEnv))
+    ?? normalizeRepoUrlValue(resolveConfigBindingValue(envSection.DOCMAN_SQLITE_URL, processEnv))
+    ?? normalizeRepoUrlValue(resolveConfigBindingValue(envSection.DOCMAN_REPO_URL, processEnv))
+}
+
+function inferDefaultRepoUrl(processEnv: NodeJS.ProcessEnv): string {
+  const configuredRepoUrl = resolveConfiguredDocmanRepoUrl(processEnv)
+  if (configuredRepoUrl) return configuredRepoUrl
+  return getDefaultDocmanSqliteRepoUrl(processEnv)
+}
+
+function maskRepoUrlForDisplay(repoUrl: unknown): string | undefined {
+  const normalized = normalizeRepoUrlValue(repoUrl)
+  if (!normalized) return undefined
+  if (inferDocmanRepoDialect(normalized) === 'sqlite') return normalized
+  return sanitizeUrl(normalized)
+}
+
+function maskStoredConfigForDisplay(stored: DocmanCliStoredConfig): Record<string, unknown> {
+  const output: Record<string, unknown> = {
+    ...stored,
+    ...(stored.repoUrl ? { repoUrl: maskRepoUrlForDisplay(stored.repoUrl) } : {}),
+  }
+  return output
+}
+
+function buildConfigSetOutput(stored: LoadedDocmanCliStoredConfig): Record<string, unknown> {
+  return {
+    configPath: stored.path,
+    exists: stored.exists,
+    stored: maskStoredConfigForDisplay(stored.config),
+  }
+}
+
+function buildConfigShowOutput(processEnv: NodeJS.ProcessEnv): Record<string, unknown> {
+  const loaded = readDocmanCliStoredConfig(processEnv)
+  const stored = loaded.config
+  const defaultSqlitePath = getDefaultDocmanSqlitePath(processEnv)
+  const defaultSqliteRepoUrl = getDefaultDocmanSqliteRepoUrl(processEnv)
+
+  const envRepoUrl =
+    normalizeRepoUrlValue(processEnv.DOCMAN_REPO_URL)
+    ?? normalizeRepoUrlValue(processEnv.DOCMAN_SQLITE_URL)
+    ?? normalizeRepoUrlValue(processEnv.DOCMAN_PG_URL)
+  const envRepoUrlBootstrapSource = normalizeNonEmptyString(processEnv.DOCMAN_CLI_BOOTSTRAPPED_REPO_URL_SOURCE)
+  const envTenantId = normalizeNonEmptyString(processEnv.TENANT_ID)
+  const envScopeId =
+    normalizeDocmanScopeId(processEnv.DOCMAN_SCOPE_ID)
+    ?? normalizeDocmanScopeId(processEnv.DOCMAN_WORKSPACE_ID)
+  const envRuntimeMode = normalizeRuntimeMode(processEnv.DOCMAN_RUNTIME_MODE)
+  const envLogLevel = normalizeNonEmptyString(processEnv.LOG_LEVEL)
+  const envExecutionModeRaw = normalizeNonEmptyString(processEnv.DOCMAN_CLI_EXECUTION_MODE)?.toLowerCase()
+  const envExecutionMode =
+    envExecutionModeRaw === 'host' || envExecutionModeRaw === 'tooling'
+      ? envExecutionModeRaw
+      : undefined
+  const envHostConfigPath =
+    normalizeNonEmptyString(processEnv.DOCMAN_CLI_HOST_CONFIG_PATH)
+    ?? normalizeNonEmptyString(processEnv.HOST_NODE_CONFIG)
+
+  const aopsConfigRepoUrl = resolveConfiguredDocmanRepoUrl(processEnv)
+  const effectiveRepoUrl = envRepoUrl ?? stored.repoUrl ?? aopsConfigRepoUrl ?? defaultSqliteRepoUrl
+
+  return {
+    configPath: loaded.path,
+    exists: loaded.exists,
+    stored: maskStoredConfigForDisplay(stored),
+    defaults: {
+      aopsConfigRepoUrl: maskRepoUrlForDisplay(aopsConfigRepoUrl) ?? null,
+      defaultSqlitePath,
+      defaultSqliteRepoUrl,
+    },
+    effective: {
+      repoUrl: maskRepoUrlForDisplay(effectiveRepoUrl) ?? null,
+      repoUrlSource:
+        envRepoUrl
+          ? envRepoUrlBootstrapSource === 'stored-config'
+            ? 'stored-config'
+            : 'env'
+          : stored.repoUrl
+            ? 'stored-config'
+            : aopsConfigRepoUrl
+              ? 'aops-config'
+              : 'default-sqlite',
+      runtimeMode: envRuntimeMode ?? stored.runtimeMode ?? 'single-user',
+      runtimeModeSource: envRuntimeMode ? 'env' : stored.runtimeMode ? 'stored-config' : 'default',
+      executionMode: envExecutionMode ?? stored.executionMode ?? 'host',
+      executionModeSource: envExecutionMode ? 'env' : stored.executionMode ? 'stored-config' : 'default',
+      scopeId: envScopeId ?? stored.scopeId ?? DEFAULT_DOCMAN_SCOPE_ID,
+      scopeIdSource: envScopeId ? 'env' : stored.scopeId ? 'stored-config' : 'default',
+      tenantId: envTenantId ?? stored.tenantId ?? DEFAULT_TENANT_AS_UUID_STRING,
+      tenantIdSource: envTenantId ? 'env' : stored.tenantId ? 'stored-config' : 'default',
+      logLevel: envLogLevel ?? stored.logLevel ?? null,
+      logLevelSource: envLogLevel ? 'env' : stored.logLevel ? 'stored-config' : 'unset',
+      hostConfigPath: envHostConfigPath ?? stored.hostConfigPath ?? null,
+      hostConfigPathSource: envHostConfigPath ? 'env' : stored.hostConfigPath ? 'stored-config' : 'unset',
+    },
+  }
+}
+
+async function buildRuntimeContext(parsed: ParsedArgv): Promise<RuntimeContext> {
+  sanitizeBlankEnvValues(process.env)
+  const storedConfig = readDocmanCliStoredConfig(process.env).config
+
+  const executionMode = getStringOption(parsed, 'execution-mode')
+  if (executionMode) {
+    const normalizedMode = executionMode.trim().toLowerCase()
+    if (normalizedMode === 'host' || normalizedMode === 'tooling') {
+      process.env.DOCMAN_CLI_EXECUTION_MODE = normalizedMode
+    } else {
+      throw new Error(`invalid_execution_mode:${executionMode}`)
+    }
+  } else if (!normalizeNonEmptyString(process.env.DOCMAN_CLI_EXECUTION_MODE) && storedConfig.executionMode) {
+    process.env.DOCMAN_CLI_EXECUTION_MODE = storedConfig.executionMode
+  }
+
+  applyOptionalHostRuntimeEnv(parsed, process.env, storedConfig)
+
+  const runtimeConfig = resolveDocmanRuntimeConfig(
+    {
+      runtimeMode: getStringOption(parsed, 'runtime-mode'),
+      repoUrl: normalizeRepoUrlValue(getStringOption(parsed, 'repo-url')),
+      scopeId: getScopeIdOption(parsed),
+    },
+    process.env,
+  )
+
+  const resolvedRepoUrl =
+    runtimeConfig.repoUrlSource === 'default-sqlite'
+      ? resolveConfiguredDocmanRepoUrl(process.env) ?? runtimeConfig.repoUrl
+      : runtimeConfig.repoUrl
+
+  if (!normalizeNonEmptyString(resolvedRepoUrl)) {
+    throw new Error('missing_repo_url:empty')
+  }
+
+  const repoDialect = inferDocmanRepoDialect(resolvedRepoUrl)
+  applyDocmanRuntimeEnv(
+    {
+      runtimeMode: runtimeConfig.runtimeMode,
+      repoUrl: resolvedRepoUrl,
+      repoDialect,
+      scopeId: runtimeConfig.scopeId,
+    },
+    process.env,
+  )
+  if (repoDialect === 'sqlite') {
+    ensureDocmanSqliteSchemaReady(resolvedRepoUrl)
+  }
+
+  const tenantId =
+    getStringOption(parsed, 'tenant-id')
+    ?? normalizeNonEmptyString(process.env.TENANT_ID)
+    ?? storedConfig.tenantId
+    ?? DEFAULT_TENANT_AS_UUID_STRING
+  const scopeId =
+    normalizeDocmanScopeId(process.env.DOCMAN_SCOPE_ID)
+    ?? normalizeDocmanScopeId(process.env.DOCMAN_WORKSPACE_ID)
+    ?? storedConfig.scopeId
+    ?? DEFAULT_DOCMAN_SCOPE_ID
+  const logLevel =
+    getStringOption(parsed, 'log-level')
+    ?? normalizeNonEmptyString(process.env.LOG_LEVEL)
+    ?? storedConfig.logLevel
+
+  process.env.TENANT_ID = tenantId
+  process.env.DOCMAN_SCOPE_ID = scopeId
+  process.env.DOCMAN_WORKSPACE_ID = scopeId
+  if (logLevel) process.env.LOG_LEVEL = logLevel
+  sanitizeBlankEnvValues(process.env)
+
+  const { tooling } = await getDocmanCliRuntimeModules()
+  tooling.clearDocmanToolingRuntimeCaches()
+
+  return { scopeId, workspaceId: scopeId, tenantId }
+}
+
+const commandSurface = createDocmanCliCommandSurface({
+  buildConfigSetOutput,
+  buildConfigShowOutput,
+  getStringOption,
+  parseJsonInput,
+  printJson,
+  runOperationById: runDocmanOperationById,
+  writeStoredConfig: writeDocmanCliStoredConfig,
+})
+
+function buildStandaloneRuntimeOutput(params: {
+  action: string
+  written: LoadedDocmanCliStoredConfig
+  runtime: ReturnType<typeof resolveDocmanRuntimeConfig>
+}): Record<string, unknown> {
+  return {
+    ok: true,
+    action: params.action,
+    configPath: params.written.path,
+    configExists: params.written.exists,
+    stored: maskStoredConfigForDisplay(params.written.config),
+    runtime: {
+      runtimeMode: params.runtime.runtimeMode,
+      runtimeModeSource: params.runtime.runtimeModeSource,
+      repoUrl: maskRepoUrlForDisplay(params.runtime.repoUrl) ?? params.runtime.repoUrl,
+      repoUrlSource: params.runtime.repoUrlSource,
+      repoDialect: params.runtime.repoDialect,
+      scopeId: params.runtime.scopeId,
+      scopeIdSource: params.runtime.scopeIdSource,
+    },
+  }
+}
+
+async function ensureDocmanRuntimeStorageReady(repoUrl: string): Promise<void> {
+  if (inferDocmanRepoDialect(repoUrl) === 'sqlite') {
+    ensureDocmanSqliteSchemaReady(repoUrl)
+    return
+  }
+
+  await applyDocmanPgSchema({ repoUrl })
+}
+
+async function handleInit(parsed: ParsedArgv): Promise<void> {
+  const runtimeMode = normalizeRuntimeMode(getStringOption(parsed, 'runtime-mode')) ?? 'single-user'
+  const repoUrl = normalizeRepoUrlValue(getStringOption(parsed, 'repo-url')) ?? getDefaultDocmanSqliteRepoUrl(process.env)
+  const scopeId = normalizeDocmanScopeId(getScopeIdOption(parsed)) ?? DEFAULT_DOCMAN_SCOPE_ID
+
+  const written = writeDocmanCliStoredConfig(
+    {
+      runtimeMode,
+      repoUrl,
+      scopeId,
+    },
+    process.env,
+  )
+
+  const runtime = resolveDocmanRuntimeConfig({}, process.env)
+  await ensureDocmanRuntimeStorageReady(runtime.repoUrl)
+  applyDocmanRuntimeEnv(
+    {
+      runtimeMode: runtime.runtimeMode,
+      repoUrl: runtime.repoUrl,
+      repoDialect: runtime.repoDialect,
+      scopeId: runtime.scopeId,
+    },
+    process.env,
+  )
+
+  printJson(buildStandaloneRuntimeOutput({ action: 'init', written, runtime }))
+}
+
+async function handleSetup(subcommand: string | undefined, parsed: ParsedArgv): Promise<void> {
+  const resolvedSubcommand = subcommand ?? 'runtime'
+  if (resolvedSubcommand !== 'runtime') {
+    throw new Error(`unknown_setup_subcommand:${resolvedSubcommand}`)
+  }
+
+  const loaded = readDocmanCliStoredConfig(process.env)
+  const nextRepoUrl =
+    normalizeRepoUrlValue(getStringOption(parsed, 'repo-url'))
+    ?? loaded.config.repoUrl
+    ?? inferDefaultRepoUrl(process.env)
+  const nextRuntimeMode = normalizeRuntimeMode(getStringOption(parsed, 'runtime-mode')) ?? loaded.config.runtimeMode ?? 'single-user'
+  const nextScopeId =
+    normalizeDocmanScopeId(getScopeIdOption(parsed))
+    ?? loaded.config.scopeId
+    ?? DEFAULT_DOCMAN_SCOPE_ID
+
+  const written = writeDocmanCliStoredConfig(
+    {
+      repoUrl: nextRepoUrl,
+      runtimeMode: nextRuntimeMode,
+      scopeId: nextScopeId,
+    },
+    process.env,
+  )
+
+  const runtime = resolveDocmanRuntimeConfig({}, process.env)
+  await ensureDocmanRuntimeStorageReady(runtime.repoUrl)
+  applyDocmanRuntimeEnv(
+    {
+      runtimeMode: runtime.runtimeMode,
+      repoUrl: runtime.repoUrl,
+      repoDialect: runtime.repoDialect,
+      scopeId: runtime.scopeId,
+    },
+    process.env,
+  )
+
+  printJson(buildStandaloneRuntimeOutput({ action: 'setup-runtime', written, runtime }))
+}
+
+type DocmanManifestPayloads = {
+  dcm: unknown
+  routes: unknown
+  agent: unknown
+  cli: DocmanCliProjection
+  hostRegistration: ReturnType<typeof buildDocmanHostRegistrationManifest>
+  operations: unknown
+}
+
+async function buildManifestPayloads(): Promise<DocmanManifestPayloads> {
+  const { tooling } = await getDocmanCliRuntimeModules()
+  return {
+    dcm: tooling.buildDocmanDomainCapabilityManifest({ includeDocs: true, refresh: true }),
+    routes: tooling.buildDocmanHostRouteProjection({ refresh: true }),
+    agent: tooling.buildDocmanAgentManifest({ refresh: true }),
+    cli: tooling.buildDocmanCliProjection({ refresh: true }),
+    hostRegistration: buildDocmanHostRegistrationManifest({ mode: 'installed' }),
+    operations: tooling.listDocmanToolingOperations({ refresh: true }),
+  }
+}
+
+function resolveManifestArtifactId(
+  identifier: string,
+  projection: DocmanCliProjection,
+): DocmanCliManifestArtifact['id'] | null {
+  const normalized = normalizeIdentifier(identifier)
+  for (const artifact of projection.artifacts) {
+    if (normalizeIdentifier(artifact.id) === normalized) return artifact.id
+    for (const alias of artifact.aliases ?? []) {
+      if (normalizeIdentifier(alias) === normalized) return artifact.id
+    }
+  }
+  return null
+}
+
+function getManifestArtifactValue(
+  payloads: DocmanManifestPayloads,
+  artifactId: DocmanCliManifestArtifact['id'],
+): unknown {
+  if (artifactId === 'dcm') return payloads.dcm
+  if (artifactId === 'routes') return payloads.routes
+  if (artifactId === 'agent') return payloads.agent
+  if (artifactId === 'cli') return payloads.cli
+  if (artifactId === 'host-registration') return payloads.hostRegistration
+  return payloads.operations
+}
+
+function tokenizeManifestPath(rawPath: string): string[] {
+  return rawPath
+    .replace(/\[(\d+)\]/g, '.$1')
+    .split('.')
+    .map((segment) => segment.trim())
+    .filter(Boolean)
+}
+
+function resolveManifestPathValue(
+  root: unknown,
+  rawPath: string | undefined,
+): { found: boolean; value: unknown } {
+  if (!rawPath) return { found: true, value: root }
+
+  const segments = tokenizeManifestPath(rawPath)
+  let current: unknown = root
+  let index = 0
+
+  while (index < segments.length) {
+    const segment = segments[index]
+
+    if (Array.isArray(current)) {
+      const numericIndex = Number(segment)
+      if (!Number.isInteger(numericIndex) || numericIndex < 0 || numericIndex >= current.length) {
+        return { found: false, value: null }
+      }
+      current = current[numericIndex]
+      index += 1
+      continue
+    }
+
+    if (!current || typeof current !== 'object') {
+      return { found: false, value: null }
+    }
+
+    const record = current as Record<string, unknown>
+    if (Object.prototype.hasOwnProperty.call(record, segment)) {
+      current = record[segment]
+      index += 1
+      continue
+    }
+
+    let matched = false
+    for (let end = segments.length; end > index; end -= 1) {
+      const composite = segments.slice(index, end).join('.')
+      if (!Object.prototype.hasOwnProperty.call(record, composite)) continue
+      current = record[composite]
+      index = end
+      matched = true
+      break
+    }
+
+    if (!matched) {
+      return { found: false, value: null }
+    }
+  }
+
+  return { found: true, value: current }
+}
+
+function renderManifestScalar(value: unknown): string {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  return JSON.stringify(value)
+}
+
+function renderManifestValueLines(value: unknown, indent = ''): string[] {
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return [`${indent}${renderManifestScalar(value)}`]
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [`${indent}[]`]
+    const lines: string[] = []
+    for (const item of value) {
+      if (
+        item === null ||
+        item === undefined ||
+        typeof item === 'string' ||
+        typeof item === 'number' ||
+        typeof item === 'boolean'
+      ) {
+        lines.push(`${indent}- ${renderManifestScalar(item)}`)
+        continue
+      }
+      lines.push(`${indent}-`)
+      lines.push(...renderManifestValueLines(item, `${indent}  `))
+    }
+    return lines
+  }
+
+  const record = value as Record<string, unknown>
+  const keys = Object.keys(record).sort()
+  if (keys.length === 0) return [`${indent}{}`]
+
+  const lines: string[] = []
+  for (const key of keys) {
+    const entry = record[key]
+    if (
+      entry === null ||
+      entry === undefined ||
+      typeof entry === 'string' ||
+      typeof entry === 'number' ||
+      typeof entry === 'boolean'
+    ) {
+      lines.push(`${indent}${key}: ${renderManifestScalar(entry)}`)
+      continue
+    }
+    lines.push(`${indent}${key}:`)
+    lines.push(...renderManifestValueLines(entry, `${indent}  `))
+  }
+  return lines
+}
+
+function buildManifestShowLines(
+  artifactId: DocmanCliManifestArtifact['id'],
+  value: unknown,
+  rawPath?: string,
+): string[] {
+  const title = `docman manifest show ${artifactId}${rawPath ? ` --path ${rawPath}` : ''}`
+  if (rawPath) {
+    const lines = [title]
+    appendTextSection(lines, 'Value', renderManifestValueLines(value))
+    return lines
+  }
+
+  if (artifactId === 'dcm') {
+    const manifest = toRecord(value)
+    const domain = toRecord(manifest.domain)
+    const capabilities = toRecord(manifest.capabilities)
+    const docs = toRecord(manifest.docs)
+    const domainDocs = toRecord(docs.domain)
+    const operations = Array.isArray(capabilities.operations)
+      ? capabilities.operations as Array<Record<string, unknown>>
+      : []
+    const resources = Array.isArray(capabilities.resources)
+      ? capabilities.resources as Array<Record<string, unknown>>
+      : []
+    const policyOps = toRecord(toRecord(manifest.policies).operations)
+    const schemaRefs = toRecord(toRecord(manifest.contracts).schemas)
+    const lines = [title]
+    appendTextSection(lines, 'Identity', [
+      `manifest version: ${renderManifestScalar(manifest.manifestVersion)}`,
+      `domain: ${renderManifestScalar(domain.id)} v${renderManifestScalar(domain.version)}`,
+      `display name: ${renderManifestScalar(domain.displayName)}`,
+    ])
+    appendTextSection(lines, 'Summary', [
+      normalizeNonEmptyString(domain.description) ?? '',
+      normalizeNonEmptyString(domainDocs.summary) ?? '',
+    ])
+    appendTextSection(lines, 'Counts', [
+      `operations: ${operations.length}`,
+      `resources: ${resources.length}`,
+      `policies: ${Object.keys(policyOps).length}`,
+      `schemas: ${Object.keys(schemaRefs).length}`,
+    ])
+    appendTextSection(lines, 'Resources', resources.map((resource) => {
+      const resourceId = renderManifestScalar(resource.resourceId)
+      const resourceTitle = normalizeNonEmptyString(resource.title)
+      return resourceTitle ? `${resourceId}  ${resourceTitle}` : resourceId
+    }))
+    appendTextSection(lines, 'Operations', operations.map((operation) => {
+      const operationId = renderManifestScalar(operation.operationId)
+      const operationTitle = normalizeNonEmptyString(operation.title)
+      return operationTitle ? `${operationId}  ${operationTitle}` : operationId
+    }))
+    appendTextSection(lines, 'Browse', [
+      'docman manifest get dcm --path docs.operations.document.list',
+      'docman manifest show dcm --path docs.operations.document.list',
+      'docman manifest get dcm --path contracts.schemas',
+    ])
+    return lines
+  }
+
+  if (artifactId === 'routes') {
+    const routes = Array.isArray(value) ? value as Array<Record<string, unknown>> : []
+    const lines = [title]
+    appendTextSection(lines, 'Counts', [`routes: ${routes.length}`])
+    appendTextSection(lines, 'Routes', routes.map((route) => (
+      `${renderManifestScalar(route.method)} ${renderManifestScalar(route.pattern)} -> ${renderManifestScalar(route.operation)}`
+    )))
+    return lines
+  }
+
+  if (artifactId === 'agent') {
+    const manifest = toRecord(value)
+    const tools = Array.isArray(manifest.tools) ? manifest.tools as Array<Record<string, unknown>> : []
+    const lines = [title]
+    appendTextSection(lines, 'Identity', [
+      `kind: ${renderManifestScalar(manifest.kind)}`,
+      `version: ${renderManifestScalar(manifest.version)}`,
+      `domain: ${renderManifestScalar(manifest.domain)}`,
+    ])
+    appendTextSection(lines, 'Counts', [`tools: ${tools.length}`])
+    appendTextSection(lines, 'Tools', tools.map((tool) => {
+      const toolId = renderManifestScalar(tool.toolId)
+      const summary = normalizeNonEmptyString(tool.summary)
+      return summary ? `${toolId}  ${summary}` : toolId
+    }))
+    return lines
+  }
+
+  if (artifactId === 'cli') {
+    const projection = value as DocmanCliProjection
+    const commands = Array.isArray(projection.commands) ? projection.commands : []
+    const staticCount = commands.filter((command: DocmanCliCommandDescriptor) => command.kind !== 'operation').length
+    const operationCount = commands.filter((command: DocmanCliCommandDescriptor) => command.kind === 'operation').length
+    const lines = [title]
+    appendTextSection(lines, 'Identity', [
+      `kind: ${projection.kind}`,
+      `version: ${projection.version}`,
+      `domain: ${projection.domain}`,
+    ])
+    appendTextSection(lines, 'Counts', [
+      `commands: ${commands.length}`,
+      `static/root commands: ${staticCount}`,
+      `operation commands: ${operationCount}`,
+      `artifacts: ${projection.artifacts.length}`,
+    ])
+    appendTextSection(lines, 'Source of Truth', projection.sourceOfTruth.notes)
+    appendTextSection(lines, 'Browse', [
+      'docman manifest get cli --path commandsById.config.set',
+      'docman manifest get cli --path commandsById.document.list',
+      'docman manifest show cli --path commandsById.document.compose.fetch',
+    ])
+    appendTextSection(lines, 'Commands', commands.map((command: DocmanCliCommandDescriptor) => {
+      const summary = normalizeNonEmptyString(command.summary)
+      return summary ? `${command.id}  ${summary}` : command.id
+    }))
+    return lines
+  }
+
+  if (artifactId === 'host-registration') {
+    const manifest = toRecord(value)
+    const providers = Array.isArray(manifest.manifestProviders)
+      ? manifest.manifestProviders as Array<Record<string, unknown>>
+      : []
+    const plugins = Array.isArray(manifest.plugins)
+      ? manifest.plugins as Array<Record<string, unknown>>
+      : []
+    const lines = [title]
+    appendTextSection(lines, 'Identity', [
+      `kind: ${renderManifestScalar(manifest.kind)}`,
+      `domain: ${renderManifestScalar(manifest.domain)}`,
+      `packageName: ${renderManifestScalar(manifest.packageName)}`,
+      `baseDir: ${renderManifestScalar(manifest.baseDir)}`,
+    ])
+    appendTextSection(lines, 'Description', [normalizeNonEmptyString(manifest.description) ?? ''])
+    appendTextSection(lines, 'Manifest Providers', providers.map((provider) => (
+      `${renderManifestScalar(provider.id)} -> ${renderManifestScalar(provider.module)}#${renderManifestScalar(provider.exportName)}`
+    )))
+    appendTextSection(lines, 'Plugins', plugins.map((plugin) => (
+      `${renderManifestScalar(plugin.domain)} -> ${renderManifestScalar(plugin.module)}#${renderManifestScalar(plugin.factory)}`
+    )))
+    appendTextSection(lines, 'Notes', toStringList(manifest.notes))
+    return lines
+  }
+
+  const operations = Array.isArray(value) ? value as Array<Record<string, unknown>> : []
+  const lines = [title]
+  appendTextSection(lines, 'Counts', [`operations: ${operations.length}`])
+  appendTextSection(lines, 'Operations', operations.map((operation) => {
+    const operationId = renderManifestScalar(operation.operationId)
+    const summary = normalizeNonEmptyString(operation.summary)
+    return summary ? `${operationId}  ${summary}` : operationId
+  }))
+  return lines
+}
+
+async function handleManifest(parsed: ParsedArgv): Promise<void> {
+  const subcommand = normalizeManifestHelpSubcommand(parsed.positionals[1]?.toLowerCase())
+  const payloads = await buildManifestPayloads()
+  const projection = payloads.cli
+
+  if (!subcommand || subcommand === 'all') {
+    printJson({
+      dcm: payloads.dcm,
+      routes: payloads.routes,
+      agent: payloads.agent,
+      cli: payloads.cli,
+      hostRegistration: payloads.hostRegistration,
+      operations: payloads.operations,
+    })
+    return
+  }
+
+  if (subcommand === 'get' || subcommand === 'show') {
+    const artifactInput = parsed.positionals[2]
+    if (!artifactInput) throw new Error('missing_required_option:<artifact>')
+    const artifactId = resolveManifestArtifactId(artifactInput, projection)
+    if (!artifactId) throw new Error(`unknown_manifest_artifact:${artifactInput}`)
+    const rawPath = getStringOption(parsed, 'path')
+    const target = getManifestArtifactValue(payloads, artifactId)
+    const resolved = resolveManifestPathValue(target, rawPath)
+    if (!resolved.found) {
+      throw new Error(`manifest_path_not_found:${artifactId}:${rawPath ?? '<root>'}`)
+    }
+    if (subcommand === 'get') {
+      printJson(resolved.value)
+      return
+    }
+    printHelpLines(buildManifestShowLines(artifactId, resolved.value, rawPath))
+    return
+  }
+
+  const artifactId = resolveManifestArtifactId(subcommand, projection)
+  if (!artifactId) {
+    throw new Error(`unknown_manifest_subcommand:${subcommand}`)
+  }
+  printJson(getManifestArtifactValue(payloads, artifactId))
+}
+
+async function executeResolvedOperation(
+  operationId: string,
+  parsed: ParsedArgv,
+  runtime: RuntimeContext,
+  operationMap: ReadonlyMap<string, DocmanOperationSpec>,
+  options?: { allowHooks?: boolean },
+): Promise<void> {
+  const allowHooks = options?.allowHooks !== false
+  if (allowHooks) {
+    const handledByHook = await commandSurface.tryExecuteOperationViaHook(operationId, parsed)
+    if (handledByHook) return
+  }
+
+  const { tooling } = await getDocmanCliRuntimeModules()
+  const operation = operationMap.get(operationId) ?? tooling.getDocmanOperationSpecById(operationId, { refresh: true })
+  if (!operation) {
+    throw new Error(`unknown_docman_operation:${operationId}`)
+  }
+
+  const input = buildGeneratedOperationInput(operation, parsed, runtime)
+  const output = await runDocmanOperationById(operation.operationId, input)
+  printJson(output)
+}
+
+async function main(): Promise<void> {
+  const parsed = parseArgv(process.argv.slice(2))
+  const helpMode = parsed.positionals[0]?.toLowerCase() === 'help'
+  const effectiveParsed: ParsedArgv = helpMode
+    ? {
+        positionals: parsed.positionals.slice(1),
+        options: {
+          ...parsed.options,
+          help: true,
+        },
+      }
+    : parsed
+  const command = effectiveParsed.positionals[0]?.toLowerCase()
+  const subcommand = effectiveParsed.positionals[1]?.toLowerCase()
+  const helpRequested = getBooleanOption(effectiveParsed, 'help', false)
+
+  if (getBooleanOption(parsed, 'version', false) || (command === 'version' && !helpRequested)) {
+    printVersion()
+    return
+  }
+
+  if (!command || helpRequested) {
+    if (command && await tryPrintCommandHelp(effectiveParsed)) return
+    await printHelp()
+    return
+  }
+
+  if (command === 'tools') {
+    const { tooling } = await getDocmanCliRuntimeModules()
+    printJson(tooling.listDocmanToolingTools({ refresh: true }))
+    return
+  }
+
+  if (command === 'init') {
+    await handleInit(effectiveParsed)
+    return
+  }
+
+  if (command === 'setup') {
+    await handleSetup(subcommand, effectiveParsed)
+    return
+  }
+
+  if (command === 'ops') {
+    const { tooling } = await getDocmanCliRuntimeModules()
+    printJson(tooling.listDocmanToolingOperations({ refresh: true }))
+    return
+  }
+
+  if (command === 'manifest') {
+    await handleManifest(effectiveParsed)
+    return
+  }
+
+  if (command === 'config') {
+    await commandSurface.handleConfig(subcommand, effectiveParsed)
+    return
+  }
+
+  const { tooling } = await getDocmanCliRuntimeModules()
+  const operationSpecs = tooling.listDocmanToolingOperations({ refresh: true })
+  const operationMap = new Map(
+    operationSpecs.map((operation) => [normalizeOperationIdentifier(operation.operationId), operation]),
+  )
+  const resolvedOperationId = await resolveGeneratedOperationId(effectiveParsed, operationMap)
+  const rawOperationMode = command ? DIRECT_OPERATION_COMMANDS.has(command) : false
+  const hooksDisabled = areHooksDisabled(effectiveParsed)
+
+  if (!resolvedOperationId && DIRECT_OPERATION_COMMANDS.has(command)) {
+    throw new Error(`unknown_operation_command:${command}`)
+  }
+
+  if (command === 'tool' || command === 'invoke') {
+    await buildRuntimeContext(effectiveParsed)
+    const identifier = requireStringOption(effectiveParsed, 'id', '--id')
+    const input = parseJsonInput(getStringOption(effectiveParsed, 'input'), 'input') ?? {}
+    const output = await runDocmanToolById(identifier, input)
+    printJson(output)
+    return
+  }
+
+  const runtime = await buildRuntimeContext(effectiveParsed)
+
+  if (resolvedOperationId) {
+    const allowHooks = !rawOperationMode && !hooksDisabled
+    await executeResolvedOperation(resolvedOperationId, effectiveParsed, runtime, operationMap, { allowHooks })
+    return
+  }
+
+  throw new Error(`unknown_command:${command}`)
+}
+
+async function disconnectRepoHandles(): Promise<void> {
+  try {
+    const drizzleModule = await import('@aopslab/xf-db-drizzle')
+    const tasks: Promise<unknown>[] = []
+    if (typeof drizzleModule.drizzleDisconnect === 'function') {
+      tasks.push(drizzleModule.drizzleDisconnect())
+    }
+    if (typeof drizzleModule.drizzleSqliteDisconnect === 'function') {
+      tasks.push(drizzleModule.drizzleSqliteDisconnect())
+    }
+    if (tasks.length > 0) {
+      await Promise.allSettled(tasks)
+    }
+  } catch {}
+}
+
+void (async () => {
+  try {
+    await main()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    process.stderr.write(`${message}\n`)
+    process.exitCode = 1
+  } finally {
+    await disconnectRepoHandles()
+  }
+})()