Initial Commit
This commit is contained in:
153
openspec/changes/reorg-cache-payment-categories/proposal.md
Normal file
153
openspec/changes/reorg-cache-payment-categories/proposal.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# OpenSpec Change: reorg-cache-payment-categories
|
||||
|
||||
- **Change ID**: reorg-cache-payment-categories
|
||||
- **Scope**: Monorepo-wide structural change (folder taxonomy)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-19
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Promote two package families to their own top-level domain folders under `packages/<plugin>/`, in line with the domain-first taxonomy established by `2026-04-25-folder-reorg-by-domain`:
|
||||
|
||||
1. Move every `@suaveplan/cache*` package out of `packages/flow/` into a new `packages/cache/` folder.
|
||||
2. Move every `@suaveplan/payment*` package out of `packages/universal/` into a new `packages/payment/` folder.
|
||||
|
||||
No code is rewritten. Moves are `git mv` only; downstream `package.json`/`workspace:^` ranges are unaffected because workspaces are discovered by globbing `packages/*/*`. The only edits after the move are:
|
||||
|
||||
- `scripts/folder-reorg/assignment.yml` — relocate the entries to new plugin sections.
|
||||
- `MANIFEST.md` — regenerated from `assignment.yml` + `workspace:^` graph.
|
||||
- `packages/drive/drive-plugin-cache/README.md` — one stale relative path (`../../flow/cache` → `../../cache/cache`).
|
||||
|
||||
---
|
||||
|
||||
## Motivation
|
||||
|
||||
The taxonomy spec (`openspec/specs/monorepo-structure/spec.md`, established by `2026-04-25-folder-reorg-by-domain`) requires each top-level folder under `packages/` to correspond 1:1 to a plugin in the `suaveplan-skills` marketplace. Two families currently violate that rule:
|
||||
|
||||
### `cache*` is not a `flow` concern
|
||||
|
||||
`packages/flow/` houses control-flow primitives — `cron`, `crdt`, `idempotency`, `job-scheduler`, `queue*`, `retry`, `fsm`. The three cache packages (`cache`, `cache-redis`, `cache-storage`) ended up there historically but are not control-flow; they are a horizontal caching domain consumed by `drive-plugin-cache`, `storage-plugin-cache`, `api-plugin-*`, and future HTTP/CDN layers. Leaving them under `flow/` muddies that folder's identity and makes the `cache` plugin in `suaveplan-skills` unreachable through a single directory.
|
||||
|
||||
The pre-existing `scripts/folder-reorg/assignment.yml` already lists `cache-browser`, `cache-memory`, `cache-redis` under a `storage` plugin section (lines 582-584) — that mapping is out of date with disk reality (on-disk: `cache`, `cache-redis`, `cache-storage` under `flow`). This change consolidates the source of truth: cache is its own plugin, separate from both `flow` and `storage`.
|
||||
|
||||
### `payment*` is not a `universal` concern
|
||||
|
||||
`packages/universal/` was intended as the catch-all for early-genesis universal-tier libraries before the domain split landed. Almost all of its remaining entries are domain-specific (`ab-testing`, `payment`, `payment-providers`, `payment-provider-{stripe,square,paypal,mollie,adyen}`) and should be promoted out. The `2026-04-25-folder-reorg-by-domain` proposal explicitly identifies the `payment` family as one of the cross-tier domains that "should live in one plugin folder" — including future `api-plugin-payment` (already exists), `react-payment`, and `payment-provider-*` adapters.
|
||||
|
||||
`assignment.yml` already lists `payment`, `payment-providers`, `payment-provider-stripe` under `commerce` (lines 151-153). However, the broader payment family (5 provider adapters today, more expected) deserves its own `payment` plugin folder rather than being lumped under commerce alongside `bank`, `banking`, `booking`, `money`, and `currency*`. Splitting `payment` out of `commerce` mirrors how `crypto` and `vault` are separate plugins despite both being "security" by feature.
|
||||
|
||||
### Cost is at its lowest now
|
||||
|
||||
10 package folders move; no source code changes. Every additional `payment-provider-*` adapter or `cache-*` backend shipped under the legacy layout is one more `git mv` later.
|
||||
|
||||
---
|
||||
|
||||
## Design
|
||||
|
||||
### New folder layout
|
||||
|
||||
```
|
||||
packages/
|
||||
├── cache/ # NEW plugin folder
|
||||
│ ├── cache/ # was packages/flow/cache
|
||||
│ ├── cache-redis/ # was packages/flow/cache-redis
|
||||
│ └── cache-storage/ # was packages/flow/cache-storage
|
||||
├── flow/ # cache* removed; cron, crdt, idempotency, job-scheduler, queue*, retry, fsm remain
|
||||
├── payment/ # NEW plugin folder
|
||||
│ ├── payment/ # was packages/universal/payment
|
||||
│ ├── payment-providers/ # was packages/universal/payment-providers
|
||||
│ ├── payment-provider-adyen/ # was packages/universal/payment-provider-adyen
|
||||
│ ├── payment-provider-mollie/ # was packages/universal/payment-provider-mollie
|
||||
│ ├── payment-provider-paypal/ # was packages/universal/payment-provider-paypal
|
||||
│ ├── payment-provider-square/ # was packages/universal/payment-provider-square
|
||||
│ └── payment-provider-stripe/ # was packages/universal/payment-provider-stripe
|
||||
└── universal/ # payment* removed
|
||||
```
|
||||
|
||||
### `assignment.yml` edits
|
||||
|
||||
Remove `cache` from `flow:` section. Remove `cache-browser`, `cache-memory`, `cache-redis` from `storage:` section (stale entries, never matched disk). Add a new `cache:` section:
|
||||
|
||||
```yaml
|
||||
cache:
|
||||
- cache
|
||||
- cache-redis
|
||||
- cache-storage
|
||||
```
|
||||
|
||||
Remove `payment`, `payment-providers`, `payment-provider-stripe` from `commerce:` section. Move them plus the four other on-disk payment providers into a new `payment:` section:
|
||||
|
||||
```yaml
|
||||
payment:
|
||||
- payment
|
||||
- payment-providers
|
||||
- payment-provider-adyen
|
||||
- payment-provider-mollie
|
||||
- payment-provider-paypal
|
||||
- payment-provider-square
|
||||
- payment-provider-stripe
|
||||
```
|
||||
|
||||
### Workspace discovery
|
||||
|
||||
`package.json` declares `"workspaces": { "packages": ["packages/*/*", "docker", "apps/*"] }`. The two new plugin folders match the existing glob — no `package.json` edits required. Bun, Turbo, and Verdaccio publish flow all keep working.
|
||||
|
||||
### What does NOT change
|
||||
|
||||
- No package name changes (`@suaveplan/cache`, `@suaveplan/payment`, etc. stay identical).
|
||||
- No `package.json` edits inside the moved packages.
|
||||
- No source-code changes inside the moved packages.
|
||||
- No `workspace:^` range edits in consumers — package names are unchanged.
|
||||
- No version bumps. All moved packages stay at their current `0.1.0`.
|
||||
- No OpenSpec spec deltas — `openspec/specs/<capability>/spec.md` files reference packages by `@suaveplan/<name>`, not by path.
|
||||
|
||||
### Stale path references to fix after move
|
||||
|
||||
Grep found exactly **one** non-OpenSpec, non-archive file referencing the old paths:
|
||||
|
||||
| File | Current | New |
|
||||
|---|---|---|
|
||||
| `packages/drive/drive-plugin-cache/README.md` line 3 | `../../flow/cache` | `../../cache/cache` |
|
||||
|
||||
Archived OpenSpec proposals (`openspec/archive/**`) and superseded change folders (`openspec/changes/_superseded-*/**`) intentionally retain their original paths as historical record — they are NOT updated. Active spec files under `openspec/specs/<capability>/spec.md` reference packages by name, not path, so no edits needed.
|
||||
|
||||
---
|
||||
|
||||
## Parity Checklist
|
||||
|
||||
| Capability | Before | After | Notes |
|
||||
|---|---|---|---|
|
||||
| `@suaveplan/cache` package builds | ✅ | ✅ | Path-only move; no source change |
|
||||
| `@suaveplan/cache-redis` package builds | ✅ | ✅ | Path-only move |
|
||||
| `@suaveplan/cache-storage` package builds | ✅ | ✅ | Path-only move |
|
||||
| `@suaveplan/payment` package builds | ✅ | ✅ | Path-only move |
|
||||
| `@suaveplan/payment-providers` builds | ✅ | ✅ | Path-only move |
|
||||
| `@suaveplan/payment-provider-{adyen,mollie,paypal,square,stripe}` build | ✅ | ✅ | Path-only move |
|
||||
| `drive-plugin-cache` README relative link | ✅ | ✅ | Updated `../../flow/cache` → `../../cache/cache` |
|
||||
| `MANIFEST.md` matches disk | ✅ | ✅ | Regenerated post-move |
|
||||
| `assignment.yml` matches disk | ⬆️ | ✅ | Enhanced: stale `cache-{browser,memory}` entries dropped, payment family promoted |
|
||||
| Downstream consumer `workspace:^` ranges | ✅ | ✅ | Package names unchanged → ranges unaffected |
|
||||
| Pre-publish gate (`lint typecheck test`) on every moved pkg | ✅ | ✅ | Re-run after move |
|
||||
|
||||
---
|
||||
|
||||
## Risks & mitigations
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| `git mv` of a folder containing `node_modules` symlinks or build artifacts corrupts state | Run from clean working tree (§Pre-flight in tasks); move source-controlled paths only; `bun install` after move to re-link workspace symlinks |
|
||||
| `tsbuildinfo`/`dist`/`coverage` caches go stale | These are gitignored; delete locally before re-running pre-publish gate |
|
||||
| A downstream consumer hard-codes `packages/flow/cache` or `packages/universal/payment` in a build script | Grep already verified zero non-OpenSpec, non-archive references except `drive-plugin-cache/README.md`; that one is fixed in this change |
|
||||
| Turbo cache misses on first run after move | Acceptable one-time cost; cache rebuilds automatically |
|
||||
| Active in-flight OpenSpec change folders reference old paths | Those folders are work-in-progress and will be updated naturally when their owners next touch them; no production code depends on those paths |
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Renaming any package (`@suaveplan/cache` → `@suaveplan/cache-core`, etc.) — not requested, would break consumers.
|
||||
- Adding new cache or payment packages — separate proposals.
|
||||
- Touching `flow/` or `universal/` residents that are NOT cache or payment — separate cleanup, separate proposal.
|
||||
- Updating archived OpenSpec proposals or superseded change folders — those are historical record.
|
||||
79
openspec/changes/reorg-cache-payment-categories/tasks.md
Normal file
79
openspec/changes/reorg-cache-payment-categories/tasks.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# Tasks: reorg-cache-payment-categories
|
||||
|
||||
**Change ID**: reorg-cache-payment-categories
|
||||
**Scope**: Folder taxonomy move (no source code edits inside moved packages)
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Pre-flight
|
||||
|
||||
- [ ] 1.1 Confirm clean working tree: `git status` reports no unstaged changes outside this proposal directory (uncommitted edits in `STATUS.md`, `packages/react/react-audio/**` are an in-flight unrelated branch — they remain untouched).
|
||||
- [ ] 1.2 Confirm no in-flight worktrees with uncommitted work on `packages/flow/cache*` or `packages/universal/payment*`: `git worktree list` then `git status` in each.
|
||||
- [ ] 1.3 Snapshot current Verdaccio state for moved packages: `bun scripts/list-published.ts` (or `npm view @suaveplan/cache versions` x10). All moved packages stay at `0.1.0` — no republish.
|
||||
|
||||
## 2. Cache family move
|
||||
|
||||
- [ ] 2.1 `mkdir -p packages/cache`
|
||||
- [ ] 2.2 `git mv packages/flow/cache packages/cache/cache`
|
||||
- [ ] 2.3 `git mv packages/flow/cache-redis packages/cache/cache-redis`
|
||||
- [ ] 2.4 `git mv packages/flow/cache-storage packages/cache/cache-storage`
|
||||
- [ ] 2.5 Verify directory empty of cache packages: `ls packages/flow/ | grep -i cache` → no output.
|
||||
- [ ] 2.6 Verify all three new locations exist with `package.json`, `src/`, `tests/`.
|
||||
|
||||
## 3. Payment family move
|
||||
|
||||
- [ ] 3.1 `mkdir -p packages/payment`
|
||||
- [ ] 3.2 `git mv packages/universal/payment packages/payment/payment`
|
||||
- [ ] 3.3 `git mv packages/universal/payment-providers packages/payment/payment-providers`
|
||||
- [ ] 3.4 `git mv packages/universal/payment-provider-adyen packages/payment/payment-provider-adyen`
|
||||
- [ ] 3.5 `git mv packages/universal/payment-provider-mollie packages/payment/payment-provider-mollie`
|
||||
- [ ] 3.6 `git mv packages/universal/payment-provider-paypal packages/payment/payment-provider-paypal`
|
||||
- [ ] 3.7 `git mv packages/universal/payment-provider-square packages/payment/payment-provider-square`
|
||||
- [ ] 3.8 `git mv packages/universal/payment-provider-stripe packages/payment/payment-provider-stripe`
|
||||
- [ ] 3.9 Verify `ls packages/universal/ | grep -i payment` → no output.
|
||||
- [ ] 3.10 Verify all seven new locations exist with `package.json`, `src/`, `tests/`.
|
||||
|
||||
## 4. Update `assignment.yml`
|
||||
|
||||
- [ ] 4.1 In `scripts/folder-reorg/assignment.yml`, remove `- cache` from `flow:` section.
|
||||
- [ ] 4.2 Remove `- cache-browser`, `- cache-memory`, `- cache-redis` from `storage:` section (stale entries; never matched disk).
|
||||
- [ ] 4.3 Add new top-level section `cache:` with `cache`, `cache-redis`, `cache-storage`.
|
||||
- [ ] 4.4 Remove `- payment`, `- payment-providers`, `- payment-provider-stripe` from `commerce:` section.
|
||||
- [ ] 4.5 Add new top-level section `payment:` with `payment`, `payment-providers`, `payment-provider-adyen`, `payment-provider-mollie`, `payment-provider-paypal`, `payment-provider-square`, `payment-provider-stripe`.
|
||||
- [ ] 4.6 Verify yaml parses: `bun -e "import yaml from 'yaml'; console.log(Object.keys(yaml.parse(await Bun.file('scripts/folder-reorg/assignment.yml').text())))"`.
|
||||
|
||||
## 5. Fix stale path references
|
||||
|
||||
- [ ] 5.1 Edit `packages/drive/drive-plugin-cache/README.md` line 3: replace `../../flow/cache` with `../../cache/cache`.
|
||||
- [ ] 5.2 Re-grep to confirm zero remaining non-archive references: `grep -rln -E "flow/cache|universal/payment" --include="*.ts" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.md" | grep -v "node_modules\|dist\|coverage\|\.tsbuildinfo\|openspec/archive\|openspec/changes"` → empty.
|
||||
|
||||
## 6. Regenerate manifest & re-link workspaces
|
||||
|
||||
- [ ] 6.1 `bun scripts/folder-reorg/generate-manifest.ts` — overwrites `MANIFEST.md`.
|
||||
- [ ] 6.2 Diff `MANIFEST.md`: every moved package's plugin column changes from `flow`/`universal` to `cache`/`payment`. No other rows change.
|
||||
- [ ] 6.3 `bun install` to refresh workspace symlinks under each consumer's `node_modules/@suaveplan/`.
|
||||
|
||||
## 7. Verification gate
|
||||
|
||||
- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/cache` green.
|
||||
- [ ] 7.2 `bunx turbo lint typecheck test --filter=@suaveplan/cache-redis` green.
|
||||
- [ ] 7.3 `bunx turbo lint typecheck test --filter=@suaveplan/cache-storage` green.
|
||||
- [ ] 7.4 `bunx turbo lint typecheck test --filter=@suaveplan/payment` green.
|
||||
- [ ] 7.5 `bunx turbo lint typecheck test --filter=@suaveplan/payment-providers` green.
|
||||
- [ ] 7.6 `bunx turbo lint typecheck test --filter=@suaveplan/payment-provider-adyen` green.
|
||||
- [ ] 7.7 `bunx turbo lint typecheck test --filter=@suaveplan/payment-provider-mollie` green.
|
||||
- [ ] 7.8 `bunx turbo lint typecheck test --filter=@suaveplan/payment-provider-paypal` green.
|
||||
- [ ] 7.9 `bunx turbo lint typecheck test --filter=@suaveplan/payment-provider-square` green.
|
||||
- [ ] 7.10 `bunx turbo lint typecheck test --filter=@suaveplan/payment-provider-stripe` green.
|
||||
- [ ] 7.11 `bunx turbo lint typecheck test --filter=@suaveplan/drive-plugin-cache` green (verifies README link fix did not introduce ts/lint regression).
|
||||
|
||||
## 8. Archive
|
||||
|
||||
- [ ] 8.1 No spec deltas — `openspec/specs/<capability>/spec.md` references packages by name, not path. Skip fold-in.
|
||||
- [ ] 8.2 Move `openspec/changes/reorg-cache-payment-categories/` → `openspec/archive/2026-05-19-reorg-cache-payment-categories/` post-merge.
|
||||
Reference in New Issue
Block a user