spec-driven-development 3.7.6 → 3.7.7

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 (3) hide show
  1. package/README.md +25 -170
  2. package/bin/contractspec.mjs +1 -1
  3. package/package.json +33 -33
package/README.md CHANGED
@@ -1,192 +1,47 @@
1
- # Spec-Driven Development (SDD)
1
+ # spec-driven-development
2
2
 
3
- **Spec-Driven Development** is a way to build software where the **specification is the source of truth**, not a “documentation artifact we promise to update later”.
3
+ Website: https://contractspec.io
4
4
 
5
- If you’ve ever shipped something that *looked right* in code review and still broke production because the DB, API, client, docs, and policies drifted apart… welcome. SDD is what you do when you’re tired of reality diverging from your repo.
5
+ **npm-published CLI alias for ContractSpec under the `sdd` / `spec-driven-development` binary names. Thin wrapper that delegates to `@contractspec/app.cli-contractspec`.**
6
6
 
7
- This package provides a practical SDD toolchain (currently powered by **ContractSpec**) while keeping the README focused on the **method**, not just the tooling.
7
+ ## What It Does
8
8
 
9
- ---
9
+ - **Layer**: apps-registry
10
+ - **Consumers**: end-users installing `npx sdd` or `npx spec-driven-development`
10
11
 
11
- ## What “Spec-Driven” actually means
12
+ ## Installation
12
13
 
13
- SDD is **not** “we wrote an OpenAPI file once”.
14
- SDD is:
14
+ `npm install spec-driven-development`
15
15
 
16
- - You express **intent** in a structured, reviewable spec
17
- - The spec is **executable** (it can generate or validate artifacts)
18
- - Changes are managed through **contract diffs**, not vibes
19
- - The spec sits **above** implementations and keeps them coherent over time
16
+ or
20
17
 
21
- A good spec is:
22
- - **Typed** (or at least structurally constrained)
23
- - **Diffable** (PR review works)
24
- - **Enforceable** (CI can fail you)
25
- - **Composable** (small specs > giant documents)
26
-
27
- ---
28
-
29
- ## Why this exists
30
-
31
- Traditional workflow (a.k.a. “drift by design”):
32
-
33
- 1. Implement code
34
- 2. Update docs “later”
35
- 3. Ship
36
- 4. Debug why clients don’t match the backend
37
- 5. Repeat until burnout
38
-
39
- SDD workflow (boring in the best way):
40
-
41
- 1. Define / update spec
42
- 2. Review spec changes (diffs + breaking-change flags)
43
- 3. Generate / update code + SDKs + docs + tests
44
- 4. Validate implementation against spec in CI
45
- 5. Ship with fewer surprises
46
-
47
- This matters more when:
48
- - You have **multiple surfaces** (DB + API + Web + Mobile + integrations)
49
- - You use **AI coding** (fast output, high drift risk)
50
- - You need **governance** (policies, PII rules, permissions, compliance)
51
-
52
- ---
53
-
54
- ## What belongs in a spec
55
-
56
- A spec can describe *more than endpoints*.
57
-
58
- Typical useful layers:
59
-
60
- - **Domain models**: entities, value objects, enums, invariants
61
- - **Operations**: commands/queries, inputs/outputs, error shapes
62
- - **Events**: event names, payloads, versioning rules
63
- - **Policies**: auth rules, PII classification, access constraints
64
- - **Examples**: representative requests/responses, edge cases
65
- - **UI contracts (optional)**: view models, forms, display schemas
66
-
67
- The goal is **coherence**. Your system should have one “truth spine” that everything else attaches to.
68
-
69
- ---
70
-
71
- ## What does *not* belong in a spec
72
-
73
- Specs should avoid becoming implementation fan-fiction.
74
-
75
- Usually keep out:
76
- - Framework choices (“use Next.js”, “use NestJS”) unless required
77
- - Internal function names
78
- - Micro-optimizations
79
- - Detailed component trees (unless you’re explicitly generating UI)
80
-
81
- Put those in design docs or architecture notes if you want, but don’t let them poison the contract.
82
-
83
- ---
84
-
85
- ## The SDD loop (the part people skip)
86
-
87
- SDD is only real if you do **diffs and gates**.
88
-
89
- A healthy loop looks like:
90
-
91
- 1. **Propose change**
92
- Update the spec as the first PR commit.
93
-
94
- 2. **Review contract diff**
95
- Humans review *impact*, not just code.
96
- - What breaks?
97
- - What needs migration?
98
- - What needs versioning?
99
-
100
- 3. **Regenerate artifacts**
101
- Update SDKs, stubs, docs, types, schemas, fixtures.
102
-
103
- 4. **Validate implementation**
104
- CI checks that implementations match the contract (and policies).
105
-
106
- 5. **Ship with intent preserved**
107
- The “why” remains attached to the system, not lost in chat logs.
108
-
109
- This is the main reason SDD pairs well with AI:
110
- the spec is the constraint system that prevents silent drift.
111
-
112
- ---
113
-
114
- ## “Isn’t this just contract-first?”
115
-
116
- Adjacent, but broader.
117
-
118
- - **Contract-first** often means “API schema first”.
119
- - **Spec-driven** means “system intent first”, across multiple surfaces:
120
- API, events, models, policies, examples, and sometimes UI boundaries.
121
-
122
- If your “contract” only covers endpoints, you’re still leaving a lot of drift vectors open.
123
-
124
- ---
125
-
126
- ## What this package provides
127
-
128
- `spec-driven-development` is a **tooling distribution** that helps you practice SDD in real projects, including:
129
-
130
- - Keeping specs as **versioned artifacts**
131
- - Producing **diffs** to detect breaking changes
132
- - Generating / syncing artifacts to reduce manual duplication
133
- - Enforcing constraints in **CI** (so reality cannot “quietly” diverge)
134
-
135
- At the moment, this package is powered by **ContractSpec** (same engine, different framing).
136
-
137
- ---
138
-
139
- ## Install
140
-
141
- ```bash
142
- npm install spec-driven-development
143
- # or
144
- pnpm add spec-driven-development
145
- # or
146
- yarn add spec-driven-development
147
- # or
148
- bun add spec-driven-development
149
- ````
150
-
151
- ---
18
+ `bun add spec-driven-development`
152
19
 
153
20
  ## Usage
154
21
 
155
- This package is meant to be used as a CLI/tooling workflow inside your repo.
156
-
157
- Start here:
158
-
159
22
  ```bash
