termcard 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmet Erkan Paşahan
+
+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

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# termcard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Renders and runs interactive terminal business cards. You usually don't install this
+directly — start with:
+
+```bash
+npm create termcard@latest
+```
+
+## Using it in your own package
+
+```js
+#!/usr/bin/env node
+import { start } from 'termcard';
+
+await start(new URL('../card.config.json', import.meta.url));
+```
+
+## CLI
+
+```bash
+termcard preview [config]   # show the card
+termcard validate [config]  # check the config
+termcard build [config]     # web page, vCards and curl files in dist/
+```
+
+Configuration: <https://github.com/aepasahan/termcard/blob/main/docs/configuration.md>

package/bin/termcard.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { cli } from '../src/cli.js';
+
+process.exitCode = await cli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "termcard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Interactive business cards for the terminal — npx yourname",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./browser": "./src/browser.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "termcard": "bin/termcard.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "keywords": [
+    "business-card",
+    "terminal",
+    "cli",
+    "npx",
+    "vcard",
+    "card"
+  ],
+  "author": "Ahmet Erkan Paşahan <ae.pasahan@creetivelab.com> (https://aepasahan.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aepasahan/termcard.git",
+    "directory": "packages/termcard"
+  },
+  "homepage": "https://github.com/aepasahan/termcard#readme",
+  "bugs": "https://github.com/aepasahan/termcard/issues"
+}

package/src/browser.js

@@ -0,0 +1,17 @@
+/**
+ * Browser-safe entry point (no Node.js built-ins): validation, layout and
+ * HTML/plain rendering. Used by the web config builder.
+ *
+ *   import { normalizeConfig, layoutCard, toHtml } from 'termcard/browser';
+ */
+
+export { normalizeConfig, ConfigError, isEmail, urlProblem, TEXT_LIMIT, DESCRIPTION_LIMIT, ICON_SETS } from './config/schema.js';
+export { templates, DEFAULT_TEMPLATE, CARD_OPTIONS } from './config/templates.js';
+export { themes, THEME_DESCRIPTIONS, DEFAULT_THEME } from './config/themes.js';
+export { BUILT_IN_LANGUAGES, createTranslator, detectLanguage, languageFromHeader, languageName } from './i18n/index.js';
+export { layoutCard, layoutHeader } from './render/card.js';
+export { toPlain, toHtml, escapeHtml } from './render/format.js';
+export { webIconSet } from './render/icons.js';
+export { buildMenu } from './tui/actions.js';
+export { createVCard } from './vcard.js';
+export { slugify } from './text.js';

package/src/build/index.js

@@ -0,0 +1,53 @@
+/** `termcard build`: writes every output format of a card into a directory. */
+
+import { mkdirSync, writeFileSync, rmSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { layoutCard } from '../render/card.js';
+import { toAnsi, toPlain } from '../render/format.js';
+import { createVCard } from '../vcard.js';
+import { renderWebPage } from './web.js';
+import { integrations } from './integrations.js';
+
+/**
+ * @param {object} config normalized config
+ * @param {{ outDir: string, packageName?: string }} options
+ * @returns {string[]} written file names, relative to outDir
+ */
+export class UnsafeOutputError extends Error {
+  constructor(dir) {
+    super(`${dir} is not empty and was not created by termcard build; choose another --out folder`);
+    this.name = 'UnsafeOutputError';
+  }
+}
+
+// Marks a folder as termcard output, so a rebuild may safely empty it.
+const MARKER = '.termcard-build';
+
+export function buildCard(config, { outDir, packageName }) {
+  if (existsSync(outDir) && readdirSync(outDir).length) {
+    if (!existsSync(join(outDir, MARKER))) throw new UnsafeOutputError(outDir);
+    rmSync(outDir, { recursive: true });
+  }
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, MARKER), 'Generated by termcard build. This folder is replaced on every build.\n');
+  const written = [];
+  const write = (name, content) => {
+    const path = join(outDir, name);
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, content);
+    written.push(name);
+  };
+
+  const langs = config.language.available;
+  for (const lang of langs) {
+    const lines = layoutCard(config, lang);
+    write(`card.${lang}.ansi`, `\n${toAnsi(lines, config.theme, 256)}\n\n`);
+    write(`card.${lang}.txt`, `\n${toPlain(lines)}\n\n`);
+    write(`contact.${lang}.vcf`, createVCard(config, lang));
+  }
+  write('index.html', renderWebPage(config, { command: packageName ? `npx ${packageName}` : 'npx termcard' }));
+  if (packageName) {
+    for (const [name, code] of Object.entries(integrations(packageName, langs))) write(`integrations/${name}`, code);
+  }
+  return written;
+}

