chudbot 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Basedwon
+
+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,225 @@
+<p align="center">
+  <img src="chud.png" width="300" />
+</p>
+
+<h1 align="center">Chudbot</h1>
+
+<p align="center">
+  Chudbot is a stupid-simple “chat in a file” bot.
+</p>
+
+You write messages in a `chat.md` file, save it, and Chudbot appends the assistant reply right into the same file.
+
+## What you need
+
+- A computer (Windows or Mac)
+- Node.js (free)
+- An OpenRouter account + API key
+
+## Step 1: Install Node.js
+
+### Windows
+
+1. Go to nodejs.org
+2. Download the LTS installer
+3. Run it (Next, Next, Finish)
+4. Open **PowerShell** (Start menu → type “PowerShell”)
+
+### Mac
+
+1. Go to nodejs.org
+2. Download the LTS installer
+3. Run it
+4. Open **Terminal**
+
+To confirm Node is installed, run:
+
+```bash
+node -v
+npm -v
+```
+
+## Step 2: Install Chudbot
+
+Install it globally:
+
+```bash
+npm install -g chudbot
+```
+
+Confirm it works:
+
+```bash
+chudbot --help
+```
+
+## Step 3: Create an OpenRouter account and API key
+
+1. Create an account:
+
+[https://openrouter.ai](https://openrouter.ai/)
+
+1. Create an API key:
+
+https://openrouter.ai/settings/keys
+
+You’ll paste that key into Chudbot’s `.env` in a minute.
+
+## Step 4: Create a folder and open a terminal in it
+
+Create a new folder anywhere you want, for example:
+
+- `Desktop/chudbot-test`
+
+Now open a terminal and make sure you’re “in” that folder.
+
+If you already have a terminal open, you can always use `cd` to switch into the folder.
+
+### Windows
+
+Option A (easiest): open PowerShell directly in the folder
+
+1. Open File Explorer and open your `chudbot-test` folder
+2. Click the address bar (where the folder path is)
+3. Type `powershell` and press Enter
+
+Option B: open PowerShell first, then cd
+
+```bash
+cd $HOME
+cd Desktop
+cd chudbot-test
+```
+
+### Mac
+
+Option A: open Terminal, then cd
+
+1. Open Terminal
+2. Type `cd` (with a space)
+3. Drag the folder into the Terminal window
+4. Press Enter
+
+Option B (if enabled): open Terminal at the folder
+
+- In Finder, right-click the folder → Services → New Terminal at Folder
+
+## Step 5: Initialize the folder
+
+This creates a starter `chat.md` in your folder.
+
+It also creates `~/.chudbot/.env` if it doesn’t exist yet.
+
+```bash
+chudbot init
+```
+
+## Step 6: Paste your API key into Chudbot’s .env
+
+Chudbot reads its API key from your user folder:
+
+- Mac: `~/.chudbot/.env`
+- Windows: `%USERPROFILE%\\.chudbot\\.env`
+
+Open that file and set:
+
+```bash
+OPENROUTER_API_KEY=YOUR_KEY_HERE
+OPENROUTER_MODEL=openrouter/free
+```
+
+`openrouter/free` routes to a currently-free option on OpenRouter. If it ever errors later, pick a different model.
+
+## Step 7: Use it
+
+Open `chat.md`, type under the last `# %% user` block, save the file, then run:
+
+```bash
+chudbot run
+```
+
+It only runs if the chat ends with a non-empty `# %% user` message.
+
+On success it appends `# %% assistant` with the reply, then appends a fresh `# %% user` header so you can type the next message.
+
+## Watch mode (auto-reply on save)
+
+```bash
+chudbot watch
+```
+
+Stop with **Ctrl+C**.
+
+## How the chat format works
+
+A chat file is just blocks. Each block starts with a header line:
+
+- `# %% system`
+- `# %% user`
+- `# %% assistant`
+
+Everything under that header (until the next header) is the message content.
+
+Important rule: only type into the LAST `# %% user` block.
+
+## Optional: create memory.md
+
+If you create a `memory.md`, it gets injected as extra system instructions.
+
+Example `memory.md`:
+
+```markdown
+- My name is Craig
+- Keep answers short and practical
+- I like humor
+```
+
+## Advanced: front matter
+
+At the very top of `chat.md`, you can add front matter to set the model and memory file for that chat:
+
+```markdown
+---
+model: openrouter/free
+memory: memory.md
+---
+```
+
+If you want the local memory file to override root memory instead of merging, add:
+
+```markdown
+---
+memory.override: true
+---
+```
+
+## Where files are loaded from
+
+Chat:
+
+- Uses `chat.md` in your current folder by default (or `f/--chat`)
+
+Env:
+
+- Mac: `~/.chudbot/.env`
+- Windows: `%USERPROFILE%\\.chudbot\\.env`
+
+Memory:
+
+- Root memory: `~/.chudbot/memory.md` (Windows: `%USERPROFILE%\\.chudbot\\memory.md`)
+- Local memory: `memory.md` next to your `chat.md`
+- Default behavior is merge (root + blank line + local)
+- If `memory.override: true` is set in chat front matter, local memory overrides root
+
+## Troubleshooting
+
+- “Missing OPENROUTER_API_KEY”
+    - Put your key into `~/.chudbot/.env` (Windows: `%USERPROFILE%\\.chudbot\\.env`)
+- “It didn’t reply”
+    - Make sure the chat ends with a `# %% user` block that has real text
+- “401 / unauthorized”
+    - Your API key is missing or wrong
+- “Model not found”
+    - Try a different `OPENROUTER_MODEL` or set `model:` in chat front matter
+- “It replied twice / weird loop”
+    - Only edit the last `# %% user` block, and let the bot append assistant blocks

package/bin/chudbot-cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+const path = require('path')
+const { Command } = require('commander')
+
+const pkg = require('../package.json')
+const { Chudbot } = require('../lib/chudbot')
+
+function int(v, def) {
+  const n = parseInt(v, 10)
+  return Number.isFinite(n) ? n : def
+}
+
+function pick(opts, keys) {
+  const out = {}
+  for (const k of keys) {
+    if (opts[k] !== undefined)
+      out[k] = opts[k]
+  }
+  return out
+}
+
+function makeBot(opts) {
+  return new Chudbot(pick(opts, ['userRoot', 'chudRoot', 'envPath', 'debounceMs']))
+}
+
+async function main(argv) {
+  const program = new Command()
+  program
+    .name('chudbot')
+    .description('A tiny local markdown chatbot (chat.md in, replies appended)')
+    .version(pkg.version)
+    .option('--user-root <dir>', 'override OS home dir')
+    .option('--chud-root <dir>', 'override chudbot root (default: ~/.chudbot)')
+    .option('--env <path>', 'override env path (default: ~/.chudbot/.env)')
+
+  program
+    .command('init')
+    .description('Create a starter chat file in a folder')
+    .option('-C, --cwd <dir>', 'target folder (default: current folder)')
+    .option('-f, --chat <file>', 'chat filename (default: chat.md)')
+    .option('--force', 'overwrite chat file if it exists', false)
+    .option('--system <text>', 'system prompt for the starter chat')
+    .action((opts) => {
+      const root = program.opts()
+      const bot = makeBot(root)
+      const res = bot.init({
+        cwd: opts.cwd || process.cwd(),
+        chat: opts.chat,
+        force: !!opts.force,
+        system: opts.system,
+      })
+      console.log('created:', res.chatPath)
+    })
+
+  program
+    .command('run')
+    .description('Run once and append the assistant reply (if last user block is non-empty)')
+    .option('-C, --cwd <dir>', 'folder to run in (default: current folder)')
+    .option('-f, --chat <file>', 'chat file (default: chat.md)')
+    .option('-m, --memory <file>', 'memory file (default: memory.md)')
+    .option('--model <id>', 'model id (default: openrouter/free)')
+    .action(async (opts) => {
+      const root = program.opts()
+      const bot = makeBot(root)
+      const res = await bot.run({
+        cwd: opts.cwd || process.cwd(),
+        chat: opts.chat,
+        memory: opts.memory,
+        model: opts.model,
+      })
+      if (!res.ok) {
+        console.error(res.error && res.error.message ? res.error.message : res.error)
+        process.exitCode = 1
+        return
+      }
+      if (!res.didRun) {
+        console.log('no-op: chat did not end with a non-empty # %% user block')
+        return
+      }
+      console.log('appended reply to:', res.chatPath)
+    })
+
+  program
+    .command('watch')
+    .description('Watch chat file and auto-append replies on save (Ctrl+C to stop)')
+    .option('-C, --cwd <dir>', 'folder to run in (default: current folder)')
+    .option('-f, --chat <file>', 'chat file (default: chat.md)')
+    .option('-m, --memory <file>', 'memory file (default: memory.md)')
+    .option('--model <id>', 'model id (default: openrouter/free)')
+    .option('--debounce-ms <n>', 'debounce delay in ms (default: 200)')
+    .action((opts) => {
+      const root = program.opts()
+      const bot = makeBot({ ...root, debounceMs: int(opts.debounceMs, 200) })
+
+      const res = bot.watch({
+        cwd: opts.cwd || process.cwd(),
+        chat: opts.chat,
+        memory: opts.memory,
+        model: opts.model,
+        debounceMs: int(opts.debounceMs, 200),
+      })
+
+      const chatPath = res && res.chatPath
+        ? res.chatPath
+        : path.join(opts.cwd || process.cwd(), opts.chat || 'chat.md')
+
+      console.log('watching:', chatPath)
+      console.log('tip: edit the last # %% user block, save, and wait for the reply')
+      console.log('tip: press Ctrl+C to stop')
+
+      const onStop = async () => {
+        try {
+          await bot.stop()
+        } catch (_) {}
+        process.exit(0)
+      }
+      process.on('SIGINT', onStop)
+      process.on('SIGTERM', onStop)
+    })
+
+  program.addHelpText(
+    'afterAll',
+    '\nMore help: read the README in the project folder.\n'
+  )
+
+  await program.parseAsync(argv)
+}
+
+main(process.argv).catch((err) => {
+  console.error(err && err.message ? err.message : err)
+  process.exitCode = 1
+})

package/lib/chudbot.js

@@ -0,0 +1,105 @@
+const os = require('os')
+const fs = require('fs')
+const path = require('path')
+
+const { Runner } = require('./runner')
+const { Watcher } = require('./watcher')
+const { ChatParser } = require('./parser')
+const { Provider } = require('./provider')
+const { ContextResolver } = require('./resolver')
+const { EnvLoader, Initializer } = require('./initializer')
+
+const ANSI_DIM = '\x1b[2m'
+const ANSI_RESET = '\x1b[0m'
+
+class Spinner {
+  constructor() {
+    this.spinner = null
+    this.spinnerFrame = 0
+    this.spinnerFrames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏']
+    this.spinnerActive = false
+  }
+  startSpinner(label = 'thinking') {
+    if (this.spinnerActive) return
+    this.spinnerActive = true
+    process.stdout.write(ANSI_DIM)
+    this.spinner = setInterval(() => {
+      const index = this.spinnerFrame++ % this.spinnerFrames.length
+      const frame = this.spinnerFrames[index]
+      process.stdout.write('\r' + frame + ' ' + label)
+    }, 80)
+  }
+  stopSpinner() {
+    if (!this.spinnerActive) return
+    clearInterval(this.spinner)
+    this.spinner = null
+    this.spinnerActive = false
+    process.stdout.write('\r\x1b[K')
+    process.stdout.write(ANSI_RESET)
+  }
+}
+class Chudbot {
+  constructor(opts = {}) {
+    this.userRoot = opts.userRoot || os.homedir()
+    this.chudRoot = opts.chudRoot || path.join(this.userRoot, '.chudbot')
+    this.envPath = opts.envPath || path.join(this.chudRoot, '.env')
+
+    this.parser = new ChatParser(opts)
+    this.resolver = new ContextResolver({
+      ...opts,
+      userRoot: this.userRoot,
+      chudRoot: this.chudRoot,
+      envPath: this.envPath,
+    })
+    this.env = new EnvLoader({
+      ...opts,
+      userRoot: this.userRoot,
+      chudRoot: this.chudRoot,
+      envPath: this.envPath,
+    })
+    this.initializer = new Initializer({
+      ...opts,
+      userRoot: this.userRoot,
+      chudRoot: this.chudRoot,
+      envPath: this.envPath,
+    })
+
+    this.initializer.initRoot({ makeEnv: true })
+    this.env.load({ envPath: this.envPath, required: false, override: false })
+
+    this.provider = new Provider(opts)
+    this.runner = new Runner({
+      parser: this.parser,
+      resolver: this.resolver,
+      provider: this.provider,
+    })
+    const spinner = new Spinner()
+    this.watcher = new Watcher({
+      runner: this.runner,
+      debounceMs: opts.debounceMs,
+      onEvent: (evt) => {
+        if (evt.type === 'signal')
+          spinner.startSpinner('thinking')
+        if (evt.type === 'run_end')
+          spinner.stopSpinner()
+      },
+    })
+  }
+  init(opts = {}) {
+    // opts.cwd, opts.chat, opts.force, opts.system
+    return this.initializer.initChat(opts)
+  }
+  async run(opts = {}) {
+    // opts.cwd, opts.chat, opts.memory, opts.model
+    return await this.runner.runOnce(opts)
+  }
+  watch(opts = {}) {
+    // opts.cwd, opts.chat, opts.memory, opts.model, opts.debounceMs
+    return this.watcher.start(opts)
+  }
+  async stop() {
+    return await this.watcher.stop()
+  }
+}
+
+module.exports = { Chudbot }

package/lib/initializer.js

@@ -0,0 +1,119 @@
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const dotenv = require('dotenv')
+
+class EnvLoader {
+  constructor(opts = {}) {
+    this.userRoot = opts.userRoot || os.homedir()
+    this.chudRoot = opts.chudRoot || path.join(this.userRoot, '.chudbot')
+    this.envPath = opts.envPath || path.join(this.chudRoot, '.env')
+  }
+  load(opts = {}) {
+    // Loads env vars from envPath into process.env.
+    // opts.envPath: string (override)
+    // opts.override: boolean (default false)
+    // opts.required: boolean (default false)
+    const envPath = opts.envPath || this.envPath
+    const override = opts.override ?? false
+    const required = opts.required ?? false
+    if (!fs.existsSync(envPath)) {
+      if (required)
+        throw new Error('Missing env file: ' + envPath)
+      return { ok: true, envPath, loaded: false }
+    }
+    const res = dotenv.config({ path: envPath, override, quiet: true })
+    if (res && res.error)
+      throw res.error
+    return { ok: true, envPath, loaded: true }
+  }
+}
+
+class Initializer {
+  constructor(opts = {}) {
+    this.userRoot = opts.userRoot || os.homedir()
+    this.chudRoot = opts.chudRoot || path.join(this.userRoot, '.chudbot')
+    this.envPath = opts.envPath || path.join(this.chudRoot, '.env')
+    this.defaultChatName = opts.defaultChatName || 'chat.md'
+  }
+  initRoot(opts = {}) {
+    // Create chudRoot and (optionally) starter .env.
+    // opts.makeEnv: boolean (default true)
+    const makeEnv = opts.makeEnv ?? true
+    fs.mkdirSync(this.chudRoot, { recursive: true })
+    const b = makeEnv
+      ? this.writeIfMissing(this.envPath, this.defaultEnv(), { force: false })
+      : { didWrite: false }
+    return {
+      ok: true,
+      chudRoot: this.chudRoot,
+      envPath: this.envPath,
+      didWriteEnv: b.didWrite,
+    }
+  }
+  initChat(opts = {}) {
+    // Create starter chat in opts.cwd.
+    // opts.cwd: string (default process.cwd())
+    // opts.chat: string (default chat.md)
+    // opts.force: boolean
+    // opts.system: string
+    const cwd = opts.cwd || process.cwd()
+    const chat = opts.chat || this.defaultChatName
+    const force = opts.force ?? false
+    const chatPath = path.isAbsolute(chat) ? chat : path.join(cwd, chat)
+    const a = this.writeIfMissing(
+      chatPath,
+      this.defaultChat({ system: opts.system }),
+      { force }
+    )
+    return { ok: true, chatPath, didWriteChat: a.didWrite }
+  }
+  init(opts = {}) {
+    // Convenience: initRoot + initChat.
+    const root = this.initRoot({ makeEnv: opts.makeEnv })
+    const chat = this.initChat(opts)
+    return {
+      ok: true,
+      chudRoot: root.chudRoot,
+      envPath: root.envPath,
+      chatPath: chat.chatPath,
+      didWriteEnv: root.didWriteEnv,
+      didWriteChat: chat.didWriteChat,
+    }
+  }
+  defaultChat(opts = {}) {
+    // System + empty user header.
+    const system = String(opts.system || 'You are a helpful assistant.').trim()
+    return [
+      '# %% system',
+      system,
+      '',
+      '# %% user',
+      '',
+    ].join('\n')
+  }
+  defaultEnv() {
+    // Minimal template.
+    return [
+      '# Chudbot env',
+      '# Put your key here:',
+      'OPENROUTER_API_KEY=REPLACE_ME',
+      'OPENROUTER_MODEL=openrouter/free',
+      '',
+    ].join('\n')
+  }
+  writeIfMissing(filePath, content, opts = {}) {
+    // Write only if missing unless force.
+    const force = opts.force ?? false
+    const p = String(filePath || '')
+    if (!p)
+      throw new Error('Missing filePath')
+    if (fs.existsSync(p) && !force)
+      return { didWrite: false }
+    fs.mkdirSync(path.dirname(p), { recursive: true })
+    fs.writeFileSync(p, String(content || ''), 'utf8')
+    return { didWrite: true }
+  }
+}
+
+module.exports = { EnvLoader, Initializer }

package/lib/parser.js

@@ -0,0 +1,117 @@
+class ChatParser {
+  constructor(opts = {}) {
+    this.eol = opts.eol || '\n'
+    this.headerRe = opts.headerRe || /^#\s*%%\s*(\w+)\s*$/
+    this.allowedRoles = opts.allowedRoles || {
+      system: true,
+      user: true,
+      assistant: true,
+    }
+  }
+  parse(raw, opts = {}) {
+    raw = String(raw || '')
+    const fm = this.parseFrontMatter(raw)
+    if (fm && fm.body != null)
+      raw = fm.body
+    const blocks = this.parseBlocks(raw, opts)
+    const messages = blocks.map((b) => ({ role: b.role, content: b.content }))
+    return {
+      frontMatter: fm ? fm.data : {},
+      blocks,
+      messages,
+    }
+  }
+  parseFile(filePath, opts = {}) {
+    const raw = require('fs').readFileSync(filePath, 'utf8')
+    return this.parse(raw, { ...opts, filePath })
+  }
+  parseFrontMatter(raw) {
+    // Minimal YAML-ish front matter:
+    // ---
+    // model: openrouter/free
+    // memory: memory.md
+    // ---
+    // Only supports top-level key: value pairs.
+    const s = String(raw || '')
+    if (!s.startsWith('---\n') && !s.startsWith('---\r\n'))
+      return null
+    const endIdx = s.indexOf('\n---', 4)
+    if (endIdx === -1)
+      return null
+    const head = s.slice(4, endIdx + 1)
+    const body = s.slice(endIdx + 5)
+    const data = {}
+    for (const line of head.split(/\r?\n/)) {
+      const t = String(line || '').trim()
+      if (!t || t.startsWith('#'))
+        continue
+      const ii = t.indexOf(':')
+      if (ii === -1)
+        continue
+      const k = t.slice(0, ii).trim()
+      let v = t.slice(ii + 1).trim()
+      if ((v.startsWith('"') && v.endsWith('"')) ||
+        (v.startsWith("'") && v.endsWith("'")))
+        v = v.slice(1, -1)
+      if (k)
+        data[k] = v
+    }
+    return { data, body }
+  }
+  parseBlocks(raw, opts = {}) {
+    const lines = String(raw || '').split(/\r?\n/)
+    const blocks = []
+    let cur = null
+    let buf = []
+    const push = () => {
+      if (!cur)
+        return
+      const content = buf.join(this.eol).replace(/\s+$/,'')
+      blocks.push({ role: cur, content })
+      buf = []
+    }
+    for (const line of lines) {
+      const m = String(line || '').match(this.headerRe)
+      if (m) {
+        push()
+        const role = String(m[1] || '').toLowerCase()
+        if (!this.allowedRoles[role]) {
+          if (opts.allowUnknown)
+            cur = role
+          else
+            throw new Error('Unknown role: ' + role)
+        } else {
+          cur = role
+        }
+        continue
+      }
+      if (cur)
+        buf.push(line)
+    }
+    push()
+    return blocks
+  }
+  isRunnable(parsed, opts = {}) {
+    const minLen = Number(opts.minLen || 1)
+    const last = this.getLastBlock(parsed)
+    if (!last || last.role !== 'user')
+      return false
+    return String(last.content || '').trim().length >= minLen
+  }
+  getLastBlock(parsed) {
+    const blocks = parsed && parsed.blocks
+    if (!Array.isArray(blocks) || !blocks.length)
+      return null
+    return blocks[blocks.length - 1]
+  }
+  formatAppendAssistant(text, opts = {}) {
+    const trim = opts.trim ?? true
+    const body = trim ? String(text || '').trim() : String(text || '')
+    return this.eol + this.eol + '# %% assistant' + this.eol + body
+  }
+  formatAppendUser() {
+    return this.eol + this.eol + '# %% user' + this.eol
+  }
+}
+
+module.exports = { ChatParser }

package/lib/provider.js

@@ -0,0 +1,69 @@
+const axios = require('axios')
+const path = require('path')
+const os = require('os')
+const dotenv = require('dotenv')
+
+class Provider {
+  constructor(opts = {}) {
+    this.baseUrl = opts.baseUrl || 'https://openrouter.ai/api/v1'
+    this.apiKey = opts.apiKey || process.env.OPENROUTER_API_KEY || ''
+    this.model = opts.model || process.env.OPENROUTER_MODEL || 'openrouter/free'
+    this.timeoutMs = opts.timeoutMs || 60000
+    this.headers = opts.headers || {}
+    if (!this.apiKey)
+      throw new Error('Missing OPENROUTER_API_KEY')
+  }
+  async send(messages, opts = {}) {
+    // POST /chat/completions, return full JSON response.
+    // opts.model, opts.temperature, opts.maxTokens, opts.headers
+    const url = this.baseUrl.replace(/\/+$/, '') + '/chat/completions'
+    const model = opts.model || this.model
+    const payload = {
+      model,
+      messages,
+    }
+    if (opts.temperature != null)
+      payload.temperature = opts.temperature
+    if (opts.maxTokens != null)
+      payload.max_tokens = opts.maxTokens
+    const headers = {
+      Authorization: 'Bearer ' + this.apiKey,
+      'Content-Type': 'application/json',
+      ...this.headers,
+      ...(opts.headers || {}),
+    }
+    try {
+      const res = await axios.post(url, payload, {
+        headers,
+        timeout: this.timeoutMs,
+      })
+      return res.data
+    } catch (err) {
+      const r = err && err.response
+      if (r && r.status)
+        throw new Error('OpenRouter ' + r.status + ': ' + this._errMsg(r.data))
+      throw err
+    }
+  }
+  async complete(messages, opts = {}) {
+    // send() then return assistant content string.
+    const json = await this.send(messages, opts)
+    return this.extractContent(json)
+  }
+  extractContent(json) {
+    const c = json && json.choices && json.choices[0]
+    const m = c && c.message
+    const t = m && m.content
+    const s = String(t || '')
+    if (!s.trim())
+      throw new Error('Missing assistant content')
+    return s
+  }
+  _errMsg(data) {
+    const e = data && (data.error || data)
+    const m = e && (e.message || e.error || e)
+    return String(m || 'request failed')
+  }
+}
+
+module.exports = { Provider }

package/lib/resolver.js

@@ -0,0 +1,103 @@
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+class ContextResolver {
+  constructor(opts = {}) {
+    this.userRoot = opts.userRoot || os.homedir()
+    this.chudRoot = opts.chudRoot || path.join(this.userRoot, '.chudbot')
+    this.envPath = opts.envPath || path.join(this.chudRoot, '.env')
+    this.defaultChatName = opts.defaultChatName || 'chat.md'
+    this.defaultMemoryName = opts.defaultMemoryName || 'memory.md'
+  }
+  resolvePaths(opts = {}) {
+    // Finds chat in cwd first, then chudRoot.
+    const cwd = opts.cwd || process.cwd()
+    const chatName = opts.chat || this.defaultChatName
+    const chatPath = this._pickPath(chatName, [cwd, this.chudRoot])
+    const chatDir = path.dirname(chatPath)
+    const fm = opts.frontMatter || null
+    const memName = (fm && fm.memory) || opts.memory || this.defaultMemoryName
+    const rootMem = path.join(this.chudRoot, this.defaultMemoryName)
+    const localMem = this._pickPath(memName, [chatDir], { allowMissing: true })
+    return {
+      cwd,
+      userRoot: this.userRoot,
+      chudRoot: this.chudRoot,
+      envPath: this.envPath,
+      chatPath,
+      rootMemoryPath: rootMem,
+      localMemoryPath: localMem,
+    }
+  }
+  readText(filePath, opts = {}) {
+    // opts.required: throw if missing
+    const p = String(filePath || '')
+    if (!p)
+      return ''
+    if (!fs.existsSync(p)) {
+      if (opts.required)
+        throw new Error('Missing file: ' + p)
+      return ''
+    }
+    return fs.readFileSync(p, 'utf8')
+  }
+  loadChat(opts = {}) {
+    const paths = this.resolvePaths(opts)
+    const raw = this.readText(paths.chatPath, { required: true })
+    return { chatPath: paths.chatPath, raw, paths }
+  }
+  loadMemory(opts = {}) {
+    // Merges root + local memory unless memory.override is truthy.
+    const paths = this.resolvePaths(opts)
+    const fm = opts.frontMatter || null
+    const over = this._truthy(fm && fm['memory.override'])
+    const root = this.readText(paths.rootMemoryPath)
+    const local = this.readText(paths.localMemoryPath)
+    let raw = ''
+    if (over)
+      raw = local
+    else
+      raw = this._joinNonEmpty(root, local)
+    return { raw, paths, over }
+  }
+  buildMessages(parsed, memoryRaw, opts = {}) {
+    // Prepends memory as a system message if present.
+    const msgs = (parsed && parsed.messages) || []
+    const mem = String(memoryRaw || '').trim()
+    if (!mem)
+      return msgs
+    const role = opts.memoryRole || 'system'
+    return [{ role, content: mem }, ...msgs]
+  }
+  _pickPath(name, roots, opts = {}) {
+    const s = String(name || '').trim()
+    if (!s)
+      return ''
+    if (path.isAbsolute(s))
+      return s
+    for (const root of roots || []) {
+      const p = path.join(root, s)
+      if (fs.existsSync(p))
+        return p
+    }
+    if (opts.allowMissing)
+      return path.join(roots && roots[0] ? roots[0] : '', s)
+    return path.join(roots && roots[0] ? roots[0] : '', s)
+  }
+  _truthy(v) {
+    const s = String(v || '').trim().toLowerCase()
+    return s === '1' || s === 'true' || s === 'yes' || s === 'y'
+  }
+  _joinNonEmpty(a, b) {
+    const x = String(a || '').trim()
+    const y = String(b || '').trim()
+    if (x && y)
+      return x + '\n\n' + y
+    return x || y || ''
+  }
+}
+
+module.exports = {
+  ContextResolver,
+}

package/lib/runner.js

@@ -0,0 +1,51 @@
+const fs = require('fs')
+
+class Runner {
+  constructor(opts = {}) {
+    this.parser = opts.parser
+    this.resolver = opts.resolver
+    this.provider = opts.provider
+    if (!this.parser) throw new Error('Runner requires parser')
+    if (!this.resolver) throw new Error('Runner requires resolver')
+    if (!this.provider) throw new Error('Runner requires provider')
+  }
+  async runOnce(opts = {}) {
+    // opts.cwd: string
+    // opts.chat: string
+    // opts.memory: string
+    // opts.model: string
+    try {
+      const chat = this.resolver.loadChat(opts)
+      const parsed = this.parser.parse(chat.raw, opts)
+      if (!this.shouldRun(parsed, opts))
+        return { ok: true, didRun: false, chatPath: chat.chatPath }
+      const mem = this.resolver.loadMemory({
+        ...opts,
+        cwd: chat.paths.cwd,
+        frontMatter: parsed.frontMatter,
+      })
+      const messages = this.resolver.buildMessages(parsed, mem.raw, opts)
+      const model = opts.model || (parsed.frontMatter && parsed.frontMatter.model)
+      const assistantText = await this.provider.complete(messages, { model })
+      const rawNext = this.buildAppend(chat.raw, assistantText, opts)
+      this.writeAll(chat.chatPath, rawNext, opts)
+      return { ok: true, didRun: true, chatPath: chat.chatPath }
+    } catch (err) {
+      return { ok: false, didRun: false, error: err }
+    }
+  }
+  shouldRun(parsed, opts = {}) {
+    return this.parser.isRunnable(parsed, opts)
+  }
+  buildAppend(raw, assistantText, opts = {}) {
+    const base = String(raw || '').replace(/\s+$/, '')
+    const a = this.parser.formatAppendAssistant(assistantText, opts)
+    const u = this.parser.formatAppendUser(opts)
+    return base + a + u
+  }
+  writeAll(filePath, rawNext, opts = {}) {
+    fs.writeFileSync(filePath, String(rawNext || ''), 'utf8')
+  }
+}
+
+module.exports = { Runner }

package/lib/watcher.js

@@ -0,0 +1,157 @@
+const chokidar = require('chokidar')
+
+class Watcher {
+  constructor(opts = {}) {
+    this.runner = opts.runner
+    this.watcher = null
+    this.busy = false
+    this.pending = false
+    this.timer = null
+    this.debounceMs = opts.debounceMs || 200
+    this.onEvent = typeof opts.onEvent === 'function' ? opts.onEvent : null
+    this.quiet = opts.quiet ?? false
+    if (!this.runner)
+      throw new Error('Watcher requires runner')
+  }
+  start(opts = {}) {
+    this.debounceMs = opts.debounceMs || this.debounceMs
+    if (typeof opts.onEvent === 'function')
+      this.onEvent = opts.onEvent
+    if (this.watcher)
+      return { ok: true, watching: true }
+
+    const chatPath = this._chatPath(opts)
+
+
+    this.watcher = chokidar.watch(chatPath, {
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 150,
+        pollInterval: 25
+      }
+    })
+
+    this.watcher.on('all', (evt, p) => {
+      if (evt === 'add' || evt === 'change')
+        this.onChange(p, opts)
+    })
+    // this.watcher.on('change', p => this.onChange(p, opts))
+    this._emit('watch_start', { chatPath }, opts)
+
+    return { ok: true, watching: true, chatPath }
+  }
+  async stop(opts = {}) {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+    if (this.watcher) {
+      const w = this.watcher
+      this.watcher = null
+      try { await w.close() } catch {}
+    }
+    this.busy = false
+    this.pending = false
+    this._emit('watch_stop', {}, opts)
+    return { ok: true, watching: false }
+  }
+  _chatPath(opts = {}) {
+    if (opts.chatPath)
+      return String(opts.chatPath)
+    if (opts.chat)
+      return String(opts.chat)
+
+    const r = this.runner.resolver
+    if (!r || typeof r.resolvePaths !== 'function')
+      throw new Error('Watcher requires chatPath/chat or runner.resolver.resolvePaths()')
+
+    const out = r.resolvePaths(opts) || {}
+    const chatPath = out.chatPath || null
+    if (!chatPath)
+      throw new Error('Missing chat path')
+
+    return chatPath
+  }
+  _emit(type, payload = {}, opts = {}) {
+    const fn = (opts && typeof opts.onEvent === 'function')
+      ? opts.onEvent
+      : this.onEvent
+
+    if (typeof fn === 'function') {
+      try {
+        fn({ type, ...payload })
+      } catch (e) {
+        const message = e && e.message ? e.message : String(e)
+        process.stderr.write('watch onEvent error: ' + message + '\n')
+      }
+      return
+    }
+
+    if (this.quiet)
+      return
+
+    if (type === 'watch_start')
+      return process.stdout.write('watching: ' + (payload.chatPath || '') + '\n')
+
+    if (type === 'signal')
+      return process.stdout.write('change detected\n')
+
+    if (type === 'pending')
+      return process.stdout.write('queued\n')
+
+    if (type === 'run_start')
+      return process.stdout.write('running...\n')
+
+    if (type === 'run_end') {
+      if (payload && payload.ok)
+        return process.stdout.write('done\n')
+      const msg = payload && payload.error ? String(payload.error) : 'error'
+      return process.stdout.write('error: ' + msg + '\n')
+    }
+
+    if (type === 'watch_stop')
+      return process.stdout.write('stopped\n')
+  }
+  onChange(filePath, opts = {}) {
+    const first = !this.timer
+    if (this.timer)
+      clearTimeout(this.timer)
+    this.timer = setTimeout(() => {
+      this.timer = null
+      this._kick(opts)
+    }, this.debounceMs)
+    if (first)
+      this._emit('signal', { filePath }, opts)
+  }
+  async _kick(opts = {}) {
+    if (this.busy) {
+      this.pending = true
+      this._emit('pending', {}, opts)
+      return
+    }
+
+    this.busy = true
+    const start = Date.now()
+    this._emit('run_start', {}, opts)
+
+    let ok = true
+    let errMsg = null
+
+    try {
+      await this.runner.runOnce(opts)
+    } catch (err) {
+      ok = false
+      errMsg = err && err.message ? err.message : String(err)
+    }
+
+    this._emit('run_end', { ok, ms: Date.now() - start, error: errMsg }, opts)
+    this.busy = false
+
+    if (this.pending) {
+      this.pending = false
+      await this._kick(opts)
+    }
+  }
+}
+
+module.exports = { Watcher }

