` and animate the wrapper instead.\n\n**Incorrect (animating SVG directly - no hardware acceleration):**\n\n```tsx\nfunction LoadingSpinner() {\n return (\n
\n \n )\n}\n```\n\n**Correct (animating wrapper div - hardware accelerated):**\n\n```tsx\nfunction LoadingSpinner() {\n return (\n
\n \n \n
\n )\n}\n```\n\nThis applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rendering-conditional-render.md",
"content": "---\ntitle: Use Explicit Conditional Rendering\nimpact: LOW\nimpactDescription: prevents rendering 0 or NaN\ntags: rendering, conditional, jsx, falsy-values\n---\n\n## Use Explicit Conditional Rendering\n\nUse explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.\n\n**Incorrect (renders \"0\" when count is 0):**\n\n```tsx\nfunction Badge({ count }: { count: number }) {\n return (\n
\n {count && {count} }\n
\n )\n}\n\n// When count = 0, renders:
0
\n// When count = 5, renders:
5
\n```\n\n**Correct (renders nothing when count is 0):**\n\n```tsx\nfunction Badge({ count }: { count: number }) {\n return (\n
\n {count > 0 ? {count} : null}\n
\n )\n}\n\n// When count = 0, renders:
\n// When count = 5, renders:
5
\n```\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rendering-content-visibility.md",
"content": "---\ntitle: CSS content-visibility for Long Lists\nimpact: HIGH\nimpactDescription: faster initial render\ntags: rendering, css, content-visibility, long-lists\n---\n\n## CSS content-visibility for Long Lists\n\nApply `content-visibility: auto` to defer off-screen rendering.\n\n**CSS:**\n\n```css\n.message-item {\n content-visibility: auto;\n contain-intrinsic-size: 0 80px;\n}\n```\n\n**Example:**\n\n```tsx\nfunction MessageList({ messages }: { messages: Message[] }) {\n return (\n
\n {messages.map(msg => (\n
\n ))}\n
\n )\n}\n```\n\nFor 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rendering-hoist-jsx.md",
"content": "---\ntitle: Hoist Static JSX Elements\nimpact: LOW\nimpactDescription: avoids re-creation\ntags: rendering, jsx, static, optimization\n---\n\n## Hoist Static JSX Elements\n\nExtract static JSX outside components to avoid re-creation.\n\n**Incorrect (recreates element every render):**\n\n```tsx\nfunction LoadingSkeleton() {\n return
\n}\n\nfunction Container() {\n return (\n
\n {loading &&
\n )\n}\n```\n\n**Correct (reuses same element):**\n\n```tsx\nconst loadingSkeleton = (\n
\n)\n\nfunction Container() {\n return (\n
\n {loading && loadingSkeleton}\n
\n )\n}\n```\n\nThis is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.\n\n**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rendering-hydration-no-flicker.md",
"content": "---\ntitle: Prevent Hydration Mismatch Without Flickering\nimpact: MEDIUM\nimpactDescription: avoids visual flicker and hydration errors\ntags: rendering, ssr, hydration, localStorage, flicker\n---\n\n## Prevent Hydration Mismatch Without Flickering\n\nWhen rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.\n\n**Incorrect (breaks SSR):**\n\n```tsx\nfunction ThemeWrapper({ children }: { children: ReactNode }) {\n // localStorage is not available on server - throws error\n const theme = localStorage.getItem('theme') || 'light'\n \n return (\n
\n {children}\n
\n )\n}\n```\n\nServer-side rendering will fail because `localStorage` is undefined.\n\n**Incorrect (visual flickering):**\n\n```tsx\nfunction ThemeWrapper({ children }: { children: ReactNode }) {\n const [theme, setTheme] = useState('light')\n \n useEffect(() => {\n // Runs after hydration - causes visible flash\n const stored = localStorage.getItem('theme')\n if (stored) {\n setTheme(stored)\n }\n }, [])\n \n return (\n
\n {children}\n
\n )\n}\n```\n\nComponent first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.\n\n**Correct (no flicker, no hydration mismatch):**\n\n```tsx\nfunction ThemeWrapper({ children }: { children: ReactNode }) {\n return (\n <>\n
\n {children}\n
\n
\n \n )\n}\n```\n\nThe inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.\n\nThis pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rendering-svg-precision.md",
"content": "---\ntitle: Optimize SVG Precision\nimpact: LOW\nimpactDescription: reduces file size\ntags: rendering, svg, optimization, svgo\n---\n\n## Optimize SVG Precision\n\nReduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.\n\n**Incorrect (excessive precision):**\n\n```svg\n
\n```\n\n**Correct (1 decimal place):**\n\n```svg\n
\n```\n\n**Automate with SVGO:**\n\n```bash\nnpx svgo --precision=1 --multipass icon.svg\n```\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rerender-defer-reads.md",
"content": "---\ntitle: Defer State Reads to Usage Point\nimpact: MEDIUM\nimpactDescription: avoids unnecessary subscriptions\ntags: rerender, searchParams, localStorage, optimization\n---\n\n## Defer State Reads to Usage Point\n\nDon't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.\n\n**Incorrect (subscribes to all searchParams changes):**\n\n```tsx\nfunction ShareButton({ chatId }: { chatId: string }) {\n const searchParams = useSearchParams()\n\n const handleShare = () => {\n const ref = searchParams.get('ref')\n shareChat(chatId, { ref })\n }\n\n return
Share \n}\n```\n\n**Correct (reads on demand, no subscription):**\n\n```tsx\nfunction ShareButton({ chatId }: { chatId: string }) {\n const handleShare = () => {\n const params = new URLSearchParams(window.location.search)\n const ref = params.get('ref')\n shareChat(chatId, { ref })\n }\n\n return
Share \n}\n```\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rerender-dependencies.md",
"content": "---\ntitle: Narrow Effect Dependencies\nimpact: LOW\nimpactDescription: minimizes effect re-runs\ntags: rerender, useEffect, dependencies, optimization\n---\n\n## Narrow Effect Dependencies\n\nSpecify primitive dependencies instead of objects to minimize effect re-runs.\n\n**Incorrect (re-runs on any user field change):**\n\n```tsx\nuseEffect(() => {\n console.log(user.id)\n}, [user])\n```\n\n**Correct (re-runs only when id changes):**\n\n```tsx\nuseEffect(() => {\n console.log(user.id)\n}, [user.id])\n```\n\n**For derived state, compute outside effect:**\n\n```tsx\n// Incorrect: runs on width=767, 766, 765...\nuseEffect(() => {\n if (width < 768) {\n enableMobileMode()\n }\n}, [width])\n\n// Correct: runs only on boolean transition\nconst isMobile = width < 768\nuseEffect(() => {\n if (isMobile) {\n enableMobileMode()\n }\n}, [isMobile])\n```\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rerender-derived-state.md",
"content": "---\ntitle: Subscribe to Derived State\nimpact: MEDIUM\nimpactDescription: reduces re-render frequency\ntags: rerender, derived-state, media-query, optimization\n---\n\n## Subscribe to Derived State\n\nSubscribe to derived boolean state instead of continuous values to reduce re-render frequency.\n\n**Incorrect (re-renders on every pixel change):**\n\n```tsx\nfunction Sidebar() {\n const width = useWindowWidth() // updates continuously\n const isMobile = width < 768\n return
\n}\n```\n\n**Correct (re-renders only when boolean changes):**\n\n```tsx\nfunction Sidebar() {\n const isMobile = useMediaQuery('(max-width: 767px)')\n return \n}\n```\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rerender-functional-setstate.md",
"content": "---\ntitle: Use Functional setState Updates\nimpact: MEDIUM\nimpactDescription: prevents stale closures and unnecessary callback recreations\ntags: react, hooks, useState, useCallback, callbacks, closures\n---\n\n## Use Functional setState Updates\n\nWhen updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.\n\n**Incorrect (requires state as dependency):**\n\n```tsx\nfunction TodoList() {\n const [items, setItems] = useState(initialItems)\n \n // Callback must depend on items, recreated on every items change\n const addItems = useCallback((newItems: Item[]) => {\n setItems([...items, ...newItems])\n }, [items]) // ❌ items dependency causes recreations\n \n // Risk of stale closure if dependency is forgotten\n const removeItem = useCallback((id: string) => {\n setItems(items.filter(item => item.id !== id))\n }, []) // ❌ Missing items dependency - will use stale items!\n \n return {avatar}
\n}\n```\n\n**Correct (skips computation when loading):**\n\n```tsx\nconst UserAvatar = memo(function UserAvatar({ user }: { user: User }) {\n const id = useMemo(() => computeAvatarId(user), [user])\n return \n
\n )\n}\n```\n\n**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.\n"
},
{
"path": ".claude/skills/react-best-practices/rules/rerender-transitions.md",
"content": "---\ntitle: Use Transitions for Non-Urgent Updates\nimpact: MEDIUM\nimpactDescription: maintains UI responsiveness\ntags: rerender, transitions, startTransition, performance\n---\n\n## Use Transitions for Non-Urgent Updates\n\nMark frequent, non-urgent state updates as transitions to maintain UI responsiveness.\n\n**Incorrect (blocks UI on every scroll):**\n\n```tsx\nfunction ScrollTracker() {\n const [scrollY, setScrollY] = useState(0)\n useEffect(() => {\n const handler = () => setScrollY(window.scrollY)\n window.addEventListener('scroll', handler, { passive: true })\n return () => window.removeEventListener('scroll', handler)\n }, [])\n}\n```\n\n**Correct (non-blocking updates):**\n\n```tsx\nimport { startTransition } from 'react'\n\nfunction ScrollTracker() {\n const [scrollY, setScrollY] = useState(0)\n useEffect(() => {\n const handler = () => {\n startTransition(() => setScrollY(window.scrollY))\n }\n window.addEventListener('scroll', handler, { passive: true })\n return () => window.removeEventListener('scroll', handler)\n }, [])\n}\n```\n"
},
{
"path": ".claude/skills/react-best-practices/rules/server-after-nonblocking.md",
"content": "---\ntitle: Use after() for Non-Blocking Operations\nimpact: MEDIUM\nimpactDescription: faster response times\ntags: server, async, logging, analytics, side-effects\n---\n\n## Use after() for Non-Blocking Operations\n\nUse Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.\n\n**Incorrect (blocks response):**\n\n```tsx\nimport { logUserAction } from '@/app/utils'\n\nexport async function POST(request: Request) {\n // Perform mutation\n await updateDatabase(request)\n \n // Logging blocks the response\n const userAgent = request.headers.get('user-agent') || 'unknown'\n await logUserAction({ userAgent })\n \n return new Response(JSON.stringify({ status: 'success' }), {\n status: 200,\n headers: { 'Content-Type': 'application/json' }\n })\n}\n```\n\n**Correct (non-blocking):**\n\n```tsx\nimport { after } from 'next/server'\nimport { headers, cookies } from 'next/headers'\nimport { logUserAction } from '@/app/utils'\n\nexport async function POST(request: Request) {\n // Perform mutation\n await updateDatabase(request)\n \n // Log after response is sent\n after(async () => {\n const userAgent = (await headers()).get('user-agent') || 'unknown'\n const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'\n \n logUserAction({ sessionCookie, userAgent })\n })\n \n return new Response(JSON.stringify({ status: 'success' }), {\n status: 200,\n headers: { 'Content-Type': 'application/json' }\n })\n}\n```\n\nThe response is sent immediately while logging happens in the background.\n\n**Common use cases:**\n\n- Analytics tracking\n- Audit logging\n- Sending notifications\n- Cache invalidation\n- Cleanup tasks\n\n**Important notes:**\n\n- `after()` runs even if the response fails or redirects\n- Works in Server Actions, Route Handlers, and Server Components\n\nReference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)\n"
},
{
"path": ".claude/skills/react-best-practices/rules/server-cache-lru.md",
"content": "---\ntitle: Cross-Request LRU Caching\nimpact: HIGH\nimpactDescription: caches across requests\ntags: server, cache, lru, cross-request\n---\n\n## Cross-Request LRU Caching\n\n`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.\n\n**Implementation:**\n\n```typescript\nimport { LRUCache } from 'lru-cache'\n\nconst cache = new LRUCache({\n max: 1000,\n ttl: 5 * 60 * 1000 // 5 minutes\n})\n\nexport async function getUser(id: string) {\n const cached = cache.get(id)\n if (cached) return cached\n\n const user = await db.user.findUnique({ where: { id } })\n cache.set(id, user)\n return user\n}\n\n// Request 1: DB query, result cached\n// Request 2: cache hit, no DB query\n```\n\nUse when sequential user actions hit multiple endpoints needing the same data within seconds.\n\n**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.\n\n**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.\n\nReference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)\n"
},
{
"path": ".claude/skills/react-best-practices/rules/server-cache-react.md",
"content": "---\ntitle: Per-Request Deduplication with React.cache()\nimpact: MEDIUM\nimpactDescription: deduplicates within request\ntags: server, cache, react-cache, deduplication\n---\n\n## Per-Request Deduplication with React.cache()\n\nUse `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.\n\n**Usage:**\n\n```typescript\nimport { cache } from 'react'\n\nexport const getCurrentUser = cache(async () => {\n const session = await auth()\n if (!session?.user?.id) return null\n return await db.user.findUnique({\n where: { id: session.user.id }\n })\n})\n```\n\nWithin a single request, multiple calls to `getCurrentUser()` execute the query only once.\n"
},
{
"path": ".claude/skills/react-best-practices/rules/server-parallel-fetching.md",
"content": "---\ntitle: Parallel Data Fetching with Component Composition\nimpact: CRITICAL\nimpactDescription: eliminates server-side waterfalls\ntags: server, rsc, parallel-fetching, composition\n---\n\n## Parallel Data Fetching with Component Composition\n\nReact Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.\n\n**Incorrect (Sidebar waits for Page's fetch to complete):**\n\n```tsx\nexport default async function Page() {\n const header = await fetchHeader()\n return (\n \n )\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return {items.map(renderItem)} \n}\n```\n\n**Correct (both fetch simultaneously):**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return {items.map(renderItem)} \n}\n\nexport default function Page() {\n return (\n \n \n
\n )\n}\n```\n\n**Alternative with children prop:**\n\n```tsx\nasync function Layout({ children }: { children: ReactNode }) {\n const header = await fetchHeader()\n return (\n \n
{header}
\n {children}\n
{items.map(renderItem)} \n}\n\nexport default function Page() {\n return (\n \n \n )\n}\n```\n"
},
{
"path": ".claude/skills/react-best-practices/rules/server-serialization.md",
"content": "---\ntitle: Minimize Serialization at RSC Boundaries\nimpact: HIGH\nimpactDescription: reduces data transfer size\ntags: server, rsc, serialization, props\n---\n\n## Minimize Serialization at RSC Boundaries\n\nThe React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.\n\n**Incorrect (serializes all 50 fields):**\n\n```tsx\nasync function Page() {\n const user = await fetchUser() // 50 fields\n return {user.name}
// uses 1 field\n}\n```\n\n**Correct (serializes only 1 field):**\n\n```tsx\nasync function Page() {\n const user = await fetchUser()\n return {name}
\n}\n```\n"
},
{
"path": ".dockerignore",
"content": "node_modules\n.next\ndist\n.turbo\n.git\n*.log\n.env*\n!.env.template\n"
},
{
"path": ".github/FUNDING.yml",
"content": "github: ridafkih\n"
},
{
"path": ".github/workflows/checks.yml",
"content": "name: Check Code Standards\n\non:\n pull_request:\n branches: [main]\n\njobs:\n types:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v2\n - run: bun install --frozen-lockfile\n - run: bun run types\n\n lint:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v2\n - run: bun install --frozen-lockfile\n - run: bun run lint\n\n unused:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v2\n - run: bun install --frozen-lockfile\n - run: bun run unused\n\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v2\n - run: bun install --frozen-lockfile\n - run: bun run test\n"
},
{
"path": ".github/workflows/docker-publish.yml",
"content": "name: Publish Docker Images\n\non:\n push:\n tags:\n - \"v*.*.*\"\n\nconcurrency:\n group: publish-${{ github.ref }}\n cancel-in-progress: false\n\nenv:\n REGISTRY: ghcr.io\n\njobs:\n build-core:\n strategy:\n matrix:\n arch: [amd64, arm64]\n package:\n - name: api\n dockerfile: services/api/Dockerfile\n - name: cron\n dockerfile: services/cron/Dockerfile\n - name: worker\n dockerfile: services/worker/Dockerfile\n - name: mcp\n dockerfile: services/mcp/Dockerfile\n - name: web\n dockerfile: applications/web/Dockerfile\n include:\n - arch: amd64\n runner: ubuntu-24.04\n - arch: arm64\n runner: ubuntu-24.04-arm\n runs-on: ${{ matrix.runner }}\n permissions:\n contents: read\n packages: write\n steps:\n - uses: actions/checkout@v4\n - uses: docker/setup-buildx-action@v3\n - uses: docker/login-action@v3\n with:\n registry: ${{ env.REGISTRY }}\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n - id: meta\n uses: docker/metadata-action@v5\n with:\n images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/keeper-${{ matrix.package.name }}\n tags: |\n type=semver,pattern={{version}}\n type=semver,pattern={{major}}.{{minor}},enable=${{ !contains(github.ref, '-') }}\n type=raw,value=latest,enable=${{ !contains(github.ref, '-') }}\n flavor: suffix=-${{ matrix.arch }}\n - uses: docker/build-push-action@v6\n with:\n context: .\n file: ${{ matrix.package.dockerfile }}\n push: true\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n cache-from: type=gha,scope=${{ matrix.package.name }}-${{ matrix.arch }}\n cache-to: type=gha,mode=max,scope=${{ matrix.package.name }}-${{ matrix.arch }}\n\n build-convenience:\n strategy:\n matrix:\n package: [standalone, services]\n arch: [amd64, arm64]\n include:\n - arch: amd64\n runner: ubuntu-24.04\n - arch: arm64\n runner: ubuntu-24.04-arm\n runs-on: ${{ matrix.runner }}\n permissions:\n contents: read\n packages: write\n steps:\n - uses: actions/checkout@v4\n - uses: docker/setup-buildx-action@v3\n - uses: docker/login-action@v3\n with:\n registry: ${{ env.REGISTRY }}\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n - id: meta\n uses: docker/metadata-action@v5\n with:\n images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/keeper-${{ matrix.package }}\n tags: |\n type=semver,pattern={{version}}\n type=semver,pattern={{major}}.{{minor}},enable=${{ !contains(github.ref, '-') }}\n type=raw,value=latest,enable=${{ !contains(github.ref, '-') }}\n flavor: suffix=-${{ matrix.arch }}\n - uses: docker/build-push-action@v6\n with:\n context: .\n file: docker/${{ matrix.package }}/Dockerfile\n push: true\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n cache-from: type=gha,scope=${{ matrix.package }}-${{ matrix.arch }}\n cache-to: type=gha,mode=max,scope=${{ matrix.package }}-${{ matrix.arch }}\n\n merge-core-manifests:\n runs-on: ubuntu-latest\n needs: build-core\n permissions:\n contents: read\n packages: write\n strategy:\n matrix:\n package:\n - api\n - cron\n - worker\n - mcp\n - web\n steps:\n - uses: docker/setup-buildx-action@v3\n - uses: docker/login-action@v3\n with:\n registry: ${{ env.REGISTRY }}\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n - id: meta\n uses: docker/metadata-action@v5\n with:\n images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/keeper-${{ matrix.package }}\n tags: |\n type=semver,pattern={{version}}\n type=semver,pattern={{major}}.{{minor}},enable=${{ !contains(github.ref, '-') }}\n type=raw,value=latest,enable=${{ !contains(github.ref, '-') }}\n - name: Create multi-arch manifest\n env:\n TAGS: ${{ steps.meta.outputs.tags }}\n run: |\n for tag in $TAGS; do\n docker buildx imagetools create -t \"$tag\" \\\n \"${tag}-amd64\" \\\n \"${tag}-arm64\"\n done\n\n merge-convenience-manifests:\n runs-on: ubuntu-latest\n needs: build-convenience\n permissions:\n contents: read\n packages: write\n strategy:\n matrix:\n package: [standalone, services]\n steps:\n - uses: docker/setup-buildx-action@v3\n - uses: docker/login-action@v3\n with:\n registry: ${{ env.REGISTRY }}\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n - id: meta\n uses: docker/metadata-action@v5\n with:\n images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/keeper-${{ matrix.package }}\n tags: |\n type=semver,pattern={{version}}\n type=semver,pattern={{major}}.{{minor}},enable=${{ !contains(github.ref, '-') }}\n type=raw,value=latest,enable=${{ !contains(github.ref, '-') }}\n - name: Create multi-arch manifest\n env:\n TAGS: ${{ steps.meta.outputs.tags }}\n run: |\n for tag in $TAGS; do\n docker buildx imagetools create -t \"$tag\" \\\n \"${tag}-amd64\" \\\n \"${tag}-arm64\"\n done\n\n deploy-ec2:\n runs-on: ubuntu-latest\n needs: merge-core-manifests\n if: ${{ !contains(github.ref, '-') }}\n concurrency:\n group: production-deploy\n cancel-in-progress: false\n permissions:\n contents: read\n steps:\n - uses: actions/checkout@v4\n\n - uses: appleboy/scp-action@v0.1.7\n with:\n host: ${{ secrets.EC2_HOST }}\n username: ubuntu\n key: ${{ secrets.EC2_SSH_KEY }}\n source: \"deploy/compose.yaml,deploy/Caddyfile,docker/caddy/Dockerfile\"\n target: /home/ubuntu\n\n - uses: appleboy/ssh-action@v1.2.4\n with:\n host: ${{ secrets.EC2_HOST }}\n username: ubuntu\n key: ${{ secrets.EC2_SSH_KEY }}\n script: |\n set -euo pipefail\n\n exec 9>/tmp/keeper-deploy.lock\n flock 9\n\n cd /home/ubuntu\n\n cd deploy\n docker compose pull\n docker compose up -d --build --remove-orphans --wait\n docker image prune -af --filter \"until=24h\"\n"
},
{
"path": ".gitignore",
"content": "node_modules\n.env\n.idea\n.DS_Store\n.turbo/\ndist/\n*.tsbuildinfo\nscreenshots/\napplications/mobile/\n.pki/\n"
},
{
"path": ".oxlintrc.json",
"content": "{\n \"$schema\": \"./node_modules/oxlint/configuration_schema.json\",\n \"plugins\": [\"import\", \"typescript\", \"unicorn\", \"promise\"],\n \"env\": {\n \"browser\": true,\n \"node\": true,\n \"es2024\": true\n },\n \"globals\": {\n \"Bun\": \"readonly\"\n },\n \"categories\": {\n \"correctness\": \"error\",\n \"suspicious\": \"error\",\n \"pedantic\": \"error\",\n \"perf\": \"error\",\n \"style\": \"error\",\n \"restriction\": \"error\"\n },\n \"rules\": {\n \"eqeqeq\": [\"error\", \"always\"],\n \"@typescript-eslint/no-explicit-any\": \"error\",\n \"@typescript-eslint/no-unused-vars\": \"error\",\n \"@typescript-eslint/consistent-type-imports\": \"error\",\n \"@typescript-eslint/explicit-module-boundary-types\": \"off\",\n \"@typescript-eslint/explicit-function-return-type\": \"off\",\n \"import/no-cycle\": \"error\",\n \"import/no-self-import\": \"error\",\n \"import/no-named-export\": \"off\",\n \"import/prefer-default-export\": \"off\",\n \"import/max-dependencies\": \"off\",\n \"import/no-anonymous-default-export\": \"off\",\n \"import/consistent-type-specifier-style\": \"off\",\n \"import/no-duplicates\": \"off\",\n \"import/no-nodejs-modules\": \"off\",\n \"import/no-relative-parent-imports\": \"off\",\n \"unicorn/no-null\": \"off\",\n \"unicorn/prefer-global-this\": \"off\",\n \"unicorn/prefer-top-level-await\": \"off\",\n \"unicorn/no-process-exit\": \"off\",\n \"react/jsx-max-depth\": \"off\",\n \"react/react-in-jsx-scope\": \"off\",\n \"react/jsx-filename-extension\": \"off\",\n \"react/no-unescaped-entities\": \"off\",\n \"react/jsx-props-no-spreading\": \"off\",\n \"promise/avoid-new\": \"off\",\n \"promise/prefer-await-to-then\": \"off\",\n \"promise/prefer-await-to-callbacks\": \"off\",\n \"no-duplicate-imports\": \"off\",\n \"no-default-export\": \"off\",\n \"no-await-in-loop\": \"off\",\n \"no-plusplus\": \"off\",\n \"no-continue\": \"off\",\n \"no-magic-numbers\": \"off\",\n \"no-warning-comments\": \"off\",\n \"no-eq-null\": \"off\",\n \"max-lines-per-function\": \"off\",\n \"max-statements\": \"off\",\n \"max-lines\": \"off\",\n \"max-params\": \"off\",\n \"max-classes-per-file\": \"off\",\n \"sort-imports\": \"off\",\n \"sort-keys\": \"off\",\n \"id-length\": [\"error\", { \"exceptions\": [\"x\", \"y\"] }]\n },\n \"ignorePatterns\": [\n \"**/node_modules/**\",\n \"**/dist/**\",\n \"**/.next/**\",\n \"**/.turbo/**\",\n \"**/coverage/**\"\n ]\n}\n"
},
{
"path": "Caddyfile",
"content": "keeper.localhost {\n\ttls internal\n\n\treverse_proxy host.docker.internal:5173\n}\n\n:80 {\n\treverse_proxy host.docker.internal:5173\n}\n"
},
{
"path": "LICENSE",
"content": " GNU AFFERO GENERAL PUBLIC LICENSE\n Version 3, 19 November 2007\n\n Copyright (C) 2007 Free Software Foundation, Inc. \n Copyright (C) \n\n This program is free software: you can redistribute it and/or modify\n it under the terms of the GNU Affero General Public License as published by\n the Free Software Foundation, either version 3 of the License, or\n (at your option) any later version.\n\n This program is distributed in the hope that it will be useful,\n but WITHOUT ANY WARRANTY; without even the implied warranty of\n MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n GNU Affero General Public License for more details.\n\n You should have received a copy of the GNU Affero General Public License\n along with this program. If not, see
\n \n \n\n"
},
{
"path": "applications/web/package.json",
"content": "{\n \"name\": \"@keeper.sh/web\",\n \"private\": true,\n \"version\": \"0.0.0\",\n \"type\": \"module\",\n \"scripts\": {\n \"dev\": \"bun src/server/index.ts\",\n \"build\": \"vite build --outDir dist/client && vite build --ssr src/server.tsx --outDir dist/server && bun scripts/build.ts\",\n \"lint\": \"eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0\",\n \"types\": \"tsc --noEmit\",\n \"test\": \"bun x --bun vitest run\",\n \"preview\": \"vite preview\",\n \"start\": \"bun scripts/start.ts\"\n },\n \"dependencies\": {\n \"@better-auth/passkey\": \"^1.5.5\",\n \"@keeper.sh/data-schemas\": \"workspace:*\",\n \"@keeper.sh/otelemetry\": \"workspace:*\",\n \"@polar-sh/checkout\": \"^0.2.0\",\n \"@tanstack/react-router\": \"^1.163.3\",\n \"arktype\": \"^2.2.0\",\n \"better-auth\": \"^1.5.5\",\n \"clsx\": \"^2.1.1\",\n \"entrykit\": \"^0.1.3\",\n \"fast-xml-parser\": \"^5.4.2\",\n \"jotai\": \"^2.18.0\",\n \"linkedom\": \"^0.18.12\",\n \"lucide-react\": \"^0.576.0\",\n \"motion\": \"^12.34.4\",\n \"react\": \"^19.2.4\",\n \"react-dom\": \"^19.2.4\",\n \"streamdown\": \"^2.4.0\",\n \"swr\": \"^2.4.1\",\n \"tailwind-variants\": \"^3.2.2\",\n \"widelogger\": \"^0.7.0\",\n \"yaml\": \"^2.8.2\"\n },\n \"devDependencies\": {\n \"@babel/preset-typescript\": \"^7.28.5\",\n \"@eslint/js\": \"^10.0.1\",\n \"@rolldown/plugin-babel\": \"^0.2.0\",\n \"@tailwindcss/vite\": \"^4.2.1\",\n \"@tanstack/router-plugin\": \"^1.164.0\",\n \"@types/react\": \"^19.2.14\",\n \"@types/react-dom\": \"^19.2.3\",\n \"@typescript-eslint/eslint-plugin\": \"^8.56.1\",\n \"@typescript-eslint/parser\": \"^8.56.1\",\n \"@vitejs/plugin-react\": \"^6.0.0\",\n \"babel-plugin-react-compiler\": \"^1.0.0\",\n \"eslint\": \"^10.0.2\",\n \"eslint-plugin-react-hooks\": \"^7.0.1\",\n \"eslint-plugin-react-refresh\": \"^0.5.2\",\n \"tailwindcss\": \"^4.2.1\",\n \"typescript\": \"^5.9.3\",\n \"vite\": \"^8.0.0\",\n \"vite-plugin-svgr\": \"^4.5.0\",\n \"vitest\": \"^4.1.4\"\n }\n}\n"
},
{
"path": "applications/web/plugins/blog.ts",
"content": "import { readFileSync, readdirSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport { type } from \"arktype\";\nimport { parse as parseYaml } from \"yaml\";\n\nconst blogPostMetadataSchema = type({\n \"+\": \"reject\",\n blurb: \"string >= 1\",\n createdAt: \"string.date.iso\",\n description: \"string >= 1\",\n \"slug?\": /^[a-z0-9]+(?:-[a-z0-9]+)*$/,\n tags: \"string[]\",\n title: \"string >= 1\",\n updatedAt: \"string.date.iso\",\n});\n\ntype BlogPostMetadata = typeof blogPostMetadataSchema.infer;\n\ninterface ProcessedBlogPost {\n content: string;\n metadata: BlogPostMetadata;\n slug: string;\n}\n\nfunction toIsoDate(value: string): string {\n return value.slice(0, 10);\n}\n\nfunction normalizeMetadataInput(value: unknown): unknown {\n if (typeof value !== \"object\" || value === null) return value;\n const normalized: Record = { ...value };\n\n if (normalized.createdAt instanceof Date) {\n normalized.createdAt = normalized.createdAt.toISOString();\n }\n if (normalized.updatedAt instanceof Date) {\n normalized.updatedAt = normalized.updatedAt.toISOString();\n }\n\n return normalized;\n}\n\nfunction splitFrontmatter(\n raw: string,\n filePath: string,\n): { content: string; data: unknown } {\n const match = raw.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n?/);\n if (!match) {\n throw new Error(\n `Blog post \"${filePath}\" must start with a YAML frontmatter block.`,\n );\n }\n\n let parsed: unknown;\n try {\n parsed = parseYaml(match[1]);\n } catch (error) {\n const message =\n error instanceof Error ? error.message : \"Unknown YAML parse error\";\n throw new Error(\n `Blog frontmatter parsing failed for \"${filePath}\": ${message}`,\n );\n }\n\n return {\n content: raw.slice(match[0].length).trimStart(),\n data: parsed ?? {},\n };\n}\n\nfunction parseMetadata(value: unknown, filePath: string): BlogPostMetadata {\n const result = blogPostMetadataSchema(normalizeMetadataInput(value));\n if (result instanceof type.errors) {\n throw new Error(\n `Blog metadata is invalid for \"${filePath}\": ${result}`,\n );\n }\n\n if (result.tags.length === 0) {\n throw new Error(\n `Blog metadata tags must contain at least one tag in \"${filePath}\".`,\n );\n }\n\n return {\n ...result,\n createdAt: toIsoDate(result.createdAt),\n updatedAt: toIsoDate(result.updatedAt),\n };\n}\n\nfunction createSlug(title: string): string {\n return title\n .toLowerCase()\n .trim()\n .replace(/['\"]/g, \"\")\n .replace(/[^a-z0-9]+/g, \"-\")\n .replace(/^-+|-+$/g, \"\");\n}\n\nfunction removeRedundantLeadingHeading(\n content: string,\n title: string,\n): string {\n const lines = content.split(\"\\n\");\n const firstLine = lines[0]?.trim() ?? \"\";\n\n if (!firstLine.startsWith(\"# \")) return content;\n\n const headingText = firstLine.slice(2).trim().toLowerCase();\n if (headingText !== title.trim().toLowerCase()) return content;\n\n let nextIndex = 1;\n while (nextIndex < lines.length && lines[nextIndex].trim().length === 0) {\n nextIndex += 1;\n }\n\n return lines.slice(nextIndex).join(\"\\n\");\n}\n\nfunction processBlogDirectory(blogDir: string): ProcessedBlogPost[] {\n const files = readdirSync(blogDir)\n .filter((f) => f.endsWith(\".mdx\"))\n .sort();\n\n const slugCounts = new Map();\n\n const posts = files.map((file) => {\n const filePath = join(blogDir, file);\n const raw = readFileSync(filePath, \"utf-8\");\n const { content: rawContent, data } = splitFrontmatter(raw, file);\n const metadata = parseMetadata(data, file);\n const content = removeRedundantLeadingHeading(rawContent, metadata.title);\n\n const hasCustomSlug = typeof metadata.slug === \"string\";\n const baseSlug = hasCustomSlug ? metadata.slug : createSlug(metadata.title);\n const seenCount = slugCounts.get(baseSlug) ?? 0;\n\n if (hasCustomSlug && seenCount > 0) {\n throw new Error(`Duplicate blog slug \"${baseSlug}\" found in metadata.`);\n }\n\n slugCounts.set(baseSlug, seenCount + 1);\n const slug = seenCount === 0 ? baseSlug : `${baseSlug}-${seenCount + 1}`;\n\n return { content, metadata, slug };\n });\n\n return posts.sort((a, b) =>\n b.metadata.createdAt.localeCompare(a.metadata.createdAt),\n );\n}\n\nconst VIRTUAL_MODULE_ID = \"virtual:blog-posts\";\nconst RESOLVED_ID = `\\0${VIRTUAL_MODULE_ID}`;\n\nexport function blogPlugin(): Plugin {\n let blogDir: string;\n\n return {\n name: \"keeper-blog\",\n\n configResolved(config) {\n blogDir = resolve(config.root, \"src/content/blog\");\n },\n\n resolveId(id) {\n if (id === VIRTUAL_MODULE_ID) return RESOLVED_ID;\n },\n\n load(id) {\n if (id !== RESOLVED_ID) return;\n\n const posts = processBlogDirectory(blogDir);\n return `export const blogPosts = ${JSON.stringify(posts)};`;\n },\n\n handleHotUpdate({ file, server }) {\n if (file.startsWith(blogDir) && file.endsWith(\".mdx\")) {\n const module = server.moduleGraph.getModuleById(RESOLVED_ID);\n if (module) {\n server.moduleGraph.invalidateModule(module);\n return [module];\n }\n }\n },\n };\n}\n"
},
{
"path": "applications/web/plugins/sitemap.ts",
"content": "import { readdirSync, readFileSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport { XMLBuilder } from \"fast-xml-parser\";\nimport { parse as parseYaml } from \"yaml\";\n\nconst SITE_URL = \"https://keeper.sh\";\nconst FRONTMATTER_PATTERN = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---/;\n\ninterface SitemapEntry {\n loc: string;\n lastmod: string;\n}\n\nconst staticEntries: SitemapEntry[] = [\n { loc: `${SITE_URL}/`, lastmod: \"2026-03-09\" },\n { loc: `${SITE_URL}/blog`, lastmod: \"2026-03-09\" },\n { loc: `${SITE_URL}/privacy`, lastmod: \"2025-12-01\" },\n { loc: `${SITE_URL}/terms`, lastmod: \"2025-12-01\" },\n];\n\nfunction parseFrontmatter(raw: string): Record {\n const [, match] = raw.match(FRONTMATTER_PATTERN);\n if (!match) return {};\n return parseYaml(match);\n}\n\nfunction discoverBlogEntries(blogDir: string): SitemapEntry[] {\n const files = readdirSync(blogDir).filter((f) => f.endsWith(\".mdx\"));\n\n return files.map((file) => {\n const raw = readFileSync(join(blogDir, file), \"utf-8\");\n const frontmatter = parseFrontmatter(raw);\n\n if (typeof frontmatter.slug !== \"string\") {\n throw new Error(`Blog post \"${file}\" is missing a slug.`);\n }\n\n if (typeof frontmatter.updatedAt !== \"string\") {\n throw new Error(`Blog post \"${file}\" is missing updatedAt.`);\n }\n\n return {\n loc: `${SITE_URL}/blog/${frontmatter.slug}`,\n lastmod: frontmatter.updatedAt.slice(0, 10),\n };\n });\n}\n\nconst xmlBuilder = new XMLBuilder({\n format: true,\n ignoreAttributes: false,\n suppressEmptyNode: true,\n});\n\nfunction buildSitemapXml(entries: SitemapEntry[]): string {\n const document = {\n \"?xml\": { \"@_version\": \"1.0\", \"@_encoding\": \"UTF-8\" },\n urlset: {\n \"@_xmlns\": \"http://www.sitemaps.org/schemas/sitemap/0.9\",\n url: entries.map((entry) => ({\n loc: entry.loc,\n lastmod: entry.lastmod,\n })),\n },\n };\n\n return String(xmlBuilder.build(document));\n}\n\nexport function sitemapPlugin(): Plugin {\n let blogDir: string;\n\n return {\n name: \"keeper-sitemap\",\n apply: \"build\",\n\n configResolved(config) {\n blogDir = resolve(config.root, \"src/content/blog\");\n },\n\n generateBundle() {\n const blogEntries = discoverBlogEntries(blogDir);\n const entries = [...staticEntries, ...blogEntries];\n\n this.emitFile({\n type: \"asset\",\n fileName: \"sitemap.xml\",\n source: buildSitemapXml(entries),\n });\n },\n };\n}\n"
},
{
"path": "applications/web/public/llms-full.txt",
"content": "# Keeper.sh — Full Context\n\n> Open-source calendar event syncing. Synchronize events between your personal, work, business and school calendars.\n\nKeeper.sh is an open-source (AGPL-3.0) calendar synchronization service built by Rida F'kih. It keeps time slots aligned across multiple calendar providers using a pull-compare-push sync engine. The project is self-hostable and offers a hosted version at keeper.sh.\n\n## Problem\n\nPeople with calendars across multiple providers (Google Calendar, Outlook, iCloud, FastMail) end up with fragmented availability. Different people see incomplete windows into their schedule, causing constant overlap and scheduling friction. Existing tools were too manual, had finicky sync behavior, lacked privacy controls, or didn't offer self-hosting.\n\n## How It Works\n\n### Sync Engine\n\nKeeper.sh uses a pull-compare-push architecture. On each sync cycle:\n\n1. **Pull**: Events are fetched from configured source calendars\n2. **Compare**: Events are compared against known state\n3. **Push**: Changes are pushed to destination calendars\n\nCore sync operations:\n- **Add**: Source event with no mapping on destination gets created\n- **Delete**: Mapping exists but source event is gone — destination event gets removed\n- **Cleanup**: Keeper-created events with no mapping are cleaned up\n\nEvents created by Keeper are tagged with a `@keeper.sh` suffix on their remote UID. For Outlook (which doesn't support custom UIDs), a `\"keeper.sh\"` category is used instead.\n\nRace conditions are prevented using Redis-backed generation counters. If two syncs target the same calendar simultaneously, the later one backs off.\n\nFor Google and Outlook, Keeper uses incremental sync tokens — only fetching what changed since the last sync, making cycles fast even for calendars with thousands of events.\n\n### Supported Providers\n\n**OAuth providers:**\n- **Google Calendar** — full read/write, supports filtering Focus Time, Working Location, and Out of Office events\n- **Microsoft Outlook** — full read/write via Microsoft Graph API\n\n**CalDAV-based providers:**\n- **FastMail** — pre-configured CalDAV\n- **iCloud** — pre-configured CalDAV with app-specific password support\n- **Generic CalDAV** — any CalDAV-compatible server\n- **iCal/ICS feeds** — read-only URL-based calendars\n\nEach calendar has capability flags: \"pull\" (read events from) and \"push\" (write events to). iCal feeds are pull-only. OAuth and CalDAV calendars support both.\n\n### Privacy Controls\n\nBy default, only busy/free time blocks are shared. Event titles, descriptions, locations, and attendee lists are stripped before syncing.\n\nPer-source calendar settings:\n- Include or exclude event titles (replace with \"Busy\")\n- Include or exclude descriptions and locations\n- Custom event name templates using `{{event_name}}` or `{{calendar_name}}` placeholders\n- Skip all-day events\n- Skip Google-specific event types (Focus Time, Working Location, Out of Office)\n\n### iCal Feed\n\nKeeper generates a unique, token-authenticated URL combining events from selected source calendars. Subscribable from any calendar app supporting iCal (Apple Calendar, Thunderbird, etc.). Respects all privacy settings.\n\n### Source and Destination Mappings\n\nConnect calendar accounts, then configure which calendars are sources and which are destinations. A single source can push to multiple destinations. A single destination can receive from multiple sources.\n\nSetup flow:\n1. Connect an account (OAuth, CalDAV, or iCal URL)\n2. Select calendars\n3. Rename for clearer labels\n4. Map sources to destinations\n\n## Pricing\n\n- **Free**: 2 linked accounts, 2 calendars per account, 30-minute sync intervals, aggregated iCal feed\n- **Pro ($5/month)**: Unlimited accounts, unlimited calendars, 1-minute sync intervals, priority support\n\nSelf-hosted instances get Pro-tier features by default.\n\n## Self-Hosting\n\nThe entire stack runs on PostgreSQL, Redis, Bun, and Vite + React.\n\nThree deployment models:\n- **Standalone**: Single `compose.yaml` bundling Caddy, PostgreSQL, Redis, API, web, and cron\n- **Services-only**: Application containers only (bring your own PostgreSQL and Redis)\n- **Individual containers**: Separate `keeper-web`, `keeper-api`, `keeper-cron`, and `keeper-mcp` images\n\nGoogle Calendar and Outlook require OAuth app setup (Google Cloud / Azure). CalDAV providers and iCal feeds work without OAuth.\n\n## MCP (Model Context Protocol)\n\nKeeper includes an optional MCP server that gives AI agents (such as Claude) read-only access to calendar data. The server authenticates via OAuth 2.1 with a user consent flow and is proxied through the web service at `/mcp`.\n\n### Available Tools\n\n- **list_calendars** — List all calendars connected to Keeper, including provider name and account\n- **get_events** — Get calendar events within a date range (ISO 8601 datetimes + IANA timezone)\n- **get_event_count** — Get the total number of synced calendar events\n\n### Connecting\n\nPoint any MCP-compatible client at the `/mcp` endpoint of a Keeper instance. The client will be guided through the OAuth consent flow to authorize read access.\n\nMCP is fully optional — all related environment variables are optional across every service. Existing deployments are unaffected when upgrading.\n\n## Technical Architecture\n\n- **CalDAV as universal protocol**: RFC 4791 as the common layer for FastMail, iCloud, and standards-compliant servers\n- **Encrypted credentials at rest**: CalDAV passwords and OAuth tokens encrypted with configurable key\n- **Content hashing for iCal feeds**: Skips processing if feed content unchanged, keeps snapshots for 6 hours\n- **Real-time sync status**: WebSocket endpoint broadcasts sync progress to dashboard\n- **MCP via OAuth 2.1**: Separate MCP server with JWT-based session resolution, proxied through the web service at `/mcp`\n\n## Links\n\n- Homepage: https://keeper.sh\n- Blog: https://keeper.sh/blog\n- Privacy Policy: https://keeper.sh/privacy\n- Terms & Conditions: https://keeper.sh/terms\n- GitHub: https://github.com/ridafkih/keeper.sh\n\n## Maintainer\n\nMaintained by Rida F'kih (https://rida.dev)\n"
},
{
"path": "applications/web/public/llms.txt",
"content": "# Keeper.sh\n\n> Open-source calendar event syncing. Synchronize events between your personal, work, business and school calendars.\n\nKeeper.sh is an open-source (AGPL-3.0) calendar synchronization service that keeps time slots aligned across multiple calendar providers. It uses a pull-compare-push architecture to sync events between Google Calendar, Outlook, FastMail, iCloud, CalDAV, and iCal feeds.\n\n## Key Features\n\n- Universal calendar sync across Google Calendar, Outlook, Apple Calendar, FastMail, CalDAV, and iCal feeds\n- Privacy-first: only busy/free time blocks are shared by default, with granular controls for titles, descriptions, and locations\n- Aggregated iCal feed generation for sharing availability externally\n- MCP (Model Context Protocol) server for AI agent calendar access via OAuth 2.1\n- Self-hostable with Docker Compose (standalone, services-only, or individual containers)\n- Free tier (30-minute sync, 2 accounts) and Pro tier ($5/month, 1-minute sync, unlimited)\n\n## Links\n\n- [Homepage](https://keeper.sh)\n- [Blog](https://keeper.sh/blog)\n- [Privacy Policy](https://keeper.sh/privacy)\n- [Terms & Conditions](https://keeper.sh/terms)\n- [GitHub Repository](https://github.com/ridafkih/keeper.sh)\n- [Full LLM Context](https://keeper.sh/llms-full.txt)\n"
},
{
"path": "applications/web/public/robots.txt",
"content": "User-agent: *\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: GPTBot\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: ChatGPT-User\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: ClaudeBot\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: PerplexityBot\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: Google-Extended\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: Amazonbot\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: Applebot\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: Bytespider\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nUser-agent: Cohere-AI\nAllow: /\nDisallow: /dashboard\nDisallow: /auth\nDisallow: /login\nDisallow: /register\nDisallow: /verify-email\nDisallow: /verify-authentication\nDisallow: /reset-password\nDisallow: /forgot-password\n\nSitemap: https://keeper.sh/sitemap.xml\n"
},
{
"path": "applications/web/public/site.webmanifest",
"content": "{\n \"name\": \"Keeper.sh\",\n \"short_name\": \"Keeper\",\n \"start_url\": \"/\",\n \"icons\": [\n {\n \"src\": \"/180x180-light-on-dark.png\",\n \"sizes\": \"180x180\",\n \"type\": \"image/png\"\n },\n {\n \"src\": \"/180x180-light-on-dark.png\",\n \"sizes\": \"192x192\",\n \"type\": \"image/png\",\n \"purpose\": \"any\"\n },\n {\n \"src\": \"/512x512-on-light.png\",\n \"sizes\": \"512x512\",\n \"type\": \"image/png\"\n }\n ],\n \"theme_color\": \"#FAFAFA\",\n \"background_color\": \"#FAFAFA\",\n \"display\": \"standalone\"\n}\n"
},
{
"path": "applications/web/scripts/build.ts",
"content": "import { build } from \"bun\";\n\nawait build({\n entrypoints: [\"src/server/index.ts\"],\n outdir: \"./dist/server-entry\",\n target: \"bun\",\n splitting: false,\n external: [\n \"entrykit\",\n \"linkedom\",\n \"fast-xml-parser\",\n \"vite\",\n \"yaml\",\n \"widelogger\",\n \"pino-opentelemetry-transport\",\n ],\n});\n"
},
{
"path": "applications/web/scripts/start.ts",
"content": "import { existsSync } from \"node:fs\";\n\nconst serverEntryUrl = new URL(\"../dist/server-entry/index.js\", import.meta.url);\n\nif (!existsSync(serverEntryUrl)) {\n throw new Error(\n \"Missing production server entry at applications/web/dist/server-entry/index.js. Run `bun run build` before `bun run start`.\",\n );\n}\n\nawait import(serverEntryUrl.href);\n"
},
{
"path": "applications/web/src/components/analytics-scripts.tsx",
"content": "import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\nimport { useLocation } from \"@tanstack/react-router\";\nimport type { PublicRuntimeConfig } from \"@/lib/runtime-config\";\nimport {\n identify,\n resolveEffectiveConsent,\n track,\n} from \"@/lib/analytics\";\nimport { useSession } from \"@/hooks/use-session\";\n\nconst subscribe = (callback: () => void): (() => void) => {\n window.addEventListener(\"storage\", callback);\n return () => window.removeEventListener(\"storage\", callback);\n};\n\nconst getServerSnapshot = (): boolean => false;\n\nfunction resolveConsentLabel(hasConsent: boolean): \"granted\" | \"denied\" {\n if (hasConsent) return \"granted\";\n return \"denied\";\n}\n\nfunction AnalyticsScripts({ runtimeConfig }: { runtimeConfig: PublicRuntimeConfig }) {\n const { gdprApplies, googleAdsId, visitorsNowToken } = runtimeConfig;\n const getSnapshot = useCallback(\n () => resolveEffectiveConsent(gdprApplies),\n [gdprApplies],\n );\n const hasConsent = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n const location = useLocation();\n const consentState = resolveConsentLabel(hasConsent);\n const { user } = useSession();\n const identifiedUserId = useRef(null);\n\n useEffect(() => {\n track(\"page_view\", { path: location.pathname });\n }, [location.pathname]);\n\n useEffect(() => {\n if (!user) return;\n if (identifiedUserId.current === user.id) return;\n\n identifiedUserId.current = user.id;\n identify({ id: user.id, email: user.email, name: user.name }, { gdprApplies });\n }, [user, gdprApplies]);\n\n return (\n <>\n {visitorsNowToken && (\n \n {children}\n
\n );\n}\n\nfunction ConsentBannerActions({ children }: PropsWithChildren) {\n return (\n \n {children}\n
\n );\n}\n\nfunction ConsentBannerCard({ children }: PropsWithChildren) {\n return (\n \n {children}\n
\n );\n}\n\nfunction CookieConsent() {\n const [visible, setVisible] = useState(() => !hasConsentChoice());\n\n const handleChoice = useCallback((consent: boolean): void => {\n track(resolveConsentEventName(consent));\n setAnalyticsConsent(consent);\n setVisible(false);\n }, []);\n\n return (\n \n
\n
\n \n {visible && (\n \n \n \n \n \n Can Keeper{\" \"}\n \n use cookies for analytics?\n \n \n \n handleChoice(true)}>\n Yes \n \n handleChoice(false)}>\n No \n \n \n \n \n \n \n )}\n \n \n
\n
| void;\n label?: string;\n children?: ReactNode;\n defaultEditing?: boolean;\n disabled?: boolean;\n className?: string;\n} & ({ value: string } | { getValue: () => string });\n\nexport function NavigationMenuEditableItem(props: NavigationMenuEditableItemProps) {\n const {\n onCommit,\n label,\n children,\n defaultEditing,\n disabled,\n className,\n } = props;\n\n const resolveValue = () => \"getValue\" in props ? props.getValue() : props.value;\n\n const [editing, setEditing] = useState(defaultEditing ?? false);\n\n const startEditing = () => setEditing(true);\n const stopEditing = () => setEditing(false);\n\n if (editing) {\n return (\n {\n await onCommit(trimmed);\n stopEditing();\n }}\n onCancel={stopEditing}\n />\n );\n }\n\n return (\n \n {children ?? | void;\n label?: string;\n valueContent?: ReactNode;\n children?: ReactNode;\n renderInput: (value: string) => ReactNode;\n defaultEditing?: boolean;\n disabled?: boolean;\n className?: string;\n} & ({ value: string } | { getValue: () => string });\n\nexport function NavigationMenuEditableTemplateItem(props: NavigationMenuEditableTemplateItemProps) {\n const {\n onCommit,\n label,\n valueContent,\n children,\n renderInput,\n defaultEditing,\n disabled,\n className,\n } = props;\n\n const resolveValue = () => \"getValue\" in props ? props.getValue() : props.value;\n\n const [editing, setEditing] = useState(defaultEditing ?? false);\n\n const startEditing = () => setEditing(true);\n const stopEditing = () => setEditing(false);\n\n if (editing) {\n return (\n {\n await onCommit(trimmed);\n stopEditing();\n }}\n onCancel={stopEditing}\n />\n );\n }\n\n return (\n \n {children ?? | void,\n onCancel: () => void,\n) {\n const inputRef = useRef(null);\n const committingRef = useRef(false);\n\n const commit = async () => {\n if (committingRef.current) return;\n\n const trimmed = inputRef.current?.value.trim();\n if (!trimmed || trimmed === value) {\n onCancel();\n return;\n }\n\n committingRef.current = true;\n try {\n await onCommit(trimmed);\n } finally {\n committingRef.current = false;\n }\n };\n\n const handleKeyDown = (event: ReactKeyboardEvent) => {\n if (event.key === \"Enter\") {\n event.preventDefault();\n void commit();\n }\n\n if (event.key === \"Escape\") {\n onCancel();\n }\n };\n\n const inputProps = {\n ref: inputRef,\n type: \"text\" as const,\n defaultValue: value,\n autoComplete: \"off\",\n onBlur: () => {\n void commit();\n },\n onKeyDown: handleKeyDown,\n autoFocus: true,\n };\n\n return { inputProps };\n}\n\nfunction EditableItemInput({\n value,\n label,\n className,\n onCommit,\n onCancel,\n}: {\n value: string;\n label?: string;\n className?: string;\n onCommit: (value: string) => Promise | void;\n onCancel: () => void;\n}) {\n const variant = use(MenuVariantContext);\n const { inputProps } = useEditableCommit(value, onCommit, onCancel);\n const inputClass = cn(\n \"min-w-0 text-sm tracking-tight bg-transparent cursor-text outline-none\",\n label ? \"flex-1 text-right\" : \"flex-1\",\n );\n\n return (\n \n \n {label && {label} }\n
\n \n );\n}\n\nfunction EditableTemplateItemInput({\n value,\n label,\n className,\n renderInput,\n onCommit,\n onCancel,\n}: {\n value: string;\n label?: string;\n className?: string;\n renderInput: (value: string) => ReactNode;\n onCommit: (value: string) => Promise | void;\n onCancel: () => void;\n}) {\n const variant = use(MenuVariantContext);\n const { inputProps } = useEditableCommit(value, onCommit, onCancel);\n const inputClass = cn(\n \"min-w-0 text-sm tracking-tight bg-transparent cursor-text outline-none\",\n label ? \"flex-1 text-right\" : \"flex-1\",\n );\n\n return (\n \n \n {label &&
{label} }\n
\n
\n
\n );\n}\n\nfunction TemplateInputOverlay({\n inputRef,\n defaultValue,\n renderInput,\n label,\n}: {\n inputRef: React.RefObject;\n defaultValue: string;\n renderInput: (value: string) => ReactNode;\n label?: string;\n}) {\n const [liveValue, setLiveValue] = useState(defaultValue);\n const overlayRef = useRef(null);\n\n useEffect(() => {\n const input = inputRef.current;\n if (!input) return;\n\n const handleInput = () => setLiveValue(input.value);\n const handleScroll = () => {\n if (overlayRef.current) overlayRef.current.scrollLeft = input.scrollLeft;\n };\n\n input.addEventListener(\"input\", handleInput);\n input.addEventListener(\"scroll\", handleScroll);\n return () => {\n input.removeEventListener(\"input\", handleInput);\n input.removeEventListener(\"scroll\", handleScroll);\n };\n }, [inputRef]);\n\n return (\n \n {renderInput(liveValue)}\n