docs-cache 0.4.3 → 0.5.1

package/dist/esm/commands/clean-git-cache.d.ts

@@ -0,0 +1,10 @@
+export type CleanGitCacheResult = {
+    removed: boolean;
+    cacheDir: string;
+    repoCount?: number;
+    bytesFreed?: number;
+};
+export type CleanGitCacheOptions = {
+    json?: boolean;
+};
+export declare const cleanGitCache: () => Promise<CleanGitCacheResult>;

package/dist/esm/commands/clean-git-cache.mjs

@@ -0,0 +1,48 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { exists, resolveGitCacheDir } from "#git/cache-dir";
+const getDirSize = async (dirPath) => {
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    let totalSize = 0;
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        totalSize += await getDirSize(fullPath);
+      } else {
+        const stats = await stat(fullPath);
+        totalSize += stats.size;
+      }
+    }
+    return totalSize;
+  } catch {
+    return 0;
+  }
+};
+const countCachedRepos = async (cacheDir) => {
+  try {
+    const entries = await readdir(cacheDir);
+    return entries.length;
+  } catch {
+    return 0;
+  }
+};
+export const cleanGitCache = async () => {
+  const cacheDir = resolveGitCacheDir();
+  const cacheExists = await exists(cacheDir);
+  if (!cacheExists) {
+    return {
+      removed: false,
+      cacheDir
+    };
+  }
+  const repoCount = await countCachedRepos(cacheDir);
+  const bytesFreed = await getDirSize(cacheDir);
+  await rm(cacheDir, { recursive: true, force: true });
+  return {
+    removed: true,
+    cacheDir,
+    repoCount,
+    bytesFreed
+  };
+};

package/dist/esm/commands/clean.d.ts

@@ -0,0 +1,10 @@
+type CleanOptions = {
+    configPath?: string;
+    cacheDirOverride?: string;
+    json: boolean;
+};
+export declare const cleanCache: (options: CleanOptions) => Promise<{
+    cacheDir: any;
+    removed: boolean;
+}>;
+export {};

package/dist/esm/commands/clean.mjs

