@kntic/links 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KNTIC
+
+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.

package/README.md

@@ -0,0 +1,149 @@
+# @kntic/links
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@kntic/links)](https://www.npmjs.com/package/@kntic/links)
+[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+A CLI for building and deploying link-in-bio pages. No accounts, no tracking, no third-party servers. You own the HTML.
+
+---
+
+## Quick Start
+
+Five commands from zero to a deployed page:
+
+```bash
+# 1. Install
+npm install -g @kntic/links
+
+# 2. Scaffold a new project
+links init my-page && cd my-page
+
+# 3. Add some links
+links add "GitHub" "https://github.com/you"
+links add "Blog"   "https://your-blog.dev"
+
+# 4. Build a self-contained HTML file
+links deploy --self
+
+# 5. Open it
+open dist/index.html
+```
+
+That's it. `dist/index.html` is a single file — inline CSS, base64 avatar, no external requests. Drop it on any static host.
+
+---
+
+## Install
+
+```bash
+npm install -g @kntic/links
+```
+
+Requires Node.js 18 or later.
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `links init [directory]` | Scaffold a new `links.yaml` project. `--force` to overwrite. |
+| `links add <label> <url>` | Add a link. `--from`/`--until` for scheduling, `--update` to replace. |
+| `links remove <label>` | Remove a link by label (case-insensitive). |
+| `links list` | List all links. `--json` for machine-readable output. |
+| `links deploy --self` | Generate a self-contained HTML page to `dist/`. `--out <dir>` to change output, `--open` to open in browser. |
+| `links theme list` | List available themes. |
+| `links theme set <name>` | Set the active theme in `links.yaml`. |
+| `links qr` | Generate a QR code for your page URL. |
+| `links config` | Open `links.yaml` in your `$EDITOR`. |
+| `links open` | Open your deployed page URL in the browser. `--local` for `dist/index.html`. |
+| `links status` | Show project config summary. |
+
+---
+
+## `links.yaml` Schema
+
+```yaml
+# Required
+name: "Your Name"
+url: "https://your-site.com"
+
+# Optional
+bio: "A short bio line."
+avatar: "avatar.png"          # Path to image — gets base64-inlined on build
+theme: "minimal-dark"          # Any theme name from src/themes/
+
+# Links
+links:
+  - label: "GitHub"
+    url: "https://github.com/you"
+  - label: "Blog"
+    url: "https://your-blog.dev"
+    scheduled_from: "2026-04-01"    # Optional: link becomes visible on this date
+    scheduled_until: "2026-12-31"   # Optional: link hidden after this date
+```
+
+### Scheduling
+
+Links support `scheduled_from` and `scheduled_until` fields (ISO 8601 date strings). The generator filters links at build time — only active links appear in the output HTML.
+
+---
+
+## Themes
+
+Five built-in themes ship with Links:
+
+| Theme | Description |
+|-------|-------------|
+| `minimal-dark` | Default. Muted violet accent on dark background. |
+| `minimal-light` | Clean off-white with indigo accent. |
+| `terminal` | Green-on-black with cursor blink and scanlines. |
+| `glass` | Glassmorphism with backdrop-filter blur and purple/blue gradient. |
+| `developer` | IDE-inspired aesthetic with KNTIC orange and left border bar. |
+
+```bash
+# List themes
+links theme list
+
+# Switch theme
+links theme set terminal
+
+# Rebuild
+links deploy --self
+```
+
+### Custom Themes
+
+Themes are plain CSS files. Copy any built-in theme and override the 17 CSS custom properties. See [`src/themes/README.md`](src/themes/README.md) for the full token contract.
+
+> 📸 **Screenshots coming soon.**
+
+---
+
+## Self-Hosted by Default
+
+`links deploy --self` generates a single HTML file with everything inlined:
+
+- CSS is embedded in a `<style>` tag
+- Avatar is base64-encoded into an `<img>` src
+- Zero external requests — no fonts CDN, no analytics, no tracking
+
+Upload `dist/index.html` anywhere: Nginx, S3, GitHub Pages, Netlify, a Raspberry Pi — it doesn't matter.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch
+3. Make your changes (themes are a great first contribution)
+4. Submit a merge request
+
+Please keep the zero-dependency-on-external-services philosophy. If it can be done with a single HTML file, it should be.
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 KNTIC

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kntic/links",
+  "version": "0.1.0",
+  "description": "CLI for building and deploying self-hosted link-in-bio pages. No accounts, no tracking — just HTML.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "links": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "linktree",
+    "link-page",
+    "link-in-bio",
+    "cli",
+    "privacy",
+    "self-hosted",
+    "developer",
+    "static-site"
+  ],
+  "homepage": "https://kntic.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.kommune7.wien/kommune7/apps/links.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.kommune7.wien/kommune7/apps/links/-/issues"
+  },
+  "scripts": {
+    "prepublishOnly": "node -e \"import('./src/config.js').then(() => console.log('prepublish check passed'))\""
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0",
+    "open": "^10.1.0",
+    "qrcode": "^1.5.4"
+  }
+}

