@thxgg/steward 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +95 -120
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,175 +1,150 @@
1
1
  # Steward
2
2
 
3
- Steward is a local-first Nuxt app for browsing Product Requirements Documents and tracking implementation state in a global SQLite database.
3
+ Local-first PRD workflow steward for AI agents and developers.
4
+ Nuxt UI + codemode MCP + SQLite state store.
4
5
 
5
- It is published as `@thxgg/steward` and provides the `prd` CLI command.
6
-
7
- This project is intended to be downloaded and run locally on your machine. It is not designed for public internet deployment.
8
-
9
- ## What It Does
10
-
11
- - Scans repositories for `docs/prd/*.md` files and displays them in a focused UI.
12
- - Reads task state (`tasks.json` and `progress.json`) from a global SQLite database.
13
- - Supports legacy `.claude/state/*` migration into the global database.
14
- - Resolves commit references for tasks, including pseudo-monorepo sub-repo contexts.
15
-
16
- ## Local-First Security Model
17
-
18
- Steward exposes local filesystem and git metadata for convenience. Because of that:
6
+ - npm package: `@thxgg/steward`
7
+ - CLI command: `prd`
19
8
 
20
- - Run it only on trusted local machines.
21
- - Do not expose it directly to the public internet.
22
- - Treat it as a developer workstation tool, not a hosted multi-user service.
9
+ ## Acknowledgments
23
10
 
