cocod 0.0.1

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,37 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  publish:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+      - name: Configure git user
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Bump version
+        run: npm version patch --no-git-tag-version
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public
+      - name: Commit version bump
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          git add package.json
+          git commit -m "chore(release): v$VERSION [skip ci]"
+          git push

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always"
+}

package/AGENTS.md

@@ -0,0 +1,210 @@
+# AGENTS.md
+
+This repository is a small Bun + TypeScript CLI/daemon.
+Agents should optimize for: minimal diffs, strict types, Bun-native APIs, and predictable CLI UX.
+
+## Ground Rules (Repo Policy)
+
+- Runtime: Bun (not Node). Prefer Bun APIs over Node/polyfills.
+- Module system: ESM (`"type": "module"` in `package.json`).
+- TypeScript is the linter: `tsc --noEmit` is the primary check.
+- No Cursor/Copilot rule files were found (`.cursor/rules/**`, `.cursorrules`, `.github/copilot-instructions.md`).
+- Also follow `CLAUDE.md` (Bun defaults, preferred APIs, testing conventions).
+
+## Project Shape
+
+- `src/index.ts`: entrypoint for the `cocod` binary (shebang: `#!/usr/bin/env bun`).
+- `src/cli.ts` + `src/cli-shared.ts`: Commander-based CLI.
+- `src/daemon.ts`: background daemon implemented with `Bun.serve()` on a UNIX socket.
+- `src/routes.ts`: HTTP route handlers for the daemon (endpoints like /balance, /receive, /init, etc.).
+- `src/utils/`:
+  - `state.ts`: DaemonStateManager and wallet state logic
+  - `wallet.ts`: Wallet initialization helpers
+  - `crypto.ts`: Mnemonic encryption/decryption
+  - `config.ts`: Configuration paths, env vars, and types
+- IPC: CLI talks to daemon via `fetch()` with Bun's `RequestInit.unix` option.
+
+Key paths/env:
+
+- Socket: `COCOD_SOCKET` (default `/tmp/cocod.sock`).
+- PID file: `COCOD_PID` (default `/tmp/cocod.pid`).
+- Wallet config: `~/.config/cocod/config.json` (generated; do not commit).
+
+## Commands
+
+All commands run from repo root (`/home/egge/projects/cocod`).
+
+### Install
+
+```sh
+bun install
+```
+
+### Run the CLI (foreground)
+
+- Entrypoint:
+
+```sh
+bun src/index.ts --help
+```
+
+- Via npm-style script (use `--` to pass args):
+
+```sh
+bun run start -- --help
+```
+
+- Common commands:
+
+```sh
+bun src/index.ts balance
+bun src/index.ts ping
+bun src/index.ts mint list
+```
+
+### Start the daemon
+
+The daemon can be started explicitly, but the CLI also auto-starts it when needed.
+
+```sh
+bun run daemon
+```
+
+### Build / bundle
+
+There is no required build step (the CLI runs directly via Bun + TypeScript).
+
+- Optional: produce a bundled artifact:
+
+```sh
+bun build src/index.ts --outdir dist --target bun
+```
+
+### Lint / typecheck
+
+This repo currently uses TypeScript as the main lint gate.
+
+```sh
+bun run lint
+```
+
+If you need to run tsc directly:
+
+```sh
+bunx tsc --noEmit
+```
+
+### Tests
+
+There are currently no committed test files, but Bun's test runner is the expected choice.
+
+- Run all tests:
+
+```sh
+bun test
+```
+
+- Run a single test file:
+
+```sh
+bun test path/to/file.test.ts
+```
+
+- Run a single test by name (recommended when adding tests):
+
+```sh
+bun test -t "ping returns pong"
+```
+
+Notes:
+
+- Prefer test files named `*.test.ts` and colocated near the code they test.
+- Use `import { test, expect } from "bun:test";`.
+
+## Code Style
+
+There is no formatter config in this repo. Match existing style and avoid drive-by reformatting.
+
+### Formatting
+
+- Indentation: 2 spaces.
+- Quotes: double quotes for strings.
+- Semicolons: use them consistently (match surrounding file).
+- Line length: keep lines reasonably short; wrap long function signatures.
+
+### Imports
+
+- Order:
+  1. external packages
+  2. blank line
+  3. local relative imports
+- Prefer `import type { ... }` for type-only imports.
+- Prefer named imports; avoid default imports unless the package is default-first.
+- Keep relative imports extensionless (match current code). Only include `.js` when required by ESM packages.
+
+### Types and strictness
+
+`tsconfig.json` enables strict TypeScript plus `noUncheckedIndexedAccess`.
+
+- Avoid `any`. Use `unknown` at boundaries and narrow.
+- Validate untrusted inputs (CLI args, request bodies, env vars).
+- When indexing objects, handle `undefined` explicitly (e.g., `balance[mintUrl] || 0`).
+- Prefer explicit return types on exported functions and non-trivial helpers.
+- Use discriminated unions / literal types for protocol-like payloads.
+
+### Naming
+
+- Files: kebab-case for multiword modules (e.g., `cli-shared.ts`).
+- Types/interfaces: `PascalCase`.
+- Functions/variables: `camelCase`.
+- Constants: `UPPER_SNAKE_CASE` for configuration-like values.
+- CLI commands: lowercase; nouns/verbs consistent with existing Commander usage.
+
+### Error handling
+
+General:
+
+- Only `process.exit()` from true CLI entrypoints.
+- Prefer throwing `Error` (or subclasses) from library-ish functions.
+- In `catch`, treat the error as `unknown`; derive a safe message:
+  - `error instanceof Error ? error.message : String(error)`.
+
+Daemon (`src/daemon.ts`):
+
+- Return JSON with either `{ output: string }` or `{ error: string }`.
+- Use proper HTTP status codes for failures (e.g., 400 for bad input, 404 unknown endpoint, 500 unexpected).
+- Do not swallow errors silently; if you intentionally suppress errors (e.g., delete stale files), add a short comment.
+
+CLI (`src/cli-shared.ts`):
+
+- Print user-facing errors to stderr (`console.error`).
+- Exit with code 1 for expected failures.
+- For daemon connectivity issues, prefer actionable messages (socket path, how to start daemon).
+
+### Bun-specific guidance (from `CLAUDE.md`)
+
+- Use `bun <file>` / `bun run <script>` (not `node`, `ts-node`, `npm`).
+- Use `bun test` (not jest/vitest).
+- Use `Bun.serve()` routes/websocket support (not express).
+- Prefer `Bun.file` for file IO; Bun loads `.env` automatically (avoid `dotenv`).
+- Prefer Bun-native DB/network libs where applicable:
+  - `bun:sqlite` for SQLite (avoid `better-sqlite3`)
+  - `Bun.sql` for Postgres (avoid `pg`)
+  - `Bun.redis` for Redis (avoid `ioredis`)
+  - built-in `WebSocket` (avoid `ws`)
+
+## Editing Expectations for Agents
+
+- Keep diffs surgical; do not reformat unrelated code.
+- Preserve CLI UX and backward compatibility of command names/flags unless explicitly requested.
+- Avoid committing/generated artifacts (e.g., `coco.db`, sockets, pid files, `.env`).
+- When adding new commands/routes:
+  - update Commander wiring in `src/cli.ts`
+  - add a daemon handler in `src/daemon.ts` (and ensure it returns the `{ output | error }` shape)
+  - keep the CLI/daemon contract explicit (method, path, request/response types).
+
+## Quick Debugging Checklist
+
+- CLI can't connect: verify `COCOD_SOCKET` matches daemon and the socket exists.
+- Daemon won't start: check for stale `/tmp/cocod.sock` and `/tmp/cocod.pid`.
+- Type errors: run `bun run lint` and fix strictness issues (especially `undefined` from indexing).

