create-strata 3.1.0 → 3.1.1
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 +2 -0
- package/dist/cli.js +135 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -43,3 +43,5 @@ The generator installs the application-local `strata` CLI. Run the generated `bu
|
|
|
43
43
|
`create-strata` and [`@getstrata/starter`](https://www.npmjs.com/package/@getstrata/starter) provide the same generator.
|
|
44
44
|
|
|
45
45
|
See the [project README](https://github.com/EyK-26/strata/blob/main/README.md), [starter guide](https://github.com/EyK-26/strata/blob/main/docs/STARTER.md), [authentication guide](https://github.com/EyK-26/strata/blob/main/docs/AUTH.md), and [integration guide](https://github.com/EyK-26/strata/blob/main/docs/INTEGRATIONS.md).
|
|
46
|
+
|
|
47
|
+
Generated apps include an `AGENTS.md` tailored to their selected stack, with application feature workflows and validation guidance for AI coding agents.
|
package/dist/cli.js
CHANGED
|
@@ -388,6 +388,7 @@ function compileStarterFeatures(input, reference) {
|
|
|
388
388
|
browserTransport: cookie ? "cookie" : layers.auth
|
|
389
389
|
});
|
|
390
390
|
const artifacts = [
|
|
391
|
+
"AGENTS.md",
|
|
391
392
|
"package.json",
|
|
392
393
|
"src/bootstrap/createApp.ts",
|
|
393
394
|
"src/routes/api.ts",
|
|
@@ -1397,6 +1398,133 @@ async function resolveStarterPlan(flags, injected) {
|
|
|
1397
1398
|
}
|
|
1398
1399
|
}
|
|
1399
1400
|
|
|
1401
|
+
// ../strata-starter/src/renderAgentInstructions.ts
|
|
1402
|
+
function renderAgentInstructions(projectName, plan) {
|
|
1403
|
+
const { layers, decisions, services } = plan;
|
|
1404
|
+
const extras = Object.entries(layers.extras).filter(([, enabled]) => enabled).map(([name]) => name).sort();
|
|
1405
|
+
return `# Building ${projectName}
|
|
1406
|
+
|
|
1407
|
+
This is an application built with Strata, TypeScript and Bun. Build product features
|
|
1408
|
+
in this app using the installed public APIs; do not recreate framework internals or
|
|
1409
|
+
edit node_modules. Follow Laravel-style organization where it fits TypeScript.
|
|
1410
|
+
|
|
1411
|
+
## Start here
|
|
1412
|
+
|
|
1413
|
+
Read README.md, package.json and the files involved in the feature. Installed package
|
|
1414
|
+
versions and current application code take precedence over generic examples. Runtime
|
|
1415
|
+
choices live in src/config/app.ts and environment configuration. strata.layers.json
|
|
1416
|
+
records generation choices; editing it does not reconfigure the application.
|
|
1417
|
+
Update this guide when the app's structure or stack changes. Do not print secrets
|
|
1418
|
+
from .env or commit credentials.
|
|
1419
|
+
|
|
1420
|
+
Starting stack: frontend=${layers.frontend}; database=${layers.database}; auth=${layers.auth};
|
|
1421
|
+
tenancy=${layers.tenancy}; cache=${layers.cache}; queue=${layers.queue}; mail=${layers.mail}.
|
|
1422
|
+
Selected extras: ${extras.join(", ") || "none"}.
|
|
1423
|
+
|
|
1424
|
+
## Where features belong
|
|
1425
|
+
|
|
1426
|
+
- src/routes/api.ts and src/routes/web.ts: endpoints and their middleware.
|
|
1427
|
+
- src/http/controllers/: named actions; create a controller when needed.
|
|
1428
|
+
- src/http/requests/: input validation and request authorization when needed.
|
|
1429
|
+
- src/policies/: resource access rules when needed.
|
|
1430
|
+
- src/models/: model classes; add new classes to src/models/register.ts.
|
|
1431
|
+
- src/db/migrations/: explicit schema changes, separate from model declarations.
|
|
1432
|
+
- src/config/app.ts and src/bootstrap/: configuration and dependency composition.
|
|
1433
|
+
${decisions.serverViews || decisions.mfaViews ? `- views/: Eta templates; use the existing view rendering and escaping helpers.
|
|
1434
|
+
` : ""}${decisions.frontendBuild ? `- frontend/: React UI built by Bun; preserve the configured SPA prefix (${layers.spaPrefix}).
|
|
1435
|
+
` : ""}
|
|
1436
|
+
Optional folders need not exist until their first feature is added. Larger domains
|
|
1437
|
+
may use modules; ordinary CRUD needs no module, forwarding service or repository layer.
|
|
1438
|
+
|
|
1439
|
+
## Add a feature
|
|
1440
|
+
|
|
1441
|
+
Use the local CLI from this directory; inspect each command's help before guessing flags:
|
|
1442
|
+
|
|
1443
|
+
\`\`\`sh
|
|
1444
|
+
bunx strata make:model Product
|
|
1445
|
+
bunx strata make:migration create_products
|
|
1446
|
+
bunx strata make:controller ProductController
|
|
1447
|
+
bunx strata make:request StoreProductRequest
|
|
1448
|
+
bunx strata make:policy ProductPolicy
|
|
1449
|
+
\`\`\`
|
|
1450
|
+
|
|
1451
|
+
1. Declare model fields once with defineModel and field from
|
|
1452
|
+
@getstrata/core/database/model. Infer row types with ModelAttributes when needed.
|
|
1453
|
+
Put relationships on the model class, for example
|
|
1454
|
+
category() { return this.belongsTo(Category, "category_id"); }.
|
|
1455
|
+
Register both model classes. Ordinary models need no separate XxxRepository.
|
|
1456
|
+
2. Implement a new migration for the actual table/columns/indexes. Model declarations
|
|
1457
|
+
do not change the database. Keep applied migrations intact.
|
|
1458
|
+
3. Validate input in a request and authorize the operation/resource. A fillable list
|
|
1459
|
+
is not authorization. Derive identity/ownership values from trusted context.
|
|
1460
|
+
4. Put application behavior in the controller or a service that adds real domain
|
|
1461
|
+
behavior. Register routes through the existing kernel/middleware composition.
|
|
1462
|
+
5. Query through database.model(Product), or transaction.model(Product) inside its
|
|
1463
|
+
transaction. Never cache a request session, identity or bound model in a singleton.
|
|
1464
|
+
Keep after-commit effects inside the existing transaction-aware workflow.
|
|
1465
|
+
6. Add focused tests for successful, denied and invalid operations. Check persisted
|
|
1466
|
+
outcomes and rollback when a feature changes data.
|
|
1467
|
+
|
|
1468
|
+
Use @getstrata/core/... and @getstrata/bootstrap/... public subpaths. Inspect installed
|
|
1469
|
+
types and neighboring app code before inventing an API. Pass narrow dependencies to
|
|
1470
|
+
controllers; do not pass the whole container. Prefer native Bun HTTP, SQL, streaming
|
|
1471
|
+
and image capabilities through Strata's APIs instead of adding duplicate frameworks.
|
|
1472
|
+
|
|
1473
|
+
## Access and the selected stack
|
|
1474
|
+
|
|
1475
|
+
${layers.auth === "headers" ? `Development header auth is selected. It is not a production login mechanism; adopt an appropriate real guard before exposing private data.
|
|
1476
|
+
` : `Keep the generated authentication and account-state checks. Authentication, abilities and resource policies are separate checks; do not bypass them in a new endpoint.
|
|
1477
|
+
`}${decisions.cookie ? `Preserve the existing cookie/CSRF handshake and server-side session handling. Do not store session credentials in browser storage or mint cookies in controllers.
|
|
1478
|
+
` : ""}${decisions.token || decisions.jwt ? `Preserve bearer-token/JWT verification and expiry. Do not persist bearer credentials in localStorage or sessionStorage, or treat unverified claims as identity.
|
|
1479
|
+
` : ""}${decisions.rls ? `PostgreSQL RLS is selected. Keep runtime access on the restricted app role and tenant policy inside the owned transaction; administrative migration credentials never belong in request handlers.
|
|
1480
|
+
` : decisions.tenantTable ? `Column tenancy is selected. Explicitly filter tenant-owned reads and writes using the trusted current tenant; a tenant_id column alone does not isolate records.
|
|
1481
|
+
` : `No tenancy is selected. Do not invent tenant fields or middleware without adding the corresponding schema and application policy.
|
|
1482
|
+
`}${layers.database === "sqlite" ? `SQLite is selected. Use its configured file and portable schema/query APIs; do not assume PostgreSQL RLS or full-text operators are available.
|
|
1483
|
+
` : ""}${decisions.redisQueue ? `Redis queued work needs a separate bun run queue:work process. Make job effects idempotent and preserve retry/cancellation semantics.
|
|
1484
|
+
` : `The queue is synchronous; HTTP startup does not create a background queue worker.
|
|
1485
|
+
`}Only run bun run outbox:work when this application uses SQL durable listeners.
|
|
1486
|
+
${layers.mail === "log" ? `Mail is logged locally; configure an actual mail transport before relying on delivered account emails.
|
|
1487
|
+
` : `SMTP is selected; use the configured transport and preserve failure/retry handling without logging credentials.
|
|
1488
|
+
`}
|
|
1489
|
+
## Commands and validation
|
|
1490
|
+
|
|
1491
|
+
Use the Bun version in .bun-version. Follow README.md for environment setup and
|
|
1492
|
+
${services.docker.length ? `selected Docker services (${services.docker.join(", ")}).` : services.local.length ? `local services (${services.local.join(", ")}).` : "local startup; this selection needs no supporting service containers."}
|
|
1493
|
+
|
|
1494
|
+
\`\`\`sh
|
|
1495
|
+
bun install
|
|
1496
|
+
bun run check
|
|
1497
|
+
bun run db:migrate
|
|
1498
|
+
bun run dev
|
|
1499
|
+
${decisions.frontendBuild ? `bun run frontend:install
|
|
1500
|
+
bun run frontend:build
|
|
1501
|
+
` : ""}\`\`\`
|
|
1502
|
+
|
|
1503
|
+
Run migrations against the intended development database after reviewing the changes.
|
|
1504
|
+
db:fresh is destructive; never use it on shared or production data. Demo seeds are
|
|
1505
|
+
development-only. Use disposable test data. Run existing focused tests with bun test
|
|
1506
|
+
when present; do not assume this app defines test, lint or framework-monorepo scripts.
|
|
1507
|
+
Inspect package.json for additional commands and add application tests where needed.
|
|
1508
|
+
|
|
1509
|
+
Keep changes small and inspect the diff. Avoid reading unrelated files or repeatedly
|
|
1510
|
+
running full suites. Recheck affected behavior after edits; report what ran and what
|
|
1511
|
+
remains unverified. Do not replace a failed check with a weaker assertion. Keep new
|
|
1512
|
+
dependencies, public APIs and infrastructure proportional to the product requirement.
|
|
1513
|
+
|
|
1514
|
+
## Framework reference
|
|
1515
|
+
|
|
1516
|
+
- [Application workflow](https://github.com/EyK-26/strata/blob/main/docs/BUILDING-APPS.md)
|
|
1517
|
+
- [Models and migrations](https://github.com/EyK-26/strata/blob/main/docs/DATABASE.md)
|
|
1518
|
+
- [Authentication](https://github.com/EyK-26/strata/blob/main/docs/AUTH.md)
|
|
1519
|
+
- [Tenancy](https://github.com/EyK-26/strata/blob/main/docs/TENANCY.md)
|
|
1520
|
+
- [Uploads and images](https://github.com/EyK-26/strata/blob/main/docs/MEDIA.md)
|
|
1521
|
+
|
|
1522
|
+
Documentation on main may be newer than the installed release. Keep this app's
|
|
1523
|
+
versions and public type contracts authoritative. Adding a feature should not require
|
|
1524
|
+
studying Strata's contributor workspace or changing framework package versions.
|
|
1525
|
+
`;
|
|
1526
|
+
}
|
|
1527
|
+
|
|
1400
1528
|
// ../strata-starter/src/controllerActions.ts
|
|
1401
1529
|
class ControllerActions {
|
|
1402
1530
|
className;
|
|
@@ -3562,6 +3690,9 @@ function renderReadme(projectName, plan, options = {}) {
|
|
|
3562
3690
|
const neededTools = plan.services.required;
|
|
3563
3691
|
const dockerLabel = neededTools.length === 0 ? "not needed" : dockerServices.length > 0 ? dockerServices.join(", ") : "off (local installs)";
|
|
3564
3692
|
return `${renderReadmeIntro(projectName, options)}
|
|
3693
|
+
AI coding agents: read [AGENTS.md](AGENTS.md) for this application's structure,
|
|
3694
|
+
selected stack, feature workflow and validation commands. Keep it current as the app evolves.
|
|
3695
|
+
|
|
3565
3696
|
## Layers
|
|
3566
3697
|
|
|
3567
3698
|
| Layer | Choice |
|
|
@@ -4090,9 +4221,9 @@ function renderPackageJson(projectName, options = {}) {
|
|
|
4090
4221
|
"@getstrata/cli": "workspace:*",
|
|
4091
4222
|
"@getstrata/core": "workspace:*"
|
|
4092
4223
|
} : {
|
|
4093
|
-
"@getstrata/bootstrap": "^3.1.
|
|
4094
|
-
"@getstrata/cli": "^3.1.
|
|
4095
|
-
"@getstrata/core": "^3.1.
|
|
4224
|
+
"@getstrata/bootstrap": "^3.1.1",
|
|
4225
|
+
"@getstrata/cli": "^3.1.1",
|
|
4226
|
+
"@getstrata/core": "^3.1.1"
|
|
4096
4227
|
};
|
|
4097
4228
|
if (!options.plan || options.plan.decisions.serverViews || options.plan.decisions.mfaViews)
|
|
4098
4229
|
coreDeps.eta = "^4.6.0";
|
|
@@ -5934,6 +6065,7 @@ export const TENANCY_ENABLED = ${decisions.tenantTable};
|
|
|
5934
6065
|
}
|
|
5935
6066
|
writeText(join2(targetDir, ".bun-version"), `1.4.4
|
|
5936
6067
|
`);
|
|
6068
|
+
writeText(join2(targetDir, "AGENTS.md"), renderAgentInstructions(projectName, plan));
|
|
5937
6069
|
writeText(join2(targetDir, ".env.example"), renderEnvExample(projectName, plan));
|
|
5938
6070
|
writeText(join2(targetDir, ".gitignore"), renderGitignore());
|
|
5939
6071
|
writeText(join2(targetDir, "package.json"), renderPackageJson(projectName, { ...options, plan }));
|