@@ -0,0 +1,27 @@
+import { access, rm } from "node:fs/promises";
+import { DEFAULT_CACHE_DIR, loadConfig } from "#config";
+import { resolveCacheDir } from "#core/paths";
+const exists = async (target) => {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+export const cleanCache = async (options) => {
+  const { config, resolvedPath } = await loadConfig(options.configPath);
+  const cacheDir = resolveCacheDir(
+    resolvedPath,
+    config.cacheDir ?? DEFAULT_CACHE_DIR,
+    options.cacheDirOverride
+  );
+  const cacheDirExists = await exists(cacheDir);
+  if (cacheDirExists) {
+    await rm(cacheDir, { recursive: true, force: true });
+  }
+  return {
+    cacheDir,
+    removed: cacheDirExists
+  };
+};

package/dist/esm/commands/init.d.ts

@@ -0,0 +1,19 @@
+import { confirm as clackConfirm, isCancel as clackIsCancel, select as clackSelect, text as clackText } from "@clack/prompts";
+type InitOptions = {
+    cacheDirOverride?: string;
+    json: boolean;
+    cwd?: string;
+};
+type PromptDeps = {
+    confirm?: typeof clackConfirm;
+    isCancel?: typeof clackIsCancel;
+    select?: typeof clackSelect;
+    text?: typeof clackText;
+};
+export declare const initConfig: (options: InitOptions, deps?: PromptDeps) => Promise<{
+    configPath: string;
+    created: boolean;
+    gitignoreUpdated: any;
+    gitignorePath: any;
+}>;
+export {};

package/dist/esm/commands/init.mjs

@@ -0,0 +1,179 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  confirm as clackConfirm,
+  isCancel as clackIsCancel,
+  select as clackSelect,
+  text as clackText
+} from "@clack/prompts";
+import {
+  DEFAULT_CACHE_DIR,
+  DEFAULT_CONFIG_FILENAME,
+  stripDefaultConfigValues,
+  writeConfig
+} from "#config";
+import { ensureGitignoreEntry, getGitignoreStatus } from "#core/gitignore";
+const exists = async (target) => {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+const readJson = async (filePath) => {
+  const raw = await readFile(filePath, "utf8");
+  return JSON.parse(raw);
+};
+const findExistingConfigPaths = async (cwd) => {
+  const defaultConfigPath = path.resolve(cwd, DEFAULT_CONFIG_FILENAME);
+  const packagePath = path.resolve(cwd, "package.json");
+  const existingConfigPaths = [];
+  if (await exists(defaultConfigPath)) {
+    existingConfigPaths.push(defaultConfigPath);
+  }
+  if (await exists(packagePath)) {
+    const parsed = await readJson(packagePath);
+    if (parsed["docs-cache"]) {
+      existingConfigPaths.push(packagePath);
+    }
+  }
+  return { existingConfigPaths, defaultConfigPath, packagePath };
+};
+const selectConfigPath = async (packagePath, defaultConfigPath, select, isCancel) => {
+  if (!await exists(packagePath)) {
+    return defaultConfigPath;
+  }
+  const parsed = await readJson(packagePath);
+  if (parsed["docs-cache"]) {
+    return defaultConfigPath;
+  }
+  const locationAnswer = await select({
+    message: "Config location",
+    options: [
+      { value: "config", label: "docs.config.json" },
+      { value: "package", label: "package.json" }
+    ],
+    initialValue: "config"
+  });
+  if (isCancel(locationAnswer)) {
+    throw new Error("Init cancelled.");
+  }
+  return locationAnswer === "package" ? packagePath : defaultConfigPath;
+};
+const promptInitAnswers = async (cacheDir, cwd, confirm, text, isCancel) => {
+  const cacheDirAnswer = await text({
+    message: "Cache directory",
+    initialValue: cacheDir
+  });
+  if (isCancel(cacheDirAnswer)) {
+    throw new Error("Init cancelled.");
+  }
+  const cacheDirValue = cacheDirAnswer || DEFAULT_CACHE_DIR;
+  const tocAnswer = await confirm({
+    message: "Generate TOC.md (table of contents with links to all documentation)",
+    initialValue: true
+  });
+  if (isCancel(tocAnswer)) {
+    throw new Error("Init cancelled.");
+  }
+  const gitignoreStatus = await getGitignoreStatus(cwd, cacheDirValue);
+  let gitignoreAnswer = false;
+  if (gitignoreStatus.entry && !gitignoreStatus.hasEntry) {
+    const reply = await confirm({
+      message: "Add cache directory to .gitignore",
+      initialValue: true
+    });
+    if (isCancel(reply)) {
+      throw new Error("Init cancelled.");
+    }
+    gitignoreAnswer = reply;
+  }
+  return {
+    cacheDir: cacheDirValue,
+    toc: tocAnswer,
+    gitignore: gitignoreAnswer
+  };
+};
+const buildBaseConfig = (cacheDir, toc) => {
+  const config = {
+    $schema: "https://raw.githubusercontent.com/fbosch/docs-cache/main/docs.config.schema.json",
+    sources: []
+  };
+  if (cacheDir !== DEFAULT_CACHE_DIR) {
+    config.cacheDir = cacheDir;
+  }
+  if (!toc) {
+    config.defaults = { toc: false };
+  }
+  return config;
+};
+const writePackageConfig = async (configPath, config, gitignore) => {
+  const raw = await readFile(configPath, "utf8");
+  const pkg = JSON.parse(raw);
+  if (pkg["docs-cache"]) {
+    throw new Error(`docs-cache config already exists in ${configPath}.`);
+  }
+  pkg["docs-cache"] = stripDefaultConfigValues(config);
+  await writeFile(configPath, `${JSON.stringify(pkg, null, 2)}
+`, "utf8");
+  const gitignoreResult = gitignore ? await ensureGitignoreEntry(
+    path.dirname(configPath),
+    config.cacheDir ?? DEFAULT_CACHE_DIR
+  ) : null;
+  return {
+    configPath,
+    created: true,
+    gitignoreUpdated: gitignoreResult?.updated ?? false,
+    gitignorePath: gitignoreResult?.gitignorePath ?? null
+  };
+};
+const writeStandaloneConfig = async (configPath, config, gitignore) => {
+  await writeConfig(configPath, config);
+  const gitignoreResult = gitignore ? await ensureGitignoreEntry(
+    path.dirname(configPath),
+    config.cacheDir ?? DEFAULT_CACHE_DIR
+  ) : null;
+  return {
+    configPath,
+    created: true,
+    gitignoreUpdated: gitignoreResult?.updated ?? false,
+    gitignorePath: gitignoreResult?.gitignorePath ?? null
+  };
+};
+export const initConfig = async (options, deps = {}) => {
+  const confirm = deps.confirm ?? clackConfirm;
+  const isCancel = deps.isCancel ?? clackIsCancel;
+  const select = deps.select ?? clackSelect;
+  const text = deps.text ?? clackText;
+  const cwd = options.cwd ?? process.cwd();
+  const { existingConfigPaths, defaultConfigPath, packagePath } = await findExistingConfigPaths(cwd);
+  if (existingConfigPaths.length > 0) {
+    throw new Error(
+      `Config already exists at ${existingConfigPaths.join(", ")}. Init aborted.`
+    );
+  }
+  const configPath = await selectConfigPath(
+    packagePath,
+    defaultConfigPath,
+    select,
+    isCancel
+  );
+  const cacheDir = options.cacheDirOverride ?? DEFAULT_CACHE_DIR;
+  const answers = await promptInitAnswers(
+    cacheDir,
+    cwd,
+    confirm,
+    text,
+    isCancel
+  );
+  const resolvedConfigPath = path.resolve(cwd, configPath);
+  const config = buildBaseConfig(answers.cacheDir, answers.toc);
+  if (path.basename(resolvedConfigPath) === "package.json") {
+    return writePackageConfig(resolvedConfigPath, config, answers.gitignore);
+  }
+  if (await exists(resolvedConfigPath)) {
+    throw new Error(`Config already exists at ${resolvedConfigPath}.`);
+  }
+  return writeStandaloneConfig(resolvedConfigPath, config, answers.gitignore);
+};

package/dist/esm/commands/prune.d.ts

@@ -0,0 +1,11 @@
+type PruneOptions = {
+    configPath?: string;
+    cacheDirOverride?: string;
+    json: boolean;
+};
+export declare const pruneCache: (options: PruneOptions) => Promise<{
+    cacheDir: any;
+    removed: string[];
+    kept: any;
+}>;
+export {};

package/dist/esm/commands/prune.mjs

@@ -0,0 +1,52 @@
+import { access, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_CACHE_DIR, loadConfig } from "#config";
+import { resolveCacheDir } from "#core/paths";
+const exists = async (target) => {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+export const pruneCache = async (options) => {
+  const { config, resolvedPath, sources } = await loadConfig(
+    options.configPath
+  );
+  const cacheDir = resolveCacheDir(
+    resolvedPath,
+    config.cacheDir ?? DEFAULT_CACHE_DIR,
+    options.cacheDirOverride
+  );
+  const cacheDirExists = await exists(cacheDir);
+  if (!cacheDirExists) {
+    return {
+      cacheDir,
+      removed: [],
+      kept: sources.map((source) => source.id)
+    };
+  }
+  const keepIds = new Set(sources.map((source) => source.id));
+  const entries = await readdir(cacheDir, { withFileTypes: true });
+  const removed = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const name = entry.name;
+    if (keepIds.has(name)) {
+      continue;
+    }
+    if (name.startsWith(".tmp-")) {
+      continue;
+    }
+    await rm(path.join(cacheDir, name), { recursive: true, force: true });
+    removed.push(name);
+  }
+  return {
+    cacheDir,
+    removed,
+    kept: sources.map((source) => source.id)
+  };
+};

package/dist/esm/commands/remove.d.ts

@@ -0,0 +1,12 @@
+export declare const removeSources: (params: {
+    configPath?: string;
+    ids: string[];
+}) => Promise<{
+    configPath: any;
+    removed: any;
+    missing: string[];
+    targetsRemoved: {
+        id: string;
+        targetDir: string;
+    }[];
+}>;

package/dist/esm/commands/remove.mjs

@@ -0,0 +1,87 @@
+import { rm } from "node:fs/promises";
+import {
+  mergeConfigBase,
+  readConfigAtPath,
+  resolveConfigTarget,
+  writeConfigFile
+} from "#config/io";
+import { resolveTargetDir } from "#core/paths";
+import { resolveRepoInput } from "#git/resolve-repo";
+const resolveIdsToRemove = (ids, config) => {
+  const sourcesById = new Map(
+    config.sources.map((source) => [source.id, source])
+  );
+  const sourcesByRepo = new Map(
+    config.sources.map((source) => [source.repo, source])
+  );
+  const idsToRemove = /* @__PURE__ */ new Set();
+  const missing = [];
+  for (const token of ids) {
+    if (sourcesById.has(token)) {
+      idsToRemove.add(token);
+      continue;
+    }
+    const resolved = resolveRepoInput(token);
+    if (resolved.repoUrl && sourcesByRepo.has(resolved.repoUrl)) {
+      const source = sourcesByRepo.get(resolved.repoUrl);
+      if (source) {
+        idsToRemove.add(source.id);
+      }
+      continue;
+    }
+    if (resolved.inferredId && sourcesById.has(resolved.inferredId)) {
+      idsToRemove.add(resolved.inferredId);
+      continue;
+    }
+    missing.push(token);
+  }
+  return { idsToRemove, missing };
+};
+const removeTargets = async (resolvedPath, removedSources) => {
+  const targetRemovals = [];
+  for (const source of removedSources) {
+    if (!source.targetDir) {
+      continue;
+    }
+    const targetDir = resolveTargetDir(resolvedPath, source.targetDir);
+    await rm(targetDir, { recursive: true, force: true });
+    targetRemovals.push({ id: source.id, targetDir });
+  }
+  return targetRemovals;
+};
+export const removeSources = async (params) => {
+  if (params.ids.length === 0) {
+    throw new Error("No sources specified to remove.");
+  }
+  const target = await resolveConfigTarget(params.configPath);
+  const resolvedPath = target.resolvedPath;
+  const { config, rawConfig, rawPackage } = await readConfigAtPath(target);
+  if (target.mode === "package" && !rawConfig) {
+    throw new Error(`Missing docs-cache config in ${resolvedPath}.`);
+  }
+  const { idsToRemove, missing } = resolveIdsToRemove(params.ids, config);
+  const remaining = config.sources.filter(
+    (source) => !idsToRemove.has(source.id)
+  );
+  const removed = config.sources.filter((source) => idsToRemove.has(source.id)).map((source) => source.id);
+  const removedSources = config.sources.filter(
+    (source) => idsToRemove.has(source.id)
+  );
+  if (removed.length === 0) {
+    throw new Error("No matching sources found to remove.");
+  }
+  const nextConfig = mergeConfigBase(rawConfig ?? config, remaining);
+  await writeConfigFile({
+    mode: target.mode,
+    resolvedPath,
+    config: nextConfig,
+    rawPackage
+  });
+  const targetRemovals = await removeTargets(resolvedPath, removedSources);
+  return {
+    configPath: resolvedPath,
+    removed,
+    missing,
+    targetsRemoved: targetRemovals
+  };
+};

package/dist/esm/commands/status.d.ts

@@ -0,0 +1,16 @@
+type StatusOptions = {
+    configPath?: string;
+    cacheDirOverride?: string;
+    json: boolean;
+};
+export declare const getStatus: (options: StatusOptions) => Promise<{
+    configPath: any;
+    cacheDir: any;
+    cacheDirExists: boolean;
+    lockPath: any;
+    lockExists: boolean;
+    lockValid: boolean;
+    sources: any;
+}>;
+export declare const printStatus: (status: Awaited<ReturnType<typeof getStatus>>) => void;
+export {};

package/dist/esm/commands/status.mjs

@@ -0,0 +1,78 @@
+import { access } from "node:fs/promises";
+import pc from "picocolors";
+import { DEFAULT_LOCK_FILENAME, readLock, resolveLockPath } from "#cache/lock";
+import { symbols, ui } from "#cli/ui";
+import { DEFAULT_CACHE_DIR, loadConfig } from "#config";
+import { getCacheLayout, resolveCacheDir } from "#core/paths";
+const exists = async (target) => {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+export const getStatus = async (options) => {
+  const { config, resolvedPath, sources } = await loadConfig(
+    options.configPath
+  );
+  const resolvedCacheDir = resolveCacheDir(
+    resolvedPath,
+    config.cacheDir ?? DEFAULT_CACHE_DIR,
+    options.cacheDirOverride
+  );
+  const cacheDirExists = await exists(resolvedCacheDir);
+  const lockPath = resolveLockPath(resolvedPath);
+  const lockExists = await exists(lockPath);
+  let lockValid = false;
+  let lockData = null;
+  if (lockExists) {
+    try {
+      lockData = await readLock(lockPath);
+      lockValid = true;
+    } catch {
+      lockValid = false;
+    }
+  }
+  const sourceStatus = await Promise.all(
+    sources.map(async (source) => {
+      const layout = getCacheLayout(resolvedCacheDir, source.id);
+      const docsExists = await exists(layout.sourceDir);
+      const lockEntry = lockData?.sources?.[source.id] ?? null;
+      return {
+        id: source.id,
+        docsPath: layout.sourceDir,
+        docsExists,
+        lockEntry
+      };
+    })
+  );
+  return {
+    configPath: resolvedPath,
+    cacheDir: resolvedCacheDir,
+    cacheDirExists,
+    lockPath,
+    lockExists,
+    lockValid,
+    sources: sourceStatus
+  };
+};
+export const printStatus = (status) => {
+  const relCache = ui.path(status.cacheDir);
+  const cacheState = status.cacheDirExists ? pc.green("present") : pc.red("missing");
+  const lockState = status.lockExists ? status.lockValid ? pc.green("valid") : pc.red("invalid") : pc.yellow("missing");
+  ui.header("Cache", `${relCache} (${cacheState})`);
+  ui.header("Lock", `${DEFAULT_LOCK_FILENAME} (${lockState})`);
+  if (status.sources.length === 0) {
+    ui.line();
+    ui.line(`${symbols.warn} No sources configured.`);
+    return;
+  }
+  ui.line();
+  for (const source of status.sources) {
+    const icon = source.docsExists ? symbols.success : symbols.error;
+    const lockLabel = source.lockEntry ? pc.green("locked") : pc.yellow("new");
+    const shortHash = ui.hash(source.lockEntry?.resolvedCommit);
+    ui.item(icon, source.id.padEnd(20), `${lockLabel.padEnd(10)} ${shortHash}`);
+  }
+};

package/dist/esm/commands/sync.d.ts

@@ -0,0 +1,33 @@
+import { materializeSource } from "#cache/materialize";
+import { fetchSource } from "#git/fetch-source";
+import { resolveRemoteCommit } from "#git/resolve-remote";
+import type { SyncOptions } from "#types/sync";
+type SyncDeps = {
+    resolveRemoteCommit?: typeof resolveRemoteCommit;
+    fetchSource?: typeof fetchSource;
+    materializeSource?: typeof materializeSource;
+};
+export declare const getSyncPlan: (options: SyncOptions, deps?: SyncDeps) => Promise<{
+    config: any;
+    configPath: any;
+    cacheDir: any;
+    lockPath: any;
+    lockExists: boolean;
+    lockData: any;
+    results: SyncResult[];
+    sources: any;
+    defaults: DocsCacheDefaults;
+}>;
+export declare const runSync: (options: SyncOptions, deps?: SyncDeps) => Promise<{
+    config: any;
+    configPath: any;
+    cacheDir: any;
+    lockPath: any;
+    lockExists: boolean;
+    lockData: any;
+    results: SyncResult[];
+    sources: any;
+    defaults: DocsCacheDefaults;
+}>;
+export declare const printSyncPlan: (plan: Awaited<ReturnType<typeof getSyncPlan>>) => void;
+export {};