@kntic/links 0.1.0

package/src/generator.js

@@ -0,0 +1,185 @@
+/**
+ * Static HTML page generator for KNTIC Links.
+ *
+ * Produces a single, fully self-contained index.html with all CSS inlined.
+ * No JavaScript in the output — works with JS disabled.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isLinkActive } from './utils.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** HTML-escape a string to prevent XSS. */
+function esc(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/** MIME type lookup for common image formats. */
+function imageMime(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  const map = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.avif': 'image/avif',
+  };
+  return map[ext] || 'application/octet-stream';
+}
+
+/**
+ * Read a local image file and return a base64 data URI.
+ * @param {string} filePath — path to the image (absolute or relative to configDir)
+ * @param {string} configDir — directory that links.yaml lives in
+ * @returns {string} data URI string
+ */
+export function inlineImage(filePath, configDir) {
+  const abs = resolve(configDir, filePath);
+  const buf = readFileSync(abs);
+  const mime = imageMime(abs);
+  return `data:${mime};base64,${buf.toString('base64')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Schedule filtering
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter links to only those whose schedule window includes `now`.
+ * Links without scheduling fields are always included.
+ * Delegates to isLinkActive() from utils.js for per-link evaluation.
+ */
+export function filterScheduled(links, now = new Date()) {
+  if (!links || !Array.isArray(links)) return [];
+  return links.filter((link) => isLinkActive(link, now));
+}
+
+// ---------------------------------------------------------------------------
+// Theme CSS loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Load theme CSS from the themes directory.
+ * @param {string} themeName — name without .css extension
+ * @returns {string} CSS content
+ */
+export function loadThemeCSS(themeName) {
+  const themePath = resolve(__dirname, 'themes', `${themeName}.css`);
+  try {
+    return readFileSync(themePath, 'utf8');
+  } catch {
+    throw new Error(
+      `Theme "${themeName}" not found at ${themePath}. ` +
+      'Available themes live in src/themes/.',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTML generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a complete, self-contained HTML page from a links config.
+ *
+ * @param {object} config — parsed links.yaml config object
+ * @param {object} [options]
+ * @param {string} [options.configDir=process.cwd()] — directory links.yaml lives in (for resolving relative paths)
+ * @param {Date}   [options.now=new Date()]           — current time (for schedule filtering)
+ * @returns {string} Complete HTML document
+ */
+export function generatePage(config, options = {}) {
+  const configDir = options.configDir || process.cwd();
+  const now = options.now || new Date();
+
+  const name = config.name || 'My Links';
+  const bio = config.bio || '';
+  const theme = config.theme || 'minimal-dark';
+
+  // Load and inline CSS
+  const css = loadThemeCSS(theme);
+
+  // Filter links by schedule
+  const allLinks = config.links || [];
+  const links = filterScheduled(allLinks, now);
+  const totalCount = allLinks.length;
+  const activeCount = links.length;
+  const buildDate = now.toISOString().slice(0, 10);
+
+  // Avatar handling
+  let avatarHTML = '';
+  if (config.avatar && config.avatar.trim().length > 0) {
+    try {
+      const dataUri = inlineImage(config.avatar, configDir);
+      avatarHTML = `<img class="profile__avatar" src="${dataUri}" alt="${esc(name)}" width="88" height="88">`;
+    } catch {
+      // Fallback: reference the file directly (it will be copied to output dir)
+      avatarHTML = `<img class="profile__avatar" src="${esc(config.avatar)}" alt="${esc(name)}" width="88" height="88">`;
+    }
+  }
+
+  // Build link list HTML
+  const linksHTML = links.map((link) => {
+    const icon = link.icon ? `<span class="links__icon">${esc(link.icon)}</span>` : '';
+    const description = link.description
+      ? `<span class="links__description">${esc(link.description)}</span>`
+      : '';
+
+    return `      <li class="links__item">
+        <a class="links__anchor" href="${esc(link.url)}" target="_blank" rel="noopener noreferrer">
+          <span class="links__label">${icon}${esc(link.label)}</span>${description}
+        </a>
+      </li>`;
+  }).join('\n');
+
+  // OG description falls back to bio, then a generic string
+  const ogDescription = bio || `${name} — link page`;
+
+  return `<!DOCTYPE html>
+<!-- built at ${buildDate}, ${activeCount} of ${totalCount} links active -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${esc(name)}</title>
+  <meta name="description" content="${esc(ogDescription)}">
+  <meta property="og:title" content="${esc(name)}">
+  <meta property="og:description" content="${esc(ogDescription)}">
+  <meta property="og:type" content="website">
+  <style>
+${css}
+  </style>
+</head>
+<body>
+  <section class="profile">
+    ${avatarHTML}
+    <h1 class="profile__name">${esc(name)}</h1>
+${bio ? `    <p class="profile__bio">${esc(bio)}</p>\n` : ''}  </section>
+
+  <ul class="links">
+${linksHTML}
+  </ul>
+
+  <footer class="footer">
+    <a class="footer__link" href="https://kntic.ai">Powered by KNTIC Links</a>
+  </footer>
+</body>
+</html>
+`;
+}

package/src/themes/README.md

@@ -0,0 +1,110 @@
+# KNTIC Links — Theme System
+
+Themes are **plain CSS files** that live in `src/themes/`. No build step, no
+preprocessor. Each file defines a complete visual identity for a link page by
+implementing a fixed set of **CSS custom properties** (design tokens) on `:root`
+and using them throughout.
+
+---
+
+## Quick start — creating a new theme
+
+1. Copy an existing theme (e.g. `minimal-dark.css`) to a new file:
+
+   ```bash
+   cp src/themes/minimal-dark.css src/themes/my-theme.css
+   ```
+
+2. Edit the `:root` block to change colours, fonts, radii, etc.
+
+3. Set the theme in your project's `links.yaml`:
+
+   ```yaml
+   theme: my-theme
+   ```
+
+4. Run `links deploy --self` to see the result.
+
+---
+
+## Custom property contract
+
+Every theme **must** declare all of the following custom properties inside a
+`:root { … }` rule. The generator and the base HTML structure depend on these
+tokens — omitting any of them will produce broken or inconsistent output.
+
+| Token | Purpose | Example value |
+|---|---|---|
+| `--bg-color` | Page background colour | `#0d0d0d` |
+| `--bg-secondary` | Card / surface background | `#1a1a1a` |
+| `--text-primary` | Primary text colour | `#f0f0f0` |
+| `--text-secondary` | Secondary text colour (descriptions) | `#cccccc` |
+| `--text-muted` | Muted / de-emphasised text | `#999999` |
+| `--accent-color` | Primary accent (link text, highlights) | `#e0e0e0` |
+| `--accent-hover` | Accent on hover / focus | `#ffffff` |
+| `--link-bg` | Link card background | `var(--bg-secondary)` |
+| `--link-bg-hover` | Link card background on hover | `#252525` |
+| `--link-border` | Link card border colour | `#333333` |
+| `--link-radius` | Link card border-radius | `8px` |
+| `--link-padding` | Link card inner padding | `0.875rem 1.25rem` |
+| `--font-body` | Body font stack | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif` |
+| `--font-mono` | Monospace font stack (if needed) | `'SF Mono', 'Fira Code', monospace` |
+| `--avatar-radius` | Avatar image border-radius | `50%` |
+| `--page-max-width` | Max width of the page content column | `480px` |
+| `--footer-opacity` | Footer link resting opacity | `0.6` |
+
+### Rules
+
+* **No hardcoded colours outside `:root`** — every colour value used in
+  selectors must reference one of the tokens above.
+* Themes may add *extra* custom properties for internal use but must **not**
+  remove or rename any of the standard tokens.
+* The base reset (`box-sizing`, `margin`, `padding`) should be included in
+  every theme so each theme is fully self-contained.
+
+---
+
+## Loader API (`src/themes/loader.js`)
+
+The loader is a pure ES-module with two exports:
+
+### `loadTheme(themeName)`
+
+Resolves a theme name (e.g. `"minimal-dark"`) to the corresponding `.css` file
+in the themes directory, reads it, and returns the raw CSS string.
+
+* Throws a descriptive `Error` if the theme is not found (includes list of
+  available themes).
+* Sanitises the input to prevent directory-traversal (uses `path.basename`).
+
+### `listThemes()`
+
+Returns a sorted `string[]` of available theme names (filenames without the
+`.css` extension).
+
+```js
+import { loadTheme, listThemes } from './themes/loader.js';
+
+console.log(listThemes());       // ['minimal-dark']
+const css = loadTheme('minimal-dark');
+```
+
+---
+
+## File structure
+
+```
+src/themes/
+├── loader.js          # Theme loader module
+├── minimal-dark.css   # Default theme
+├── README.md          # This file
+└── <your-theme>.css   # Add your own here
+```
+
+---
+
+## Integration with the generator
+
+The generator (`src/generator.js`) loads the theme specified in `links.yaml`
+and inlines the full CSS into a `<style>` block in the generated HTML. The
+output is a single self-contained file — no external stylesheets.

package/src/themes/developer.css

@@ -0,0 +1,210 @@
+/* developer — hacker / IDE aesthetic for KNTIC Links
+ *
+ * Monospace everywhere. Links styled as code blocks.
+ * KNTIC orange accent. Left border bar on links (VSCode-style).
+ */
+
+@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700&display=swap');
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+:root {
+  /* Backgrounds */
+  --bg-color: #1e1e1e;
+  --bg-secondary: #252526;
+
+  /* Text */
+  --text-primary: #d4d4d4;
+  --text-secondary: #9cdcfe;
+  --text-muted: #6a9955;
+
+  /* Accent — KNTIC orange */
+  --accent-color: #FF4500;
+  --accent-hover: #ff6a33;
+
+  /* Link cards */
+  --link-bg: var(--bg-secondary);
+  --link-bg-hover: #2d2d30;
+  --link-border: #3e3e42;
+  --link-radius: 3px;
+  --link-padding: 0.75rem 1rem 0.75rem 1.15rem;
+
+  /* Typography */
+  --font-body: 'JetBrains Mono', Menlo, Monaco, 'Cascadia Code', 'Courier New', monospace;
+  --font-mono: 'JetBrains Mono', Menlo, Monaco, 'Cascadia Code', 'Courier New', monospace;
+
+  /* Avatar */
+  --avatar-radius: 4px;
+
+  /* Layout */
+  --page-max-width: 540px;
+
+  /* Footer */
+  --footer-opacity: 0.45;
+}
+
+/* ── Base ────────────────────────────────────────────────────────── */
+
+html {
+  font-size: 16px;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  font-family: var(--font-body);
+  background-color: var(--bg-color);
+  color: var(--text-primary);
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 2.5rem 1rem 1rem;
+  line-height: 1.6;
+}
+
+/* ── Profile ─────────────────────────────────────────────────────── */
+
+.profile {
+  text-align: left;
+  margin-bottom: 1.5rem;
+  max-width: var(--page-max-width);
+  width: 100%;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--link-border);
+}
+
+.profile__avatar {
+  width: 64px;
+  height: 64px;
+  border-radius: var(--avatar-radius);
+  object-fit: cover;
+  margin-bottom: 0.75rem;
+  border: 1px solid var(--link-border);
+}
+
+.profile__name {
+  font-size: 1.1rem;
+  font-weight: 700;
+  margin-bottom: 0.25rem;
+  color: var(--accent-color);
+}
+
+/* File-path style decoration */
+.profile__name::before {
+  content: '~/';
+  color: var(--text-muted);
+  font-weight: 400;
+}
+
+.profile__bio {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+}
+
+.profile__bio::before {
+  content: '/* ';
+}
+
+.profile__bio::after {
+  content: ' */';
+}
+
+/* ── Links ───────────────────────────────────────────────────────── */
+
+.links {
+  list-style: none;
+  width: 100%;
+  max-width: var(--page-max-width);
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+}
+
+.links__item {
+  display: block;
+  width: 100%;
+}
+
+.links__anchor {
+  display: block;
+  width: 100%;
+  padding: var(--link-padding);
+  background-color: var(--link-bg);
+  border: 1px solid var(--link-border);
+  border-left: 3px solid var(--accent-color);
+  border-radius: var(--link-radius);
+  color: var(--text-primary);
+  text-decoration: none;
+  text-align: left;
+  font-family: var(--font-mono);
+  transition: background-color 0.15s ease, border-left-color 0.15s ease;
+}
+
+.links__anchor:hover,
+.links__anchor:focus {
+  background-color: var(--link-bg-hover);
+  color: var(--text-primary);
+  border-left-color: var(--accent-hover);
+  outline: none;
+}
+
+/* Filename-style label prefix */
+.links__anchor::before {
+  content: '$ open ';
+  color: var(--text-muted);
+  font-size: 0.8rem;
+}
+
+.links__label {
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--text-secondary);
+}
+
+.links__icon {
+  margin-right: 0.4em;
+}
+
+.links__description {
+  display: block;
+  font-size: 0.75rem;
+  color: var(--text-muted);
+  margin-top: 0.15rem;
+  padding-left: 5.2em;
+}
+
+.links__description::before {
+  content: '# ';
+}
+
+/* ── Footer ──────────────────────────────────────────────────────── */
+
+.footer {
+  margin-top: auto;
+  padding-top: 2rem;
+  padding-bottom: 1rem;
+  text-align: center;
+  max-width: var(--page-max-width);
+  width: 100%;
+  border-top: 1px solid var(--link-border);
+}
+
+.footer__link {
+  font-size: 0.65rem;
+  color: var(--text-muted);
+  text-decoration: none;
+  opacity: var(--footer-opacity);
+  font-family: var(--font-mono);
+  transition: opacity 0.2s ease;
+}
+
+.footer__link:hover {
+  opacity: 1;
+  color: var(--accent-color);
+}