@timber-js/app 0.2.0-alpha.221 → 0.2.0-alpha.223

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 (380) hide show
  1. package/agent-skill.md +21 -5
  2. package/dist/_chunks/{actions-BDqn4Oxj.js → actions-7dTXYJfu.js} +53 -24
  3. package/dist/_chunks/actions-7dTXYJfu.js.map +1 -0
  4. package/dist/_chunks/{als-registry-BZqHCtq-.js → als-registry-DpygwCp0.js} +2 -3
  5. package/dist/_chunks/{als-registry-BZqHCtq-.js.map → als-registry-DpygwCp0.js.map} +1 -1
  6. package/dist/_chunks/{als-slots-BEEIPKYm.js → als-slots-kbQrHTzm.js} +2 -3
  7. package/dist/_chunks/{als-slots-BEEIPKYm.js.map → als-slots-kbQrHTzm.js.map} +1 -1
  8. package/dist/_chunks/{base-path-DaQrzbez.js → base-path-DDIx0FXe.js} +2 -3
  9. package/dist/_chunks/{base-path-DaQrzbez.js.map → base-path-DDIx0FXe.js.map} +1 -1
  10. package/dist/_chunks/{build-manifest-DWppEdLB.js → build-manifest-Y4jl7nwU.js} +2 -3
  11. package/dist/_chunks/{build-manifest-DWppEdLB.js.map → build-manifest-Y4jl7nwU.js.map} +1 -1
  12. package/dist/_chunks/{build-output-helper-RV_BRcF1.js → build-output-helper-B7wWGTfR.js} +14 -10
  13. package/dist/_chunks/build-output-helper-B7wWGTfR.js.map +1 -0
  14. package/dist/_chunks/{cache-api-GE4AOe2H.js → cache-api-TDZ4hlDc.js} +237 -37
  15. package/dist/_chunks/cache-api-TDZ4hlDc.js.map +1 -0
  16. package/dist/_chunks/{canonicalize-BAWkWiKK.js → canonicalize-CqK135BN.js} +29 -4
  17. package/dist/_chunks/{canonicalize-BAWkWiKK.js.map → canonicalize-CqK135BN.js.map} +1 -1
  18. package/dist/_chunks/chains-CwOr3Myj.js +1 -0
  19. package/dist/_chunks/{chains-e_Buf9vg.js → chains-Dgm3PrMe.js} +3 -4
  20. package/dist/_chunks/{chains-e_Buf9vg.js.map → chains-Dgm3PrMe.js.map} +1 -1
  21. package/dist/_chunks/{classify-2Yp3xJY1.js → classify--_kINHQV.js} +4 -5
  22. package/dist/_chunks/{classify-2Yp3xJY1.js.map → classify--_kINHQV.js.map} +1 -1
  23. package/dist/_chunks/{cli-check-DDwCkeDY.js → cli-check-Dv3f8d2j.js} +5 -6
  24. package/dist/_chunks/{cli-check-DDwCkeDY.js.map → cli-check-Dv3f8d2j.js.map} +1 -1
  25. package/dist/_chunks/{cli-context-_mPttGGY.js → cli-context-CbZp32SK.js} +3 -4
  26. package/dist/_chunks/{cli-context-_mPttGGY.js.map → cli-context-CbZp32SK.js.map} +1 -1
  27. package/dist/_chunks/cli-context-n5hmkdla.js +1 -0
  28. package/dist/_chunks/cli-dev-status-prPMLU8G.js +138 -0
  29. package/dist/_chunks/cli-dev-status-prPMLU8G.js.map +1 -0
  30. package/dist/_chunks/cli-init-BoXOYYil.js +196 -0
  31. package/dist/_chunks/cli-init-BoXOYYil.js.map +1 -0
  32. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js → cli-schema-sync-DIPurq7X.js} +4 -5
  33. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js.map → cli-schema-sync-DIPurq7X.js.map} +1 -1
  34. package/dist/_chunks/{cli-schema-sync-CLNfXQDK.js → cli-schema-sync-uq72EZmD.js} +1 -1
  35. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js → client-dep-entries-CP7AkMCM.js} +4 -5
  36. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js.map → client-dep-entries-CP7AkMCM.js.map} +1 -1
  37. package/dist/_chunks/{cloudflare-Byxl8FWP.js → cloudflare-B75X6u4O.js} +10 -13
  38. package/dist/_chunks/{cloudflare-Byxl8FWP.js.map → cloudflare-B75X6u4O.js.map} +1 -1
  39. package/dist/_chunks/{codec-registry-oOUxugz3.js → codec-registry-CPc6bjVl.js} +2 -3
  40. package/dist/_chunks/{codec-registry-oOUxugz3.js.map → codec-registry-CPc6bjVl.js.map} +1 -1
  41. package/dist/_chunks/{codegen-Bps1sLKJ.js → codegen-B9oWkWGf.js} +5 -8
  42. package/dist/_chunks/{codegen-Bps1sLKJ.js.map → codegen-B9oWkWGf.js.map} +1 -1
  43. package/dist/_chunks/{convention-lint-ByKJ6aqD.js → convention-lint-hZwz5wd4.js} +8 -11
  44. package/dist/_chunks/{convention-lint-ByKJ6aqD.js.map → convention-lint-hZwz5wd4.js.map} +1 -1
  45. package/dist/_chunks/dev-discovery-YnabkCKD.js +238 -0
  46. package/dist/_chunks/dev-discovery-YnabkCKD.js.map +1 -0
  47. package/dist/_chunks/{dev-server-DIy-SY-J.js → dev-server-C61GWpGg.js} +409 -51
  48. package/dist/_chunks/dev-server-C61GWpGg.js.map +1 -0
  49. package/dist/_chunks/dev-server-CBvvM7Lr.js +1 -0
  50. package/dist/_chunks/{dev-store-BOa304m_.js → dev-store-BvdqtHvK.js} +82 -38
  51. package/dist/_chunks/dev-store-BvdqtHvK.js.map +1 -0
  52. package/dist/_chunks/{dist-DtrJyBbw.js → dist-C1Rjlo6s.js} +3 -5
  53. package/dist/_chunks/{dist-DtrJyBbw.js.map → dist-C1Rjlo6s.js.map} +1 -1
  54. package/dist/_chunks/{error-boundary-Bc8QPZuq.js → error-boundary-DRQXGWCp.js} +20 -27
  55. package/dist/_chunks/{error-boundary-Bc8QPZuq.js.map → error-boundary-DRQXGWCp.js.map} +1 -1
  56. package/dist/_chunks/{fast-hash-C-tVYrLb.js → fast-hash-DddxkU5Y.js} +2 -3
  57. package/dist/_chunks/{fast-hash-C-tVYrLb.js.map → fast-hash-DddxkU5Y.js.map} +1 -1
  58. package/dist/_chunks/{flight-source-node-HptmGMT8.js → flight-source-node-0Tp6evlz.js} +6 -8
  59. package/dist/_chunks/flight-source-node-0Tp6evlz.js.map +1 -0
  60. package/dist/_chunks/{format-BKclgVbk.js → format-DuPOoXUP.js} +2 -3
  61. package/dist/_chunks/{format-BKclgVbk.js.map → format-DuPOoXUP.js.map} +1 -1
  62. package/dist/_chunks/{fs-identity-BRKuL215.js → fs-identity-BmQ_Agg-.js} +3 -5
  63. package/dist/_chunks/{fs-identity-BRKuL215.js.map → fs-identity-BmQ_Agg-.js.map} +1 -1
  64. package/dist/_chunks/global-context-DbxNWeBP.js +47 -0
  65. package/dist/_chunks/global-context-DbxNWeBP.js.map +1 -0
  66. package/dist/_chunks/{graph-cache-CYiUS2aS.js → graph-cache-B1LAg4t7.js} +5 -89
  67. package/dist/_chunks/graph-cache-B1LAg4t7.js.map +1 -0
  68. package/dist/_chunks/{href-validation-BIrxavIy.js → href-validation-CEZy1V-k.js} +4 -7
  69. package/dist/_chunks/{href-validation-BIrxavIy.js.map → href-validation-CEZy1V-k.js.map} +1 -1
  70. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js → json-lossy-check-DVkLUlfC.js} +3 -4
  71. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js.map → json-lossy-check-DVkLUlfC.js.map} +1 -1
  72. package/dist/_chunks/{live-graph-tSWrv8eH.js → live-graph-BcVjQ1Te.js} +6 -7
  73. package/dist/_chunks/{live-graph-tSWrv8eH.js.map → live-graph-BcVjQ1Te.js.map} +1 -1
  74. package/dist/_chunks/{logger-CbLdcy-W.js → logger-CWk44DLp.js} +97 -47
  75. package/dist/_chunks/logger-CWk44DLp.js.map +1 -0
  76. package/dist/_chunks/{metadata-routes-B3XJNyIH.js → metadata-routes-BL26HCDd.js} +2 -3
  77. package/dist/_chunks/{metadata-routes-B3XJNyIH.js.map → metadata-routes-BL26HCDd.js.map} +1 -1
  78. package/dist/_chunks/{navigation-root-BQfo1-kG.js → navigation-root-M3B2ZrdO.js} +6 -10
  79. package/dist/_chunks/{navigation-root-BQfo1-kG.js.map → navigation-root-M3B2ZrdO.js.map} +1 -1
  80. package/dist/_chunks/{node-response-rkQqcFGq.js → node-response-B9aviPDa.js} +43 -9
  81. package/dist/_chunks/node-response-B9aviPDa.js.map +1 -0
  82. package/dist/_chunks/{param-value-C8TNYchQ.js → param-value-DqlGfF57.js} +2 -3
  83. package/dist/_chunks/{param-value-C8TNYchQ.js.map → param-value-DqlGfF57.js.map} +1 -1
  84. package/dist/_chunks/{plugin-context-uDHFqHHJ.js → plugin-context-BfSRKJfz.js} +1 -1
  85. package/dist/_chunks/{plugin-context-DxMMvjUt.js → plugin-context-FCkaNLUB.js} +4 -6
  86. package/dist/_chunks/plugin-context-FCkaNLUB.js.map +1 -0
  87. package/dist/_chunks/{poison-rules-DoEhbqaY.js → poison-rules-Bmz-lCPi.js} +2 -3
  88. package/dist/_chunks/{poison-rules-DoEhbqaY.js.map → poison-rules-Bmz-lCPi.js.map} +1 -1
  89. package/dist/_chunks/{poison-scan-C4FgMxFl.js → poison-scan-DJYxZc_7.js} +4 -5
  90. package/dist/_chunks/{poison-scan-C4FgMxFl.js.map → poison-scan-DJYxZc_7.js.map} +1 -1
  91. package/dist/_chunks/{purge-store-WZaxu-3m.js → purge-store-8BqLAYZ1.js} +2 -3
  92. package/dist/_chunks/{purge-store-WZaxu-3m.js.map → purge-store-8BqLAYZ1.js.map} +1 -1
  93. package/dist/_chunks/{render-timeout-joFhz4KH.js → render-timeout-MrrqD1wd.js} +20 -4
  94. package/dist/_chunks/{render-timeout-joFhz4KH.js.map → render-timeout-MrrqD1wd.js.map} +1 -1
  95. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js → resolve-schema-B-aCuTu3.js} +3 -4
  96. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js.map → resolve-schema-B-aCuTu3.js.map} +1 -1
  97. package/dist/_chunks/{rsc-cache-key-ClUiXQnK.js → rsc-cache-key-D0cb0Gmc.js} +2 -3
  98. package/dist/_chunks/{rsc-cache-key-ClUiXQnK.js.map → rsc-cache-key-D0cb0Gmc.js.map} +1 -1
  99. package/dist/_chunks/{rsc-media-type-DDc7duTD.js → rsc-media-type-m8jz9u6_.js} +2 -3
  100. package/dist/_chunks/{rsc-media-type-DDc7duTD.js.map → rsc-media-type-m8jz9u6_.js.map} +1 -1
  101. package/dist/_chunks/{rsc-payload-path-dffcs4jp.js → rsc-payload-path-EphpDB-J.js} +2 -3
  102. package/dist/_chunks/{rsc-payload-path-dffcs4jp.js.map → rsc-payload-path-EphpDB-J.js.map} +1 -1
  103. package/dist/_chunks/{scan-BoP17W3w.js → scan-CyizcBiX.js} +2 -3
  104. package/dist/_chunks/{scan-BoP17W3w.js.map → scan-CyizcBiX.js.map} +1 -1
  105. package/dist/_chunks/{scanner-Cb3fSjAC.js → scanner-CJC-ScJU.js} +15 -23
  106. package/dist/_chunks/{scanner-Cb3fSjAC.js.map → scanner-CJC-ScJU.js.map} +1 -1
  107. package/dist/_chunks/{schema-bridge-C83xa9lT.js → schema-bridge-DyRs3cqy.js} +61 -25
  108. package/dist/_chunks/schema-bridge-DyRs3cqy.js.map +1 -0
  109. package/dist/_chunks/{segment-classify-C539Pa2O.js → segment-classify-Ho8jXWeC.js} +3 -5
  110. package/dist/_chunks/{segment-classify-C539Pa2O.js.map → segment-classify-Ho8jXWeC.js.map} +1 -1
  111. package/dist/_chunks/{segment-context-xtPUGfdq.js → segment-context-CYiGTi3K.js} +6 -12
  112. package/dist/_chunks/segment-context-CYiGTi3K.js.map +1 -0
  113. package/dist/_chunks/{segment-keys-D5hu1hz4.js → segment-keys-Y60KNc8C.js} +2 -3
  114. package/dist/_chunks/{segment-keys-D5hu1hz4.js.map → segment-keys-Y60KNc8C.js.map} +1 -1
  115. package/dist/_chunks/{singleflight-BeVMMKi0.js → singleflight-BChPMjwH.js} +2 -3
  116. package/dist/_chunks/{singleflight-BeVMMKi0.js.map → singleflight-BChPMjwH.js.map} +1 -1
  117. package/dist/_chunks/{sizeof-QPE5nd3u.js → sizeof-DG4W40lv.js} +3 -4
  118. package/dist/_chunks/{sizeof-QPE5nd3u.js.map → sizeof-DG4W40lv.js.map} +1 -1
  119. package/dist/_chunks/{ssr-data-nA3I70_n.js → ssr-data-9hPtcNOr.js} +3 -4
  120. package/dist/_chunks/{ssr-data-nA3I70_n.js.map → ssr-data-9hPtcNOr.js.map} +1 -1
  121. package/dist/_chunks/{state-BhNGPsdi.js → state-B-EBjeER.js} +2 -3
  122. package/dist/_chunks/{state-BhNGPsdi.js.map → state-B-EBjeER.js.map} +1 -1
  123. package/dist/_chunks/{status-page-marker-BRX9Ib-d.js → status-page-marker-XIQXlTOb.js} +8 -13
  124. package/dist/_chunks/{status-page-marker-BRX9Ib-d.js.map → status-page-marker-XIQXlTOb.js.map} +1 -1
  125. package/dist/_chunks/{tree-match-6yihorhk.js → tree-match-Bqdr9szG.js} +2 -3
  126. package/dist/_chunks/{tree-match-6yihorhk.js.map → tree-match-Bqdr9szG.js.map} +1 -1
  127. package/dist/_chunks/{use-query-states-I3JMng6J.js → use-query-states-pkDV-jSg.js} +4 -7
  128. package/dist/_chunks/{use-query-states-I3JMng6J.js.map → use-query-states-pkDV-jSg.js.map} +1 -1
  129. package/dist/_chunks/{walkers-qu8TpiLh.js → walkers-DIE203ir.js} +6 -8
  130. package/dist/_chunks/{walkers-qu8TpiLh.js.map → walkers-DIE203ir.js.map} +1 -1
  131. package/dist/_chunks/{write-file-atomic-D1qWqHb4.js → write-file-atomic-DW8m_Atv.js} +2 -3
  132. package/dist/_chunks/{write-file-atomic-D1qWqHb4.js.map → write-file-atomic-DW8m_Atv.js.map} +1 -1
  133. package/dist/adapters/build-output-helper.d.ts +10 -1
  134. package/dist/adapters/build-output-helper.d.ts.map +1 -1
  135. package/dist/adapters/cloudflare-dev.js +2 -3
  136. package/dist/adapters/cloudflare-kv-cache.js +3 -4
  137. package/dist/adapters/cloudflare.d.ts.map +1 -1
  138. package/dist/adapters/cloudflare.js +1 -1
  139. package/dist/adapters/nitro-presets.d.ts +6 -0
  140. package/dist/adapters/nitro-presets.d.ts.map +1 -1
  141. package/dist/adapters/nitro-preview.d.ts.map +1 -1
  142. package/dist/adapters/nitro.d.ts.map +1 -1
  143. package/dist/adapters/nitro.js +94 -57
  144. package/dist/adapters/nitro.js.map +1 -1
  145. package/dist/analyze/crawl-entry.js +7 -9
  146. package/dist/analyze/crawl-entry.js.map +1 -1
  147. package/dist/analyze/graph-command.d.ts.map +1 -1
  148. package/dist/analyze/graph-command.js +19 -105
  149. package/dist/analyze/graph-command.js.map +1 -1
  150. package/dist/cache/guarded-read.d.ts +29 -0
  151. package/dist/cache/guarded-read.d.ts.map +1 -0
  152. package/dist/cache/index.js +3 -3
  153. package/dist/cache/key-discipline.d.ts +61 -0
  154. package/dist/cache/key-discipline.d.ts.map +1 -0
  155. package/dist/cache/stores/cloudflare-kv.js +1 -2
  156. package/dist/cache/stores/memory.js +2 -3
  157. package/dist/cache/stores/redis.js +1 -2
  158. package/dist/cache/stores/vercel.js +1 -2
  159. package/dist/cache/timber-cache.d.ts +5 -1
  160. package/dist/cache/timber-cache.d.ts.map +1 -1
  161. package/dist/cdn/cloudflare-purge.js +1 -2
  162. package/dist/cdn/fastly-purge.js +1 -2
  163. package/dist/cdn/index.js +2 -3
  164. package/dist/cdn/workers-cache-purge.js +3 -5
  165. package/dist/cdn/workers-cache-purge.js.map +1 -1
  166. package/dist/cli-dev-status.d.ts +75 -0
  167. package/dist/cli-dev-status.d.ts.map +1 -0
  168. package/dist/cli-init.d.ts +72 -0
  169. package/dist/cli-init.d.ts.map +1 -0
  170. package/dist/cli.d.ts +4 -12
  171. package/dist/cli.d.ts.map +1 -1
  172. package/dist/cli.js +27 -54
  173. package/dist/cli.js.map +1 -1
  174. package/dist/client/error-boundary.d.ts.map +1 -1
  175. package/dist/client/error-boundary.js +1 -1
  176. package/dist/client/global-context.d.ts +21 -1
  177. package/dist/client/global-context.d.ts.map +1 -1
  178. package/dist/client/index.js +23 -44
  179. package/dist/client/index.js.map +1 -1
  180. package/dist/client/internal.js +13 -18
  181. package/dist/client/internal.js.map +1 -1
  182. package/dist/client/navigation-context.d.ts.map +1 -1
  183. package/dist/client/params-context.d.ts.map +1 -1
  184. package/dist/client/slot-context.d.ts +2 -2
  185. package/dist/client/slot-context.d.ts.map +1 -1
  186. package/dist/client/use-cookie.d.ts +18 -5
  187. package/dist/client/use-cookie.d.ts.map +1 -1
  188. package/dist/codec.js +2 -3
  189. package/dist/config-types.d.ts +22 -5
  190. package/dist/config-types.d.ts.map +1 -1
  191. package/dist/config-validation.d.ts.map +1 -1
  192. package/dist/cookies/define-cookie.d.ts.map +1 -1
  193. package/dist/cookies/index.js +40 -67
  194. package/dist/cookies/index.js.map +1 -1
  195. package/dist/cookies/json-cookie.d.ts +4 -4
  196. package/dist/index.js +266 -229
  197. package/dist/index.js.map +1 -1
  198. package/dist/params/index.js +3 -4
  199. package/dist/plugin-context.d.ts +7 -0
  200. package/dist/plugin-context.d.ts.map +1 -1
  201. package/dist/plugins/dev-discovery.d.ts +69 -5
  202. package/dist/plugins/dev-discovery.d.ts.map +1 -1
  203. package/dist/plugins/dev-hostname.d.ts +152 -0
  204. package/dist/plugins/dev-hostname.d.ts.map +1 -0
  205. package/dist/plugins/dev-server.d.ts +6 -2
  206. package/dist/plugins/dev-server.d.ts.map +1 -1
  207. package/dist/plugins/dev-store-clear.d.ts +83 -0
  208. package/dist/plugins/dev-store-clear.d.ts.map +1 -0
  209. package/dist/plugins/graph-endpoint.d.ts +4 -2
  210. package/dist/plugins/graph-endpoint.d.ts.map +1 -1
  211. package/dist/plugins/prebuilt.d.ts.map +1 -1
  212. package/dist/routing/index.js +4 -4
  213. package/dist/rsc-runtime/rsc.d.ts +2 -1
  214. package/dist/rsc-runtime/rsc.d.ts.map +1 -1
  215. package/dist/rsc-runtime/server-references.d.ts +8 -0
  216. package/dist/rsc-runtime/server-references.d.ts.map +1 -0
  217. package/dist/schema-bridge.d.ts +28 -19
  218. package/dist/schema-bridge.d.ts.map +1 -1
  219. package/dist/search-params/define.d.ts +1 -1
  220. package/dist/search-params/define.d.ts.map +1 -1
  221. package/dist/search-params/index.js +11 -14
  222. package/dist/search-params/index.js.map +1 -1
  223. package/dist/search-params/wrappers.d.ts +3 -3
  224. package/dist/server/access-gate.d.ts +12 -0
  225. package/dist/server/access-gate.d.ts.map +1 -1
  226. package/dist/server/canonicalize.d.ts +21 -0
  227. package/dist/server/canonicalize.d.ts.map +1 -1
  228. package/dist/server/cookie-context.d.ts +8 -1
  229. package/dist/server/cookie-context.d.ts.map +1 -1
  230. package/dist/server/flight-source-node.d.ts.map +1 -1
  231. package/dist/server/flight-source.d.ts.map +1 -1
  232. package/dist/server/index.d.ts +1 -1
  233. package/dist/server/index.d.ts.map +1 -1
  234. package/dist/server/index.js +8 -13
  235. package/dist/server/index.js.map +1 -1
  236. package/dist/server/interception-gates.d.ts +49 -0
  237. package/dist/server/interception-gates.d.ts.map +1 -0
  238. package/dist/server/internal.js +1080 -959
  239. package/dist/server/internal.js.map +1 -1
  240. package/dist/server/logger.d.ts +26 -0
  241. package/dist/server/logger.d.ts.map +1 -1
  242. package/dist/server/param-coercion.d.ts +8 -0
  243. package/dist/server/param-coercion.d.ts.map +1 -1
  244. package/dist/server/pipeline-interception.d.ts +34 -4
  245. package/dist/server/pipeline-interception.d.ts.map +1 -1
  246. package/dist/server/pipeline-metadata-route.d.ts +24 -0
  247. package/dist/server/pipeline-metadata-route.d.ts.map +1 -0
  248. package/dist/server/pipeline-metadata.d.ts +3 -2
  249. package/dist/server/pipeline-metadata.d.ts.map +1 -1
  250. package/dist/server/pipeline-phases.d.ts +9 -3
  251. package/dist/server/pipeline-phases.d.ts.map +1 -1
  252. package/dist/server/pipeline.d.ts +18 -0
  253. package/dist/server/pipeline.d.ts.map +1 -1
  254. package/dist/server/prebuilt/dev-store.d.ts +68 -22
  255. package/dist/server/prebuilt/dev-store.d.ts.map +1 -1
  256. package/dist/server/prebuilt/overlay.d.ts +17 -3
  257. package/dist/server/prebuilt/overlay.d.ts.map +1 -1
  258. package/dist/server/prebuilt-runtime.d.ts.map +1 -1
  259. package/dist/server/primitives.d.ts +13 -0
  260. package/dist/server/primitives.d.ts.map +1 -1
  261. package/dist/server/render-utils.d.ts +21 -0
  262. package/dist/server/render-utils.d.ts.map +1 -1
  263. package/dist/server/request-context.d.ts +14 -0
  264. package/dist/server/request-context.d.ts.map +1 -1
  265. package/dist/server/route-element-builder.d.ts.map +1 -1
  266. package/dist/server/route-handler.d.ts +7 -0
  267. package/dist/server/route-handler.d.ts.map +1 -1
  268. package/dist/server/route-matcher.d.ts +14 -3
  269. package/dist/server/route-matcher.d.ts.map +1 -1
  270. package/dist/server/rsc-entry/api-handler.d.ts.map +1 -1
  271. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  272. package/dist/server/rsc-entry/rsc-stream.d.ts.map +1 -1
  273. package/dist/server/signal-identity.d.ts +6 -0
  274. package/dist/server/signal-identity.d.ts.map +1 -1
  275. package/dist/server/traced-access.d.ts +18 -0
  276. package/dist/server/traced-access.d.ts.map +1 -0
  277. package/dist/server/tracing.d.ts.map +1 -1
  278. package/dist/server/types.d.ts +5 -4
  279. package/dist/server/types.d.ts.map +1 -1
  280. package/dist/shims/font-google.js +1 -2
  281. package/dist/shims/font-local.js +1 -2
  282. package/dist/shims/headers.d.ts +11 -4
  283. package/dist/shims/headers.d.ts.map +1 -1
  284. package/docs/api/30-api-server.mdx +3 -1
  285. package/docs/api/32-api-cache.mdx +1 -1
  286. package/docs/api/33-api-search-params.mdx +3 -1
  287. package/docs/api/34-api-config.mdx +22 -0
  288. package/docs/api/36-cli.mdx +72 -6
  289. package/docs/learn/01-quick-start.mdx +1 -1
  290. package/docs/learn/06-typed-params.mdx +4 -4
  291. package/docs/learn/10-caching.mdx +26 -5
  292. package/llms.txt +1 -1
  293. package/package.json +12 -12
  294. package/src/adapters/build-output-helper.ts +26 -4
  295. package/src/adapters/cloudflare.ts +1 -0
  296. package/src/adapters/nitro-presets.ts +15 -0
  297. package/src/adapters/nitro-preview.ts +66 -34
  298. package/src/adapters/nitro.ts +14 -6
  299. package/src/analyze/graph-command.ts +25 -133
  300. package/src/cache/guarded-read.ts +44 -0
  301. package/src/cache/key-discipline.ts +218 -0
  302. package/src/cache/timber-cache.ts +46 -7
  303. package/src/cli-dev-status.ts +196 -0
  304. package/src/cli-init.ts +278 -0
  305. package/src/cli.ts +33 -79
  306. package/src/client/error-boundary.tsx +19 -2
  307. package/src/client/global-context.ts +42 -14
  308. package/src/client/navigation-context.ts +4 -11
  309. package/src/client/params-context.ts +5 -17
  310. package/src/client/segment-update-context.ts +1 -1
  311. package/src/client/slot-content-cache-context.ts +1 -1
  312. package/src/client/slot-context.ts +6 -17
  313. package/src/client/use-cookie.ts +33 -21
  314. package/src/config-types.ts +22 -5
  315. package/src/config-validation.ts +17 -0
  316. package/src/cookies/define-cookie.ts +10 -46
  317. package/src/cookies/json-cookie.ts +4 -4
  318. package/src/plugin-context.ts +7 -0
  319. package/src/plugins/dev-discovery.ts +216 -6
  320. package/src/plugins/dev-hostname.ts +322 -0
  321. package/src/plugins/dev-server.ts +130 -37
  322. package/src/plugins/dev-store-clear.ts +145 -0
  323. package/src/plugins/graph-endpoint.ts +15 -3
  324. package/src/plugins/prebuilt.ts +9 -0
  325. package/src/rsc-runtime/rsc.ts +7 -3
  326. package/src/rsc-runtime/server-references.ts +73 -0
  327. package/src/rsc-runtime/vendor-types.d.ts +17 -0
  328. package/src/schema-bridge.ts +93 -38
  329. package/src/search-params/define.ts +5 -6
  330. package/src/search-params/wrappers.ts +3 -3
  331. package/src/server/access-gate.tsx +32 -20
  332. package/src/server/action-handler.ts +58 -36
  333. package/src/server/canonicalize.ts +27 -0
  334. package/src/server/cookie-context.ts +11 -3
  335. package/src/server/flight-source-node.ts +5 -2
  336. package/src/server/flight-source.ts +4 -3
  337. package/src/server/index.ts +6 -1
  338. package/src/server/interception-gates.ts +94 -0
  339. package/src/server/logger.ts +32 -0
  340. package/src/server/param-coercion.ts +22 -0
  341. package/src/server/pipeline-interception.ts +64 -4
  342. package/src/server/pipeline-metadata-route.ts +242 -0
  343. package/src/server/pipeline-metadata.ts +7 -5
  344. package/src/server/pipeline-phases.ts +71 -131
  345. package/src/server/pipeline.ts +20 -2
  346. package/src/server/prebuilt/dev-store.ts +113 -34
  347. package/src/server/prebuilt/overlay.ts +32 -4
  348. package/src/server/prebuilt-runtime.ts +63 -45
  349. package/src/server/primitives.ts +14 -0
  350. package/src/server/render-utils.ts +25 -0
  351. package/src/server/request-context.ts +27 -3
  352. package/src/server/route-element-builder.ts +15 -2
  353. package/src/server/route-handler.ts +3 -2
  354. package/src/server/route-matcher.ts +48 -33
  355. package/src/server/rsc-entry/api-handler.ts +2 -33
  356. package/src/server/rsc-entry/index.ts +8 -3
  357. package/src/server/rsc-entry/rsc-stream.ts +7 -1
  358. package/src/server/signal-identity.ts +30 -12
  359. package/src/server/traced-access.ts +50 -0
  360. package/src/server/tracing.ts +18 -1
  361. package/src/server/types.ts +5 -4
  362. package/src/shims/headers.ts +12 -4
  363. package/dist/_chunks/actions-BDqn4Oxj.js.map +0 -1
  364. package/dist/_chunks/build-output-helper-RV_BRcF1.js.map +0 -1
  365. package/dist/_chunks/cache-api-GE4AOe2H.js.map +0 -1
  366. package/dist/_chunks/chains-CDK1AWZQ.js +0 -1
  367. package/dist/_chunks/cli-context-BJQB6rtF.js +0 -1
  368. package/dist/_chunks/dev-server-BiWNMBVU.js +0 -1
  369. package/dist/_chunks/dev-server-DIy-SY-J.js.map +0 -1
  370. package/dist/_chunks/dev-store-BOa304m_.js.map +0 -1
  371. package/dist/_chunks/flight-source-node-HptmGMT8.js.map +0 -1
  372. package/dist/_chunks/graph-cache-CYiUS2aS.js.map +0 -1
  373. package/dist/_chunks/logger-CbLdcy-W.js.map +0 -1
  374. package/dist/_chunks/node-response-rkQqcFGq.js.map +0 -1
  375. package/dist/_chunks/plugin-context-DxMMvjUt.js.map +0 -1
  376. package/dist/_chunks/schema-bridge-C83xa9lT.js.map +0 -1
  377. package/dist/_chunks/segment-context-xtPUGfdq.js.map +0 -1
  378. package/dist/server/prebuilt/key-discipline.d.ts +0 -52
  379. package/dist/server/prebuilt/key-discipline.d.ts.map +0 -1
  380. package/src/server/prebuilt/key-discipline.ts +0 -122
