@kntic/links 0.1.0

package/src/commands/list.js

@@ -0,0 +1,108 @@
+/**
+ * links list — List all configured links.
+ *
+ * Reads the nearest links.yaml and prints a formatted table of links.
+ * Supports --json for machine-readable output.
+ */
+
+import chalk from 'chalk';
+import { findConfig, readConfig } from '../config.js';
+
+/**
+ * Build a schedule status string for a link.
+ *
+ * Format:
+ *   ⏰ from 2026-04-01          (only scheduled_from)
+ *   ⏰ until 2026-12-31         (only scheduled_until)
+ *   ⏰ 2026-04-01 → 2026-12-31 (both)
+ *   ''                          (always active)
+ */
+function scheduleStatus(link) {
+  const hasFrom = !!link.scheduled_from;
+  const hasUntil = !!link.scheduled_until;
+
+  if (hasFrom && hasUntil) {
+    return `⏰ ${link.scheduled_from} → ${link.scheduled_until}`;
+  }
+  if (hasFrom) {
+    return `⏰ from ${link.scheduled_from}`;
+  }
+  if (hasUntil) {
+    return `⏰ until ${link.scheduled_until}`;
+  }
+  return '';
+}
+
+/**
+ * Pad a string to a given width.
+ */
+function pad(str, width) {
+  const len = str.length;
+  return len >= width ? str : str + ' '.repeat(width - len);
+}
+
+export function registerList(program) {
+  program
+    .command('list')
+    .description('List all links')
+    .option('--json', 'Output links as a JSON array')
+    .action(async (opts) => {
+      // Find and read config
+      let config;
+      try {
+        const configPath = findConfig();
+        config = readConfig(configPath);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const links = config.links || [];
+
+      if (links.length === 0) {
+        console.log('No links yet. Use: links add <label> <url>');
+        return;
+      }
+
+      // JSON output
+      if (opts.json) {
+        console.log(JSON.stringify(links, null, 2));
+        return;
+      }
+
+      // Calculate column widths
+      const idxWidth = String(links.length).length;
+      let labelWidth = 5; // minimum "LABEL"
+      let urlWidth = 3;   // minimum "URL"
+      let iconWidth = 0;
+
+      const hasIcons = links.some((l) => l.icon);
+
+      for (const link of links) {
+        if (link.label.length > labelWidth) labelWidth = link.label.length;
+        if (link.url.length > urlWidth) urlWidth = link.url.length;
+        if (link.icon && link.icon.length > iconWidth) iconWidth = link.icon.length;
+      }
+
+      // Print header
+      let header = `${pad('#', idxWidth)}  ${pad('LABEL', labelWidth)}  ${pad('URL', urlWidth)}`;
+      if (hasIcons) header += `  ${pad('ICON', iconWidth)}`;
+      header += '  SCHEDULE';
+      console.log(chalk.bold(header));
+      console.log(chalk.gray('─'.repeat(header.length)));
+
+      // Print rows
+      links.forEach((link, i) => {
+        const idx = pad(String(i + 1), idxWidth);
+        const label = pad(link.label, labelWidth);
+        const url = pad(link.url, urlWidth);
+        const icon = hasIcons ? `  ${pad(link.icon || '', iconWidth)}` : '';
+        const sched = scheduleStatus(link);
+
+        let line = `${chalk.gray(idx)}  ${chalk.cyan(label)}  ${url}${icon}`;
+        if (sched) line += `  ${chalk.yellow(sched)}`;
+        console.log(line);
+      });
+    });
+}

package/src/commands/open-cmd.js

@@ -0,0 +1,64 @@
+/**
+ * links open — Open the deployed page in a browser.
+ */
+
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import open from 'open';
+import { findConfig, readConfig } from '../config.js';
+
+export function registerOpen(program) {
+  program
+    .command('open')
+    .description('Open the deployed page in a browser')
+    .option('--local', 'Open the local dist/index.html instead of the live domain')
+    .action(async (options) => {
+      let configPath;
+      try {
+        configPath = findConfig();
+      } catch {
+        if (options.local) {
+          // Allow --local even without config
+          const localPath = resolve('dist', 'index.html');
+          if (!existsSync(localPath)) {
+            console.error(`Local file not found: ${localPath}`);
+            console.error('Run: links deploy --self');
+            process.exit(1);
+          }
+          await open(`file://${localPath}`);
+          return;
+        }
+        console.error('No links.yaml found. Run: links init');
+        process.exit(1);
+      }
+
+      if (options.local) {
+        const config = readConfig(configPath);
+        const outDir = resolve(configPath, '..', 'dist');
+        const localPath = resolve(outDir, 'index.html');
+
+        if (!existsSync(localPath)) {
+          console.error(`Local file not found: ${localPath}`);
+          console.error('Run: links deploy --self');
+          process.exit(1);
+        }
+
+        await open(`file://${localPath}`);
+        console.log(`Opened: file://${localPath}`);
+        return;
+      }
+
+      // Default: open domain
+      const config = readConfig(configPath);
+      const domain = config.domain?.trim();
+
+      if (!domain) {
+        console.error('No domain set. Use --local to preview, or set domain in links.yaml');
+        process.exit(1);
+      }
+
+      const url = domain.startsWith('http') ? domain : `https://${domain}`;
+      await open(url);
+      console.log(`Opened: ${url}`);
+    });
+}

package/src/commands/qr.js

@@ -0,0 +1,99 @@
+/**
+ * links qr — Generate a QR code for the link page URL.
+ *
+ * Usage:
+ *   links qr [url] [options]
+ *
+ * If url is omitted, uses config.domain from links.yaml.
+ * --out <file>   Save QR code as PNG to specified file path.
+ * --link <label> Generate QR for a specific link's URL instead of the page URL.
+ */
+
+import QRCode from 'qrcode';
+import chalk from 'chalk';
+import { findConfig, readConfig } from '../config.js';
+
+export function registerQr(program) {
+  program
+    .command('qr')
+    .description('Generate a QR code for the link page URL')
+    .argument('[url]', 'URL to encode (defaults to config.domain)')
+    .option('--out <file>', 'save QR code as PNG to specified file path')
+    .option('--link <label>', 'generate QR for a specific link by label')
+    .action(async (urlArg, options) => {
+      let url = urlArg;
+
+      // If --link is provided, look up the link's URL from config
+      if (options.link) {
+        let config;
+        try {
+          const configPath = findConfig();
+          config = readConfig(configPath);
+        } catch (err) {
+          console.error(chalk.red(err.message));
+          process.exitCode = 1;
+          return;
+        }
+
+        const links = config.links || [];
+        const match = links.find(
+          (l) => l.label.toLowerCase() === options.link.toLowerCase(),
+        );
+
+        if (!match) {
+          console.error(
+            chalk.red(`Link with label "${options.link}" not found in links.yaml.`),
+          );
+          process.exitCode = 1;
+          return;
+        }
+
+        url = match.url;
+      }
+
+      // If no URL yet, fall back to config.domain
+      if (!url) {
+        try {
+          const configPath = findConfig();
+          const config = readConfig(configPath);
+
+          if (config.domain && config.domain.trim().length > 0) {
+            url = config.domain.trim();
+            // Ensure it has a protocol
+            if (!/^https?:\/\//i.test(url)) {
+              url = `https://${url}`;
+            }
+          }
+        } catch {
+          // config not found — will fall through to error below
+        }
+      }
+
+      if (!url) {
+        console.error(
+          chalk.red(
+            'No URL specified and no domain set in links.yaml. Run: links qr <url>',
+          ),
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      try {
+        if (options.out) {
+          // Save as PNG
+          await QRCode.toFile(options.out, url);
+          console.log(chalk.green(`QR code saved to ${options.out}`));
+          console.log(`URL: ${url}`);
+        } else {
+          // Render to terminal
+          const qrString = await QRCode.toString(url, { type: 'terminal' });
+          console.log(qrString);
+          console.log(`URL: ${url}`);
+        }
+      } catch (err) {
+        console.error(chalk.red(`Failed to generate QR code: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/remove.js

@@ -0,0 +1,55 @@
+/**
+ * links remove — Remove an existing link entry.
+ *
+ * Finds a link by label (case-insensitive), removes it from the config,
+ * and writes the updated file atomically.
+ */
+
+import { findConfig, readConfig, writeConfig } from '../config.js';
+
+export function registerRemove(program) {
+  program
+    .command('remove <label>')
+    .description('Remove a link')
+    .action(async (label) => {
+      // 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;
+      }
+
+      const links = config.links || [];
+
+      // Find link by label (case-insensitive)
+      const index = links.findIndex(
+        (l) => l.label.toLowerCase() === label.toLowerCase(),
+      );
+
+      if (index === -1) {
+        console.error(`No link with label "${label}" found.`);
+        process.exitCode = 1;
+        return;
+      }
+
+      // Remove the link
+      const removed = links.splice(index, 1)[0];
+      config.links = links;
+
+      // Write back
+      try {
+        writeConfig(configPath, config);
+      } catch (err) {
+        console.error(`Error: could not write links.yaml — ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log(`✓ Removed: ${removed.label}`);
+    });
+}

package/src/commands/status.js

@@ -0,0 +1,64 @@
+/**
+ * links status — Show current project status summary.
+ */
+
+import { statSync } from 'node:fs';
+import chalk from 'chalk';
+import { findConfig, readConfig } from '../config.js';
+import { isLinkActive } from '../utils.js';
+
+export function registerStatus(program) {
+  program
+    .command('status')
+    .description('Show current project status')
+    .action(() => {
+      let configPath;
+      try {
+        configPath = findConfig();
+      } catch {
+        console.error('No links.yaml found. Run: links init');
+        process.exit(1);
+      }
+
+      const config = readConfig(configPath);
+      const links = config.links ?? [];
+
+      // Count scheduled (have scheduling fields) vs active
+      const scheduledLinks = links.filter(
+        (l) => l.scheduled_from || l.scheduled_until,
+      );
+      const activeLinks = links.filter((l) => isLinkActive(l));
+
+      // Last modified
+      let lastModified = 'unknown';
+      try {
+        const stat = statSync(configPath);
+        lastModified = stat.mtime.toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+      } catch {
+        // ignore
+      }
+
+      // Bio truncation
+      const bio = config.bio?.trim() || '';
+      const bioDisplay = bio.length > 60 ? bio.slice(0, 57) + '...' : bio || chalk.dim('not set');
+
+      // Domain
+      const domain = config.domain?.trim() || '';
+
+      // Output
+      console.log();
+      console.log(chalk.bold('  Links Project Status'));
+      console.log(chalk.dim('  ─────────────────────────────'));
+      console.log(`  ${chalk.cyan('Name:')}           ${config.name}`);
+      console.log(`  ${chalk.cyan('Bio:')}            ${bioDisplay}`);
+      console.log(`  ${chalk.cyan('Theme:')}          ${config.theme || 'minimal-dark'}`);
+      console.log(`  ${chalk.cyan('Domain:')}         ${domain || chalk.dim('not set')}`);
+      console.log(`  ${chalk.cyan('Avatar:')}         ${config.avatar ? chalk.green('set') : chalk.dim('not set')}`);
+      console.log(`  ${chalk.cyan('Total links:')}    ${links.length}`);
+      console.log(`  ${chalk.cyan('Active links:')}   ${activeLinks.length}`);
+      console.log(`  ${chalk.cyan('Scheduled:')}      ${scheduledLinks.length}`);
+      console.log(`  ${chalk.cyan('Last modified:')}  ${lastModified}`);
+      console.log(`  ${chalk.cyan('Config:')}         ${configPath}`);
+      console.log();
+    });
+}

package/src/commands/theme.js

@@ -0,0 +1,86 @@
+/**
+ * links theme — Switch and list themes.
+ *
+ * Subcommands:
+ *   links theme list        — list available themes (default)
+ *   links theme set <name>  — set the active theme in links.yaml
+ *   links theme              — alias for `links theme list`
+ */
+
+import { findConfig, readConfig, writeConfig } from '../config.js';
+import { listThemes } from '../themes/loader.js';
+
+/**
+ * Print the list of available themes, marking the active one with ✓.
+ * @param {string} activeTheme — currently configured theme name
+ */
+function printThemeList(activeTheme) {
+  const themes = listThemes();
+
+  if (themes.length === 0) {
+    console.log('No themes installed.');
+    return;
+  }
+
+  for (const name of themes) {
+    const marker = name === activeTheme ? ' ✓' : '';
+    console.log(`  ${name}${marker}`);
+  }
+}
+
+export function registerTheme(program) {
+  const themeCmd = program
+    .command('theme')
+    .description('Switch and list themes')
+    .action(() => {
+      // `links theme` with no subcommand → default to list behaviour
+      try {
+        const configPath = findConfig();
+        const config = readConfig(configPath);
+        printThemeList(config.theme || 'minimal-dark');
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  // --- links theme list ---------------------------------------------------
+  themeCmd
+    .command('list')
+    .description('List available themes')
+    .action(() => {
+      try {
+        const configPath = findConfig();
+        const config = readConfig(configPath);
+        printThemeList(config.theme || 'minimal-dark');
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  // --- links theme set <name> ---------------------------------------------
+  themeCmd
+    .command('set <name>')
+    .description('Set the active theme')
+    .action((name) => {
+      try {
+        const available = listThemes();
+
+        if (!available.includes(name)) {
+          console.error(`Unknown theme: ${name}. Run: links theme list`);
+          process.exit(1);
+        }
+
+        const configPath = findConfig();
+        const config = readConfig(configPath);
+        config.theme = name;
+        writeConfig(configPath, config);
+
+        console.log(`✓ Theme set to: ${name}. Rebuild with: links deploy --self`);
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/config.js

@@ -0,0 +1,221 @@
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import yaml from 'js-yaml';
+
+// ---------------------------------------------------------------------------
+// Schema defaults
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_CONFIG = {
+  name: 'My Links',
+  bio: '',
+  avatar: '',
+  theme: 'minimal-dark',
+  domain: '',
+  links: [],
+};
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a URL string starts with http:// or https://.
+ * @param {string} url
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateUrl(url) {
+  if (typeof url !== 'string' || url.length === 0) {
+    return { valid: false, error: 'url must be a non-empty string' };
+  }
+  if (!/^https?:\/\//i.test(url)) {
+    return { valid: false, error: `url must start with http:// or https:// — got "${url}"` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate that a string is a valid ISO 8601 date (YYYY-MM-DD or full ISO 8601).
+ * @param {string} str
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateDate(str) {
+  if (typeof str !== 'string' || str.length === 0) {
+    return { valid: false, error: 'date must be a non-empty string' };
+  }
+  if (Number.isNaN(Date.parse(str))) {
+    return { valid: false, error: `not a valid ISO 8601 date — got "${str}"` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate a full config object against the links.yaml schema.
+ * Collects all errors instead of failing on the first one.
+ * @param {object} config
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateConfig(config) {
+  const errors = [];
+
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    return { valid: false, errors: ['links.yaml: config must be a YAML mapping (object)'] };
+  }
+
+  // --- top-level required fields ---
+  if (typeof config.name !== 'string' || config.name.trim().length === 0) {
+    errors.push("links.yaml: missing required field 'name' (must be a non-empty string)");
+  }
+
+  // --- top-level optional string fields ---
+  for (const field of ['bio', 'avatar', 'domain']) {
+    if (config[field] !== undefined && config[field] !== null && typeof config[field] !== 'string') {
+      errors.push(`links.yaml: field '${field}' must be a string`);
+    }
+  }
+
+  // --- theme ---
+  if (config.theme !== undefined && config.theme !== null) {
+    if (typeof config.theme !== 'string' || config.theme.trim().length === 0) {
+      errors.push("links.yaml: field 'theme' must be a non-empty string");
+    }
+  }
+
+  // --- links array ---
+  if (config.links !== undefined && config.links !== null) {
+    if (!Array.isArray(config.links)) {
+      errors.push("links.yaml: field 'links' must be an array");
+    } else {
+      config.links.forEach((link, i) => {
+        const prefix = `links.yaml: links[${i}]`;
+
+        if (link === null || typeof link !== 'object' || Array.isArray(link)) {
+          errors.push(`${prefix} must be an object`);
+          return;
+        }
+
+        // required
+        if (typeof link.label !== 'string' || link.label.trim().length === 0) {
+          errors.push(`${prefix}: missing required field 'label' (must be a non-empty string)`);
+        }
+        if (typeof link.url !== 'string' || link.url.trim().length === 0) {
+          errors.push(`${prefix}: missing required field 'url' (must be a non-empty string)`);
+        } else {
+          const urlCheck = validateUrl(link.url);
+          if (!urlCheck.valid) {
+            errors.push(`${prefix}: ${urlCheck.error}`);
+          }
+        }
+
+        // optional strings
+        for (const field of ['icon', 'description']) {
+          if (link[field] !== undefined && link[field] !== null && typeof link[field] !== 'string') {
+            errors.push(`${prefix}: field '${field}' must be a string`);
+          }
+        }
+
+        // optional ISO date strings
+        for (const field of ['scheduled_from', 'scheduled_until']) {
+          if (link[field] !== undefined && link[field] !== null) {
+            if (typeof link[field] !== 'string') {
+              errors.push(`${prefix}: field '${field}' must be an ISO 8601 date string`);
+            } else {
+              const dateCheck = validateDate(link[field]);
+              if (!dateCheck.valid) {
+                errors.push(`${prefix}: field '${field}' — ${dateCheck.error}`);
+              }
+            }
+          }
+        }
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Config file discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk up from `startDir` (defaults to cwd) looking for links.yaml.
+ * @param {string} [startDir=process.cwd()]
+ * @returns {string} Absolute path to the nearest links.yaml.
+ * @throws {Error} If no links.yaml is found before reaching the filesystem root.
+ */
+export function findConfig(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = join(dir, 'links.yaml');
+    try {
+      readFileSync(candidate); // existence check
+      return candidate;
+    } catch {
+      // not found — go up
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(
+        'links.yaml not found. Run "links init" to create a new project.',
+      );
+    }
+    dir = parent;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read / Write
+// ---------------------------------------------------------------------------
+
+/**
+ * Read, parse, and validate a links.yaml file.
+ * @param {string} filePath — absolute or relative path to links.yaml
+ * @returns {object} Parsed and validated config object.
+ * @throws {Error} On read failure, YAML parse failure, or validation failure.
+ */
+export function readConfig(filePath) {
+  let raw;
+  try {
+    raw = readFileSync(resolve(filePath), 'utf8');
+  } catch (err) {
+    throw new Error(`links.yaml: unable to read file "${filePath}" — ${err.message}`);
+  }
+
+  let config;
+  try {
+    config = yaml.load(raw);
+  } catch (err) {
+    throw new Error(`links.yaml: YAML parse error — ${err.message}`);
+  }
+
+  const { valid, errors } = validateConfig(config);
+  if (!valid) {
+    throw new Error(errors.join('\n'));
+  }
+
+  return config;
+}
+
+/**
+ * Serialize a config object to YAML and write it atomically.
+ * Writes to a temporary file first, then renames into place.
+ * @param {string} filePath — absolute or relative path to links.yaml
+ * @param {object} config — config object to persist
+ */
+export function writeConfig(filePath, config) {
+  const dest = resolve(filePath);
+  const tmp = `${dest}.tmp`;
+
+  const content = yaml.dump(config, {
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+  });
+
+  writeFileSync(tmp, content, 'utf8');
+  renameSync(tmp, dest);
+}