spexcode 0.1.0 → 0.1.1
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.
- package/README.md +86 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
<img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
|
|
2
|
+
|
|
3
|
+
> Spec-driven development gets wrecked by spec drift and spec bloat. SpexCode's bet
|
|
4
|
+
> is to keep the spec the cheap, honest twin of the code — rewritten in place, never
|
|
5
|
+
> a tuxedo of stale ceremony.
|
|
6
|
+
|
|
7
|
+
**SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
|
|
8
|
+
*spec node* — a `.spec/**/spec.md` whose body states the part's *present* intent — and **git is the
|
|
9
|
+
database**: a node's version is its count of content commits, and "drift" is governed code that moved
|
|
10
|
+
ahead of its spec. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
|
|
11
|
+
separate store.
|
|
12
|
+
|
|
13
|
+
There are two ways to meet SpexCode, and they are kept separate on purpose:
|
|
14
|
+
|
|
15
|
+
- **[Using SpexCode](#using-spexcode)** — install the `spex` CLI from npm and govern *your own* project.
|
|
16
|
+
- **[Contributing to SpexCode](#contributing-to-spexcode)** — develop the tool itself, in this repo.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Using SpexCode
|
|
21
|
+
|
|
22
|
+
You don't clone this repo to *use* SpexCode. Install the published CLI once, then point it at any project.
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
npm i -g spexcode # installs the `spex` command (needs Node ≥ 22)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Adopt it in your project — `spex init` is **additive**, it never restructures your code:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
cd ~/my-app
|
|
32
|
+
spex init # seed .spec/, a starter spexcode.json, and git hooks — nothing destructive
|
|
33
|
+
# 1. edit .spec/project/spec.md to describe your project
|
|
34
|
+
# 2. point spexcode.json's lint.governedRoots at your real source dir(s)
|
|
35
|
+
spex lint # the "coverage" warnings are your adoption TODO list
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Run it. The backend and the dashboard are **two commands on two ports**, so several projects can run
|
|
39
|
+
side by side on one host (the cwd picks which project is served):
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
spex serve --port 8788 # the backend (API + sessions) for THIS repo
|
|
43
|
+
spex dashboard --port 5174 --api-port 8788 # the board UI, pointed at that backend
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Then open <http://localhost:5174>. With no flags, `spex serve` defaults to `:8787` and `spex dashboard`
|
|
47
|
+
to `:5173`.
|
|
48
|
+
|
|
49
|
+
Day to day:
|
|
50
|
+
|
|
51
|
+
| command | what it does |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `spex lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
|
|
54
|
+
| `spex watch` | stream session / board transitions as they happen |
|
|
55
|
+
| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` file-format manuals |
|
|
56
|
+
| `spex board` | dump the current board state as JSON |
|
|
57
|
+
|
|
58
|
+
The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
|
|
59
|
+
place** (never a `## vN` changelog) and versioned by its commits.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Contributing to SpexCode
|
|
64
|
+
|
|
65
|
+
This repository *is* the SpexCode source, and it **dogfoods itself**: every change to the tool lands as a
|
|
66
|
+
spec node merged into `main`. Set up a checkout:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
|
|
70
|
+
npm --prefix spec-cli install
|
|
71
|
+
npm --prefix spec-dashboard install
|
|
72
|
+
npm run hooks # install the per-clone git hooks (main-guard + the session-stamp hook)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The development loop runs from source, with hot-reload — this is what `npm run web` is for, as opposed
|
|
76
|
+
to an installed user's `spex dashboard`:
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
npm run api # backend on :8787, hot-reloads on spec-cli/src changes
|
|
80
|
+
npm run web # the dashboard via Vite (HMR), proxying /api → :8787
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The contribution ritual in one breath: branch `node/<id>` off `main`, make the code change **and** its
|
|
84
|
+
`spec.md` *together*, commit, then `spex session done --propose merge` — a human performs the `--no-ff`
|
|
85
|
+
merge. That ritual, the spec-node model, the lint rules, and the reflexive config system are all spelled
|
|
86
|
+
out in **[`CLAUDE.md`](./CLAUDE.md)** — read it before your first change.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spexcode",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
|
|
6
6
|
"license": "MIT",
|