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
8 changes: 2 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,5 @@ jobs:
- 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
- name: Build package
run: nix build --no-link .#default
34 changes: 18 additions & 16 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,28 @@
# AGENTS.md

Guidance for AI assistants working on Attic UI.
Guidance for AI assistants working on `attic-ui`.

## What Attic UI is
## Architecture

Attic UI is the lightweight, next-generation web interface and store inspector for Attic, the multi-tenant Nix binary cache server powering the kleinbem fleet.
It replaces the plain text/ASCII welcome screen with a modern, high-tech SvelteKit application styled with `@kleinbem/web-config` and Tailwind CSS 4.
`attic-ui` is a pure static Single-Page Application (`ssr = false`, `prerender = true` via `@sveltejs/adapter-static`) for inspecting Attic and Nix HTTP binary caches:

## Key Capabilities
- `src/lib/attic-api.ts`: Pure protocol parser, URL/scheme sanitizer, origin-isolated token storage (`attic-tokens`), snippet generator, and optional `./config.json` loader. Keep free of Svelte runtime imports so `node --test` runs directly against `.ts` sources.
- `src/lib/clipboard.svelte.ts`: Shared Svelte 5 rune helper for clipboard copy feedback and timer cleanup.
- `src/lib/components/`: Presentational Svelte 5 components (`Header`, `CacheTelemetry`, `NarinfoInspector`, `ClientConfig`) using explicit callback props and zero `$effect` state loops.
- `src/routes/+page.svelte`: Top-level state coordinator with `AbortController` request cancellation and `CommandPalette` actions.
- `package.nix`: Upstream-ready `nixpkgs` derivation (`pkgs/by-name/at/attic-ui/package.nix`) installing static SPA files directly to `$out/`.

- **Fleet Design System**: Uses `@kleinbem/web-config` themes (dark/light, system preference, zero-FOUC).
- **Live Cache Health & Metrics**: Displays live status of Attic instances (public endpoint, NetBird mesh, or local host) via `<StatusDot />`.
- **Nix Store Inspector**: Queries and parses `.narinfo` records, visualizing store path dependencies, derivers, NAR sizes, and cryptographic signatures.
- **Client Configuration Assistant**: One-click copy for `nix.conf` (`substituters`, `trusted-public-keys`) and `attic` CLI authentication.
- **Command Palette (`⌘K` / `/`)**: Fast keyboard-driven navigation across caches, inspector, and actions.
- **Zero Runtime Overhead**: Packaged via Nix (`buildNpmPackage`) as a pure static SPA served directly by Caddy or static file hosts.
## Invariants

## Development
- **Fleet-agnostic defaults**: Never hardcode private IPs, internal hostnames, or signing keys in `src/`. Operator-specific defaults belong in runtime `./config.json`.
- **Token & URL safety**: Bearer tokens must never be sent over non-loopback `http://` or carried across origins when `endpoint` changes. All generated `href` URLs must pass `http:` / `https:` allowlisting.
- **Nix purity**: Keep `package.nix` free of IFD (`importNpmLock`) and eval-time `fetchGit`. Update `npmDepsHash` with `prefetch-npm-deps package-lock.json` whenever dependencies change.

## 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 test # Unit, security, and mock HTTP integration suite (node --test)
just check # svelte-kit sync && svelte-check (0 errors, 0 warnings)
just build # Production static bundle
nix flake check # Full sandboxed build + tests + smoke check + nixfmt/deadnix/statix
```
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.
59 changes: 47 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,57 @@
# Attic UI

Next-generation web interface and store inspector for [Attic](https://github.com/zhaofengli/attic), the multi-tenant Nix binary cache server powering the `kleinbem` fleet.
Web interface and closure inspector for [Attic](https://github.com/zhaofengli/attic) and standard Nix HTTP binary caches.

Styled with [`@kleinbem/web-config`](https://github.com/kleinbem/web-config), Svelte 5 runes, and Tailwind CSS 4.
Built as a zero-SSR static SPA with SvelteKit, Svelte 5 Runes, Tailwind CSS 4, and [`@kleinbem/web-config`](https://github.com/kleinbem/web-config).

## Features

- **Live Cache Health & Metrics**: Connects to Attic binary cache endpoints with live ping, auth status, and health indicators (`<StatusDot />`).
- **Nix Store Inspector**: Look up any Nix store path or NAR hash to view its parsed `.narinfo` details (compression, NAR size, references, derivers, and signature keys).
- **Client Configuration Helper**: 1-click copyable snippets for `nix.conf`, NixOS flake configuration (`substituters`, `trusted-public-keys`), and `attic` CLI token commands.
- **Command Palette (`⌘K` / `/`)**: Rapid navigation across inspector tools and settings.
- **Pure Static SPA**: Builds with zero runtime dependencies via Nix (`buildNpmPackage`), ready for Caddy or static hosting.
- **Live Cache Telemetry**: Queries `/nix-cache-info` with latency measurement, `StoreDir` / `Priority` / `WantMassQuery` inspection, and private-cache bearer-token authentication.
- **Closure & `.narinfo` Inspector**: Parses `.narinfo` metadata (`StorePath`, `NarHash`, `FileHash`, compression ratio, `Deriver`, `References`, cryptographic `Sig` entries, `CA`), supports interactive reference traversal with breadcrumb history, and falls back to `cache.nixos.org` for upstream paths when configured.
- **Origin-Scoped Token Safety**: Withholds bearer tokens over non-loopback plain HTTP, scopes saved tokens strictly per endpoint origin, and rejects non-HTTP(S) URL schemes.
- **Client Setup Snippets**: Generates copy-ready `NixOS` / flake configuration, `nix.conf` settings, and `attic` CLI commands.
- **Command Palette (`⌘K` / `/`)**: Keyboard-first navigation across path search, cache presets, snippet copying, and theme switching.
- **Runtime Operator Config (`./config.json`)**: Fleet-agnostic out of the box (auto-detects hosting origin or defaults to `https://cache.nixos.org` on `localhost`), with optional zero-rebuild customization via `./config.json`.

