@marktiderman/genesis-cli 1.23.0 → 1.25.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
@@ -821,9 +821,9 @@ async function runScaffold(opts, fs) {
821
821
  function joinPath(...parts) {
822
822
  return parts.filter(Boolean).join("/").replace(/\/+/g, "/");
823
823
  }
824
- function dirname(path48) {
825
- const idx = path48.lastIndexOf("/");
826
- return idx === -1 ? "." : path48.slice(0, idx);
824
+ function dirname(path49) {
825
+ const idx = path49.lastIndexOf("/");
826
+ return idx === -1 ? "." : path49.slice(0, idx);
827
827
  }
828
828
  function brandPackageJson(consumer, genesisVersion) {
829
829
  return JSON.stringify(
@@ -1081,8 +1081,8 @@ function routeTags(source) {
1081
1081
  var GUARD = /<((?:[A-Z]\w*)?(?:Admin|Staff)\w*(?:Guard|Route|Only)|RequireAdmin|RequireStaff)>/;
1082
1082
  function wireStudioRoute(source, route, pageImportPath) {
1083
1083
  const tags = routeTags(source);
1084
- const relative13 = route.replace(/^\//, "");
1085
- const existing = tags.find((t) => new RegExp(`path=["'](/?${relative13.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})["']`).test(t.text));
1084
+ const relative14 = route.replace(/^\//, "");
1085
+ const existing = tags.find((t) => new RegExp(`path=["'](/?${relative14.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})["']`).test(t.text));
1086
1086
  if (existing) {
1087
1087
  return { skipped: `Your router already has a page at ${route}. Replace its element with <DataStudioPage /> to use the studio there.` };
1088
1088
  }
@@ -1090,17 +1090,17 @@ function wireStudioRoute(source, route, pageImportPath) {
1090
1090
  const roots = layouts.length ? layouts : tags.filter((t) => !t.selfClosing && t.close !== void 0 && /path=["']\/["']/.test(t.text));
1091
1091
  if (roots.length !== 1) {
1092
1092
  return {
1093
- skipped: roots.length === 0 ? `No layout route found to put the page under. Add <Route path="${route}" element={<DataStudioPage />} /> where your app's other pages are.` : `More than one layout route; add <Route path="${relative13}" element={<DataStudioPage />} /> inside the one your other admin pages use.`
1093
+ skipped: roots.length === 0 ? `No layout route found to put the page under. Add <Route path="${route}" element={<DataStudioPage />} /> where your app's other pages are.` : `More than one layout route; add <Route path="${relative14}" element={<DataStudioPage />} /> inside the one your other admin pages use.`
1094
1094
  };
1095
1095
  }
1096
1096
  const layout = roots[0];
1097
1097
  const base = (/\bpath=["']([^"']*)["']/.exec(layout.text)?.[1] ?? "").replace(/^\/+|\/+$/g, "");
1098
- if (base && !relative13.startsWith(`${base}/`)) {
1098
+ if (base && !relative14.startsWith(`${base}/`)) {
1099
1099
  return {
1100
1100
  skipped: `Your layout route lives at /${base}, outside ${route}. Add <Route path="${route}" element={<DataStudioPage />} /> where your app's other pages are.`
1101
1101
  };
1102
1102
  }
1103
- const childPath = base ? relative13.slice(base.length + 1) : relative13;
1103
+ const childPath = base ? relative14.slice(base.length + 1) : relative14;
1104
1104
  const guard = GUARD.exec(source)?.[1];
1105
1105
  const element = guard ? `<${guard}><DataStudioPage /></${guard}>` : "<DataStudioPage />";
1106
1106
  const before = source.slice(0, layout.close);
@@ -1505,6 +1505,25 @@ var PRIVACY_PURPOSES = {
1505
1505
  "third-party advertising": "NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising",
1506
1506
  other: "NSPrivacyCollectedDataTypePurposeOther"
1507
1507
  };
1508
+ var ENVIRONMENT_KEYS = /* @__PURE__ */ new Set(["previews", "label", "branchPrefix", "$comment"]);
1509
+ function validateEnvironments(raw, source = "config") {
1510
+ const fail = (msg) => {
1511
+ throw new GenesisConfigError(`${source}: ${msg}`);
1512
+ };
1513
+ if (!isObject(raw)) return fail(`"environments" must be an object`);
1514
+ for (const key2 of Object.keys(raw)) if (!ENVIRONMENT_KEYS.has(key2)) fail(`environments: unknown setting "${key2}" (known: previews, label, branchPrefix)`);
1515
+ const out = {};
1516
+ if (raw.previews !== void 0) {
1517
+ if (raw.previews !== "on-demand" && raw.previews !== "every-pr" && raw.previews !== "off") fail(`environments.previews must be "on-demand", "every-pr" or "off" (got ${JSON.stringify(raw.previews)})`);
1518
+ out.previews = raw.previews;
1519
+ }
1520
+ for (const key2 of ["label", "branchPrefix"]) {
1521
+ if (raw[key2] === void 0) continue;
1522
+ if (typeof raw[key2] !== "string") fail(`environments.${key2} must be a string ("" turns that check off)`);
1523
+ out[key2] = raw[key2];
1524
+ }
1525
+ return out;
1526
+ }
1508
1527
  var STRING_LISTS = ["src", "extensions", "ignore", "tokenFiles", "ignoreTokenPrefixes", "localPrimitiveDirs", "build", "componentPackages"];
1509
1528
  var STRINGS = ["uiPackage", "rulesDoc"];
1510
1529
  var KNOWN = /* @__PURE__ */ new Set([
@@ -1515,6 +1534,7 @@ var KNOWN = /* @__PURE__ */ new Set([
1515
1534
  "forbiddenImports",
1516
1535
  "rules",
1517
1536
  "allow",
1537
+ "extend",
1518
1538
  "patterns",
1519
1539
  "plugins",
1520
1540
  "packs",
@@ -1529,14 +1549,17 @@ var KNOWN = /* @__PURE__ */ new Set([
1529
1549
  "$comment"
1530
1550
  ]);
1531
1551
  var LEVELS = /* @__PURE__ */ new Set(["error", "warn", "info", "off"]);
1532
- var META_RULES = /* @__PURE__ */ new Set(["allow-grew", "rules-weakened", "ratchet-skipped"]);
1552
+ var META_RULES = /* @__PURE__ */ new Set(["allow-grew", "rules-weakened", "ratchet-skipped", "extension-invalid"]);
1553
+ var CONFIG_RULES = /* @__PURE__ */ new Set(["stale-exception", "stale-extension", "package-rule-override"]);
1554
+ var EXTENSION_KEYS = /* @__PURE__ */ new Set(["rule", "file", "buildsOn", "reason", "upstream"]);
1555
+ var EXTENSION_REASON_MIN = { chars: 40, words: 6 };
1533
1556
  var PATTERN_KEYS = /* @__PURE__ */ new Set(["id", "level", "files", "exclude", "forbid", "require", "path", "message", "newOnly"]);
1534
1557
  var PACKAGE_RULE_KEYS = /* @__PURE__ */ new Set(["level", "files", "exclude", "reason"]);
1535
1558
  var CONTRACT_KEYS = /* @__PURE__ */ new Set(["out", "schemas", "databaseEnv"]);
1536
1559
  var PACKS = /* @__PURE__ */ new Set(["native", "supabase", "packages"]);
1537
1560
  var PACK_KEYS = {
1538
1561
  native: { routerRoot: "path" },
1539
- supabase: { migrations: "path", base: "string", exposedSchemas: "list", since: "string" },
1562
+ supabase: { migrations: "path", base: "string", exposedSchemas: "list", since: "string", automaticBranching: "boolean" },
1540
1563
  packages: { base: "string" }
1541
1564
  };
1542
1565
  function appPath(v, where2, fail) {
@@ -1597,6 +1620,7 @@ function readGenesisConfig(root) {
1597
1620
  if (supabase !== true) out.supabase = supabase;
1598
1621
  }
1599
1622
  if (raw.appFolder !== void 0) out.appFolder = validateAppFolder(raw.appFolder, file);
1623
+ if (raw.environments !== void 0) out.environments = validateEnvironments(raw.environments, file);
1600
1624
  return out;
1601
1625
  }
1602
1626
  var PLAIN_FOLDER = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,59}(?:\/[A-Za-z0-9_][A-Za-z0-9_.-]{0,59}){0,7}$/;
@@ -1739,6 +1763,30 @@ function validateConfig(raw, source = "config") {
1739
1763
  }
1740
1764
  });
1741
1765
  }
1766
+ if (c.extend !== void 0) {
1767
+ if (!Array.isArray(c.extend)) fail(`"extend" must be a list of { rule, file, buildsOn, reason, upstream? }`);
1768
+ const seen = /* @__PURE__ */ new Set();
1769
+ c.extend.forEach((e, i) => {
1770
+ const where2 = `extend[${i}]`;
1771
+ if (!isObject(e)) return fail(`${where2} must be an object`);
1772
+ for (const k of Object.keys(e)) if (!EXTENSION_KEYS.has(k)) fail(`${where2}: unknown key "${k}" (known: ${[...EXTENSION_KEYS].join(", ")})`);
1773
+ for (const k of ["rule", "file", "buildsOn", "reason"]) if (typeof e[k] !== "string" || !e[k].trim()) fail(`${where2} needs "${k}"`);
1774
+ const { rule, file, buildsOn, reason } = e;
1775
+ if (META_RULES.has(rule) || CONFIG_RULES.has(rule)) fail(`${where2} can't extend ${rule}: it is about the config, not the app's code`);
1776
+ if (!rule.includes("/")) fail(`${where2} can't extend ${rule}: only package rules declare extension points (a built-in rule's findings are fixed, or recorded as allow debt)`);
1777
+ if (/[*?[\]{}]/.test(file)) fail(`${where2}.file must be one file, not a glob: each extension is reviewed on its own`);
1778
+ e.file = appPath(file, `${where2}.file`, fail);
1779
+ if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(buildsOn)) fail(`${where2}.buildsOn must name a Genesis export, or a part of one ("FormBuilder", "ResourceView.slots")`);
1780
+ const text = reason.trim();
1781
+ if (text.length < EXTENSION_REASON_MIN.chars || text.split(/\s+/).length < EXTENSION_REASON_MIN.words) {
1782
+ fail(`${where2} (${rule}) needs a reason of at least ${EXTENSION_REASON_MIN.words} words and ${EXTENSION_REASON_MIN.chars} characters: why the rule's primitive doesn't fit this file`);
1783
+ }
1784
+ if (e.upstream !== void 0 && (typeof e.upstream !== "string" || !e.upstream.trim())) fail(`${where2}.upstream must be a link to the gap's write-up`);
1785
+ const key2 = `${rule}\0${e.file}`;
1786
+ if (seen.has(key2)) fail(`${where2} extends ${rule} in ${e.file} twice`);
1787
+ seen.add(key2);
1788
+ });
1789
+ }
1742
1790
  if (c.patterns !== void 0) {
1743
1791
  if (!Array.isArray(c.patterns)) fail(`"patterns" must be a list`);
1744
1792
  c.patterns.forEach((p, i) => {
@@ -1795,6 +1843,7 @@ function validateConfig(raw, source = "config") {
1795
1843
  if (!want) fail(`${pack}: unknown setting "${k}"`);
1796
1844
  if (want === "string" && typeof v !== "string") fail(`${pack}.${k} must be a string`);
1797
1845
  if (want === "list" && !isStringList(v)) fail(`${pack}.${k} must be a list of strings`);
1846
+ if (want === "boolean" && typeof v !== "boolean") fail(`${pack}.${k} must be true or false`);
1798
1847
  if (want === "string" && !v.trim()) fail(`${pack}.${k} must not be empty`);
1799
1848
  if (want === "path") block[k] = appPath(v, `${pack}.${k}`, fail);
1800
1849
  }
@@ -1846,7 +1895,7 @@ function globToRegExp(glob) {
1846
1895
  }
1847
1896
  function globMatcher(globs) {
1848
1897
  const res = (globs ?? []).filter((g) => g.trim()).map(globToRegExp);
1849
- return (path48) => res.some((re) => re.test(path48));
1898
+ return (path49) => res.some((re) => re.test(path49));
1850
1899
  }
1851
1900
  var GENESIS_PACKAGE = /^@marktiderman\/genesis(-[a-z0-9-]+)?$/;
1852
1901
  var BLOCK_ID = /^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$/;
@@ -2431,6 +2480,9 @@ function scanFiles(root, config) {
2431
2480
  for (const pkg of local) walk3(pkg.dir);
2432
2481
  return files;
2433
2482
  }
2483
+ function withText(file, text) {
2484
+ return { ...file, text, code: stripBlockComments(text, LINE_COMMENT_EXTS.has(file.ext)) };
2485
+ }
2434
2486
  function lineAt(text, index) {
2435
2487
  let line = 1;
2436
2488
  for (let i = 0; i < index && i < text.length; i++) if (text.charCodeAt(i) === 10) line++;
@@ -3402,6 +3454,7 @@ var BUILTIN_RULES = [
3402
3454
  "migration-edited",
3403
3455
  "migration-testing-kit",
3404
3456
  "migration-view-rls",
3457
+ "exposed-schema-created-later",
3405
3458
  // packages pack
3406
3459
  "package-app-import",
3407
3460
  "package-undeclared-dependency",
@@ -3427,6 +3480,10 @@ var BUILTIN_RULES = [
3427
3480
  "ratchet-skipped",
3428
3481
  "allow-grew",
3429
3482
  "rules-weakened",
3483
+ "extension-added",
3484
+ // declared extensions (extensions.ts)
3485
+ "stale-extension",
3486
+ "extension-invalid",
3430
3487
  // agent guide (primitives.ts)
3431
3488
  "agent-guide-stale",
3432
3489
  // supabase pack: contracts (contracts.ts)
@@ -3715,6 +3772,34 @@ function readSource(abs) {
3715
3772
  return null;
3716
3773
  }
3717
3774
  }
3775
+ var lastBlanked = null;
3776
+ function blankStrings(code) {
3777
+ if (lastBlanked?.source === code) return lastBlanked.blanked;
3778
+ const out = code.split("");
3779
+ for (let i = 0; i < code.length; i++) {
3780
+ const ch = code[i];
3781
+ if (ch !== '"' && ch !== "'" && ch !== "`") continue;
3782
+ let j = i - 1;
3783
+ while (j >= 0 && /[ \t]/.test(code[j])) j--;
3784
+ const before = j >= 0 ? code[j] : "\n";
3785
+ const word = /[\w$]/.test(before) ? /(?:^|[^\w$])(return|case|typeof|in|of|yield|await)$/.test(code.slice(Math.max(0, j - 8), j + 1)) : false;
3786
+ if (/[\w$)\]]/.test(before) && !word) continue;
3787
+ let k = i + 1;
3788
+ for (; k < code.length; k++) {
3789
+ const c = code[k];
3790
+ if (c === "\\") {
3791
+ k++;
3792
+ continue;
3793
+ }
3794
+ if (c === ch) break;
3795
+ if (c === "\n" && ch !== "`") break;
3796
+ }
3797
+ for (let x = i + 1; x < k && x < code.length; x++) if (code[x] !== "\n") out[x] = " ";
3798
+ i = k;
3799
+ }
3800
+ lastBlanked = { source: code, blanked: out.join("") };
3801
+ return lastBlanked.blanked;
3802
+ }
3718
3803
  function tagEnd(code, start) {
3719
3804
  let depth = 0;
3720
3805
  let quote2 = null;
@@ -3736,7 +3821,8 @@ function tagEnd(code, start) {
3736
3821
  }
3737
3822
  return { end: code.length, selfClosing: false };
3738
3823
  }
3739
- function openElementsAt(code, index, track) {
3824
+ function openElementsAt(source, index, track) {
3825
+ const code = blankStrings(source);
3740
3826
  const open = [];
3741
3827
  const re = /<(\/?)([A-Z][\w.]*)(?=[\s>/])/g;
3742
3828
  for (let m = re.exec(code); m && m.index < index; m = re.exec(code)) {
@@ -4588,9 +4674,9 @@ var PackageDeclarationError = class extends Error {
4588
4674
  var GENESIS = /^@marktiderman\/genesis(?:-([a-z0-9-]+))?$/;
4589
4675
  var ID = /^[a-z0-9][a-z0-9-]*$/;
4590
4676
  var LEVELS2 = /* @__PURE__ */ new Set(["error", "warn", "info"]);
4591
- var PREFER_KEYS = /* @__PURE__ */ new Set(["id", "need", "level", "platform", "files", "exclude", "forbid", "unless", "use", "import", "docs", "why", "newOnly"]);
4677
+ var PREFER_KEYS = /* @__PURE__ */ new Set(["id", "need", "level", "platform", "files", "exclude", "forbid", "unless", "use", "import", "docs", "why", "newOnly", "extensible"]);
4592
4678
  var FORBID_KEYS = /* @__PURE__ */ new Set(["jsx", "imports", "pattern"]);
4593
- var UNLESS_KEYS = /* @__PURE__ */ new Set(["renders", "pattern"]);
4679
+ var UNLESS_KEYS = /* @__PURE__ */ new Set(["renders", "inside", "pattern"]);
4594
4680
  var PRIMITIVE_KEYS = /* @__PURE__ */ new Set(["need", "use", "import", "docs"]);
4595
4681
  var DECLARATION_KEYS = /* @__PURE__ */ new Set(["enforce", "reason", "prefer", "catalog", "primitives", "plugin", "$comment"]);
4596
4682
  var SCRIPT_GLOBS = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.mts", "**/*.cts", "**/*.mjs", "**/*.cjs"];
@@ -4699,6 +4785,9 @@ function validatePrefer(raw, where2, fail, unknownKey) {
4699
4785
  if (raw.platform !== void 0 && raw.platform !== "web" && raw.platform !== "native") fail(`${at}.platform must be "web" or "native"`);
4700
4786
  if (raw.newOnly !== void 0 && typeof raw.newOnly !== "boolean") fail(`${at}.newOnly must be true or false`);
4701
4787
  for (const key2 of ["files", "exclude"]) if (raw[key2] !== void 0 && !isStringList2(raw[key2])) fail(`${at}.${key2} must be a list of globs`);
4788
+ if (raw.extensible !== void 0 && !(isStringList2(raw.extensible) && raw.extensible.every((n) => /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(n)))) {
4789
+ fail(`${at}.extensible must be a list of export names, or parts of one ("ResourceView.slots")`);
4790
+ }
4702
4791
  if (!isObject3(raw.forbid)) fail(`${at} needs "forbid": { jsx?, imports?, pattern? }`);
4703
4792
  const forbid = raw.forbid;
4704
4793
  for (const key2 of Object.keys(forbid)) if (!FORBID_KEYS.has(key2)) unknownKey(`${at}.forbid`, key2);
@@ -4711,6 +4800,7 @@ function validatePrefer(raw, where2, fail, unknownKey) {
4711
4800
  const unless = raw.unless;
4712
4801
  for (const key2 of Object.keys(unless)) if (!UNLESS_KEYS.has(key2)) narrowing(`${at}.unless`, key2, UNLESS_KEYS);
4713
4802
  if (unless.renders !== void 0 && !isStringList2(unless.renders)) fail(`${at}.unless.renders must be a list of component names`);
4803
+ if (unless.inside !== void 0 && !(isStringList2(unless.inside) && unless.inside.every((n) => /^[A-Z][\w.]*$/.test(n)))) fail(`${at}.unless.inside must be a list of component names`);
4714
4804
  if (unless.pattern !== void 0) checkPattern(unless.pattern, `${at}.unless.pattern`, fail);
4715
4805
  }
4716
4806
  return raw;
@@ -4825,6 +4915,7 @@ function compile(rule, setting, routes) {
4825
4915
  imports: (rule.forbid.imports ?? []).map(specMatcher),
4826
4916
  ...rule.forbid.pattern ? { pattern: toRegExp2(rule.forbid.pattern, "g") } : {},
4827
4917
  unlessRenders: new Set(rule.unless?.renders ?? []),
4918
+ unlessInside: new Set(rule.unless?.inside ?? []),
4828
4919
  ...rule.unless?.pattern ? { unlessPattern: toRegExp2(rule.unless.pattern) } : {}
4829
4920
  };
4830
4921
  }
@@ -4836,10 +4927,11 @@ function messageFor(rule, found) {
4836
4927
  const docs = rule.docs ? ` See ${rule.docs}` : "";
4837
4928
  return `${found}; use ${rule.use}${from}. ${rule.why}${docs}`;
4838
4929
  }
4930
+ var CHILDREN = /\{\s*(?:props\.)?children\s*\}/g;
4839
4931
  var TOP_LEVEL = /^(export\s+(default\s+)?)?(?:async\s+)?(?:function\*?|const|let|var|class)\s+([\w$]+)/gm;
4840
4932
  var EXPORT_LIST = /\bexport\s*\{([^}]*)\}(?!\s*from)/g;
4841
4933
  var EXPORT_DEFAULT_NAME = /^export\s+default\s+([A-Z][\w$]*)\s*;?\s*$/gm;
4842
- function wrappersIn(file, elements, c) {
4934
+ function wrappersIn(file, elements, names, accept) {
4843
4935
  const out = /* @__PURE__ */ new Map();
4844
4936
  const decls = [...file.code.matchAll(TOP_LEVEL)];
4845
4937
  const listed = /* @__PURE__ */ new Map();
@@ -4852,12 +4944,12 @@ function wrappersIn(file, elements, c) {
4852
4944
  for (const m of file.code.matchAll(EXPORT_DEFAULT_NAME)) listed.set(m[1], [...listed.get(m[1]) ?? [], "default"]);
4853
4945
  decls.forEach((d, i) => {
4854
4946
  const name = d[3];
4855
- if (!/^[A-Z]/.test(name) || c.jsx.has(name)) return;
4947
+ if (!/^[A-Z]/.test(name) || names.has(name)) return;
4856
4948
  const end = decls[i + 1]?.index ?? file.code.length;
4857
- const hit = elements.find((m) => m.index > d.index && m.index < end && c.jsx.has(m[1]));
4858
- if (!hit) return;
4859
- const names = [...d[1] ? [d[2] ? "default" : name] : [], ...listed.get(name) ?? []];
4860
- for (const n of names) out.set(n, hit[1]);
4949
+ const hit = elements.find((m) => m.index > d.index && m.index < end && names.has(m[1]));
4950
+ if (!hit || accept && !accept(d.index, end)) return;
4951
+ const exported = [...d[1] ? [d[2] ? "default" : name] : [], ...listed.get(name) ?? []];
4952
+ for (const n of exported) out.set(n, hit[1]);
4861
4953
  });
4862
4954
  return out;
4863
4955
  }
@@ -4865,6 +4957,32 @@ function runPrefer(ctx, c) {
4865
4957
  const own = c.rule.packageDir;
4866
4958
  const checked = ctx.files.filter((file) => SCRIPT.has(file.ext) && c.includes(file.path) && !c.excludes(file.path) && !inside(own, file.absolutePath));
4867
4959
  const exempt = (file, rendered) => rendered.some((n) => c.unlessRenders.has(n)) || (c.unlessPattern?.test(file.code) ?? false);
4960
+ const scanned = new Map(ctx.files.map((f) => [f.absolutePath, f]));
4961
+ const importedBy = /* @__PURE__ */ new Map();
4962
+ const importsOf = (file) => {
4963
+ if (!importedBy.has(file)) importedBy.set(file, localImportedNames(ctx.root, file));
4964
+ return importedBy.get(file);
4965
+ };
4966
+ const builders = /* @__PURE__ */ new Map();
4967
+ const buildersIn = (abs) => {
4968
+ if (!builders.has(abs)) {
4969
+ const target = scanned.get(abs) ?? readSource(abs);
4970
+ const code = target ? "ext" in target ? target.code : stripBlockComments(target.code, true) : "";
4971
+ const childrenInside = (start, end) => [...code.slice(start, end).matchAll(CHILDREN)].some((m) => openElementsAt(code, start + m.index, (n) => c.unlessInside.has(n)).length > 0);
4972
+ builders.set(abs, code ? wrappersIn({ code }, [...code.matchAll(ELEMENT)], c.unlessInside, childrenInside) : /* @__PURE__ */ new Map());
4973
+ }
4974
+ return builders.get(abs);
4975
+ };
4976
+ const nestedInBuilder = (file, index) => {
4977
+ if (!c.unlessInside.size) return false;
4978
+ const imported = importsOf(file);
4979
+ const isBuilder = (name) => {
4980
+ if (c.unlessInside.has(name)) return true;
4981
+ const from = name.includes(".") ? void 0 : imported.get(name);
4982
+ return from !== void 0 && buildersIn(from.file).has(from.name);
4983
+ };
4984
+ return openElementsAt(file.code, index, isBuilder).length > 0;
4985
+ };
4868
4986
  const wrappers = /* @__PURE__ */ new Map();
4869
4987
  const renderedBy = /* @__PURE__ */ new Map();
4870
4988
  for (const file of checked) {
@@ -4872,16 +4990,17 @@ function runPrefer(ctx, c) {
4872
4990
  const elements = [...file.code.matchAll(ELEMENT)];
4873
4991
  renderedBy.set(file, elements);
4874
4992
  if (!c.jsx.size || exempt(file, elements.map((m) => m[1]))) continue;
4875
- const found = wrappersIn(file, elements, c);
4993
+ const found = wrappersIn(file, elements, c.jsx);
4876
4994
  if (found.size) wrappers.set(file.absolutePath, found);
4877
4995
  }
4878
4996
  for (const file of checked) {
4879
4997
  const elements = renderedBy.get(file) ?? [];
4880
4998
  if (exempt(file, elements.map((m) => m[1]))) continue;
4881
4999
  const report = (line, subject, found) => ctx.report({ rule: c.rule.ruleId, level: c.level, file: file.path, line, subject, message: messageFor(c.rule, found) });
4882
- const imported = wrappers.size && elements.length ? localImportedNames(ctx.root, file) : null;
5000
+ const imported = wrappers.size && elements.length ? importsOf(file) : null;
4883
5001
  for (const m of elements) {
4884
5002
  const name = m[1];
5003
+ if (nestedInBuilder(file, m.index)) continue;
4885
5004
  if (c.jsx.has(name)) {
4886
5005
  report(lineAt(file.code, m.index), name, `renders <${name}>`);
4887
5006
  continue;
@@ -4898,6 +5017,7 @@ function runPrefer(ctx, c) {
4898
5017
  if (c.pattern) {
4899
5018
  c.pattern.lastIndex = 0;
4900
5019
  for (const m of file.code.matchAll(c.pattern)) {
5020
+ if (nestedInBuilder(file, m.index)) continue;
4901
5021
  const text = m[0].trim().replace(/\s+/g, " ").slice(0, 60);
4902
5022
  report(lineAt(file.code, m.index), text, `has ${text}`);
4903
5023
  }
@@ -5545,6 +5665,67 @@ function checkSupabasePack(ctx) {
5545
5665
  checkViewInvoker(ctx, migrations, exposed);
5546
5666
  checkDefinerSearchPath(ctx, migrations);
5547
5667
  checkTestingKit(ctx, migrations);
5668
+ checkExposedSchemasCreatedLater(ctx, dir, migrations, settings.exposedSchemas, settings.automaticBranching !== false);
5669
+ }
5670
+ var PLATFORM_SCHEMAS = /* @__PURE__ */ new Set(["public", "graphql_public", "graphql", "extensions", "storage", "auth", "realtime", "vault"]);
5671
+ function apiSchemas(toml) {
5672
+ const lines = toml.split("\n");
5673
+ const start = lines.findIndex((l) => /^\s*\[api\]\s*(?:#.*)?$/.test(l));
5674
+ if (start < 0) return null;
5675
+ let end = lines.findIndex((l, i) => i > start && /^\s*\[/.test(l));
5676
+ if (end < 0) end = lines.length;
5677
+ const bare = (l) => {
5678
+ let quoted = false;
5679
+ for (let i = 0; i < l.length; i++) {
5680
+ if (l[i] === '"' && l[i - 1] !== "\\") quoted = !quoted;
5681
+ else if (l[i] === "#" && !quoted) return l.slice(0, i);
5682
+ }
5683
+ return l;
5684
+ };
5685
+ const body = lines.slice(start + 1, end).map(bare);
5686
+ const enabled = !body.some((l) => /^\s*enabled\s*=\s*false\b/.test(l));
5687
+ const at = body.findIndex((l) => /^\s*schemas\s*=/.test(l));
5688
+ if (at < 0) return { enabled, schemas: [], line: start + 1 };
5689
+ let list = "";
5690
+ for (let i = at; i < body.length; i++) {
5691
+ list += `${body[i]}
5692
+ `;
5693
+ if (body[i].includes("]")) break;
5694
+ }
5695
+ const inner = /\[([\s\S]*?)\]/.exec(list)?.[1] ?? "";
5696
+ const schemas = [...inner.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g)].map((m) => (m[1] ?? m[2]).trim().toLowerCase()).filter(Boolean);
5697
+ return { enabled, schemas, line: start + at + 2 };
5698
+ }
5699
+ function checkExposedSchemasCreatedLater(ctx, dir, migrations, configured, branching) {
5700
+ const created = /* @__PURE__ */ new Map();
5701
+ for (const { file, statements } of migrations) {
5702
+ for (const { sql, line } of statements) {
5703
+ const m = /^create schema (?:if not exists )?"?([\w$]+)"?/.exec(sql);
5704
+ if (m && m[1] !== "authorization" && !created.has(m[1])) created.set(m[1], { file, line });
5705
+ }
5706
+ }
5707
+ const tomlFile = path21.posix.join(path21.posix.dirname(dir), "config.toml");
5708
+ const tomlText = existsSync(path21.join(ctx.root, tomlFile)) ? readFileSync(path21.join(ctx.root, tomlFile), "utf8") : null;
5709
+ const api2 = tomlText === null ? null : apiSchemas(tomlText);
5710
+ const sources = [];
5711
+ if (api2?.enabled) for (const schema of api2.schemas) sources.push({ schema, file: tomlFile, line: api2.line, where: `${tomlFile} [api] schemas` });
5712
+ for (const schema of api2?.enabled === false ? [] : configured ?? []) {
5713
+ const s = schema.toLowerCase();
5714
+ if (!sources.some((x) => x.schema === s)) sources.push({ schema: s, file: "genesis.config.json", where: "doctor.supabase.exposedSchemas" });
5715
+ }
5716
+ for (const { schema, file, line, where: where2 } of sources) {
5717
+ if (PLATFORM_SCHEMAS.has(schema)) continue;
5718
+ const by = created.get(schema);
5719
+ if (by && !branching) continue;
5720
+ ctx.report({
5721
+ rule: "exposed-schema-created-later",
5722
+ level: "warn",
5723
+ file,
5724
+ ...line ? { line } : {},
5725
+ subject: schema,
5726
+ message: by ? `${where2} exposes ${schema}, which only a migration creates (${by.file}:${by.line}); a Supabase branch points its Data API at ${schema} before it runs migrations, so a fresh preview branch fails its health check. Turn off Supabase's automatic branching (Genesis docs/APP-CI.md, "Previews"), then set doctor.supabase.automaticBranching to false` : `${where2} exposes ${schema}, which no migration creates, so a database built from the migrations can't serve it (a Supabase branch fails its health check); create it in a migration or stop exposing it`
5727
+ });
5728
+ }
5548
5729
  }
5549
5730
  function checkTestingKit(ctx, migrations) {
5550
5731
  for (const { file, statements } of migrations) {
@@ -6632,13 +6813,34 @@ function git3(root, args) {
6632
6813
  return r.status === 0 ? r.stdout : null;
6633
6814
  }
6634
6815
  function changedSince(root, base) {
6635
- const mergeBase = git3(root, ["merge-base", base, "HEAD"])?.trim();
6816
+ const mergeBase = mergeBaseOf2(root, base);
6636
6817
  if (!mergeBase) return null;
6637
6818
  const committed = git3(root, ["diff", "-z", "--name-only", "--relative", `${mergeBase}`, "--"]);
6638
6819
  const untracked = git3(root, ["ls-files", "-z", "--others", "--exclude-standard"]);
6639
6820
  if (committed === null || untracked === null) return null;
6640
6821
  return new Set([...committed.split("\0"), ...untracked.split("\0")].filter(Boolean));
6641
6822
  }
6823
+ function originsSince(root, base) {
6824
+ const out = /* @__PURE__ */ new Map();
6825
+ const mergeBase = mergeBaseOf2(root, base);
6826
+ if (!mergeBase) return out;
6827
+ const diff = git3(root, ["diff", "-z", "-M", "--name-status", "--relative", mergeBase, "--"]);
6828
+ if (diff === null) return out;
6829
+ const parts = diff.split("\0");
6830
+ for (let i = 0; i < parts.length; ) {
6831
+ const status = parts[i++] ?? "";
6832
+ if (!status) continue;
6833
+ if (status.startsWith("R") || status.startsWith("C")) {
6834
+ const from = parts[i++];
6835
+ const to = parts[i++];
6836
+ if (status.startsWith("R")) out.set(to, from);
6837
+ } else i++;
6838
+ }
6839
+ return out;
6840
+ }
6841
+ function mergeBaseOf2(root, base) {
6842
+ return git3(root, ["merge-base", base, "HEAD"])?.trim() || null;
6843
+ }
6642
6844
  var objectOr = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : {};
6643
6845
  function showAt(dir, rev, file) {
6644
6846
  const at = `${rev}:./${file}`;
@@ -6646,7 +6848,7 @@ function showAt(dir, rev, file) {
6646
6848
  return git3(dir, ["show", at]);
6647
6849
  }
6648
6850
  function configAtBase(root, base, explicitFile) {
6649
- const mergeBase = git3(root, ["merge-base", base, "HEAD"])?.trim();
6851
+ const mergeBase = mergeBaseOf2(root, base);
6650
6852
  if (!mergeBase) return null;
6651
6853
  const candidates = explicitFile ? [{ dir: path21.dirname(explicitFile), file: path21.basename(explicitFile), explicit: true }] : [
6652
6854
  { dir: root, file: "genesis.config.json", explicit: false },
@@ -6667,7 +6869,12 @@ function configAtBase(root, base, explicitFile) {
6667
6869
  continue;
6668
6870
  }
6669
6871
  const b = objectOr(block);
6670
- return { allow: Array.isArray(b.allow) ? b.allow : [], rules: objectOr(b.rules), packageRules: objectOr(b.packageRules) };
6872
+ return {
6873
+ allow: Array.isArray(b.allow) ? b.allow : [],
6874
+ extend: Array.isArray(b.extend) ? b.extend : [],
6875
+ rules: objectOr(b.rules),
6876
+ packageRules: objectOr(b.packageRules)
6877
+ };
6671
6878
  }
6672
6879
  return "absent";
6673
6880
  }
@@ -6681,6 +6888,16 @@ function allowGrew(allow, before, base) {
6681
6888
  message: `allow gained an entry for ${a.rule}${a.match ? ` (${a.match})` : ""} since ${base}; the list only shrinks, so fix what it hides instead`
6682
6889
  }));
6683
6890
  }
6891
+ function extensionsAdded(extend, before, base) {
6892
+ const had = new Set(before.map((e) => `${e.rule}\0${e.file}\0${e.buildsOn}`));
6893
+ return extend.filter((e) => !had.has(`${e.rule}\0${e.file}\0${e.buildsOn}`)).map((e) => ({
6894
+ rule: "extension-added",
6895
+ level: "info",
6896
+ file: e.file,
6897
+ subject: e.rule,
6898
+ message: `extends ${e.rule} since ${base}, building on ${e.buildsOn}: "${e.reason}"${e.upstream ? ` (upstream: ${e.upstream})` : ""}; the pull request's review accepts it, and it covers only the findings the file has now`
6899
+ }));
6900
+ }
6684
6901
  var RANK = { off: 0, info: 1, warn: 2, error: 3 };
6685
6902
  function rulesWeakened(config, before, base) {
6686
6903
  const out = [];
@@ -6718,14 +6935,169 @@ var NEVER_RATCHETED = /* @__PURE__ */ new Set([
6718
6935
  "plugin-error",
6719
6936
  "build",
6720
6937
  "agent-guide-stale",
6721
- "contracts-stale"
6938
+ "contracts-stale",
6939
+ "stale-extension",
6940
+ "extension-added"
6722
6941
  ]);
6942
+ function isRatcheted(rule, config, newOnly) {
6943
+ return !NEVER_RATCHETED.has(rule) && (config.ratchet === true || newOnly.has(rule) || Array.isArray(config.ratchet) && config.ratchet.includes(rule));
6944
+ }
6945
+ var countKey = (file, rule) => `${file}\0${rule}`;
6946
+ function countFindings(findings) {
6947
+ const counts = /* @__PURE__ */ new Map();
6948
+ for (const f of findings) counts.set(countKey(f.file, f.rule), (counts.get(countKey(f.file, f.rule)) ?? 0) + 1);
6949
+ return counts;
6950
+ }
6723
6951
  function applyRatchet(findings, options) {
6724
- const { config, newOnly, changed, base, isAppPath } = options;
6725
- const ratcheted = (rule) => !NEVER_RATCHETED.has(rule) && (config.ratchet === true || newOnly.has(rule) || Array.isArray(config.ratchet) && config.ratchet.includes(rule));
6952
+ const { config, newOnly, changed, base, isAppPath, baseCounts, existedAtBase } = options;
6953
+ const originOf = options.originOf ?? ((f) => f);
6954
+ const counts = countFindings(findings.map((f) => ({ file: originOf(f.file), rule: f.rule })));
6726
6955
  return findings.map((f) => {
6727
- if (f.level === "info" || !ratcheted(f.rule) || !isAppPath(f.file) || touched(f.file, changed)) return f;
6728
- return { ...f, level: "info", message: `${f.message} (ratcheted: unchanged since ${base})` };
6956
+ if (f.level === "info" || !isRatcheted(f.rule, config, newOnly) || !isAppPath(f.file)) return f;
6957
+ if (!touched(f.file, changed)) return { ...f, level: "info", message: `${f.message} (ratcheted: unchanged since ${base})` };
6958
+ const origin = originOf(f.file);
6959
+ if (!baseCounts || !existedAtBase?.(origin)) return f;
6960
+ const now = counts.get(countKey(origin, f.rule)) ?? 0;
6961
+ const was = baseCounts.get(countKey(origin, f.rule)) ?? 0;
6962
+ const where2 = origin === f.file ? "this file" : `the files from ${origin}`;
6963
+ if (now > was) return { ...f, message: `${f.message} (${now} ${f.rule} findings in ${where2}, ${was} at the merge base with ${base}: don't add to the debt)` };
6964
+ return { ...f, level: "info", message: `${f.message} (ratcheted: ${now} in ${where2}, ${was} at the merge base with ${base})` };
6965
+ });
6966
+ }
6967
+ function snapshotAtBase(root, base, files, changed, originOf = (f) => f) {
6968
+ const mergeBase = mergeBaseOf2(root, base);
6969
+ if (!mergeBase) return null;
6970
+ const out = [];
6971
+ const seen = /* @__PURE__ */ new Set();
6972
+ for (const f of files) {
6973
+ if (!changed.has(f.path)) {
6974
+ if (!seen.has(f.path)) out.push(f);
6975
+ seen.add(f.path);
6976
+ continue;
6977
+ }
6978
+ const origin = originOf(f.path);
6979
+ if (seen.has(origin)) continue;
6980
+ seen.add(origin);
6981
+ const text = showAt(root, mergeBase, origin);
6982
+ if (text === null) return null;
6983
+ if (text !== void 0) out.push(withText({ ...f, path: origin, absolutePath: path21.join(root, origin) }, text));
6984
+ }
6985
+ const cache2 = /* @__PURE__ */ new Map();
6986
+ return {
6987
+ mergeBase,
6988
+ files: out,
6989
+ existed(file) {
6990
+ if (!cache2.has(file)) cache2.set(file, git3(root, ["cat-file", "-e", `${mergeBase}:./${file}`]) !== null);
6991
+ return cache2.get(file);
6992
+ }
6993
+ };
6994
+ }
6995
+
6996
+ // src/doctor/extensions.ts
6997
+ function pointProblem(entry, packages) {
6998
+ const rule = preferRules(packages).find((r) => r.ruleId === entry.rule);
6999
+ if (!rule?.extensible?.length) return `${entry.rule} declares no extension points, so it can't be extended (debt goes in allow, and is fixed)`;
7000
+ if (!rule.extensible.includes(entry.buildsOn)) return `${entry.buildsOn} isn't one of ${entry.rule}'s extension points (${rule.extensible.join(", ")})`;
7001
+ return null;
7002
+ }
7003
+ function extensionProblem(entry, ctx) {
7004
+ const point = pointProblem(entry, ctx.packages);
7005
+ if (point) return point;
7006
+ const name = entry.buildsOn.split(".")[0];
7007
+ const replaces = preferRules(ctx.packages).find((r) => r.forbid.jsx?.includes(name));
7008
+ if (replaces) return `${name} is what ${replaces.ruleId} replaces (use ${replaces.use}); a legacy component can't be built on`;
7009
+ const flagged = ctx.raw.find((f) => f.file === entry.file && f.subject === name);
7010
+ if (flagged) return `${name} is flagged in this file by ${flagged.rule}; build on a current Genesis primitive`;
7011
+ const file = ctx.files.find((f) => f.path === entry.file);
7012
+ if (!file) return `${entry.file} isn't one of the files the doctor scans`;
7013
+ const imported = genesisNamedImports(file.code).some((i) => i.names.includes(name));
7014
+ if (!imported) return `${entry.file} doesn't import ${name} from a Genesis package; buildsOn names the extension point the file uses`;
7015
+ if (!usesPoint(blankStrings(file.code), entry.buildsOn)) {
7016
+ const prop = entry.buildsOn.split(".")[1];
7017
+ return prop ? `${entry.file} doesn't pass ${prop} to <${name}>; an extension point is one the file uses` : `${entry.file} imports ${name} but doesn't render or call it; an extension point is one the file uses`;
7018
+ }
7019
+ return null;
7020
+ }
7021
+ var escape2 = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
7022
+ function usesPoint(code, point) {
7023
+ const [name, prop] = point.split(".");
7024
+ const n = escape2(name);
7025
+ if (!prop) return new RegExp(`(?<![\\w$.])<${n}(?=[\\s>/<])|(?<![\\w$.])${n}\\s*(?:<[^>()]*>)?\\s*\\(`).test(code);
7026
+ for (const m of code.matchAll(new RegExp(`(?<![\\w$.])<${n}(?=[\\s>/<])`, "g"))) {
7027
+ const { end } = tagEnd(code, m.index);
7028
+ if (new RegExp(`(?<![\\w$.])${escape2(prop)}\\s*=`).test(code.slice(m.index, end))) return true;
7029
+ }
7030
+ return false;
7031
+ }
7032
+ function applyExtensions(findings, ctx) {
7033
+ const entries = ctx.config.extend ?? [];
7034
+ if (!entries.length) return findings;
7035
+ const staleLevel = ctx.config.rules?.["stale-extension"];
7036
+ const covered = /* @__PURE__ */ new Set();
7037
+ const grew = /* @__PURE__ */ new Map();
7038
+ const out = [];
7039
+ const invalid = (entry, problem) => out.push({ rule: "extension-invalid", level: "error", file: entry.file, line: 0, subject: entry.rule, message: `the extension of ${entry.rule} isn't accepted: ${problem}` });
7040
+ for (const entry of entries) {
7041
+ if (ctx.config.rules?.[entry.rule] === "off" || ctx.config.packageRules?.[entry.rule]?.level === "off") continue;
7042
+ const point = pointProblem(entry, ctx.packages);
7043
+ if (point) {
7044
+ invalid(entry, point);
7045
+ continue;
7046
+ }
7047
+ const hits = findings.filter((f) => f.rule === entry.rule && f.file === entry.file);
7048
+ if (!hits.length) {
7049
+ if (staleLevel === "off") continue;
7050
+ out.push({
7051
+ rule: "stale-extension",
7052
+ level: staleLevel ?? "warn",
7053
+ file: entry.file,
7054
+ line: 0,
7055
+ subject: entry.rule,
7056
+ message: `the extension of ${entry.rule} (building on ${entry.buildsOn}) no longer matches a finding in this file; remove it from doctor.extend`
7057
+ });
7058
+ continue;
7059
+ }
7060
+ const problem = extensionProblem(entry, ctx);
7061
+ if (problem) {
7062
+ invalid(entry, problem);
7063
+ continue;
7064
+ }
7065
+ const limit = ctx.limit?.(entry);
7066
+ if (limit !== void 0 && hits.length > limit) {
7067
+ for (const h of hits) grew.set(h, `${h.message} (the extension of ${entry.rule} here covers the ${limit} at the merge base; this file now has ${hits.length}, so they all count)`);
7068
+ continue;
7069
+ }
7070
+ for (const h of hits) covered.add(h);
7071
+ }
7072
+ const kept = findings.filter((f) => !covered.has(f)).map((f) => grew.has(f) ? { ...f, message: grew.get(f) } : f);
7073
+ return [...kept, ...out].sort(byPlace);
7074
+ }
7075
+ var byPlace = (x, y) => x.file.localeCompare(y.file) || x.line - y.line || x.rule.localeCompare(y.rule);
7076
+ var RANK2 = { info: 0, warn: 1, error: 2 };
7077
+ function dedupeFindings(findings) {
7078
+ const groups = /* @__PURE__ */ new Map();
7079
+ const order = [];
7080
+ for (const f of findings) {
7081
+ if (f.subject === void 0 || !f.line) {
7082
+ order.push([f]);
7083
+ continue;
7084
+ }
7085
+ const key2 = `${f.file}\0${f.line}\0${f.subject}`;
7086
+ const list = groups.get(key2) ?? [];
7087
+ const group = list.find((g) => !g.some((x) => x.rule === f.rule));
7088
+ if (group) group.push(f);
7089
+ else {
7090
+ const fresh = [f];
7091
+ list.push(fresh);
7092
+ groups.set(key2, list);
7093
+ order.push(fresh);
7094
+ }
7095
+ }
7096
+ return order.map((group) => {
7097
+ if (group.length === 1) return group[0];
7098
+ const primary = group.reduce((a, b) => RANK2[b.level] > RANK2[a.level] ? b : a);
7099
+ const rules = [primary.rule, ...group.filter((g) => g !== primary).map((g) => g.rule)];
7100
+ return { ...primary, rules, message: `${primary.message} (also ${rules.slice(1).join(", ")})` };
6729
7101
  });
6730
7102
  }
6731
7103
  var DEFAULT_CONTRACT_OUT = "resources.genesis.ts";
@@ -6795,6 +7167,7 @@ async function checkContracts(ctx, read2 = postgresContract) {
6795
7167
  }
6796
7168
  }
6797
7169
  var GENESIS_DOCS = "https://github.com/marktiderman/genesis/blob/main/docs";
7170
+ var read = (file) => existsSync(file) ? readFileSync(file, "utf8") : null;
6798
7171
  var CORE = [
6799
7172
  {
6800
7173
  need: "anything, before building it",
@@ -6867,14 +7240,79 @@ var SKILL_PATH = ".claude/skills/genesis/SKILL.md";
6867
7240
  var AGENTS_START = "<!-- genesis-primitives:start -->";
6868
7241
  var AGENTS_END = "<!-- genesis-primitives:end -->";
6869
7242
  var RULES = [
6870
- "Use the Genesis primitive for the need first: reuse, then extend, then invent (docs/FRAMEWORK.md, G1 to G6).",
7243
+ `Use the Genesis primitive for the need first: reuse, then extend, then invent (G1 to G6 in ${GENESIS_DOCS}/FRAMEWORK.md).`,
6871
7244
  "Never copy an older screen as a template. Old screens predate the primitives; the doctor flags what they did.",
6872
7245
  "A list screen is a view (`defineView`) rendered by `ResourceView`; a record view is `RecordView`; on the phone, `NativeResourceView`.",
6873
7246
  "Screens never call the database client (`supabase.from`, `.rpc`) directly: reads go through a view or a named data function, writes through the resource's provider rules.",
6874
7247
  "When no primitive fits, write the gap up for Genesis before inventing, then invent in the app on Genesis primitives.",
6875
7248
  "Run `genesis doctor` before you finish; it enforces these rules."
6876
7249
  ];
6877
- function renderSkill(rows) {
7250
+ function skillDescription(text) {
7251
+ const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
7252
+ if (!fm) return "";
7253
+ const lines = fm.split(/\r?\n/);
7254
+ const i = lines.findIndex((l) => /^description:/.test(l));
7255
+ if (i < 0) return "";
7256
+ const first = lines[i].replace(/^description:\s*/, "").trim();
7257
+ if (first && !/^[>|][+-]?$/.test(first)) return first.replace(/^["']|["']$/g, "");
7258
+ const more = [];
7259
+ for (const l of lines.slice(i + 1)) {
7260
+ if (!/^\s+\S/.test(l)) break;
7261
+ more.push(l.trim());
7262
+ }
7263
+ return more.join(" ");
7264
+ }
7265
+ var GUIDE_SEARCH_LEVELS = 4;
7266
+ function stableGuidePath(root, p) {
7267
+ const real2 = (f) => {
7268
+ try {
7269
+ return realpathSync(f);
7270
+ } catch {
7271
+ return null;
7272
+ }
7273
+ };
7274
+ const want = real2(p.dir);
7275
+ for (let dir = root, level = 0; level <= GUIDE_SEARCH_LEVELS; level++) {
7276
+ const found = path21.join(dir, "node_modules", p.name);
7277
+ if (existsSync(found)) {
7278
+ const file = path21.join(found, "SKILL.md");
7279
+ return want !== null && real2(found) === want && existsSync(file) ? file : null;
7280
+ }
7281
+ if (existsSync(path21.join(dir, ".git")) || existsSync(path21.join(dir, "pnpm-workspace.yaml"))) return null;
7282
+ const up = path21.dirname(dir);
7283
+ if (up === dir) return null;
7284
+ dir = up;
7285
+ }
7286
+ return null;
7287
+ }
7288
+ function packageGuides(root, packages) {
7289
+ const guides = [];
7290
+ for (const p of packages) {
7291
+ const stable = p.local ? path21.join(p.dir, "SKILL.md") : stableGuidePath(root, p);
7292
+ const text = stable === null ? null : read(stable);
7293
+ if (stable === null || text === null) continue;
7294
+ const description = skillDescription(text);
7295
+ const at = description.indexOf("Load before");
7296
+ guides.push({ package: p.name, path: path21.relative(root, stable).split(path21.sep).join("/"), when: at >= 0 ? description.slice(at) : description });
7297
+ }
7298
+ return guides.sort((a, b) => a.package.localeCompare(b.package));
7299
+ }
7300
+ function unlistedGuides(root, packages) {
7301
+ const listed = new Set(packageGuides(root, packages).map((g) => g.package));
7302
+ return packages.filter((p) => !p.local && !listed.has(p.name) && existsSync(path21.join(p.dir, "SKILL.md"))).map((p) => p.name).sort();
7303
+ }
7304
+ function guidesSection(guides) {
7305
+ if (!guides.length) return [];
7306
+ return [
7307
+ "### Package guides (they match the installed versions)",
7308
+ "",
7309
+ "Before using a package's primitives, read its guide:",
7310
+ "",
7311
+ ...guides.map((g) => `- \`${g.path}\` (${g.package}): ${g.when}`),
7312
+ ""
7313
+ ];
7314
+ }
7315
+ function renderSkill(rows, guides = []) {
6878
7316
  return [
6879
7317
  "---",
6880
7318
  "name: genesis",
@@ -6887,6 +7325,7 @@ function renderSkill(rows) {
6887
7325
  "",
6888
7326
  ...RULES.map((r) => `- ${r}`),
6889
7327
  "",
7328
+ ...guidesSection(guides),
6890
7329
  "## What to use for each need",
6891
7330
  "",
6892
7331
  catalogTable(rows, { docs: true }),
@@ -6895,7 +7334,7 @@ function renderSkill(rows) {
6895
7334
  ""
6896
7335
  ].join("\n");
6897
7336
  }
6898
- function renderAgentsBlock(rows) {
7337
+ function renderAgentsBlock(rows, guides = []) {
6899
7338
  return [
6900
7339
  AGENTS_START,
6901
7340
  "## Building with Genesis",
@@ -6906,6 +7345,7 @@ function renderAgentsBlock(rows) {
6906
7345
  "",
6907
7346
  ...RULES.map((r) => `- ${r}`),
6908
7347
  "",
7348
+ ...guidesSection(guides),
6909
7349
  catalogTable(rows),
6910
7350
  AGENTS_END
6911
7351
  ].join("\n");
@@ -6924,14 +7364,37 @@ function currentAgentsBlock(agents) {
6924
7364
  if (span === "broken") return "broken";
6925
7365
  return agents.slice(span.start, span.end).replace(/\r\n/g, "\n");
6926
7366
  }
6927
- var read = (file) => existsSync(file) ? readFileSync(file, "utf8") : null;
7367
+ function claudeState(root) {
7368
+ const file = path21.join(root, "CLAUDE.md");
7369
+ let names = [];
7370
+ try {
7371
+ names = readdirSync(root);
7372
+ } catch {
7373
+ }
7374
+ if (!names.includes("CLAUDE.md")) return names.some((n) => n.toLowerCase() === "claude.md") ? "blocked" : "missing";
7375
+ let text;
7376
+ try {
7377
+ text = readFileSync(file, "utf8");
7378
+ } catch {
7379
+ return "blocked";
7380
+ }
7381
+ if (/^@AGENTS\.md\b/m.test(text)) return "ok";
7382
+ try {
7383
+ if (realpathSync(file) === realpathSync(path21.join(root, "AGENTS.md"))) return "ok";
7384
+ } catch {
7385
+ }
7386
+ return "no-import";
7387
+ }
6928
7388
  function agentGuideState(root, packages, agentsFile = "AGENTS.md") {
6929
7389
  const rows = primitivesCatalog(packages);
7390
+ const guides = packageGuides(root, packages);
6930
7391
  const skill = read(path21.join(root, SKILL_PATH))?.replace(/\r\n/g, "\n") ?? null;
6931
7392
  const block = currentAgentsBlock(read(path21.join(root, agentsFile)));
6932
7393
  return {
6933
- skill: skill === null ? "missing" : skill === renderSkill(rows) ? "ok" : "stale",
6934
- agents: block === null || block === "broken" ? block ?? "missing" : block === renderAgentsBlock(rows) ? "ok" : "stale"
7394
+ skill: skill === null ? "missing" : skill === renderSkill(rows, guides) ? "ok" : "stale",
7395
+ agents: block === null || block === "broken" ? block ?? "missing" : block === renderAgentsBlock(rows, guides) ? "ok" : "stale",
7396
+ // Only the default AGENTS.md gets a CLAUDE.md written for it, so only then is a missing one reported.
7397
+ claude: agentsFile !== "AGENTS.md" ? "ok" : claudeState(root)
6935
7398
  };
6936
7399
  }
6937
7400
  function checkAgentGuide(ctx) {
@@ -6949,6 +7412,41 @@ function checkAgentGuide(ctx) {
6949
7412
  }[state.agents];
6950
7413
  ctx.report({ rule: "agent-guide-stale", level: "warn", file: "AGENTS.md", message });
6951
7414
  }
7415
+ if (state.claude === "no-import") {
7416
+ ctx.report({ rule: "agent-guide-stale", level: "info", file: "CLAUDE.md", message: "doesn't import AGENTS.md (`@AGENTS.md`), so reviewers and cloud project threads that read only CLAUDE.md don't see the Genesis guide" });
7417
+ }
7418
+ if (state.claude === "missing") {
7419
+ ctx.report({ rule: "agent-guide-stale", level: "warn", file: "CLAUDE.md", message: `is missing, so reviewers and cloud project threads that read only CLAUDE.md never see AGENTS.md; ${fix} (it writes \`@AGENTS.md\`)` });
7420
+ }
7421
+ if (state.claude === "blocked") {
7422
+ ctx.report({ rule: "agent-guide-stale", level: "warn", file: "CLAUDE.md", message: `can't be read: something else is in its place (another case of the name such as claude.md, a dangling link, a folder or an unreadable file), and genesis agents won't write over it; ${BLOCKED_FIX}` });
7423
+ }
7424
+ const unlisted = unlistedGuides(ctx.root, ctx.packages);
7425
+ if (unlisted.length) {
7426
+ ctx.report({ rule: "agent-guide-stale", level: "info", file: "AGENTS.md", message: `leaves out the guide of ${unlisted.join(", ")}: it's only inside pnpm's store, under a path that changes with unrelated bumps. Add the package as a direct dependency to list its guide.` });
7427
+ }
7428
+ }
7429
+ var BLOCKED_FIX = "rename or replace it with a CLAUDE.md file (or remove the dangling link), then run genesis agents";
7430
+ var SETTINGS_PATH = ".claude/settings.json";
7431
+ var SUBAGENT_HOOK_COMMAND = '"$CLAUDE_PROJECT_DIR"/node_modules/.bin/genesis agents --hook subagent-start --dir "$CLAUDE_PROJECT_DIR" 2>/dev/null || true';
7432
+ var isObject4 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
7433
+ var isGenesisHook = (h) => typeof h.command === "string" && h.command.includes("genesis agents --hook");
7434
+ function agentHooksState(root) {
7435
+ let settings;
7436
+ try {
7437
+ settings = JSON.parse(readFileSync(path21.join(root, SETTINGS_PATH), "utf8"));
7438
+ } catch {
7439
+ return "none";
7440
+ }
7441
+ const start = isObject4(settings) && isObject4(settings.hooks) ? settings.hooks["SubagentStart"] : void 0;
7442
+ const commands = (Array.isArray(start) ? start : []).flatMap((e) => isObject4(e) && Array.isArray(e.hooks) ? e.hooks : []).filter((h) => isObject4(h) && isGenesisHook(h)).map((h) => h.command);
7443
+ if (!commands.length) return "none";
7444
+ return commands.every((c) => c === SUBAGENT_HOOK_COMMAND) ? "ok" : "stale";
7445
+ }
7446
+ function checkAgentHooks(ctx) {
7447
+ if (agentHooksState(ctx.root) === "stale") {
7448
+ ctx.report({ rule: "agent-guide-stale", level: "warn", file: SETTINGS_PATH, message: "has an older Genesis SubagentStart hook command; run genesis agents --hooks and commit the result" });
7449
+ }
6952
7450
  }
6953
7451
 
6954
7452
  // src/blocks/templates.ts
@@ -7793,14 +8291,8 @@ async function runDoctor(options = {}) {
7793
8291
  }
7794
8292
  const raw = [];
7795
8293
  const ctx = { root, files, genesis, config, packages, ...options.base ? { base: options.base } : {}, ...options.strict ? { strict: true } : {}, report: (f) => raw.push(f) };
7796
- for (const plugin of [...builtinChecks(config, { contracts: options.contracts ?? true, figma: options.figma ?? true }), ...packagePlugins, ...patterns ? [patterns.plugin] : [], ...plugins]) {
7797
- try {
7798
- await plugin.check(ctx);
7799
- } catch (err) {
7800
- if (err instanceof DoctorConfigError) throw err;
7801
- raw.push({ rule: "plugin-error", file: plugin.name, message: `rule plugin "${plugin.name}" threw: ${err.message}` });
7802
- }
7803
- }
8294
+ const appChecks = [...packagePlugins, ...patterns ? [patterns.plugin] : [], ...plugins];
8295
+ await runChecks(ctx, [...builtinChecks(config, { contracts: options.contracts ?? true, figma: options.figma ?? true }), ...appChecks]);
7804
8296
  if (options.build) {
7805
8297
  const failure = runBuild(root, buildCommands(root, config), options.quietBuild ?? false);
7806
8298
  if (failure) raw.push(failure);
@@ -7810,30 +8302,57 @@ async function runDoctor(options = {}) {
7810
8302
  let changed = null;
7811
8303
  let skipped = false;
7812
8304
  const ratchetNeeded = newOnly.size > RATCHETED_BY_DEFAULT.length || raw.some((f) => RATCHETED_BY_DEFAULT.includes(f.rule));
7813
- if (options.base && (ratchetNeeded || config.ratchet)) {
8305
+ if (options.base && (ratchetNeeded || config.ratchet || config.extend?.length)) {
7814
8306
  changed = options.changedFiles ? new Set(options.changedFiles) : changedSince(root, options.base);
7815
8307
  skipped ||= !changed;
7816
8308
  }
7817
8309
  const configFile = "file" in loaded ? loaded.file : null;
7818
- const guarded = (config.allow?.length ?? 0) + Object.keys(config.rules ?? {}).length + Object.keys(config.packageRules ?? {}).length > 0;
8310
+ const guarded = (config.allow?.length ?? 0) + (config.extend?.length ?? 0) + Object.keys(config.rules ?? {}).length + Object.keys(config.packageRules ?? {}).length > 0;
7819
8311
  let configSkipped = false;
8312
+ let baseExtend = [];
7820
8313
  if (options.base && configFile) {
7821
8314
  const before = configAtBase(root, options.base, options.configPath !== void 0 ? configFile : void 0);
8315
+ if (before && before !== "absent") baseExtend = before.extend;
8316
+ if (before === "absent") raw.push(...extensionsAdded(config.extend ?? [], [], options.base));
7822
8317
  if (before && before !== "absent") {
7823
8318
  raw.push(...allowGrew(config.allow ?? [], before.allow, options.base));
7824
8319
  raw.push(...rulesWeakened(config, before, options.base));
8320
+ raw.push(...extensionsAdded(config.extend ?? [], before.extend, options.base));
7825
8321
  }
7826
8322
  configSkipped = !before && guarded;
7827
8323
  }
7828
8324
  if (skipped || configSkipped) {
7829
8325
  raw.push(
7830
- configSkipped ? { rule: "ratchet-skipped", level: "error", file: "genesis config", message: `couldn't compare allow, rules and packageRules against ${options.base} (not a git repository, or the ref isn't fetched; in CI check out with fetch-depth: 0)` } : { rule: "ratchet-skipped", level: "warn", file: "genesis config", message: `couldn't compare against ${options.base} (not a git repository, or the ref isn't fetched); every rule ran at its full level` }
8326
+ configSkipped ? { rule: "ratchet-skipped", level: "error", file: "genesis config", message: `couldn't compare allow, extend, rules and packageRules against ${options.base} (not a git repository, or the ref isn't fetched; in CI check out with fetch-depth: 0)` } : { rule: "ratchet-skipped", level: "warn", file: "genesis config", message: `couldn't compare against ${options.base} (not a git repository, or the ref isn't fetched); every rule ran at its full level` }
7831
8327
  );
7832
8328
  }
7833
- let findings = applyConfig(raw, config, packageRuleIds(packages));
8329
+ const packageIds = packageRuleIds(packages);
8330
+ const extensionCtx = { config, files, packages, raw };
8331
+ const configured = applyConfig(raw, config, packageIds);
8332
+ let findings = applyExtensions(configured, extensionCtx);
7834
8333
  if (options.base && changed) {
7835
- findings = applyRatchet(findings, { config, newOnly, changed, base: options.base, isAppPath: (f) => existsSync(path21.join(root, f)) });
8334
+ const isAppPath = (f) => existsSync(path21.join(root, f));
8335
+ const origins = options.changedFiles ? /* @__PURE__ */ new Map() : originsSince(root, options.base);
8336
+ const originOf = (f) => origins.get(f) ?? f;
8337
+ const dueRules = new Set(findings.filter((f) => f.level !== "info" && isRatcheted(f.rule, config, newOnly) && isAppPath(f.file) && touched(f.file, changed)).map((f) => f.rule));
8338
+ const heldExtensions = (config.extend ?? []).filter((e) => touched(e.file, changed) && baseExtend.some((b) => b.rule === e.rule && (b.file === e.file || b.file === originOf(e.file))));
8339
+ for (const e of heldExtensions) dueRules.add(e.rule);
8340
+ const snapshot = dueRules.size ? snapshotAtBase(root, options.base, files, changed, originOf) : null;
8341
+ let baseCounts;
8342
+ if (snapshot) {
8343
+ const before = [];
8344
+ await runChecks({ ...ctx, files: snapshot.files, report: (f) => before.push(f) }, baseChecks(dueRules, packageIds, packagePlugins, () => [...builtinChecks(config, { contracts: false, figma: false }), ...appChecks]));
8345
+ baseCounts = countFindings(applyConfig(before, config, packageIds));
8346
+ if (heldExtensions.length) {
8347
+ const counts = baseCounts;
8348
+ const held = new Set(heldExtensions);
8349
+ findings = applyExtensions(configured, { ...extensionCtx, limit: (e) => held.has(e) ? counts.get(countKey(originOf(e.file), e.rule)) ?? 0 : void 0 });
8350
+ }
8351
+ }
8352
+ findings = applyRatchet(findings, { config, newOnly, changed, base: options.base, isAppPath, originOf, ...snapshot && baseCounts ? { baseCounts, existedAtBase: snapshot.existed } : {} });
7836
8353
  }
8354
+ findings = dedupeFindings(findings);
8355
+ const extensionsNew = (config.extend ?? []).filter((e) => findings.some((f) => f.rule === "extension-added" && f.file === e.file && f.subject === e.rule));
7837
8356
  const errors = findings.filter((f) => f.level === "error").length;
7838
8357
  const warnings = findings.filter((f) => f.level === "warn").length;
7839
8358
  const infos = findings.length - errors - warnings;
@@ -7847,9 +8366,24 @@ async function runDoctor(options = {}) {
7847
8366
  primitives: primitivesSummary(packages),
7848
8367
  errors,
7849
8368
  warnings,
7850
- infos
8369
+ infos,
8370
+ ...extensionsNew.length ? { extensionsAdded: extensionsNew } : {}
7851
8371
  };
7852
8372
  }
8373
+ function baseChecks(rules, preferIds, packagePlugins, all) {
8374
+ if ([...rules].every((r) => preferIds.has(r))) return packagePlugins.filter((p) => p.name === "package-rules");
8375
+ return all();
8376
+ }
8377
+ async function runChecks(ctx, checks) {
8378
+ for (const plugin of checks) {
8379
+ try {
8380
+ await plugin.check(ctx);
8381
+ } catch (err) {
8382
+ if (err instanceof DoctorConfigError) throw err;
8383
+ ctx.report({ rule: "plugin-error", file: plugin.name, message: `rule plugin "${plugin.name}" threw: ${err.message}` });
8384
+ }
8385
+ }
8386
+ }
7853
8387
  function builtinChecks(config, options = {}) {
7854
8388
  const packs = {
7855
8389
  native: { name: "native", check: checkNativePack },
@@ -7875,7 +8409,10 @@ function builtinChecks(config, options = {}) {
7875
8409
  { name: "studio-server-imports", check: checkStudioServerImports },
7876
8410
  { name: "removed-scope-names", check: checkRemovedScopeNames },
7877
8411
  { name: "stability-imports", check: checkStabilityImports },
7878
- { name: "agent-guide", check: checkAgentGuide },
8412
+ { name: "agent-guide", check: (ctx) => {
8413
+ checkAgentGuide(ctx);
8414
+ checkAgentHooks(ctx);
8415
+ } },
7879
8416
  { name: "overlays", check: (ctx) => checkOverlays(ctx) },
7880
8417
  { name: "lock-files", check: checkLockFiles },
7881
8418
  { name: "database-elsewhere", check: checkDatabaseHome },
@@ -7940,10 +8477,14 @@ function formatReport(result, options = {}) {
7940
8477
  `Genesis doctor: ${g.uiPackage}@${g.uiVersion}, ${g.components.length} components, ${g.tokens.size} tokens, ${result.ruleCount} app rules; raw tags checked: ${[...g.rawTags.keys()].join(", ") || "none"}`
7941
8478
  ];
7942
8479
  for (const f of result.findings) {
7943
- lines.push(`${f.level.toUpperCase().padEnd(5)} ${f.file}${f.line ? `:${f.line}` : ""} [${f.rule}] ${f.message}`);
8480
+ lines.push(`${f.level.toUpperCase().padEnd(5)} ${f.file}${f.line ? `:${f.line}` : ""} [${(f.rules ?? [f.rule]).join(", ")}] ${f.message}`);
7944
8481
  }
7945
8482
  lines.push(options.verbose ? `Available but unused (${result.unused.length}): ${result.unused.join(", ") || "none"}` : `Available but unused: ${result.unused.length} (genesis doctor --verbose lists them)`);
7946
8483
  lines.push(`Primitives: ${result.primitives.rules} rules from ${result.primitives.packages} packages; see genesis catalog`);
8484
+ if (result.extensionsAdded?.length) {
8485
+ lines.push(`Extensions added on this branch (${result.extensionsAdded.length}); the pull request's review accepts each:`);
8486
+ for (const e of result.extensionsAdded) lines.push(` ${e.file} [${e.rule}] builds on ${e.buildsOn}: ${e.reason}${e.upstream ? ` (upstream: ${e.upstream})` : ""}`);
8487
+ }
7947
8488
  const info = result.infos ? `, ${result.infos} info` : "";
7948
8489
  lines.push(result.ok ? `PASS (${result.warnings} warnings${info})` : `FAIL (${result.errors} errors, ${result.warnings} warnings${info})`);
7949
8490
  return lines.join("\n");