@brianli/kimaki 0.4.72-brianli.1

package/src/bin.ts

@@ -0,0 +1,108 @@
+// Respawn wrapper for the kimaki bot process.
+// When running the default command (no subcommand) with --auto-restart,
+// spawns cli.js as a child process and restarts it on non-zero exit codes
+// (crash, OOM kill, etc). Intentional exits (code 0 or EXIT_NO_RESTART=64)
+// are not restarted.
+//
+// Subcommands (send, tunnel, project, etc.) run directly without the wrapper
+// since they are short-lived and don't need crash recovery.
+//
+// When __KIMAKI_CHILD is set, we're the child process -- just run cli.js directly.
+//
+// V8 heap snapshot flags:
+// Injects --heapsnapshot-near-heap-limit=3 and --diagnostic-dir so V8 writes
+// heap snapshots internally as it approaches the heap limit. This catches OOM
+// situations where SIGKILL (exit 137) would kill the process before our
+// heap-monitor.ts polling can react. The polling monitor is kept as an early
+// warning system at 85% usage; the V8 flag is the last-resort safety net.
+
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const HEAP_SNAPSHOT_DIR = path.join(os.homedir(), '.kimaki', 'heap-snapshots')
+
+// First arg after node + script is either a subcommand or a flag.
+// If it doesn't start with '-', it's a subcommand (e.g. "send", "tunnel", "project").
+const firstArg = process.argv[2]
+const isSubcommand = firstArg && !firstArg.startsWith('-')
+const hasAutoRestart = process.argv.includes('--auto-restart')
+
+if (process.env.__KIMAKI_CHILD || isSubcommand || !hasAutoRestart) {
+  await import('./cli.js')
+} else {
+  const EXIT_NO_RESTART = 64
+  const MAX_RAPID_RESTARTS = 5
+  const RAPID_RESTART_WINDOW_MS = 60_000
+  const RESTART_DELAY_MS = 2_000
+
+  const restartTimestamps: number[] = []
+  let child: ReturnType<typeof spawn> | null = null
+  // Track when we forwarded a termination signal so we don't restart after graceful shutdown
+  let shutdownRequested = false
+
+  function start() {
+    if (!fs.existsSync(HEAP_SNAPSHOT_DIR)) {
+      fs.mkdirSync(HEAP_SNAPSHOT_DIR, { recursive: true })
+    }
+    const heapArgs = [
+      `--heapsnapshot-near-heap-limit=3`,
+      `--diagnostic-dir=${HEAP_SNAPSHOT_DIR}`,
+    ]
+    child = spawn(
+      process.argv[0]!,
+      [...heapArgs, ...process.execArgv, ...process.argv.slice(1)],
+      {
+        stdio: 'inherit',
+        env: { ...process.env, __KIMAKI_CHILD: '1' },
+      },
+    )
+
+    child.on('exit', (code, signal) => {
+      if (code === 0 || code === EXIT_NO_RESTART || shutdownRequested) {
+        process.exit(code ?? 0)
+        return
+      }
+
+      const now = Date.now()
+      restartTimestamps.push(now)
+      while (
+        restartTimestamps.length > 0 &&
+        restartTimestamps[0]! < now - RAPID_RESTART_WINDOW_MS
+      ) {
+        restartTimestamps.shift()
+      }
+
+      if (restartTimestamps.length > MAX_RAPID_RESTARTS) {
+        console.error(
+          `[kimaki] Crash loop detected (${MAX_RAPID_RESTARTS} crashes in ${RAPID_RESTART_WINDOW_MS / 1000}s), exiting`,
+        )
+        process.exit(1)
+        return
+      }
+
+      const reason = signal ? `signal ${signal}` : `code ${code}`
+      console.error(
+        `[kimaki] Process exited with ${reason}, restarting in ${RESTART_DELAY_MS / 1000}s...`,
+      )
+      setTimeout(start, RESTART_DELAY_MS)
+    })
+  }
+
+  // Forward signals to child so graceful shutdown and heap snapshots work.
+  // SIGTERM/SIGINT mark shutdownRequested so we don't restart after graceful exit.
+  for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+    process.on(sig, () => {
+      shutdownRequested = true
+      child?.kill(sig)
+    })
+  }
+  for (const sig of ['SIGUSR1', 'SIGUSR2'] as const) {
+    process.on(sig, () => {
+      child?.kill(sig)
+    })
+  }
+
+  start()
+}