## Development
## Runtime Configuration (`config.json`)

Serve an optional `config.json` alongside the static root (`$out/`) to customize defaults without rebuilding:

```json
{
"subtitle": "Production Nix Binary Cache",
"footer": "Example Infrastructure",
"defaultEndpoint": "https://attic.example.org",
"defaultCache": "main",
"upstreamFallback": true,
"publicKeys": {
"main": "main:base64-ed25519-public-key="
},
"presets": [
{ "label": "attic.example.org", "endpoint": "https://attic.example.org", "cacheName": "main" },
{ "label": "cache.nixos.org", "endpoint": "https://cache.nixos.org", "cacheName": "" }
],
"samples": [
{ "name": "hello-2.12.3", "hash": "sd779x86bjaqxj2lzh2jsir4h0zjz6d1", "group": "Samples" }
],
"specs": {
"Chunking": "FastCDC deduplicated NARs"
}
}
```

## Development & Nix Packaging

```bash
npm install
npm run dev
npm run check
npm run build
just dev # Start Vite dev server (proxies /proxy-cache -> ATTIC_PROXY_TARGET)
just test # Run Node unit & loopback HTTP integration tests
just check # Run svelte-kit sync and svelte-check
just build # Build static SPA into build/
nix flake check # Sandboxed build, tests, typecheck, smoke test, and Nix linters
```

`package.nix` follows `NixOS/nixpkgs` RFC 0140 (`pkgs/by-name/at/attic-ui/package.nix`) and RFC 0166 (`nixfmt`) conventions with pure `fetchNpmDeps`, `strictDeps = true`, `__structuredAttrs = true`, and `allowedReferences = [ ]`.

## 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.

132 changes: 96 additions & 36 deletions flake.nix
Original file line number Diff line number Diff line change
@@ -1,48 +1,108 @@
{
description = "Next-generation web interface and store inspector for Attic Nix binary cache";
description = "Web interface and closure inspector for Attic Nix binary caches";

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 = lib.genAttrs systems;
localSrc = lib.fileset.toSource {
root = ./.;
fileset = lib.fileset.unions [
./LICENSE
./package.json
./package-lock.json
./src
./test
./tsconfig.json
./vite.config.ts
];
};
in
{
nixpkgs,
flake-utils,
...
}:
flake-utils.lib.eachDefaultSystem (
system:
let
pkgs = nixpkgs.legacyPackages.${system};
in
{
formatter = pkgs.nixfmt;
formatter = forAllSystems (system: nixpkgs.legacyPackages.${system}.nixfmt-tree);

packages.default = pkgs.buildNpmPackage {
pname = "attic-ui";
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 = "Web interface and store inspector for Attic Nix binary cache";
homepage = "https://github.com/kleinbem-dev/attic-ui";
license = licenses.mit;
packages = forAllSystems (
system:
let
pkgs = nixpkgs.legacyPackages.${system};
attic-ui = (pkgs.callPackage ./package.nix { }).overrideAttrs (prevAttrs: {
src = localSrc;
npmDeps = pkgs.fetchNpmDeps {
pname = "${prevAttrs.pname}-npm-deps";
inherit (prevAttrs) version;
src = localSrc;
hash = prevAttrs.npmDepsHash;
};
});
in
{
inherit attic-ui;
default = attic-ui;
}
);

checks = forAllSystems (
system:
let
pkgs = nixpkgs.legacyPackages.${system};
pkg = self.packages.${system}.default;
nixSrc = lib.fileset.toSource {
root = ./.;
fileset = lib.fileset.unions [
./flake.nix
./package.nix
];
};
};
in
{
default = pkg;
inherit (pkg.passthru.tests) smoke;
nix-lint =
pkgs.runCommand "attic-ui-nix-lint"
{
nativeBuildInputs = [
pkgs.nixfmt
pkgs.deadnix
pkgs.statix
];
}
''
nixfmt --check "${nixSrc}/flake.nix" "${nixSrc}/package.nix"
deadnix --fail "${nixSrc}"
statix check "${nixSrc}"
touch "$out"
'';
}
);

devShells.default = pkgs.mkShell {
packages = with pkgs; [
nodejs_22
just
];
};
}
);
devShells = forAllSystems (
system:
let
pkgs = nixpkgs.legacyPackages.${system};
in
{
default = pkgs.mkShell {
packages = with pkgs; [
nodejs
just
nixfmt
deadnix
statix
prefetch-npm-deps
];
};
}
);
};
}
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 unit and integration tests
test:
npm test

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