@jant/core 0.8.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/dist/{app-CFsmRVJN.js → app--uxnaIRV.js} +427 -245
  2. package/dist/client/.vite/manifest.json +2 -2
  3. package/dist/client/_assets/{client-DTLBOHqD.js → client-BT6kpcuG.js} +1 -1
  4. package/dist/client/_assets/{client-auth-D6Ix6SmE.js → client-auth-begiT1tq.js} +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/node.js +2 -2
  7. package/package.json +1 -1
  8. package/src/__tests__/fixtures/releases/0.8.0/site-export/README.md +130 -0
  9. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/2thjq/_index.md +25 -0
  10. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/2u5e5/_index.md +35 -0
  11. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/0x4nv/index.md +18 -0
  12. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/_index.md +44 -0
  13. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/faqyt/index.md +30 -0
  14. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/the-potting-mix-guide-i-keep-rereading/index.md +20 -0
  15. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/5kayp/_index.md +23 -0
  16. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/5ynfs/_index.md +31 -0
  17. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/5ynfs/hu597/index.md +21 -0
  18. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/_index.md +5 -0
  19. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/a-night-heron-field-guide-for-my-walk-folder/_index.md +31 -0
  20. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/a-quiet-saturday-after-a-busy-week/_index.md +36 -0
  21. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/archive/_index.md +8 -0
  22. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/are-na-is-the-only-bookmark-pile-i-still-revisit/_index.md +30 -0
  23. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/bought-too-many-lemons-again/_index.md +37 -0
  24. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/city-walks/_index.md +12 -0
  25. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/cleanshot-for-screenshots-ocr-and-screen-recording-on-the-mac/_index.md +33 -0
  26. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/cleanshotmac-shang-de-jie-tu-ocr-lu-ping-gong-ju/_index.md +32 -0
  27. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/co344/_index.md +25 -0
  28. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/collections/_index.md +5 -0
  29. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/current-tea-rotation/_index.md +34 -0
  30. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/derek-sivers-still-writes-the-kind-of-internet-i-want-more-of/_index.md +30 -0
  31. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/desk-but-better/_index.md +25 -0
  32. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/e0kcg/_index.md +22 -0
  33. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/egi3c/_index.md +24 -0
  34. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/evf9j/_index.md +152 -0
  35. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/featured/_index.md +8 -0
  36. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-basho/_index.md +25 -0
  37. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-epictetus/_index.md +25 -0
  38. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-marcus-aurelius/_index.md +25 -0
  39. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-seneca/_index.md +26 -0
  40. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-thoreau/_index.md +25 -0
  41. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/2cl6d/index.md +18 -0
  42. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/3zqv7/index.md +30 -0
  43. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/5oxsv/index.md +18 -0
  44. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/_index.md +39 -0
  45. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gwob9/_index.md +25 -0
  46. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/home-cooking/_index.md +12 -0
  47. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/hz729/_index.md +24 -0
  48. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/inaturalist-ai-zi-ran-she-qu/_index.md +44 -0
  49. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/j4v0q/_index.md +35 -0
  50. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k278t/_index.md +25 -0
  51. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k4eee/_index.md +22 -0
  52. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/_index.md +32 -0
  53. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/a-reading-log-idea-i-might-steal/index.md +20 -0
  54. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/a83qu/index.md +18 -0
  55. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/from-seneca-5hibo/index.md +21 -0
  56. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/kan-qi-lai-bi-jiao-ku-de-gong-si-men/_index.md +41 -0
  57. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/l2m7y/_index.md +29 -0
  58. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/lan-ya-yao-kong-qi-chuang-shang-yue-du-de-fan-ye-shen-qi/_index.md +57 -0
  59. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/mynoise-for-rainy-afternoons/_index.md +30 -0
  60. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/n09le/_index.md +23 -0
  61. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/ni-fu-jin-de-wei-ji-bai-ke-tiao-mu/_index.md +42 -0
  62. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/nts-archives-are-good-cleaning-music/_index.md +30 -0
  63. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/_index.md +32 -0
  64. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/c91j0/index.md +18 -0
  65. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/qyucy/index.md +18 -0
  66. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/wsgck/index.md +18 -0
  67. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/rain-makes-my-neighborhood-look-better/_index.md +46 -0
  68. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/reading-notes/_index.md +12 -0
  69. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/s4r3e/_index.md +25 -0
  70. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/serious-eats-on-tomato-and-egg-soup/_index.md +30 -0
  71. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/_index.md +44 -0
  72. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/cxiu6/index.md +18 -0
  73. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/t77ms/index.md +18 -0
  74. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/the-soup-trick-i-always-forget/index.md +20 -0
  75. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/telk3/_index.md +30 -0
  76. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/telk3/from-thoreau-pawt2/index.md +21 -0
  77. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/the-five-minute-reset-is-still-the-best-habit-i-have/_index.md +36 -0
  78. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/the-hallway-light-took-12-minutes-and-3-months/_index.md +32 -0
  79. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/the-recurse-center-manual-is-weirdly-calming/_index.md +30 -0
  80. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/tiny-projects/_index.md +12 -0
  81. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/tong-wang-xing-fu-zhi-lu/_index.md +68 -0
  82. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/tou-ma-yan-jiang-ju-le-bu-chu-ti-yan/_index.md +62 -0
  83. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/useful-links/_index.md +12 -0
  84. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/weekend-notes/_index.md +12 -0
  85. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/what-i-actually-use-my-notebook-for/_index.md +52 -0
  86. package/src/__tests__/fixtures/releases/0.8.0/site-export/data/jant.toml +124 -0
  87. package/src/__tests__/fixtures/releases/0.8.0/site-export/hugo.toml +45 -0
  88. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/_redirects +25 -0
  89. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/15d51730a4f7-med_01kn8jtq3penf98tfq4gzmh9g9.png +0 -0
  90. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jtx8qenf98tm9ahxr48sw.webp +0 -0
  91. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jv0jdenf98tp6qr9zgjjc.webp +0 -0
  92. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jv452enf98trbkwrvhvgd.webp +0 -0
  93. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jvb16enf98txp7p0pf5ge.webp +0 -0
  94. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jve5nenf98tzap11gpxzr.webp +0 -0
  95. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jvq58enf98v538w5vsqp4.webp +0 -0
  96. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jvsaeenf98v6ct4gjzppc.webp +0 -0
  97. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jw26cenf98vc7k0ppz5k8.webp +0 -0
  98. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q1hme4e8cmby77dn66yy.webp +0 -0
  99. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q2w7e4e8cmc20036yh66.webp +0 -0
  100. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q7d2e4e8cmdeqjmyafby.webp +0 -0
  101. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q887e4e8cmdjssych7yh.webp +0 -0
  102. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167jx2f6ct88pkz45j3ycp-poster.webp +0 -0
  103. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167jx2f6ct88pkz45j3ycp.mp4 +0 -0
  104. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167mbdf6ct88pr4ga1b9kf-poster.webp +0 -0
  105. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167mbdf6ct88pr4ga1b9kf.mp4 +0 -0
  106. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167nsvf6ct88q1anhz4svb-poster.webp +0 -0
  107. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167nsvf6ct88q1anhz4svb.mp4 +0 -0
  108. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167qaxf6ct88qfndwzxx83-poster.webp +0 -0
  109. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167qaxf6ct88qfndwzxx83.mp4 +0 -0
  110. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167sm0f6ct88qw5brtsgcw.webp +0 -0
  111. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167tf8f6ct88r169s51j49.webp +0 -0
  112. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167vaaf6ct88rbx5ztenwb.webp +0 -0
  113. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167w51f6ct88rp19pybkw1.webp +0 -0
  114. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167x0nf6ct88rzajb84tw3.webp +0 -0
  115. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167xxbf6ct88s5t2300bjk.webp +0 -0
  116. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167yq5f6ct88s9pjwt5fxg.webp +0 -0
  117. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167zg4f6ct88sge8jp28ja.webp +0 -0
  118. package/src/__tests__/fixtures/releases/0.8.0/site-export/themes/jant/static/apple-touch-icon.png +0 -0
  119. package/src/__tests__/fixtures/releases/0.8.0/site-export/themes/jant/static/custom.css +0 -0
  120. package/src/__tests__/fixtures/releases/0.8.0/site-export/themes/jant/static/favicon.ico +0 -0
  121. package/src/__tests__/fixtures/releases/0.8.0/site-export/wrangler.jsonc +24 -0
  122. package/src/__tests__/fixtures/releases/0.8.0/snapshot/db.sql +322 -0
  123. package/src/__tests__/fixtures/releases/0.8.0/snapshot/meta.json +11 -0
  124. package/src/__tests__/helpers/cursor-walk.ts +52 -0
  125. package/src/__tests__/release-fixtures.test.ts +6 -2
  126. package/src/lib/__tests__/post-list-cursor.test.ts +105 -0
  127. package/src/lib/__tests__/timeline.test.ts +14 -14
  128. package/src/lib/post-list-cursor.ts +211 -0
  129. package/src/routes/api/__tests__/mcp.test.ts +58 -0
  130. package/src/routes/api/__tests__/posts.test.ts +79 -0
  131. package/src/routes/api/posts.ts +5 -9
  132. package/src/routes/api/public/__tests__/archive.test.ts +261 -0
  133. package/src/routes/api/public/__tests__/posts.test.ts +344 -19
  134. package/src/routes/api/public/archive.ts +18 -16
  135. package/src/routes/api/public/posts.ts +15 -16
  136. package/src/services/__tests__/post.test.ts +342 -36
  137. package/src/services/mcp.ts +6 -11
  138. package/src/services/post.ts +513 -319
  139. package/src/ui/shared/Pagination.tsx +1 -1
