DOCSEARCHbyAlgolia
Submit Docs

petdex Documentation

repository·main·Indexed 25 days ago

https://github.com/crafter-station/petdex

A CLI and desktop application ecosystem for browsing, installing, and submitting animated pets for coding agents. Includes a CLI for asset management, a Discord bot for community interaction and webhooks, a native desktop application, and integration guides for ChatGPT via codex:// deep links.

Tokens
18.4K
Snippets
43
Records
117
Agent score
87%

What's inside petdex

  1. Review Petdex Infrastructure Implementation Plans

    main

    The plans/README.md file tracks the execution of infrastructure cost-optimization plans for Petdex, specifically focusing on the migration from Vercel to Cloudflare and reducing infrastructure expenses. The plans are prioritized by impact and effort, following a specific execution order to mitigate risks like Error 1027 outages.

    Key Optimization Strategies implemented:

    • Edge Caching: Serving assets from assets.petdex.dev via Cloudflare edge cache with specific TTL overrides and CORS settings.
    • HTML Caching: Making anonymous public HTML cacheable by Cloudflare by managing NEXT_LOCALE cookies and Cloudflare-CDN-Cache-Control headers.
    • Static/ISR Conversion: Converting high-traffic routes like /requests, /leaderboard, and /download to static or Incremental Static Regeneration (ISR) to reduce dynamic compute.
    • Middleware Optimization: Reducing middleware overhead by offloading WAF tasks and optimizing Clerk authentication scopes.
    • Server-First Shell: Reducing client-side JS size by dropping global Clerk/header requirements for public shells.

  2. Verify Cloudflare Edge Caching for Anonymous HTML

    main

    To ensure that anonymous public HTML routes are correctly cached by Cloudflare and not triggering unnecessary Vercel hits, verify the following using curl:

    1. Check for Cookie Suppression: A request to a public route (e.g., https://petdex.dev/en) must not contain a set-cookie: NEXT_LOCALE header.
    2. Check Cache Status: A second consecutive request to the same route should return a cf-cache-status: HIT header.
    3. Verify Session Bypass: Ensure that any request containing a __session cookie is not served from the cache (it should bypass the cache to ensure authenticated users see correct data).
    4. Verify Locale Integrity: Ensure /zh serves HTML with lang="zh" and /es serves Spanish content.
    curl -sI https://petdex.dev/en

  4. Implement hotlink protection via WAF rules

    main

    Replace the Worker's referer-gating logic with a Cloudflare WAF rule. This allows CLI, desktop, and direct requests (which have no Referer) while blocking hotlinking from foreign websites.

    WAF Custom Rule Configuration:

    • Expression: (http.host eq "assets.petdex.dev" and http.referer ne "" and not http.referer contains "petdex.dev" and not http.referer contains "localhost")
    • Action: Block

    Verification:

    • No Referer (CLI/App): curl -s -o /dev/null -w "%{http_code}" https://assets.petdex.dev/manifests/petdex-v1.json $\rightarrow$ 200
    • Foreign Referer: curl -s -o /dev/null -w "%{http_code}" -H "Referer: https://evil.example/" https://assets.petdex.dev/manifests/petdex-v1.json $\rightarrow$ 403
    • Allowed Referer: curl -s -o /dev/null -w "%{http_code}" -H "Referer: https://petdex.dev/en" https://assets.petdex.dev/manifests/petdex-v1.json $\rightarrow$ 200

  5. Configure Cloudflare Cache Rules for assets.petdex.dev

    main

    To ensure zero origin reads on warm traffic, enable edge caching for the asset hostname in the Cloudflare dashboard (Caching $\rightarrow$ Cache Rules) or via API.

    Rule Configuration:

    • Expression: (http.host eq "assets.petdex.dev")
    • Action: Eligible for cache ("Cache Everything")
    • Edge TTL: "Use cache-control header if present, else 1 day"
    • Browser TTL: Respect origin

    Verification: Run curl -sI twice, approximately 5 seconds apart. The first request should return cf-cache-status: MISS (or EXPIRED), and the second should return cf-cache-status: HIT.

  6. Convert /download to static/ISR

    main

    The /download page can be converted to static/ISR by moving the activation command logic into a client-side component.

    Implementation Steps

    1. Modify Server Component: In src/app/[locale]/download/page.tsx, remove export const dynamic = "force-dynamic"; and the stale GitHub release fetch comments. Add export const revalidate = 3600;.
    2. Create Client Island: Implement a new component src/components/download-activation-command.tsx. This component should use useSearchParams() inside a <Suspense> boundary to read the next parameter.
    3. Command Logic:
      • If next is present: Render npx petdex install <slug>.
      • If next is absent: Render npx petdex init.
    4. Preview Pet: Keep the preview pet server-side but pin it to DEFAULT_PREVIEW_PET_SLUG to maintain static compatibility.

    Verification

    • Mock build should show /[locale]/download as static/ISR.
    • Verify command generation: curl -s "http://localhost:3000/en/download?next=nukey" should return a 200 OK and the command should include nukey.
    export const revalidate = 3600;

  8. Diagnose asset hosting for assets.petdex.dev

    main

    Before optimizing asset delivery, determine if assets.petdex.dev is served by an R2 custom domain or a Cloudflare Worker. This determines whether you need to migrate the hostname from the Worker to the R2 bucket.

    Use the following commands to investigate:

    • Check R2 custom domains: bunx wrangler r2 bucket domain list petdex-pets
    • Check Worker deployments: bunx wrangler deployments list --name petdex-assets
    • Check Cloudflare Dashboard: Navigate to Workers & Pages $\rightarrow$ petdex-assets $\rightarrow$ Settings $\rightarrow$ Domains & Routes.

    Outcomes:

    • Scenario A: assets.petdex.dev is an R2 custom domain. Proceed to adding Cache Rules.
    • Scenario B: assets.petdex.dev is a Worker route. You must first move the hostname to the R2 bucket (Step 2a) before adding Cache Rules.
    bunx wrangler r2 bucket domain list petdex-pets
bunx wrangler deployments list --name petdex-assets

  9. Verify project drift before executing Plan 005

    main

    Before starting the refactor described in Plan 005, run the following drift check command to ensure the in-scope files have not changed since the plan was written. If there is a mismatch between the 'Current state' in the plan and the live code, stop and report it.

    git diff --stat 82ffb6b..HEAD -- "src/app/[locale]/layout.tsx" src/components/theme-providers.tsx src/components/header-state-provider.tsx src/components/site-header.tsx src/components/feedback-widget.tsx

  10. Configure R2 Bucket CORS for assets.petdex.dev

    main

    When using an R2 custom domain instead of a Worker, you must configure CORS directly on the R2 bucket to allow the web application to fetch assets.

    CORS Configuration: Set a policy that allows GET and HEAD methods from https://petdex.dev and http://localhost:3000.

    Command:

    bunx wrangler r2 bucket cors set petdex-pets --file <(echo '[{"AllowedOrigins":["https://petdex.dev","http://localhost:3000"],"AllowedMethods":["GET","HEAD"],"AllowedHeaders":["Range"],"MaxAgeSeconds":86400}]')

    Verification: Check the Access-Control-Allow-Origin header using curl: curl -sI -H "Origin: https://petdex.dev" https://assets.petdex.dev/manifests/petdex-v1.json | grep -i access-control-allow-origin

  11. Build the Petdex Community Discord server using Claude Code

    main

    To automate the setup of the Petdex Community Discord server, you can use Claude Code combined with the discord-mcp container. This process uses a template file to instruct Claude to execute specific Discord MCP tools to create roles, categories, and channels.

    Prerequisites

    1. Start the discord-mcp container.
    2. Add the MCP to Claude using the following command:
      claude mcp add discord -t http http://localhost:8085/mcp

    Execution Steps

    1. Provide the Template: Copy the contents of docs/discord/apply-template.md and paste it as a single message into a Claude Code session.
    2. Automated Build: Claude will read docs/discord/server-template.json and use the discord-mcp toolset to:
      • Verify the guild matches the DISCORD_GUILD_ID environment variable.
      • Set the guild icon to public/brand/discord-icon.png (if supported by the MCP).
      • Create roles with exact colors, hoisting, and permissions.
      • Create categories and channels (text, announcement, or voice) with exact names, emojis, and topics.
      • Configure permissions for lockedToBot: true channels and private: true categories.
    3. Verification: Claude will call list_channels to provide a tree view of the resulting structure.
    4. Manual Follow-ups: Claude will identify items in the _followups section of the template that require manual configuration via the Discord Server Settings UI (e.g., AutoMod or Community enablement).
    claude mcp add discord -t http http://localhost:8085/mcp

  12. Submit a pet to the gallery

    main

    You can submit pets using the petdex submit <path> command. The CLI supports three input shapes:

    • Single folder: Must contain pet.json and spritesheet.{webp,png}.
    • Single zip: Must have the same root layout as a folder.
    • Parent folder: Every subfolder containing a pet.json will be submitted (bulk).

    Validation Rules:

    • pet.json and spritesheet.webp (or .png) must exist at the root.
    • Spritesheet must be an 8x9 grid (1536x1872) or a v2 8x11 grid (1536x2288), or a clean scale of either.
    • Rate limit: 10 submissions / 24h per user.
    petdex submit ~/.petdex/pets/boba      # single folder
petdex submit ~/Downloads/boba.zip     # single zip
petdex submit ~/.petdex/pets           # bulk submit