@gitpagedocs/cli 1.1.61 → 1.1.63

package/presentation/options/parser.ts

@@ -1,104 +1,119 @@
-import type { CliOptions } from "../../domain/models/cli-options";
-import { DEFAULTS } from "./schema";
-
-const KNOWN_FLAGS = new Set([
-  "--build",
-  "--serve",
-  "--layoutconfig",
-  "--full",
-  "--push",
-  "--home",
-  "--search",
-  "--path",
-  "--output",
-  "--interactive",
-  "-i",
-  "--ai",
-  "--pages-actions",
-]);
-
-function readOptionValue(args: string[], optionName: string): string {
-  const equalsArg = args.find((a) => a.startsWith(`${optionName}=`));
-  if (equalsArg) return equalsArg.slice(optionName.length + 1).trim();
-  const index = args.indexOf(optionName);
-  if (index >= 0) {
-    const next = args[index + 1];
-    if (next && !next.startsWith("--")) return next.trim();
-  }
-  return "";
-}
-
-export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOptions {
-  const args = argv.slice(2);
-
-  let githubOwner = readOptionValue(args, "--owner");
-  let githubRepo = readOptionValue(args, "--repo");
-  const docsPath = readOptionValue(args, "--path");
-  const outputDir = readOptionValue(args, "--output");
-  const searchRaw = readOptionValue(args, "--search");
-
-  const fallbackDashedArgs = args
-    .filter((a) => a.startsWith("--"))
-    .filter((a) => !KNOWN_FLAGS.has(a))
-    .filter((a) => !a.startsWith("--owner"))
-    .filter((a) => !a.startsWith("--repo"))
-    .filter((a) => !a.startsWith("--path"))
-    .filter((a) => !a.startsWith("--home"))
-    .filter((a) => !a.startsWith("--output"))
-    .filter((a) => !a.startsWith("--search"))
-    .map((a) => a.replace(/^--/, "").trim())
-    .filter(Boolean);
-
-  if (!githubOwner && fallbackDashedArgs[0]) githubOwner = fallbackDashedArgs[0];
-  if (!githubRepo && fallbackDashedArgs[1]) githubRepo = fallbackDashedArgs[1];
-
-  // New verb aliases (Phase 6) that map onto existing modes without new modes.
-  const command = args[0];
-  const isDocument = command === "document" || (command?.startsWith("document:") ?? false);
-  const isDeploy = command === "deploy" || command === "pages";
-
-  const isBuild = args.includes("--build") || env.GITPAGEDOCS_BUILD === "1";
-  const isServe = args.includes("--serve");
-  const useLocalLayoutConfig = args.includes("--layoutconfig");
-  const shouldPush = args.includes("--push") || isDeploy;
-  const isHome = args.includes("--home");
-  const isInteractive = args.includes("--interactive") || args.includes("-i");
-  const isAi = command === "ai" || args.includes("--ai") || isDocument;
-  const aiCommand =
-    command === "ai"
-      ? args[1]
-      : command === "document"
-        ? args[1] ?? "repo"
-        : command?.startsWith("document:")
-          ? command.split(":")[1]
-          : undefined;
-
-  const mode: import("../../domain/models/cli-options").CliMode = isAi ? "ai" : isHome ? "home" : args.includes("--full") ? "full" : "config-only";
-  const repositorySearch =
-    searchRaw === "true"
-      ? true
-      : searchRaw === "false"
-        ? false
-        : isHome
-          ? DEFAULTS.home.repositorySearch
-          : undefined;
-
-  const normalizedPath = docsPath.trim();
-
-  return {
-    isBuild,
-    isServe,
-    mode,
-    aiCommand,
-    outputDir: outputDir || (isHome ? DEFAULTS.home.outputDir : DEFAULTS.outputDir),
-    useLocalLayoutConfig,
-    shouldPush,
-    githubOwner,
-    githubRepo,
-    docsPath: normalizedPath,
-    basePath: normalizedPath,
-    repositorySearch,
-    isInteractive,
-    hasArgs: args.length > 0,
-  };
-}
+import type { CliOptions } from "../../domain/models/cli-options";
+import { DEFAULTS } from "./schema";
+import { normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
+
+const KNOWN_FLAGS = new Set([
+  "--build",
+  "--serve",
+  "--layoutconfig",
+  "--full",
+  "--push",
+  "--home",
+  "--search",
+  "--path",
+  "--output",
+  "--layouts-dir",
+  "--interactive",
+  "-i",
+  "--no-interactive",
+  "--yes",
+  "-y",
+  "--ai",
+  "--pages-actions",
+]);
+
+function readOptionValue(args: string[], optionName: string): string {
+  const equalsArg = args.find((a) => a.startsWith(`${optionName}=`));
+  if (equalsArg) return equalsArg.slice(optionName.length + 1).trim();
+  const index = args.indexOf(optionName);
+  if (index >= 0) {
+    const next = args[index + 1];
+    if (next && !next.startsWith("--")) return next.trim();
+  }
+  return "";
+}
+
+export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOptions {
+  const args = argv.slice(2);
+
+  let githubOwner = readOptionValue(args, "--owner");
+  let githubRepo = readOptionValue(args, "--repo");
+  const docsPath = readOptionValue(args, "--path");
+  const outputDir = readOptionValue(args, "--output");
+  const layoutsDir = readOptionValue(args, "--layouts-dir");
+  const searchRaw = readOptionValue(args, "--search");
+
+  const fallbackDashedArgs = args
+    .filter((a) => a.startsWith("--"))
+    .filter((a) => !KNOWN_FLAGS.has(a))
+    .filter((a) => !a.startsWith("--owner"))
+    .filter((a) => !a.startsWith("--repo"))
+    .filter((a) => !a.startsWith("--path"))
+    .filter((a) => !a.startsWith("--home"))
+    .filter((a) => !a.startsWith("--output"))
+    .filter((a) => !a.startsWith("--layouts-dir"))
+    .filter((a) => !a.startsWith("--search"))
+    .map((a) => a.replace(/^--/, "").trim())
+    .filter(Boolean);
+
+  if (!githubOwner && fallbackDashedArgs[0]) githubOwner = fallbackDashedArgs[0];
+  if (!githubRepo && fallbackDashedArgs[1]) githubRepo = fallbackDashedArgs[1];
+
+  // New verb aliases (Phase 6) that map onto existing modes without new modes.
+  const command = args[0];
+  const isDocument = command === "document" || (command?.startsWith("document:") ?? false);
+  const isDeploy = command === "deploy" || command === "pages";
+
+  const isBuild = args.includes("--build") || env.GITPAGEDOCS_BUILD === "1";
+  const isServe = args.includes("--serve");
+  const useLocalLayoutConfig = args.includes("--layoutconfig");
+  const shouldPush = args.includes("--push") || isDeploy;
+  const isHome = args.includes("--home");
+  const isInteractive = args.includes("--interactive") || args.includes("-i");
+  const isAi = command === "ai" || args.includes("--ai") || isDocument;
+  const aiCommand =
+    command === "ai"
+      ? args[1]
+      : command === "document"
+        ? args[1] ?? "repo"
+        : command?.startsWith("document:")
+          ? command.split(":")[1]
+          : undefined;
+
+  const mode: import("../../domain/models/cli-options").CliMode = isAi ? "ai" : isHome ? "home" : args.includes("--full") ? "full" : "config-only";
+  const repositorySearch =
+    searchRaw === "true"
+      ? true
+      : searchRaw === "false"
+        ? false
+        : isHome
+          ? DEFAULTS.home.repositorySearch
+          : undefined;
+
+  const normalizedPath = docsPath.trim();
+
+  return {
+    isBuild,
+    isServe,
+    mode,
+    aiCommand,
+    outputDir: outputDir || (isHome ? DEFAULTS.home.outputDir : DEFAULTS.outputDir),
+    layoutsDir: normalizeLayoutsDir(layoutsDir || DEFAULTS.layoutsDir),
+    useLocalLayoutConfig,
+    shouldPush,
+    githubOwner,
+    githubRepo,
+    docsPath: normalizedPath,
+    basePath: normalizedPath,
+    repositorySearch,
+    isInteractive,
+    hasArgs: args.length > 0,
+    explicit: {
+      useLocalLayoutConfig,
+      layoutsDir: Boolean(layoutsDir),
+      githubOwner: Boolean(githubOwner),
+      githubRepo: Boolean(githubRepo),
+      outputDir: Boolean(outputDir),
+    },
+  };
+}

package/presentation/options/resolver.ts

@@ -1,48 +1,46 @@
-import type { CliOptions } from "../../domain/models/cli-options";
-import { parseCliOptions } from "./parser";
-import {
-  shouldRunInteractive,
-  promptConfigOnlyOptions,
-  promptHomeOptions,
-  promptDeployOptions,
-  ensureGitRepoInteractive,
-  interactivePromptsAvailable,
-} from "../ui/prompts";
-import { DEFAULTS } from "./schema";
-// @ts-expect-error .mjs runtime module is type-less in this package.
-import { detectRepoFromGit } from "../../runtime/git-ops.mjs";
-
-export async function resolveOptions(argv: string[], env: NodeJS.ProcessEnv): Promise<CliOptions> {
-  const parsed = parseCliOptions(argv, env);
-
-  if (parsed.mode === "home") {
-    parsed.repositorySearch = parsed.repositorySearch ?? DEFAULTS.home.repositorySearch;
-    parsed.basePath = parsed.basePath ?? parsed.docsPath ?? DEFAULTS.home.basePath;
-  }
-
-  // `deploy` / `--push` need owner + repo AND a git repo. If anything is
-  // missing, prompt interactively (owner/repo pre-filled from the git origin
-  // remote; offer to `git init`) instead of throwing. In CI/non-TTY we fall
-  // through so the explicit guards in the push flow still fire clearly.
-  if (parsed.shouldPush && interactivePromptsAvailable()) {
-    let resolved = parsed;
-    if (!parsed.githubOwner || !parsed.githubRepo) {
-      const detected = detectRepoFromGit(process.cwd()) as { owner: string; repo: string } | null;
-      resolved = await promptDeployOptions(parsed, detected);
-    }
-    await ensureGitRepoInteractive(process.cwd());
-    return resolved;
-  }
-
-  const runHomeInteractive = parsed.isInteractive || (shouldRunInteractive(argv) && parsed.mode === "home");
-  if (runHomeInteractive && parsed.mode === "home") {
-    return promptHomeOptions(parsed);
-  }
-
-  const runConfigInteractive = parsed.isInteractive || (shouldRunInteractive(argv) && parsed.mode === "config-only");
-  if (runConfigInteractive && parsed.mode === "config-only") {
-    return promptConfigOnlyOptions(parsed);
-  }
-
-  return parsed;
-}
+import type { CliOptions } from "../../domain/models/cli-options";
+import { parseCliOptions } from "./parser";
+import {
+  shouldRunInteractive,
+  promptConfigOnlyOptions,
+  promptHomeOptions,
+  promptDeployOptions,
+  ensureGitRepoInteractive,
+  interactivePromptsAvailable,
+} from "../ui/prompts";
+import { DEFAULTS } from "./schema";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { detectRepoFromGit } from "../../runtime/git-ops.mjs";
+
+export async function resolveOptions(argv: string[], env: NodeJS.ProcessEnv): Promise<CliOptions> {
+  const parsed = parseCliOptions(argv, env);
+
+  if (parsed.mode === "home") {
+    parsed.repositorySearch = parsed.repositorySearch ?? DEFAULTS.home.repositorySearch;
+    parsed.basePath = parsed.basePath ?? parsed.docsPath ?? DEFAULTS.home.basePath;
+  }
+
+  // `deploy` / `--push` need owner + repo AND a git repo. If anything is
+  // missing, prompt interactively (owner/repo pre-filled from the git origin
+  // remote; offer to `git init`) instead of throwing. In CI/non-TTY we fall
+  // through so the explicit guards in the push flow still fire clearly.
+  if (parsed.shouldPush && interactivePromptsAvailable()) {
+    let resolved = parsed;
+    if (!parsed.githubOwner || !parsed.githubRepo) {
+      const detected = detectRepoFromGit(process.cwd()) as { owner: string; repo: string } | null;
+      resolved = await promptDeployOptions(parsed, detected);
+    }
+    await ensureGitRepoInteractive(process.cwd());
+    return resolved;
+  }
+
+  // Every command prompts in a real terminal; shouldRunInteractive owns the
+  // CI / piped-stdin / --no-interactive opt-outs, and each prompt asks only for
+  // what the command line left unanswered.
+  if (!shouldRunInteractive(argv)) return parsed;
+
+  if (parsed.mode === "home") return promptHomeOptions(parsed);
+  if (parsed.mode === "config-only") return promptConfigOnlyOptions(parsed);
+
+  return parsed;
+}

package/presentation/options/schema.ts

@@ -1,5 +1,9 @@
+import { DEFAULT_LAYOUTS_DIR } from "../../contracts/layouts-paths.mjs";
+
 export const DEFAULTS = {
   outputDir: "gitpagedocs",
+  /** Standalone layouts home; local layouts are generated here, never in outputDir. */
+  layoutsDir: DEFAULT_LAYOUTS_DIR as string,
   repositorySearch: false,
   basePath: "",
   home: {

package/presentation/ui/clack.ts

@@ -1,91 +1,91 @@
-/**
- * Thin, cancellation-aware wrappers over @clack/prompts. Centralizes the
- * isCancel handling so prompt modules stay declarative and a Ctrl-C exits
- * cleanly (mirroring the previous inquirer behaviour).
- */
-import {
-  text,
-  password,
-  confirm,
-  select,
-  multiselect,
-  isCancel,
-  cancel,
-} from "@clack/prompts";
-
-function exitIfCancelled<T>(value: T | symbol): T {
-  if (isCancel(value)) {
-    cancel("Operation cancelled.");
-    process.exit(0);
-  }
-  return value as T;
-}
-
-export interface AskTextOptions {
-  message: string;
-  defaultValue?: string;
-  placeholder?: string;
-  validate?: (value: string) => string | undefined;
-}
-
-export async function askText(options: AskTextOptions): Promise<string> {
-  const result = await text({
-    message: options.message,
-    placeholder: options.placeholder,
-    defaultValue: options.defaultValue,
-    initialValue: undefined,
-    validate: options.validate
-      ? (value) => options.validate?.(value ?? "")
-      : undefined,
-  });
-  return exitIfCancelled(result);
-}
-
-export interface AskPasswordOptions {
-  message: string;
-  validate?: (value: string) => string | undefined;
-}
-
-/** Masked password prompt (input hidden as the user types). */
-export async function askPassword(options: AskPasswordOptions): Promise<string> {
-  const result = await password({
-    message: options.message,
-    validate: options.validate
-      ? (value) => options.validate?.(value ?? "")
-      : undefined,
-  });
-  return exitIfCancelled(result);
-}
-
-export async function askConfirm(message: string, initialValue = false): Promise<boolean> {
-  const result = await confirm({ message, initialValue });
-  return exitIfCancelled(result);
-}
-
-export interface Choice<T extends string> {
-  value: T;
-  label: string;
-  hint?: string;
-}
-
-export async function askSelect<T extends string>(
-  message: string,
-  options: Choice<T>[],
-  initialValue?: T,
-): Promise<T> {
-  // clack's Option<Value> is a conditional type TS can't match against a generic
-  // Choice<T> (identical shape); cast at the boundary, inference flows from initialValue.
-  const result = await select<T>({ message, options: options as never, initialValue });
-  return exitIfCancelled(result);
-}
-
-export async function askMultiSelect<T extends string>(
-  message: string,
-  options: Choice<T>[],
-  initialValues?: T[],
-): Promise<T[]> {
-  const result = await multiselect<T>({ message, options: options as never, initialValues, required: true });
-  return exitIfCancelled(result);
-}
-
-export { intro, outro, note, spinner } from "@clack/prompts";
+/**
+ * Thin, cancellation-aware wrappers over @clack/prompts. Centralizes the
+ * isCancel handling so prompt modules stay declarative and a Ctrl-C exits
+ * cleanly (mirroring the previous inquirer behaviour).
+ */
+import {
+  text,
+  password,
+  confirm,
+  select,
+  multiselect,
+  isCancel,
+  cancel,
+} from "@clack/prompts";
+
+function exitIfCancelled<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel("Operation cancelled.");
+    process.exit(0);
+  }
+  return value as T;
+}
+
+export interface AskTextOptions {
+  message: string;
+  defaultValue?: string;
+  placeholder?: string;
+  validate?: (value: string) => string | undefined;
+}
+
+export async function askText(options: AskTextOptions): Promise<string> {
+  const result = await text({
+    message: options.message,
+    placeholder: options.placeholder,
+    defaultValue: options.defaultValue,
+    initialValue: undefined,
+    validate: options.validate
+      ? (value) => options.validate?.(value ?? "")
+      : undefined,
+  });
+  return exitIfCancelled(result);
+}
+
+export interface AskPasswordOptions {
+  message: string;
+  validate?: (value: string) => string | undefined;
+}
+
+/** Masked password prompt (input hidden as the user types). */
+export async function askPassword(options: AskPasswordOptions): Promise<string> {
+  const result = await password({
+    message: options.message,
+    validate: options.validate
+      ? (value) => options.validate?.(value ?? "")
+      : undefined,
+  });
+  return exitIfCancelled(result);
+}
+
+export async function askConfirm(message: string, initialValue = false): Promise<boolean> {
+  const result = await confirm({ message, initialValue });
+  return exitIfCancelled(result);
+}
+
+export interface Choice<T extends string> {
+  value: T;
+  label: string;
+  hint?: string;
+}
+
+export async function askSelect<T extends string>(
+  message: string,
+  options: Choice<T>[],
+  initialValue?: T,
+): Promise<T> {
+  // clack's Option<Value> is a conditional type TS can't match against a generic
+  // Choice<T> (identical shape); cast at the boundary, inference flows from initialValue.
+  const result = await select<T>({ message, options: options as never, initialValue });
+  return exitIfCancelled(result);
+}
+
+export async function askMultiSelect<T extends string>(
+  message: string,
+  options: Choice<T>[],
+  initialValues?: T[],
+): Promise<T[]> {
+  const result = await multiselect<T>({ message, options: options as never, initialValues, required: true });
+  return exitIfCancelled(result);
+}
+
+export { intro, outro, note, spinner } from "@clack/prompts";

package/presentation/ui/layouts-prompts.ts

@@ -0,0 +1,124 @@
+/**
+ * Layout-related prompts: where layouts come from, where they are written, and
+ * the opt-in migration away from the legacy `<outputDir>/layouts/` folder.
+ */
+import path from "node:path";
+import { askConfirm, askSelect, askText, note } from "./clack";
+import { interactivePromptsAvailable } from "./tty";
+import {
+  DEFAULT_LAYOUTS_DIR,
+  normalizeLayoutsDir,
+  legacyLayoutsDir,
+} from "../../contracts/layouts-paths.mjs";
+import { planLayoutsMigration } from "../../domain/services/layouts-migration.mjs";
+import { listFilesRecursively, executeLayoutsMigration } from "../../runtime/layouts-migrator.mjs";
+
+type LayoutsSource = "official" | "local";
+
+/** Outcome of a completed migration, for the caller to report. */
+export interface LayoutsMigrationOutcome {
+  from: string;
+  to: string;
+  movedCount: number;
+}
+
+/** Ask whether layouts come from the official remote source or a local folder. */
+export async function askLayoutsSource(useLocal: boolean): Promise<boolean> {
+  const choice = await askSelect<LayoutsSource>(
+    "Layout source",
+    [
+      {
+        value: "official",
+        label: "Official layouts (remote)",
+        hint: "nothing is written to your repository",
+      },
+      {
+        value: "local",
+        label: "Local layouts",
+        hint: `generated into ${DEFAULT_LAYOUTS_DIR}/`,
+      },
+    ],
+    useLocal ? "local" : "official",
+  );
+  return choice === "local";
+}
+
+/** Ask which folder should hold the generated layouts. */
+export async function askLayoutsDir(current: string): Promise<string> {
+  const answer = await askText({
+    message: "Layouts folder:",
+    defaultValue: normalizeLayoutsDir(current),
+    validate: (value) => (value.trim() ? undefined : "A folder name is required."),
+  });
+  return normalizeLayoutsDir(answer);
+}
+
+function toAbsolute(root: string, repoRelative: string): string {
+  return path.join(root, ...repoRelative.split("/"));
+}
+
+/**
+ * Offer to move layouts left behind in the legacy folder.
+ *
+ * Nothing is moved without an explicit confirmation. Outside a TTY the legacy
+ * folder is reported and left alone — the viewer still reads it, so declining
+ * (or automating) never breaks an existing site.
+ *
+ * @returns The outcome when files were moved, otherwise `null`.
+ */
+export async function migrateLegacyLayoutsInteractive(
+  root: string,
+  options: { outputDir: string; layoutsDir: string },
+): Promise<LayoutsMigrationOutcome | null> {
+  const from = legacyLayoutsDir(options.outputDir);
+  const to = normalizeLayoutsDir(options.layoutsDir);
+
+  const plan = planLayoutsMigration({
+    outputDir: options.outputDir,
+    layoutsDir: to,
+    legacyFiles: listFilesRecursively(toAbsolute(root, from)),
+    targetFiles: listFilesRecursively(toAbsolute(root, to)),
+  });
+
+  if (!plan.required) return null;
+
+  if (!interactivePromptsAvailable()) {
+    note(
+      `${plan.files.length} layout file(s) still live in ${plan.from}/.\n` +
+        `The viewer still reads them. Run this in a terminal to move them to ${plan.to}/.`,
+      "Legacy layouts",
+    );
+    return null;
+  }
+
+  const overwriteWarning =
+    plan.overwrites.length > 0
+      ? `\n${plan.overwrites.length} file(s) already in ${plan.to}/ would be replaced.`
+      : "";
+  note(
+    `Found ${plan.files.length} layout file(s) in ${plan.from}/.\n` +
+      `Layouts are now generated in ${plan.to}/.${overwriteWarning}`,
+    "Legacy layouts",
+  );
+
+  const confirmed = await askConfirm(
+    `Move them to ${plan.to}/ now?`,
+    plan.overwrites.length === 0,
+  );
+  if (!confirmed) {
+    note(`Left untouched — the viewer still reads ${plan.from}/.`, "Legacy layouts");
+    return null;
+  }
+
+  const result = executeLayoutsMigration(root, plan);
+
+  if (result.failed.length > 0) {
+    note(
+      `${result.failed.length} file(s) could not be moved:\n` +
+        result.failed.map((entry) => `- ${entry.file}: ${entry.reason}`).join("\n"),
+      "Migration incomplete",
+    );
+  }
+
+  return { from: plan.from, to: plan.to, movedCount: result.moved.length };
+}