@@ -0,0 +1,11 @@
1
+ {
2
+ "format": "jant-site-snapshot",
3
+ "version": 2,
4
+ "dialect": "sqlite",
5
+ "jant": "0.8.0",
6
+ "schema": "0034_cheerful_rumiko_fujikawa",
7
+ "site": {
8
+ "id": "sit_01kn8jq3t4famtyg9hjd074ckr",
9
+ "key": "default"
10
+ }
11
+ }
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Cursor Walk Helper
3
+ *
4
+ * Follows a paginated posts endpoint the way a client does, so route tests can
5
+ * compare a walk against one unpaged request.
6
+ */
7
+
8
+ import { expect } from "vitest";
9
+
10
+ interface RequestTarget {
11
+ request(path: string): Response | Promise<Response>;
12
+ }
13
+
14
+ /**
15
+ * Follow `nextCursor` from the first page until it is null, one request per
16
+ * page, and fail on any non-200 page or a walk that doesn't end.
17
+ *
18
+ * @param app - The test app the endpoint is mounted on
19
+ * @param path - Endpoint path with its query, without `limit` or `cursor`
20
+ * @param limit - Page size
21
+ * @param from - A `nextCursor` to resume from instead of the first page
22
+ * @returns Every post ID, in the order the pages returned them
23
+ * @example
24
+ * ```ts
25
+ * expect(await walkPostPages(app, "/api/public/archive", 1)).toEqual(ids);
26
+ * ```
27
+ */
28
+ export async function walkPostPages(
29
+ app: RequestTarget,
30
+ path: string,
31
+ limit: number,
32
+ from: string | null = null,
33
+ ): Promise<string[]> {
34
+ const separator = path.includes("?") ? "&" : "?";
35
+ const ids: string[] = [];
36
+ let cursor = from;
37
+ for (let page = 0; page < 100; page++) {
38
+ const query: string = cursor
39
+ ? `limit=${limit}&cursor=${encodeURIComponent(cursor)}`
40
+ : `limit=${limit}`;
41
+ const res = await app.request(`${path}${separator}${query}`);
42
+ expect(res.status).toBe(200);
43
+ const body = (await res.json()) as {
44
+ posts: Array<{ id: string }>;
45
+ nextCursor: string | null;
46
+ };
47
+ ids.push(...body.posts.map((post) => post.id));
48
+ if (body.nextCursor === null) return ids;
49
+ cursor = body.nextCursor;
50
+ }
51
+ throw new Error(`The walk of ${path} did not end`);
52
+ }
@@ -4,8 +4,12 @@
4
4
  * `fixtures/releases/<version>/` freezes what that release wrote: a site