package/package.json

@@ -1,12 +1,52 @@
 {
   "name": "chudbot",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.0.1",
+  "description": "Chudbot is a stupid-simple “chat in a file” bot.",
+  "main": "lib/chudbot.js",
+  "bin": {
+    "chudbot": "bin/chudbot-cli.js"
   },
-  "keywords": [],
-  "author": "",
-  "license": "MIT"
+  "types": "types.d.ts",
+  "files": [
+    "bin/",
+    "lib/",
+    "types.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "lib": "lib"
+  },
+  "scripts": {},
+  "dependencies": {
+    "axios": "^1.13.6",
+    "chokidar": "^3.6.0",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1"
+  },
+  "author": "Basedwon",
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "llm",
+    "chatgpt",
+    "gpt",
+    "claude",
+    "openrouter",
+    "prompt",
+    "prompting",
+    "chatbot",
+    "markdown",
+    "markdown-chat",
+    "chat-in-a-file",
+    "file-based",
+    "local-first",
+    "cli",
+    "command-line",
+    "terminal",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
 }

package/types.d.ts

@@ -0,0 +1,241 @@
+declare module 'chudbot' {
+  export type Role = 'system' | 'user' | 'assistant' | string
+
+  export interface ChatBlock {
+    role: Role
+    content: string
+  }
+
+  export interface ChatMessage {
+    role: Role
+    content: string
+  }
+
+  export interface ChatParsed {
+    frontMatter?: Record<string, string>
+    blocks: ChatBlock[]
+    messages: ChatMessage[]
+  }
+
+  export interface ChatParserOptions {
+    eol?: string
+    headerRe?: RegExp
+    allowedRoles?: Record<string, boolean>
+  }
+
+  export class ChatParser {
+    constructor(opts?: ChatParserOptions)
+    parse(raw: string, opts?: { allowUnknown?: boolean }): ChatParsed
+    parseFile(filePath: string, opts?: { allowUnknown?: boolean }): ChatParsed
+    isRunnable(parsed: ChatParsed, opts?: { minLen?: number }): boolean
+    getLastBlock(parsed: ChatParsed): ChatBlock | null
+    formatAppendAssistant(text: string, opts?: { trim?: boolean }): string
+    formatAppendUser(opts?: {}): string
+  }
+
+  export interface ResolvePathsResult {
+    cwd: string
+    userRoot: string
+    chudRoot: string
+    envPath: string
+    chatPath: string
+    rootMemoryPath: string
+    localMemoryPath: string
+  }
+
+  export interface ContextResolverOptions {
+    userRoot?: string
+    chudRoot?: string
+    envPath?: string
+    defaultChatName?: string
+    defaultMemoryName?: string
+  }
+
+  export class ContextResolver {
+    constructor(opts?: ContextResolverOptions)
+    resolvePaths(opts?: {
+      cwd?: string
+      chat?: string
+      memory?: string
+      frontMatter?: Record<string, string>
+    }): ResolvePathsResult
+    readText(filePath: string, opts?: { required?: boolean }): string
+    loadChat(opts?: { cwd?: string; chat?: string }): {
+      chatPath: string
+      raw: string
+      paths: ResolvePathsResult
+    }
+    loadMemory(opts?: {
+      cwd?: string
+      memory?: string
+      frontMatter?: Record<string, string>
+    }): {
+      raw: string
+      paths: ResolvePathsResult
+      over: boolean
+    }
+    buildMessages(
+      parsed: ChatParsed,
+      memoryRaw: string,
+      opts?: { memoryRole?: Role }
+    ): ChatMessage[]
+  }
+
+  export interface EnvLoaderOptions {
+    userRoot?: string
+    chudRoot?: string
+    envPath?: string
+  }
+
+  export class EnvLoader {
+    constructor(opts?: EnvLoaderOptions)
+    load(opts?: {
+      envPath?: string
+      override?: boolean
+      required?: boolean
+    }): { ok: boolean; envPath: string; loaded: boolean }
+  }
+
+  export interface InitializerOptions {
+    userRoot?: string
+    chudRoot?: string
+    envPath?: string
+    defaultChatName?: string
+  }
+
+  export class Initializer {
+    constructor(opts?: InitializerOptions)
+    initRoot(opts?: { makeEnv?: boolean }): {
+      ok: boolean
+      chudRoot: string
+      envPath: string
+      didWriteEnv: boolean
+    }
+    initChat(opts?: {
+      cwd?: string
+      chat?: string
+      force?: boolean
+      system?: string
+    }): { ok: boolean; chatPath: string; didWriteChat: boolean }
+    init(opts?: {
+      cwd?: string
+      chat?: string
+      force?: boolean
+      system?: string
+      makeEnv?: boolean
+    }): {
+      ok: boolean
+      chudRoot: string
+      envPath: string
+      chatPath: string
+      didWriteEnv: boolean
+      didWriteChat: boolean
+    }
+    defaultChat(opts?: { system?: string }): string
+    defaultEnv(opts?: {}): string
+    writeIfMissing(
+      filePath: string,
+      content: string,
+      opts?: { force?: boolean }
+    ): { didWrite: boolean }
+  }
+
+  export interface OpenRouterProviderOptions {
+    baseUrl?: string
+    apiKey?: string
+    model?: string
+    timeoutMs?: number
+    headers?: Record<string, string>
+  }
+
+  export class OpenRouterProvider {
+    constructor(opts?: OpenRouterProviderOptions)
+    send(
+      messages: ChatMessage[],
+      opts?: {
+        model?: string
+        temperature?: number
+        maxTokens?: number
+        headers?: Record<string, string>
+      }
+    ): Promise<any>
+    complete(
+      messages: ChatMessage[],
+      opts?: {
+        model?: string
+        temperature?: number
+        maxTokens?: number
+        headers?: Record<string, string>
+      }
+    ): Promise<string>
+    extractContent(json: any): string
+  }
+
+  export interface RunnerOptions {
+    parser: ChatParser
+    resolver: ContextResolver
+    provider: OpenRouterProvider
+  }
+
+  export class Runner {
+    constructor(opts: RunnerOptions)
+    runOnce(opts?: {
+      cwd?: string
+      chat?: string
+      memory?: string
+      model?: string
+    }): Promise<{ ok: boolean; didRun: boolean; chatPath?: string; error?: any }>
+    shouldRun(parsed: ChatParsed, opts?: { minLen?: number }): boolean
+    buildAppend(raw: string, assistantText: string, opts?: {}): string
+    writeAll(filePath: string, rawNext: string, opts?: {}): void
+  }
+
+  export interface WatcherOptions {
+    runner: Runner
+    debounceMs?: number
+  }
+
+  export class Watcher {
+    constructor(opts: WatcherOptions)
+    start(opts?: {
+      cwd?: string
+      chat?: string
+      memory?: string
+      model?: string
+      debounceMs?: number
+    }): { ok: boolean; watching: boolean; chatPath?: string }
+    stop(): Promise<{ ok: boolean; watching: boolean }>
+    onChange(filePath: string, opts?: any): void
+  }
+
+  export interface ChudbotOptions {
+    userRoot?: string
+    chudRoot?: string
+    envPath?: string
+    debounceMs?: number
+  }
+
+  export class Chudbot {
+    constructor(opts?: ChudbotOptions)
+    init(opts?: {
+      cwd?: string
+      chat?: string
+      force?: boolean
+      system?: string
+    }): { ok: boolean; chatPath: string; didWriteChat: boolean }
+    run(opts?: {
+      cwd?: string
+      chat?: string
+      memory?: string
+      model?: string
+    }): Promise<{ ok: boolean; didRun: boolean; chatPath?: string; error?: any }>
+    watch(opts?: {
+      cwd?: string
+      chat?: string
+      memory?: string
+      model?: string
+      debounceMs?: number
+    }): { ok: boolean; watching: boolean; chatPath?: string }
+    stop(): Promise<{ ok: boolean; watching: boolean }>
+  }
+}