@@ -0,0 +1,218 @@
1
+ /**
2
+ * Key-discipline diagnostic for both cache tiers (design/45 §Enforcement).
3
+ *
4
+ * A cached value is stored under a key computed from declared inputs only —
5
+ * props and segment params for `cache.component`, the function's arguments
6
+ * for `cache.data`. A request-context read while the value is being computed
7
+ * is the data-leak danger zone (design/06 security note): the result varies
8
+ * by user but the key does not. While the cached work runs, the ALS store is
9
+ * wrapped in a transparent observing proxy; any request-context read
10
+ * produces a structured, rate-limited production diagnostic.
11
+ *
12
+ * The diagnostic fires per offending callsite, rate-limited to once per
13
+ * interval (default 60 s) — not once per process. This ensures the
14
+ * signal stays visible in log aggregators across restarts and deploys.
15
+ *
16
+ * When `strictKeyDiscipline` is enabled (via timber.config.ts
17
+ * `cache.strictKeyDiscipline: true`), the diagnostic is promoted to a
18
+ * thrown error that prevents the tainted value from being cached.
19
+ */
20
+
21
+ import { requestContextAls, type RequestContextStore } from '../server/als-registry.ts';
22
+ import { logKeyDisciplineViolation } from '../server/logger.ts';
23
+
24
+ /** Store fields every tier's key leaves out, by the API that reads them. */
25
+ const REQUEST_FIELDS: ReadonlyMap<PropertyKey, string> = new Map([
26
+ ['headers', 'headers()'],
27
+ ['parsedCookies', 'cookies()'],
28
+ ['searchParams', 'searchParams'],
29
+ ]);
30
+
31
+ /**
32
+ * The data tier also leaves out segment params: a cache.component key
33
+ * includes them, a cache.data key holds only the function's arguments.
34
+ */
35
+ const DATA_TIER_FIELDS: ReadonlyMap<PropertyKey, string> = new Map([
36
+ ...REQUEST_FIELDS,
37
+ ['segmentParams', 'segment params'],
38
+ ['slotParams', 'segment params'],
39
+ ]);
40
+
41
+ /** Which cache tier a callsite belongs to — selects the diagnostic wording. */
42
+ export type KeyDisciplineTier = 'cache.component' | 'cache.data';
43
+
44
+ /** A cached callsite whose work is observed for request-context reads. */
45
+ export interface KeyDisciplineSite {
46
+ tier: KeyDisciplineTier;
47
+ /** Stable id of the callsite — the rate-limit key within its tier. */
48
+ id: string;
49
+ /** Human-readable name for the message; defaults to the id. */
50
+ label?: string;
51
+ /** The cache key this call computed — logged so the entry can be found. */
52
+ cacheKey?: string;
53
+ }
54
+
55
+ interface TierRules {
56
+ /** Store fields whose read is a violation, mapped to the API name logged. */
57
+ observed: ReadonlyMap<PropertyKey, string>;
58
+ keyedBy: string;
59
+ passAs: string;
60
+ work: string;
61
+ }
62
+
63
+ const TIERS: Record<KeyDisciplineTier, TierRules> = {
64
+ 'cache.component': {
65
+ observed: REQUEST_FIELDS,
66
+ keyedBy: 'props and segment params',
67
+ passAs: 'as props',
68
+ work: 'a cache capture render',
69
+ },
70
+ 'cache.data': {
71
+ observed: DATA_TIER_FIELDS,
72
+ keyedBy: "the function's arguments",
73
+ passAs: 'as an argument',
74
+ work: 'a cached call',
75
+ },
76
+ };
77
+
78
+ /** Rate-limit interval: one diagnostic per callsite per 60 seconds. */
79
+ const RATE_LIMIT_MS = 60_000;
80
+
81
+ /**
82
+ * Last emission timestamp per `${tier}:${id}`. Past this many entries,
83
+ * ones whose window has elapsed are pruned — an untransformed callsite
84
+ * re-created per request gets a fresh fallback id each time.
85
+ */
86
+ const lastEmitted = new Map<string, number>();
87
+ const PRUNE_AT = 1_000;
88
+
89
+ /**
90
+ * Thrown in strict mode. A distinct class so a caller holding an earlier
91
+ * result computed by the same fn (a stale SWR entry) can drop it.
92
+ */
93
+ export class KeyDisciplineViolation extends Error {
94
+ override name = 'KeyDisciplineViolation';
95
+ }
96
+
97
+ let strict = false;
98
+
99
+ /**
100
+ * Configure strict key-discipline mode. When true, a violation throws
101
+ * instead of logging — the tainted value is never cached.
102
+ * Called at boot from the RSC entry with the resolved config value.
103
+ */
104
+ export function setKeyDisciplineStrict(enabled: boolean): void {
105
+ strict = enabled;
106
+ }
107
+
108
+ /**
109
+ * Run a cached callsite's work under the observing proxy, then report any
110
+ * request-context read it made. The proxy is transparent — it forwards all
111
+ * reads and writes; it only observes.
112
+ *
113
+ * Outside a request context `run` executes as-is: there is nothing to read,
114
+ * and cache.data must keep working there. In default mode a callsite that
115
+ * reported within the rate-limit window is not observed at all. In strict
116
+ * mode a violation rejects after `run` resolves, so the caller never stores
117
+ * the value.
118
+ */
119
+ export async function observeKeyDiscipline<T>(
120
+ site: KeyDisciplineSite,
121
+ run: () => Promise<T>
122
+ ): Promise<T> {
123
+ const store = requestContextAls.getStore();
124
+ if (!store || !shouldCheck(site)) return run();
125
+
126
+ const { proxy, accessedApis } = createObservingProxy(store, TIERS[site.tier].observed);
127
+ const result = await requestContextAls.run(proxy, run);
128
+ if (accessedApis.size > 0) reportViolation(site, accessedApis);
129
+ return result;
130
+ }
131
+
132
+ function rateLimitKey(site: KeyDisciplineSite): string {
133
+ return `${site.tier}:${site.id}`;
134
+ }
135
+
136
+ /**
137
+ * Whether to observe this callsite on this call. Always in strict mode;
138
+ * otherwise only once the rate-limit window since its last report elapsed.
139
+ */
140
+ function shouldCheck(site: KeyDisciplineSite): boolean {
141
+ if (strict) return true;
142
+ const last = lastEmitted.get(rateLimitKey(site));
143
+ if (last === undefined) return true;
144
+ return Date.now() - last >= RATE_LIMIT_MS;
145
+ }
146
+
147
+ function createObservingProxy(
148
+ store: RequestContextStore,
149
+ observed: ReadonlyMap<PropertyKey, string>
150
+ ): {
151
+ proxy: RequestContextStore;
152
+ accessedApis: Set<string>;
153
+ } {
154
+ const accessedApis = new Set<string>();
155
+ const proxy = new Proxy(store, {
156
+ get(target, prop, receiver) {
157
+ // A Map, not an object literal: `constructor` or `toString` read
158
+ // off the store must not count as a request-context read.
159
+ const api = observed.get(prop);
160
+ if (api) accessedApis.add(api);
161
+ return Reflect.get(target, prop, receiver);
162
+ },
163
+ });
164
+ return { proxy, accessedApis };
165
+ }
166
+
167
+ /**
168
+ * Throw in strict mode; otherwise emit a structured error-level diagnostic
169
+ * through the logger (same path as render errors), rate-limited per callsite.
170
+ */
171
+ function reportViolation(site: KeyDisciplineSite, apis: Set<string>): void {
172
+ const { tier, id } = site;
173
+ const name = site.label ?? id;
174
+ const apiList = Array.from(apis).join(', ');
175
+ const wording = TIERS[tier];
176
+ const remedy =
177
+ `Either pass request-derived values ${wording.passAs} (included in the ` +
178
+ `cache key) or remove the ${apiList} call.`;
179
+
180
+ if (strict) {
181
+ throw new KeyDisciplineViolation(
182
+ `[timber] ${tier} key-discipline violation: "${name}" reads ${apiList} ` +
183
+ `during ${wording.work}. The cache key is computed from ` +
184
+ `${wording.keyedBy} only — caching this result would serve one ` +
185
+ `user's data to another. ${remedy} ` +
186
+ `To downgrade this to a warning, set cache.strictKeyDiscipline: false ` +
187
+ `in timber.config.ts.`
188
+ );
189
+ }
190
+
191
+ const now = Date.now();
192
+ const key = rateLimitKey(site);
193
+ const last = lastEmitted.get(key);
194
+ if (last !== undefined && now - last < RATE_LIMIT_MS) return;
195
+ if (lastEmitted.size >= PRUNE_AT) {
196
+ for (const [k, t] of lastEmitted) if (now - t >= RATE_LIMIT_MS) lastEmitted.delete(k);
197
+ }
198
+ lastEmitted.set(key, now);
199
+
200
+ logKeyDisciplineViolation(`${tier} cross-user data leak risk`, {
201
+ ...(tier === 'cache.component'
202
+ ? { component: name }
203
+ : { fn: name, id, cacheKey: site.cacheKey }),
204
+ accessedApis: Array.from(apis),
205
+ message:
206
+ `${tier} "${name}" reads ${apiList} but the cache key is computed ` +
207
+ `from ${wording.keyedBy} only. If the result varies by ${apiList}, ` +
208
+ `different users may see each other's cached data. ${remedy}`,
209
+ });
210
+ }
211
+
212
+ /**
213
+ * Reset all diagnostic state. Exported for tests only.
214
+ */
215
+ export function resetKeyDisciplineState(): void {
216
+ lastEmitted.clear();
217
+ strict = false;
218
+ }
@@ -7,10 +7,12 @@ import {
7
7
  wasInvalidatedSince,
8
8
  } from './invalidation-epoch.ts';