package/src/cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+
+import { registerInit } from './commands/init.js';
+import { registerAdd } from './commands/add.js';
+import { registerRemove } from './commands/remove.js';
+import { registerList } from './commands/list.js';
+import { registerDeploy } from './commands/deploy.js';
+import { registerTheme } from './commands/theme.js';
+import { registerQr } from './commands/qr.js';
+import { registerConfig } from './commands/config-cmd.js';
+import { registerOpen } from './commands/open-cmd.js';
+import { registerStatus } from './commands/status.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('links')
+  .description('CLI tool for managing and deploying link-in-bio pages')
+  .version(version);
+
+// Register all subcommands
+registerInit(program);
+registerAdd(program);
+registerRemove(program);
+registerList(program);
+registerDeploy(program);
+registerTheme(program);
+registerQr(program);
+registerConfig(program);
+registerOpen(program);
+registerStatus(program);
+
+program.parse();

package/src/commands/add.js

@@ -0,0 +1,83 @@
+/**
+ * links add — Add a new link entry.
+ *
+ * Reads the nearest links.yaml, appends a new link, and writes it back
+ * atomically. Validates the URL and rejects duplicate labels.
+ */
+
+import { findConfig, readConfig, writeConfig, validateUrl } from '../config.js';
+
+export function registerAdd(program) {
+  program
+    .command('add <label> <url>')
+    .description('Add a new link')
+    .option('--icon <emoji>', 'Icon emoji or name for the link')
+    .option('--description <text>', 'Short description of the link')
+    .option('--from <date>', 'Scheduled start date (ISO 8601)')
+    .option('--until <date>', 'Scheduled end date (ISO 8601)')
+    .option('--update', 'Replace an existing link with the same label')
+    .action(async (label, url, opts) => {
+      // Validate URL
+      const urlCheck = validateUrl(url);
+      if (!urlCheck.valid) {
+        console.error(`Error: ${urlCheck.error}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      // Find and read config
+      let configPath;
+      let config;
+      try {
+        configPath = findConfig();
+        config = readConfig(configPath);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      // Ensure links array exists
+      if (!config.links) {
+        config.links = [];
+      }
+
+      // Check for duplicate label (case-insensitive)
+      const existingIndex = config.links.findIndex(
+        (l) => l.label.toLowerCase() === label.toLowerCase(),
+      );
+
+      if (existingIndex !== -1 && !opts.update) {
+        console.error(
+          `A link with label "${label}" already exists. Use --update to replace it.`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      // Build link object
+      const link = { label, url };
+      if (opts.icon) link.icon = opts.icon;
+      if (opts.description) link.description = opts.description;
+      if (opts.from) link.scheduled_from = opts.from;
+      if (opts.until) link.scheduled_until = opts.until;
+
+      // Add or replace
+      if (existingIndex !== -1) {
+        config.links[existingIndex] = link;
+      } else {
+        config.links.push(link);
+      }
+
+      // Write back
+      try {
+        writeConfig(configPath, config);
+      } catch (err) {
+        console.error(`Error: could not write links.yaml — ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log(`✓ Added: ${label} → ${url}`);
+    });
+}

package/src/commands/config-cmd.js

@@ -0,0 +1,49 @@
+/**
+ * links config — Open links.yaml in the user's preferred editor.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { findConfig } from '../config.js';
+
+export function registerConfig(program) {
+  program
+    .command('config')
+    .description('Open links.yaml in your default editor')
+    .action(() => {
+      let configPath;
+      try {
+        configPath = findConfig();
+      } catch {
+        console.error('No links.yaml found. Run: links init');
+        process.exit(1);
+      }
+
+      const editor =
+        process.env.EDITOR ||
+        process.env.VISUAL ||
+        'nano';
+
+      const result = spawnSync(editor, [configPath], {
+        stdio: 'inherit',
+      });
+
+      if (result.error) {
+        // If nano wasn't found, try vi as last resort
+        if (result.error.code === 'ENOENT' && editor === 'nano') {
+          const fallback = spawnSync('vi', [configPath], {
+            stdio: 'inherit',
+          });
+          if (fallback.error) {
+            console.error(`Could not open editor. Set $EDITOR and try again.`);
+            process.exit(1);
+          }
+          process.exit(fallback.status ?? 0);
+        }
+
+        console.error(`Could not open editor "${editor}": ${result.error.message}`);
+        process.exit(1);
+      }
+
+      process.exit(result.status ?? 0);
+    });
+}

package/src/commands/deploy.js

@@ -0,0 +1,97 @@
+/**
+ * links deploy --self — Build a self-contained static HTML page.
+ */
+
+import { mkdirSync, writeFileSync, copyFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, dirname, basename, join } from 'node:path';
+import chalk from 'chalk';
+import { findConfig, readConfig } from '../config.js';
+import { generatePage } from '../generator.js';
+
+export function registerDeploy(program) {
+  program
+    .command('deploy')
+    .description('Build and deploy the link page')
+    .option('--self', 'Generate a self-contained static HTML page')
+    .option('--out <dir>', 'Output directory', './dist')
+    .option('--open', 'Open the generated page in a browser after build')
+    .action(async (opts) => {
+      if (!opts.self) {
+        console.log(
+          chalk.yellow('Usage: links deploy --self [--out <dir>] [--open]'),
+        );
+        console.log('Other deploy targets are not yet implemented.');
+        process.exitCode = 1;
+        return;
+      }
+
+      // 1. Locate and read config
+      let configPath;
+      try {
+        configPath = findConfig();
+      } catch (err) {
+        console.error(chalk.red(`✗ ${err.message}`));
+        process.exitCode = 1;
+        return;
+      }
+
+      let config;
+      try {
+        config = readConfig(configPath);
+      } catch (err) {
+        console.error(chalk.red(`✗ ${err.message}`));
+        process.exitCode = 1;
+        return;
+      }
+
+      const configDir = dirname(configPath);
+
+      // 2. Generate HTML
+      let html;
+      try {
+        html = generatePage(config, { configDir });
+      } catch (err) {
+        console.error(chalk.red(`✗ Build failed: ${err.message}`));
+        process.exitCode = 1;
+        return;
+      }
+
+      // 3. Write output
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+
+      const outFile = join(outDir, 'index.html');
+      writeFileSync(outFile, html, 'utf8');
+
+      // 4. Copy avatar as fallback asset (if it's a local file)
+      if (config.avatar && config.avatar.trim().length > 0) {
+        const avatarSrc = resolve(configDir, config.avatar);
+        if (existsSync(avatarSrc)) {
+          try {
+            const avatarDest = join(outDir, basename(config.avatar));
+            copyFileSync(avatarSrc, avatarDest);
+          } catch {
+            // non-fatal — avatar is already inlined
+          }
+        }
+      }
+
+      // 5. Summary
+      const size = statSync(outFile).size;
+      const sizeStr = size < 1024
+        ? `${size} B`
+        : `${(size / 1024).toFixed(1)} KB`;
+
+      console.log(chalk.green(`✓ Built to ${outFile}`) + chalk.dim(` (${sizeStr})`));
+
+      // 6. Optionally open in browser
+      if (opts.open) {
+        try {
+          const open = (await import('open')).default;
+          await open(outFile);
+        } catch {
+          console.log(chalk.yellow('⚠ Could not open browser automatically.'));
+        }
+      }
+    });
+}

package/src/commands/init.js

@@ -0,0 +1,107 @@
+/**
+ * links init — Scaffold a new link page project.
+ *
+ * Creates a links.yaml with sensible defaults and prints a getting-started
+ * message. Safe to run — never overwrites an existing links.yaml unless
+ * --force is passed.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { userInfo } from 'node:os';
+
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+
+function buildTemplate(name) {
+  return `# links.yaml — your link-in-bio page configuration
+# Docs: links help
+
+name: "${name}"
+
+# Short bio displayed under your name
+bio: ""
+
+# Avatar image URL (uncomment and set your image URL)
+# avatar: "https://example.com/avatar.png"
+
+# Theme for the generated page
+theme: minimal-dark
+
+# Your page URL once deployed (uncomment and set your domain)
+# domain: "https://links.example.com"
+
+# Links — add as many as you like
+links:
+  - label: "My Website"
+    url: "https://example.com"
+    # icon: "globe"
+    # description: "My personal website"
+
+  - label: "Twitter"
+    url: "https://twitter.com/example"
+    # icon: "twitter"
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export function registerInit(program) {
+  program
+    .command('init [directory]')
+    .description('Initialise a new links project')
+    .option('--force', 'Overwrite existing links.yaml', false)
+    .action(async (directory, opts) => {
+      const targetDir = directory ? resolve(directory) : process.cwd();
+      const filePath = join(targetDir, 'links.yaml');
+
+      // If a directory argument was provided, ensure it exists
+      if (directory && !existsSync(targetDir)) {
+        try {
+          mkdirSync(targetDir, { recursive: true });
+        } catch (err) {
+          console.error(`Error: could not create directory "${targetDir}" — ${err.message}`);
+          process.exitCode = 1;
+          return;
+        }
+      }
+
+      // Safety check — never overwrite without --force
+      if (existsSync(filePath) && !opts.force) {
+        console.error('links.yaml already exists. Use --force to overwrite.');
+        process.exitCode = 1;
+        return;
+      }
+
+      // Resolve a sensible default name
+      let defaultName = 'My Links';
+      try {
+        const info = userInfo();
+        if (info.username) {
+          defaultName = info.username;
+        }
+      } catch {
+        // userInfo can throw on some platforms — fall back silently
+      }
+
+      const content = buildTemplate(defaultName);
+
+      try {
+        writeFileSync(filePath, content, 'utf8');
+      } catch (err) {
+        console.error(`Error: could not write links.yaml — ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      // Success message
+      const relPath = directory ? join(directory, 'links.yaml') : 'links.yaml';
+      console.log(`✔ Created ${relPath}\n`);
+      console.log('Next steps:');
+      console.log('  links add <label> <url>        Add a link');
+      console.log('  links deploy --self --out ./dist  Build your page');
+    });
+}