Files
raucao 66e58c49da Cut and publish extension releases from the version lifecycle
Releases were built and signed in CI, which meant AMO credentials had to
live on the runner. Move the whole flow local: builds and Firefox signing
happen on the maintainer's machine and only the finished artifacts are
published.

Add `ext:pack:firefox` and `ext:pack:chrome` (production builds; the
Firefox one is signed via `web-ext sign` unlisted with credentials read
from the GNOME Keyring through `secret-tool`, the Chrome one is zipped)
and wire them to the `version` lifecycle:

- `preversion` runs lint and tests.
- `version` builds and signs into `web-ext-artifacts/`.
- `postversion` pushes the bump commit and tag, then uploads both
  artifacts to the Gitea release and publishes it if still a draft.

Switch the plain `ext:build:*` scripts to production and add
`ext:build:dev:*` for development builds; `ext:dev` is unchanged. The
build manifest now takes its version from package.json and drops the
"(dev)" name suffix when `DASHTAB_RELEASE=1`.

Because packaging needs a production build, relax the AGENTS.md
production-build restriction to allow it for packaging and releasing.
2026-11-10 12:14:14 +04:00

4.7 KiB

AGENTS.md

Overview

Dashtab is a client-side new-tab dashboard distributed as a Manifest V3 browser extension and built with Ember.js, Vite, and Tailwind CSS. It features widgets (clock, greeting), customizable wallpapers, and third-party integrations (e.g., Discourse).

Tech Stack

  • Framework: Ember.js (Octane) with Embroider & Vite (@embroider/vite)
  • Components: Glimmer Template Tag format (.gjs)
  • Styling: Tailwind CSS v4 (@tailwindcss/vite) & @tailwindplus/elements
  • Storage: localforage (IndexedDB / LocalStorage)
  • Cryptography: Web Crypto API & node-forge
  • Testing: QUnit, @ember/test-helpers, qunit-dom, testem
  • Distribution: Manifest V3 browser extension (Chrome/Firefox); the web build is dev-only
  • Package Manager: pnpm

Code Layout

  • app/components/: UI components using .gjs single-file template tags.
  • app/services/: Shared state and logic (e.g., clock.js, storage.js).
  • app/routes/ & app/templates/: Route definitions and .gjs templates.
  • app/styles/: Application styles and Tailwind entry points.
  • doc/: Protocol notes and integration specifications.
  • extension/: Chrome/Firefox MV3 manifests; extension/build/<target>/ is generated output.
  • tests/: QUnit tests (tests/integration/ for .gjs components, tests/unit/ for services).

Commands

  • pnpm start: Run the app in the browser for development only (http://localhost:4200).
  • pnpm test: Build and run the test suite via Testem.
  • pnpm lint: Run all linters (ESLint, Prettier, stylelint, template-lint).
  • pnpm lint:fix: Auto-fix linting and formatting issues.
  • pnpm ext:dev: Watch-build the Firefox extension (development) and launch it via web-ext.
  • pnpm ext:build:chrome / pnpm ext:build:firefox: Build the extension (production).
  • pnpm ext:build:dev:chrome / pnpm ext:build:dev:firefox: Build the extension (development).
  • pnpm ext:pack: Build, sign (Firefox, via AMO) and package both targets into web-ext-artifacts/.
  • pnpm version <patch|minor|major>: Cut a release — lints/tests, bumps the version, builds and signs, commits and tags, pushes, and uploads to the Gitea release.
  • pnpm ext:lint: Lint the packaged Firefox extension with web-ext.

Browser Extension

Dashtab is a Manifest V3 browser extension that overrides the new tab. It can also run as a plain web app via pnpm start, but that path exists only for development convenience. vite.config.mjs switches to relative asset paths and writes the target manifest into extension/build/<target>/ when DASHTAB_EXT=1, with DASHTAB_EXT_TARGET selecting chrome or firefox. The written manifest takes its version from package.json and drops the (dev) name suffix when DASHTAB_RELEASE=1. Never edit extension/build/ by hand.

  • Manifests: extension/manifest.chrome.json and extension/manifest.firefox.json. Extension ids are pinned (Chrome key, Firefox browser_specific_settings.gecko.id) so identity.getRedirectURL() stays stable.
  • Auth transport: app/auth/transport.js feature-detects the identity API (app/utils/extension.js). The extension uses identity.launchWebAuthFlow + getRedirectURL; the dev-server build (no identity API) falls back to a full-page redirect to the provider callback. See doc/extension_auth.md.
  • Releasing: pnpm version <bump> builds and signs locally (the Firefox XPI is signed via AMO, with credentials read from the GNOME Keyring) and publishes a Gitea release with the signed .xpi and a Chrome .zip. See scripts/release/.

Key Conventions

  • Component Format: Author all new components and templates in Glimmer Template Tag (.gjs) syntax.
  • State & Services: Use autotracking (@tracked) for state. Inject services with @service.
  • Client Persistence: Access client storage exclusively through service:storage (using namespaces: preferences, integrations, settings).
  • Integration Security: Cryptographic keypairs for third-party auth flows are generated via Web Crypto API and decrypted via node-forge; private keys must be purged once authorization is complete.
  • Testing: Write component tests in .gjs with <template> and render(). Use qunit-dom assertions. Run pnpm lint and pnpm test to verify changes.

Agent Restrictions

  • No Git Write Operations: Do not run Git commands that mutate state or commit changes (e.g., git commit, git add, git push, etc.) without being asked to do so, or without asking for approval first.
  • Production Builds: Run pnpm build or production builds only when packaging or releasing an extension (pnpm ext:build:*, pnpm ext:pack, pnpm version). For day-to-day development use pnpm start (or pnpm ext:dev) and pnpm test.