@getstrata/starter 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.
Files changed (3) hide show
  1. package/README.md +2 -0
  2. package/dist/cli.js +135 -3
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -27,3 +27,5 @@ Generated apps contain model classes in `src/models`, named controllers in `src/
27
27
  Follow the generated README to configure the environment, start selected services, install dependencies, migrate, and run the app. Choices are recorded in `strata.layers.json`; the generated file inventory is in `.strata/generator.json`.
28
28
 
29
29
  See the [project README](https://github.com/EyK-26/strata/blob/main/README.md), [starter and layer options](https://github.com/EyK-26/strata/blob/main/docs/STARTER.md), [authentication](https://github.com/EyK-26/strata/blob/main/docs/AUTH.md), [integrations](https://github.com/EyK-26/strata/blob/main/docs/INTEGRATIONS.md), and [production](https://github.com/EyK-26/strata/blob/main/docs/PRODUCTION.md).
30
+
31
+ 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
+ // 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
  // 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.0",
4094
- "@getstrata/cli": "^3.1.0",
4095
- "@getstrata/core": "^3.1.0"
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 }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getstrata/starter",
3
- "version": "3.1.0",
3
+ "version": "3.1.1",
4
4
  "description": "Interactive create-strata wizard. Choose each layer; one database engine.",
5
5
  "type": "module",
6
6
  "license": "MIT",