@routstr/cocod 0.0.16

package/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  checks:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+      - name: Typecheck
+        run: bun run lint
+      - name: Tests
+        run: bun test

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

@@ -0,0 +1,78 @@
+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
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
+        with:
+          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: bun pm version patch --no-git-tag-version
+      - name: Sync SKILL version pins
+        run: |
+          VERSION=$(bun -e 'const pkg = JSON.parse(await Bun.file("package.json").text()); console.log(pkg.version)')
+          VERSION="$VERSION" bun -e '
+            const version = process.env.VERSION;
+            if (!version) {
+              throw new Error("Missing VERSION env var");
+            }
+
+            const skillPath = "SKILL.md";
+            const skill = await Bun.file(skillPath).text();
+
+            if (!/^metadata:\s*$/m.test(skill)) {
+              throw new Error("SKILL.md is missing metadata field");
+            }
+
+            if (!/^\s{2}skill_version:\s*.+$/m.test(skill)) {
+              throw new Error("SKILL.md is missing metadata.skill_version field");
+            }
+
+            if (!/^\s{2}requires_cocod_version:\s*.+$/m.test(skill)) {
+              throw new Error("SKILL.md is missing metadata.requires_cocod_version field");
+            }
+
+            const next = skill
+              .replace(/^\s{2}skill_version:\s*.+$/m, `  skill_version: ${version}`)
+              .replace(/^\s{2}requires_cocod_version:\s*.+$/m, `  requires_cocod_version: ${version}`);
+
+            await Bun.write(skillPath, next);
+          '
+      - name: Pack tarball
+        run: bun pm pack
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public *.tgz
+      - name: Commit version bump
+        run: |
+          VERSION=$(bun -e 'console.log(require("./package.json").version)')
+          git add package.json bun.lock SKILL.md
+          git commit -m "chore(release): v$VERSION [skip ci]"
+          git push
+      - name: Publish to skill registry
+        env:
+          TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
+        run: |
+          VERSION=$(bun -e 'console.log(require("./package.json").version)')
+          SLUG=$(bun -e 'console.log(require("./package.json").name)')
+          curl -X POST "https://www.clawhub.ai/api/v1/skills" \
+            -H "Authorization: Bearer $TOKEN" \
+            -H "Accept: application/json" \
+            -F "payload={\"slug\":\"$SLUG\",\"displayName\":\"Cocod\",\"version\":\"$VERSION\",\"changelog\":\"Release v$VERSION\",\"tags\":[\"latest\"]}" \
+            -F "files=@SKILL.md;filename=SKILL.md"

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,244 @@
+# 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 `~/.cocod/cocod.sock`).
+- PID file: `COCOD_PID` (default `~/.cocod/cocod.pid`).
+- Wallet 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
+
+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 a formatter config at `.prettierrc`. 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/update the route handler in `src/routes.ts` (and ensure it returns the `{ output | error }` shape)
+  - keep the CLI/daemon contract explicit (method, path, request/response types).
+  - update `docs/daemon-api.json` to keep the route contract in sync.
+
+## Agent Playbook
+
+Use these repeatable recipes to keep changes predictable.
+
+### Add or update a CLI command
+
+1. Update command wiring in `src/cli.ts`.
+2. Add/update daemon route in `src/routes.ts`.
+3. Keep route responses to `{ output: ... }` on success and `{ error: string }` on failure.
+4. Return explicit status codes:
+   - 400 invalid input
+   - 401 auth/passphrase failure
+   - 403 locked wallet for unlocked-only endpoints
+   - 404 unknown endpoint
+   - 409 state conflict
+   - 500 unexpected runtime failure
+5. Update docs:
+   - `README.md` command tables/examples
+   - `docs/daemon-api.json` endpoint contract
+6. Add/adjust tests and run checks (`bun run lint`, `bun test`).
+
+### Validate request bodies
+
+- Treat request bodies as untrusted.
+- Validate required fields before calling wallet methods.
+- Return 400 with actionable messages for malformed JSON, missing fields, wrong types, or invalid ranges.
+
+### Keep docs and runtime aligned
+
+- If you change command names, env var behavior, or defaults, update docs in the same patch.
+- Prefer one source of truth for path constants (`src/utils/config.ts`).
+- Do not leave placeholders in user-facing docs.
+
+## Quick Debugging Checklist
+
+- CLI can't connect: verify `COCOD_SOCKET` matches daemon and the socket exists.
+- Daemon won't start: check for stale `~/.cocod/cocod.sock` and `~/.cocod/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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egge
+
+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,139 @@
+# cocod
+
+`cocod` is a Cashu wallet CLI with a local daemon.
+
+If you like simple tools: run commands in your terminal, and let the daemon handle wallet state in the background.
+
+## What it does
+
+- Initialize and secure a Cashu wallet
+- Check balances and transaction history
+- Send and receive Cashu tokens
+- Send and receive Lightning payments (BOLT11)
+- Handle HTTP 402 payments with `X-Cashu`
+- Manage trusted mints
+
+## Install
+
+```bash
+bun install --global cocod
+```
+
+Or from source:
+
+```bash
+git clone <repository-url>
+cd cocod
+bun install
+```
+
+## Quick start
+
+```bash
+# Check daemon status
+cocod status
+
+# Create a wallet (auto-generates mnemonic)
+cocod init
+
+# If encrypted during init, unlock it
+cocod unlock "your-passphrase"
+
+# Check balance
+cocod balance
+```
+
+## Most common commands
+
+```bash
+# Receive
+cocod receive cashu "cashuA..."
+cocod receive bolt11 1000
+
+# Send
+cocod send cashu 500
+cocod send bolt11 "lnbc..."
+
+# Mints
+cocod mints add https://mint.example.com/Bitcoin
+cocod mints list
+
+# History
+cocod history --limit 10
+cocod history --watch
+
+# Logs
+cocod logs
+cocod logs --follow
+cocod logs --path
+```
+
+## NPC (Lightning Address)
+
+```bash
+# Your NPC address
+cocod npc address
+
+# Check username price, then confirm purchase
+cocod npc username myname
+cocod npc username myname --confirm
+```
+
+## HTTP 402 / X-Cashu
+
+```bash
+# Inspect request from a 402 response
+cocod x-cashu parse "<encoded-x-cashu-request>"
+
+# Settle and get header value for retry
+cocod x-cashu handle "<encoded-x-cashu-request>"
+```
+
+## How it works
+
+- CLI: `src/cli.ts`
+- Daemon: `src/daemon.ts`
+- Routes: `src/routes.ts`
+- IPC transport: HTTP over UNIX socket
+
+Defaults:
+
+- Socket: `~/.cocod/cocod.sock` (or `COCOD_SOCKET`)
+- PID file: `~/.cocod/cocod.pid` (or `COCOD_PID`)
+- Daemon log: `~/.cocod/daemon.log` (or `COCOD_LOG_FILE`)
+- Config: `~/.cocod/config.json`
+- Database: `~/.cocod/coco.db`
+
+Logging defaults:
+
+- Structured JSON logs are written to `~/.cocod/daemon.log`
+- Rotation keeps 5 files at 5 MiB each by default
+- Override with `COCOD_LOG_LEVEL`, `COCOD_LOG_MAX_BYTES`, and `COCOD_LOG_MAX_FILES`
+
+## Development
+
+```bash
+# Run CLI from source
+bun src/index.ts --help
+
+# Run daemon directly
+bun run daemon
+
+# Typecheck
+bun run lint
+
+# Tests
+bun test
+
+# Isolated daemon smoke test
+bun run smoke:daemon
+```
+
+## Docs
+
+- [API and command reference](docs/API.md)
+- [Machine-readable daemon contract](docs/daemon-api.json)
+
+## License
+
+MIT