package/src/bot-token.test.ts

@@ -0,0 +1,171 @@
+import crypto from 'node:crypto'
+import { afterAll, beforeEach, describe, expect, test } from 'vitest'
+import {
+  appIdFromToken,
+  getBotToken,
+  hydrateBotTokenCache,
+  isAuthModeEnabled,
+} from './bot-token.js'
+
+const ORIGINAL_BOT_TOKEN = process.env.KIMAKI_BOT_TOKEN
+const ORIGINAL_GUILD_ID = process.env.KIMAKI_GUILD_ID
+const ORIGINAL_PRIVATE_KEY = process.env.KIMAKI_PRIVATE_KEY
+const ORIGINAL_APP_ID = process.env.KIMAKI_APP_ID
+
+beforeEach(() => {
+  delete process.env.KIMAKI_BOT_TOKEN
+  delete process.env.KIMAKI_GUILD_ID
+  delete process.env.KIMAKI_PRIVATE_KEY
+  delete process.env.KIMAKI_APP_ID
+  hydrateBotTokenCache(null)
+})
+
+afterAll(() => {
+  process.env.KIMAKI_BOT_TOKEN = ORIGINAL_BOT_TOKEN
+  process.env.KIMAKI_GUILD_ID = ORIGINAL_GUILD_ID
+  process.env.KIMAKI_PRIVATE_KEY = ORIGINAL_PRIVATE_KEY
+  process.env.KIMAKI_APP_ID = ORIGINAL_APP_ID
+})
+
+describe('appIdFromToken', () => {
+  test('derives app id from valid token format', () => {
+    const token = 'MTQ3Njc0NTc2MzAwOTU5MzM2NQ.anything.anything'
+    expect(appIdFromToken(token)).toBe('1476745763009593365')
+  })
+
+  test('returns undefined for malformed tokens', () => {
+    expect(appIdFromToken('not-a-token')).toBeUndefined()
+    expect(appIdFromToken('')).toBeUndefined()
+  })
+})
+
+describe('getBotToken', () => {
+  test('prefers env token over db by default', () => {
+    process.env.KIMAKI_BOT_TOKEN =
+      'MTQ3Njc0NTc2MzAwOTU5MzM2NQ.env.payload'
+    hydrateBotTokenCache({ app_id: 'db-app', token: 'db-token' })
+
+    const resolved = getBotToken()
+
+    expect(resolved).toEqual({
+      token: 'MTQ3Njc0NTc2MzAwOTU5MzM2NQ.env.payload',
+      appId: '1476745763009593365',
+      source: 'env',
+    })
+  })
+
+  test('uses db token when env is absent', () => {
+    delete process.env.KIMAKI_BOT_TOKEN
+    hydrateBotTokenCache({
+      app_id: '1476745763009593365',
+      token: 'db-token',
+    })
+
+    const resolved = getBotToken()
+
+    expect(resolved).toEqual({
+      token: 'db-token',
+      appId: '1476745763009593365',
+      source: 'db',
+    })
+  })
+
+  test('supports db-only lookup when preferEnv is false', () => {
+    process.env.KIMAKI_BOT_TOKEN = 'env-token'
+    hydrateBotTokenCache({
+      app_id: '1476745763009593365',
+      token: 'db-token',
+    })
+
+    const resolved = getBotToken({ preferEnv: false })
+
+    expect(resolved).toEqual({
+      token: 'db-token',
+      appId: '1476745763009593365',
+      source: 'db',
+    })
+  })
+
+  test('can skip db lookup entirely', () => {
+    delete process.env.KIMAKI_BOT_TOKEN
+    hydrateBotTokenCache({ app_id: 'x', token: 'y' })
+
+    const resolved = getBotToken({ allowDatabase: false })
+
+    expect(resolved).toBeUndefined()
+  })
+
+  test('applies appId override consistently', () => {
+    process.env.KIMAKI_BOT_TOKEN = 'env-token'
+    const fromEnv = getBotToken({
+      appIdOverride: 'override-app-id',
+      allowDatabase: false,
+    })
+    expect(fromEnv?.appId).toBe('override-app-id')
+
+    delete process.env.KIMAKI_BOT_TOKEN
+    hydrateBotTokenCache({
+      app_id: 'db-app',
+      token: 'db-token',
+    })
+    const fromDb = getBotToken({
+      appIdOverride: 'override-app-id',
+    })
+    expect(fromDb?.appId).toBe('override-app-id')
+  })
+
+  test('auth mode takes precedence over env and db token', () => {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519')
+    process.env.KIMAKI_GUILD_ID = '1477130736841658398'
+    process.env.KIMAKI_APP_ID = '1476745763009593365'
+    process.env.KIMAKI_PRIVATE_KEY = privateKey
+      .export({ format: 'pem', type: 'pkcs8' })
+      .toString()
+    process.env.KIMAKI_BOT_TOKEN = 'env-token'
+    hydrateBotTokenCache({
+      app_id: 'db-app',
+      token: 'db-token',
+    })
+
+    const resolved = getBotToken()
+
+    expect(isAuthModeEnabled()).toBe(true)
+    expect(resolved?.source).toBe('auth')
+    expect(resolved?.appId).toBe('1476745763009593365')
+    expect(resolved?.token.split('.')).toHaveLength(3)
+
+    const tokenParts = resolved!.token.split('.')
+    expect(tokenParts).toHaveLength(3)
+    const guildPart = tokenParts[0]!
+    const timestamp = tokenParts[1]!
+    const signaturePart = tokenParts[2]!
+    const decodedGuildId = Buffer.from(guildPart, 'base64').toString('utf8')
+    expect(decodedGuildId).toBe('1477130736841658398')
+    expect(Number.isNaN(Number.parseInt(timestamp, 10))).toBe(false)
+
+    const signature = Buffer.from(signaturePart, 'base64url')
+    const verified = crypto.verify(
+      null,
+      Buffer.from(`${decodedGuildId}\n${timestamp}`, 'utf8'),
+      publicKey,
+      signature,
+    )
+    expect(verified).toBe(true)
+  })
+
+  test('auth mode requires all env vars', () => {
+    process.env.KIMAKI_GUILD_ID = '1477130736841658398'
+    delete process.env.KIMAKI_PRIVATE_KEY
+    process.env.KIMAKI_APP_ID = '1476745763009593365'
+    process.env.KIMAKI_BOT_TOKEN = 'env-token'
+
+    const resolved = getBotToken()
+
+    expect(isAuthModeEnabled()).toBe(false)
+    expect(resolved).toEqual({
+      token: 'env-token',
+      appId: undefined,
+      source: 'env',
+    })
+  })
+})