24
- ## Requirements
11
+ Steward is heavily inspired by work from [dmmulroy](https://github.com/dmmulroy), including the similar project [Overseer](https://github.com/dmmulroy/overseer).
25
12
 
26
- - Node.js 22+
27
- - npm (or pnpm)
28
- - Git
29
- - Linux/macOS (or compatible environment)
13
+ ## Install
30
14
 
31
- ## Quick Start
15
+ ### Via npm
32
16
 
33
17
  ```bash
34
- npm install
35
- npm run dev
18
+ npm install -g @thxgg/steward
36
19
  ```
37
20
 
38
- With pnpm:
21
+ ### Without global install
39
22
 
40
23
  ```bash
41
- pnpm install
42
- pnpm run dev
24
+ npx -y @thxgg/steward ui
43
25
  ```
44
26
 
45
- Open `http://localhost:3000`, then add a local repository path that contains a `docs/prd/` directory.
27
+ ## Usage
46
28
 
47
- ## Install CLI
29
+ ### MCP Server
48
30
 
49
- ```bash
50
- npm install -g @thxgg/steward
51
- prd ui
31
+ Add to your MCP client config:
32
+
33
+ ```json
34
+ {
35
+ "mcpServers": {
36
+ "prd": {
37
+ "command": "npx",
38
+ "args": ["-y", "@thxgg/steward", "mcp"]
39
+ }
40
+ }
41
+ }
52
42
  ```
53
43
 
54
- With pnpm:
44
+ ### CLI
55
45
 
56
46
  ```bash
57
- pnpm add -g @thxgg/steward
58
47
  prd ui
48
+ prd ui --preview
49
+ prd ui --port 3100 --host 127.0.0.1
50
+ prd mcp
59
51
  ```
60
52
 
61
- Without global install:
53
+ ## Architecture
62
54
 
63
- ```bash
64
- npx -y @thxgg/steward ui
65
55
  ```
66
-
67
- You can also run the app through the project CLI:
68
-
69
- ```bash
70
- npm run ui
56
+ ┌─────────────────────────────────────────┐
57
+ │ Steward CLI (Node) │
58
+ │ - `prd ui` launches Nuxt app │
59
+ │ - `prd mcp` starts MCP over stdio │
60
+ └─────────────────────────────────────────┘
61
+ │
62
+ ▼
63
+ ┌─────────────────────────────────────────┐
64
+ │ Codemode MCP (`execute`) │
65
+ │ - VM sandbox │
66
+ │ - APIs: repos, prds, git, state │
67
+ └─────────────────────────────────────────┘
68
+ │
69
+ ▼
70
+ ┌─────────────────────────────────────────┐
71
+ │ Local SQLite PRD State │
72
+ │ - Global store shared across repos │
73
+ └─────────────────────────────────────────┘
71
74
  ```
72
75
 
73
- ## Scripts
74
-
75
- - `npm run dev` - Start local dev server
76
- - `npm run typecheck` - Run Nuxt type checking
77
- - `npm run build` - Build production bundle
78
- - `npm run preview` - Preview the production build locally
79
- - `npm run ui` - Launch `prd ui` (dev mode)
80
- - `npm run mcp` - Start MCP server over stdio
76
+ ## Codemode Pattern
81
77
 
82
- ## CLI
78
+ Steward exposes one MCP tool: `execute`.
83
79
 
84
- This package ships a `prd` command.
80
+ ```js
81
+ const reposList = await repos.list()
82
+ const repo = reposList[0]
83
+ if (!repo) return { error: 'No repos configured' }
85
84
 
86
- - npm package: `@thxgg/steward`
85
+ const prdList = await prds.list(repo.id)
86
+ if (prdList.length === 0) return { repo: repo.name, prds: 0 }
87
87
 
88
- - `prd ui` - Launch the web app in dev mode (default)
89
- - `prd ui --preview` - Launch the production preview server
90
- - `prd ui --port 3100 --host 127.0.0.1` - Pass Nuxt host/port options
91
- - `prd mcp` - Run the codemode MCP server over stdio
92
-
93
- For local shell usage while developing this repo:
94
-
95
- ```bash
96
- npm link
97
- prd ui
88
+ const slug = prdList[0].slug
89
+ return {
90
+ doc: await prds.getDocument(repo.id, slug),
91
+ tasks: await prds.getTasks(repo.id, slug),
92
+ progress: await prds.getProgress(repo.id, slug)
93
+ }
98
94
  ```
99
95
 
100
- ## MCP Usage
96
+ ## APIs
101
97
 
102
- The MCP server exposes one codemode tool: `execute`.
98
+ Inside `execute`, these APIs are available:
103
99
 
104
- The codemode runtime has these APIs in scope:
100
+ - `repos` - register/list/remove repos and refresh discovered git repos
101
+ - `prds` - list/read PRD docs, tasks, progress, and task commit refs
102
+ - `git` - commit metadata, diffs, file diffs, and file contents
103
+ - `state` - direct PRD state get/upsert by repo id or path
105
104
 
106
- - `repos` - list/add/remove/refresh repository registrations
107
- - `prds` - list/get PRD documents and state-backed task/progress data
108
- - `git` - commit metadata, diffs, and file content lookups
109
- - `state` - direct PRD state reads/writes in SQLite
105
+ Detailed API docs and examples: `docs/MCP.md`
110
106
 
111
- Example MCP client configuration:
107
+ ## Local-First Security Model
112
108
 
113
- ```json
114
- {
115
- "mcpServers": {
116
- "prd": {
117
- "command": "prd",
118
- "args": ["mcp"]
119
- }
120
- }
121
- }
122
- ```
109
+ Steward reads local filesystem and git metadata by design.
123
110
 
124
- For codemode API details and examples, see `docs/MCP.md`.
111
+ - Run only on trusted local machines
112
+ - Do not expose directly to the public internet
113
+ - Treat as a workstation tool, not a hosted multi-user service
125
114
 
126
- ## Global PRD State Storage
115
+ ## Storage
127
116
 
128
- PRD state is system-global and stored in SQLite:
117
+ PRD state is stored in SQLite at:
129
118
 
130
- - Default: `${XDG_DATA_HOME:-~/.local/share}/prd/state.db`
131
- - Override full path: `PRD_STATE_DB_PATH`
132
- - Override base dir: `PRD_STATE_HOME` (resolved to `<PRD_STATE_HOME>/state.db`)
119
+ 1. `PRD_STATE_DB_PATH` (if set)
120
+ 2. `PRD_STATE_HOME/state.db` (if set)
121
+ 3. `${XDG_DATA_HOME:-~/.local/share}/prd/state.db`
133
122
 
134
- This allows multiple local repos to share one PRD state store.
123
+ ## Development
135
124
 
136
- ## Environment Variables
125
+ ```bash
126
+ npm install
127
+ npm run dev
128
+ npm run typecheck
129
+ npm run build
130
+ ```
137
131
 
138
- Copy `.env.example` to `.env` if you want to override defaults.
132
+ ## Environment Variables
139
133
 
140
- | Variable | Required | Description |
141
- | --- | --- | --- |
142
- | `PRD_STATE_DB_PATH` | No | Absolute path to SQLite database file |
143
- | `PRD_STATE_HOME` | No | Directory used for database home (`state.db` inside it) |
144
- | `XDG_DATA_HOME` | No | Used for default global state location |
134
+ | Variable | Description |
135
+ | --- | --- |
136
+ | `PRD_STATE_DB_PATH` | Absolute path to SQLite DB file |
137
+ | `PRD_STATE_HOME` | Base directory for DB (`state.db` inside) |
138
+ | `XDG_DATA_HOME` | Fallback base path for default DB location |
145
139
 
146
- ## OpenCode Bundle Included
140
+ ## OpenCode Bundle
147
141
 
148
- This repository includes a curated OpenCode bundle under `opencode/`:
142
+ This repo includes curated OpenCode assets under `opencode/`:
149
143
 
150
144
  - Commands: `prd`, `prd-task`, `complete-next-task`, `commit`
151
145
  - Skills: `prd`, `prd-task`, `complete-next-task`, `commit`
152
146
  - Script: `prd-db.mjs`
153
147
 
154
- `frontend-design` is intentionally not included.
155
-
156
- To install into a local OpenCode config:
157
-
158
- ```bash
159
- mkdir -p ~/.config/opencode
160
- cp -R opencode/commands ~/.config/opencode/
161
- cp -R opencode/skills ~/.config/opencode/
162
- cp -R opencode/scripts ~/.config/opencode/
163
- ```
164
-
165
- ## CI
166
-
167
- GitHub Actions runs:
168
-
169
- - Typecheck + build validation
170
- - Secret scanning with gitleaks
171
-
172
- ## Roadmap
148
+ ## License
173
149
 
174
- - Continue hardening local-only workflows
175
- - Expand codemode APIs and automation patterns
150
+ MIT
package/package.json CHANGED
@@ -1,18 +1,18 @@
1
1
  {
2
2
  "name": "@thxgg/steward",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Local-first PRD workflow steward with codemode MCP and web UI.",
5
5
  "type": "module",
6
6
  "author": "thxgg",
7
7
  "license": "MIT",
8
8
  "repository": {
9
9
  "type": "git",
10
- "url": "git+https://github.com/thxgg/prd-viewer.git"
10
+ "url": "git+https://github.com/thxgg/steward.git"
11
11
  },
12
12
  "bugs": {
13
- "url": "https://github.com/thxgg/prd-viewer/issues"
13
+ "url": "https://github.com/thxgg/steward/issues"
14
14
  },
15
- "homepage": "https://github.com/thxgg/prd-viewer#readme",
15
+ "homepage": "https://github.com/thxgg/steward#readme",
16
16
  "keywords": [
17
17
  "prd",
18
18
  "mcp",