Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 3 additions & 7 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,6 @@ jobs:
persist-credentials: false
- uses: kleinbem/actions/nix-setup@f1b4f5fc52ea31b1f9e53ca29170570fe4651c7d # v1.7.1
- name: Flake check
run: nix flake check
- name: Svelte check
run: |
nix develop --command npm ci
nix develop --command npm run check
- name: Build web
run: nix build .#default
run: nix flake check -L
- name: Build package
run: nix build --no-link .#default
34 changes: 17 additions & 17 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,31 @@

Guidance for AI assistants working on Foyer.

## What Foyer is
## Architecture

Foyer is the lightweight, next-generation homelab portal and service launchpad for the kleinbem fleet (`home.kleinbem.dev`).
It replaces legacy heavy dashboards (like Homepage) with a fast, modern static SvelteKit application styled with `@kleinbem/web-config` and Tailwind CSS 4.
Foyer is a pure static SvelteKit 5 SPA (`ssr = false`, `prerender = true`, `200.html` fallback) styled with Tailwind CSS 4 and `@kleinbem/web-config`.

## Key Capabilities
- **`src/lib/config.ts`**: Runtime `/config.json` parser and loader (`parsePortalConfig`, `loadPortalConfig`, URL scheme sanitization, duplicate-ID filtering). Upstream ships a neutral default in `static/config.json`; fleet deployments inject site inventory via `/config.json`.
- **`src/lib/portal.ts`**: Pure domain logic for bookmark validation/creation, multi-token `⌘K` palette search (`#host`, `@category`, `!network`, `>`), category grouping, health metrics, and Open-Meteo parsing.
- **`src/lib/data/gatus.ts`**: Optional client-side Gatus `/api/v1/endpoints/statuses` health polling and endpoint resolution.
- **`src/lib/components/`**: Svelte 5 runes UI components (`Header`, `WeatherWidget`, `HostBar`, `LayoutToggle`, `BookmarksSection`, `CategorySection`, `ServiceCard`, `CommandPalette`). Modals use native `<dialog>` (`showModal()`).
- **`test/`**: Hermetic Node `node:test` + Svelte 5 SSR test suite (`test/setup.ts` compiles `.svelte` and `.svelte.js`/`.svelte.ts` on the fly with zero extra npm dependencies).
- **`nix/package.nix`**: `nixpkgs`-compliant `buildNpmPackage` derivation (`fetchNpmDeps`, `strictDeps = true`, `__structuredAttrs = true`, `checkPhase`, `installCheckPhase`, and offline Caddy `passthru.tests.smoke`).

- **Fleet Design System**: Uses `@kleinbem/web-config` themes (dark/light, system preference, zero-FOUC).
- **Service catalogue**: hand-maintained `FLEET_SERVICES` in `src/lib/data/services.ts` and `FLEET_HOSTS` in `src/lib/data/hosts.ts` (not generated from `inventory.nix`).
- **Network Reachability Indicators**: Highlights Public (Cloudflare Tunnel), Mesh-Only (NetBird), and LAN endpoints.
- **Gatus Live Health**: Queries live service statuses from `status.kleinbem.dev`.
- **Command Palette (`⌘K`)**: Instant fuzzy search across services, hosts, and tools.
- **Zero Runtime Overhead**: Packaged via Nix (`buildNpmPackage`) as a pure static SPA served directly by Caddy.

## Development
## Development & Verification

```bash
just dev # Run Vite dev server
just check # Run svelte-check and TypeScript checks
just build # Build static production assets
just preview # Preview production build
just dev # Run Vite dev server
just test # Run unit and SSR component tests
just check # Run svelte-check and TypeScript checks (--fail-on-warnings)
just build # Build static production assets
nix flake check # Run sandboxed package build, checks, installCheck, and Caddy smoke test
```

When editing `.svelte` files, verify with `npx --offline @sveltejs/mcp svelte-autofixer <file>`.

