@rsktash/beads-ui 0.1.50 → 0.10.3

package/README.md

@@ -1,182 +1,123 @@
-# beads-ui
+# @rsktash/bd-web
 
-Web UI for [Beads](https://github.com/rsktash/beads) workspaces.
+Web UI for [bd](https://github.com/rsktash/beads). Same workspace, runs
+locally or on a server, no Go runtime needed.
 
-## Install
-
-```bash
-npm install -g @rsktash/beads-ui
-```
-
-## Usage
-
-```bash
-cd /path/to/your/beads-workspace
-bd-ui start
-```
-
-### Commands
-
-| Command   | Description              |
-|-----------|--------------------------|
-| `start`   | Start the UI server      |
-| `stop`    | Stop the UI server       |
-| `restart` | Restart the UI server    |
-
-### Options
-
-| Flag             | Description                             | Default     |
-|------------------|-----------------------------------------|-------------|
-| `-h, --help`     | Show help message                       |             |
-| `-v, --version`  | Show version                            |             |
-| `-d, --debug`    | Enable debug logging                    |             |
-| `--open`         | Open browser after start                |             |
-| `--host <addr>`  | Bind address                            | `127.0.0.1` |
-| `--port <num>`   | Bind port                               | `3333`      |
-
-## Environment Variables
-
-| Variable                   | Description                                  | Default     |
-|----------------------------|----------------------------------------------|-------------|
-| `PORT`                     | Server port                                  | `3333`      |
-| `HOST`                     | Bind address                                 | `127.0.0.1` |
-| `BEADS_DOLT_PASSWORD`      | Password for remote Dolt server connection   |             |
-| `FILE_ATTACHMENT_BASE_URL` | Base URL for resolving `attach://` URIs      |             |
-| `BEADS_UI_AUTH_FILE`       | Path to users JSON file for authentication   |             |
-
-## Authentication
-
-Auth is optional. When `BEADS_UI_AUTH_FILE` points to a valid users file, login is required. When not set, auth is bypassed entirely.
-
-### Users file format
-
-```json
-{
-  "users": [
-    { "username": "alice", "password": "secret", "role": "Developer" },
-    { "username": "bob", "password": "guest", "role": "Viewer" }
-  ]
-}
-```
-
-### Running with auth
-
-```bash
-BEADS_UI_AUTH_FILE=/path/to/users.json bd-ui start
+```sh
+npm install -g @rsktash/bd-web
+cd /path/to/your/bd-workspace   # contains .bd/config
+bd-web start
+# → http://127.0.0.1:3333
 ```
 
-Session tokens are stored in the browser's localStorage and kept in server memory. Tokens are invalidated on server restart.
+## Stack
 
-## Dolt Database Modes
+- Server: Hono + `@hono/node-server`, `pg`, `better-sqlite3`
+- Client: Vite + React 19 + TanStack Router + TanStack Query + Tailwind v4
 
-Two Dolt connection modes, configured via `.beads/metadata.json`:
+## Environment
 
-### Embedded (default)
+| var | purpose |
+|---|---|
+| `BD_DB`             | override DSN (otherwise read from `.bd/config`) |
+| `BD_DB_PASSWORD`    | postgres password (or put it in `.bd/.env`) |
+| `BD_WEB_AUTH_FILE`  | enable optional auth — JSON `{users:[{username,password,role}]}` |
+| `HOST`, `PORT`      | bind (default `127.0.0.1:3333`) |
+| `DEBUG`             | extra logging |
 
-Spawns a local `dolt sql-server` from `.beads/embeddeddolt/`.
+## Development
 
-```json
-{
-  "backend": "dolt",
-  "dolt_database": "mydb"
-}
+```sh
+cd web/
+npm install
+npm run dev   # vite at 5173 + hono at 3333; vite proxies /api -> hono
 ```
 
-### Remote Server
+`npm run build` writes to `web/dist/`. `npm start` runs the Hono server, which
+serves both `/api/*` and the built client at `/`.
 
-Connects to an external Dolt server:
+## Releases
 
-```json
-{
-  "backend": "dolt",
-  "dolt_mode": "server",
-  "dolt_server_host": "127.0.0.1",
-  "dolt_server_port": 3308,
-  "dolt_server_user": "root",
-  "dolt_database": "mydb"
-}
-```
+Tag `v*` to publish:
 
-```bash
-BEADS_DOLT_PASSWORD=secret bd-ui start
+```sh
+git tag v0.1.1 && git push origin v0.1.1
 ```
 
-## Docker
+That triggers two GitHub Actions:
 
-```yaml
-services:
-  beads-ui:
-    image: ghcr.io/rsktash/beads-ui:latest
-    ports:
-      - "3333:3333"
-    volumes:
-      - /path/to/workspace:/workspace
-    working_dir: /workspace
-    environment:
-      - HOST=0.0.0.0
-      - BEADS_DOLT_PASSWORD=secret
-      - BEADS_UI_AUTH_FILE=/workspace/.beads/users.json
-      - FILE_ATTACHMENT_BASE_URL=https://files.example.com/attachments
-```
+- `.github/workflows/publish.yml` — `npm publish --provenance --access public`
+  for `@rsktash/bd-web`. Required repo secret: `NPM_TOKEN`.
+- `.github/workflows/docker.yml` — pushes `ghcr.io/rsktash/bd-web:{version}`,
+  `:{major}.{minor}`, and `:latest`. Uses the built-in `GITHUB_TOKEN`.
 
-Images published to `ghcr.io/rsktash/beads-ui` on version tags via GitHub Actions.
+Bump `web/package.json` before tagging.
 
-## Markdown Features
+## Routes
 
-### Attachments
+- `/` — board (kanban by status; ready issues at top)
+- `/list` — table view with filters
+- `/issue/<id>` — detail with markdown sections, deps, comments
+- `/projects` — postgres-only; lists schemas containing a `config` table
 
-`attach://` URIs for portable file references, resolved against `FILE_ATTACHMENT_BASE_URL`:
+The header always shows the project prefix, current user, and backend driver.
 
-```md
-![Screenshot](attach://bead-42/screenshot.png)
-```
+## Docker
 
-### Issue Mentions
+The repo ships a multi-stage [Dockerfile](Dockerfile). It builds the client,
+keeps only production deps, and runs `node server/index.js` as PID 1.
 
-`#issue-id` auto-links to the issue detail page:
+For the **full stack** (Postgres + bd-web together), use the root-level
+[docker-compose.yml](../docker-compose.yml):
 
-```md
-See #proj-a1b for details. Depends on #proj-c3d.
+```sh
+# from repo root
+cp .env.example .env             # set POSTGRES_PASSWORD and BD_PREFIX
+docker compose --profile full up -d --build
+# → http://127.0.0.1:3333
 ```
 
-### Deep Linking
-
-Sections and headings get unique element IDs for fragment linking:
+For an existing database, just run the bd-web container directly:
 
-- Predefined sections: `#description`, `#acceptance-criteria`, `#notes`, `#design`
-- Content headings: auto-slugified (e.g., `## My Heading` → `#my-heading`)
-
-```md
-[see details](/detail/proj-a1b#my-heading)
+```sh
+docker run --rm -p 3333:3333 \
+  -e BD_DB="postgres://bd@host.docker.internal:5432/tracker?sslmode=disable&search_path=myproject" \
+  -e BD_DB_PASSWORD=mypassword \
+  -e HOST=0.0.0.0 \
+  $(docker build -q ./web)
 ```
 
-### Theme
-
-Solarized Light color palette with matching syntax highlighting.
-
-## CLI Tools
+To enable auth, mount a users JSON file and point at it:
 
-### bd-grep
-
-Grep across beads issue content with snippet output. Uses `bd list` for issue filtering, then greps field content for pattern matches.
-
-```bash
-bd-grep <pattern> [bd-list-flags] [--field fields] [-A N] [-B N] [-C N] [-i] [-l]
+```sh
+docker run --rm -p 3333:3333 \
+  -v $(pwd)/users.json:/etc/bd/users.json:ro \
+  -e BD_DB=... -e BD_DB_PASSWORD=... \
+  -e BD_WEB_AUTH_FILE=/etc/bd/users.json \
+  $(docker build -q ./web)
 ```
 
-Examples:
+`users.json` shape:
 
-```bash
-bd-grep "timeline"                              # open issues, description
-bd-grep "timeline" --all                        # include closed
-bd-grep "route" -t epic                         # epics only
-bd-grep "fallback" --field description,design   # multiple fields
-bd-grep "composite" -C2                         # 2 lines context
-bd-grep "trip.id" -l                            # list matching IDs only
+```json
+{
+  "users": [
+    { "username": "alice", "password": "secret", "role": "Developer" },
+    { "username": "bob",   "password": "guest",  "role": "Viewer" }
+  ]
+}
 ```
 
-Requires `bd` and `jq`.
+## CLI setup (Go)
 
-## License
+The companion CLI `bd` lives in this repo's [parent directory](..). Install
+and initialise from the project README:
 
-MIT
+```sh
+go install github.com/rsktash/beads/cmd/bd@latest
+bd init --prefix myproject \
+  --db "postgres://bd@127.0.0.1:5432/tracker?sslmode=disable"
+export BD_DB_PASSWORD=...
+bd create "first issue" -p 0
+bd-web start                 # uses the same .bd/config
+```

package/bin/bd-web

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// Thin CLI shim for `bd-web`. Mirrors beads-ui/bin/bd-ui in shape: parses a
+// few flags (start/stop/restart, --port, --host, --debug, --open) and spawns
+// the server. We keep the surface tiny — heavy lifting lives in server/.
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SERVER = resolve(HERE, '..', 'server', 'index.js');
+
+const argv = process.argv.slice(2);
+const flags = { open: false, debug: false, host: undefined, port: undefined };
+let action = 'start';
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  switch (a) {
+    case '-h':
+    case '--help':
+      printHelp();
+      process.exit(0);
+    case '-v':
+    case '--version':
+      printVersion();
+      process.exit(0);
+    case 'start':
+    case 'stop':
+    case 'restart':
+      action = a;
+      break;
+    case '-d':
+    case '--debug':
+      flags.debug = true;
+      break;
+    case '--open':
+      flags.open = true;
+      break;
+    case '--host':
+      flags.host = argv[++i];
+      break;
+    case '--port':
+      flags.port = argv[++i];
+      break;
+    default:
+      process.stderr.write(`unknown arg: ${a}\n`);
+      process.exit(2);
+  }
+}
+
+if (action !== 'start') {
+  process.stderr.write(`only 'start' is implemented for now (got '${action}')\n`);
+  process.exit(2);
+}
+
+const env = { ...process.env };
+if (flags.port) env.PORT = String(flags.port);
+if (flags.host) env.HOST = flags.host;
+if (flags.debug) env.DEBUG = (env.DEBUG ? env.DEBUG + ',' : '') + 'bd-web*';
+if (flags.open) env.BD_WEB_OPEN = '1';
+
+const child = spawn(process.execPath, [SERVER], { env, stdio: 'inherit' });
+child.on('exit', (code) => process.exit(code ?? 0));
+
+function printHelp() {
+  process.stdout.write(`bd-web — web UI for beads
+
+Usage:
+  bd-web start [options]
+
+Options:
+  -h, --help          Show this help
+  -v, --version       Show version
+  -d, --debug         Verbose logging
+      --open          Open browser after start
+      --host <addr>   Bind address (default 127.0.0.1; HOST env)
+      --port <num>    Bind port (default 3333; PORT env)
+
+Environment:
+  BD_DB                 Override DSN (otherwise read from .bd/config)
+  BD_DB_PASSWORD        Password for postgres DSN (or .bd/.env, .env)
+  BD_WEB_AUTH_FILE      Optional JSON users file to enable auth
+  HOST, PORT            Bind address overrides
+`);
+}
+
+function printVersion() {
+  // The version is read from the package.json next to us, not hardcoded.
+  import('node:fs').then((fs) => {
+    const pkg = JSON.parse(fs.readFileSync(resolve(HERE, '..', 'package.json'), 'utf8'));
+    process.stdout.write(pkg.version + '\n');
+  });
+}