package/src/build/integrations.js

@@ -0,0 +1,72 @@
+/**
+ * Snippets that make `curl yourdomain.com` print the card. They fetch the
+ * prebuilt text files from the published npm package via jsDelivr, so the
+ * site always shows the latest released card without redeploying.
+ */
+
+const shared = (pkg, langs) => `const CARD_BASE = 'https://cdn.jsdelivr.net/npm/${pkg}@latest/dist';
+const LANGS = ${JSON.stringify(langs)};
+const TERMINAL = /^(curl|wget|httpie|xh|fetch|libfetch)\\b/i;
+
+function cardFile(url, headers) {
+  const ua = headers.get('user-agent') || '';
+  if (!TERMINAL.test(ua)) return null;
+  const path = url.pathname.replace(/\\/+$/, '') || '/';
+  const fromPath = LANGS.find((l) => path === '/' + l);
+  if (path !== '/' && !fromPath) return null;
+  const accepted = (headers.get('accept-language') || '').split(',').map((p) => p.trim().slice(0, 2).toLowerCase());
+  const lang = fromPath || LANGS.find((l) => url.searchParams.get('lang') === l) || accepted.find((l) => LANGS.includes(l)) || LANGS[0];
+  const plain = /^wget/i.test(ua) || url.searchParams.has('plain');
+  return CARD_BASE + '/card.' + lang + (plain ? '.txt' : '.ansi');
+}
+
+const TEXT_HEADERS = {
+  'content-type': 'text/plain; charset=utf-8',
+  'cache-control': 'public, max-age=3600',
+  vary: 'user-agent, accept-language',
+};`;
+
+export function integrations(pkg, langs) {
+  const ordered = langs.includes('en') ? ['en', ...langs.filter((l) => l !== 'en')] : langs;
+  const routes = JSON.stringify(['/', ...ordered.map((l) => `/${l}`)]);
+  return {
+    'cloudflare-worker.js': `// Cloudflare Worker: add a route for your domain (e.g. example.com/*).
+// Terminal clients get the card; everyone else gets your site unchanged.
+${shared(pkg, ordered)}
+
+export default {
+  async fetch(request) {
+    const file = cardFile(new URL(request.url), request.headers);
+    if (!file) return fetch(request);
+    const res = await fetch(file, { cf: { cacheTtl: 3600 } });
+    return res.ok ? new Response(res.body, { headers: TEXT_HEADERS }) : fetch(request);
+  },
+};
+`,
+    'nextjs-middleware.js': `// Next.js / Vercel: save as middleware.js in your project root.
+import { NextResponse } from 'next/server';
+${shared(pkg, ordered)}
+
+export const config = { matcher: ${routes} };
+
+export async function middleware(request) {
+  const file = cardFile(request.nextUrl, request.headers);
+  if (!file) return NextResponse.next();
+  const res = await fetch(file, { next: { revalidate: 3600 } });
+  return res.ok ? new NextResponse(await res.text(), { headers: TEXT_HEADERS }) : NextResponse.next();
+}
+`,
+    'netlify-edge.js': `// Netlify: save as netlify/edge-functions/terminal-card.js
+${shared(pkg, ordered)}
+
+export default async (request, context) => {
+  const file = cardFile(new URL(request.url), request.headers);
+  if (!file) return context.next();
+  const res = await fetch(file);
+  return res.ok ? new Response(res.body, { headers: TEXT_HEADERS }) : context.next();
+};
+
+export const config = { path: ${routes} };
+`,
+  };
+}

package/src/build/web.js