## TypeScript

`typescript` is aliased to `@typescript/typescript6` and TypeScript 7 sits beside it as
`@typescript/native`: svelte-check and the Svelte tooling need the TS 6 JavaScript API, which the
`@typescript/native`: `svelte-check` and the Svelte tooling need the TS 6 JavaScript API, which the
native TS 7 compiler does not ship. Same setup in every fleet Svelte repo.
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Martin Kleinberger

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
91 changes: 73 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,87 @@
# Foyer 🏠
# Foyer

> *The elegant, lightweight homelab portal and service launchpad for the kleinbem fleet.*
Lightweight static homelab portal and service launchpad built with SvelteKit 5, Tailwind CSS 4, and [`@kleinbem/web-config`](https://github.com/kleinbem/web-config).

Foyer serves as the front door to [`home.kleinbem.dev`](https://home.kleinbem.dev). Built with modern SvelteKit and Tailwind CSS 4 using the shared [`@kleinbem/web-config`](https://github.com/kleinbem/web-config) design system, Foyer delivers instantaneous page loads with zero runtime overhead on host infrastructure.
Foyer compiles to a pure static SPA (`index.html`, `200.html`, `_app/`) with zero backend process or database, and loads its service and host catalogue at runtime from `/config.json`.

## ✨ Features
## Features

- **Fleet Design System**: Fully synchronized theme tokens, typography, and dark/light modes powered by `@kleinbem/web-config`.
- **Zero Runtime Overhead**: Packaged via Nix as a pure static SPA served directly by Caddy; no persistent Node.js or container runtime required on `core-pi`.
- **Network Reachability Awareness**: Clear visual badges for **Public** (Cloudflare Tunnel), **Mesh-Only** (NetBird), and **LAN-Only** services.
- **Real-Time Health & Uptime**: Direct live status integration with the fleet's [Gatus](https://status.kleinbem.dev) instance.
- **Command Palette (`⌘K` / `/`)**: Fast keyboard-driven fuzzy search across all services, host nodes, and quick links.
- **Host Node Filtering**: Filter services dynamically by node (`core-pi`, `nixos-nvme`, `mac-mini`, `nasbook`, `orin-nano`, `bpi-r4`).
- **Live Weather & Telemetry**: Built-in weather widget (Open-Meteo) and system clocks.
- **Runtime `/config.json` Catalogue**: Deploy one immutable static build anywhere and mount or serve `/config.json` per environment with strict runtime schema and URL validation.
- **Command Palette (`⌘K` / `/`)**: Multi-token keyboard search across services, pinned bookmarks, and host nodes with `#host`, `@category`, `!network`, and `>` web-search prefixes.
- **Network Reachability Badges**: Distinct indicators for `public`, `mesh`, and `lan` endpoints plus one-click filter chips.
- **Live Gatus Health**: Optional client-side polling against a [Gatus](https://gatus.io) `/api/v1/endpoints/statuses` endpoint with visibility-aware refresh and stale-data indication.
- **Host Node Bar**: Per-host service counts, one-click host filtering, and IP clipboard copy.
- **Local Quick Bookmarks**: Browser-stored personal links (`localStorage`) in a dedicated native `<dialog>` modal, immediately searchable from `⌘K`.
- **Optional Weather & Clock**: Minute-aligned UTC/local header clock and optional [Open-Meteo](https://open-meteo.com) telemetry widget.

## 🛠️ Development
## Runtime Configuration (`/config.json`)

Serve a `/config.json` file at the web root alongside Foyer's static assets (an empty neutral config ships by default):

```json
{
"title": "Foyer",
"subtitle": "Homelab Launchpad",
"gatusUrl": "https://status.example.com",
"searchUrlTemplate": "https://duckduckgo.com/?q=%s",
"weather": {
"latitude": 51.5072,
"longitude": -0.1276,
"label": "London"
},
"categoryOrder": ["Infrastructure", "Media"],
"hosts": [
{
"id": "core-01",
"name": "core-01",
"ip": "192.0.2.10",
"role": "Edge & Ingress"
}
],
"services": [
{
"id": "grafana",
"name": "Grafana",
"description": "Metrics and dashboards",
"url": "https://grafana.example.com",
"icon": "📊",
"category": "Infrastructure",
"host": "core-01",
"network": "mesh",
"gatusEndpoint": "grafana",
"tags": ["metrics", "observability"]
}
],
"footerLinks": [
{
"label": "Status",
"url": "https://status.example.com"
}
]
}
```

## Development

```bash
just dev # Start local development server
just check # Run Svelte and TypeScript checks
just build # Build static assets (to build/)
just preview # Preview production build
just dev # Start Vite development server
just test # Run Node + Svelte SSR unit & component tests
just check # Run svelte-check and TypeScript checks (--fail-on-warnings)
just build # Build production static assets to build/
just preview # Preview production build locally
```

## 📦 Deployment & Nix
## Nix & Deployment

Packaged using `pkgs.buildNpmPackage` with reproducible npm locks:
Foyer builds reproducibly in the Nix sandbox via `buildNpmPackage` (`nix/package.nix`):

```bash
nix build .#default
nix flake check
```

Serve the resulting store path with any static file server (such as Caddy or nginx) configured with `try_files {path} /200.html` and mount your site-specific `/config.json` over the web root.

## License

[MIT](./LICENSE)
34 changes: 0 additions & 34 deletions flake.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

76 changes: 43 additions & 33 deletions flake.nix
Original file line number Diff line number Diff line change
@@ -1,48 +1,58 @@
{
description = "Lightweight homelab portal and service launchpad for the kleinbem fleet";
description = "Lightweight static homelab portal and service launchpad";

inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
};

outputs =
{ self, nixpkgs }:
let
inherit (nixpkgs) lib;
systems = [
"x86_64-linux"
"aarch64-linux"
"x86_64-darwin"
"aarch64-darwin"
];
forAllSystems = f: lib.genAttrs systems (system: f nixpkgs.legacyPackages.${system});
in
{
nixpkgs,
flake-utils,
...
}:
flake-utils.lib.eachDefaultSystem (
system:
let
pkgs = nixpkgs.legacyPackages.${system};
in
{
formatter = pkgs.nixfmt;
overlays.default = final: _: {
foyer = final.callPackage ./nix/package.nix { };
};

packages.default = pkgs.buildNpmPackage {
pname = "foyer";
version = "0.1.0";
src = ./.;
npmDeps = pkgs.importNpmLock { npmRoot = ./.; };
npmConfigHook = pkgs.importNpmLock.npmConfigHook;
installPhase = ''
mkdir -p $out
cp -r build/* $out/
'';
meta = with pkgs.lib; {
description = "Lightweight homelab portal and service launchpad";
homepage = "https://github.com/kleinbem-dev/foyer";
license = licenses.mit;
};
};
formatter = forAllSystems (pkgs: pkgs.nixfmt);

packages = forAllSystems (
pkgs:
let
foyer = pkgs.callPackage ./nix/package.nix { };
in
{
inherit foyer;
default = foyer;
}
);

checks = forAllSystems (
pkgs:
let
inherit (self.packages.${pkgs.stdenv.hostPlatform.system}) foyer;
in
{
default = foyer;
smoke = foyer.tests.smoke;
}
);

devShells.default = pkgs.mkShell {
devShells = forAllSystems (pkgs: {
default = pkgs.mkShell {
packages = with pkgs; [
nodejs_22
nodejs
just
];
};
}
);
});
};
}
4 changes: 4 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ build:
check:
npm run check

# Run automated unit and component tests
test:
npm test

# Preview production build locally
preview:
npm run preview
Loading
Loading