@gusto/create-baerly-storage 0.3.0 → 0.4.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/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 that can be layered on top of a base template
385
- * (`docker`) or on top of an existing wrangler project in bolt-on
386
- * mode (`agent-rules`). Adding a new entry here is what makes
387
- * `--with=<name>` recognised by both the flag parser and the wizard.
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-only): drops a delimited block telling AI
393
- * agents that `node_modules/@gusto/baerly-storage/dist/API.md` is the
394
- * canonical API surface. Scaffolded apps already ship that
395
- * guidance via the per-template `AGENTS.md`; this closes the gap
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
- * The single error class thrown by Baerly. Discriminate by `code`, not
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
- * // ... CAS lost; retry
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
- constructor(code, message, cause, issues, status) {
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
- * The `--with=agent-rules` bolt-on add-on. Drops a delimited block
2132
- * that tells the user's AI agent (Claude / Cursor / Copilot) that
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
- * densest with (Postgres/Prisma/Drizzle, Mongo, Firebase) don't
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 project — where no
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). Bolt-on mode (`create baerly .` in an existing wrangler project): \"agent-rules\" drops an AGENTS.md block pointing at the baerly API surface.",
2473
- valueHint: "docker|agent-rules"
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: withAddonsFromFlag?.includes("agent-rules") === true
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: withAddonsFromFlag?.includes("agent-rules") === true
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 only applies to bolt-on mode (pnpm create baerly . inside an existing wrangler project). Scaffolded apps already include an AGENTS.md preamble — drop --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,