docs(kutt): implementation plan for Kutt URL shortener as a Void app
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
root
587
docs/superpowers/plans/2026-06-08-kutt-url-shortener.md
Normal file
587
docs/superpowers/plans/2026-06-08-kutt-url-shortener.md
Normal file
@@ -0,0 +1,587 @@
|
||||
# Kutt URL Shortener as a Void App — Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Self-host stock Kutt (bare-metal LXC, Postgres on void-db, blackflame via custom CSS) behind `link.hynesy.com` (private via CF Access), surfaced in the Void as a Hybrid Apps item (embedded themed Kutt + a native update-tracker/quick-add card).
|
||||
|
||||
**Architecture:** Kutt runs unmodified in CT 113; the Void embeds its themed UI and adds a native card backed by a `/api/links` server proxy that holds the Kutt API key. Theming + deploy live in `Hynes/URLShortener-void-kutt`; the Void integration lives in `Hynes/Void-Homelab` (void-v2).
|
||||
|
||||
**Tech Stack:** Kutt (Node/knex/Postgres), systemd, Traefik + Cloudflare Access, void-v2 (Express + vanilla-ESM SPA, vitest/supertest/jsdom).
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-06-08-kutt-url-shortener-design.md`
|
||||
**Branch:** `feat/kutt-url-shortener` (spec already committed there).
|
||||
**Conventions to mirror (void-v2):** embed view = `public/views/timelapse.js` + `public/views/embed.js`; route = `lib/api/routes/health.js` (`Router`, `asyncWrap`, `requireOwner`, `validate`); api mount in `lib/api/index.js`; supertest = `tests/server.test.js`; frontend test = `tests/frontend/embed.test.js`.
|
||||
|
||||
---
|
||||
|
||||
## Phase A — Kutt service (infra + theme repo)
|
||||
|
||||
### Task 1: Create the `kutt` database + role on void-db
|
||||
|
||||
**Files:** none (live DB on CT 310).
|
||||
|
||||
- [ ] **Step 1: Create role + database (least-priv, NOSUPERUSER)**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.215 "su - postgres -c \"psql -v ON_ERROR_STOP=1 <<'SQL'
|
||||
CREATE ROLE kutt LOGIN PASSWORD 'CHANGE_ME_STRONG' NOSUPERUSER NOCREATEDB NOCREATEROLE;
|
||||
CREATE DATABASE kutt OWNER kutt;
|
||||
SQL\""
|
||||
```
|
||||
(Replace `CHANGE_ME_STRONG` with a generated secret; reuse it in Task 2's `.env`.)
|
||||
|
||||
- [ ] **Step 2: Verify**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.215 "su - postgres -c \"psql -tAc \\\"SELECT datname FROM pg_database WHERE datname='kutt'\\\"\""
|
||||
```
|
||||
Expected: prints `kutt`.
|
||||
|
||||
- [ ] **Step 3: Allow LAN access from CT 113** — confirm void-db's `pg_hba.conf` / `listen_addresses` already accept the LAN subnet (the `void` app on CT 311 connects, so it does). Note the host/port for the DSN: `192.168.1.215:5432`.
|
||||
|
||||
(No commit — record the password in the homelab secrets store, not git.)
|
||||
|
||||
### Task 2: Create CT 113 + install/run Kutt (bare-metal, Postgres)
|
||||
|
||||
**Files:** none in-repo yet (the repeatable scripts are committed in Task 9).
|
||||
|
||||
- [ ] **Step 1: Create the LXC on Z**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.124 "pct create 113 <debian-12-template> \
|
||||
--hostname kutt --cores 2 --memory 2048 --rootfs localzfs:8 \
|
||||
--net0 name=eth0,bridge=vmbr0,gw=192.168.1.1,ip=192.168.1.226/24,hwaddr=<gen-mac> \
|
||||
--onboot 1 --features nesting=1 --unprivileged 1 && pct start 113"
|
||||
```
|
||||
Pick the current Debian template (`pveam available | grep debian-12`); if `.226` is taken, use the next free infra IP. Add the MAC→`.226` reservation in the router. HA-tag via `ha-manager add ct:113 --state started` (matches the other guests).
|
||||
|
||||
- [ ] **Step 2: Install Node 20 + clone Kutt at a pinned tag**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.226 "
|
||||
apt-get update -qq && apt-get install -y curl git build-essential
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y nodejs
|
||||
useradd -r -m -d /opt/kutt -s /bin/bash kutt
|
||||
sudo -u kutt git clone --depth 1 --branch v3.2.5 https://github.com/thedevs-network/kutt /opt/kutt
|
||||
cd /opt/kutt && sudo -u kutt npm ci
|
||||
"
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Write `/opt/kutt/.env`** (mode 600, owned by `kutt`)
|
||||
|
||||
```ini
|
||||
PORT=3000
|
||||
SITE_NAME=Hynesy Links
|
||||
DEFAULT_DOMAIN=link.hynesy.com
|
||||
JWT_SECRET=<generated-32+char-secret>
|
||||
TRUST_PROXY=true
|
||||
DB_CLIENT=pg
|
||||
DB_HOST=192.168.1.215
|
||||
DB_PORT=5432
|
||||
DB_NAME=kutt
|
||||
DB_USER=kutt
|
||||
DB_PASSWORD=<the password from Task 1>
|
||||
DB_SSL=false
|
||||
REDIS_ENABLED=false
|
||||
DISALLOW_REGISTRATION=true
|
||||
DISALLOW_ANONYMOUS_LINKS=true
|
||||
MAIL_ENABLED=false
|
||||
ENABLE_RATE_LIMIT=true
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Migrate + create the admin (temporarily allow registration)**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.226 "cd /opt/kutt && sudo -u kutt env \$(grep -v '^#' .env | xargs) npm run migrate"
|
||||
# Temporarily set DISALLOW_REGISTRATION=false, start, register your admin in the browser/API, then set it back to true.
|
||||
```
|
||||
Confirm against Kutt's README "first user / admin" flow during this step (Kutt makes the first registered user the admin). After creating the admin, set `DISALLOW_REGISTRATION=true`.
|
||||
|
||||
- [ ] **Step 5: systemd unit `kutt.service`**
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Kutt URL shortener
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=kutt
|
||||
WorkingDirectory=/opt/kutt
|
||||
EnvironmentFile=/opt/kutt/.env
|
||||
ExecStart=/usr/bin/npm start
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
`systemctl daemon-reload && systemctl enable --now kutt`.
|
||||
|
||||
- [ ] **Step 6: Generate a Kutt API key** — log into the admin account → Settings → API → generate a key. Record it for Task 8 (`KUTT_API_KEY`).
|
||||
|
||||
- [ ] **Step 7: Verify Kutt runs + resolves on the LAN**
|
||||
|
||||
```bash
|
||||
curl -fsS -m6 -o /dev/null -w "kutt root: %{http_code}\n" http://192.168.1.226:3000/
|
||||
# create a test link via the API and resolve it:
|
||||
curl -s -X POST http://192.168.1.226:3000/api/v2/links -H "X-API-KEY: <key>" -H "Content-Type: application/json" -d '{"target":"https://example.com"}'
|
||||
curl -sI http://192.168.1.226:3000/<returned-slug> | grep -iE '^HTTP|^location'
|
||||
```
|
||||
Expected: root `200`; the slug returns a `302` to `https://example.com`.
|
||||
|
||||
### Task 3: Blackflame theme (custom CSS, no fork)
|
||||
|
||||
**Files:** Create `theme/css/blackflame.css` in `Hynes/URLShortener-void-kutt` (committed in Task 9); deployed into `/opt/kutt/custom/css/`.
|
||||
|
||||
- [ ] **Step 1: Write the blackflame CSS** — override Kutt's palette/typography to the Void tokens:
|
||||
|
||||
```css
|
||||
/* blackflame.css — Void theme for stock Kutt (drop-in; no source changes) */
|
||||
:root{
|
||||
--bg:#0a0a0e; --panel:#14141c; --border:#2a2a36; --text:#e8e6ed; --muted:#888094;
|
||||
--accent:#ff4f2e; --accent-dim:#7a2716;
|
||||
}
|
||||
@import url('https://fonts.googleapis.com/css2?family=Cinzel:wght@500;600&family=Cormorant+Garamond:wght@400;600&family=JetBrains+Mono:wght@400;500&display=swap');
|
||||
body{background:var(--bg);color:var(--text);font-family:'Cormorant Garamond',Georgia,serif}
|
||||
a,.link{color:var(--accent)}
|
||||
button,.button,[type=submit]{background:var(--accent-dim);border:1px solid var(--accent);color:var(--text);border-radius:3px}
|
||||
button:hover,.button:hover{background:var(--accent);color:var(--bg)}
|
||||
input,select,textarea{background:#1c1c26;border:1px solid var(--border);color:var(--text);border-radius:3px}
|
||||
h1,h2,h3{font-family:'Cinzel',serif;letter-spacing:.04em}
|
||||
code,.mono{font-family:'JetBrains Mono',monospace}
|
||||
/* refine specific Kutt classes during the deploy task by inspecting the rendered DOM */
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Deploy + verify it's served**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.1.226 "mkdir -p /opt/kutt/custom/css && chown -R kutt: /opt/kutt/custom"
|
||||
rsync theme/css/blackflame.css root@192.168.1.226:/opt/kutt/custom/css/
|
||||
ssh root@192.168.1.226 "systemctl restart kutt"
|
||||
curl -fsS -m6 http://192.168.1.226:3000/ | grep -o 'custom/css/blackflame.css' | head -1
|
||||
```
|
||||
Expected: the page references `custom/css/blackflame.css` (Kutt auto-includes files under `custom/css/` per its README). Eyeball via webapp-testing and tighten selectors as needed.
|
||||
|
||||
### Task 4: Domain + CF Access (private Phase 1)
|
||||
|
||||
**Files:** Traefik dynamic config on mediastack (mirror existing routers); CF Access via API.
|
||||
|
||||
- [ ] **Step 1: Traefik router `link.hynesy.com` → CT 113:3000**
|
||||
|
||||
On mediastack (`192.168.1.230`), in `/docker/proxy/dynamic.yml` (mirror the `aiusage` block added earlier): add a `link` router (`Host(\`link.hynesy.com\`)`, `websecure`, `certResolver: cloudflare`) + service → `http://192.168.1.226:3000`. Back up the file first. File-provider hot-reloads.
|
||||
|
||||
- [ ] **Step 2: CF Access app over the whole host (private)**
|
||||
|
||||
Clone the `aiusage` Access app (Google IdP + email allowlist) for domain `link.hynesy.com` via the CF API (creds in the `reference_cloudflare_api` memory). This gates **everything** on `link.hynesy.com` for Phase 1.
|
||||
|
||||
- [ ] **Step 3: Verify**
|
||||
|
||||
```bash
|
||||
curl -sI -m8 https://link.hynesy.com | grep -iE '^HTTP|location' # expect 302 -> cloudflareaccess (gated)
|
||||
```
|
||||
In a browser authed to CF Access: `https://link.hynesy.com` loads the blackflame Kutt; a created slug `https://link.hynesy.com/<slug>` 302s to target.
|
||||
|
||||
---
|
||||
|
||||
## Phase B — Void integration (void-v2, TDD)
|
||||
|
||||
### Task 5: Kutt API client + version-compare (pure-ish, injectable fetch)
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/links/kutt.js`
|
||||
- Test: `tests/links/kutt.test.js`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```js
|
||||
// tests/links/kutt.test.js
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { compareVersions, fetchLatestKuttRelease, createLink } from '../../lib/links/kutt.js';
|
||||
|
||||
describe('kutt helpers', () => {
|
||||
it('compareVersions flags an available update (tolerates v-prefix)', () => {
|
||||
expect(compareVersions('v3.2.5', 'v3.2.6')).toEqual({ running: 'v3.2.5', latest: 'v3.2.6', updateAvailable: true });
|
||||
expect(compareVersions('3.2.6', 'v3.2.6')).toMatchObject({ updateAvailable: false });
|
||||
});
|
||||
|
||||
it('fetchLatestKuttRelease returns tag + url from the GitHub API (injected fetch)', async () => {
|
||||
const fakeFetch = async () => ({ ok: true, json: async () => ({ tag_name: 'v3.2.6', html_url: 'https://x/releases/v3.2.6' }) });
|
||||
expect(await fetchLatestKuttRelease({ fetch: fakeFetch })).toEqual({ latest: 'v3.2.6', url: 'https://x/releases/v3.2.6' });
|
||||
});
|
||||
|
||||
it('createLink POSTs to the Kutt API with the key and returns the short link', async () => {
|
||||
let seen;
|
||||
const fakeFetch = async (url, opts) => { seen = { url, opts }; return { ok: true, json: async () => ({ link: 'https://link.hynesy.com/abc', address: 'abc' }) }; };
|
||||
const r = await createLink({ target: 'https://example.com' }, { base: 'http://10.0.0.1:3000', key: 'K', fetch: fakeFetch });
|
||||
expect(seen.url).toBe('http://10.0.0.1:3000/api/v2/links');
|
||||
expect(seen.opts.headers['X-API-KEY']).toBe('K');
|
||||
expect(r.link).toBe('https://link.hynesy.com/abc');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run it; verify it fails**
|
||||
|
||||
Run: `npm test -- tests/links/kutt.test.js`
|
||||
Expected: FAIL — module not found.
|
||||
|
||||
- [ ] **Step 3: Create `lib/links/kutt.js`**
|
||||
|
||||
```js
|
||||
// Thin client for stock Kutt's REST API + release-version compare. fetch injected
|
||||
// for tests; defaults to global fetch (Node 22). No Kutt source coupling.
|
||||
const norm = v => String(v || '').replace(/^v/, '');
|
||||
|
||||
export function compareVersions(running, latest) {
|
||||
return { running, latest, updateAvailable: norm(running) !== '' && norm(latest) !== '' && norm(running) !== norm(latest) };
|
||||
}
|
||||
|
||||
export async function fetchLatestKuttRelease({ fetch = globalThis.fetch } = {}) {
|
||||
const res = await fetch('https://api.github.com/repos/thedevs-network/kutt/releases/latest',
|
||||
{ headers: { 'Accept': 'application/vnd.github+json', 'User-Agent': 'void' } });
|
||||
if (!res.ok) throw new Error(`github ${res.status}`);
|
||||
const j = await res.json();
|
||||
return { latest: j.tag_name, url: j.html_url };
|
||||
}
|
||||
|
||||
export async function createLink(body, { base, key, fetch = globalThis.fetch }) {
|
||||
const res = await fetch(`${base}/api/v2/links`, {
|
||||
method: 'POST',
|
||||
headers: { 'X-API-KEY': key, 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(body)
|
||||
});
|
||||
if (!res.ok) throw new Error(`kutt ${res.status}`);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
export async function recentLinks({ base, key, fetch = globalThis.fetch, limit = 5 }) {
|
||||
const res = await fetch(`${base}/api/v2/links?limit=${limit}`, { headers: { 'X-API-KEY': key } });
|
||||
if (!res.ok) throw new Error(`kutt ${res.status}`);
|
||||
return res.json();
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run it; verify it passes**
|
||||
|
||||
Run: `npm test -- tests/links/kutt.test.js`
|
||||
Expected: PASS (3 passed).
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add lib/links/kutt.js tests/links/kutt.test.js
|
||||
git commit -m "feat(links): Kutt API client + release version-compare"
|
||||
```
|
||||
|
||||
### Task 6: `/api/links` proxy route
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/api/routes/links.js`
|
||||
- Modify: `lib/api/index.js` (import + `api.use('/links', linksRouter)`)
|
||||
- Test: `tests/api/links.test.js`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```js
|
||||
// tests/api/links.test.js
|
||||
import { describe, it, expect, beforeAll, vi } from 'vitest';
|
||||
import request from 'supertest';
|
||||
|
||||
vi.mock('../../lib/links/kutt.js', () => ({
|
||||
compareVersions: (r, l) => ({ running: r, latest: l, updateAvailable: r !== l }),
|
||||
fetchLatestKuttRelease: async () => ({ latest: 'v9.9.9', url: 'https://x' }),
|
||||
createLink: async (b) => ({ link: 'https://link.hynesy.com/abc', address: 'abc', target: b.target }),
|
||||
recentLinks: async () => ({ data: [] })
|
||||
}));
|
||||
|
||||
let app;
|
||||
const owner = r => r.set('Authorization', 'Bearer test-token');
|
||||
beforeAll(async () => {
|
||||
process.env.OWNER_TOKEN = 'test-token';
|
||||
process.env.KUTT_API_URL = 'http://10.0.0.1:3000';
|
||||
process.env.KUTT_API_KEY = 'K';
|
||||
process.env.KUTT_VERSION = 'v3.2.5';
|
||||
({ createApp } = await import('../../server.js'));
|
||||
app = createApp();
|
||||
});
|
||||
let createApp;
|
||||
|
||||
describe('/api/links', () => {
|
||||
it('GET /version returns running/latest/updateAvailable (owner)', async () => {
|
||||
expect((await request(app).get('/api/links/version')).status).toBe(401);
|
||||
const res = await owner(request(app).get('/api/links/version'));
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body).toMatchObject({ running: 'v3.2.5', latest: 'v9.9.9', updateAvailable: true });
|
||||
});
|
||||
|
||||
it('POST / creates a link via Kutt (owner)', async () => {
|
||||
const res = await owner(request(app).post('/api/links')).send({ target: 'https://example.com' });
|
||||
expect(res.status).toBe(201);
|
||||
expect(res.body.link).toBe('https://link.hynesy.com/abc');
|
||||
});
|
||||
|
||||
it('POST / rejects a non-URL target', async () => {
|
||||
expect((await owner(request(app).post('/api/links')).send({ target: 'not a url' })).status).toBe(400);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run it; verify it fails**
|
||||
|
||||
Run: `npm test -- tests/api/links.test.js`
|
||||
Expected: FAIL — route not mounted.
|
||||
|
||||
- [ ] **Step 3: Create `lib/api/routes/links.js`**
|
||||
|
||||
```js
|
||||
import { Router } from 'express';
|
||||
import { z } from 'zod';
|
||||
import { asyncWrap } from '../errors.js';
|
||||
import { requireOwner } from '../cap.js';
|
||||
import { validate } from '../validate.js';
|
||||
import { compareVersions, fetchLatestKuttRelease, createLink, recentLinks } from '../../links/kutt.js';
|
||||
|
||||
export const router = Router();
|
||||
const cfg = () => ({ base: process.env.KUTT_API_URL, key: process.env.KUTT_API_KEY });
|
||||
|
||||
// GET /links/version — running (pinned env) vs latest GitHub release (cached 6h).
|
||||
let cache = { at: 0, val: null };
|
||||
router.get('/version', requireOwner, asyncWrap(async (_req, res) => {
|
||||
const running = process.env.KUTT_VERSION || 'unknown';
|
||||
if (Date.now() - cache.at > 6 * 3600e3 || !cache.val) {
|
||||
try { cache = { at: Date.now(), val: await fetchLatestKuttRelease({}) }; }
|
||||
catch { return res.json({ running, latest: null, updateAvailable: false, error: 'version check unavailable' }); }
|
||||
}
|
||||
res.json({ ...compareVersions(running, cache.val.latest), url: cache.val.url });
|
||||
}));
|
||||
|
||||
const linkBody = z.object({
|
||||
target: z.string().url(),
|
||||
customurl: z.string().max(64).optional(),
|
||||
description: z.string().max(200).optional()
|
||||
});
|
||||
|
||||
// POST /links — create via Kutt (owner). Key stays server-side.
|
||||
router.post('/', requireOwner, validate({ body: linkBody }), asyncWrap(async (req, res) => {
|
||||
if (!process.env.KUTT_API_KEY) return res.status(502).json({ error: { code: 'kutt_unconfigured' } });
|
||||
res.status(201).json(await createLink(req.body, cfg()));
|
||||
}));
|
||||
|
||||
// GET /links/recent — last few links (owner).
|
||||
router.get('/recent', requireOwner, asyncWrap(async (_req, res) => {
|
||||
res.json(await recentLinks(cfg()));
|
||||
}));
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Mount in `lib/api/index.js`**
|
||||
|
||||
Add with the other imports + mounts:
|
||||
```js
|
||||
import { router as linksRouter } from './routes/links.js';
|
||||
```
|
||||
```js
|
||||
api.use('/links', linksRouter);
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Run it; verify it passes**
|
||||
|
||||
Run: `npm test -- tests/api/links.test.js`
|
||||
Expected: PASS (3 passed).
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add lib/api/routes/links.js lib/api/index.js tests/api/links.test.js
|
||||
git commit -m "feat(links): /api/links proxy (version + create + recent)"
|
||||
```
|
||||
|
||||
### Task 7: Front-end — "Links" Apps view (embed + native card)
|
||||
|
||||
**Files:**
|
||||
- Create: `public/views/links.js`
|
||||
- Modify: `public/router.js`, `public/app.js`, `public/components/sidebar.js`, `public/style.css`
|
||||
- Test: `tests/frontend/links_view.test.js`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```js
|
||||
// tests/frontend/links_view.test.js
|
||||
import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
|
||||
import { JSDOM } from 'jsdom';
|
||||
|
||||
vi.mock('../../public/api.js', () => ({ api: {
|
||||
get: vi.fn(async (p) => p.endsWith('/version')
|
||||
? { running: 'v3.2.5', latest: 'v3.2.6', updateAvailable: true, url: 'https://x' }
|
||||
: { data: [] }),
|
||||
post: vi.fn(async () => ({ link: 'https://link.hynesy.com/abc' }))
|
||||
} }));
|
||||
|
||||
let render;
|
||||
beforeAll(async () => {
|
||||
const dom = new JSDOM('<!doctype html><html><body><div id="main"></div></body></html>', { url: 'http://localhost/' });
|
||||
global.window = dom.window; global.document = dom.window.document; global.Node = dom.window.Node;
|
||||
({ render } = await import('../../public/views/links.js'));
|
||||
});
|
||||
afterAll(() => { delete global.window; delete global.document; delete global.Node; });
|
||||
|
||||
describe('links view', () => {
|
||||
it('renders the update badge + quick-add + the Kutt iframe', async () => {
|
||||
const main = document.getElementById('main');
|
||||
await render(main);
|
||||
await new Promise(r => setTimeout(r, 0));
|
||||
expect(main.querySelector('iframe.term-frame').getAttribute('src')).toBe('https://link.hynesy.com/');
|
||||
expect(main.textContent).toMatch(/update available/i);
|
||||
expect(main.querySelector('.lk-quickadd')).not.toBeNull();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run it; verify it fails**
|
||||
|
||||
Run: `npm test -- tests/frontend/links_view.test.js`
|
||||
Expected: FAIL — module not found.
|
||||
|
||||
- [ ] **Step 3: Create `public/views/links.js`**
|
||||
|
||||
```js
|
||||
// #/links — Hybrid Apps view: a Void-native card (update-tracker + quick-add) on
|
||||
// top of the embedded themed Kutt UI. Reuses the .term-bar/.term-frame embed classes.
|
||||
import { el, mount } from '../dom.js';
|
||||
import { api } from '../api.js';
|
||||
|
||||
const SRC = 'https://link.hynesy.com/';
|
||||
|
||||
export async function render(main) {
|
||||
const badge = el('span', { class: 'lk-badge muted' }, 'checking…');
|
||||
const out = el('span', { class: 'lk-out muted' }, '');
|
||||
const input = el('input', { class: 'lk-url', placeholder: 'https://long-url-to-shorten…' });
|
||||
const add = el('button', { class: 'primary' }, '◆ Shorten');
|
||||
add.onclick = async () => {
|
||||
const target = input.value.trim(); if (!target) return;
|
||||
out.textContent = 'creating…';
|
||||
try { const r = await api.post('/api/links', { target }); out.innerHTML = ''; out.appendChild(el('a', { href: r.link, target: '_blank', rel: 'noopener' }, r.link)); input.value = ''; }
|
||||
catch { out.textContent = 'failed (is Kutt reachable / API key set?)'; }
|
||||
};
|
||||
|
||||
mount(main,
|
||||
el('div', { class: 'term-bar' },
|
||||
el('span', { class: 'term-title' }, '◆ Links'),
|
||||
el('a', { class: 'ghost', style: { marginLeft: 'auto' }, href: SRC, target: '_blank', rel: 'noopener' }, '↗ Open Kutt')
|
||||
),
|
||||
el('div', { class: 'card lk-card' },
|
||||
el('div', { class: 'lk-row' }, el('span', { class: 'muted' }, 'Kutt version'), badge),
|
||||
el('div', { class: 'lk-quickadd' }, input, add),
|
||||
el('div', {}, out)
|
||||
),
|
||||
el('iframe', { id: 'embed-frame', src: SRC, class: 'term-frame' })
|
||||
);
|
||||
|
||||
try {
|
||||
const v = await api.get('/api/links/version');
|
||||
badge.classList.remove('muted');
|
||||
if (v.updateAvailable) { badge.classList.add('lk-update'); badge.innerHTML = ''; badge.appendChild(el('a', { href: v.url, target: '_blank', rel: 'noopener' }, `${v.running} → ${v.latest} · update available`)); }
|
||||
else badge.textContent = `${v.running} · up to date`;
|
||||
} catch { badge.textContent = 'version check unavailable'; }
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Wire route/dispatch/sidebar**
|
||||
|
||||
- `public/router.js` — after the `obd2` route: `{ name: 'links', re: /^\/links$/, keys: [] },`
|
||||
- `public/app.js` — in `VIEWS`, after `obd2`: `links: () => import('./views/links.js'),`
|
||||
- `public/components/sidebar.js` — in the Apps section, after the OBD2 item: `navItem('Links', '/links')`
|
||||
|
||||
- [ ] **Step 5: Add styles in `public/style.css`** (after the `.dv-mac` rule)
|
||||
|
||||
```css
|
||||
.lk-card { max-width: 760px; }
|
||||
.lk-row { display: flex; gap: 12px; align-items: center; margin-bottom: 10px; }
|
||||
.lk-update a { color: var(--accent); }
|
||||
.lk-quickadd { display: flex; gap: 8px; }
|
||||
.lk-quickadd .lk-url { flex: 1; }
|
||||
.lk-out { display: block; margin-top: 8px; font-family: var(--font-mono); font-size: 13px; }
|
||||
```
|
||||
|
||||
- [ ] **Step 6: Run it; verify it passes**
|
||||
|
||||
Run: `npm test -- tests/frontend/links_view.test.js`
|
||||
Expected: PASS. Then `node --check public/app.js` (clean).
|
||||
|
||||
- [ ] **Step 7: Commit**
|
||||
|
||||
```bash
|
||||
git add public/views/links.js public/router.js public/app.js public/components/sidebar.js public/style.css tests/frontend/links_view.test.js
|
||||
git commit -m "feat(links): Links Apps view — embed + update-tracker + quick-add"
|
||||
```
|
||||
|
||||
### Task 8: Env wiring + version bump + deploy
|
||||
|
||||
**Files:** Modify `package.json`, `server.js`, `CHANGELOG.md`; void-app `.env` (live).
|
||||
|
||||
- [ ] **Step 1: Add Kutt env to void-app** — on CT 311, append to `/opt/void-server/.env`:
|
||||
```
|
||||
KUTT_API_URL=http://192.168.1.226:3000
|
||||
KUTT_API_KEY=<the key from Task 2 Step 6>
|
||||
KUTT_VERSION=v3.2.5
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Bump version + CHANGELOG** — `package.json` + `server.js` → `2.2.0`; prepend:
|
||||
```markdown
|
||||
## 2.2.0 — Links (Kutt) Apps item
|
||||
- **Kutt URL shortener** folded into the Apps rail (`#/links`): embedded blackflame-themed
|
||||
Kutt (link.hynesy.com) + a Void-native card with a release update-tracker and a quick-add
|
||||
that proxies Kutt's REST API server-side (`/api/links`, key held in void-app env). Kutt runs
|
||||
stock (CT 113, Postgres on void-db), private via CF Access.
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Full suite + deploy**
|
||||
|
||||
```bash
|
||||
npm test
|
||||
ssh root@192.168.1.124 "pct snapshot 311 pre_2_2_0 --description 'before Links/Kutt'"
|
||||
./deploy/push.sh
|
||||
curl -s https://void.hynesy.com/health # via LAN: http://192.168.1.216:3000/health → version 2.2.0
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add package.json server.js CHANGELOG.md
|
||||
git commit -m "chore(release): 2.2.0 — Links (Kutt) Apps item"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase C — repo + docs
|
||||
|
||||
### Task 9: `Hynes/URLShortener-void-kutt` repo (theme + deploy)
|
||||
|
||||
**Files:** new local repo `/project/src/urlshortener-void-kutt` (or your preferred path).
|
||||
|
||||
- [ ] **Step 1: Assemble + commit**
|
||||
|
||||
Create the repo with: `theme/css/blackflame.css` (Task 3), `deploy/create-ct.sh` + `deploy/bootstrap.sh` + `deploy/kutt.service` + `deploy/.env.example` (the exact steps/files from Task 2), and a `README.md` documenting the CT 113 deploy + how to update Kutt (bump tag → `git fetch && git checkout <tag> && npm ci && npm run migrate && systemctl restart kutt` → bump `KUTT_VERSION` in void-app). Then:
|
||||
```bash
|
||||
cd /project/src/urlshortener-void-kutt && git init -b main && git add -A
|
||||
git commit -m "Kutt-on-Void: blackflame theme + bare-metal CT 113 deploy"
|
||||
git remote add origin gitea@192.168.1.223:Hynes/URLShortener-void-kutt.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### Task 10: Wiki page + push the void-v2 branch
|
||||
|
||||
- [ ] **Step 1: Create the wiki page** — `POST /api/spaces/2201a3dd-…/pages` (owner token) under **Hosts & Services** (`ab398d61-…`), slug `kutt-link-shortener-lxc-113`, title "Kutt / Link Shortener LXC (113)". Body: CT 113 as-deployed (Node, Postgres on void-db, link.hynesy.com, CF-Access-private), the blackflame-via-custom-CSS note, the Void Hybrid integration, and the update flow. Avoid contiguous `IP:port` for any non-live host.
|
||||
|
||||
- [ ] **Step 2: Push void-v2** — `git push origin feat/kutt-url-shortener`, then finish the branch (merge to `main`, tag `v2.2.0`) per `superpowers:finishing-a-development-branch`.
|
||||
|
||||
---
|
||||
|
||||
## Self-review notes
|
||||
|
||||
- **Spec coverage:** stock Kutt bare-metal LXC (T2) · Postgres on void-db (T1) · blackflame custom CSS no-fork (T3) · link.hynesy.com + CF-Access-private (T4) · `/api/links` proxy holding the key (T6) · update-tracker vs GitHub release (T5,T6,T7) · quick-add (T6,T7) · embedded themed Kutt in Apps rail (T7) · QR/geo deferred (out of scope, noted) · repos + wiki (T9,T10). All spec sections map to a task.
|
||||
- **Type/name consistency:** `compareVersions/fetchLatestKuttRelease/createLink/recentLinks` defined in T5 are consumed identically in T6; `KUTT_API_URL/KUTT_API_KEY/KUTT_VERSION` env names match across T6/T8; `/api/links/version|/|recent` paths match between route (T6) and view (T7); embed uses the existing `.term-bar/.term-frame` classes.
|
||||
- **Out of scope (not planned, per spec):** Phase-2 public access + per-link second domain; geo/tags upstream MRs; Redis; SMTP/registration.
|
||||
- **Infra discovery flagged inline:** exact Debian template + free IP/MAC (T2), Kutt admin-creation flow (T2 S4), and CSS selector refinement (T3) are confirmed against the live system/Kutt docs during those tasks.
|
||||
```
|
||||
Reference in New Issue
Block a user