marco/AGENTS.md

Agent Instructions for Marco

Marco is a privacy-respecting, unhosted maps application that allows users to connect their own remote storage to sync place bookmarks across apps and devices.

Relevant Commands

All commands must be executed using pnpm. Never use npm.

• Install dependencies: pnpm install
• Start development server: pnpm start (Runs Vite)
• Run tests: pnpm test (Builds and runs via Testem)
• Linting:
  • pnpm lint (Runs ESLint, Stylelint, Prettier, and ember-template-lint concurrently)
  • pnpm lint:fix (Automatically fixes linting and formatting errors)

NEVER RUN

• pnpm build (only run for releases by the devs)
• git add, git commit, or any other commands that modify git history or the staging area

Application Architecture & Frameworks

Core Stack

• Framework: Ember.js (Octane / Polaris editions). The project heavily uses modern Ember paradigms including .gjs (template-tag format), @glimmer/component, and @glimmer/tracking.
• Build System: Vite coupled with Embroider (@embroider/vite) for fast, modern asset compilation.

Mapping & Geocoding

• Maps: Uses OpenLayers (ol and ol-mapbox-style) for rendering the map interface.
• Search: Uses the Photon API (via app/services/photon.js) for geocoding and search functionality.
• Data Source: OpenStreetMap (OSM) data is fetched and parsed to display rich place details.

Storage & Authentication

• RemoteStorage: The app is "unhosted" meaning user data isn't locked in a central database. It uses remotestoragejs and @remotestorage/module-places to sync bookmarks to a user's chosen storage provider. (Managed in app/services/storage.js).
• OSM Auth: Allows users to log into OpenStreetMap using OAuth 2.0 PKCE (oauth2-pkce) to fetch user info and potentially interact with OSM directly (Managed in app/services/osm-auth.js).

Directory Structure Highlights

• app/components/: UI components using .gjs (Glimmer JS with embedded <template> tags).
• app/services/: Core business logic, state management, and API integrations.
• app/utils/: Helper functions for geohashing, parsing OSM tags, icon mapping, and link formatting.
• tests/: Comprehensive QUnit test suite containing unit, integration, and acceptance tests.

Key Libraries

• ember-concurrency / ember-lifeline: Managing async tasks and debouncing.
• remotestorage-widget: The UI widget for connecting to a RemoteStorage provider.