Add CLI features, dashboard preferences, and npm release preparation

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
 
       - name: Install dependencies
@@ -37,6 +37,9 @@ jobs:
       - name: Build production bundle
         run: npm run build
 
+      - name: Verify packed npm artifact
+        run: npm run verify:package
+
       - name: Install Playwright browser
         run: npx playwright install --with-deps chromium
 

.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: write
+  id-token: write
 
 concurrency:
   group: release-${{ github.ref_name }}
@@ -28,11 +29,17 @@ jobs:
           git fetch origin main --depth=1
           git branch -r --contains HEAD | grep -q 'origin/main'
 
+      - name: Verify tag matches package version
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          test "v${VERSION}" = "${GITHUB_REF_NAME}"
+
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
+          registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
         run: npm ci --ignore-scripts
@@ -43,12 +50,45 @@ jobs:
       - name: Build production bundle
         run: npm run build
 
+      - name: Verify packed npm artifact
+        run: npm run verify:package
+
       - name: Install Playwright browser
         run: npx playwright install --with-deps chromium
 
       - name: Run end-to-end smoke tests
         run: npm run test:e2e:ci
 
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Publish package to npm
+        run: npm publish
+
+      - name: Wait for npm registry propagation
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          for attempt in 1 2 3 4 5 6; do
+            if npm view "@roastcodes/ttdash@${VERSION}" version >/dev/null 2>&1; then
+              exit 0
+            fi
+            sleep 10
+          done
+          echo "Package was not visible on npm in time."
+          exit 1
+
+      - name: Verify npx install path
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          npx --yes "@roastcodes/ttdash@${VERSION}" --help
+
+      - name: Verify bunx install path
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          bunx "@roastcodes/ttdash@${VERSION}" --help
+
       - name: Create GitHub release
         env:
           GH_TOKEN: ${{ github.token }}

.gitignore

@@ -4,6 +4,7 @@ data.json
 .DS_Store
 .playwright-mcp/
 .tmp-playwright/
+.tmp-smoke-*/
 playwright-report/
 test-results/
 test-json/

AGENTS.md

@@ -18,7 +18,7 @@ During development, keep `npm run dev` and `node server.js` running in separate
 Frontend code is TypeScript + React. Follow the existing style: 2-space indentation, single quotes, trailing commas where the formatter leaves them, and no semicolons in `src/` files. Component, hook, and type filenames use PascalCase or descriptive kebab-free names such as `Dashboard.tsx`, `use-usage-data.ts`, and `formatters.ts`. Keep utilities small and colocate feature-specific UI under `src/components/features/`. In `server.js`, preserve the current CommonJS style and semicolon usage instead of rewriting it to match the frontend.
 
 ## Testing Guidelines
-There is no committed automated test suite yet. Before opening a PR, run `npm run build` and manually verify the main flows: dashboard load, auto-import, JSON upload, filtering, and export actions. If you add tests, prefer colocated `*.test.ts` or `*.test.tsx` files and keep them focused on data transforms, hooks, or complex UI behavior.
+Automated tests are part of the repo now. Before opening a PR, run `npm run build`, `npm run test:unit`, `npm run verify:package`, and `npm run test:e2e`. If local port `3015` is already in use, run Playwright with `PLAYWRIGHT_TEST_PORT=3016 npm run test:e2e`. Continue to manually verify the main flows affected by the change: dashboard load, auto-import, JSON upload, filtering, and export actions. If you add tests, prefer focused `*.test.ts` or `*.test.tsx` coverage for data transforms, hooks, or complex UI behavior.
 
 ## Commit & Pull Request Guidelines
 Recent history favors short, imperative subjects, often with a version prefix, for example `v5.3.1: Fix timezone bug` or `Fix install.sh -e output`. Keep commits narrowly scoped. PRs should explain the user-visible change, note any manual verification performed, link related issues, and include screenshots or GIFs for UI changes.

CHANGELOG.md

@@ -1,41 +1,63 @@
 # Changelog
 
