Skip to content

Commit db44c18

Browse files
henryomanhenryoman
committed
Generate visible Dispatch workspace
1 parent 0b072b0 commit db44c18

8 files changed

Lines changed: 676 additions & 136 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ It can:
1919

2020
It does not:
2121

22-
- replace project-specific scripts unless `dispatch init --force` is used
22+
- add package scripts for normal quality commands like `lint`, `test`, or `check`
23+
- manage app runtime scripts like `dev`, `build`, or `start`
2324
- infer a deployment platform
2425
- hide destructive sync behavior behind a safe-sounding command
2526
- require every quality command to be added to `package.json`
@@ -39,6 +40,7 @@ Setup may update the target repo by:
3940
- adding `@memoir/dispatch` to `devDependencies`
4041
- adding the small managed script set to `package.json`
4142
- creating or patching `AGENTS.md`
43+
- writing the visible `dispatch/` workspace for agent options and project commands
4244
- writing `.oxlintrc.json`
4345
- writing `.github/workflows/ci.yml`
4446
- running the detected package manager install command
@@ -61,13 +63,13 @@ Refresh Dispatch-managed files later:
6163
dispatch init
6264
```
6365

64-
Force replacement of conflicting managed scripts:
66+
Force replacement of managed files such as the CI workflow and oxlint config:
6567

6668
```bash
6769
dispatch init --force
6870
```
6971

70-
Use `--force` carefully. It is appropriate after moving repo-specific behavior into `dispatch.config.ts` or `.dispatch/commands/*.ts`; it is not a safe way to blindly overwrite existing project scripts.
72+
Use `--force` carefully. It is not needed for the generated utility package scripts.
7173

7274
## Install Versus Init
7375

@@ -87,38 +89,49 @@ or by invoking the package as a bootstrap command:
8789
bunx @memoir/dispatch
8890
```
8991

90-
After initialization, package scripts such as `bun dev` or `bun sync` call the `dispatch` binary from `node_modules/.bin`. The command implementation still comes from the installed package unless the repo overrides it with local config, local command files, or unmanaged package scripts.
92+
After initialization, package scripts such as `bun sync` and `bun portclean` run visible files in `dispatch/scripts/`. Those files delegate to the `dispatch` binary from `node_modules/.bin`.
9193

9294
## Generated Package Scripts
9395

94-
`dispatch init` keeps `package.json` intentionally small. It manages only common human workflow aliases:
96+
`dispatch init` adds easy package-script aliases for common Dispatch workflows:
9597

9698
```json
9799
{
98100
"scripts": {
99-
"dev": "dispatch dev",
100-
"sync": "dispatch sync",
101-
"sync-careful": "dispatch sync-careful",
102-
"portclean": "dispatch portclean",
103-
"update-all": "dispatch update-all",
104-
"dp": "dispatch dp",
105-
"menu": "dispatch menu"
101+
"clean": "bun run dispatch/scripts/clean.ts",
102+
"sync": "bun run dispatch/scripts/sync.ts",
103+
"sync-careful": "bun run dispatch/scripts/sync-careful.ts",
104+
"port": "bun run dispatch/scripts/port.ts",
105+
"portclean": "bun run dispatch/scripts/portclean.ts",
106+
"processes": "bun run dispatch/scripts/processes.ts",
107+
"update": "bun run dispatch/scripts/update.ts",
108+
"update-all": "bun run dispatch/scripts/update-all.ts",
109+
"scripts": "bun run dispatch/scripts/scripts.ts",
110+
"ops": "bun run dispatch/scripts/ops.ts",
111+
"menu": "bun run dispatch/scripts/menu.ts"
106112
}
107113
}
108114
```
109115

110116
People can then use normal package-manager commands:
111117

112118
```bash
113-
bun dev
119+
bun clean
114120
bun sync
115121
bun sync-careful
122+
bun port
116123
bun portclean
117124
bun update-all
118-
bun dp
119125
```
120126

121-
Quality commands stay available through `dispatch` without adding more package-script noise:
127+
`dispatch init` intentionally writes those utility script names. It does not generate normal project quality scripts such as `lint`, `test`, or `check`, and it does not replace `dev`.
128+
129+
```bash
130+
bun sync
131+
bun portclean
132+
```
133+
134+
The same quality commands are always available through the binary too:
122135

123136
```bash
124137
dispatch lint
@@ -133,20 +146,20 @@ If the repo appears to use Convex, `dispatch init` also adds:
133146
```json
134147
{
135148
"scripts": {
136-
"convex": "dispatch convex",
137-
"convex:dev": "dispatch convex dev",
138-
"convex:deploy": "dispatch convex deploy"
149+
"convex": "bun run dispatch/scripts/convex.ts",
150+
"convex:dev": "bun run dispatch/scripts/convex-dev.ts",
151+
"convex:deploy": "bun run dispatch/scripts/convex-deploy.ts"
139152
}
140153
}
141154
```
142155

143156
## Agent Instructions
144157

145-
`dispatch init` creates or updates the consuming repo's root `AGENTS.md`.
158+
`dispatch init` creates or updates the consuming repo's root `AGENTS.md` and writes the Dispatch agent option at `dispatch/agents/default.md`.
146159

147160
The important behavior is that the target codebase gets instructions when it runs setup. The package having its own `AGENTS.md` is not enough.
148161

149-
Dispatch writes only this managed block:
162+
The root `AGENTS.md` gets only this managed block:
150163

151164
```md
152165
<!-- dispatch:agents:start -->
@@ -156,6 +169,8 @@ Dispatch writes only this managed block:
156169

157170
User-authored content outside the block is preserved. On later runs, Dispatch replaces only the managed block.
158171

172+
The managed block points agents at the visible `dispatch/` folder, where Dispatch-owned scripts, command guidance, and agent options live. Generated agent profiles include `default.md`, `bun-svelte.md`, `bun-next.md`, `bun-astro.md`, and `quant.md`.
173+
159174
If `AGENTS.md` contains only one marker, or markers are in the wrong order, setup refuses to continue. That prevents Dispatch from guessing and overwriting user content.
160175

161176
Check the state with:
@@ -206,14 +221,15 @@ Use `commands` when you want to fully override a Dispatch command with an argv a
206221
Project command files live at:
207222

208223
```txt
209-
.dispatch/commands/<name>.ts
224+
dispatch/commands/<name>.ts
210225
```
211226

212227
Example:
213228

214229
```txt
215-
package.json "sync": "dispatch sync"
216-
.dispatch/commands/sync.ts repo-specific implementation
230+
package.json "sync": "bun run dispatch/scripts/sync.ts"
231+
dispatch/scripts/sync.ts generated package-script entrypoint
232+
dispatch/commands/sync-db.ts repo-specific dispatch sync-db implementation
217233
```
218234

219235
A command file can export an argv array:
@@ -380,7 +396,8 @@ Dispatch tries to be boring and predictable:
380396

381397
- user-authored `AGENTS.md` content is preserved outside Dispatch markers
382398
- partial marker state is treated as a conflict
383-
- existing package scripts are preserved unless they are already managed by Dispatch or `--force` is used
399+
- `init` writes the managed utility package scripts directly
400+
- `init` does not generate package scripts for `lint`, `test`, `check`, `dev`, `build`, or `start`
384401
- deploy has no platform fallback
385402
- `sync` is labeled as destructive and supports `--dry-run`
386403
- `sync-careful` exists for the common safe update case

‎examples/package-scripts.json‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
11
{
22
"scripts": {
3-
"dev": "dispatch dev",
4-
"sync": "dispatch sync",
5-
"sync-careful": "dispatch sync-careful",
6-
"portclean": "dispatch portclean",
7-
"update-all": "dispatch update-all",
8-
"dp": "dispatch dp",
9-
"menu": "dispatch menu"
3+
"clean": "bun run dispatch/scripts/clean.ts",
4+
"sync": "bun run dispatch/scripts/sync.ts",
5+
"sync-careful": "bun run dispatch/scripts/sync-careful.ts",
6+
"port": "bun run dispatch/scripts/port.ts",
7+
"portclean": "bun run dispatch/scripts/portclean.ts",
8+
"processes": "bun run dispatch/scripts/processes.ts",
9+
"update": "bun run dispatch/scripts/update.ts",
10+
"update-all": "bun run dispatch/scripts/update-all.ts",
11+
"scripts": "bun run dispatch/scripts/scripts.ts",
12+
"ops": "bun run dispatch/scripts/ops.ts",
13+
"menu": "bun run dispatch/scripts/menu.ts"
1014
},
1115
"devDependencies": {
1216
"@memoir/dispatch": "^0.1.0"

‎repo-tools-standardization-spec.md‎

Lines changed: 72 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -143,18 +143,17 @@ Every repo should end up with this shape:
143143
```json
144144
{
145145
"scripts": {
146-
"ci": "repo-tools ci",
147-
"check": "repo-tools check",
148-
"lint": "repo-tools lint",
149-
"lint:fix": "repo-tools lint --fix",
150-
"typecheck": "repo-tools typecheck",
151-
"test": "repo-tools test",
152-
"test:watch": "repo-tools test --watch",
153-
"test:coverage": "repo-tools test --coverage",
154146
"clean": "repo-tools clean",
155-
"dev": "<repo-specific>",
156-
"build": "<repo-specific>",
157-
"start": "<repo-specific>"
147+
"sync": "repo-tools sync",
148+
"sync-careful": "repo-tools sync-careful",
149+
"port": "repo-tools port",
150+
"portclean": "repo-tools portclean",
151+
"processes": "repo-tools processes",
152+
"update": "repo-tools update",
153+
"update-all": "repo-tools update-all",
154+
"scripts": "repo-tools scripts",
155+
"ops": "repo-tools ops",
156+
"menu": "repo-tools menu"
158157
},
159158
"devDependencies": {
160159
"@your-scope/repo-tools": "^1.0.0"
@@ -165,15 +164,17 @@ Every repo should end up with this shape:
165164
Only these scripts are standardized by default:
166165

167166
```txt
168-
ci
169-
check
170-
lint
171-
lint:fix
172-
typecheck
173-
test
174-
test:watch
175-
test:coverage
176167
clean
168+
sync
169+
sync-careful
170+
port
171+
portclean
172+
processes
173+
update
174+
update-all
175+
scripts
176+
ops
177+
menu
177178
```
178179

179180
These remain repo-local when needed:
@@ -679,25 +680,27 @@ For each managed script:
679680
| Missing | Add it. |
680681
| Already equals the expected `repo-tools` command | Leave it. |
681682
| Starts with `repo-tools` but old command shape | Update it. |
682-
| Custom command exists | Do not overwrite unless `--force`. |
683+
| Custom command exists for a managed utility alias | Replace it with the expected `repo-tools` command. |
683684

684685
Managed scripts:
685686

686687
```json
687688
{
688-
"ci": "repo-tools ci",
689-
"check": "repo-tools check",
690-
"lint": "repo-tools lint",
691-
"lint:fix": "repo-tools lint --fix",
692-
"typecheck": "repo-tools typecheck",
693-
"test": "repo-tools test",
694-
"test:watch": "repo-tools test --watch",
695-
"test:coverage": "repo-tools test --coverage",
696-
"clean": "repo-tools clean"
689+
"clean": "repo-tools clean",
690+
"sync": "repo-tools sync",
691+
"sync-careful": "repo-tools sync-careful",
692+
"port": "repo-tools port",
693+
"portclean": "repo-tools portclean",
694+
"processes": "repo-tools processes",
695+
"update": "repo-tools update",
696+
"update-all": "repo-tools update-all",
697+
"scripts": "repo-tools scripts",
698+
"ops": "repo-tools ops",
699+
"menu": "repo-tools menu"
697700
}
698701
```
699702

700-
Do not overwrite these:
703+
Do not add or overwrite lifecycle/product scripts that are not managed aliases:
701704

702705
```txt
703706
dev
@@ -709,29 +712,39 @@ deploy
709712
release
710713
```
711714

712-
### 8.3 Init conflict example
715+
### 8.3 Init script collision example
713716

714717
If the repo has this:
715718

716719
```json
717720
{
718721
"scripts": {
719-
"lint": "eslint ."
722+
"dev": "vite dev",
723+
"sync": "bash scripts/sync-with-main.sh",
724+
"portclean": "bash scripts/portclean.sh"
720725
}
721726
}
722727
```
723728

724-
`repo-tools init` should print:
729+
`repo-tools init` should keep non-managed project scripts and write managed utility aliases:
725730

726731
```txt
727-
Conflict: package.json scripts.lint already exists.
728-
Current: eslint .
729-
Wanted: repo-tools lint
730-
731-
Run repo-tools init --force to replace it.
732+
repo-tools init updated:
733+
package.json scripts.sync
734+
package.json scripts.portclean
732735
```
733736

734-
This protects repo-specific behavior.
737+
The final `package.json` keeps repo-specific behavior:
738+
739+
```json
740+
{
741+
"scripts": {
742+
"dev": "vite dev",
743+
"sync": "repo-tools sync",
744+
"portclean": "repo-tools portclean"
745+
}
746+
}
747+
```
735748

736749
### 8.4 Idempotence requirement
737750

@@ -1575,15 +1588,17 @@ Standard scripts checklist:
15751588

15761589
```json
15771590
{
1578-
"ci": "repo-tools ci",
1579-
"check": "repo-tools check",
1580-
"lint": "repo-tools lint",
1581-
"lint:fix": "repo-tools lint --fix",
1582-
"typecheck": "repo-tools typecheck",
1583-
"test": "repo-tools test",
1584-
"test:watch": "repo-tools test --watch",
1585-
"test:coverage": "repo-tools test --coverage",
1586-
"clean": "repo-tools clean"
1591+
"clean": "repo-tools clean",
1592+
"sync": "repo-tools sync",
1593+
"sync-careful": "repo-tools sync-careful",
1594+
"port": "repo-tools port",
1595+
"portclean": "repo-tools portclean",
1596+
"processes": "repo-tools processes",
1597+
"update": "repo-tools update",
1598+
"update-all": "repo-tools update-all",
1599+
"scripts": "repo-tools scripts",
1600+
"ops": "repo-tools ops",
1601+
"menu": "repo-tools menu"
15871602
}
15881603
```
15891604

@@ -1599,15 +1614,16 @@ Standard scripts checklist:
15991614
"private": true,
16001615
"packageManager": "pnpm@10.0.0",
16011616
"scripts": {
1602-
"ci": "repo-tools ci",
1603-
"check": "repo-tools check",
1604-
"lint": "repo-tools lint",
1605-
"lint:fix": "repo-tools lint --fix",
1606-
"typecheck": "repo-tools typecheck",
1607-
"test": "repo-tools test",
1608-
"test:watch": "repo-tools test --watch",
1609-
"test:coverage": "repo-tools test --coverage",
16101617
"clean": "repo-tools clean",
1618+
"sync": "repo-tools sync",
1619+
"sync-careful": "repo-tools sync-careful",
1620+
"port": "repo-tools port",
1621+
"portclean": "repo-tools portclean",
1622+
"processes": "repo-tools processes",
1623+
"update": "repo-tools update",
1624+
"update-all": "repo-tools update-all",
1625+
"scripts": "repo-tools scripts",
1626+
"ops": "repo-tools ops",
16111627
"dev": "vite dev",
16121628
"build": "vite build",
16131629
"start": "vite preview"

0 commit comments

Comments
 (0)