@constructive-io/seeder 0.5.0
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 +90 -0
- package/SEED_GUIDE.md +1925 -0
- package/SEED_USAGE.md +135 -0
- package/dist/bin.js +21860 -0
- package/dist/bin.js.map +1 -0
- package/dist/index.cjs +21939 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +16196 -0
- package/dist/index.d.ts +16196 -0
- package/dist/index.js +21876 -0
- package/dist/index.js.map +1 -0
- package/package.json +83 -0
package/SEED_USAGE.md
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Seeder Usage
|
|
2
|
+
|
|
3
|
+
`@constructive-io/seeder` has two first-class concepts:
|
|
4
|
+
|
|
5
|
+
- `blueprint`: schema shape only
|
|
6
|
+
- `dataset`: row generation plan only
|
|
7
|
+
|
|
8
|
+
The CLI exposes them explicitly.
|
|
9
|
+
|
|
10
|
+
## Commands
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
# Provision a new database, apply schema, then seed rows
|
|
14
|
+
pnpm seed --email=user@example.com --password=pass
|
|
15
|
+
pnpm --filter @constructive-io/seeder exec constructive-seeder full \
|
|
16
|
+
--blueprint marketplace \
|
|
17
|
+
--dataset marketplace-demo \
|
|
18
|
+
--size sm
|
|
19
|
+
|
|
20
|
+
# Provision schema only
|
|
21
|
+
pnpm --filter @constructive-io/seeder exec constructive-seeder schema \
|
|
22
|
+
--blueprint logistics \
|
|
23
|
+
--email=user@example.com \
|
|
24
|
+
--password=pass
|
|
25
|
+
|
|
26
|
+
# Seed rows into an existing database
|
|
27
|
+
pnpm --filter @constructive-io/seeder exec constructive-seeder rows \
|
|
28
|
+
--dataset crm-demo \
|
|
29
|
+
--data-endpoint http://app-public-mydb.localhost:3000/graphql \
|
|
30
|
+
--auth-endpoint http://auth-mydb.localhost:3000/graphql \
|
|
31
|
+
--email=user@example.com \
|
|
32
|
+
--password=pass
|
|
33
|
+
|
|
34
|
+
# Discover available assets
|
|
35
|
+
pnpm --filter @constructive-io/seeder exec constructive-seeder list
|
|
36
|
+
pnpm --filter @constructive-io/seeder exec constructive-seeder list blueprints
|
|
37
|
+
pnpm --filter @constructive-io/seeder exec constructive-seeder list datasets
|
|
38
|
+
|
|
39
|
+
# Provision from an external schema blueprint file
|
|
40
|
+
node packages/seeder/dist/bin.js schema \
|
|
41
|
+
--blueprint-file ./blueprint.json \
|
|
42
|
+
--email=user@example.com \
|
|
43
|
+
--password=pass
|
|
44
|
+
|
|
45
|
+
# Provision + seed from external runtime specs
|
|
46
|
+
node packages/seeder/dist/bin.js full \
|
|
47
|
+
--blueprint-file ./blueprint.json \
|
|
48
|
+
--dataset-file ./dataset.mjs \
|
|
49
|
+
--email=user@example.com \
|
|
50
|
+
--password=pass
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Flags
|
|
54
|
+
|
|
55
|
+
| Flag | Applies To | Description |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| `--blueprint` | `full`, `schema` | Schema blueprint to provision |
|
|
58
|
+
| `--blueprint-file` | `full`, `schema`, `rows` | Load schema blueprint from JSON or JS module |
|
|
59
|
+
| `--dataset` | `full`, `rows` | Dataset to seed |
|
|
60
|
+
| `--dataset-file` | `full`, `rows` | Load dataset from JS module |
|
|
61
|
+
| `--size` | `full`, `rows` | Dataset size preset: `sm`, `md`, `lg` |
|
|
62
|
+
| `--endpoint` | `full`, `schema` | Schema-builder GraphQL endpoint |
|
|
63
|
+
| `--data-endpoint` | `rows` | App-public GraphQL endpoint |
|
|
64
|
+
| `--auth-endpoint` | `rows` | Auth GraphQL endpoint |
|
|
65
|
+
| `--domain` | `full`, `schema` | Base domain for provisioned database |
|
|
66
|
+
| `--subdomain` | `full`, `schema` | Explicit database subdomain |
|
|
67
|
+
| `--database-name` | `full`, `schema` | Explicit database name |
|
|
68
|
+
| `--seed-id` | `full`, `schema` | Stable suffix for generated names |
|
|
69
|
+
| `--email` | all mutating commands | Login email |
|
|
70
|
+
| `--password` | all mutating commands | Login password |
|
|
71
|
+
| `--verbose` | all mutating commands | Extra logs |
|
|
72
|
+
| `--dry-run` | all mutating commands | Print intent and skip mutations |
|
|
73
|
+
|
|
74
|
+
## Runtime model
|
|
75
|
+
|
|
76
|
+
`full`
|
|
77
|
+
1. Authenticate against schema builder.
|
|
78
|
+
2. Provision a database with `databaseProvisionModule`.
|
|
79
|
+
3. Resolve canonical topology.
|
|
80
|
+
4. Apply the schema blueprint with `secureTableProvision` and `relationProvision`.
|
|
81
|
+
5. Wait for `_meta` visibility.
|
|
82
|
+
6. Seed the dataset into the app-public endpoint.
|
|
83
|
+
|
|
84
|
+
`schema`
|
|
85
|
+
1. Authenticate against schema builder.
|
|
86
|
+
2. Provision a database.
|
|
87
|
+
3. Apply only the schema blueprint.
|
|
88
|
+
|
|
89
|
+
`rows`
|
|
90
|
+
1. Authenticate against the provided auth endpoint.
|
|
91
|
+
2. Verify the dataset's blueprint tables exist on the provided data endpoint.
|
|
92
|
+
3. Seed the dataset into the existing database.
|
|
93
|
+
|
|
94
|
+
## Package structure
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
src/
|
|
98
|
+
├── blueprints/ # schema only
|
|
99
|
+
├── datasets/ # row plans only
|
|
100
|
+
├── tables.ts # admin-aligned provisioning
|
|
101
|
+
├── seed-engine.ts
|
|
102
|
+
└── bin.ts
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## External spec validation
|
|
106
|
+
|
|
107
|
+
External blueprints and datasets are validated before execution.
|
|
108
|
+
|
|
109
|
+
- Blueprint files:
|
|
110
|
+
- supported: `.json`, `.js`, `.mjs`, `.cjs`
|
|
111
|
+
- must resolve to `{ name, description, schema: { tables: [...] } }`
|
|
112
|
+
- Dataset files:
|
|
113
|
+
- supported: `.js`, `.mjs`, `.cjs`
|
|
114
|
+
- must resolve to `{ name, description, blueprint, presets, seedPlan }`
|
|
115
|
+
- `seedPlan[].generate` must be a function, so JSON datasets are intentionally rejected
|
|
116
|
+
- Dataset modules may also export `blueprint` alongside `dataset`
|
|
117
|
+
- that allows one runtime module to carry both definitions for custom AI-generated runs
|
|
118
|
+
|
|
119
|
+
## Current assets
|
|
120
|
+
|
|
121
|
+
Blueprints:
|
|
122
|
+
- `marketplace`
|
|
123
|
+
- `blog`
|
|
124
|
+
- `saas`
|
|
125
|
+
- `crm`
|
|
126
|
+
- `peptides`
|
|
127
|
+
- `logistics`
|
|
128
|
+
|
|
129
|
+
Datasets:
|
|
130
|
+
- `marketplace-demo`
|
|
131
|
+
- `blog-demo`
|
|
132
|
+
- `saas-demo`
|
|
133
|
+
- `crm-demo`
|
|
134
|
+
- `peptides-demo`
|
|
135
|
+
- `logistics-demo`
|