@@ -0,0 +1,101 @@
+/** Standalone, dependency-free web version of the card (one HTML file). */
+
+import { layoutCard } from '../render/card.js';
+import { webIconSet } from '../render/icons.js';
+import { toHtml, escapeHtml } from '../render/format.js';
+import { createTranslator, languageName } from '../i18n/index.js';
+import { localize } from '../text.js';
+
+export function renderWebPage(config, { command }) {
+  const { theme } = config;
+  const langs = config.language.available;
+  const fallback = langs.includes('en') ? 'en' : langs[0];
+  const data = Object.fromEntries(
+    langs.map((lang) => {
+      const t = createTranslator(lang, config.strings);
+      return [lang, { card: toHtml(layoutCard(config, lang, { iconSet: webIconSet(config.icons) })), save: t('action.save'), vcf: `contact.${lang}.vcf` }];
+    }),
+  );
+  const description = [config.name, localize(config.title, fallback), localize(config.tagline, fallback)].filter(Boolean).join(' — ');
+  // JSON embedded in <script> must not be able to close the tag.
+  const json = JSON.stringify(data).replace(/</g, '\\u003c');
+
+  return `<!doctype html>
+<html lang="${fallback}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; img-src 'self' data:; base-uri 'none'; form-action 'none'">
+<meta name="referrer" content="no-referrer">
+<title>${escapeHtml(config.name)}</title>
+<meta name="description" content="${escapeHtml(description)}">
+<meta property="og:title" content="${escapeHtml(config.name)}">
+<meta property="og:description" content="${escapeHtml(description)}">
+<meta name="color-scheme" content="dark">
+<style>
+:root{--bg:#0e0e0e;--window:#161616;--line:#262626;--text:${theme.text === 'default' ? '#eeeeee' : theme.text};--muted:${theme.muted};--faint:${theme.faint};--accent:${theme.accent}}
+*{box-sizing:border-box}
+html,body{margin:0;background:var(--bg);color:var(--text)}
+body{min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px 16px;
+  font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,"Liberation Mono",monospace;font-size:min(15px,calc((100vw - 72px) / 32))}
+.window{width:max-content;max-width:100%;background:var(--window);border:1px solid var(--line);border-radius:10px;overflow:hidden}
+.bar{display:flex;align-items:center;justify-content:space-between;gap:16px;padding:10px 16px;border-bottom:1px solid var(--line);color:var(--faint);font-size:.85em}
+.lang{display:flex;gap:4px}
+.lang button{all:unset;cursor:pointer;padding:2px 8px;border-radius:4px;color:var(--faint)}
+.lang button[aria-pressed="true"]{color:var(--accent)}
+.lang button:focus-visible,.btn:focus-visible,a:focus-visible{outline:1px solid var(--accent);outline-offset:2px}
+pre{margin:20px;padding:1.6em 2.4em;border:1px solid var(--line);border-radius:6px;font:inherit;line-height:1.45;white-space:pre;overflow-x:auto}
+a{color:inherit;text-decoration:none}
+a:hover span{text-decoration:underline;text-underline-offset:3px}
+.name{color:var(--text);font-weight:700}.text{color:var(--text)}.muted{color:var(--muted)}.faint{color:var(--faint)}.accent{color:var(--accent)}
+.foot{display:flex;flex-wrap:wrap;align-items:center;justify-content:space-between;gap:12px;padding:0 20px 20px}
+.cmd{display:flex;align-items:center;gap:10px}
+.cmd code::before{content:"$ ";color:var(--faint)}
+.btn{all:unset;cursor:pointer;color:var(--faint);font-size:.85em;padding:2px 8px;border:1px solid var(--line);border-radius:4px}
+.btn:hover{color:var(--accent)}
+@media (max-width:600px){body{padding:16px}pre{margin:12px;padding:1.2em 1.4em}.foot{padding:0 12px 14px}}
+</style>
+</head>
+<body>
+<main class="window">
+  <div class="bar"><span>~ ${escapeHtml(command)}</span>${
+    langs.length > 1
+      ? `<span class="lang" role="group" aria-label="Language">${langs.map((l) => `<button type="button" data-lang="${l}" title="${escapeHtml(languageName(l, config.strings))}">${l.toUpperCase()}</button>`).join('')}</span>`
+      : ''
+  }</div>
+  <pre id="card" aria-label="${escapeHtml(config.name)}">${data[fallback].card}</pre>
+  <div class="foot">
+    <span class="cmd"><code>${escapeHtml(command)}</code><button class="btn" type="button" id="copy">Copy</button></span>
+    <a class="btn" id="vcf" href="${data[fallback].vcf}" download>${escapeHtml(data[fallback].save)}</a>
+  </div>
+</main>
+<script>
+(() => {
+  const data = ${json};
+  const langs = Object.keys(data);
+  const $ = (id) => document.getElementById(id);
+  const has = (lang) => Object.prototype.hasOwnProperty.call(data, lang);
+  const set = (lang) => {
+    if (!has(lang)) lang = langs.includes('${fallback}') ? '${fallback}' : langs[0];
+    document.documentElement.lang = lang;
+    $('card').innerHTML = data[lang].card;
+    $('vcf').textContent = data[lang].save;
+    $('vcf').href = data[lang].vcf;
+    document.querySelectorAll('[data-lang]').forEach((b) => b.setAttribute('aria-pressed', String(b.dataset.lang === lang)));
+  };
+  document.querySelectorAll('[data-lang]').forEach((b) => b.addEventListener('click', () => {
+    set(b.dataset.lang);
+    const url = new URL(location.href); url.searchParams.set('lang', b.dataset.lang); history.replaceState(null, '', url);
+  }));
+  $('copy').addEventListener('click', async () => {
+    try { await navigator.clipboard.writeText($('copy').previousElementSibling.textContent); $('copy').textContent = '✓'; setTimeout(() => { $('copy').textContent = 'Copy'; }, 1500); } catch {}
+  });
+  const param = new URLSearchParams(location.search).get('lang');
+  const browser = (navigator.languages || [navigator.language]).map((l) => String(l).slice(0, 2).toLowerCase()).find(has);
+  set(param || browser);
+})();
+</script>
+</body>
+</html>
+`;
+}

