docs-cache 0.4.2 → 0.5.1

package/dist/esm/cli/exit-code.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI exit codes.
+ *
+ * @see https://nodejs.org/api/process.html#process_exit_codes
+ */
+export declare const ExitCode: {
+    Success: number;
+    FatalError: number;
+    InvalidArgument: number;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/esm/cli/exit-code.mjs

@@ -0,0 +1,5 @@
+export const ExitCode = {
+  Success: 0,
+  FatalError: 1,
+  InvalidArgument: 9
+};

package/dist/esm/cli/index.d.ts

@@ -0,0 +1,5 @@
+export declare const CLI_NAME = "docs-cache";
+/**
+ * The main entry point of the CLI
+ */
+export declare function main(): Promise<void>;

package/dist/esm/cli/index.mjs

@@ -0,0 +1,345 @@
+import path from "node:path";
+import process from "node:process";
+import pc from "picocolors";
+import { ExitCode } from "#cli/exit-code";
+import { parseArgs } from "#cli/parse-args";
+import { setSilentMode, setVerboseMode, symbols, ui } from "#cli/ui";
+export const CLI_NAME = "docs-cache";
+const HELP_TEXT = `
+Usage: ${CLI_NAME} <command> [options]
+
+Commands:
+  add         Add sources to the config (supports github:org/repo#ref)
+  remove      Remove sources from the config and targets
+  sync        Synchronize cache with config
+  status      Show cache status
+  clean       Remove project cache
+  clean-cache Clear global git cache
+  prune       Remove unused data
+  verify      Validate cache integrity
+  init        Create a new config interactively
+
+Global options:
+  --config <path>
+  --cache-dir <path>
+  --offline
+  --fail-on-miss
+  --lock-only
+  --concurrency <n>
+  --json
+  --timeout-ms <n>
+  --silent
+  --verbose
+
+Add options:
+  --source <repo>
+  --target <dir>
+  --target-dir <path>
+  --id <id>
+`;
+const printHelp = () => {
+  process.stdout.write(HELP_TEXT.trimStart());
+};
+const printError = (message) => {
+  process.stderr.write(`${symbols.error} ${message}
+`);
+};
+const runAdd = async (parsed) => {
+  const options = parsed.options;
+  const { addSources } = await import("#commands/add");
+  const { runSync } = await import("#commands/sync");
+  if (parsed.entries.length === 0) {
+    throw new Error(
+      "Usage: docs-cache add [--source <repo> --target <dir>] <repo...>"
+    );
+  }
+  const result = await addSources({
+    configPath: options.config,
+    entries: parsed.entries
+  });
+  if (options.offline) {
+    if (!options.json) {
+      ui.line(`${symbols.warn} Offline: skipped sync`);
+    }
+  } else {
+    await runSync({
+      configPath: options.config,
+      cacheDirOverride: options.cacheDir,
+      json: options.json,
+      lockOnly: options.lockOnly,
+      offline: options.offline,
+      failOnMiss: options.failOnMiss,
+      sourceFilter: result.sources.map((source) => source.id),
+      timeoutMs: options.timeoutMs,
+      verbose: options.verbose
+    });
+  }
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  for (const source of result.sources) {
+    const repoLabel = source.repo.replace(/^https?:\/\//, "").replace(/\.git$/, "");
+    const targetLabel = source.targetDir ? ` ${pc.dim("->")} ${pc.magenta(source.targetDir)}` : "";
+    ui.item(symbols.success, source.id, `${pc.blue(repoLabel)}${targetLabel}`);
+  }
+  if (result.skipped?.length) {
+    ui.line(
+      `${symbols.warn} Skipped ${result.skipped.length} existing source${result.skipped.length === 1 ? "" : "s"}: ${result.skipped.join(", ")}`
+    );
+  }
+  ui.line(
+    `${symbols.info} Updated ${pc.gray(path.relative(process.cwd(), result.configPath) || "docs.config.json")}`
+  );
+  if (result.gitignoreUpdated && result.gitignorePath) {
+    ui.line(
+      `${symbols.info} Updated ${pc.gray(ui.path(result.gitignorePath))}`
+    );
+  }
+};
+const runRemove = async (parsed) => {
+  const options = parsed.options;
+  const { removeSources } = await import("#commands/remove");
+  const { pruneCache } = await import("#commands/prune");
+  if (parsed.ids.length === 0) {
+    throw new Error("Usage: docs-cache remove <id...>");
+  }
+  const result = await removeSources({
+    configPath: options.config,
+    ids: parsed.ids
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (result.removed.length > 0) {
+    ui.line(
+      `${symbols.success} Removed ${result.removed.length} source${result.removed.length === 1 ? "" : "s"}: ${result.removed.join(", ")}`
+    );
+  }
+  if (result.missing.length > 0) {
+    ui.line(
+      `${symbols.warn} Missing ${result.missing.length} source${result.missing.length === 1 ? "" : "s"}: ${result.missing.join(", ")}`
+    );
+  }
+  if (result.targetsRemoved.length > 0) {
+    const targetLabels = result.targetsRemoved.map((entry) => `${entry.id} -> ${ui.path(entry.targetDir)}`).join(", ");
+    ui.line(
+      `${symbols.success} Removed ${result.targetsRemoved.length} target${result.targetsRemoved.length === 1 ? "" : "s"}: ${targetLabels}`
+    );
+  }
+  ui.line(
+    `${symbols.info} Updated ${pc.gray(path.relative(process.cwd(), result.configPath) || "docs.config.json")}`
+  );
+  if (options.prune) {
+    await pruneCache({
+      configPath: options.config,
+      cacheDirOverride: options.cacheDir,
+      json: options.json
+    });
+  }
+};
+const runStatus = async (parsed) => {
+  const options = parsed.options;
+  const { getStatus, printStatus } = await import("#commands/status");
+  const status = await getStatus({
+    configPath: options.config,
+    cacheDirOverride: options.cacheDir,
+    json: options.json
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(status, null, 2)}
+`);
+    return;
+  }
+  printStatus(status);
+};
+const runClean = async (parsed) => {
+  const options = parsed.options;
+  const { cleanCache } = await import("#commands/clean");
+  const result = await cleanCache({
+    configPath: options.config,
+    cacheDirOverride: options.cacheDir,
+    json: options.json
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (result.removed) {
+    ui.line(`${symbols.success} Removed cache at ${ui.path(result.cacheDir)}`);
+    return;
+  }
+  ui.line(
+    `${symbols.info} Cache already missing at ${ui.path(result.cacheDir)}`
+  );
+};
+const runCleanCache = async (parsed) => {
+  const options = parsed.options;
+  const { cleanGitCache } = await import("#commands/clean-git-cache");
+  const result = await cleanGitCache();
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (!result.removed) {
+    ui.line(
+      `${symbols.info} Global git cache already empty at ${ui.path(result.cacheDir)}`
+    );
+    return;
+  }
+  const sizeInMB = result.bytesFreed !== void 0 ? `${(result.bytesFreed / 1024 / 1024).toFixed(2)} MB` : "unknown size";
+  const repoLabel = result.repoCount !== void 0 ? ` (${result.repoCount} cached repositor${result.repoCount === 1 ? "y" : "ies"})` : "";
+  ui.line(
+    `${symbols.success} Cleared global git cache${repoLabel}: ${sizeInMB} freed`
+  );
+  ui.line(`${symbols.info} Cache location: ${ui.path(result.cacheDir)}`);
+};
+const runPrune = async (parsed) => {
+  const options = parsed.options;
+  const { pruneCache } = await import("#commands/prune");
+  const result = await pruneCache({
+    configPath: options.config,
+    cacheDirOverride: options.cacheDir,
+    json: options.json
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (result.removed.length === 0) {
+    ui.line(`${symbols.info} No cache entries to prune.`);
+    return;
+  }
+  ui.line(
+    `${symbols.success} Pruned ${result.removed.length} cache entr${result.removed.length === 1 ? "y" : "ies"}: ${result.removed.join(", ")}`
+  );
+};
+const runSyncCommand = async (parsed) => {
+  const options = parsed.options;
+  const { printSyncPlan, runSync } = await import("#commands/sync");
+  const plan = await runSync({
+    configPath: options.config,
+    cacheDirOverride: options.cacheDir,
+    json: options.json,
+    lockOnly: options.lockOnly,
+    offline: options.offline,
+    failOnMiss: options.failOnMiss,
+    timeoutMs: options.timeoutMs,
+    verbose: options.verbose
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(plan, null, 2)}
+`);
+    return;
+  }
+  printSyncPlan(plan);
+};
+const runVerify = async (parsed) => {
+  const options = parsed.options;
+  const { printVerify, verifyCache } = await import("#commands/verify");
+  const report = await verifyCache({
+    configPath: options.config,
+    cacheDirOverride: options.cacheDir,
+    json: options.json
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+  } else {
+    printVerify(report);
+  }
+  if (report.results.some((result) => !result.ok)) {
+    process.exit(ExitCode.FatalError);
+  }
+};
+const runInit = async (parsed) => {
+  const options = parsed.options;
+  const { initConfig } = await import("#commands/init");
+  if (options.config) {
+    throw new Error("Init does not accept --config. Use the project root.");
+  }
+  const result = await initConfig({
+    cacheDirOverride: options.cacheDir,
+    json: options.json
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  ui.line(`${symbols.success} Wrote ${pc.gray(ui.path(result.configPath))}`);
+  if (result.gitignoreUpdated && result.gitignorePath) {
+    ui.line(
+      `${symbols.info} Updated ${pc.gray(ui.path(result.gitignorePath))}`
+    );
+  }
+};
+const runCommand = async (parsed) => {
+  switch (parsed.command) {
+    case "add":
+      await runAdd(parsed);
+      return;
+    case "remove":
+      await runRemove(parsed);
+      return;
+    case "status":
+      await runStatus(parsed);
+      return;
+    case "clean":
+      await runClean(parsed);
+      return;
+    case "clean-cache":
+      await runCleanCache(parsed);
+      return;
+    case "prune":
+      await runPrune(parsed);
+      return;
+    case "sync":
+      await runSyncCommand(parsed);
+      return;
+    case "verify":
+      await runVerify(parsed);
+      return;
+    case "init":
+      await runInit(parsed);
+      return;
+    default:
+      ui.line(`${CLI_NAME} ${parsed.command}: not implemented yet.`);
+  }
+};
+export async function main() {
+  try {
+    process.on("uncaughtException", errorHandler);
+    process.on("unhandledRejection", errorHandler);
+    const parsed = parseArgs();
+    setSilentMode(parsed.options.silent);
+    setVerboseMode(parsed.options.verbose);
+    if (parsed.help) {
+      printHelp();
+      process.exit(ExitCode.Success);
+    }
+    if (!parsed.command) {
+      printHelp();
+      process.exit(ExitCode.InvalidArgument);
+    }
+    if (parsed.command !== "add" && parsed.command !== "remove" && parsed.positionals.length > 0) {
+      printError(`${CLI_NAME}: unexpected arguments.`);
+      printHelp();
+      process.exit(ExitCode.InvalidArgument);
+    }
+    await runCommand(parsed.parsed);
+  } catch (error) {
+    errorHandler(error);
+  }
+}
+function errorHandler(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  printError(message);
+  process.exit(ExitCode.FatalError);
+}

package/dist/esm/cli/live-output.d.ts

@@ -0,0 +1,12 @@
+type LiveOutputOptions = {
+    stdout?: NodeJS.WriteStream;
+    maxWidth?: number;
+};
+export type LiveOutput = {
+    render: (lines: string[]) => void;
+    persist: (lines: string[]) => void;
+    clear: () => void;
+    stop: () => void;
+};
+export declare const createLiveOutput: (options?: LiveOutputOptions) => LiveOutput;
+export {};

package/dist/esm/cli/live-output.mjs

@@ -0,0 +1,30 @@
+import cliTruncate from "cli-truncate";
+import { createLogUpdate } from "log-update";
+const normalizeLines = (lines) => lines.map((line) => line.length === 0 ? line : line);
+export const createLiveOutput = (options = {}) => {
+  const stdout = options.stdout ?? process.stdout;
+  const updater = createLogUpdate(stdout);
+  const maxWidth = options.maxWidth ?? Math.max(20, (stdout.columns ?? 80) - 2);
+  const truncate = (line) => cliTruncate(line, maxWidth, { position: "end" });
+  const render = (lines) => {
+    const output = normalizeLines(lines).map(truncate).join("\n");
+    updater(output);
+  };
+  const persist = (lines) => {
+    const output = normalizeLines(lines).map(truncate).join("\n");
+    updater(output);
+    updater.done();
+  };
+  const clear = () => {
+    updater.clear();
+  };
+  const stop = () => {
+    updater.done();
+  };
+  return {
+    render,
+    persist,
+    clear,
+    stop
+  };
+};

package/dist/esm/cli/parse-args.d.ts

@@ -0,0 +1,13 @@
+import type { CliCommand, CliOptions } from "./types";
+declare const COMMANDS: readonly ["add", "remove", "sync", "status", "clean", "clean-cache", "prune", "verify", "init"];
+type Command = (typeof COMMANDS)[number];
+export type ParsedArgs = {
+    command: Command | null;
+    options: CliOptions;
+    positionals: string[];
+    rawArgs: string[];
+    help: boolean;
+    parsed: CliCommand;
+};
+export declare const parseArgs: (argv?: any) => ParsedArgs;
+export {};