chudbot 0.0.0 → 0.0.2

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 }