package/src/cli.js

@@ -0,0 +1,79 @@
+/** `termcard` command-line tool for card authors: preview, validate, build. */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { loadConfig } from './config/load.js';
+import { ConfigError } from './config/schema.js';
+import { run } from './run.js';
+import { buildCard, UnsafeOutputError } from './build/index.js';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const DEFAULT_CONFIG = 'card.config.json';
+
+const HELP = `termcard ${VERSION} — terminal business cards
+
+Usage:
+  termcard preview [config]          Show the card (accepts the same flags as the card itself)
+  termcard validate [config]         Check a config and list any problems
+  termcard build [config] [--out d]  Write terminal, web, vCard and curl files (default: dist)
+
+Create a new card:
+  npm create termcard@latest
+
+The config defaults to ./${DEFAULT_CONFIG}.`;
+
+/** Package name of the card, read from the package.json next to the config. */
+function packageNameFor(configPath) {
+  const pkg = join(dirname(resolve(configPath)), 'package.json');
+  if (!existsSync(pkg)) return undefined;
+  try {
+    return JSON.parse(readFileSync(pkg, 'utf8')).name;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function cli(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const [command, ...rest] = argv;
+  if (!command || command === 'help' || command === '--help' || command === '-h') return io.stdout.write(`${HELP}\n`), 0;
+  if (command === '--version' || command === '-v') return io.stdout.write(`${VERSION}\n`), 0;
+
+  const positional = rest[0] && !rest[0].startsWith('-') ? rest[0] : undefined;
+  const configPath = positional ?? DEFAULT_CONFIG;
+  const flags = positional ? rest.slice(1) : rest;
+
+  try {
+    if (command === 'preview') return await run(loadConfig(configPath), { argv: flags, ...io });
+
+    if (command === 'validate') {
+      const config = loadConfig(configPath);
+      io.stdout.write(
+        `✓ ${configPath} is valid\n` +
+          `  template   ${config.template}\n` +
+          `  languages  ${config.language.available.join(', ')} (default: ${config.language.default})\n` +
+          `  fields     ${config.card.fields.join(', ') || '—'}\n` +
+          `  menu       ${config.menu.enabled ? config.menu.items.map((i) => (typeof i === 'string' ? i : 'custom')).join(', ') : 'off'}\n`,
+      );
+      return 0;
+    }
+
+    if (command === 'build') {
+      const { values } = parseArgs({ args: flags, options: { out: { type: 'string', default: 'dist' }, name: { type: 'string' } } });
+      const config = loadConfig(configPath);
+      const outDir = resolve(values.out);
+      const files = buildCard(config, { outDir, packageName: values.name ?? packageNameFor(configPath) });
+      io.stdout.write(`✓ Built ${files.length} files in ${values.out}/\n${files.map((f) => `  ${f}`).join('\n')}\n`);
+      return 0;
+    }
+  } catch (error) {
+    if (error instanceof ConfigError || error instanceof UnsafeOutputError || error.code?.startsWith('ERR_PARSE_ARGS')) {
+      io.stderr.write(`${error.message}\n`);
+      return 1;
+    }
+    throw error;
+  }
+
+  io.stderr.write(`Unknown command "${command}".\n\n${HELP}\n`);
+  return 2;
+}

package/src/config/load.js

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { normalizeConfig, ConfigError } from './schema.js';
+
+const MAX_CONFIG_BYTES = 64 * 1024;
+
+/**
+ * Reads and validates a JSON config file. Only JSON is accepted on purpose:
+ * a config can never execute code.
+ */
+export function loadConfig(file) {
+  const path = file instanceof URL ? fileURLToPath(file) : file;
+  let source;
+  try {
+    source = readFileSync(path, 'utf8');
+  } catch (error) {
+    throw new ConfigError([`cannot read ${path} (${error.code ?? error.message})`]);
+  }
+  if (Buffer.byteLength(source) > MAX_CONFIG_BYTES) throw new ConfigError([`${path} is larger than 64 KB`]);
+  let raw;
+  try {
+    raw = JSON.parse(source);
+  } catch (error) {
+    throw new ConfigError([`${path} is not valid JSON (${error.message})`]);
+  }
+  return normalizeConfig(raw);
+}