package/src/bot-token.ts

@@ -0,0 +1,159 @@
+import crypto from 'node:crypto'
+
+export type ResolvedBotToken = {
+  token: string
+  appId: string | undefined
+  source: 'auth' | 'env' | 'db'
+}
+
+export type StoredBotToken = { app_id: string; token: string }
+
+type GetBotTokenOptions = {
+  appIdOverride?: string
+  preferEnv?: boolean
+  allowDatabase?: boolean
+}
+
+let dbBotToken: StoredBotToken | null = null
+
+type AuthModeConfig = {
+  guildId: string
+  privateKey: string
+  appId: string
+}
+
+function toBase64(value: string): string {
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/')
+  const padding = '='.repeat((4 - (normalized.length % 4)) % 4)
+  return `${normalized}${padding}`
+}
+
+function resolveAuthModeConfig(): AuthModeConfig | null {
+  const guildId = process.env.KIMAKI_GUILD_ID?.trim()
+  const privateKey = process.env.KIMAKI_PRIVATE_KEY?.trim()
+  const appId = process.env.KIMAKI_APP_ID?.trim()
+  if (!guildId || !privateKey || !appId) {
+    return null
+  }
+  return {
+    guildId,
+    privateKey,
+    appId,
+  }
+}
+
+function parsePrivateKey(privateKeyValue: string): crypto.KeyObject {
+  if (privateKeyValue.includes('BEGIN PRIVATE KEY')) {
+    return crypto.createPrivateKey(privateKeyValue)
+  }
+
+  const candidates: Array<{ key: Buffer; format: 'der'; type: 'pkcs8' }> = []
+
+  try {
+    candidates.push({
+      key: Buffer.from(toBase64(privateKeyValue), 'base64'),
+      format: 'der',
+      type: 'pkcs8',
+    })
+  } catch {
+    // Ignore and continue to hex fallback.
+  }
+
+  try {
+    candidates.push({
+      key: Buffer.from(privateKeyValue, 'hex'),
+      format: 'der',
+      type: 'pkcs8',
+    })
+  } catch {
+    // Ignore and continue.
+  }
+
+  for (const candidate of candidates) {
+    try {
+      return crypto.createPrivateKey(candidate)
+    } catch {
+      // Try next candidate.
+    }
+  }
+
+  throw new Error('Invalid KIMAKI_PRIVATE_KEY for auth mode')
+}
+
+function createAuthModeToken(config: AuthModeConfig): string {
+  const timestamp = Date.now()
+  const key = parsePrivateKey(config.privateKey)
+  const message = `${config.guildId}\n${timestamp}`
+  const signature = crypto
+    .sign(null, Buffer.from(message, 'utf8'), key)
+    .toString('base64url')
+  const guildPart = Buffer.from(config.guildId, 'utf8').toString('base64')
+  return `${guildPart}.${timestamp}.${signature}`
+}
+
+// Derive the Discord Application ID from a bot token.
+// Discord bot tokens have the format: base64(userId).timestamp.hmac
+// The first segment is the bot's user ID (= Application ID) base64-encoded.
+export function appIdFromToken(token: string): string | undefined {
+  const segment = token.split('.')[0]
+  if (!segment) {
+    return undefined
+  }
+  try {
+    const decoded = Buffer.from(segment, 'base64').toString('utf8')
+    if (/^\d{17,20}$/.test(decoded)) {
+      return decoded
+    }
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function hydrateBotTokenCache(botToken: StoredBotToken | null): void {
+  dbBotToken = botToken
+}
+
+export function isAuthModeEnabled(): boolean {
+  return resolveAuthModeConfig() !== null
+}
+
+export function getBotToken(
+  options: GetBotTokenOptions = {},
+): ResolvedBotToken | undefined {
+  const { appIdOverride, preferEnv = true, allowDatabase = true } = options
+  const authMode = resolveAuthModeConfig()
+
+  if (authMode) {
+    return {
+      token: createAuthModeToken(authMode),
+      appId: appIdOverride || authMode.appId,
+      source: 'auth',
+    }
+  }
+
+  const envToken = process.env.KIMAKI_BOT_TOKEN
+
+  if (preferEnv && envToken) {
+    return {
+      token: envToken,
+      appId: appIdOverride || appIdFromToken(envToken),
+      source: 'env',
+    }
+  }
+
+  if (!allowDatabase) {
+    return undefined
+  }
+
+  const botRow = dbBotToken
+  if (!botRow) {
+    return undefined
+  }
+
+  return {
+    token: botRow.token,
+    appId: appIdOverride || botRow.app_id,
+    source: 'db',
+  }
+}

package/src/channel-management.ts

@@ -0,0 +1,172 @@
+// Discord channel and category management.
+// Creates and manages Kimaki project channels (text + voice pairs),
+// extracts channel metadata from topic tags, and ensures category structure.
+
+import {
+  ChannelType,
+  type CategoryChannel,
+  type Guild,
+  type TextChannel,
+} from 'discord.js'
+import path from 'node:path'
+import { getChannelDirectory, setChannelDirectory } from './database.js'
+
+export async function ensureKimakiCategory(
+  guild: Guild,
+  botName?: string,
+): Promise<CategoryChannel> {
+  // Skip appending bot name if it's already "kimaki" to avoid "Kimaki kimaki"
+  const isKimakiBot = botName?.toLowerCase() === 'kimaki'
+  const categoryName = botName && !isKimakiBot ? `Kimaki ${botName}` : 'Kimaki'
+
+  const existingCategory = guild.channels.cache.find(
+    (channel): channel is CategoryChannel => {
+      if (channel.type !== ChannelType.GuildCategory) {
+        return false
+      }
+
+      return channel.name.toLowerCase() === categoryName.toLowerCase()
+    },
+  )
+
+  if (existingCategory) {
+    return existingCategory
+  }
+
+  return guild.channels.create({
+    name: categoryName,
+    type: ChannelType.GuildCategory,
+  })
+}
+
+export async function ensureKimakiAudioCategory(
+  guild: Guild,
+  botName?: string,
+): Promise<CategoryChannel> {
+  // Skip appending bot name if it's already "kimaki" to avoid "Kimaki Audio kimaki"
+  const isKimakiBot = botName?.toLowerCase() === 'kimaki'
+  const categoryName =
+    botName && !isKimakiBot ? `Kimaki Audio ${botName}` : 'Kimaki Audio'
+
+  const existingCategory = guild.channels.cache.find(
+    (channel): channel is CategoryChannel => {
+      if (channel.type !== ChannelType.GuildCategory) {
+        return false
+      }
+
+      return channel.name.toLowerCase() === categoryName.toLowerCase()
+    },
+  )
+
+  if (existingCategory) {
+    return existingCategory
+  }
+
+  return guild.channels.create({
+    name: categoryName,
+    type: ChannelType.GuildCategory,
+  })
+}
+
+export async function createProjectChannels({
+  guild,
+  projectDirectory,
+  appId,
+  botName,
+  enableVoiceChannels = false,
+}: {
+  guild: Guild
+  projectDirectory: string
+  appId: string
+  botName?: string
+  enableVoiceChannels?: boolean
+}): Promise<{
+  textChannelId: string
+  voiceChannelId: string | null
+  channelName: string
+}> {
+  const baseName = path.basename(projectDirectory)
+  const channelName = `${baseName}`
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .slice(0, 100)
+
+  const kimakiCategory = await ensureKimakiCategory(guild, botName)
+
+  const textChannel = await guild.channels.create({
+    name: channelName,
+    type: ChannelType.GuildText,
+    parent: kimakiCategory,
+    // Channel configuration is stored in SQLite, not in the topic
+  })
+
+  await setChannelDirectory({
+    channelId: textChannel.id,
+    directory: projectDirectory,
+    channelType: 'text',
+    appId,
+  })
+
+  let voiceChannelId: string | null = null
+
+  if (enableVoiceChannels) {
+    const kimakiAudioCategory = await ensureKimakiAudioCategory(guild, botName)
+
+    const voiceChannel = await guild.channels.create({
+      name: channelName,
+      type: ChannelType.GuildVoice,
+      parent: kimakiAudioCategory,
+    })
+
+    await setChannelDirectory({
+      channelId: voiceChannel.id,
+      directory: projectDirectory,
+      channelType: 'voice',
+      appId,
+    })
+
+    voiceChannelId = voiceChannel.id
+  }
+
+  return {
+    textChannelId: textChannel.id,
+    voiceChannelId,
+    channelName,
+  }
+}
+
+export type ChannelWithTags = {
+  id: string
+  name: string
+  description: string | null
+  kimakiDirectory?: string
+  kimakiApp?: string
+}
+
+export async function getChannelsWithDescriptions(
+  guild: Guild,
+): Promise<ChannelWithTags[]> {
+  const channels: ChannelWithTags[] = []
+
+  const textChannels = guild.channels.cache.filter((channel) =>
+    channel.isTextBased(),
+  )
+
+  for (const channel of textChannels.values()) {
+    const textChannel = channel as TextChannel
+    const description = textChannel.topic || null
+
+    // Get channel config from database instead of parsing XML from topic
+    const channelConfig = await getChannelDirectory(textChannel.id)
+
+    channels.push({
+      id: textChannel.id,
+      name: textChannel.name,
+      description,
+      kimakiDirectory: channelConfig?.directory,
+      kimakiApp: channelConfig?.appId || undefined,
+    })
+  }
+
+  return channels
+}