anyfreebook-cli 0.0.0-stage → 0.1.1

package/src/config.js

@@ -0,0 +1,113 @@
+/**
+ * Configuration, limits and validation helpers.
+ *
+ * Everything here is deliberately dependency-free and side-effect free so the
+ * same values can be reused by the CLI and by the tests.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { usageError } from './errors.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+function readVersion() {
+  try {
+    const raw = readFileSync(path.join(here, '..', 'package.json'), 'utf8');
+    return JSON.parse(raw).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export const VERSION = readVersion();
+
+export const DEFAULT_API_BASE = 'https://anyfreebook.com/api/v1';
+export const DEFAULT_TIMEOUT_MS = 20000;
+export const DEFAULT_SEARCH_LIMIT = 10;
+export const DEFAULT_DOWNLOAD_LIMIT = 5;
+export const DEFAULT_OUT_DIR = './books';
+export const MAX_LIMIT = 50;
+export const MAX_QUERY_LENGTH = 200;
+
+/** Source identifiers accepted by the `source` query parameter. */
+export const SOURCES = [
+  'all',
+  'gutenberg',
+  'openlibrary',
+  'archive',
+  'googlebooks',
+  'pubmed',
+  'doaj',
+  'librivox',
+];
+
+/** File formats the CLI knows how to download. */
+export const FORMATS = ['epub', 'pdf', 'txt', 'html'];
+
+/** Preference order used when no explicit `--format` is given. */
+export const FORMAT_PREFERENCE = ['epub', 'pdf', 'txt', 'html'];
+
+export const USER_AGENT = `anyfreebook-cli/${VERSION} (+https://anyfreebook.com)`;
+
+/**
+ * Merge CLI flags with environment variables.
+ * Flags win, then env, then the built-in defaults.
+ */
+export function resolveConfig(flags = {}, env = {}) {
+  const base = String(flags.apiBase || env.ANYFREEBOOK_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
+  const apiKey = String(flags.apiKey || env.ANYFREEBOOK_API_KEY || '').trim();
+  const timeoutMs =
+    flags.timeout !== undefined && flags.timeout !== null
+      ? Number(flags.timeout)
+      : env.ANYFREEBOOK_TIMEOUT_MS !== undefined
+        ? Number(env.ANYFREEBOOK_TIMEOUT_MS)
+        : DEFAULT_TIMEOUT_MS;
+
+  return {
+    base: base || DEFAULT_API_BASE,
+    apiKey,
+    timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS,
+  };
+}
+
+/** Parse an integer option and clamp it into [min, max]. */
+export function clampInt(value, fallback, min, max, label) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+    throw usageError(`${label} must be a whole number (got "${value}").`);
+  }
+  if (parsed < min || parsed > max) {
+    throw usageError(`${label} must be between ${min} and ${max} (got ${parsed}).`);
+  }
+  return parsed;
+}
+
+/** Validate the `--source` option. */
+export function validateSource(value) {
+  if (value === undefined || value === null || value === '') return 'all';
+  const normalized = String(value).trim().toLowerCase();
+  if (!SOURCES.includes(normalized)) {
+    throw usageError(
+      `Unknown source "${value}".`,
+      `Valid sources: ${SOURCES.join(', ')}.`,
+    );
+  }
+  return normalized;
+}
+
+/** Validate the `--format` option. */
+export function validateFormat(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const normalized = String(value).trim().toLowerCase().replace(/^\./, '');
+  if (!FORMATS.includes(normalized)) {
+    throw usageError(
+      `Unknown format "${value}".`,
+      `Valid formats: ${FORMATS.join(', ')}.`,
+    );
+  }
+  return normalized;
+}

package/src/errors.js

@@ -0,0 +1,57 @@
+/**
+ * Error types shared by the CLI.
+ *
+ * Every error that reaches the top level carries an exit code, so the process
+ * never has to guess and never has to print a stack trace.
+ */
+
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_RATE_LIMITED = 2;
+
+export class CliError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = options.exitCode ?? EXIT_ERROR;
+    this.hint = options.hint ?? '';
+    this.code = options.code ?? 'error';
+    this.status = options.status ?? null;
+    this.retryAfter = options.retryAfter ?? null;
+  }
+}
+
+/** A mistake in how the command was invoked (bad flag, missing argument...). */
+export function usageError(message, hint = '') {
+  return new CliError(message, { exitCode: EXIT_ERROR, code: 'usage', hint });
+}
+
+/** The API answered with a non-2xx status. */
+export function apiError(message, options = {}) {
+  return new CliError(message, { code: 'api', ...options });
+}
+
+/** The API could not be reached at all. */
+export function networkError(message, options = {}) {
+  return new CliError(message, { code: 'network', ...options });
+}
+
+/** Normalise anything thrown into a CliError. */
+export function toCliError(err) {
+  if (err instanceof CliError) return err;
+  if (err instanceof Error) {
+    return new CliError(err.message || 'Unexpected error.', { code: 'error' });
+  }
+  return new CliError(String(err), { code: 'error' });
+}
+
+/** JSON shape used for `--json` error output. */
+export function errorPayload(err) {
+  const payload = { error: err.message, code: err.code };
+  if (err.hint) payload.hint = err.hint;
+  if (err.status) payload.status = err.status;
+  if (err.retryAfter !== null && err.retryAfter !== undefined) {
+    payload.retryAfter = err.retryAfter;
+  }
+  return payload;
+}