9
9
  import { addSpanEventSync } from '../server/tracing.ts';
10
- import { logSwrRefetchFailed, swallow } from '../server/logger.ts';
10
+ import { logCacheMiss, logSwrRefetchFailed, swallow } from '../server/logger.ts';
11
+ import { guardedRead } from './guarded-read.ts';
11
12
  import { getWaitUntil } from '../server/waituntil-bridge.ts';
12
13
  import { fnv1aHash } from './fast-hash.ts';
13
14
  import { devDataCacheKey } from '../server/prebuilt/dev-store.ts';
15
+ import { KeyDisciplineViolation, observeKeyDiscipline } from './key-discipline.ts';
14
16
 
15
17
  let defaultSingleflight = createSingleflight();
16
18
 
@@ -122,7 +124,11 @@ function deriveFallbackFnId(fn: (...args: any[]) => any): string {
122
124
  * configured handler once it arrives (TIM-1029)
123
125
  * - No ALS dependency for correctness — cache() works outside a request
124
126
  * context. The waitUntil ALS bridge is read optionally so the SWR
125
- * background refetch survives handler return on Workers/Lambda.
127
+ * background refetch survives handler return on Workers/Lambda, and
128
+ * inside one, fn runs under the key-discipline observer (design/45
129
+ * §Enforcement): the key comes from the arguments only, so a
130
+ * request-context read in fn is reported, or rejected in strict mode
131
+ * before the result is stored.
126
132
  *
127
133
  * Cache hits/misses are recorded as OTEL span events on the enclosing
128
134
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
@@ -137,6 +143,10 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
137
143
  // With an explicit `key` option the fnId never reaches key generation, so
138
144
  // no fallback derivation (or warning) is needed in that case.
139
145
  const fnId = stableId ?? (opts.key ? undefined : deriveFallbackFnId(fn));
146
+ // Key-discipline rate-limit id. An explicit-key callsite without a
147
+ // build-time ID has no fnId; its source hash is stable enough for a
148
+ // rate limit and, unlike deriveFallbackFnId, never warns.
149
+ const disciplineId = fnId ?? `key-fn:${fnv1aHash(fn.toString())}`;
140
150
 
141
151
  // Per-call timeoutMs gets a dedicated singleflight instance. Otherwise
142
152
  // resolve defaultSingleflight per invocation (not captured at creation
@@ -157,7 +167,7 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
157
167
  const storeKey = devDataCacheKey(key);
158
168
 
159
169
  const cacheStart = performance.now();
160
- const cached = await getHandler().get(storeKey);
170
+ const cached = await guardedRead(key, () => getHandler().get(storeKey), null);
161
171
 
162
172
  if (cached && !cached.stale) {
163
173
  // Record as OTEL span event on enclosing span (not a child span).
@@ -174,9 +184,11 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
174
184
  // key/tags: a caller arriving after an invalidation must not coalesce
175
185
  // onto a flight that started before it — it would receive the
176
186
  // pre-invalidation result the invalidation was issued to discard.
177
- // NUL separator: cannot collide with user-provided key strings.
187
+ // NUL separator: cannot collide with user-provided key strings. The
188
+ // store key, not the logical key: in dev it carries the source
189
+ // generation, so a caller after a save never joins a pre-save flight.
178
190
  const tags = resolveTags(opts, args);
179
- const flightKey = `${key}\u0000${lastInvalidationEpochFor(key, tags)}`;
191
+ const flightKey = `${storeKey}\u0000${lastInvalidationEpochFor(key, tags)}`;
180
192
 
181
193
  /**
182
194
  * Run fn and store the result — exactly once per coalesced execution,
@@ -191,7 +203,32 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
191
203
  const executeAndStore = async (signal: AbortSignal): Promise<Awaited<ReturnType<Fn>>> => {
192
204
  const startEpoch = currentInvalidationEpoch();
193
205
  const generation = nextGeneration(key);
194
- const result = await fn(...args);
206
+ // Observed on every execution — the miss path and the SWR refetch,
207
+ // which runs in the triggering request's context. Never on a hit:
208
+ // a hit runs no fn, so it reads nothing.
209
+ let result: Awaited<ReturnType<Fn>>;
210
+ try {
211
+ result = await observeKeyDiscipline(
212
+ { tier: 'cache.data', id: disciplineId, label: fn.name || undefined, cacheKey: key },
213
+ () => fn(...args)
214
+ );
215
+ } catch (err) {
216
+ // Strict key discipline rejected this fn, so any entry already
217
+ // under the key was computed by the same request-reading fn (stored
218
+ // before strict mode was on). Drop it rather than serve it to
219
+ // everyone as stale — but only under the same guards as a write: a
220
+ // timed-out or superseded flight must not delete a newer result.
221
+ if (
222
+ err instanceof KeyDisciplineViolation &&
223
+ !signal.aborted &&
224
+ writeGenerations.get(key) === generation
225
+ ) {
226
+ await getHandler()
227
+ .invalidate({ key: storeKey })
228
+ .catch((e: unknown) => swallow(e, `cache invalidate failed for key "${key}"`));
229
+ }
230
+ throw err;
231
+ }
195
232
  if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) {
196
233
  try {
197
234
  await getHandler().set(storeKey, result, { ttl: opts.ttl, tags, generation });
@@ -219,7 +256,8 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
219
256
  try {
220
257
  await executeAndStore(signal);
221
258
  } catch (err) {
222
- // Failed refetch — stale entry continues to be served.
259
+ // Failed refetch — stale entry continues to be served (unless
260
+ // executeAndStore dropped it for a key-discipline violation).
223
261
  logSwrRefetchFailed({ cacheKey: key, error: err });
224
262
  }
225
263
  })
@@ -246,6 +284,7 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
246
284
  key,
247
285
  duration_ms: Math.round(performance.now() - cacheStart),
248
286
  });
287
+ logCacheMiss({ cacheKey: key });
249
288
 
250
289
  return result;
251
290
  }) as unknown as Fn;
@@ -0,0 +1,196 @@
1
+ /**
2
+ * `timber dev status [--json]` — which dev servers are running for this app.
3
+ *
4
+ * The agent-facing answer to "is a dev server already up?" Agents that
5
+ * skip the question start a second server, Vite bumps it to the next
6
+ * port, and the agent then tests a different server than the one the user
7
+ * is watching.
8
+ *
9
+ * Servers are found through their discovery records (plugins/dev-discovery.ts)
10
+ * and listed only after the full validation: pid alive AND the server
11
+ * answers the status probe with that pid. The record format stays private;
12
+ * this command is the public contract.
13
+ *
14
+ * Worktree-aware: `.timber/` is gitignored, so each git worktree has its own
15
+ * records. A server in another worktree serves that worktree's code — never
16
+ * reuse it — but it may be holding the port this checkout would have taken,
17
+ * so it is reported separately.
18
+ *
19
+ * See design/21-dev-server.md §"`timber dev status`".
20
+ */
21
+
22
+ import { execFile } from 'node:child_process';
23
+ import { realpath } from 'node:fs/promises';
24
+ import { dirname, join, relative, resolve } from 'node:path';
25
+ import { promisify } from 'node:util';
26
+ import { readLiveDevRecords, type DevRecord } from './plugins/dev-discovery.ts';
27
+
28
+ const execFileAsync = promisify(execFile);
29
+
30
+ /** `git` must answer fast or not at all — not being a repo is normal. */
31
+ const GIT_TIMEOUT_MS = 2_000;
32
+
33
+ /** Bumped only on a breaking change to the `--json` shape. */
34
+ export const DEV_STATUS_JSON_VERSION = 1;
35
+
36
+ export interface DevStatusServer {
37
+ /** The URL the server printed — open this in a browser (`http://blog.localhost:3000/`). */
38
+ url: string;
39
+ /**
40
+ * The same server through plain `localhost` (`http://localhost:3000/`), for
41
+ * HTTP clients that resolve through the OS, which may not map `*.localhost`.
42
+ * Equal to `url` when the server has no dev hostname, or when its https
43
+ * certificate does not cover `localhost` (the named URL is then the only
44
+ * one that verifies).
45
+ */
46
+ loopbackUrl: string;
47
+ port: number;
48
+ pid: number;
49
+ }
50
+
51
+ export interface DevStatusWorktree {
52
+ /** The other worktree's root directory. */
53
+ path: string;
54
+ /** Short branch name, or null for a detached HEAD. */
55
+ branch: string | null;
56
+ /** The same app, inside that worktree. */
57
+ appRoot: string;
58
+ servers: DevStatusServer[];
59
+ }
60
+
61
+ /** The `timber dev status --json` contract. */
62
+ export interface DevStatusReport {
63
+ version: typeof DEV_STATUS_JSON_VERSION;
64
+ /** The app this checkout's servers were looked up for. */
65
+ appRoot: string;
66
+ /** Live servers serving this checkout. Reuse one of these. */
67
+ servers: DevStatusServer[];
68
+ /** Live servers in other git worktrees of the same app — different code. */
69
+ otherWorktrees: DevStatusWorktree[];
70
+ }
71
+
72
+ function toServer(record: DevRecord): DevStatusServer {
73
+ return {
74
+ url: record.url,
75
+ loopbackUrl: record.loopbackUrl,
76
+ port: record.port,
77
+ pid: record.pid,
78
+ };
79
+ }
80
+
81
+ async function liveServers(appRoot: string): Promise<DevStatusServer[]> {
82
+ return (await readLiveDevRecords(appRoot)).map(toServer).sort((a, b) => a.port - b.port);
83
+ }
84
+
85
+ interface Worktree {
86
+ path: string;
87
+ branch: string | null;
88
+ }
89
+
90
+ /** Parse `git worktree list --porcelain`, skipping bare entries. */
91
+ export function parseWorktreeList(porcelain: string): Worktree[] {
92
+ const worktrees: Worktree[] = [];
93
+ for (const stanza of porcelain.split(/\n\s*\n/)) {
94
+ let path: string | null = null;
95
+ let branch: string | null = null;
96
+ let bare = false;
97
+ for (const line of stanza.split('\n')) {
98
+ if (line.startsWith('worktree ')) path = line.slice('worktree '.length);
99
+ else if (line.startsWith('branch ')) branch = line.slice('branch '.length);
100
+ else if (line === 'bare') bare = true;
101
+ }
102
+ if (path && !bare) {
103
+ worktrees.push({ path, branch: branch?.replace(/^refs\/heads\//, '') ?? null });
104
+ }
105
+ }
106
+ return worktrees;
107
+ }
108
+
109
+ async function git(cwd: string, args: string[]): Promise<string> {
110
+ const { stdout } = await execFileAsync('git', args, { cwd, timeout: GIT_TIMEOUT_MS });
111
+ return stdout;
112
+ }
113
+
114
+ /**
115
+ * Live servers for this app in every other worktree of its repository.
116
+ * Any git failure (not a repo, no git binary, timeout) means "no other
117
+ * worktrees", silently.
118
+ */
119
+ async function otherWorktreeServers(appRoot: string): Promise<DevStatusWorktree[]> {
120
+ let toplevel: string;
121
+ let porcelain: string;
122
+ try {
123
+ toplevel = (await git(appRoot, ['rev-parse', '--show-toplevel'])).trim();
124
+ porcelain = await git(appRoot, ['worktree', 'list', '--porcelain']);
125
+ } catch {
126
+ return [];
127
+ }
128
+ // git prints resolved paths; resolve the app root too (macOS /tmp is a
129
+ // symlink) so the relative app path is computed in one path space.
130
+ const appPath = relative(await realpath(toplevel), await realpath(appRoot));
131
+ const self = resolve(toplevel);
132
+
133
+ const results = await Promise.all(
134
+ parseWorktreeList(porcelain)
135
+ .filter((worktree) => resolve(worktree.path) !== self)
136
+ .map(async (worktree): Promise<DevStatusWorktree> => {
137
+ const otherApp = join(worktree.path, appPath);
138
+ return { ...worktree, appRoot: otherApp, servers: await liveServers(otherApp) };
139
+ })
140
+ );
141
+ return results.filter((worktree) => worktree.servers.length > 0);
142
+ }
143
+
144
+ export async function collectDevStatus(appRoot: string): Promise<DevStatusReport> {
145
+ const [servers, otherWorktrees] = await Promise.all([
146
+ liveServers(appRoot),
147
+ otherWorktreeServers(appRoot),
148
+ ]);
149
+ return { version: DEV_STATUS_JSON_VERSION, appRoot, servers, otherWorktrees };
150
+ }
151
+
152
+ /** `(pid N)`, plus the plain-localhost URL when it differs from the printed one. */
153
+ function serverNote(server: DevStatusServer): string {
154
+ return server.loopbackUrl === server.url
155
+ ? `(pid ${server.pid})`
156
+ : `(pid ${server.pid}; non-browser clients: ${server.loopbackUrl})`;
157
+ }
158
+
159
+ export function formatDevStatus(report: DevStatusReport): string {
160
+ const lines: string[] = [];
161
+ if (report.servers.length === 0) {
162
+ lines.push(`[timber] No dev server is running for this checkout (${report.appRoot}).`);
163
+ } else {
164
+ lines.push(`[timber] Dev server running for this checkout (${report.appRoot}):`);
165
+ for (const server of report.servers) lines.push(` ${server.url} ${serverNote(server)}`);
166
+ }
167
+ if (report.otherWorktrees.length > 0) {
168
+ lines.push('[timber] In other git worktrees (different code — do not test against these):');
169
+ for (const worktree of report.otherWorktrees) {
170
+ const branch = worktree.branch ?? 'detached HEAD';
171
+ for (const server of worktree.servers) {
172
+ lines.push(` ${server.url} ${serverNote(server)} ${worktree.path} [${branch}]`);
173
+ }
174
+ }
175
+ }
176
+ return lines.join('\n');
177
+ }
178
+
179
+ /**
180
+ * Resolve the app root the way `timber graph` does — the directory of the
181
+ * Vite config, found by walking up from the cwd unless `--config` names it —
182
+ * then print the report. Exits 0 whether or not servers are found ("no server"
183
+ * is an answer); throws only when there is no config to anchor on.
184
+ */
185
+ export async function runDevStatus(options: { config?: string; json: boolean }): Promise<void> {
186
+ const { findViteConfigUpward } = await import('./analyze/graph-command.ts');
187
+ const configFile = options.config ? resolve(options.config) : findViteConfigUpward(process.cwd());
188
+ if (!configFile) {
189
+ throw new Error(
190
+ '[timber] No Vite config found in this directory or any parent — ' +
191
+ 'run `timber dev status` from inside a timber app, or pass --config <path>.'
192
+ );
193
+ }
194
+ const report = await collectDevStatus(dirname(configFile));
195
+ console.log(options.json ? JSON.stringify(report) : formatDevStatus(report));
196
+ }