@lukoweb/apitogo 0.2.22 → 0.2.24

package/src/config/v2/init.ts

@@ -1,273 +1,273 @@
-import { access, mkdir, stat, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { ApitogoError } from "../../lib/util/invariant.js";
-import { APITOGO_CONFIG_FILENAME } from "../apitogo-config-core.js";
-import {
-  type DocsCandidate,
-  detectExistingDocs,
-  detectLayout,
-  ensureStateDir,
-} from "./layout.js";
-import { parseConfigV2 } from "./parse.js";
-import { layoutRoot, statePathsFor } from "./paths.js";
-import type { ConfigV2, Layout } from "./schema.js";
-
-export class InitError extends ApitogoError {
-  constructor(message: string, developerHint?: string) {
-    super(message, { developerHint, title: "Cannot initialise the project" });
-    this.name = "InitError";
-  }
-}
-
-export type InitOptions = {
-  /** Project directory; created if it does not exist. */
-  dir: string;
-  /** Overrides layout detection. */
-  layout?: Layout;
-  /** Project and portal name; defaults to the directory name. */
-  name?: string;
-  /** Existing docs to include, as paths relative to `dir`; `false` skips docs detection. */
-  docs?: string[] | false;
-  /** When several docs candidates exist, include all of them instead of asking. */
-  acceptAllDocs?: boolean;
-  /** Replace an existing `apitogo.config.json`. It is the only existing file `init` ever replaces. */
-  force?: boolean;
-};
-
-export type PlannedEntry = {
-  kind: "dir" | "file";
-  /** Absolute path. */
-  path: string;
-  /** `state` entries are created by {@link ensureStateDir}. */
-  purpose: "config" | "state" | "portal";
-  content?: string;
-};
-
-export type InitPlan = {
-  dir: string;
-  configPath: string;
-  layout: Layout;
-  layoutSource: "detected" | "flag";
-  layoutReason: string;
-  /** The config that will be written; already validated against the v2 schema. */
-  config: ConfigV2;
-  docsCandidates: DocsCandidate[];
-  /** Globs written to `portal.docs.content`. */
-  docsIncluded: string[];
-  /** Several candidates were found and none was chosen yet: the caller should ask and plan again. */
-  needsDocsChoice: boolean;
-  /** Everything `init` will create. */
-  entries: PlannedEntry[];
-  /** Files that already exist and stay untouched. */
-  keep: string[];
-  /** An existing config will be replaced (only with `force`). */
-  replacesConfig: boolean;
-};
-
-async function exists(target: string): Promise<boolean> {
-  try {
-    await access(target);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function starterPage(name: string): string {
-  return `---
-title: Welcome
----
-
-# ${name}
-
-This page was created by \`apitogo init\`. Edit it, and add more \`.md\` or \`.mdx\` files next to it: each one becomes a page of your portal.
-`;
-}
-
-/** Turns paths the user named into globs, checking that each exists inside the project. */
-export async function docsFromPaths(
-  dir: string,
-  requested: readonly string[],
-): Promise<string[]> {
-  const globs: string[] = [];
-  for (const requestedPath of requested) {
-    const absolute = path.resolve(dir, requestedPath);
-    const relative = path.relative(dir, absolute).split(path.sep).join("/");
-    if (
-      relative === "" ||
-      relative.startsWith("..") ||
-      path.isAbsolute(relative)
-    ) {
-      throw new InitError(
-        `Docs path "${requestedPath}" is outside the project directory.`,
-      );
-    }
-    const info = await stat(absolute).catch(() => undefined);
-    if (!info)
-      throw new InitError(
-        `Docs path "${requestedPath}" does not exist in ${dir}.`,
-      );
-    globs.push(info.isDirectory() ? `${relative}/**/*.{md,mdx}` : relative);
-  }
-  return globs;
-}
-
-/**
- * Decides what `init` would do without touching the disk (Reference, section 1.2). Existing files are never moved,
- * renamed or modified; existing docs are referenced in place; the root `.gitignore` is never edited.
- */
-export async function planInit(options: InitOptions): Promise<InitPlan> {
-  const dir = path.resolve(options.dir);
-  const configPath = path.join(dir, APITOGO_CONFIG_FILENAME);
-
-  const replacesConfig = await exists(configPath);
-  if (replacesConfig && !options.force) {
-    throw new InitError(
-      `${configPath} already exists.`,
-      "Pass --force to replace it. Nothing else in the project is changed.",
-    );
-  }
-
-  const detection = options.layout ? undefined : await detectLayout(dir);
-  const layout = options.layout ?? detection?.layout ?? "standalone";
-  const layoutReason = options.layout
-    ? `chosen with --layout ${options.layout}`
-    : (detection?.reason ?? "");
-
-  let docsCandidates: DocsCandidate[] = [];
-  let docsIncluded: string[] = [];
-  let needsDocsChoice = false;
-  if (Array.isArray(options.docs) && options.docs.length > 0) {
-    docsIncluded = await docsFromPaths(dir, options.docs);
-  } else if (options.docs !== false) {
-    docsCandidates = await detectExistingDocs(dir);
-    if (
-      docsCandidates.length === 1 ||
-      (docsCandidates.length > 1 && options.acceptAllDocs)
-    ) {
-      docsIncluded = docsCandidates.map((candidate) => candidate.glob);
-    } else if (docsCandidates.length > 1) {
-      needsDocsChoice = true;
-    }
-  }
-
-  const name = options.name?.trim() || path.basename(dir);
-  const config = parseConfigV2({
-    version: 2,
-    layout,
-    project: { name },
-    portal: {
-      name,
-      ...(docsIncluded.length > 0 ? { docs: { content: docsIncluded } } : {}),
-    },
-  });
-
-  const root = layoutRoot(dir, layout);
-  const state = statePathsFor(dir, layout);
-  const entries: PlannedEntry[] = [
-    {
-      kind: "file",
-      path: configPath,
-      purpose: "config",
-      content: `${JSON.stringify(config, null, 2)}\n`,
-    },
-    { kind: "file", path: state.gitignore, purpose: "state", content: "*\n" },
-    { kind: "dir", path: state.generatedDir, purpose: "state" },
-    { kind: "dir", path: state.buildDir, purpose: "state" },
-  ];
-
-  const keep: string[] = [];
-  if (docsIncluded.length === 0) {
-    // No existing docs to reference: give the portal an empty pages folder with one starter page.
-    const starter = path.join(root, "portal", "pages", "index.mdx");
-    if (await exists(starter)) keep.push(starter);
-    else
-      entries.push({
-        kind: "file",
-        path: starter,
-        purpose: "portal",
-        content: starterPage(name),
-      });
-  }
-
-  return {
-    dir,
-    configPath,
-    layout,
-    layoutSource: options.layout ? "flag" : "detected",
-    layoutReason,
-    config,
-    docsCandidates,
-    docsIncluded,
-    needsDocsChoice,
-    entries,
-    keep,
-    replacesConfig,
-  };
-}
-
-export type InitResult = {
-  created: string[];
-  kept: string[];
-};
-
-/** Writes the plan. Existing files are skipped, except the config when the plan replaces it. */
-export async function applyInitPlan(plan: InitPlan): Promise<InitResult> {
-  const created: string[] = [];
-  const kept = [...plan.keep];
-
-  await mkdir(plan.dir, { recursive: true });
-  await ensureStateDir(statePathsFor(plan.dir, plan.layout));
-  for (const entry of plan.entries.filter((e) => e.purpose === "state"))
-    created.push(entry.path);
-
-  for (const entry of plan.entries.filter((e) => e.purpose !== "state")) {
-    if (entry.kind === "dir") {
-      await mkdir(entry.path, { recursive: true });
-      created.push(entry.path);
-      continue;
-    }
-    await mkdir(path.dirname(entry.path), { recursive: true });
-    try {
-      await writeFile(entry.path, entry.content ?? "", {
-        flag: entry.purpose === "config" && plan.replacesConfig ? "w" : "wx",
-      });
-      created.push(entry.path);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-      kept.push(entry.path);
-    }
-  }
-
-  return { created, kept };
-}
-
-/** The "will create" list shown before anything is written. */
-export function formatInitPlan(plan: InitPlan): string[] {
-  const rel = (target: string) =>
-    path.relative(plan.dir, target).split(path.sep).join("/") || ".";
-  const lines = [
-    `Layout: ${plan.layout} (${plan.layoutReason})`,
-    plan.docsIncluded.length > 0
-      ? `Existing docs are used in place: ${plan.docsIncluded.join(", ")}`
-      : "No existing docs found: a starter page is created.",
-    "Will create:",
-    ...plan.entries
-      .filter((entry) => !(entry.kind === "dir" && entry.purpose === "state"))
-      .map(
-        (entry) =>
-          `  ${rel(entry.path)}${plan.replacesConfig && entry.purpose === "config" ? " (replaces the existing file)" : ""}`,
-      ),
-    `  ${rel(statePathsFor(plan.dir, plan.layout).dir)}/generated/ and build/ (generated state, ignored by git)`,
-  ];
-  if (plan.keep.length > 0) {
-    lines.push(
-      "Will keep as they are:",
-      ...plan.keep.map((target) => `  ${rel(target)}`),
-    );
-  }
-  lines.push(
-    "Your own files are never moved, renamed or edited, and your .gitignore is left alone.",
-  );
-  return lines;
-}
+import { access, mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ApitogoError } from "../../lib/util/invariant.js";
+import { APITOGO_CONFIG_FILENAME } from "../apitogo-config-core.js";
+import {
+  type DocsCandidate,
+  detectExistingDocs,
+  detectLayout,
+  ensureStateDir,
+} from "./layout.js";
+import { parseConfigV2 } from "./parse.js";
+import { layoutRoot, statePathsFor } from "./paths.js";
+import type { ConfigV2, Layout } from "./schema.js";
+
+export class InitError extends ApitogoError {
+  constructor(message: string, developerHint?: string) {
+    super(message, { developerHint, title: "Cannot initialise the project" });
+    this.name = "InitError";
+  }
+}
+
+export type InitOptions = {
+  /** Project directory; created if it does not exist. */
+  dir: string;
+  /** Overrides layout detection. */
+  layout?: Layout;
+  /** Project and portal name; defaults to the directory name. */
+  name?: string;
+  /** Existing docs to include, as paths relative to `dir`; `false` skips docs detection. */
+  docs?: string[] | false;
+  /** When several docs candidates exist, include all of them instead of asking. */
+  acceptAllDocs?: boolean;
+  /** Replace an existing `apitogo.config.json`. It is the only existing file `init` ever replaces. */
+  force?: boolean;
+};
+
+export type PlannedEntry = {
+  kind: "dir" | "file";
+  /** Absolute path. */
+  path: string;
+  /** `state` entries are created by {@link ensureStateDir}. */
+  purpose: "config" | "state" | "portal";
+  content?: string;
+};
+
+export type InitPlan = {
+  dir: string;
+  configPath: string;
+  layout: Layout;
+  layoutSource: "detected" | "flag";
+  layoutReason: string;
+  /** The config that will be written; already validated against the v2 schema. */
+  config: ConfigV2;
+  docsCandidates: DocsCandidate[];
+  /** Globs written to `portal.docs.content`. */
+  docsIncluded: string[];
+  /** Several candidates were found and none was chosen yet: the caller should ask and plan again. */
+  needsDocsChoice: boolean;
+  /** Everything `init` will create. */
+  entries: PlannedEntry[];
+  /** Files that already exist and stay untouched. */
+  keep: string[];
+  /** An existing config will be replaced (only with `force`). */
+  replacesConfig: boolean;
+};
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function starterPage(name: string): string {
+  return `---
+title: Welcome
+---
+
+# ${name}
+
+This page was created by \`apitogo init\`. Edit it, and add more \`.md\` or \`.mdx\` files next to it: each one becomes a page of your portal.
+`;
+}
+
+/** Turns paths the user named into globs, checking that each exists inside the project. */
+export async function docsFromPaths(
+  dir: string,
+  requested: readonly string[],
+): Promise<string[]> {
+  const globs: string[] = [];
+  for (const requestedPath of requested) {
+    const absolute = path.resolve(dir, requestedPath);
+    const relative = path.relative(dir, absolute).split(path.sep).join("/");
+    if (
+      relative === "" ||
+      relative.startsWith("..") ||
+      path.isAbsolute(relative)
+    ) {
+      throw new InitError(
+        `Docs path "${requestedPath}" is outside the project directory.`,
+      );
+    }
+    const info = await stat(absolute).catch(() => undefined);
+    if (!info)
+      throw new InitError(
+        `Docs path "${requestedPath}" does not exist in ${dir}.`,
+      );
+    globs.push(info.isDirectory() ? `${relative}/**/*.{md,mdx}` : relative);
+  }
+  return globs;
+}
+
+/**
+ * Decides what `init` would do without touching the disk (Reference, section 1.2). Existing files are never moved,
+ * renamed or modified; existing docs are referenced in place; the root `.gitignore` is never edited.
+ */
+export async function planInit(options: InitOptions): Promise<InitPlan> {
+  const dir = path.resolve(options.dir);
+  const configPath = path.join(dir, APITOGO_CONFIG_FILENAME);
+
+  const replacesConfig = await exists(configPath);
+  if (replacesConfig && !options.force) {
+    throw new InitError(
+      `${configPath} already exists.`,
+      "Pass --force to replace it. Nothing else in the project is changed.",
+    );
+  }
+
+  const detection = options.layout ? undefined : await detectLayout(dir);
+  const layout = options.layout ?? detection?.layout ?? "standalone";
+  const layoutReason = options.layout
+    ? `chosen with --layout ${options.layout}`
+    : (detection?.reason ?? "");
+
+  let docsCandidates: DocsCandidate[] = [];
+  let docsIncluded: string[] = [];
+  let needsDocsChoice = false;
+  if (Array.isArray(options.docs) && options.docs.length > 0) {
+    docsIncluded = await docsFromPaths(dir, options.docs);
+  } else if (options.docs !== false) {
+    docsCandidates = await detectExistingDocs(dir);
+    if (
+      docsCandidates.length === 1 ||
+      (docsCandidates.length > 1 && options.acceptAllDocs)
+    ) {
+      docsIncluded = docsCandidates.map((candidate) => candidate.glob);
+    } else if (docsCandidates.length > 1) {
+      needsDocsChoice = true;
+    }
+  }
+
+  const name = options.name?.trim() || path.basename(dir);
+  const config = parseConfigV2({
+    version: 2,
+    layout,
+    project: { name },
+    portal: {
+      name,
+      ...(docsIncluded.length > 0 ? { docs: { content: docsIncluded } } : {}),
+    },
+  });
+
+  const root = layoutRoot(dir, layout);
+  const state = statePathsFor(dir, layout);
+  const entries: PlannedEntry[] = [
+    {
+      kind: "file",
+      path: configPath,
+      purpose: "config",
+      content: `${JSON.stringify(config, null, 2)}\n`,
+    },
+    { kind: "file", path: state.gitignore, purpose: "state", content: "*\n" },
+    { kind: "dir", path: state.generatedDir, purpose: "state" },
+    { kind: "dir", path: state.buildDir, purpose: "state" },
+  ];
+
+  const keep: string[] = [];
+  if (docsIncluded.length === 0) {
+    // No existing docs to reference: give the portal an empty pages folder with one starter page.
+    const starter = path.join(root, "portal", "pages", "index.mdx");
+    if (await exists(starter)) keep.push(starter);
+    else
+      entries.push({
+        kind: "file",
+        path: starter,
+        purpose: "portal",
+        content: starterPage(name),
+      });
+  }
+
+  return {
+    dir,
+    configPath,
+    layout,
+    layoutSource: options.layout ? "flag" : "detected",
+    layoutReason,
+    config,
+    docsCandidates,
+    docsIncluded,
+    needsDocsChoice,
+    entries,
+    keep,
+    replacesConfig,
+  };
+}
+
+export type InitResult = {
+  created: string[];
+  kept: string[];
+};
+
+/** Writes the plan. Existing files are skipped, except the config when the plan replaces it. */
+export async function applyInitPlan(plan: InitPlan): Promise<InitResult> {
+  const created: string[] = [];
+  const kept = [...plan.keep];
+
+  await mkdir(plan.dir, { recursive: true });
+  await ensureStateDir(statePathsFor(plan.dir, plan.layout));
+  for (const entry of plan.entries.filter((e) => e.purpose === "state"))
+    created.push(entry.path);
+
+  for (const entry of plan.entries.filter((e) => e.purpose !== "state")) {
+    if (entry.kind === "dir") {
+      await mkdir(entry.path, { recursive: true });
+      created.push(entry.path);
+      continue;
+    }
+    await mkdir(path.dirname(entry.path), { recursive: true });
+    try {
+      await writeFile(entry.path, entry.content ?? "", {
+        flag: entry.purpose === "config" && plan.replacesConfig ? "w" : "wx",
+      });
+      created.push(entry.path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      kept.push(entry.path);
+    }
+  }
+
+  return { created, kept };
+}
+
+/** The "will create" list shown before anything is written. */
+export function formatInitPlan(plan: InitPlan): string[] {
+  const rel = (target: string) =>
+    path.relative(plan.dir, target).split(path.sep).join("/") || ".";
+  const lines = [
+    `Layout: ${plan.layout} (${plan.layoutReason})`,
+    plan.docsIncluded.length > 0
+      ? `Existing docs are used in place: ${plan.docsIncluded.join(", ")}`
+      : "No existing docs found: a starter page is created.",
+    "Will create:",
+    ...plan.entries
+      .filter((entry) => !(entry.kind === "dir" && entry.purpose === "state"))
+      .map(
+        (entry) =>
+          `  ${rel(entry.path)}${plan.replacesConfig && entry.purpose === "config" ? " (replaces the existing file)" : ""}`,
+      ),
+    `  ${rel(statePathsFor(plan.dir, plan.layout).dir)}/generated/ and build/ (generated state, ignored by git)`,
+  ];
+  if (plan.keep.length > 0) {
+    lines.push(
+      "Will keep as they are:",
+      ...plan.keep.map((target) => `  ${rel(target)}`),
+    );
+  }
+  lines.push(
+    "Your own files are never moved, renamed or edited, and your .gitignore is left alone.",
+  );
+  return lines;
+}