@gusto/create-baerly-storage 0.3.0 → 0.4.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/dist/index.js +54 -28
- package/dist/index.js.map +1 -1
- package/dist/templates/minimal-cloudflare/AGENTS.md +28 -25
- package/dist/templates/minimal-cloudflare/README.md +24 -21
- package/dist/templates/minimal-cloudflare/package.json +7 -7
- package/dist/templates/minimal-node/.baerly/scaffold.json +1 -1
- package/dist/templates/minimal-node/.env.example +12 -5
- package/dist/templates/minimal-node/AGENTS.md +61 -52
- package/dist/templates/minimal-node/README.md +71 -40
- package/dist/templates/minimal-node/package.json +5 -5
- package/dist/templates/minimal-node/src/server/index.ts +22 -30
- package/dist/templates/minimal-node/src/server/resolve-storage.ts +18 -0
- package/dist/templates/minimal-node/vite.config.ts +0 -2
- package/dist/templates/react-cloudflare/AGENTS.md +31 -27
- package/dist/templates/react-cloudflare/README.md +19 -13
- package/dist/templates/react-cloudflare/index.html +1 -1
- package/dist/templates/react-cloudflare/package.json +11 -11
- package/dist/templates/react-node/.env.example +12 -5
- package/dist/templates/react-node/AGENTS.md +73 -59
- package/dist/templates/react-node/README.md +62 -33
- package/dist/templates/react-node/package.json +9 -9
- package/dist/templates/react-node/src/server/index.ts +18 -29
- package/dist/templates/react-node/src/server/resolve-storage.ts +18 -0
- package/dist/templates/react-node/vite.config.ts +0 -2
- package/package.json +14 -3
package/dist/index.js
CHANGED
|
@@ -381,20 +381,19 @@ const substitutePackageJson = (text, ctx) => {
|
|
|
381
381
|
//#endregion
|
|
382
382
|
//#region src/scaffold.ts
|
|
383
383
|
/**
|
|
384
|
-
* Optional add-ons
|
|
385
|
-
*
|
|
386
|
-
*
|
|
387
|
-
* `--with=<name>` recognised by both the
|
|
384
|
+
* Optional add-ons and compatibility tokens recognised by the CLI.
|
|
385
|
+
* `docker` is a scaffold template overlay; `agent-rules` is the legacy
|
|
386
|
+
* bolt-on `--with` token for the default-on agent-rules writer. Adding
|
|
387
|
+
* a new entry here is what makes `--with=<name>` recognised by both the
|
|
388
|
+
* flag parser and the wizard.
|
|
388
389
|
*
|
|
389
390
|
* - `docker` (scaffold-only, `--target=node`): copies the Dockerfile
|
|
390
391
|
* add-on under `templates/addons/docker/` on top of the scaffolded
|
|
391
392
|
* project.
|
|
392
|
-
* - `agent-rules` (bolt-on
|
|
393
|
-
*
|
|
394
|
-
*
|
|
395
|
-
*
|
|
396
|
-
* for users adopting baerly into a repo that didn't start from a
|
|
397
|
-
* `create-baerly-storage` template.
|
|
393
|
+
* - `agent-rules` (bolt-on compatibility token): the CLI now writes
|
|
394
|
+
* this by default in bolt-on mode and accepts `--no-agent-rules` to
|
|
395
|
+
* opt out. Scaffolded apps already ship the same guidance via the
|
|
396
|
+
* per-template `AGENTS.md`.
|
|
398
397
|
*/
|
|
399
398
|
const KNOWN_ADDONS = ["docker", "agent-rules"];
|
|
400
399
|
/**
|
|
@@ -407,7 +406,7 @@ const KNOWN_ADDONS = ["docker", "agent-rules"];
|
|
|
407
406
|
* `mise.toml` / `.tool-versions` (or any other top-level metadata
|
|
408
407
|
* the user already wrote) coexists with the scaffold.
|
|
409
408
|
*/
|
|
410
|
-
const SCAFFOLD_HERE_ALLOWLIST = new Set([
|
|
409
|
+
const SCAFFOLD_HERE_ALLOWLIST = /* @__PURE__ */ new Set([
|
|
411
410
|
".git",
|
|
412
411
|
".gitignore",
|
|
413
412
|
".gitattributes",
|
|
@@ -450,7 +449,7 @@ const topLevelOutputs = (templateDir, manifest, addonDirs) => {
|
|
|
450
449
|
}
|
|
451
450
|
return out;
|
|
452
451
|
};
|
|
453
|
-
const TEXT_EXTS = new Set([
|
|
452
|
+
const TEXT_EXTS = /* @__PURE__ */ new Set([
|
|
454
453
|
".ts",
|
|
455
454
|
".tsx",
|
|
456
455
|
".js",
|
|
@@ -663,7 +662,15 @@ const scaffold = async (opts) => {
|
|
|
663
662
|
//#endregion
|
|
664
663
|
//#region ../protocol/src/errors.ts
|
|
665
664
|
/**
|
|
666
|
-
*
|
|
665
|
+
* Codes whose default failure class is resolved by retrying with a fresh read.
|
|
666
|
+
* Throw sites may override this when the same code is context-sensitive
|
|
667
|
+
* (notably caller-supplied `_id` collisions, which also use `Conflict`).
|
|
668
|
+
*/
|
|
669
|
+
const RETRIABLE_CODES = /* @__PURE__ */ new Set(["NetworkError", "Conflict"]);
|
|
670
|
+
/** True iff this error code's default failure class is retriable. */
|
|
671
|
+
const isRetriableCode = (code) => RETRIABLE_CODES.has(code);
|
|
672
|
+
/**
|
|
673
|
+
* The single error class thrown by baerly-storage. Discriminate by `code`, not
|
|
667
674
|
* `instanceof`: the code string survives `JSON.stringify` round-trips
|
|
668
675
|
* across Worker / iframe / postMessage realm boundaries, where each
|
|
669
676
|
* realm has its own `BaerlyError` constructor identity. IDB-restored
|
|
@@ -676,7 +683,7 @@ const scaffold = async (opts) => {
|
|
|
676
683
|
* await db.collection("tickets").insert({ title: "hi" });
|
|
677
684
|
* } catch (err) {
|
|
678
685
|
* if (err instanceof BaerlyError && err.code === "Conflict") {
|
|
679
|
-
* //
|
|
686
|
+
* // Check err.retriable; CAS can retry, duplicate _id cannot.
|
|
680
687
|
* }
|
|
681
688
|
* throw err;
|
|
682
689
|
* }
|
|
@@ -706,13 +713,25 @@ var BaerlyError = class extends Error {
|
|
|
706
713
|
* you genuinely need the wire value.
|
|
707
714
|
*/
|
|
708
715
|
status;
|
|
709
|
-
|
|
716
|
+
/** Canonical corrective action; crosses the wire via `HttpErrorEnvelope.error.resolution`. */
|
|
717
|
+
resolution;
|
|
718
|
+
retriableOverride;
|
|
719
|
+
/**
|
|
720
|
+
* Whether this error instance is retriable. Defaults from `code`, but
|
|
721
|
+
* context-sensitive throw sites can override it.
|
|
722
|
+
*/
|
|
723
|
+
get retriable() {
|
|
724
|
+
return this.retriableOverride ?? isRetriableCode(this.code);
|
|
725
|
+
}
|
|
726
|
+
constructor(code, message, cause, issues, status, resolution, retriableOverride) {
|
|
710
727
|
super(message);
|
|
711
728
|
this.name = "BaerlyError";
|
|
712
729
|
this.code = code;
|
|
713
730
|
this.cause = cause;
|
|
731
|
+
this.retriableOverride = retriableOverride;
|
|
714
732
|
if (issues !== void 0) this.issues = issues;
|
|
715
733
|
if (status !== void 0) this.status = status;
|
|
734
|
+
if (resolution !== void 0) this.resolution = resolution;
|
|
716
735
|
}
|
|
717
736
|
};
|
|
718
737
|
//#endregion
|
|
@@ -2128,17 +2147,18 @@ const defaultInstaller = { run: (pm, cwd) => new Promise((resolve, reject) => {
|
|
|
2128
2147
|
//#endregion
|
|
2129
2148
|
//#region src/agent-rules.ts
|
|
2130
2149
|
/**
|
|
2131
|
-
*
|
|
2132
|
-
*
|
|
2150
|
+
* Bolt-on agent-rules writer. The CLI enables this by default for
|
|
2151
|
+
* existing wrangler projects and lets users opt out with
|
|
2152
|
+
* `--no-agent-rules`. It drops a delimited block that tells the user's
|
|
2153
|
+
* AI agent (Claude / Cursor / Copilot) that
|
|
2133
2154
|
* `node_modules/@gusto/baerly-storage/dist/API.md` is the canonical API
|
|
2134
|
-
* surface and that the patterns those agents' training data is
|
|
2135
|
-
*
|
|
2136
|
-
* apply.
|
|
2155
|
+
* surface and that the patterns those agents' training data is densest
|
|
2156
|
+
* with (Postgres/Prisma/Drizzle, Mongo, Firebase) don't apply.
|
|
2137
2157
|
*
|
|
2138
2158
|
* Scaffolded apps already get this via the per-template `AGENTS.md`
|
|
2139
2159
|
* shipped by `scaffold()`. This module is for the bolt-on path —
|
|
2140
|
-
* `pnpm create baerly .` in an existing wrangler
|
|
2141
|
-
* template file is copied.
|
|
2160
|
+
* `pnpm create @gusto/baerly-storage@latest .` in an existing wrangler
|
|
2161
|
+
* project — where no template file is copied.
|
|
2142
2162
|
*
|
|
2143
2163
|
* Target detection (first match wins):
|
|
2144
2164
|
* 1. `.claude/rules/` exists → write `.claude/rules/baerly.md`.
|
|
@@ -2168,6 +2188,8 @@ This repo uses @gusto/baerly-storage. Before writing or modifying storage code:
|
|
|
2168
2188
|
- Read **\`node_modules/@gusto/baerly-storage/dist/API.md\`** — public-API
|
|
2169
2189
|
quickref. Every method, every error code, every example. If a
|
|
2170
2190
|
pattern you want to use is not here, it does not exist in baerly.
|
|
2191
|
+
- Common mistakes keyed by the exact error string live in
|
|
2192
|
+
\`node_modules/@gusto/baerly-storage/dist/RECIPES.md\`.
|
|
2171
2193
|
- Type contracts live in \`node_modules/@gusto/baerly-storage/dist/*.d.ts\`.
|
|
2172
2194
|
The whole API is \`Db\`, \`Collection<T>\`, \`Query<T>\`, and \`Predicate<T>\`.
|
|
2173
2195
|
|
|
@@ -2292,7 +2314,7 @@ const writeAgentRulesBlock = async (outDir) => {
|
|
|
2292
2314
|
* written.
|
|
2293
2315
|
*/
|
|
2294
2316
|
const DEV_SHARED_SECRET = "dev-shared-secret";
|
|
2295
|
-
const GITIGNORE_DEV_VARS_ALIASES = new Set([
|
|
2317
|
+
const GITIGNORE_DEV_VARS_ALIASES = /* @__PURE__ */ new Set([
|
|
2296
2318
|
".dev.vars",
|
|
2297
2319
|
".dev.vars*",
|
|
2298
2320
|
".env*.local",
|
|
@@ -2469,8 +2491,12 @@ const CREATE_BAERLY_ARGS = {
|
|
|
2469
2491
|
},
|
|
2470
2492
|
with: {
|
|
2471
2493
|
type: "string",
|
|
2472
|
-
description: "Comma-separated add-ons. Scaffold mode: \"docker\" (requires --target=node).
|
|
2473
|
-
valueHint: "docker
|
|
2494
|
+
description: "Comma-separated add-ons. Scaffold mode: \"docker\" (requires --target=node). The bolt-on AGENTS.md block is its own default-on flag — see --agent-rules.",
|
|
2495
|
+
valueHint: "docker"
|
|
2496
|
+
},
|
|
2497
|
+
"agent-rules": {
|
|
2498
|
+
type: "boolean",
|
|
2499
|
+
description: "Bolt-on mode: write/refresh the AGENTS.md router pointing at the baerly API (default true; negate with --no-agent-rules). Ignored in scaffold mode."
|
|
2474
2500
|
},
|
|
2475
2501
|
pm: {
|
|
2476
2502
|
type: "string",
|
|
@@ -2574,7 +2600,7 @@ const handleCreateBaerly = async (args, opts = {}) => {
|
|
|
2574
2600
|
json: jsonMode,
|
|
2575
2601
|
isInteractive,
|
|
2576
2602
|
installer: opts.installer,
|
|
2577
|
-
agentRules:
|
|
2603
|
+
agentRules: args["agent-rules"] !== false
|
|
2578
2604
|
});
|
|
2579
2605
|
projectName = w.projectName;
|
|
2580
2606
|
target = w.target;
|
|
@@ -2596,7 +2622,7 @@ const handleCreateBaerly = async (args, opts = {}) => {
|
|
|
2596
2622
|
json: jsonMode,
|
|
2597
2623
|
isInteractive,
|
|
2598
2624
|
installer: opts.installer,
|
|
2599
|
-
agentRules:
|
|
2625
|
+
agentRules: args["agent-rules"] !== false
|
|
2600
2626
|
});
|
|
2601
2627
|
if (args.target === void 0) throw new Error(`--target is required when not running in wizard mode (got undefined)`);
|
|
2602
2628
|
target = args.target;
|
|
@@ -2606,7 +2632,7 @@ const handleCreateBaerly = async (args, opts = {}) => {
|
|
|
2606
2632
|
git = args.git === true;
|
|
2607
2633
|
}
|
|
2608
2634
|
if (withAddons.includes("docker") && target !== "node") throw new Error(`--with=docker only applies to --target=node. The Docker add-on adds a Dockerfile to the Node template. Use --target=node --with=docker, or drop --with=docker to scaffold for --target=${target}.`);
|
|
2609
|
-
if (withAddons.includes("agent-rules")) throw new Error("--with=agent-rules
|
|
2635
|
+
if (withAddons.includes("agent-rules")) throw new Error("--with=agent-rules is unnecessary in scaffold mode. Bolt-on mode writes agent rules by default and supports --no-agent-rules to opt out. Scaffolded apps already include an AGENTS.md preamble — drop --with=agent-rules.");
|
|
2610
2636
|
const result = await scaffold({
|
|
2611
2637
|
projectName,
|
|
2612
2638
|
target,
|