5
5
  * snapshot (`snapshot/meta.json` and `snapshot/db.sql`, no objects) and a
6
6
  * site export (`site-export/`, without the bundled theme's templates and
7
- * styles, which import doesn't read). Both come from the canonical demo
8
- * content at that release's tag and are never edited afterwards.
7
+ * styles, which import doesn't read). From 0.8.0 on, that release's published
8
+ * package writes both from the canonical demo content at its tag
9
+ * (`scripts/release/freeze-fixtures.mjs`). 0.7.0 and 0.7.1 are copies of the
10
+ * canonical directory at their tags, which earlier versions had written: a
11
+ * July site export and a snapshot without `jant` or `schema`. Fixtures are
12
+ * never edited afterwards.
9
13
  *
10
14
  * The canonical fixtures under `sites/demo-source/canonical/` are
11
15
  * re-exported as the demo changes, so they only prove that head reads what
@@ -0,0 +1,105 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { ValidationError } from "../errors.js";
3
+ import {
4
+ decodePostListCursor,
5
+ encodePostListCursor,
6
+ isLegacyPostListCursor,
7
+ type PostListCursorShape,
8
+ } from "../post-list-cursor.js";
9
+
10
+ const POST_ID = "pst_01jpyx3m7gw4w3h7m4bknq0v1d";
11
+ const SHAPE: PostListCursorShape = {
12
+ mode: "newest:activity:pinned",
13
+ kinds: ["number", "number", "id"],
14
+ };
15
+
16
+ /** Encode an arbitrary payload the way the codec would, for hostile inputs. */
17
+ function encodeRaw(payload: unknown): string {
18
+ return btoa(JSON.stringify(payload))
19
+ .replace(/\+/g, "-")
20
+ .replace(/\//g, "_")
21
+ .replace(/=+$/, "");
22
+ }
23
+
24
+ function decodeError(raw: string, shape = SHAPE): string {
25
+ try {
26
+ decodePostListCursor(raw, shape);
27
+ } catch (error) {
28
+ expect(error).toBeInstanceOf(ValidationError);
29
+ return (error as ValidationError).message;
30
+ }
31
+ throw new Error(`Expected ${raw} to be rejected`);
32
+ }
33
+
34
+ describe("post list cursor", () => {
35
+ it("round-trips a key tuple", () => {
36
+ const values = [-1, 1706000000, POST_ID];
37
+ const cursor = encodePostListCursor(SHAPE.mode, values);
38
+
39
+ expect(cursor).toMatch(/^[A-Za-z0-9_-]+$/);
40
+ expect(decodePostListCursor(cursor, SHAPE)).toEqual(values);
41
+ });
42
+
43
+ it("stays short enough for a URL at the widest tuple", () => {
44
+ const cursor = encodePostListCursor("rating_desc:thread_updated:pinned", [
45
+ 1706000000,
46
+ 5,
47
+ 1706000000,
48
+ POST_ID,
49
+ ]);
50
+ expect(cursor.length).toBeLessThan(200);
51
+ });
52
+
53
+ it("never looks like a bare post ID", () => {
54
+ const cursor = encodePostListCursor(SHAPE.mode, [-1, 0, POST_ID]);
55
+ expect(isLegacyPostListCursor(cursor)).toBe(false);
56
+ expect(isLegacyPostListCursor(POST_ID)).toBe(true);
57
+ expect(isLegacyPostListCursor("med_01jpyx4g9m8b4y50a4gx3t7p1n")).toBe(
58
+ false,
59
+ );
60
+ });
61
+
62
+ it("rejects a cursor that can't be read", () => {
63
+ const unreadable = decodeError("not a cursor");
64
+ for (const raw of [
65
+ "",
66
+ "a",
67
+ "%%%",
68
+ "x".repeat(600),
69
+ encodeRaw("just a string"),
70
+ encodeRaw([1, "newest:activity:pinned", []]),
71
+ encodeRaw({ s: SHAPE.mode, k: [-1, 0, POST_ID] }),
72
+ encodeRaw({ v: 1, s: SHAPE.mode }),
73
+ encodeRaw({ v: 1, s: SHAPE.mode, k: [-1, 0, POST_ID], extra: true }),
74
+ encodeRaw({ v: 1, s: 7, k: [-1, 0, POST_ID] }),
75
+ // Wrong length, wrong kinds, a fraction, an unsafe integer, a non-post ID.
76
+ encodeRaw({ v: 1, s: SHAPE.mode, k: [-1, POST_ID] }),
77
+ encodeRaw({ v: 1, s: SHAPE.mode, k: [-1, 0, POST_ID, 4] }),
78
+ encodeRaw({ v: 1, s: SHAPE.mode, k: ["-1", 0, POST_ID] }),
79
+ encodeRaw({ v: 1, s: SHAPE.mode, k: [-1, 0.5, POST_ID] }),
80
+ encodeRaw({ v: 1, s: SHAPE.mode, k: [-1, 2 ** 60, POST_ID] }),
81
+ encodeRaw({
82
+ v: 1,
83
+ s: SHAPE.mode,
84
+ k: [-1, 0, "med_01jpyx4g9m8b4y50a4gx3t7p1n"],
85
+ }),
86
+ encodeRaw({ v: 1, s: SHAPE.mode, k: [-1, 0, null] }),
87
+ ]) {
88
+ expect(decodeError(raw)).toBe(unreadable);
89
+ }
90
+ });
91
+
92
+ it("names an unknown format version", () => {
93
+ expect(
94
+ decodeError(encodeRaw({ v: 2, s: SHAPE.mode, k: [-1, 0, POST_ID] })),
95
+ ).toMatch(/different version/);
96
+ });
97
+
98
+ it("names a cursor taken in another sort mode", () => {
99
+ const cursor = encodePostListCursor("newest:published:unpinned", [
100
+ 0,
101
+ POST_ID,
102
+ ]);
103
+ expect(decodeError(cursor)).toMatch(/different order/);
104
+ });
105
+ });
@@ -219,25 +219,25 @@ describe("Timeline data assembly", () => {
219
219
  );
220
220
  }
221
221
 
222
+ const filters = { status: "published" as const, excludeReplies: true };
223
+
222
224
  // First page
223
- const page1 = await postService.list({
224
- status: "published",
225
- excludeReplies: true,
226
- limit: 3,
227
- });
228
- expect(page1).toHaveLength(3);
225
+ const page1 = await postService.listPage(filters, { limit: 3 });
226
+ expect(page1.posts).toHaveLength(3);
227
+ expect(page1.nextCursor).not.toBeNull();
229
228
 
230
229
  // Second page using cursor
231
- const lastPost = page1[page1.length - 1];
232
- expect(lastPost).toBeDefined();
233
- const page2 = await postService.list({
234
- status: "published",
235
- excludeReplies: true,
230
+ const page2 = await postService.listPage(filters, {
231
+ cursor: page1.nextCursor ?? undefined,
236
232
  limit: 3,
237
- cursor: lastPost?.id,
238
233
  });
239
- expect(page2).toHaveLength(2);
240
- expect(page2.every((p) => p.id < (lastPost?.id ?? 0))).toBe(true);
234
+ expect(page2.posts.map((post) => post.id)).toEqual(
235
+ posts
236
+ .slice(0, 2)
237
+ .map((post) => post.id)
238
+ .reverse(),
239
+ );
240
+ expect(page2.nextCursor).toBeNull();
241
241
  });
242
242
 
243
243
  it("supports offset-based pagination for page navigation", async () => {
@@ -0,0 +1,211 @@
1
+ /**
2
+ * The cursor `posts.listPage()` and `posts.listCollectionThreadRootPage()`
3
+ * hand out as `nextCursor`.
4
+ *
5
+ * A cursor says where the previous page ended: the sort mode it was taken in
6
+ * and the full sort-key tuple of that page's last row, key for key as the
7
+ * ORDER BY reads them. Resuming is a pure keyset comparison against those
8
+ * values, so the post the page ended on can be deleted, unpublished, or edited
9
+ * before the next request without moving the position. The two lists name
10
+ * their sort modes apart, so a cursor from one never resumes the other.
11
+ *
12
+ * Wire format: `base64url(JSON { v, s, k })` — format version, sort mode, and
13
+ * key tuple. It is not signed. A caller who edits one can only move their own
14
+ * position on an axis they may already read; the values are never looked up.
15
+ * Filters stay out: a position on the sort axis is valid under any filter.
16
+ *
17
+ * Callers treat the string as opaque. The one other shape still accepted is
18
+ * the bare post TypeID earlier releases returned; see
19
+ * {@link isLegacyPostListCursor}.
20
+ */
21
+
22
+ import { ValidationError } from "./errors.js";
23
+ import { ID_PREFIX, isTypeId } from "./ids.js";
24
+
25
+ /** Bumped when the payload shape changes; older versions are rejected. */
26
+ const POST_LIST_CURSOR_VERSION = 1;
27
+
28
+ /**
29
+ * Longest encoded cursor accepted. The largest tuple (pinned, rating, time,
30
+ * id) encodes to under 200 characters; the cap only keeps a hostile value from
31
+ * reaching the decoder.
32
+ */
33
+ const MAX_ENCODED_LENGTH = 512;
34
+
35
+ const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
36
+
37
+ const UNREADABLE_MESSAGE =
38
+ "This cursor can't be read. Pass back nextCursor unchanged, or leave cursor out to start from the first page.";
39
+ const VERSION_MESSAGE =
40
+ "This cursor is from a different version of Jant. Leave cursor out to start from the first page.";
41
+ const MODE_MESSAGE =
42
+ "This cursor is from a list in a different order. Leave cursor out to start from the first page.";
43
+
44
+ /**
45
+ * A legacy cursor naming a Post that is gone, or that the caller can't see.
46
+ * One message for both, so a cursor can't be used to probe for private Posts.
47
+ */
48
+ export const MISSING_LEGACY_CURSOR_MESSAGE =
49
+ "This cursor names a post that can't be found. Leave cursor out to start from the first page.";
50
+
51
+ /** What one position of the key tuple holds. */
52
+ export type PostListCursorKeyKind = "number" | "id";
53
+
54
+ /** One sort-key value: a Unix timestamp, a rating, a pin, or the post ID. */
55
+ export type PostListCursorValue = number | string;
56
+
57
+ /** What a cursor must match to resume the current request. */
58
+ export interface PostListCursorShape {
59
+ /** The request's sort mode, as the service names it. */
60
+ mode: string;
61
+ /** One kind per ORDER BY key, in ORDER BY order. */
62
+ kinds: readonly PostListCursorKeyKind[];
63
+ }
64
+
65
+ interface PostListCursorPayload {
66
+ v: number;
67
+ s: string;
68
+ k: PostListCursorValue[];
69
+ }
70
+
71
+ function encodeBase64Url(text: string): string {
72
+ return btoa(text).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
73
+ }
74
+
75
+ function decodeBase64Url(encoded: string): string | null {
76
+ const padded =
77
+ encoded.replace(/-/g, "+").replace(/_/g, "/") +
78
+ "===".slice((encoded.length + 3) % 4);
79
+ try {
80
+ return atob(padded);
81
+ } catch {
82
+ return null;
83
+ }
84
+ }
85
+
86
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
87
+ return typeof value === "object" && value !== null && !Array.isArray(value);
88
+ }
89
+
90
+ function matchesKind(
91
+ value: unknown,
92
+ kind: PostListCursorKeyKind,
93
+ ): value is PostListCursorValue {
94
+ return kind === "number"
95
+ ? Number.isSafeInteger(value)
96
+ : typeof value === "string" && isTypeId(value, ID_PREFIX.post);
97
+ }
98
+
99
+ /**
100
+ * Encode the position after a page's last row.
101
+ *
102
+ * @param mode - The sort mode the page was read in
103
+ * @param values - That row's sort-key tuple, in ORDER BY order
104
+ * @returns The opaque cursor string
105
+ * @example
106
+ * ```ts
107
+ * encodePostListCursor("newest:activity:pinned", [-1, 1706000000, post.id]);
108
+ * ```
109
+ */
110
+ export function encodePostListCursor(
111
+ mode: string,
112
+ values: readonly PostListCursorValue[],
113
+ ): string {
114
+ const payload: PostListCursorPayload = {
115
+ v: POST_LIST_CURSOR_VERSION,
116
+ s: mode,
117
+ k: [...values],
118
+ };
119
+ // Every value is ASCII — digits, a mode name, a TypeID — so `btoa` can take
120
+ // the JSON text as it is.
121
+ return encodeBase64Url(JSON.stringify(payload));
122
+ }
123
+
124
+ /**
125
+ * Decode a cursor for the current request, strictly.
126
+ *
127
+ * Nothing here falls back to the first page: a cursor that can't be read, that
128
+ * an unknown format version wrote, that was taken in another sort mode, or
129
+ * whose tuple doesn't fit the mode's keys is rejected, because answering with
130
+ * page 1 would hand the caller posts it already has.
131
+ *
132
+ * @param raw - The `cursor` the caller sent
133
+ * @param shape - The current request's sort mode and key kinds
134
+ * @returns The key tuple, in ORDER BY order
135
+ * @throws {ValidationError} When the cursor doesn't resume this request
136
+ * @example
137
+ * ```ts
138
+ * const after = decodePostListCursor(cursor, {
139
+ * mode: "newest:published:unpinned",
140
+ * kinds: ["number", "id"],
141
+ * });
142
+ * ```
143
+ */
144
+ export function decodePostListCursor(
145
+ raw: string,
146
+ shape: PostListCursorShape,
147
+ ): PostListCursorValue[] {
148
+ if (raw.length > MAX_ENCODED_LENGTH || !BASE64URL_PATTERN.test(raw)) {
149
+ throw new ValidationError(UNREADABLE_MESSAGE);
150
+ }
151
+ const text = decodeBase64Url(raw);
152
+ if (text === null) {
153
+ throw new ValidationError(UNREADABLE_MESSAGE);
154
+ }
155
+
156
+ let parsed: unknown;
157
+ try {
158
+ parsed = JSON.parse(text);
159
+ } catch {
160
+ throw new ValidationError(UNREADABLE_MESSAGE);
161
+ }
162
+ if (!isPlainObject(parsed) || !Number.isSafeInteger(parsed.v)) {
163
+ throw new ValidationError(UNREADABLE_MESSAGE);
164
+ }
165
+ if (parsed.v !== POST_LIST_CURSOR_VERSION) {
166
+ throw new ValidationError(VERSION_MESSAGE);
167
+ }
168
+
169
+ const { s: mode, k: values } = parsed;
170
+ if (
171
+ Object.keys(parsed).length !== 3 ||
172
+ typeof mode !== "string" ||
173
+ !Array.isArray(values)
174
+ ) {
175
+ throw new ValidationError(UNREADABLE_MESSAGE);
176
+ }
177
+ if (mode !== shape.mode) {
178
+ throw new ValidationError(MODE_MESSAGE);
179
+ }
180
+ if (values.length !== shape.kinds.length) {
181
+ throw new ValidationError(UNREADABLE_MESSAGE);
182
+ }
183
+ const tuple: PostListCursorValue[] = [];
184
+ for (const [index, kind] of shape.kinds.entries()) {
185
+ const value: unknown = values[index];
186
+ if (!matchesKind(value, kind)) {
187
+ throw new ValidationError(UNREADABLE_MESSAGE);
188
+ }
189
+ tuple.push(value);
190
+ }
191
+ return tuple;
192
+ }
193
+
194
+ /**
195
+ * Whether a cursor is the bare post TypeID that releases before the opaque
196
+ * format returned as `nextCursor`.
197
+ *
198
+ * Accepted indefinitely — a stored cursor, or one a client built from a post
199
+ * ID, must keep resuming. An encoded cursor can never look like one: it opens
200
+ * with the base64url of `{"`, never with `pst_`.
201
+ *
202
+ * @param raw - The `cursor` the caller sent
203
+ * @returns Whether to resolve it as a post ID
204
+ * @example
205
+ * ```ts
206
+ * isLegacyPostListCursor("pst_01jpyx3m7gw4w3h7m4bknq0v1d"); // => true
207
+ * ```
208
+ */
209
+ export function isLegacyPostListCursor(raw: string): boolean {
210
+ return isTypeId(raw, ID_PREFIX.post);
211
+ }
@@ -213,6 +213,64 @@ describe("MCP API Routes", () => {
213
213
  expect(await services.collections.getThreadIds(collection.id)).toEqual([]);
214
214
  });
215
215
 
216
+ it("pages posts through tools/call with nextCursor", async () => {
217
+ const { app, services } = createTestApp({ authenticated: true });
218
+ app.route("/api/mcp", mcpApiRoutes);
219
+
220
+ const created = [];
221
+ for (let i = 0; i < 3; i++) {
222
+ created.push(
223
+ await services.posts.create({
224
+ format: "note",
225
+ bodyMarkdown: `post ${i}`,
226
+ publishedAt: 1000 + i,
227
+ }),
228
+ );
229
+ }
230
+
231
+ const listPosts = async (args: Record<string, unknown>) => {
232
+ const res = await postMcp(
233
+ app,
234
+ {
235
+ jsonrpc: "2.0",
236
+ id: 30,
237
+ method: "tools/call",
238
+ params: { name: "jant_posts_list", arguments: args },
239
+ },
240
+ { "MCP-Protocol-Version": "2025-06-18" },
241
+ );
242
+ expect(res.status).toBe(200);
243
+ return (await res.json()).result;
244
+ };
245
+
246
+ const ids: string[] = [];
247
+ let cursor: string | undefined;
248
+ for (let page = 0; page < 5; page++) {
249
+ const result = await listPosts({
250
+ limit: 1,
251
+ ...(cursor ? { cursor } : {}),
252
+ });
253
+ expect(result.isError).toBe(false);
254
+ ids.push(
255
+ ...result.structuredContent.posts.map(
256
+ (post: { id: string }) => post.id,
257
+ ),
258
+ );
259
+ cursor = result.structuredContent.nextCursor ?? undefined;
260
+ if (!cursor) break;
261
+ }
262
+ expect(ids).toEqual(created.map((post) => post.id).reverse());
263
+
264
+ const legacy = await listPosts({ cursor: created[2]?.id });
265
+ expect(
266
+ legacy.structuredContent.posts.map((post: { id: string }) => post.id),
267
+ ).toEqual([created[1]?.id, created[0]?.id]);
268
+
269
+ const unreadable = await listPosts({ cursor: "nope" });
270
+ expect(unreadable.isError).toBe(true);
271
+ expect(unreadable.structuredContent.error).toMatch(/cursor/);
272
+ });
273
+
216
274
  it("creates posts through tools/call", async () => {
217
275
  const { app, services } = createTestApp({ authenticated: true });
218
276
  app.route("/api/mcp", mcpApiRoutes);
@@ -1,5 +1,6 @@
1
1
  import { describe, it, expect } from "vitest";
2
2
  import { createTestApp } from "../../../__tests__/helpers/app.js";
3
+ import { walkPostPages } from "../../../__tests__/helpers/cursor-walk.js";
3
4
  import { createEntityId } from "../../../lib/ids.js";
4
5
  import { postsApiRoutes } from "../posts.js";
5
6
 
@@ -143,6 +144,84 @@ describe("Posts API Routes", () => {
143
144
  expect(body.nextCursor).toBeTruthy();
144
145
  });
145
146
 
147
+ it("pages published posts and drafts with an opaque cursor", async () => {
148
+ const { app, services } = createTestApp({ authenticated: true });
149
+ app.route("/api/posts", postsApiRoutes);
150
+
151
+ const published = [];
152
+ for (let i = 0; i < 5; i++) {
153
+ published.push(
154
+ await services.posts.create({
155
+ format: "note",
156
+ bodyMarkdown: `post ${i}`,
157
+ publishedAt: 1000 + (i % 2), // Ties, broken by ID.
158
+ }),
159
+ );
160
+ }
161
+ const root = published[0];
162
+ await services.posts.create({
163
+ format: "note",
164
+ bodyMarkdown: "reply",
165
+ replyToId: root?.id,
166
+ publishedAt: 900,
167
+ });
168
+ for (let i = 0; i < 3; i++) {
169
+ await services.posts.create({
170
+ format: "note",
171
+ bodyMarkdown: `draft ${i}`,
172
+ status: "draft",
173
+ });
174
+ }
175
+
176
+ for (const path of ["/api/posts", "/api/posts?status=draft"]) {
177
+ const res = await app.request(path);
178
+ const expected = (await res.json()).posts.map(
179
+ (post: { id: string }) => post.id,
180
+ );
181
+ expect(expected.length).toBeGreaterThan(2);
182
+ for (const limit of [1, 2]) {
183
+ expect(await walkPostPages(app, path, limit)).toEqual(expected);
184
+ }
185
+ }
186
+
187
+ const first = await (await app.request("/api/posts?limit=2")).json();
188
+ expect(first.nextCursor).not.toMatch(/^pst_/);
189
+ });
190
+
191
+ it("reads a bare post ID as a cursor, and rejects one it can't use", async () => {
192
+ const { app, services } = createTestApp({ authenticated: true });
193
+ app.route("/api/posts", postsApiRoutes);
194
+
195
+ const older = await services.posts.create({
196
+ format: "note",
197
+ bodyMarkdown: "older",
198
+ publishedAt: 1000,
199
+ });
200
+ const newer = await services.posts.create({
201
+ format: "note",
202
+ bodyMarkdown: "newer",
203
+ publishedAt: 2000,
204
+ });
205
+ const draft = await services.posts.create({
206
+ format: "note",
207
+ bodyMarkdown: "draft",
208
+ status: "draft",
209
+ });
210
+
211
+ const legacy = await app.request(`/api/posts?cursor=${newer.id}`);
212
+ expect(legacy.status).toBe(200);
213
+ expect(
214
+ (await legacy.json()).posts.map((post: { id: string }) => post.id),
215
+ ).toEqual([older.id]);
216
+
217
+ // A draft is not in the published list the cursor claims to continue.
218
+ const wrongList = await app.request(`/api/posts?cursor=${draft.id}`);
219
+ expect(wrongList.status).toBe(400);
220
+ const unreadable = await app.request("/api/posts?cursor=nope");
221
+ expect(unreadable.status).toBe(400);
222
+ expect((await unreadable.json()).code).toBe("VALIDATION_ERROR");
223
+ });
224
+
146
225
  it("serializes quote attribution as sourceName/sourceUrl", async () => {
147
226
  const { app, services } = createTestApp({ authenticated: true });
148
227
  app.route("/api/posts", postsApiRoutes);
@@ -59,12 +59,10 @@ postsApiRoutes.get("/", requireAuthApi(), async (c) => {
59
59
  c.req.query(),
60
60
  );
61
61
 
62
- const posts = await c.var.services.posts.list({
63
- format,
64
- status: status ?? "published",
65
- cursor: cursor ?? undefined,
66
- limit,
67
- });
62
+ const { posts, nextCursor } = await c.var.services.posts.listPage(
63
+ { format, status: status ?? "published" },
64
+ { cursor, limit },
65
+ );
68
66
 
69
67
  // Batch load media for all posts
70
68
  const postIds = posts.map((p) => p.id);
@@ -92,9 +90,7 @@ postsApiRoutes.get("/", requireAuthApi(), async (c) => {
92
90
  ),
93
91
  }),
94
92
  ),
95
-
96
- nextCursor:
97
- posts.length === limit ? (posts[posts.length - 1]?.id ?? null) : null,
93
+ nextCursor,
98
94
  });
99
95
  });
100
96