+## [Unreleased]
+
+## [6.1.0] - 2026-04-11
+
+### Added
+- **Background CLI mode** — `--background` starts the local server as a detached background process, and `ttdash stop` lists running instances so the selected one can be stopped directly
+- **Settings backups and layout preferences** — the settings dialog now supports backup import/export, conservative usage-data restore, default dashboard filters, section visibility, and section ordering
+- **Packaged CLI verification** — `npm run verify:package` now builds the real tarball and verifies that the packaged `ttdash` CLI can install, print help, and start outside the repo checkout
+- **Scoped package release prep** — the package is now prepared for the first public scoped release as `@roastcodes/ttdash`
+
+### Improved
+- **Dashboard settings model** — provider limits, persisted filters, section visibility, and section order now behave as first-class stored settings across fresh starts and backup restore flows
+- **CLI and installer UX** — terminal output, help text, and installer guidance now use English-first release-facing messaging
+- **Metrics and report correctness** — aggregated dashboard metrics, provider day counting, filter-preset behavior, and PDF language handling were corrected and aligned with the current view state
+- **Release workflow** — tagged releases now verify the packed artifact, publish the scoped package, and smoke-check both `npx` and `bunx` after publish
+- **Repository documentation** — README, contribution, release, security, and conduct docs were rewritten for a public, maintainer-led npm project
+
+### Fixed
+- **Race-safe background registry** — parallel `--background` starts briefly lock the local instance registry so no running server gets dropped from the tracked list
+- **Conservative data import** — backup imports add missing days, skip identical days, and keep conflicting local days instead of silently overwriting them
+- **Playwright release validation** — the E2E configuration now supports an override port so local release verification does not fail when the default smoke-test port is already occupied
+
 ## [6.0.11] - 2026-04-10
 
 ### Fixed
-- **Idempotenter Bun-Installer** — `install.sh` und `install.bat` bereinigen vor `bun add -g file:...` jetzt vorhandene `ttdash`-Einträge aus Bun’s globalem Manifest und löschen bei Bedarf das fehlerhafte globale `bun.lock`, damit wiederholte Upgrades keine doppelten `package.json`-Keys mehr erzeugen
+- **Idempotent Bun installer** — `install.sh` and `install.bat` now clean existing `ttdash` entries from Bun’s global manifest before `bun add -g file:...` and remove the broken global `bun.lock` when needed, so repeated upgrades do not create duplicate `package.json` keys
 
 ## [6.0.10] - 2026-04-09
 
 ### Added
-- **GitHub Release-Workflow** — ein separater `release.yml` erstellt jetzt GitHub Releases automatisiert auf `v*`-Tags, prüft vorher Tests und Build und akzeptiert nur Tags auf `main`
+- **GitHub release workflow** — a dedicated `release.yml` now creates GitHub releases automatically on `v*` tags, verifies tests and build first, and only accepts tags on `main`
 
 ### Improved
-- **README-Projektkontext** — die Dokumentation verweist jetzt explizit auf `toktrack` als Basisdatenquelle und bedankt sich bei `mag123c`
+- **README project context** — the documentation now points explicitly to `toktrack` as the primary data source and credits `mag123c`
 
 ## [6.0.9] - 2026-04-09
 
 ### Added
-- **Automatisierte Testpyramide** — Vitest deckt jetzt Datennormalisierung, Berechnungen, Hook-Logik und den lokalen Serverpfad ab; Playwright prüft den Upload-zu-Dashboard-Smoke-Flow mit echten Browser-Reports
-- **CI-Testpipeline** — GitHub Actions führt Build, Coverage, Playwright-Smoke und Report-Artefakte jetzt automatisiert auf Pushes und Pull Requests aus
+- **Automated test pyramid** — Vitest now covers data normalization, calculations, hook behavior, and the local server path; Playwright verifies the upload-to-dashboard smoke flow with real browser reports
+- **CI test pipeline** — GitHub Actions now runs build, coverage, Playwright smoke tests, and report artifacts automatically on pushes and pull requests
 
 ### Improved
