suemo 0.0.1 → 0.0.2

package/src/cli/commands/init.ts

@@ -1,90 +1,170 @@
+import { confirm } from '@crustjs/prompts'
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, join, resolve as resolvePath } from 'node:path'
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { checkCompatibility } from '../../db/preflight.ts'
 import { runSchema } from '../../db/schema.ts'
-import { initLogger } from '../../logger.ts'
-import { app } from '../shared.ts'
+import { getLogger } from '../../logger.ts'
+import { app, initCliCommand } from '../shared.ts'
 
-export const initCmd = app.sub('init')
-	.meta({ description: 'Initialize suemo: create config template and apply DB schema' })
+import template from '../../config.template.ts' with { type: 'text' }
+
+interface InitFlags {
+	debug?: boolean | undefined
+	config?: string | undefined
+	force?: boolean | undefined
+	yes?: boolean | undefined
+}
+
+const log = getLogger(['suemo', 'cli', 'init'])
+
+const init = app.sub('init')
+	.meta({ description: 'Initialize suemo config and/or database schema' })
+
+function homeConfigPath(): string {
+	const home = process.env.HOME ?? process.env.USERPROFILE
+	if (!home) throw new Error('HOME/USERPROFILE is not set; cannot resolve ~/.suemo path')
+	return join(home, '.suemo', 'suemo.ts')
+}
+
+function writeConfig(force: boolean, outputPath?: string): 'written' | 'skipped' {
+	const configPath = outputPath ? resolveConfigOutputPath(outputPath) : homeConfigPath()
+	log.debug('Preparing config template write', { configPath, force })
+	if (existsSync(configPath) && !force) {
+		console.log(`Config already exists at ${configPath}`)
+		console.log('Pass --force to overwrite.')
+		return 'skipped'
+	}
+
+	mkdirSync(dirname(configPath), { recursive: true })
+	writeFileSync(configPath, template as unknown as string, 'utf-8')
+	console.log(`✓ Config written to ${configPath}`)
+	return 'written'
+}
+
+function configOutputPath(flags: InitFlags): string | undefined {
+	const fromFlag = flags.config?.trim()
+	if (fromFlag) return fromFlag
+	const fromEnv = process.env.SUEMO_CONFIG_PATH?.trim()
+	return fromEnv || undefined
+}
+
+function resolveConfigOutputPath(configPath: string): string {
+	if (configPath.startsWith('~/')) {
+		const home = process.env.HOME ?? process.env.USERPROFILE
+		if (!home) throw new Error('HOME/USERPROFILE is not set; cannot expand ~ in config path')
+		return resolvePath(home, configPath.slice(2))
+	}
+	return resolvePath(configPath)
+}
+
+async function applySchema(configPath?: string): Promise<boolean> {
+	let connected = false
+	try {
+		log.debug('Loading config for schema apply', { cwd: process.cwd(), overridePath: configPath ?? null })
+		const config = await loadConfig(process.cwd(), configPath)
+		log.debug('Resolved schema apply target', {
+			namespace: config.surreal.namespace,
+			database: config.surreal.database,
+			url: config.surreal.url,
+		})
+		log.debug('Connecting for schema apply', {
+			url: config.surreal.url,
+			namespace: config.surreal.namespace,
+			database: config.surreal.database,
+		})
+		const db = await connect(config.surreal)
+		connected = true
+
+		const compat = await checkCompatibility(db, {
+			requireEmbedding: false,
+			context: 'cli:init-schema',
+		})
+		log.debug('Preflight result for init schema', {
+			ok: compat.ok,
+			surrealVersion: compat.surrealVersion,
+			surrealkv: compat.surrealkv,
+			retention_ok: compat.retention_ok,
+			embedding: compat.embedding,
+			errorCount: compat.errors.length,
+		})
+		if (!compat.ok) {
+			console.error('\n✗ Compatibility check failed:')
+			for (const e of compat.errors) console.error(`  • ${e}`)
+			return false
+		}
+
+		if (!compat.embedding) {
+			console.warn(
+				'\n⚠ fn::embed() is unavailable in this DB. Schema can still be applied, but observe/query/consolidate will fail until embedding model is configured.',
+			)
+		}
+
+		await runSchema(db)
+		console.log('✓ Schema applied to SurrealDB')
+		return true
+	} catch (e) {
+		console.error(`✗ Schema not applied: ${String(e)}`)
+		return false
+	} finally {
+		if (connected) {
+			await disconnect()
+		}
+	}
+}
+
+const initConfigCmd = init.sub('config')
+	.meta({ description: 'Create/update ~/.suemo/suemo.ts config template' })
 	.flags({
-		force: { type: 'boolean', description: 'Overwrite existing config without prompting' },
+		force: { type: 'boolean', description: 'Overwrite existing config file' },
 	})
 	.run(async ({ flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
+		await initCliCommand('init config', { debug: flags.debug, config: flags.config })
+		writeConfig(Boolean(flags.force), configOutputPath(flags))
+	})
 
-		const homeConfig = join(process.env.HOME ?? '~', '.suemo', 'suemo.ts')
-		const configExists = existsSync(homeConfig)
+const initSchemaCmd = init.sub('schema')
+	.meta({ description: 'Apply database schema using current config' })
+	.flags({
+		yes: { type: 'boolean', short: 'y', description: 'Skip schema confirmation prompt' },
+	})
+	.run(async ({ flags }) => {
+		await initCliCommand('init schema', { debug: flags.debug, config: flags.config })
 
-		if (configExists && !flags.force) {
-			console.log(`Config already exists at ${homeConfig}`)
-			console.log('Pass --force to overwrite.')
-			return
+		const confirmOptions: {
+			message: string
+			default: boolean
+			active: string
+			inactive: string
+			initial?: boolean
+		} = {
+			message: 'Apply schema to the configured SurrealDB now?',
+			default: false,
+			active: 'Apply',
+			inactive: 'Cancel',
 		}
+		if (flags.yes !== undefined) {
+			confirmOptions.initial = flags.yes
+		}
+		const proceed = await confirm(confirmOptions)
 
-		const template = `import { defineConfig } from "suemo";
-
-export default defineConfig({
-  surreal: {
-    url:       process.env.SURREAL_URL  ?? "ws://localhost:8000",
-    namespace: process.env.SURREAL_NS   ?? "myagents",
-    database:  process.env.SURREAL_DB   ?? "default",
-    auth: {
-      user: process.env.SURREAL_USER!,
-      pass: process.env.SURREAL_PASS!,
-    },
-  },
-  embedding: {
-    provider:  "surreal",
-    dimension: 1536,
-  },
-  consolidation: {
-    trigger:                 "timer",
-    intervalMinutes:         30,
-    reactiveThreshold:       50,
-    nremSimilarityThreshold: 0.85,
-    remRelationThreshold:    0.4,
-    llm: {
-      url:    process.env.LLM_URL!,
-      model:  process.env.LLM_MODEL ?? "gpt-4o",
-      apiKey: process.env.LLM_API_KEY!,
-    },
-  },
-  retrieval: {
-    weights: { vector: 0.5, bm25: 0.25, graph: 0.15, temporal: 0.1 },
-  },
-  mcp: {
-    port: Number(process.env.SUEMO_PORT) || 4242,
-    host: "127.0.0.1",
-  },
-});
-`
-
-		mkdirSync(join(process.env.HOME ?? '~', '.suemo'), { recursive: true })
-		writeFileSync(homeConfig, template, 'utf-8')
-		console.log(`✓ Config written to ${homeConfig}`)
-
-		// Apply schema if SURREAL_* env vars are present
-		if (process.env.SURREAL_URL && process.env.SURREAL_USER) {
-			try {
-				const config = await loadConfig(process.cwd(), flags.config)
-				const db = await connect(config.surreal)
-				const compat = await checkCompatibility(db)
-				if (!compat.ok) {
-					console.error('\n✗ Compatibility check failed:')
-					for (const e of compat.errors) console.error(`  • ${e}`)
-					await disconnect()
-					return
-				}
-				await runSchema(db)
-				await disconnect()
-				console.log('✓ Schema applied to SurrealDB')
-			} catch (e) {
-				console.warn(`  (Schema not applied — configure SURREAL_* env vars first: ${String(e)})`)
-			}
-		} else {
-			console.log('  Set SURREAL_URL, SURREAL_USER, SURREAL_PASS, then run `suemo init` again to apply schema.')
+		if (!proceed) {
+			console.log('Schema apply cancelled.')
+			return
 		}
+
+		const ok = await applySchema(flags.config)
+		if (!ok) process.exitCode = 1
+	})
+
+export const initCmd = init
+	.command(initConfigCmd)
+	.command(initSchemaCmd)
+	.run(async ({ flags }) => {
+		await initCliCommand('init', { debug: flags.debug, config: flags.config })
+		console.log('Use one of:')
+		console.log('  suemo init config [--force]')
+		console.log('  suemo init schema [--yes]')
+		console.log('\nRun `suemo init --help` for full details.')
 	})

package/src/cli/commands/observe.ts

@@ -1,9 +1,11 @@
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
-import { initLogger } from '../../logger.ts'
+import { getLogger } from '../../logger.ts'
 import { observe } from '../../memory/write.ts'
 import { MemoryKindSchema } from '../../types.ts'
-import { app } from '../shared.ts'
+import { app, initCliCommand } from '../shared.ts'
+
+const log = getLogger(['suemo', 'cli', 'observe'])
 
 export const observeCmd = app.sub('observe')
 	.meta({ description: 'Store a new observation in memory' })
@@ -17,7 +19,7 @@ export const observeCmd = app.sub('observe')
 		session: { type: 'string', description: 'Session ID (attach to open episode)' },
 	})
 	.run(async ({ args, flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
+		await initCliCommand('observe', { debug: flags.debug, config: flags.config })
 
 		const kindParse = MemoryKindSchema.safeParse(flags.kind)
 		if (!kindParse.success) {
@@ -27,14 +29,24 @@ export const observeCmd = app.sub('observe')
 
 		const config = await loadConfig(process.cwd(), flags.config)
 		const db = await connect(config.surreal)
-		const node = await observe(db, {
-			content: args.content,
-			kind: kindParse.data,
-			tags: flags.tags ? flags.tags.split(',').map((t) => t.trim()) : [],
-			scope: flags.scope,
-			confidence: flags.confidence,
-			source: flags.source,
-		})
-		await disconnect()
-		console.log(JSON.stringify({ id: node.id, kind: node.kind, valid_from: node.valid_from }, null, 2))
+		try {
+			log.debug('Running observe command', {
+				kind: kindParse.data,
+				hasScope: Boolean(flags.scope),
+				tagCount: flags.tags ? flags.tags.split(',').filter(Boolean).length : 0,
+				confidence: flags.confidence,
+				contentLength: args.content.length,
+			})
+			const node = await observe(db, {
+				content: args.content,
+				kind: kindParse.data,
+				tags: flags.tags ? flags.tags.split(',').map((t) => t.trim()) : [],
+				scope: flags.scope,
+				confidence: flags.confidence,
+				source: flags.source,
+			}, config)
+			console.log(JSON.stringify({ id: node.id, kind: node.kind, valid_from: node.valid_from }, null, 2))
+		} finally {
+			await disconnect()
+		}
 	})

package/src/cli/commands/query.ts

@@ -1,8 +1,11 @@
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
-import { initLogger } from '../../logger.ts'
+import { getLogger } from '../../logger.ts'
 import { query } from '../../memory/read.ts'
-import { app } from '../shared.ts'
+import type { MemoryNode } from '../../types.ts'
+import { app, initCliCommand } from '../shared.ts'
+
+const log = getLogger(['suemo', 'cli', 'query'])
 
 export const queryCmd = app.sub('query')
 	.meta({ description: 'Hybrid semantic search over memories' })
@@ -13,11 +16,24 @@ export const queryCmd = app.sub('query')
 		json: { type: 'boolean', short: 'j', description: 'Output full JSON nodes' },
 	})
 	.run(async ({ args, flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
-		const config = await loadConfig(process.cwd(), flags.config)
-		const db = await connect(config.surreal)
-		const nodes = await query(db, { input: args.input, scope: flags.scope, topK: flags.top })
-		await disconnect()
+		await initCliCommand('query', { debug: flags.debug, config: flags.config })
+		log.debug('Running query command', {
+			hasScope: Boolean(flags.scope),
+			top: flags.top,
+			json: Boolean(flags.json),
+			inputLength: args.input.length,
+		})
+		const nodes: MemoryNode[] = await (async () => {
+			let connected = false
+			try {
+				const config = await loadConfig(process.cwd(), flags.config)
+				const db = await connect(config.surreal)
+				connected = true
+				return await query(db, { input: args.input, scope: flags.scope, topK: flags.top }, config)
+			} finally {
+				if (connected) await disconnect()
+			}
+		})()
 		if (flags.json) {
 			console.log(JSON.stringify(nodes, null, 2))
 		} else {

package/src/cli/commands/recall.ts

@@ -1,17 +1,23 @@
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
-import { initLogger } from '../../logger.ts'
+import { getLogger } from '../../logger.ts'
 import { recall } from '../../memory/read.ts'
-import { app } from '../shared.ts'
+import { app, initCliCommand } from '../shared.ts'
+
+const log = getLogger(['suemo', 'cli', 'recall'])
 
 export const recallCmd = app.sub('recall')
 	.meta({ description: 'Fetch a single node + its neighbours (ticks FSRS)' })
 	.args([{ name: 'nodeId', type: 'string', required: true }])
 	.run(async ({ args, flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
+		await initCliCommand('recall', { debug: flags.debug, config: flags.config })
+		log.debug('Running recall command', { nodeId: args.nodeId })
 		const config = await loadConfig(process.cwd(), flags.config)
 		const db = await connect(config.surreal)
-		const result = await recall(db, args.nodeId)
-		await disconnect()
-		console.log(JSON.stringify(result, null, 2))
+		try {
+			const result = await recall(db, args.nodeId)
+			console.log(JSON.stringify(result, null, 2))
+		} finally {
+			await disconnect()
+		}
 	})

package/src/cli/commands/serve.ts

@@ -1,19 +1,28 @@
 import { loadConfig } from '../../config.ts'
-import { initLogger } from '../../logger.ts'
-import { startMcpServer } from '../../mcp/server.ts'
-import { app } from '../shared.ts'
+import { getLogger } from '../../logger.ts'
+import { startMcpServer, startMcpStdioServer } from '../../mcp/server.ts'
+import { app, initCliCommand } from '../shared.ts'
+
+const log = getLogger(['suemo', 'cli', 'serve'])
 
 export const serveCmd = app.sub('serve')
-	.meta({ description: 'Start the MCP server' })
+	.meta({ description: 'Start the MCP server (HTTP or stdio)' })
 	.flags({
 		port: { type: 'number', short: 'p', description: 'Port to listen on (overrides config)' },
 		host: { type: 'string', description: 'Host to bind to (overrides config)' },
+		stdio: { type: 'boolean', description: 'Use stdio transport instead of HTTP' },
 	})
 	.run(async ({ flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
+		await initCliCommand('serve', { debug: flags.debug, config: flags.config })
 		const config = await loadConfig(process.cwd(), flags.config)
+		if (flags.stdio) {
+			log.debug('Starting MCP stdio transport')
+			await startMcpStdioServer(config)
+			return
+		}
 		if (flags.port) config.mcp.port = flags.port
 		if (flags.host) config.mcp.host = flags.host
+		log.debug('Starting MCP HTTP transport', { host: config.mcp.host, port: config.mcp.port })
 		await startMcpServer(config)
 		// Server runs indefinitely — no disconnect
 	})

package/src/cli/commands/sync.ts

@@ -1,8 +1,10 @@
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
-import { initLogger } from '../../logger.ts'
+import { getLogger } from '../../logger.ts'
 import { syncTo } from '../../sync.ts'
-import { app } from '../shared.ts'
+import { app, initCliCommand } from '../shared.ts'
+
+const log = getLogger(['suemo', 'cli', 'sync'])
 
 export const syncCmd = app.sub('sync')
 	.meta({ description: 'Push memories to remote SurrealDB (append-only)' })
@@ -10,14 +12,21 @@ export const syncCmd = app.sub('sync')
 		'dry-run': { type: 'boolean', description: 'Show what would be pushed without writing', default: false },
 	})
 	.run(async ({ flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
+		await initCliCommand('sync', { debug: flags.debug, config: flags.config })
 		const config = await loadConfig(process.cwd(), flags.config)
 		if (!config.sync) {
 			console.error('No sync.remote configured in suemo config.')
 			process.exit(1)
 		}
+		log.debug('Running sync command', {
+			dryRun: flags['dry-run'],
+			target: `${config.sync.remote.url}/${config.sync.remote.namespace}/${config.sync.remote.database}`,
+		})
 		const db = await connect(config.surreal)
-		const result = await syncTo(db, config.sync.remote, { dryRun: flags['dry-run'] })
-		await disconnect()
-		console.log(JSON.stringify(result, null, 2))
+		try {
+			const result = await syncTo(db, config.sync.remote, { dryRun: flags['dry-run'] })
+			console.log(JSON.stringify(result, null, 2))
+		} finally {
+			await disconnect()
+		}
 	})

package/src/cli/commands/timeline.ts

@@ -1,8 +1,10 @@
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
-import { initLogger } from '../../logger.ts'
+import { getLogger } from '../../logger.ts'
 import { timeline } from '../../memory/read.ts'
-import { app } from '../shared.ts'
+import { app, initCliCommand } from '../shared.ts'
+
+const log = getLogger(['suemo', 'cli', 'timeline'])
 
 export const timelineCmd = app.sub('timeline')
 	.meta({ description: 'Chronological view of memories' })
@@ -14,24 +16,34 @@ export const timelineCmd = app.sub('timeline')
 		json: { type: 'boolean', short: 'j', description: 'Output full JSON' },
 	})
 	.run(async ({ flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
+		await initCliCommand('timeline', { debug: flags.debug, config: flags.config })
+		log.debug('Running timeline command', {
+			hasScope: Boolean(flags.scope),
+			from: flags.from ?? null,
+			until: flags.until ?? null,
+			limit: flags.limit,
+			json: Boolean(flags.json),
+		})
 		const config = await loadConfig(process.cwd(), flags.config)
 		const db = await connect(config.surreal)
-		const nodes = await timeline(db, {
-			...(flags.scope ? { scope: flags.scope } : {}),
-			...(flags.from ? { from: flags.from } : {}),
-			...(flags.until ? { until: flags.until } : {}),
-			...(flags.limit ? { limit: flags.limit } : {}),
-		})
-		await disconnect()
-		if (flags.json) {
-			console.log(JSON.stringify(nodes, null, 2))
-		} else {
-			for (const n of nodes) {
-				const ts = new Date(n.created_at).toLocaleString()
-				console.log(`${ts}  [${n.kind}] ${n.id}`)
-				console.log(`  ${n.content.slice(0, 120)}`)
-				console.log()
+		try {
+			const nodes = await timeline(db, {
+				...(flags.scope ? { scope: flags.scope } : {}),
+				...(flags.from ? { from: flags.from } : {}),
+				...(flags.until ? { until: flags.until } : {}),
+				...(flags.limit ? { limit: flags.limit } : {}),
+			})
+			if (flags.json) {
+				console.log(JSON.stringify(nodes, null, 2))
+			} else {
+				for (const n of nodes) {
+					const ts = new Date(n.created_at).toLocaleString()
+					console.log(`${ts}  [${n.kind}] ${n.id}`)
+					console.log(`  ${n.content.slice(0, 120)}`)
+					console.log()
+				}
 			}
+		} finally {
+			await disconnect()
 		}
 	})

package/src/cli/commands/wander.ts

@@ -1,8 +1,10 @@
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
-import { initLogger } from '../../logger.ts'
+import { getLogger } from '../../logger.ts'
 import { wander } from '../../memory/read.ts'
-import { app } from '../shared.ts'
+import { app, initCliCommand } from '../shared.ts'
+
+const log = getLogger(['suemo', 'cli', 'wander'])
 
 export const wanderCmd = app.sub('wander')
 	.meta({ description: 'Spreading-activation walk through the memory graph' })
@@ -13,22 +15,31 @@ export const wanderCmd = app.sub('wander')
 		json: { type: 'boolean', short: 'j', description: 'Output full JSON nodes' },
 	})
 	.run(async ({ flags }) => {
-		await initLogger({ level: flags.debug ? 'debug' : 'info' })
+		await initCliCommand('wander', { debug: flags.debug, config: flags.config })
+		log.debug('Running wander command', {
+			hasAnchor: Boolean(flags.from),
+			hops: flags.hops,
+			hasScope: Boolean(flags.scope),
+			json: Boolean(flags.json),
+		})
 		const config = await loadConfig(process.cwd(), flags.config)
 		const db = await connect(config.surreal)
-		const nodes = await wander(db, {
-			...(flags.from ? { anchor: flags.from } : {}),
-			...(flags.hops ? { hops: flags.hops } : {}),
-			...(flags.scope ? { scope: flags.scope } : {}),
-		})
-		await disconnect()
-		if (flags.json) {
-			console.log(JSON.stringify(nodes, null, 2))
-		} else {
-			for (const n of nodes) {
-				console.log(`[${n.kind}] ${n.id}  salience=${n.salience.toFixed(2)}`)
-				console.log(`  ${n.content.slice(0, 120)}`)
-				console.log()
+		try {
+			const nodes = await wander(db, {
+				...(flags.from ? { anchor: flags.from } : {}),
+				...(flags.hops ? { hops: flags.hops } : {}),
+				...(flags.scope ? { scope: flags.scope } : {}),
+			})
+			if (flags.json) {
+				console.log(JSON.stringify(nodes, null, 2))
+			} else {
+				for (const n of nodes) {
+					console.log(`[${n.kind}] ${n.id}  salience=${n.salience.toFixed(2)}`)
+					console.log(`  ${n.content.slice(0, 120)}`)
+					console.log()
+				}
 			}
+		} finally {
+			await disconnect()
 		}
 	})

package/src/cli/index.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
 
 import { helpPlugin, versionPlugin } from '@crustjs/plugins'
-import { initLogger } from '../logger.ts'
 import { believeCmd } from './commands/believe.ts'
 import { consolidateCmd } from './commands/consolidate.ts'
+import { doctorCmd } from './commands/doctor.ts'
 import { exportCmd, importCmd } from './commands/export-import.ts'
 import { goalCmd } from './commands/goal.ts'
 import { healthCmd } from './commands/health.ts'
@@ -17,9 +17,7 @@ import { timelineCmd } from './commands/timeline.ts'
 import { wanderCmd } from './commands/wander.ts'
 import { app } from './shared.ts'
 
-import packageJson from '../../package.json' with { type: 'json' }
-
-await initLogger({ level: 'info' })
+import packageJson from '@/package.json' with { type: 'json' }
 
 await app
 	.use(versionPlugin(packageJson.version ?? '0.0.0'))
@@ -34,6 +32,7 @@ await app
 	.command(timelineCmd)
 	.command(goalCmd) // goal is a container: goal set / goal list / goal resolve
 	.command(consolidateCmd)
+	.command(doctorCmd)
 	.command(healthCmd)
 	.command(syncCmd)
 	.command(exportCmd)

package/src/cli/shared.ts

@@ -1,5 +1,39 @@
 // src/cli/shared.ts — single shared root, holds inheritable flags
 import { Crust } from '@crustjs/core'
+import { getLogger, initLogger } from '../logger.ts'
+
+const cliLog = getLogger(['suemo', 'cli'])
+
+const FALSE_ENV_VALUES = new Set(['0', 'false', 'no', 'off'])
+
+function isTruthyEnv(name: string): boolean {
+	const raw = process.env[name]
+	if (raw === undefined) return false
+	const normalized = raw.trim().toLowerCase()
+	if (normalized === '') return true
+	return !FALSE_ENV_VALUES.has(normalized)
+}
+
+export function isDebugEnabled(debugFlag?: boolean): boolean {
+	return Boolean(debugFlag) || isTruthyEnv('SUEMO_DEBUG')
+}
+
+export async function initCliCommand(
+	command: string,
+	flags: { debug?: boolean | undefined; config?: string | undefined },
+): Promise<void> {
+	const debug = isDebugEnabled(flags.debug)
+	await initLogger({ level: debug ? 'debug' : 'info' })
+	cliLog.debug('CLI command invocation', {
+		command,
+		cwd: process.cwd(),
+		debugFlag: flags.debug ?? false,
+		envDebug: process.env.SUEMO_DEBUG ?? null,
+		debugEnabled: debug,
+		configFlag: flags.config ?? null,
+		envConfigPath: process.env.SUEMO_CONFIG_PATH ?? null,
+	})
+}
 
 export const app = new Crust('suemo')
 	.meta({ description: 'Persistent semantic memory for AI agents' })