package/src/filename.js

@@ -0,0 +1,75 @@
+/**
+ * Filename helpers.
+ *
+ * Downloaded books are named after their title. Titles come from a remote API,
+ * so they are treated as untrusted input: the result is always a single flat
+ * file name that stays inside the destination directory.
+ */
+
+import path from 'node:path';
+
+const WINDOWS_RESERVED = new Set([
+  'con', 'prn', 'aux', 'nul',
+  'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
+  'lpt1', 'lpt2', 'lpt3', 'lpt4', 'lpt5', 'lpt6', 'lpt7', 'lpt8', 'lpt9',
+]);
+
+/**
+ * Letters that NFKD leaves alone but that a readable slug should keep.
+ * Without this, "ø" would silently disappear from a file name.
+ */
+const TRANSLITERATIONS = {
+  ø: 'o', Ø: 'O', æ: 'ae', Æ: 'ae', œ: 'oe', Œ: 'oe',
+  ß: 'ss', đ: 'd', Đ: 'd', ł: 'l', Ł: 'l', þ: 'th', Þ: 'th',
+  ð: 'd', Ð: 'd', ħ: 'h', Ħ: 'h', ŋ: 'ng', Ŋ: 'ng',
+};
+
+/**
+ * Turn an arbitrary title into a lowercase, hyphenated, filesystem-safe slug.
+ * Never returns an empty string.
+ */
+export function slugify(input, { maxLength = 120 } = {}) {
+  const source = String(input ?? '')
+    .replace(/[øØæÆœŒßđĐłŁþÞðÐħĦŋŊ]/g, (char) => TRANSLITERATIONS[char] ?? char)
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '');
+
+  let slug = source
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+
+  if (slug.length > maxLength) {
+    slug = slug.slice(0, maxLength).replace(/-+$/, '');
+  }
+  if (!slug) slug = 'book';
+  if (WINDOWS_RESERVED.has(slug)) slug = `_${slug}`;
+  return slug;
+}
+
+/**
+ * Build the file name for a download: `<slug>.<ext>`.
+ *
+ * When the source id is known it is appended (`<slug>-pg-1342.epub`).
+ * Two different books can slugify to the same title — "Pride and Prejudice"
+ * and "Pride and Prejudice, a play" both become `pride-and-prejudice` — and
+ * without the id the second one would be skipped as a duplicate of the first.
+ */
+export function fileNameFor(title, extension, id) {
+  const ext = String(extension ?? '').replace(/^\.+/, '').replace(/[^a-z0-9]/gi, '') || 'bin';
+  const suffix = id ? `-${slugify(id, { maxLength: 24 })}` : '';
+  return `${slugify(title)}${suffix}.${ext.toLowerCase()}`;
+}
+
+/**
+ * Resolve `name` inside `dir` and guarantee the result stays inside it.
+ * Returns null when the name would escape the directory.
+ */
+export function resolveWithin(dir, name) {
+  const base = path.resolve(dir);
+  const target = path.resolve(base, name);
+  const relative = path.relative(base, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return target;
+}

package/src/format.js

@@ -0,0 +1,167 @@
+/**
+ * Terminal formatting.
+ *
+ * Colour is opt-out: NO_COLOR, a non-TTY stdout, or --no-color all disable it.
+ * No ANSI escape ever ends up in JSON output.
+ */
+
+const ANSI = {
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  red: '\u001b[31m',
+  green: '\u001b[32m',
+  yellow: '\u001b[33m',
+  blue: '\u001b[34m',
+  magenta: '\u001b[35m',
+  cyan: '\u001b[36m',
+  gray: '\u001b[90m',
+};
+
+/**
+ * Decide whether ANSI colour should be used.
+ * @param {{noColor?: boolean, env?: object, stream?: object}} options
+ */
+export function resolveColor({ noColor = false, env = {}, stream = process.stdout } = {}) {
+  if (noColor) return false;
+  const environment = env || {};
+  if (environment.NO_COLOR !== undefined && environment.NO_COLOR !== '') return false;
+  if (environment.FORCE_COLOR === '0') return false;
+  if (environment.FORCE_COLOR !== undefined && environment.FORCE_COLOR !== '') return true;
+  return Boolean(stream && stream.isTTY);
+}
+
+/** Create a tiny styling helper bound to a colour decision. */
+export function createStyler({ color = false } = {}) {
+  const wrap = (name) => (text) => (color ? `${ANSI[name]}${text}${ANSI.reset}` : String(text));
+  return {
+    color,
+    bold: wrap('bold'),
+    dim: wrap('dim'),
+    red: wrap('red'),
+    green: wrap('green'),
+    yellow: wrap('yellow'),
+    blue: wrap('blue'),
+    magenta: wrap('magenta'),
+    cyan: wrap('cyan'),
+    gray: wrap('gray'),
+  };
+}
+
+const TIER_STYLE = {
+  download: (style) => style.green('download'),
+  borrow: (style) => style.yellow('borrow'),
+  unverified: (style) => style.gray('unverified'),
+};
+
+/** Colour a tier label, falling back to the plain word for unknown tiers. */
+export function formatTier(tier, style) {
+  const key = String(tier ?? '').toLowerCase();
+  const painter = TIER_STYLE[key];
+  return painter ? painter(style) : String(tier ?? 'unknown');
+}
+
+/** Shorten text to `width` characters, using an ellipsis when it does not fit. */
+export function truncate(text, width) {
+  const value = String(text ?? '');
+  if (width <= 0) return '';
+  if (value.length <= width) return value;
+  if (width <= 1) return value.slice(0, width);
+  return `${value.slice(0, width - 1)}…`;
+}
+
+/** Human readable byte size. */
+export function humanBytes(bytes) {
+  if (bytes === null || bytes === undefined || !Number.isFinite(Number(bytes))) return 'unknown';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let value = Number(bytes);
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const rounded = unit === 0 ? Math.round(value) : Math.round(value * 10) / 10;
+  return `${rounded} ${units[unit]}`;
+}
+
+/** Formats available on a search result. */
+export function formatsOf(result) {
+  const files = Array.isArray(result?.files) ? result.files : [];
+  const formats = [];
+  for (const file of files) {
+    const format = file && file.format ? String(file.format).toLowerCase() : '';
+    if (format && !formats.includes(format)) formats.push(format);
+  }
+  return formats.length ? formats.join(', ') : '—';
+}
+
+const GUTTER = '  ';
+
+/**
+ * Render the search result table.
+ * Column widths are computed from the plain text so ANSI codes never break the
+ * alignment.
+ */
+export function renderSearchTable(results, { style, width = process.stdout.columns || 100 } = {}) {
+  const columns = [
+    { label: 'TITLE', width: 50, min: 22 },
+    { label: 'AUTHOR', width: 24, min: 10 },
+    { label: 'SOURCE', width: 20, min: 10 },
+    { label: 'TIER', width: 10, min: 9 },
+    { label: 'FORMATS', width: 22, min: 8 },
+  ];
+
+  const fixedTotal = columns.slice(1).reduce((sum, col) => sum + col.width, 0);
+  const gutterTotal = GUTTER.length * (columns.length - 1);
+  const available = Math.max(30, width - fixedTotal - gutterTotal);
+  columns[0].width = Math.max(columns[0].min, Math.min(columns[0].width, available));
+
+  const rawRows = results.map((result) => [
+    result?.title || result?.id || '(untitled)',
+    result?.author || '—',
+    result?.source || result?.sourceType || '—',
+    String(result?.tier ?? 'unknown'),
+    formatsOf(result),
+  ]);
+
+  const widths = columns.map((col, index) =>
+    rawRows.reduce((max, row) => Math.max(max, String(row[index] ?? '').length), col.label.length),
+  );
+
+  const pad = (text, width) => text + ' '.repeat(Math.max(0, width - text.length));
+
+  const header = columns.map((col, index) => style.bold(pad(col.label, widths[index]))).join(GUTTER).trimEnd();
+  const divider = columns.map((col, index) => style.dim('-'.repeat(widths[index]))).join(GUTTER).trimEnd();
+
+  const body = rawRows.map((row) =>
+    row
+      .map((cell, index) => {
+        const plain = truncate(String(cell ?? ''), widths[index]);
+        const shown = index === 3 ? formatTier(plain, style) : plain;
+        return shown + ' '.repeat(Math.max(0, widths[index] - plain.length));
+      })
+      .join(GUTTER)
+      .trimEnd(),
+  );
+
+  return [header, divider, ...body].join('\n');
+}
+
+/** One-line explanation of what a tier means. */
+export function tierLegend(style) {
+  return (
+    `${style.green('download')} = verified public-domain full text · ` +
+    `${style.yellow('borrow')} = lending-restricted (needs a free Internet Archive account + loan) · ` +
+    `${style.gray('unverified')} = no confirmed free copy of this exact title`
+  );
+}
+
+/** Warning shown when some upstream sources did not answer. */
+export function partialWarning(failedSources, style) {
+  const names = Array.isArray(failedSources) ? failedSources.filter(Boolean) : [];
+  const listed = names.length ? names.join(', ') : 'one or more sources';
+  return (
+    `${style.yellow('Warning:')} partial results — ${listed} did not respond. ` +
+    'The list below is incomplete, not empty.'
+  );
+}