-- **Öffentliche Repo-Bereitschaft** — Paket-Metadaten, Lizenz, Security-/Contribution-Dokumente und Publish-Surface wurden für ein späteres Public-Repo bereinigt
-- **Test-Isolation** — der Playwright-Webserver nutzt eine eigene lokale App-Umgebung und überschreibt keine normalen Nutzungsdaten
-- **Runtime-Härtung** — lokaler Server bindet standardmässig an `127.0.0.1`, liefert restriktivere Security-Header und vermeidet unnötige externe Runtime-Requests
+- **Public repo readiness** — package metadata, license, security/contribution docs, and publish surface were cleaned up for a public repository
+- **Test isolation** — the Playwright web server uses its own local app environment and does not overwrite normal user data
+- **Runtime hardening** — the local server now binds to `127.0.0.1` by default, returns stricter security headers, and avoids unnecessary external runtime requests
 
 ### Fixed
-- **Bun-/npm-Konsistenz** — Lockfiles und Publish-Inhalt sind jetzt auf denselben Dependency- und Runtime-Stand gebracht, sodass Build und Installation reproduzierbar bleiben
+- **Bun/npm consistency** — lockfiles and published runtime contents now stay aligned so builds and installs remain reproducible
 
 ## [6.0.8] - 2026-04-08
 
 ### Added
-- **CLI-Flags für `ttdash`** — `--port` / `-p`, `--help` / `-h`, `--no-open` / `-no` und `--auto-load` / `-al` werden jetzt direkt vom globalen CLI-Befehl unterstützt
-- **Persistente Lade-Metadaten** — App-Settings speichern jetzt, wann Daten zuletzt geladen wurden und über welchen Pfad (`Datei`, `Auto-Import`, `CLI Auto-Load`)
-- **Sichtbare Lade-Hinweise im UI** — Header und Limits-Dialog zeigen jetzt den letzten Ladezeitpunkt; bei `-al` erscheint zusätzlich ein eigener `Auto-Load beim Start`-Badge
+- **CLI flags for `ttdash`** — `--port` / `-p`, `--help` / `-h`, `--no-open` / `-no`, and `--auto-load` / `-al` are now supported directly by the global CLI command
+- **Persistent load metadata** — app settings now store when data was last loaded and from which path (`file`, `auto-import`, `cli-auto-load`)
+- **Visible load hints in the UI** — the header and limits dialog now show the last load time, and `-al` also adds a dedicated `Auto-load on start` badge
 
 ### Improved
-- **Gemeinsamer Auto-Import-Pfad** — UI-Auto-Import und CLI-Auto-Load verwenden jetzt dieselbe Server-Logik, damit Laufzeitverhalten, Persistenz und Fehlerbehandlung konsistent bleiben
+- **Shared auto-import path** — UI auto-import and CLI auto-load now use the same server logic so runtime behavior, persistence, and error handling stay consistent
 
 ## [6.0.7] - 2026-04-08
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our Standard
+
+Participation in this project should remain respectful, constructive, and focused on improving the software.
+
+Expected behavior includes:
+
+- being respectful in issues, pull requests, and reviews
+- giving technical feedback directly and with context
+- assuming good intent before escalating disagreement
+- keeping discussions focused on code, behavior, and user impact
+
+Unacceptable behavior includes:
+
+- harassment, intimidation, or personal attacks
+- discriminatory or derogatory language
+- repeated bad-faith arguing or disruptive behavior
+- publishing private information without permission
+
+## Scope
+
+This code of conduct applies to project spaces such as issues, pull requests, reviews, and other repository discussions.
+
+## Enforcement
+
+Project maintainers may remove comments, close discussions, reject participation, or block contributors whose behavior violates this code of conduct.
+
+## Reporting
+
+If you need to report a conduct issue, use GitHub private reporting if available or contact the maintainer through GitHub first.

CONTRIBUTING.md

@@ -1,42 +1,70 @@
 # Contributing
 