package/CLAUDE.md

@@ -0,0 +1,105 @@
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+// import .css files directly and it works
+import './index.css';
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.

package/README.md

@@ -0,0 +1,179 @@
+# cocod
+
+A Cashu wallet CLI and daemon built with Bun and TypeScript.
+
+## Overview
+
+`cocod` is a [Cashu](https://cashu.space/) e-cash wallet with a client-daemon architecture. It provides a command-line interface for managing Cashu tokens while a background daemon handles all wallet operations, state management, and mint communication.
+
+### Features
+
+- **Wallet Management**: Initialize with BIP39 mnemonics, optional passphrase encryption
+- **Token Operations**: Receive Cashu tokens, check balances across mints
+- **Lightning Integration**: Create BOLT11 invoices to mint new tokens
+- **Nostr Payment Codes**: NPC addresses for receiving payments
+- **Transaction History**: View and paginate wallet history
+- **Real-time Updates**: SSE endpoint for live event streaming
+- **Multi-mint Support**: Add and manage multiple Cashu mints
+
+## Installation
+
+```bash
+bun install
+```
+
+## Usage
+
+### Quick Start
+
+```bash
+# Check daemon status
+bun src/index.ts status
+
+# Initialize wallet (generates mnemonic automatically)
+bun src/index.ts init
+
+# Or initialize with your own mnemonic
+bun src/index.ts init "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+
+# Unlock encrypted wallet (if passphrase was set)
+bun src/index.ts unlock "your-passphrase"
+
+# Check balance
+bun src/index.ts balance
+```
+
+### Available Commands
+
+#### Wallet Operations
+
+| Command               | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `status`              | Check daemon and wallet status                                  |
+| `init [mnemonic]`     | Initialize wallet (generates mnemonic if not provided)          |
+| `unlock <passphrase>` | Unlock encrypted wallet                                         |
+| `balance`             | Get wallet balance across all mints                             |
+| `receive <token>`     | Receive a Cashu token                                           |
+| `history`             | View wallet history (supports `--offset`, `--limit`, `--watch`) |
+
+#### Mint Management
+
+| Command                | Description                             |
+| ---------------------- | --------------------------------------- |
+| `mint add <url>`       | Add a new mint URL                      |
+| `mint list`            | List configured mints                   |
+| `mint bolt11 <amount>` | Create Lightning invoice to mint tokens |
+
+#### NPC (npub.cash)
+
+| Command       | Description                            |
+| ------------- | -------------------------------------- |
+| `npc address` | Get NPC address for receiving payments |
+
+#### Daemon Control
+
+| Command  | Description                            |
+| -------- | -------------------------------------- |
+| `ping`   | Test daemon connectivity               |
+| `stop`   | Stop the background daemon             |
+| `daemon` | Start the background daemon explicitly |
+
+### Examples
+
+```bash
+# Add a mint
+bun src/index.ts mint add https://mint.example.com
+
+# Create a Lightning invoice for 1000 sats
+bun src/index.ts mint bolt11 1000
+
+# Receive a Cashu token
+bun src/index.ts receive "cashuAeyJ0b2tlbiI6W3sicHJvb2ZzIjpbeyJ..."
+
+# View last 10 history entries
+bun src/index.ts history --limit 10
+
+# Watch history in real-time
+bun src/index.ts history --watch
+```
+
+## Architecture
+
+### Client-Daemon Model
+
+- **CLI** (`src/cli.ts`): Thin client that sends HTTP requests to the daemon via Unix socket
+- **Daemon** (`src/daemon.ts`): Background service using `Bun.serve()` that handles all wallet operations
+
+The CLI automatically starts the daemon if it's not already running.
+
+### IPC Communication
+
+Communication happens over a Unix domain socket:
+
+- Default: `~/.cocod/cocod.sock`
+- Configurable via `COCOD_SOCKET` environment variable
+
+## Configuration
+
+### Environment Variables
+
+| Variable       | Default               | Description      |
+| -------------- | --------------------- | ---------------- |
+| `COCOD_SOCKET` | `~/.cocod/cocod.sock` | Unix socket path |
+| `COCOD_PID`    | `~/.cocod/cocod.pid`  | PID file path    |
+
+### Files
+
+- **Config**: `~/.cocod/config.json`
+- **Database**: `./coco.db` (SQLite, auto-generated)
+- **PID file**: Tracks running daemon process
+
+## Development
+
+### Commands
+
+```bash
+# Run CLI
+bun src/index.ts --help
+
+# Run with npm-style script
+bun run start -- --help
+
+# Start daemon explicitly
+bun run daemon
+
+# Type check
+bun run lint
+# or
+bunx tsc --noEmit
+
+# Build bundle
+bun build src/index.ts --outdir dist --target bun
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts          # CLI entrypoint (shebang: #!/usr/bin/env bun)
+├── cli.ts            # Commander-based CLI commands
+├── cli-shared.ts     # IPC utilities
+├── daemon.ts         # Bun.serve() daemon setup
+├── routes.ts         # HTTP route handlers
+└── utils/
+    ├── config.ts     # Config management
+    ├── state.ts      # Daemon state machine
+    ├── wallet.ts     # Wallet initialization
+    └── crypto.ts     # Mnemonic encryption
+```
+
+## Dependencies
+
+- **Bun**: Runtime and built-in APIs (`Bun.serve()`, `fetch()`, `bun:sqlite`)
+- **Cashu**: `coco-cashu-core`, `coco-cashu-sqlite3`, `coco-cashu-plugin-npc`
+- **CLI**: `commander` for argument parsing
+- **Crypto**: `@scure/bip39` for mnemonics, `nostr-tools` for NPC
+
+## License
+
+[Add your license here]

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "cocod",
+  "version": "0.0.1",
+  "module": "src/index.ts",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "cocod": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "bun src/index.ts",
+    "daemon": "bun src/index.ts daemon",
+    "lint": "tsc --noEmit",
+    "format": "prettier --write ."
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prettier": "^3.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@scure/bip39": "^2.0.1",
+    "coco-cashu-core": "^1.1.2-rc.43",
+    "coco-cashu-plugin-npc": "^2.2.4",
+    "coco-cashu-sqlite3": "^1.1.2-rc.43",
+    "commander": "^14.0.2",
+    "nostr-tools": "^2.22.1",
+    "sqlite3": "^5.1.7"
+  }
+}