Imported from luchopcerra/ascii-ticker (AGENTS.md). Install upstream with npx skills add luchopcerra/ascii-ticker. Copyright stays with the author.

AGENTS.md

Runtime

• This is a Cloudflare Worker, not a Node/Express server. The deployed entrypoint is src/worker.ts, configured by wrangler.jsonc.
• Runtime env comes from Worker bindings in wrangler.jsonc (CACHE_TTL_MS, COINGECKO_API_URL); do not use process.env in Worker code.
• Use Worker/web APIs (Request, Response, fetch, URL) and keep Cloudflare compatibility in mind.

Commands

• Install: npm install
• Local dev: npm run dev (wrangler dev; local URL is usually http://localhost:8787, not 3000).
• Typecheck/test/build: npm run check, npm test -- --run, and npm run build.
• Deploy dry run: npx wrangler deploy --dry-run.
• Deploy for real: npm run deploy after Cloudflare auth (npx wrangler login).
• Manage secrets: npx wrangler secret put <NAME>.

Verification

• Baseline verification is npm run check, npm test -- --run, npm run build, and npx wrangler deploy --dry-run.
• For a focused smoke test, run npm run dev and hit curl "http://localhost:8787/btc?format=json".
• The app fetches live CoinGecko data, so smoke tests depend on network access and upstream API availability.

Code Map

• src/worker.ts owns routing: /, /:asset, /api/prices, /api/assets, /health, /x-webhook.
• src/assets.ts is the supported asset registry and alias lookup; add new symbols there using CoinGecko ids.
• src/coingecko.ts fetches and normalizes upstream market data and keeps a per-isolate in-memory cache.
• src/render.ts owns terminal/plain-text rendering; preserve curl-friendly text output when changing responses.
• src/x-bot.ts owns the X/Twitter bot webhook: CRC challenge-response, mention parsing, OAuth 1.0a signing, and posting replies.

X Bot (Webhook)

• The webhook endpoint is GET/POST /x-webhook. X sends GET for CRC validation and POST for mention events.
• All X API credentials deployed via wrangler secret put: X_BEARER_TOKEN, X_CONSUMER_KEY, X_CONSUMER_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET.
• Vars in wrangler.jsonc: X_BOT_USER_ID (only non-secret).
• scripts/x-setup.mjs handles one-time webhook registration + subscription via the X API v2 Account Activity API.
• X_BEARER_TOKEN must use URL-encoded form (%2B for +, %3D for =) because X rejects the decoded value.

Gotchas

• package.json has no runtime dependencies; avoid adding Node-only packages unless they work in Workers.
• dist/ is generated by TypeScript and ignored; Wrangler deploys from src/worker.ts.
• Text responses intentionally add ANSI color only for curl/httpie/wget user agents; JSON is selected with ?format=json or Accept: application/json.
• Bearer Token has URL-encoded characters (%2B, %3D) — keep them encoded everywhere (.dev.vars, secrets, scripts). X rejects the decoded form.