-## Development Setup
+Thanks for your interest in `TTDash`.
 
-```bash
-npm install
-npm run dev
-node server.js
-```
+This project is currently maintained by a single maintainer. Contributions are welcome, but acceptance is selective so the codebase, scope, and release quality stay manageable.
 
-Or with Bun:
+## What Is Most Helpful
 
-```bash
-bun install
-bun run dev
-node server.js
-```
+The easiest changes to review and merge are:
 
-The frontend dev server runs on `http://localhost:5173` and the local API/static server runs on `http://localhost:3000`.
+- reproducible bug reports
+- documentation fixes and clarifications
+- focused bugfix pull requests
+- small UX or accessibility improvements
+- tests that cover existing or clearly agreed behavior
 
-## Before Opening a Pull Request
+Please open an issue before spending time on larger changes such as:
 
-Run the production build and automated checks:
+- new features
+- architectural refactors
+- dependency swaps
+- changes to import, persistence, or reporting behavior
+- broad UI redesigns
+
+Large unsolicited pull requests may be declined even if they are technically correct, simply because they do not fit the current direction or available review time.
+
+## Before You Open an Issue
+
+Please include enough detail for the problem to be actionable:
+
+- what you expected
+- what actually happened
+- exact steps to reproduce
+- sample input data if the bug depends on input shape
+- screenshots or terminal output when helpful
+- environment details when relevant: OS, Node version, install method, browser
+
+For feature requests, explain the user problem first. Suggestions that only describe an implementation without clarifying the problem are harder to evaluate.
+
+## Before You Open a Pull Request
+
+Make sure the change is small, focused, and aligned with the existing product direction.
+
+Run the main local checks:
 
 ```bash
 npm run build
 npm run test:unit
+npm run verify:package
 npm run test:e2e
 ```
 
-The Playwright suite uses an isolated local app directory under `.tmp-playwright/` and should not reuse your normal local dashboard data.
+If local port `3015` is already occupied, run Playwright on another isolated port:
+
+```bash
+PLAYWRIGHT_TEST_PORT=3016 npm run test:e2e
+```
+
+The Playwright suite uses an isolated local app directory under `.tmp-playwright/` and should not reuse your normal local dashboard data. `npm run verify:package` builds the real tarball and verifies that the packaged CLI can start outside the repo checkout.
 
-Then verify the main flows manually:
+Then manually verify the main user flows touched by your change:
 
-- Dashboard load
-- Auto-import
+- dashboard load
+- auto-import
 - JSON upload
-- Filtering
-- CSV/PDF export
+- filtering
+- CSV/PDF export when relevant
 
 If you change dependencies, update both lockfiles so npm and Bun installs stay reproducible:
 
@@ -45,8 +73,49 @@ npm install
 bun install --lockfile-only
 ```
 
+## Pull Request Expectations
+
+Good pull requests are:
+
+- narrowly scoped
+- easy to review commit-by-commit
+- consistent with the existing code style
+- explicit about user-visible behavior changes
+
+Please include:
+
+- a short summary of the change
+- why the change is needed
+- how you tested it
+- screenshots or terminal output for UI/CLI changes when helpful
+
+## Development Setup
+
+```bash
+npm install
+npm run dev
+node server.js
+```
+
+Or with Bun:
+
+```bash
+bun install
+bun run dev
+node server.js
+```
+
+The frontend dev server runs on `http://localhost:5173` and the local API/static server runs on `http://localhost:3000`.
+
 ## Style
 
 - Frontend: TypeScript + React, 2-space indentation, single quotes, no semicolons in `src/`
 - Server: CommonJS, keep existing semicolon style in `server.js`
 - Keep feature UI colocated under `src/components/features/`
+- Prefer small, targeted changes over broad cleanup refactors
+
+## Related Docs
+
+- Release process: [`RELEASING.md`](RELEASING.md)
+- Security reporting: [`SECURITY.md`](SECURITY.md)
+- Conduct expectations: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)