ework-daemon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dog and contributors
+
+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,262 @@
+# ework-daemon
+
+Issue-Driven AI Development Bridge. Connects an issue tracker (the [ework-web](../ework) SQLite shim, or real Gitea) to [OpenCode](https://github.com/sst/opencode) AI agents.
+
+> Issue-driven AI development daemon. Listens on `:3101` by default; SQLite at `~/.local/share/ework-daemon/ework-daemon.db`; systemd unit `ework-daemon.service`.
+
+## What it does
+
+You file an issue → the daemon spawns an OpenCode subprocess to handle it → the AI autonomously reads, replies, and closes via the `opencode-ework` plugin's tools (`issue`, `comments`, `floor`, `reply`, `search`). New user comments are forwarded to the running session. Stuck sessions (30 min no output) get a nudge.
+
+**The daemon only does 4 things:**
+
+1. **New issue** → auto-spawn OpenCode.
+2. **`@<bot>` mention** on existing issue → trigger a new or existing session.
+3. **Existing session + new user comment** → forward to OpenCode (wrapped as a system message).
+4. **Stuck detection** → 30 min no stdout → stuck alert.
+
+It does **not** post AI replies, auto-commit, or auto-merge. The AI does all issue interaction itself via the plugin.
+
+## Architecture
+
+```
+ework-web (:3002)             ework-daemon (:3101)              OpenCode (subprocess)
+   │                                │                               │
+   │ ── issue webhook ────────────▸ │                               │
+   │                                │ ── Bun.spawn ──────────────▸ │
+   │                                │                               │
+   │ ◂── plugin GET /issues/n ──────┼───────────────────────────────┤
+   │ ◂── plugin POST /comments ─────┼───────────────────────────────┤
+   │                                │ ◂── stdout streaming ─────────┤
+   │ ── new-comment webhook ─────▸ │                               │
+   │                                │ ── stdin (wrapped) ────────▸ │
+   │                                │ ◂── completion signal ───────┤
+   │ ◂── plugin POST /close ────────┼───────────────────────────────┤
+```
+
+The OpenCode subprocess loads the [`opencode-ework`](../opencode-ework) plugin, which speaks Gitea REST. The daemon injects `GITEA_URL`, `GITEA_TOKEN`, `BOT_TOKEN`, `BOT_USERNAME` env vars at spawn, so the plugin picks them up automatically. The plugin is backend-agnostic — same plugin works against real Gitea or any Gitea-compatible shim.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) runtime (uses `Bun.serve`, `Bun.spawn`, `bun:sqlite` — **Node.js not supported**)
+- [OpenCode](https://github.com/sst/opencode) binary
+- A running [ework-web](../ework) instance (or real Gitea)
+- A bot user PAT on that instance with comment/write permissions
+
+The `tea` CLI is **no longer required** — the OpenCode subprocess uses the `opencode-ework` plugin's `reply` tool (HTTP `POST` with `BOT_TOKEN`), not `tea comment`. The `scripts/setup.ts` wizard still configures tea as a convenience for ad-hoc admin tasks; this will be removed in a future cleanup.
+
+## Quick start
+
+### 1. Install Bun
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### 2. Clone + setup
+
+```bash
+git clone https://github.com/ranxianglei/ework-daemon.git
+cd ework-daemon
+bun install
+bun run setup        # interactive wizard: checks deps, creates data dir, writes .env
+```
+
+### 3. Configure
+
+Edit `.env` (created from `.env.example` by the wizard):
+
+```bash
+$EDITOR .env
+```
+
+Required values:
+
+- `GITEA_URL` — your ework-web (e.g. `http://localhost:3002`) or real Gitea URL
+- `GITEA_TOKEN` — admin-scope read token
+- `BOT_USERNAME` — bot user login (must match the user `BOT_TOKEN` belongs to)
+- `BOT_TOKEN` — bot user PAT (used by the plugin to post replies)
+- `GITEA_WEBHOOK_SECRET` — HMAC secret shared with the issue tracker's webhook config
+- `DAEMON_ENV=production` — must be set to enable production mode (else falls back to test)
+- `OPENCODE_BASE_WORKDIR` — parent directory for opencode work dirs (e.g. `/home/<user>/projects`)
+
+### 4. Run
+
+```bash
+# Test mode (.env.test)
+bun start
+
+# Production (.env)
+bun start:prod
+```
+
+### 5. Configure the webhook
+
+On ework-web (or Gitea), go to the repository's **Settings → Webhooks → Add Webhook → Gitea**:
+
+| Field | Value |
+| --- | --- |
+| Target URL | `http://<daemon-ip>:3101/webhook` |
+| Content type | `application/json` |
+| Secret | (the `GITEA_WEBHOOK_SECRET` from `.env`) |
+| Trigger events | Issues, Issue Comment |
+
+## Usage
+
+### New issue → auto pickup
+
+Create an issue. The daemon replies "🔄 picked up" and spawns an OpenCode session. The AI reads the issue via the plugin's `issue` tool and works autonomously.
+
+### Existing issue → trigger via mention
+
+Comment with `@<bot>` (where `<bot>` is your configured `BOT_USERNAME`, e.g. `ework-daemon`):
+
+```
+@ework-daemon this issue still needs work
+```
+
+### Ongoing session → add instructions
+
+Once a session is running, just comment (no mention needed):
+
+```
+Also add a "remember me" checkbox
+```
+
+The daemon wraps the comment as a system message and pipes it to the running opencode session's stdin. The AI replies via the plugin's `reply` tool.
+
+### Close → stop
+
+Closing the issue terminates the OpenCode subprocess and cleans up the session.
+
+## Development
+
+### Watch mode
+
+```bash
+bun dev          # test mode (.env.test) — auto-restart on file changes
+bun dev:prod     # production config (.env)
+```
+
+### Type check
+
+```bash
+bun run check    # tsc --noEmit
+```
+
+### Compile standalone binary
+
+```bash
+bun run build            # → ./ework-daemon
+bun run install-global   # build + cp to ~/.local/bin/
+```
+
+The standalone binary can run without source: `ework-daemon status`, `ework-daemon issues`, etc. (see `src/cli.ts` for the CLI surface).
+
+### Smoke tests
+
+```bash
+bun run test:gitea       # ework-web / Gitea connectivity check
+```
+
+End-to-end tests live at `scripts/test-e2e.ts` — run manually (not yet in `bun test` format).
+
+## Production deployment (systemd)
+
+A systemd unit template is provided at `scripts/ework-daemon.service`. After running `./scripts/deploy.sh`:
+
+```bash
+sudo cp scripts/ework-daemon.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now ework-daemon
+```
+
+Management commands:
+
+```bash
+sudo systemctl status ework-daemon
+sudo journalctl -u ework-daemon -f
+```
+
+**Restart safety**: restarting kills all running OpenCode subprocesses. Always check first:
+
+```bash
+curl -s http://localhost:3101/api/processes
+# non-empty → wait; empty → safe to restart
+```
+
+### Deploy workflow
+
+```bash
+cd /path/to/ework-daemon
+bun run check && git add -A && git commit -m "..."
+./scripts/deploy.sh
+# (verify no processes running) then:
+sudo systemctl restart ework-daemon
+```
+
+## Environment variables
+
+| Variable | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `DAEMON_ENV` | ✅ | `test` | `production` to use `.env` values |
+| `GITEA_URL` | ✅ | — | ework-web or real Gitea base URL |
+| `GITEA_TOKEN` | ✅ | — | Admin-scope read token |
+| `GITEA_WEBHOOK_SECRET` | ✅ | — | HMAC secret for webhook verification |
+| `BOT_USERNAME` | ✅ | — | Bot user login (anti-recursion check) |
+| `BOT_TOKEN` | ✅ | — | Bot user PAT (passed to opencode subprocess) |
+| `DAEMON_PORT` | — | `3101` | Listen port |
+| `DAEMON_HOST` | — | `0.0.0.0` | Bind host (use `127.0.0.1` for local-only) |
+| `OPENCODE_BINARY` | — | `opencode` | OpenCode binary path |
+| `OPENCODE_BASE_WORKDIR` | ✅ | — | Parent dir for opencode work dirs |
+| `COMPLETION_CHECK_API_KEY` | — | — | Optional: model API key for completion judgment |
+| `COMPLETION_CHECK_BASE_URL` | — | — | Optional: model API base URL |
+| `COMPLETION_CHECK_MODEL` | — | — | Optional: model name |
+| `DAEMON_STUCK_THRESHOLD_MS` | — | `1800000` | Stuck threshold (30 min) |
+| `DAEMON_MAX_STUCK_NUDGES` | — | `1` | Max stuck nudges before giving up |
+
+Full list in `.env.example` and `src/config.ts`.
+
+## Data storage
+
+| Data | Path |
+| --- | --- |
+| Production DB | `~/.local/share/ework-daemon/ework-daemon.db` |
+| Test DB | `test/ework-daemon-test.db` (gitignored) |
+| Large-message archive | `<workdir>/.ework-daemon/comment-NNN.txt` |
+| Code repo work dirs | `$OPENCODE_BASE_WORKDIR/<repo>/` |
+
+Honors `XDG_DATA_HOME`.
+
+## Anti-recursion
+
+- The OpenCode subprocess posts comments via the `opencode-ework` plugin's `reply` tool, using `BOT_TOKEN` (which posts as user `BOT_USERNAME`).
+- The daemon's webhook handler drops any webhook whose `comment.user.login === BOT_USERNAME`. **Critical**: `BOT_USERNAME` must exactly match the user that `BOT_TOKEN` belongs to, or this check fails and the daemon recurses into itself.
+- Same-issue concurrent requests are serialized through an in-memory queue.
+
+## Project structure
+
+```
+src/
+├── config.ts             # Zod env validation (test/production dual mode)
+├── gitea.ts              # Gitea-compatible REST client (admin read + bot write)
+├── server.ts             # Webhook HTTP service (HMAC-SHA256)
+├── opencode.ts           # OpenCode process management (queue, streaming, stuck detection)
+├── op.ts                 # SQLite persistence (Issue / OpSession / Message)
+├── cli.ts                # CLI client
+├── index.ts              # Entry
+└── trackers/
+    ├── types.ts          # IssueTracker interface + 3-entity model
+    └── gitea-tracker.ts  # Gitea implementation (ework-web or real Gitea)
+```
+
+See [AGENTS.md](./AGENTS.md) for the full development spec — it is the highest-priority doc for contributors.
+
+## Related projects
+
+- [`ework`](../ework) — Standalone SQLite-backed issue tracker with Gitea-compatible REST shim. The default backend for ework-daemon.
+- [`opencode-ework`](../opencode-ework) — Plugin loaded by the OpenCode subprocess. Provides `issue`, `comments`, `floor`, `reply`, `search` tools.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/ework-daemon-server.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/index.ts";

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "ework-daemon",
+  "version": "0.1.0",
+  "description": "Issue-driven AI development daemon. Spawns opencode subprocesses to resolve Gitea issues.",
+  "module": "src/index.ts",
+  "type": "module",
+  "license": "MIT",
+  "author": "dog and contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ranxianglei/ework-daemon.git"
+  },
+  "homepage": "https://github.com/ranxianglei/ework-daemon",
+  "bugs": {
+    "url": "https://github.com/ranxianglei/ework-daemon/issues"
+  },
+  "keywords": [
+    "issue-driven",
+    "ai-agent",
+    "opencode",
+    "gitea",
+    "automation",
+    "daemon",
+    "bridge"
+  ],
+  "bin": {
+    "ework-daemon": "./src/cli.ts",
+    "ework-daemon-server": "./bin/ework-daemon-server.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "scripts/ework-daemon.service",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "setup": "bun run scripts/setup.ts",
+    "start": "bun --env-file=.env.test run src/index.ts",
+    "start:prod": "bun --env-file=.env run src/index.ts",
+    "dev": "bun --env-file=.env.test --watch src/index.ts",
+    "dev:prod": "bun --env-file=.env --watch src/index.ts",
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:gitea": "bun run scripts/test-gitea.ts",
+    "build": "bun build src/cli.ts --compile --outfile ework-daemon",
+    "install-global": "bun run build && cp ework-daemon ~/.local/bin/"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}