160
- npx spec-driven-development --help
23
+ npx sdd --help
161
24
  # or
162
- bunx spec-driven-development --help
25
+ bunx sdd --help
163
26
  ```
164
27
 
165
- If your project/team already uses the canonical tool name, you may also want:
166
-
167
- * `contractspec` (same underlying engine, more product/tooling oriented docs)
168
-
169
- ---
170
-
171
- ## Practical tips (so SDD doesn’t become “SDD theater”)
28
+ ## Public Entry Points
172
29
 
173
- * **Make the spec reviewable**: small, composable files beat one mega-spec.
174
- * **Treat examples as tests**: if examples rot, your spec is lying.
175
- * **Version events** intentionally**: event drift is the silent killer of systems.
176
- * **Put PII + auth in the spec**: policies are part of reality, not “later work”.
177
- * **Gate breaking changes in CI**: humans are fallible, CI is relentless (good).
30
+ - `sdd` -> `./bin/contractspec.mjs`
31
+ - `spec-driven-development` -> `./bin/contractspec.mjs`
178
32
 
179
- ---
33
+ ## Local Commands
180
34
 
181
- ## Who this is for
35
+ - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
36
+ - `bun run publish:pkg:canary` — bun publish:pkg --tag canary
182
37
 
183
- * Teams shipping APIs + clients who are tired of drift
184
- * AI-assisted builders who want **constraints and coherence**
185
- * Platform/tooling folks who want safer change management
186
- * Anyone who hears “it’s just a rename” and flinches
38
+ ## Recent Updates
187
39
 
188
- ---
40
+ - Replace eslint+prettier by biomejs to optimize speed
41
+ - PublishConfig not supported by bun
189
42
 
190
- ## License
43
+ ## Notes
191
44
 
192
- MIT (or see repository for details).
45
+ - This package is a shim; all logic lives in `@contractspec/app.cli-contractspec`
46
+ - Do not add dependencies beyond the CLI app workspace reference
47
+ - Changes to `bin/contractspec.mjs` affect every user -- test locally before publishing
package/bin/contractspec.mjs CHANGED
@@ -1,3 +1,3 @@
1
1
  #!/usr/bin/env node
2
2
  // One bin, picks the right runtime via conditional exports.
3
- import "@contractspec/app.cli-contractspec/run";
3
+ import '@contractspec/app.cli-contractspec/run';
package/package.json CHANGED
@@ -1,35 +1,35 @@
1
1
  {
2
- "name": "spec-driven-development",
3
- "version": "3.7.6",
4
- "description": "CLI tool for creating, building, and validating contract specifications",
5
- "bin": {
6
- "sdd": "./bin/contractspec.mjs",
7
- "spec-driven-development": "./bin/contractspec.mjs"
8
- },
9
- "dependencies": {
10
- "@contractspec/app.cli-contractspec": "3.7.6"
11
- },
12
- "scripts": {
13
- "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
14
- "publish:pkg:canary": "bun publish:pkg --tag canary"
15
- },
16
- "keywords": [
17
- "cli",
18
- "contracts",
19
- "code-generation",
20
- "ai",
21
- "typescript"
22
- ],
23
- "publishConfig": {
24
- "name": "spec-driven-development",
25
- "access": "public",
26
- "registry": "https://registry.npmjs.org/"
27
- },
28
- "license": "MIT",
29
- "repository": {
30
- "type": "git",
31
- "url": "https://github.com/lssm-tech/contractspec.git",
32
- "directory": "packages/apps-registry/spec-driven-development"
33
- },
34
- "homepage": "https://contractspec.io"
2
+ "name": "spec-driven-development",
3
+ "version": "3.7.7",
4
+ "description": "CLI tool for creating, building, and validating contract specifications",
5
+ "bin": {
6
+ "sdd": "./bin/contractspec.mjs",
7
+ "spec-driven-development": "./bin/contractspec.mjs"
8
+ },
9
+ "dependencies": {
10
+ "@contractspec/app.cli-contractspec": "4.0.0"
11
+ },
12
+ "scripts": {
13
+ "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
14
+ "publish:pkg:canary": "bun publish:pkg --tag canary"
15
+ },
16
+ "keywords": [
17
+ "cli",
18
+ "contracts",
19
+ "code-generation",
20
+ "ai",
21
+ "typescript"
22
+ ],
23
+ "publishConfig": {
24
+ "name": "spec-driven-development",
25
+ "access": "public",
26
+ "registry": "https://registry.npmjs.org/"
27
+ },
28
+ "license": "MIT",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "https://github.com/lssm-tech/contractspec.git",
32
+ "directory": "packages/apps-registry/spec-driven-development"
33
+ },
34
+ "homepage": "https://contractspec.io"
35
35
  }