@constructive-io/seeder 0.5.0

package/README.md

@@ -0,0 +1,90 @@
+# @constructive-io/seeder
+
+Provision Constructive databases from schema blueprints and seed reusable datasets.
+
+## Install
+
+```bash
+npm install @constructive-io/seeder
+```
+
+## CLI
+
+```bash
+# Provision a new database, apply schema, then seed rows
+constructive-seeder full \
+  --blueprint marketplace \
+  --dataset marketplace-demo \
+  --email user@example.com \
+  --password '***'
+
+# Provision schema only
+constructive-seeder schema \
+  --blueprint logistics \
+  --email user@example.com \
+  --password '***'
+
+# Seed rows into an existing app database
+constructive-seeder rows \
+  --dataset crm-demo \
+  --data-endpoint http://app-public-mydb.localhost:3000/graphql \
+  --auth-endpoint http://auth-mydb.localhost:3000/graphql \
+  --email user@example.com \
+  --password '***'
+
+# Discover available blueprints and datasets
+constructive-seeder list
+
+# Use an external schema blueprint
+constructive-seeder schema \
+  --blueprint-file ./blueprint.json \
+  --email user@example.com \
+  --password '***'
+
+# Use external runtime-generated specs
+constructive-seeder full \
+  --blueprint-file ./blueprint.json \
+  --dataset-file ./dataset.mjs \
+  --email user@example.com \
+  --password '***'
+```
+
+Run `constructive-seeder help` for the full command reference.
+
+## Programmatic API
+
+```ts
+import { getBlueprint, getDataset, parseCliArgs, runSeeder } from '@constructive-io/seeder';
+
+const blueprint = getBlueprint('marketplace');
+const dataset = getDataset('marketplace-demo');
+
+await runSeeder(
+  parseCliArgs([
+    'node',
+    'constructive-seeder',
+    'full',
+    '--blueprint',
+    blueprint.name,
+    '--dataset',
+    dataset.name,
+  ]),
+);
+```
+
+## Model
+
+- `blueprint`: schema only
+- `dataset`: row generation only
+
+That split is intentional. Schema provisioning and row seeding are separate public concepts.
+
+## Notes
+
+- Schema provisioning aligns to the admin app's secure table / relation provisioning flow.
+- `rows` mode is strict: it requires both `--data-endpoint` and `--auth-endpoint`.
+- The package exports both a CLI (`constructive-seeder`) and a library entrypoint.
+- External blueprints are validated before execution.
+- External blueprint files can be JSON or JS modules.
+- External datasets must be JS modules because seed nodes require functions.
+- A dataset module may optionally export both `dataset` and `blueprint`, which is useful for AI-generated one-off specs.