@tuturuuu/utils 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.11.0](https://github.com/tutur3u/platform/compare/utils-v0.10.0...utils-v0.11.0) (2026-06-29)
+
+
+### Features
+
+* **infrastructure:** add rate-limit appeals ([f1e50e9](https://github.com/tutur3u/platform/commit/f1e50e9fd805dca6c80da8daab60ed24199f24ab))
+
+## [0.10.0](https://github.com/tutur3u/platform/compare/utils-v0.9.0...utils-v0.10.0) (2026-06-26)
+
+
+### Features
+
+* **cli:** support task description editing ([c72390b](https://github.com/tutur3u/platform/commit/c72390b909054af596ccbed8af6ded9f266dfdd4))
+
 ## [0.9.0](https://github.com/tutur3u/platform/compare/utils-v0.8.0...utils-v0.9.0) (2026-06-24)
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tuturuuu/utils",
   "license": "MIT",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/tutur3u/platform",
@@ -24,7 +24,7 @@
     "@tiptap/react": "3.27.1",
     "@tuturuuu/google": "0.0.2",
     "@tuturuuu/icons": "0.0.6",
-    "@tuturuuu/internal-api": "0.10.0",
+    "@tuturuuu/internal-api": "0.12.0",
     "@tuturuuu/supabase": "0.4.0",
     "@upstash/ratelimit": "^2.0.8",
     "@upstash/redis": "^1.38.0",
@@ -45,7 +45,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@tuturuuu/types": "0.11.0",
+    "@tuturuuu/types": "0.13.0",
     "@tuturuuu/typescript-config": "0.1.1",
     "@types/diff": "^8.0.0",
     "@types/node": "^26.0.0",

package/src/__tests__/api-proxy-guard.test.ts

@@ -10,6 +10,7 @@ const mocks = vi.hoisted(() => ({
   isBlocked: vi.fn(),
   validateEmoji: vi.fn(),
   getTrustEntries: vi.fn(),
+  hasAppealRelief: vi.fn(),
 }));
 
 vi.mock('@upstash/ratelimit', () => {
@@ -53,6 +54,8 @@ vi.mock('../abuse-protection/edge', () => ({
 
 vi.mock('../abuse-protection/edge-trust', () => ({
   getCachedTrustEntries: (keys: string[]) => mocks.getTrustEntries(keys),
+  hasCachedIpBlockAppealRelief: (sessionKey: string, ipKey: string) =>
+    mocks.hasAppealRelief(sessionKey, ipKey),
 }));
 
 vi.mock('../request-emoji-limit', () => ({
@@ -104,8 +107,10 @@ describe('guardApiProxyRequest', () => {
     mocks.isBlocked.mockReset();
     mocks.validateEmoji.mockReset();
     mocks.getTrustEntries.mockReset();
+    mocks.hasAppealRelief.mockReset();
     // Default: no cached trust (untrusted). Tests opt in by overriding.
     mocks.getTrustEntries.mockResolvedValue(new Map<string, { m: number }>());
+    mocks.hasAppealRelief.mockResolvedValue(false);
   });
 
   afterEach(() => {
@@ -172,6 +177,147 @@ describe('guardApiProxyRequest', () => {
     expect(mocks.limit).not.toHaveBeenCalled();
   });
 
+  it('allows a blocked IP to submit the rate-limit appeal endpoint only', async () => {
+    vi.stubEnv('NODE_ENV', 'production');
+    vi.stubEnv('UPSTASH_REDIS_REST_URL', 'https://redis.test');
+    vi.stubEnv('UPSTASH_REDIS_REST_TOKEN', 'token');
+    mocks.redis.mockReturnValue({});
+    mocks.extractIp.mockReturnValue('1.2.3.4');
+    mocks.isBlocked.mockResolvedValue({
+      expiresAt: new Date(Date.now() + 30_000),
+      reason: 'abuse',
+      blockLevel: 'temporary',
+    });
+    mocks.limit
+      .mockResolvedValueOnce({
+        success: true,
+        limit: 1,
+        remaining: 0,
+        reset: Date.now() + 15_000,
+      })
+      .mockResolvedValueOnce({
+        success: true,
+        limit: 3,
+        remaining: 2,
+        reset: Date.now() + 15_000,
+      })
+      .mockResolvedValueOnce({
+        success: true,
+        limit: 10,
+        remaining: 9,
+        reset: Date.now() + 15_000,
+      });
+    mocks.validateEmoji.mockResolvedValue(null);
+
+    const { guardApiProxyRequest, clearApiProxyGuardLimiterCache } =
+      await import('../api-proxy-guard.js');
+    clearApiProxyGuardLimiterCache();
+
+    const response = await guardApiProxyRequest(
+      makeRequest('/api/v1/rate-limit-appeals', 'POST', {
+        cookie: 'tuturuuu_app_session=session-value',
+      }),
+      {
+        prefixBase: 'proxy:test:api',
+      }
+    );
+
+    expect(response).toBeNull();
+    expect(mocks.hasAppealRelief).not.toHaveBeenCalled();
+    expect(mocks.limit).toHaveBeenCalledTimes(3);
+    expect(mocks.ratelimitConfigs).toContainEqual({
+      limit: 1,
+      window: '1 m',
+    });
+    expect(mocks.ratelimitPrefixes).toContain(
+      'proxy:test:api:rate-limit-appeal:anonymous:mutate:minute'
+    );
+  });
+
+  it('allows a blocked IP through normal APIs only with matching temporary session relief', async () => {
+    vi.stubEnv('NODE_ENV', 'production');
+    vi.stubEnv('UPSTASH_REDIS_REST_URL', 'https://redis.test');
+    vi.stubEnv('UPSTASH_REDIS_REST_TOKEN', 'token');
+    mocks.redis.mockReturnValue({});
+    mocks.extractIp.mockReturnValue('1.2.3.4');
+    mocks.isBlocked.mockResolvedValue({
+      expiresAt: new Date(Date.now() + 30_000),
+      reason: 'abuse',
+      blockLevel: 'temporary',
+    });
+    mocks.hasAppealRelief.mockResolvedValueOnce(true);
+    mocks.limit
+      .mockResolvedValueOnce({
+        success: true,
+        limit: 30,
+        remaining: 29,
+        reset: Date.now() + 15_000,
+      })
+      .mockResolvedValueOnce({
+        success: true,
+        limit: 120,
+        remaining: 119,
+        reset: Date.now() + 15_000,
+      })
+      .mockResolvedValueOnce({
+        success: true,
+        limit: 600,
+        remaining: 599,
+        reset: Date.now() + 15_000,
+      });
+    mocks.validateEmoji.mockResolvedValue(null);
+
+    const { guardApiProxyRequest, clearApiProxyGuardLimiterCache } =
+      await import('../api-proxy-guard.js');
+    clearApiProxyGuardLimiterCache();
+
+    const response = await guardApiProxyRequest(
+      makeRequest('/api/test', 'POST', {
+        cookie: 'tuturuuu_app_session=session-value',
+      }),
+      {
+        prefixBase: 'proxy:test:api',
+      }
+    );
+
+    expect(response).toBeNull();
+    expect(mocks.hasAppealRelief).toHaveBeenCalledWith(
+      expect.stringMatching(/^session:/),
+      'ip:1.2.3.4'
+    );
+    expect(mocks.limit).toHaveBeenCalledTimes(3);
+  });
+
+  it('keeps unrelated blocked sessions without temporary relief blocked', async () => {
+    vi.stubEnv('NODE_ENV', 'production');
+    mocks.extractIp.mockReturnValue('1.2.3.4');
+    mocks.isBlocked.mockResolvedValue({
+      expiresAt: new Date(Date.now() + 30_000),
+      reason: 'abuse',
+      blockLevel: 'temporary',
+    });
+    mocks.hasAppealRelief.mockResolvedValue(false);
+
+    const { guardApiProxyRequest, clearApiProxyGuardLimiterCache } =
+      await import('../api-proxy-guard.js');
+    clearApiProxyGuardLimiterCache();
+
+    const response = await guardApiProxyRequest(
+      makeRequest('/api/test', 'POST', {
+        cookie: 'tuturuuu_app_session=other-session',
+      }),
+      {
+        prefixBase: 'proxy:test:api',
+      }
+    );
+
+    expect(response?.status).toBe(429);
+    expect(response?.headers.get('X-Proxy-Block-Reason')).toBe(
+      'ip-already-blocked'
+    );
+    expect(mocks.limit).not.toHaveBeenCalled();
+  });
+
   it('rate limits anonymous generic GET routes', async () => {
     vi.stubEnv('NODE_ENV', 'production');
     vi.stubEnv('UPSTASH_REDIS_REST_URL', 'https://redis.test');

package/src/__tests__/task-description-codec.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createTaskDescriptionPayload,
+  decodeTaskDescriptionYjsState,
+  encodeTaskDescriptionYjsState,
+  parseMarkdownTaskDescriptionContent,
+  parsePersistedTaskDescriptionContent,
+  parseTaskDescriptionInput,
+  parseTaskDescriptionJson,
+  taskDescriptionPlainText,
+  taskDescriptionYjsStateFromBase64,
+  taskDescriptionYjsStateFromBytesJson,
+  taskDescriptionYjsStateToBase64,
+} from '../task-description-codec';
+
+describe('task description codec', () => {
+  it('creates storage payloads from plain text', () => {
+    const payload = createTaskDescriptionPayload(
+      'First paragraph\n\nSecond paragraph'
+    );
+
+    expect(payload.description).toContain('First paragraph');
+    expect(payload.description_yjs_state?.length ?? 0).toBeGreaterThan(0);
+    expect(taskDescriptionPlainText(payload.content)).toContain(
+      'Second paragraph'
+    );
+  });
+
+  it('parses common markdown blocks into TipTap content', () => {
+    const content = parseMarkdownTaskDescriptionContent(
+      [
+        '# Release notes',
+        '',
+        '- [x] Confirm CLI auth',
+        '- [ ] Ship task descriptions',
+        '',
+        '> Keep this scoped',
+        '',
+        'Visit [Tuturuuu](https://tuturuuu.com) with **bold** text.',
+        '',
+        '```ts',
+        'const shipped = true;',
+        '```',
+      ].join('\n')
+    );
+
+    const plainText = taskDescriptionPlainText(content);
+
+    expect(plainText).toContain('# Release notes');
+    expect(plainText).toContain('[x] Confirm CLI auth');
+    expect(plainText).toContain('> Keep this scoped');
+    expect(plainText).toContain('const shipped = true;');
+  });
+
+  it('round-trips TipTap content through Yjs base64', () => {
+    const content = parseTaskDescriptionInput(
+      JSON.stringify({
+        content: [
+          {
+            attrs: { level: 2 },
+            content: [{ text: 'Task heading', type: 'text' }],
+            type: 'heading',
+          },
+        ],
+        type: 'doc',
+      }),
+      'json'
+    );
+    const yjsState = encodeTaskDescriptionYjsState(content);
+    const encoded = taskDescriptionYjsStateToBase64(yjsState);
+    const decoded = decodeTaskDescriptionYjsState(
+      taskDescriptionYjsStateFromBase64(encoded ?? '')
+    );
+
+    expect(taskDescriptionPlainText(decoded)).toContain('Task heading');
+  });
+
+  it('rejects explicit non-doc JSON input', () => {
+    expect(() => parseTaskDescriptionJson('{"text":"not a doc"}')).toThrow(
+      /TipTap doc/
+    );
+  });
+
+  it('validates bytes JSON input', () => {
+    expect(taskDescriptionYjsStateFromBytesJson('[1,2,255]')).toEqual([
+      1, 2, 255,
+    ]);
+    expect(() => taskDescriptionYjsStateFromBytesJson('[1,999]')).toThrow(
+      /array of byte/
+    );
+  });
+
+  it('prefers persisted Yjs state over stale description JSON', () => {
+    const fresh = createTaskDescriptionPayload('Fresh state');
+    const content = parsePersistedTaskDescriptionContent({
+      description: JSON.stringify({
+        content: [
+          {
+            content: [{ text: 'Stale projection', type: 'text' }],
+            type: 'paragraph',
+          },
+        ],
+        type: 'doc',
+      }),
+      description_yjs_state: fresh.description_yjs_state,
+    });
+
+    expect(taskDescriptionPlainText(content)).toContain('Fresh state');
+  });
+});

package/src/abuse-protection/__tests__/edge-trust.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({
   getClient: vi.fn(),
+  get: vi.fn(),
   mget: vi.fn(),
   set: vi.fn(),
 }));
@@ -13,6 +14,7 @@ vi.mock('../../upstash-rest', () => ({
 function mockRedisClient() {
   mocks.getClient.mockResolvedValue({
     mget: (...keys: string[]) => mocks.mget(...keys),
+    get: (key: string) => mocks.get(key),
     set: (key: string, value: unknown, options?: unknown) =>
       mocks.set(key, value, options),
   });
@@ -22,6 +24,7 @@ describe('edge-trust cache', () => {
   beforeEach(() => {
     vi.resetModules();
     mocks.getClient.mockReset();
+    mocks.get.mockReset();
     mocks.mget.mockReset();
     mocks.set.mockReset();
   });
@@ -255,4 +258,42 @@ describe('edge-trust cache', () => {
       ex: 900,
     });
   });
+
+  it('writes and reads a session plus IP scoped appeal relief key', async () => {
+    mockRedisClient();
+    mocks.set.mockResolvedValue('OK');
+    mocks.get.mockResolvedValue('1');
+
+    const {
+      buildIpBlockAppealReliefKey,
+      hasCachedIpBlockAppealRelief,
+      setCachedIpBlockAppealRelief,
+    } = await import('../edge-trust.js');
+
+    expect(buildIpBlockAppealReliefKey('session:abc', 'ip:203.0.113.10')).toBe(
+      'trust:appeal-relief:session:abc:ip:203.0.113.10'
+    );
+
+    await setCachedIpBlockAppealRelief('session:abc', 'ip:203.0.113.10', 600);
+    expect(mocks.set).toHaveBeenCalledWith(
+      'trust:appeal-relief:session:abc:ip:203.0.113.10',
+      '1',
+      { ex: 600 }
+    );
+
+    await expect(
+      hasCachedIpBlockAppealRelief('session:abc', 'ip:203.0.113.10')
+    ).resolves.toBe(true);
+  });
+
+  it('fails closed for appeal relief when Redis is unavailable', async () => {
+    mockRedisClient();
+    mocks.get.mockRejectedValue(new Error('redis down'));
+
+    const { hasCachedIpBlockAppealRelief } = await import('../edge-trust.js');
+
+    await expect(
+      hasCachedIpBlockAppealRelief('session:abc', 'ip:203.0.113.10')
+    ).resolves.toBe(false);
+  });
 });

package/src/abuse-protection/edge-trust.ts

@@ -21,6 +21,7 @@ import {
 } from '../upstash-rest';
 
 const TRUST_CACHE_PREFIX = 'trust:mult';
+const APPEAL_RELIEF_CACHE_PREFIX = 'trust:appeal-relief';
 
 // Mirrors the DB CHECK constraint on trust_multiplier (> 0 AND <= 1000).
 const MIN_TRUST_MULTIPLIER = 0.35;
@@ -44,6 +45,7 @@ export interface CachedTrustEntry {
 }
 
 const DEFAULT_TRUST_CACHE_TTL_SECONDS = 3600; // 1 hour
+const DEFAULT_APPEAL_RELIEF_TTL_SECONDS = 15 * 60; // 15 minutes
 
 let trustRedisClient: UpstashRestRedisClient | null = null;
 let trustRedisInitialized = false;
@@ -65,6 +67,13 @@ export function getTrustCacheTtlSeconds(): number {
   );
 }
 
+export function getAppealReliefTtlSeconds(): number {
+  return parsePositiveIntEnv(
+    'RATE_LIMIT_APPEAL_RELIEF_TTL_SECONDS',
+    DEFAULT_APPEAL_RELIEF_TTL_SECONDS
+  );
+}
+
 async function getTrustRedisClient() {
   if (trustRedisInitialized) return trustRedisClient;
 
@@ -86,6 +95,13 @@ export function buildTrustCacheKey(subjectKey: string): string {
   return `${TRUST_CACHE_PREFIX}:${subjectKey}`;
 }
 
+export function buildIpBlockAppealReliefKey(
+  sessionKey: string,
+  ipKey: string
+): string {
+  return `${APPEAL_RELIEF_CACHE_PREFIX}:${sessionKey}:${ipKey}`;
+}
+
 function clampMultiplier(value: number): number {
   if (!Number.isFinite(value) || value <= 0) {
     return NEUTRAL_TRUST_MULTIPLIER;
@@ -410,3 +426,54 @@ export async function writeVerifiedSessionCacheForSubjects(
     // Cache writes must never block the protected request path.
   }
 }
+
+/**
+ * Grants a short, session+IP-scoped bypass for the hard IP-block check. This is
+ * used only after an authenticated user passes Turnstile and submits an appeal;
+ * it does not clear the global IP block or elevate unrelated sessions.
+ */
+export async function setCachedIpBlockAppealRelief(
+  sessionKey: string,
+  ipKey: string,
+  ttlSeconds: number = getAppealReliefTtlSeconds()
+): Promise<void> {
+  if (!sessionKey || !ipKey) {
+    return;
+  }
+
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return;
+    }
+
+    await redis.set(buildIpBlockAppealReliefKey(sessionKey, ipKey), '1', {
+      ex: ttlSeconds,
+    });
+  } catch {
+    // Cache writes must never block the appeal path.
+  }
+}
+
+export async function hasCachedIpBlockAppealRelief(
+  sessionKey: string,
+  ipKey: string
+): Promise<boolean> {
+  if (!sessionKey || !ipKey) {
+    return false;
+  }
+
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return false;
+    }
+
+    return Boolean(
+      await redis.get<string>(buildIpBlockAppealReliefKey(sessionKey, ipKey))
+    );
+  } catch {
+    // Fail closed for the hard-block bypass.
+    return false;
+  }
+}

package/src/api-proxy-guard.ts

@@ -5,6 +5,7 @@ import { extractIPFromRequest, isIPBlockedEdge } from './abuse-protection/edge';
 import {
   type CachedTrustEntry,
   getCachedTrustEntries,
+  hasCachedIpBlockAppealRelief,
 } from './abuse-protection/edge-trust';
 import { DEV_MODE, MAX_PAYLOAD_SIZE } from './constants';
 import { validateRequestEmojiLimit } from './request-emoji-limit';
@@ -256,6 +257,20 @@ const OTP_VERIFY_RATE_LIMITS: RateLimitProfile = {
   ],
 };
 
+const RATE_LIMIT_APPEAL_RATE_LIMITS: RateLimitProfile = {
+  get: NO_READ_RATE_LIMITS,
+  mutate: [
+    createConfig(
+      'minute',
+      '1 m',
+      1,
+      'API_PROXY_RATE_LIMIT_APPEAL_LIMIT_MINUTE'
+    ),
+    createConfig('hour', '1 h', 3, 'API_PROXY_RATE_LIMIT_APPEAL_LIMIT_HOUR'),
+    createConfig('day', '1 d', 10, 'API_PROXY_RATE_LIMIT_APPEAL_LIMIT_DAY'),
+  ],
+};
+
 const CRON_RATE_LIMITS: RateLimitProfile = {
   get: [
     createConfig('minute', '1 m', 10, 'API_PROXY_CRON_READ_LIMIT_MINUTE'),
@@ -429,7 +444,19 @@ function isWorkspaceDashboardRead(req: NextRequest) {
   );
 }
 
+function isRateLimitAppealSubmission(req: NextRequest) {
+  return (
+    req.method === 'POST' &&
+    /^\/api\/v1\/rate-limit-appeals\/?$/u.test(req.nextUrl.pathname)
+  );
+}
+
 const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
+  {
+    key: 'rate-limit-appeal',
+    matches: isRateLimitAppealSubmission,
+    rateLimits: RATE_LIMIT_APPEAL_RATE_LIMITS,
+  },
   {
     key: 'cron',
     matches: (req) =>
@@ -915,6 +942,13 @@ async function hashStableSubjectEdge(value: string): Promise<string> {
     .slice(0, 24);
 }
 
+export async function buildProxySessionSubjectKey(
+  cookieName: string,
+  cookieValue: string
+): Promise<string> {
+  return `session:${await hashStableSubjectEdge(`${cookieName}:${cookieValue}`)}`;
+}
+
 function parseCookieHeaderEdge(
   cookieHeader: string | null
 ): Array<{ name: string; value: string }> {
@@ -954,6 +988,19 @@ function getSessionAuthCookie(
   );
 }
 
+export async function getProxySessionSubjectKeyFromCookieHeader(
+  cookieHeader: string | null
+): Promise<string | null> {
+  const cookie =
+    parseCookieHeaderEdge(cookieHeader).find(
+      (entry) =>
+        entry.name === 'tuturuuu_app_session' ||
+        GENERIC_SUPABASE_AUTH_COOKIE_NAME_PATTERN.test(entry.name)
+    ) ?? null;
+
+  return cookie ? buildProxySessionSubjectKey(cookie.name, cookie.value) : null;
+}
+
 /**
  * Mirrors `reputation.ts getCidrSubjectKey` so the edge cidr subject key matches
  * the DB-side trusted-location key.
@@ -1013,7 +1060,7 @@ async function resolveProxyIdentity(
   const normalizedIp = ip && ip !== 'unknown' ? ip : null;
   const sessionCookie = getSessionAuthCookie(req);
   const sessionKey = sessionCookie
-    ? `session:${await hashStableSubjectEdge(`${sessionCookie.name}:${sessionCookie.value}`)}`
+    ? await buildProxySessionSubjectKey(sessionCookie.name, sessionCookie.value)
     : null;
 
   return {
@@ -1246,22 +1293,36 @@ export async function guardApiProxyRequest(
     const callerClass = getCallerClass(req);
     const ip = extractIPFromRequest(req.headers);
     const identity = await resolveProxyIdentity(req, ip);
+    const routePolicy = getRoutePolicy(req, routePolicies);
 
     if (ip !== 'unknown') {
       const blockInfo = await isIPBlockedEdge(ip);
       if (blockInfo) {
-        const retryAfter = Math.max(
-          1,
-          Math.ceil((blockInfo.expiresAt.getTime() - Date.now()) / 1000)
-        );
-
-        return buildRateLimitResponse(429, retryAfter, {
-          'X-Proxy-Block-Reason': 'ip-already-blocked',
-        });
+        const hasTemporaryRelief =
+          routePolicy.key === 'rate-limit-appeal' ||
+          (identity.sessionKey && identity.ipKey
+            ? await hasCachedIpBlockAppealRelief(
+                identity.sessionKey,
+                identity.ipKey
+              )
+            : false);
+
+        if (hasTemporaryRelief) {
+          // Keep processing: appeal submissions and matching temporary relief
+          // still go through the route limiter below.
+        } else {
+          const retryAfter = Math.max(
+            1,
+            Math.ceil((blockInfo.expiresAt.getTime() - Date.now()) / 1000)
+          );
+
+          return buildRateLimitResponse(429, retryAfter, {
+            'X-Proxy-Block-Reason': 'ip-already-blocked',
+          });
+        }
       }
     }
 
-    const routePolicy = getRoutePolicy(req, routePolicies);
     const isRead = req.method === 'GET' || req.method === 'HEAD';
 
     // Resolve server-verified session keying for reads and mutations, but apply

package/src/platform-release.test.ts

@@ -7,7 +7,7 @@ import {
 
 describe('platform release metadata', () => {
   it('uses the centralized shared browser app version', () => {
-    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.13.0'); // x-release-please-version
+    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.15.0'); // x-release-please-version
   });
 
   it('normalizes generated metadata and derives a short hash', () => {

package/src/platform-release.ts

@@ -1,6 +1,6 @@
 import { PLATFORM_BUILD_METADATA } from './generated/platform-build-metadata';
 
-export const TUTURUUU_PLATFORM_VERSION = '0.13.0'; // x-release-please-version
+export const TUTURUUU_PLATFORM_VERSION = '0.15.0'; // x-release-please-version
 
 export type PlatformBuildMetadataInput = {
   builtAt?: string | null;

package/src/task-description-codec.ts

@@ -0,0 +1,457 @@
+import { Buffer } from 'node:buffer';
+import type { JSONContent } from '@tiptap/core';
+import { Node as ProseMirrorNode } from 'prosemirror-model';
+import {
+  hasMeaningfulTaskDescriptionContent,
+  parseTaskDescriptionContent,
+  taskDescriptionSchema,
+} from './task-description-content';
+import { getDescriptionText } from './text-helper';
+import {
+  convertJsonContentToYjsState,
+  convertYjsStateToJsonContent,
+} from './yjs-helper';
+
+export type TaskDescriptionInputFormat = 'json' | 'markdown' | 'text';
+export type TaskDescriptionYjsFormat = 'bytes-json' | 'yjs-base64';
+
+export interface TaskDescriptionPayload {
+  content: JSONContent;
+  description: string | null;
+  description_yjs_state: number[] | null;
+}
+
+type InlineMark = NonNullable<JSONContent['marks']>[number];
+type ListKind = 'bulletList' | 'orderedList' | 'taskList';
+
+const MARK_PATTERNS = [
+  { mark: 'code', pattern: /`([^`]+)`/u },
+  { mark: 'bold', pattern: /\*\*([^*]+)\*\*/u },
+  { mark: 'strike', pattern: /~~(.+?)~~/u },
+  { mark: 'italic', pattern: /\*([^*\n]+)\*/u },
+] as const;
+
+function textNode(text: string, marks?: JSONContent['marks']): JSONContent[] {
+  if (!text) return [];
+  return marks?.length
+    ? [{ marks, text, type: 'text' }]
+    : [{ text, type: 'text' }];
+}
+
+function withMark(type: InlineMark['type'], attrs?: InlineMark['attrs']) {
+  const mark: InlineMark = { type };
+  if (attrs && Object.keys(attrs).length > 0) {
+    mark.attrs = attrs;
+  }
+  return mark;
+}
+
+function findEarliestInlineToken(text: string):
+  | {
+      attrs?: Record<string, unknown>;
+      before: string;
+      inner: string;
+      mark: InlineMark['type'];
+      rest: string;
+    }
+  | undefined {
+  const linkMatch = /\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]+)")?\)/u.exec(text);
+  let best:
+    | {
+        attrs?: Record<string, unknown>;
+        before: string;
+        inner: string;
+        index: number;
+        mark: InlineMark['type'];
+        rest: string;
+      }
+    | undefined;
+
+  if (linkMatch?.index !== undefined) {
+    best = {
+      attrs: {
+        href: linkMatch[2],
+        rel: null,
+        target: null,
+        title: linkMatch[3] ?? null,
+      },
+      before: text.slice(0, linkMatch.index),
+      index: linkMatch.index,
+      inner: linkMatch[1] ?? '',
+      mark: 'link',
+      rest: text.slice(linkMatch.index + linkMatch[0].length),
+    };
+  }
+
+  for (const { mark, pattern } of MARK_PATTERNS) {
+    const match = pattern.exec(text);
+    if (!match?.[0] || match.index === undefined) continue;
+    if (best && match.index >= best.index) continue;
+
+    best = {
+      before: text.slice(0, match.index),
+      index: match.index,
+      inner: match[1] ?? '',
+      mark,
+      rest: text.slice(match.index + match[0].length),
+    };
+  }
+
+  return best;
+}
+
+function parseInlineMarkdown(
+  text: string,
+  marks: JSONContent['marks'] = []
+): JSONContent[] {
+  const token = findEarliestInlineToken(text);
+  if (!token) return textNode(text, marks);
+
+  return [
+    ...textNode(token.before, marks),
+    ...parseInlineMarkdown(token.inner, [
+      ...marks,
+      withMark(token.mark, token.attrs),
+    ]),
+    ...parseInlineMarkdown(token.rest, marks),
+  ];
+}
+
+function paragraphFromText(text: string, markdown = false): JSONContent {
+  const lines = text.split('\n');
+  const content: JSONContent[] = [];
+
+  for (const [index, line] of lines.entries()) {
+    if (index > 0) {
+      content.push({ type: 'hardBreak' });
+    }
+    content.push(...(markdown ? parseInlineMarkdown(line) : textNode(line)));
+  }
+
+  return content.length > 0
+    ? { content, type: 'paragraph' }
+    : { type: 'paragraph' };
+}
+
+function codeBlockFromLines(lines: string[], language?: string): JSONContent {
+  return {
+    attrs: { language: language || null },
+    content:
+      lines.length > 0 ? [{ text: lines.join('\n'), type: 'text' }] : undefined,
+    type: 'codeBlock',
+  };
+}
+
+function isHorizontalRule(line: string) {
+  return /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/u.test(line);
+}
+
+function getListLine(line: string):
+  | {
+      checked?: boolean;
+      kind: ListKind;
+      start?: number;
+      text: string;
+    }
+  | undefined {
+  const taskMatch = /^\s*[-*+]\s+\[([ xX])\]\s+(.+)$/u.exec(line);
+  if (taskMatch) {
+    return {
+      checked: taskMatch[1]?.toLowerCase() === 'x',
+      kind: 'taskList',
+      text: taskMatch[2] ?? '',
+    };
+  }
+
+  const bulletMatch = /^\s*[-*+]\s+(.+)$/u.exec(line);
+  if (bulletMatch) {
+    return { kind: 'bulletList', text: bulletMatch[1] ?? '' };
+  }
+
+  const orderedMatch = /^\s*(\d+)[.)]\s+(.+)$/u.exec(line);
+  if (orderedMatch) {
+    return {
+      kind: 'orderedList',
+      start: Number.parseInt(orderedMatch[1] ?? '1', 10),
+      text: orderedMatch[2] ?? '',
+    };
+  }
+}
+
+function isBlockStart(line: string) {
+  return (
+    /^```/u.test(line) ||
+    /^#{1,6}\s+/u.test(line) ||
+    /^>\s?/u.test(line) ||
+    isHorizontalRule(line) ||
+    Boolean(getListLine(line))
+  );
+}
+
+function createListBlock(
+  kind: ListKind,
+  entries: Array<{ checked?: boolean; text: string }>,
+  start?: number
+): JSONContent {
+  if (kind === 'taskList') {
+    return {
+      content: entries.map((entry) => ({
+        attrs: { checked: entry.checked === true },
+        content: [paragraphFromText(entry.text, true)],
+        type: 'taskItem',
+      })),
+      type: 'taskList',
+    };
+  }
+
+  return {
+    attrs: kind === 'orderedList' ? { start: start ?? 1 } : undefined,
+    content: entries.map((entry) => ({
+      content: [paragraphFromText(entry.text, true)],
+      type: 'listItem',
+    })),
+    type: kind,
+  };
+}
+
+function parseMarkdownBlocks(markdown: string): JSONContent[] {
+  const lines = markdown.replace(/\r\n?/gu, '\n').split('\n');
+  const blocks: JSONContent[] = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const line = lines[index] ?? '';
+
+    if (!line.trim()) {
+      index += 1;
+      continue;
+    }
+
+    const fence = /^```([^\s`]*)\s*$/u.exec(line);
+    if (fence) {
+      const codeLines: string[] = [];
+      index += 1;
+      while (index < lines.length && !/^```\s*$/u.test(lines[index] ?? '')) {
+        codeLines.push(lines[index] ?? '');
+        index += 1;
+      }
+      if (index < lines.length) index += 1;
+      blocks.push(codeBlockFromLines(codeLines, fence[1]));
+      continue;
+    }
+
+    const heading = /^(#{1,6})\s+(.+)$/u.exec(line);
+    if (heading) {
+      blocks.push({
+        attrs: { level: heading[1]?.length ?? 1, textAlign: null },
+        content: parseInlineMarkdown(heading[2] ?? ''),
+        type: 'heading',
+      });
+      index += 1;
+      continue;
+    }
+
+    if (isHorizontalRule(line)) {
+      blocks.push({ type: 'horizontalRule' });
+      index += 1;
+      continue;
+    }
+
+    if (/^>\s?/u.test(line)) {
+      const quoted: string[] = [];
+      while (index < lines.length && /^>\s?/u.test(lines[index] ?? '')) {
+        quoted.push((lines[index] ?? '').replace(/^>\s?/u, ''));
+        index += 1;
+      }
+      const content = parseMarkdownBlocks(quoted.join('\n'));
+      blocks.push({
+        content: content.length > 0 ? content : [{ type: 'paragraph' }],
+        type: 'blockquote',
+      });
+      continue;
+    }
+
+    const listLine = getListLine(line);
+    if (listLine) {
+      const entries: Array<{ checked?: boolean; text: string }> = [];
+      const listKind = listLine.kind;
+      const start = listLine.start;
+
+      while (index < lines.length) {
+        const item = getListLine(lines[index] ?? '');
+        if (!item || item.kind !== listKind) break;
+        entries.push({ checked: item.checked, text: item.text });
+        index += 1;
+      }
+
+      blocks.push(createListBlock(listKind, entries, start));
+      continue;
+    }
+
+    const paragraphLines = [line];
+    index += 1;
+    while (
+      index < lines.length &&
+      (lines[index] ?? '').trim() &&
+      !isBlockStart(lines[index] ?? '')
+    ) {
+      paragraphLines.push(lines[index] ?? '');
+      index += 1;
+    }
+    blocks.push(paragraphFromText(paragraphLines.join('\n'), true));
+  }
+
+  return blocks;
+}
+
+export function createPlainTextTaskDescriptionContent(text: string) {
+  const normalizedText = text.replace(/\r\n?/gu, '\n');
+  const paragraphs = normalizedText.split(/\n{2,}/u);
+  const content = paragraphs.map((paragraph) =>
+    paragraphFromText(paragraph, false)
+  );
+
+  return {
+    content: content.length > 0 ? content : [{ type: 'paragraph' }],
+    type: 'doc',
+  } satisfies JSONContent;
+}
+
+export function parseMarkdownTaskDescriptionContent(markdown: string) {
+  const content = parseMarkdownBlocks(markdown);
+  return {
+    content: content.length > 0 ? content : [{ type: 'paragraph' }],
+    type: 'doc',
+  } satisfies JSONContent;
+}
+
+export function normalizeTaskDescriptionContent(
+  content: JSONContent
+): JSONContent {
+  const transformed = parseTaskDescriptionContent(JSON.stringify(content));
+  return ProseMirrorNode.fromJSON(
+    taskDescriptionSchema,
+    transformed
+  ).toJSON() as JSONContent;
+}
+
+export function parseTaskDescriptionJson(input: string): JSONContent {
+  const parsed = JSON.parse(input) as unknown;
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    Array.isArray(parsed) ||
+    (parsed as JSONContent).type !== 'doc'
+  ) {
+    throw new Error('Task description JSON must be a TipTap doc object');
+  }
+  return normalizeTaskDescriptionContent(parsed as JSONContent);
+}
+
+export function parseTaskDescriptionInput(
+  input: string,
+  format: TaskDescriptionInputFormat = 'text'
+): JSONContent {
+  if (format === 'json') {
+    return parseTaskDescriptionJson(input);
+  }
+  if (format === 'markdown') {
+    return normalizeTaskDescriptionContent(
+      parseMarkdownTaskDescriptionContent(input)
+    );
+  }
+  return normalizeTaskDescriptionContent(
+    createPlainTextTaskDescriptionContent(input)
+  );
+}
+
+export function parsePersistedTaskDescriptionContent({
+  description,
+  description_yjs_state,
+}: {
+  description?: string | null;
+  description_yjs_state?: number[] | null;
+}): JSONContent {
+  if (description_yjs_state && description_yjs_state.length > 0) {
+    return decodeTaskDescriptionYjsState(description_yjs_state);
+  }
+
+  try {
+    return normalizeTaskDescriptionContent(
+      parseTaskDescriptionContent(description ?? '')
+    );
+  } catch {
+    return normalizeTaskDescriptionContent(
+      createPlainTextTaskDescriptionContent(
+        getDescriptionText(description ?? '').trim()
+      )
+    );
+  }
+}
+
+export function encodeTaskDescriptionYjsState(content: JSONContent): number[] {
+  return Array.from(
+    convertJsonContentToYjsState(
+      normalizeTaskDescriptionContent(content),
+      taskDescriptionSchema
+    )
+  );
+}
+
+export function decodeTaskDescriptionYjsState(
+  yjsState: number[] | Uint8Array
+): JSONContent {
+  return convertYjsStateToJsonContent(
+    yjsState instanceof Uint8Array ? yjsState : Uint8Array.from(yjsState),
+    taskDescriptionSchema
+  );
+}
+
+export function taskDescriptionYjsStateToBase64(
+  yjsState: number[] | Uint8Array | null | undefined
+): string | null {
+  if (yjsState == null) return null;
+  const bytes =
+    yjsState instanceof Uint8Array ? yjsState : Uint8Array.from(yjsState);
+  return Buffer.from(bytes).toString('base64');
+}
+
+export function taskDescriptionYjsStateFromBase64(input: string): number[] {
+  return Array.from(Buffer.from(input.trim(), 'base64'));
+}
+
+export function taskDescriptionYjsStateFromBytesJson(input: string): number[] {
+  const parsed = JSON.parse(input) as unknown;
+  if (
+    !Array.isArray(parsed) ||
+    parsed.some((value) => !Number.isInteger(value) || value < 0 || value > 255)
+  ) {
+    throw new Error('Yjs bytes JSON must be an array of byte values');
+  }
+  return parsed as number[];
+}
+
+export function taskDescriptionPlainText(content: JSONContent): string {
+  return getDescriptionText(normalizeTaskDescriptionContent(content));
+}
+
+export function createTaskDescriptionPayload(
+  input: string,
+  format: TaskDescriptionInputFormat = 'text'
+): TaskDescriptionPayload {
+  const content = parseTaskDescriptionInput(input, format);
+
+  if (!hasMeaningfulTaskDescriptionContent(content)) {
+    return {
+      content,
+      description: null,
+      description_yjs_state: null,
+    };
+  }
+
+  return {
+    content,
+    description: JSON.stringify(content),
+    description_yjs_state: encodeTaskDescriptionYjsState(content),
+  };
+}

package/src/yjs-task-description.ts

@@ -1,15 +1,16 @@
 import type { JSONContent } from '@tiptap/core';
+import {
+  decodeTaskDescriptionYjsState,
+  encodeTaskDescriptionYjsState,
+  parsePersistedTaskDescriptionContent,
+  parseTaskDescriptionInput,
+} from './task-description-codec';
 import {
   hasMeaningfulTaskDescriptionContent,
   isValidTaskDescriptionContent,
-  parseTaskDescriptionContent,
   taskDescriptionSchema,
 } from './task-description-content';
 import { getDescriptionText } from './text-helper';
-import {
-  convertJsonContentToYjsState,
-  convertYjsStateToJsonContent,
-} from './yjs-helper';
 
 export { isValidTaskDescriptionContent, taskDescriptionSchema };
 
@@ -21,10 +22,7 @@ export function isValidTaskDescriptionYjsState(
   }
 
   try {
-    convertYjsStateToJsonContent(
-      Uint8Array.from(yjsState),
-      taskDescriptionSchema
-    );
+    decodeTaskDescriptionYjsState(yjsState);
     return true;
   } catch {
     return false;
@@ -32,11 +30,11 @@ export function isValidTaskDescriptionYjsState(
 }
 
 function encodeYjsState(content: JSONContent): number[] | null {
-  const encoded = convertJsonContentToYjsState(content, taskDescriptionSchema);
+  const encoded = encodeTaskDescriptionYjsState(content);
   if (encoded.length === 0) {
     return null;
   }
-  return Array.from(encoded);
+  return encoded;
 }
 
 /**
@@ -51,7 +49,9 @@ export function deriveTaskDescriptionYjsState(
     return null;
   }
 
-  const content = parseTaskDescriptionContent(normalizedDescription);
+  const content = parsePersistedTaskDescriptionContent({
+    description: normalizedDescription,
+  });
   if (!hasMeaningfulTaskDescriptionContent(content)) {
     return null;
   }
@@ -65,15 +65,7 @@ export function deriveTaskDescriptionYjsState(
     }
 
     try {
-      return encodeYjsState({
-        type: 'doc',
-        content: [
-          {
-            type: 'paragraph',
-            content: [{ type: 'text', text: fallbackText }],
-          },
-        ],
-      });
+      return encodeYjsState(parseTaskDescriptionInput(fallbackText, 'text'));
     } catch {
       return null;
     }