package/scripts/ework-daemon.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=ework-daemon — issue-driven AI dev daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=ework
+Group=ework
+WorkingDirectory=%h/.local/share/ework-daemon
+ExecStart=bun run src/index.ts
+Restart=on-failure
+RestartSec=5
+KillMode=process
+EnvironmentFile=%h/.local/share/ework-daemon/.env
+Environment="PATH=/usr/local/bin:/usr/bin:/bin:%h/.local/bin:%h/.bun/bin"
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=ework-daemon
+
+[Install]
+WantedBy=multi-user.target

package/src/cli.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env bun
+
+const BASE = process.env.EDAEMON_URL || "http://localhost:3101";
+
+async function api(path: string, init?: RequestInit) {
+  const res = await fetch(`${BASE}${path}`, init);
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`Error ${res.status}: ${body}`);
+    process.exit(1);
+  }
+  return res.json();
+}
+
+function fmtTime(ts: number | null) {
+  if (!ts) return "-";
+  const d = Date.now() - ts;
+  if (d < 60_000) return `${Math.floor(d / 1000)}s ago`;
+  if (d < 3_600_000) return `${Math.floor(d / 60_000)}m ago`;
+  return `${Math.floor(d / 3_600_000)}h ago`;
+}
+
+function fmtState(s: string) {
+  const colors: Record<string, string> = {
+    active: "\x1b[32m",
+    idle: "\x1b[36m",
+    running: "\x1b[33m",
+    closed: "\x1b[90m",
+    created: "\x1b[34m",
+  };
+  return `${colors[s] || ""}${s}\x1b[0m`;
+}
+
+// ─── Commands ───
+
+async function cmdStatus() {
+  const data = (await api("/api/status")) as Record<string, unknown>;
+  console.log("Daemon:    " + JSON.stringify(data.daemon));
+  console.log("Running:   " + data.running);
+  console.log("Pending:   " + data.pending);
+  console.log("Processes: " + data.processes);
+  console.log("Observed:  " + data.observedIssues);
+  console.log("Issues:    " + data.issues);
+  console.log("Sessions:  " + data.sessions);
+}
+
+async function cmdIssues() {
+  const issues = (await api("/api/issues")) as Record<string, unknown>[];
+  if (issues.length === 0) {
+    console.log("No issues.");
+    return;
+  }
+  for (const issue of issues) {
+    const scopeKey = issue.trackerScopeKey as string;
+    const issueId = issue.trackerIssueId as string;
+    const state = fmtState(issue.state as string);
+    console.log(`  ${state}  ${issue.trackerType}:${scopeKey}#${issueId}  "${issue.title}"  id=${issue.id}`);
+  }
+}
+
+async function cmdSessions() {
+  const sessions = (await api("/api/sessions")) as Record<string, unknown>[];
+  if (sessions.length === 0) {
+    console.log("No sessions.");
+    return;
+  }
+  for (const s of sessions) {
+    const state = fmtState(s.state as string);
+    const pid = s.opencodePid ? `pid=${s.opencodePid}` : "";
+    const sess = s.opencodeSessionId ? `session=${(s.opencodeSessionId as string).slice(0, 8)}` : "";
+    const extras = [pid, sess].filter(Boolean).join(", ");
+    console.log(`  ${state}  @${s.name}  ${extras}  id=${s.id}`);
+  }
+}
+
+async function cmdIssue(id: string) {
+  const data = (await api(`/api/issues/${id}`)) as Record<string, unknown>;
+  console.log("ID:         " + data.id);
+  console.log("Tracker:    " + data.trackerType);
+  console.log("Scope:      " + data.trackerScopeKey);
+  console.log("Issue ID:   " + data.trackerIssueId);
+  console.log("State:      " + fmtState(data.state as string));
+  console.log("Title:      " + data.title);
+  console.log("Created:    " + data.createdAt);
+  const sessions = data.sessions as Record<string, unknown>[] | undefined;
+  if (sessions && sessions.length > 0) {
+    console.log("Sessions:");
+    for (const s of sessions) {
+      console.log(`  @${s.name}  ${fmtState(s.state as string)}  id=${s.id}`);
+    }
+  }
+}
+
+async function cmdSession(id: string) {
+  const data = await api(`/api/sessions/${id}`) as Record<string, unknown>;
+  console.log("ID:         " + data.id);
+  console.log("Name:       " + data.name);
+  console.log("State:      " + fmtState(data.state as string));
+  console.log("Issue ID:   " + data.issueId);
+  console.log("Workdir:    " + (data.workdir || "-"));
+  console.log("PID:        " + (data.opencodePid || "-"));
+  console.log("Session:    " + (data.opencodeSessionId || "-"));
+  console.log("Created:    " + data.createdAt);
+}
+
+async function cmdSessionMessages(id: string) {
+  const messages = (await api(`/api/sessions/${id}/messages`)) as Record<string, unknown>[];
+  if (messages.length === 0) {
+    console.log("No messages.");
+    return;
+  }
+  for (const m of messages) {
+    const status = fmtState(m.status as string);
+    const preview = (m.content as string).slice(0, 60).replace(/\n/g, " ");
+    console.log(`  ${status}  ${preview}...  id=${(m.id as string).slice(0, 8)}`);
+  }
+}
+
+async function cmdQueue() {
+  const q = (await api("/api/queue")) as Record<string, number>;
+  const entries = Object.entries(q);
+  if (entries.length === 0) {
+    console.log("Queue empty.");
+    return;
+  }
+  for (const [key, depth] of entries) {
+    console.log(`  ${key}: ${depth}`);
+  }
+}
+
+async function cmdProcesses() {
+  const procs = (await api("/api/processes")) as Record<string, unknown>[];
+  if (procs.length === 0) {
+    console.log("No running processes.");
+    return;
+  }
+  for (const p of procs) {
+    console.log(
+      `  ▶ ${p.key}  pid=${p.pid}  last=${fmtTime(p.lastOutputAt as number | null)}`
+    );
+  }
+}
+
+async function cmdRetry(msgId: string) {
+  const res = (await api(`/api/messages/${msgId}/retry`, { method: "PATCH" })) as Record<string, unknown>;
+  console.log(`Retried: ${res.ok}  id=${msgId}`);
+}
+
+async function cmdStop(key: string) {
+  const res = (await api(`/api/processes/${encodeURIComponent(key)}`, { method: "DELETE" })) as Record<string, unknown>;
+  console.log(`Stopped: ${res.stopped}`);
+}
+
+// ─── Main ───
+
+function usage() {
+  console.log(`Usage: ework-daemon <command> [args...]
+
+Commands:
+  status                    Daemon overview
+  issues                    List all issues
+  issue <id>                Show issue detail + sessions
+  sessions                  List all sessions
+  session <id>              Show session detail
+  messages <sessionId>      Show messages for a session
+  queue                     Show pending queues
+  processes                 Show running processes
+  retry <msgId>             Retry a failed message
+  stop <key>                Kill process by runtime key
+
+Environment:
+  EDAEMON_URL  Daemon URL (default: http://localhost:3101)
+`);
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (!cmd) {
+  usage();
+  process.exit(0);
+}
+
+const commands: Record<string, () => Promise<void>> = {
+  status: cmdStatus,
+  issues: cmdIssues,
+  sessions: cmdSessions,
+  queue: cmdQueue,
+  processes: cmdProcesses,
+  issue: async () => {
+    if (!args[1]) { console.error("Usage: ework-daemon issue <id>"); process.exit(1); }
+    await cmdIssue(args[1]);
+  },
+  session: async () => {
+    if (!args[1]) { console.error("Usage: ework-daemon session <id>"); process.exit(1); }
+    await cmdSession(args[1]);
+  },
+  messages: async () => {
+    if (!args[1]) { console.error("Usage: ework-daemon messages <sessionId>"); process.exit(1); }
+    await cmdSessionMessages(args[1]);
+  },
+  retry: async () => {
+    if (!args[1]) { console.error("Usage: ework-daemon retry <msgId>"); process.exit(1); }
+    await cmdRetry(args[1]);
+  },
+  stop: async () => {
+    if (!args[1]) { console.error("Usage: ework-daemon stop <key>"); process.exit(1); }
+    await cmdStop(args[1]);
+  },
+};
+
+if (!commands[cmd]) {
+  console.error(`Unknown command: ${cmd}`);
+  usage();
+  process.exit(1);
+}
+
+commands[cmd]!();