@onmars/lunar-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onMars Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @onmars/lunar-core
+
+Core runtime for [Lunar](https://github.com/onmars-tech/lunar) — types, config loader, session store, router, and plugin system.
+
+This package is used internally by `@onmars/lunar-cli`. Install the CLI instead:
+
+```bash
+bun install -g @onmars/lunar-cli
+```
+
+## License
+
+MIT — [onMars Tech](https://github.com/onmars-tech)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@onmars/lunar-core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./lib/*": "./src/lib/*.ts"
+  },
+  "files": ["src/", "LICENSE"],
+  "dependencies": {
+    "pino": "^10"
+  },
+  "description": "Core runtime for Lunar — types, config loader, session store, router, and plugin system",
+  "author": "onMars Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onmars-tech/lunar",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/onmars-tech/lunar",
+  "bugs": "https://github.com/onmars-tech/lunar/issues",
+  "keywords": ["lunar", "ai", "chatbot", "bun", "runtime"],
+  "publishConfig": {
+  "access": "public"
+},
+"engines": {
+"bun": ">=1.2"
+}
+}

package/src/__tests__/clear-command.test.ts

@@ -0,0 +1,214 @@
+/**
+ * /clear Command — Test Suite
+ *
+ * Spec: clears the current session (Claude context, tokens, message history).
+ * The next query starts a fresh Claude Code session without --resume.
+ *
+ * Key contracts:
+ * - Default: runs memory hooks before clearing (graceful)
+ * - --hard: skips hooks, clears immediately
+ * - Shows previous usage stats in the response
+ * - Response confirms what was cleared
+ * - Works even when no prior session exists
+ */
+import { describe, expect, test } from 'bun:test'
+import type { ClearResult, CommandContext } from '../lib/command-handler'
+import { clearCommand } from '../lib/commands/clear'
+import { SessionTracker } from '../lib/session-tracker'
+
+function makeCtx(
+  overrides?: Partial<CommandContext> & {
+    clearResult?: ClearResult
+  },
+): CommandContext {
+  const { clearResult, ...rest } = overrides ?? {}
+
+  return {
+    sessionKey: 'test:channel-1',
+    message: {
+      id: 'msg-1',
+      channelId: 'channel-1',
+      sender: { id: 'user-1', name: 'Test User' },
+      text: '/clear',
+      timestamp: new Date(),
+    },
+    tracker: new SessionTracker(),
+    daemonStartedAt: Date.now(),
+    agent: { id: 'claude', name: 'Claude Code (CLI)' },
+    clearSession: async () => clearResult ?? { sessionCleared: true, hooksRan: false },
+    ...rest,
+  }
+}
+
+function makeCtxWithUsage(opts?: { clearResult?: ClearResult; moonName?: string }): CommandContext {
+  const tracker = new SessionTracker()
+
+  // Simulate a session with some usage
+  tracker.recordQuery('test:channel-1', {
+    inputTokens: 5000,
+    outputTokens: 2000,
+    cacheReadTokens: 150000,
+    cacheWriteTokens: 10000,
+    contextTokens: 165000,
+    model: 'claude-sonnet-4-5-20250514',
+    durationMs: 12000,
+  })
+  tracker.recordMessage('test:channel-1')
+  tracker.recordMessage('test:channel-1')
+  tracker.recordMessage('test:channel-1')
+
+  return makeCtx({
+    tracker,
+    clearResult: opts?.clearResult,
+    moon: opts?.moonName
+      ? ({ name: opts.moonName, systemPrompt: '', files: {} } as any)
+      : undefined,
+  })
+}
+
+// ═══════════════════════════════════════════════════════════
+// Basic behavior
+// ═══════════════════════════════════════════════════════════
+
+describe('/clear basic', () => {
+  test('returns a response (never null)', async () => {
+    const result = await clearCommand('', makeCtx())
+    expect(result).not.toBeNull()
+    expect(typeof result).toBe('string')
+  })
+
+  test('response includes "Session Cleared"', async () => {
+    const result = await clearCommand('', makeCtx())
+    expect(result).toContain('Session Cleared')
+  })
+
+  test('response includes "fresh session" indication', async () => {
+    const result = await clearCommand('', makeCtx())
+    expect(result).toContain('fresh session')
+  })
+
+  test('uses moon name in header', async () => {
+    const ctx = makeCtx({
+      moon: { name: 'Clawmos', systemPrompt: '', files: {} } as any,
+    })
+    const result = await clearCommand('', ctx)
+    expect(result).toContain('Clawmos')
+  })
+
+  test('defaults to "Lunar" when no moon', async () => {
+    const result = await clearCommand('', makeCtx())
+    expect(result).toContain('Lunar')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// Usage display
+// ═══════════════════════════════════════════════════════════
+
+describe('/clear usage display', () => {
+  test('shows token count from previous session', async () => {
+    const result = await clearCommand('', makeCtxWithUsage())
+    // Total tokens: 5000 + 2000 + 150000 + 10000 = 167000 ≈ 167K
+    expect(result).toContain('167K')
+  })
+
+  test('shows message count', async () => {
+    const result = await clearCommand('', makeCtxWithUsage())
+    expect(result).toContain('3 messages')
+  })
+
+  test('shows turn count', async () => {
+    const result = await clearCommand('', makeCtxWithUsage())
+    expect(result).toContain('1 turn')
+  })
+
+  test('shows "no active session data" when no prior usage', async () => {
+    const result = await clearCommand('', makeCtx())
+    expect(result).toContain('no active session data')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// Hooks behavior
+// ═══════════════════════════════════════════════════════════
+
+describe('/clear hooks', () => {
+  test('calls clearSession without skipHooks by default', async () => {
+    let capturedOpts: any = null
+    const ctx = makeCtx({
+      clearSession: async (opts) => {
+        capturedOpts = opts
+        return { sessionCleared: true, hooksRan: true }
+      },
+    })
+
+    await clearCommand('', ctx)
+    expect(capturedOpts).toEqual({ skipHooks: false })
+  })
+
+  test('shows hooks ran when result.hooksRan is true', async () => {
+    const ctx = makeCtxWithUsage({
+      clearResult: { sessionCleared: true, hooksRan: true },
+    })
+    const result = await clearCommand('', ctx)
+    expect(result).toContain('hooks ran')
+  })
+
+  test('shows "no hooks to run" when graceful but no hooks ran', async () => {
+    const ctx = makeCtxWithUsage({
+      clearResult: { sessionCleared: true, hooksRan: false },
+    })
+    const result = await clearCommand('', ctx)
+    expect(result).toContain('no hooks to run')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// --hard flag
+// ═══════════════════════════════════════════════════════════
+
+describe('/clear --hard', () => {
+  test('passes skipHooks: true with --hard flag', async () => {
+    let capturedOpts: any = null
+    const ctx = makeCtx({
+      clearSession: async (opts) => {
+        capturedOpts = opts
+        return { sessionCleared: true, hooksRan: false }
+      },
+    })
+
+    await clearCommand('--hard', ctx)
+    expect(capturedOpts).toEqual({ skipHooks: true })
+  })
+
+  test('passes skipHooks: true with bare "hard" arg', async () => {
+    let capturedOpts: any = null
+    const ctx = makeCtx({
+      clearSession: async (opts) => {
+        capturedOpts = opts
+        return { sessionCleared: true, hooksRan: false }
+      },
+    })
+
+    await clearCommand('hard', ctx)
+    expect(capturedOpts).toEqual({ skipHooks: true })
+  })
+
+  test('shows "hooks skipped" in response', async () => {
+    const result = await clearCommand('--hard', makeCtx())
+    expect(result).toContain('hooks skipped')
+    expect(result).toContain('--hard')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// Cost display
+// ═══════════════════════════════════════════════════════════
+
+describe('/clear cost', () => {
+  test('shows cost estimate when > 0', async () => {
+    const result = await clearCommand('', makeCtxWithUsage())
+    // Should show some cost (Sonnet pricing on 167K tokens)
+    expect(result).toMatch(/\$/)
+  })
+})

package/src/__tests__/command-handler.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Command Handler — Test Suite
+ *
+ * Spec: intercepts slash commands before they reach the agent.
+ * Commands are processed at zero token cost with instant response.
+ *
+ * Key contracts:
+ * - Only messages starting with "/" are candidates
+ * - Only registered commands are handled
+ * - Unknown /commands pass through to agent (return null)
+ * - Args are parsed correctly (text after command name)
+ * - Commands can be async
+ */
+import { describe, expect, test } from 'bun:test'
+import { type CommandContext, CommandHandler } from '../lib/command-handler'
+import { SessionTracker } from '../lib/session-tracker'
+
+function makeCtx(overrides?: Partial<CommandContext>): CommandContext {
+  return {
+    sessionKey: 'test:channel-1',
+    message: {
+      id: 'msg-1',
+      channelId: 'channel-1',
+      sender: { id: 'user-1', name: 'Test User' },
+      text: '/test',
+      timestamp: new Date(),
+    },
+    tracker: new SessionTracker(),
+    daemonStartedAt: Date.now(),
+    agent: { id: 'claude', name: 'Claude Code (CLI)' },
+    clearSession: async () => ({ sessionCleared: true, hooksRan: false }),
+    ...overrides,
+  }
+}
+
+// ═══════════════════════════════════════════════════════════
+// Command detection
+// ═══════════════════════════════════════════════════════════
+
+describe('isCommand', () => {
+  test('recognizes registered commands', () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    expect(handler.isCommand('/status')).toBe(true)
+  })
+
+  test('case insensitive', () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    expect(handler.isCommand('/STATUS')).toBe(true)
+    expect(handler.isCommand('/Status')).toBe(true)
+  })
+
+  test('rejects unregistered commands', () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    expect(handler.isCommand('/unknown')).toBe(false)
+  })
+
+  test('rejects non-slash messages', () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    expect(handler.isCommand('hello')).toBe(false)
+    expect(handler.isCommand('status')).toBe(false)
+    expect(handler.isCommand('')).toBe(false)
+  })
+
+  test('handles whitespace', () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    expect(handler.isCommand('  /status  ')).toBe(true)
+  })
+
+  test('handles command with args', () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    expect(handler.isCommand('/status verbose')).toBe(true)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// Command handling
+// ═══════════════════════════════════════════════════════════
+
+describe('handle', () => {
+  test('executes registered command', async () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'Status: OK')
+
+    const result = await handler.handle('/status', makeCtx())
+    expect(result).toBe('Status: OK')
+  })
+
+  test('passes args to handler', async () => {
+    const handler = new CommandHandler()
+    handler.register('echo', 'Echo text', (args) => `Echo: ${args}`)
+
+    const result = await handler.handle('/echo hello world', makeCtx())
+    expect(result).toBe('Echo: hello world')
+  })
+
+  test('returns null for non-commands', async () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    const result = await handler.handle('hello', makeCtx())
+    expect(result).toBeNull()
+  })
+
+  test('returns null for unregistered commands', async () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+
+    const result = await handler.handle('/unknown', makeCtx())
+    expect(result).toBeNull()
+  })
+
+  test('supports async handlers', async () => {
+    const handler = new CommandHandler()
+    handler.register('async', 'Async test', async () => {
+      await new Promise((resolve) => setTimeout(resolve, 1))
+      return 'async result'
+    })
+
+    const result = await handler.handle('/async', makeCtx())
+    expect(result).toBe('async result')
+  })
+
+  test('handler can return null to pass through', async () => {
+    const handler = new CommandHandler()
+    handler.register('maybe', 'Maybe handle', (args) => {
+      return args === 'yes' ? 'handled' : null
+    })
+
+    expect(await handler.handle('/maybe yes', makeCtx())).toBe('handled')
+    expect(await handler.handle('/maybe no', makeCtx())).toBeNull()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// Registration and listing
+// ═══════════════════════════════════════════════════════════
+
+describe('register and list', () => {
+  test('list returns all registered commands', () => {
+    const handler = new CommandHandler()
+    handler.register('status', 'Show status', () => 'ok')
+    handler.register('help', 'Show help', () => 'ok')
+
+    const commands = handler.list()
+    expect(commands).toHaveLength(2)
+    expect(commands.find((c) => c.name === 'status')?.description).toBe('Show status')
+    expect(commands.find((c) => c.name === 'help')?.description).toBe('Show help')
+  })
+
+  test('register with leading / is normalized', () => {
+    const handler = new CommandHandler()
+    handler.register('/status', 'Show status', () => 'ok')
+
+    expect(handler.isCommand('/status')).toBe(true)
+    expect(handler.list()[0].name).toBe('status')
+  })
+})

package/src/__tests__/compact-command.test.ts

@@ -0,0 +1,80 @@
+/**
+ * /compact Command — Test Suite
+ *
+ * Spec: force context compaction (clears session with different wording).
+ *
+ * Key contracts:
+ * - Returns "Session Compacted" (not "Session Cleared")
+ * - Delegates to clearSession
+ * - Forwards --hard flag
+ * - Shows "fresh session" indication
+ */
+import { describe, expect, test } from 'bun:test'
+import type { ClearResult, CommandContext } from '../lib/command-handler'
+import { compactCommand } from '../lib/commands/compact'
+import { SessionTracker } from '../lib/session-tracker'
+
+function makeCtx(
+  overrides?: Partial<CommandContext> & {
+    clearResult?: ClearResult
+  },
+): CommandContext {
+  const { clearResult, ...rest } = overrides ?? {}
+
+  return {
+    sessionKey: 'test:channel-1',
+    message: {
+      id: 'msg-1',
+      channelId: 'channel-1',
+      sender: { id: 'user-1', name: 'Test User' },
+      text: '/compact',
+      timestamp: new Date(),
+    },
+    tracker: new SessionTracker(),
+    daemonStartedAt: Date.now(),
+    agent: { id: 'claude', name: 'Claude Code (CLI)' },
+    clearSession: async () => clearResult ?? { sessionCleared: true, hooksRan: false },
+    ...rest,
+  }
+}
+
+// ═══════════════════════════════════════════════════════════
+// Basic behavior
+// ═══════════════════════════════════════════════════════════
+
+describe('/compact basic', () => {
+  test('returns "Session Compacted" (not "Session Cleared")', async () => {
+    const result = await compactCommand('', makeCtx())
+    expect(result).toContain('Session Compacted')
+    expect(result).not.toContain('Session Cleared')
+  })
+
+  test('delegates to clearSession', async () => {
+    let clearCalled = false
+    const ctx = makeCtx({
+      clearSession: async () => {
+        clearCalled = true
+        return { sessionCleared: true, hooksRan: false }
+      },
+    })
+    await compactCommand('', ctx)
+    expect(clearCalled).toBe(true)
+  })
+
+  test('forwards --hard flag', async () => {
+    let capturedOpts: any = null
+    const ctx = makeCtx({
+      clearSession: async (opts) => {
+        capturedOpts = opts
+        return { sessionCleared: true, hooksRan: false }
+      },
+    })
+    await compactCommand('--hard', ctx)
+    expect(capturedOpts).toEqual({ skipHooks: true })
+  })
+
+  test('shows "fresh session" indication', async () => {
+    const result = await compactCommand('', makeCtx())
+    expect(result).toContain('fresh session')
+  })
+})