instagram-cli AGENTS.md

AI Coding Assistant Context

This documentation provides context for AI coding tools like VSCode, Cursor, Gemini CLI, Claude Code, etc.

Project Overview

• Instagram CLI implemented in TypeScript with Pastel (CLI scaffolding), Ink (React TUI), and Instagram Private API + MQTT for backend interactions.
• Primary work happens in source/, tests are contained in tests/.
• Old Python version lives under instagram-py/, work on typescript client unless the user specifies otherwise.

Build & Test Commands

• Install: npm ci
• Development: npm run dev
• Build: npm run build
• Run CLI: npm run start -- <command>
• Tests: npm test

Code Style & Implementation Guidelines

• Pastel command contract: export args (zod tuple) and a default React component; render full-screen UIs inside <AltScreen>; use useInstagramClient to fetch authenticated clients.
• Maintain ClientContext boundaries, inject dependencies into hooks (useStories, etc.) for testability, and call InstagramClient.shutdown() when tearing down realtime sessions.
• Keep ESM imports with explicit .js extensions; mirror existing logging setup via initializeLogger() and createContextualLogger.
• API work lives in source/client.ts plus helpers like utils/message-parser.ts; extend these surfaces rather than scattering raw API calls.
• Place stateless Ink pieces in ui/components, orchestration in ui/views, and derived state in ui/hooks; reuse existing visual patterns (gradients, status bars) for consistency.
• When working with existing components and systems, first check their design description in docs/
• Use linter exceptions (eslint-disable-next-line) sparingly; prefer fixing the underlying issue. If a disable is unavoidable, scope it to the narrowest region (single line when possible) and add a brief justification.

Testing Instructions

• Ink smoke tests reside in tests/ using Ava + ink-testing-library; update or extend them when view output changes.
• When pre-commit hooks are unavailable, run npm run format, npm run lint-check, and npm test locally before submitting work.
• Prefer mock runs (npm run start:mock -- --chat|--feed|--story) during UI work; update source/mocks/mock-data.ts if expectations shift.
• TUI testing quirks: Ink renders to a string buffer, not a real terminal. Use render() from ink-testing-library and assert against lastFrame() output. For visual elements like unread indicators or selection highlights, check for the expected Unicode/ANSI characters in the frame string (e.g., t.truthy(output?.includes('●'))).
• What to test: Component rendering with mock data, keyboard input handling (stdin.write()), edge cases like empty states and Unicode text. Do not test Instagram API calls directly — mock the client.