@gitpagedocs/cli 1.1.62 → 1.1.63

package/presentation/commands/diagnostics.ts

@@ -1,164 +1,164 @@
-import path from "node:path";
-import { readFileSync, existsSync } from "node:fs";
-import { execSync } from "node:child_process";
-import { defaultConfigLoader } from "@gitpagedocs/tools";
-import type { CommandContext } from "./run-command";
-
-function readVersion(pkgRoot: string): string {
-  try {
-    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
-    return String(pkg.version ?? "unknown");
-  } catch {
-    return "unknown";
-  }
-}
-
-export async function runVersion(ctx: CommandContext): Promise<void> {
-  // eslint-disable-next-line no-console
-  console.log(`gitpagedocs ${readVersion(ctx.pkgRoot)} (node ${process.version})`);
-}
-
-function probe(label: string, command: string): { label: string; ok: boolean; detail: string } {
-  try {
-    const out = execSync(command, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
-    return { label, ok: true, detail: out.split("\n")[0] };
-  } catch {
-    return { label, ok: false, detail: "not found" };
-  }
-}
-
-export async function runDoctor(ctx: CommandContext): Promise<void> {
-  const checks: Array<{ label: string; ok: boolean; detail: string }> = [];
-  checks.push({ label: "node", ok: true, detail: process.version });
-  checks.push(probe("git", "git --version"));
-  checks.push(probe("gh (GitHub CLI)", "gh --version"));
-  checks.push(probe("pnpm", "pnpm --version"));
-
-  const configPath = await defaultConfigLoader.resolveConfigPath(ctx.cwd);
-  checks.push({
-    label: "gitpagedocs config",
-    ok: Boolean(configPath),
-    detail: configPath ? path.relative(ctx.cwd, configPath) : "not found (run `gitpagedocs init`)",
-  });
-  checks.push({
-    label: "gitpagedocs/ directory",
-    ok: existsSync(path.join(ctx.cwd, "gitpagedocs")),
-    detail: existsSync(path.join(ctx.cwd, "gitpagedocs")) ? "present" : "missing",
-  });
-
-  // eslint-disable-next-line no-console
-  console.log("\n  gitpagedocs doctor\n");
-  for (const c of checks) {
-    // eslint-disable-next-line no-console
-    console.log(`  ${c.ok ? "[ok]" : "[x] "} ${c.label.padEnd(22)} ${c.detail}`);
-  }
-  const failed = checks.filter((c) => !c.ok && c.label !== "gh (GitHub CLI)").length;
-  // eslint-disable-next-line no-console
-  console.log(`\n  ${failed === 0 ? "All required checks passed." : `${failed} check(s) need attention.`}\n`);
-}
-
-/** Used only when package.json is unreadable — the CLI's published name. */
-const FALLBACK_PACKAGE = "@gitpagedocs/cli";
-/** The bin this package installs; shown alongside the package name. */
-const BIN_NAME = "gitpagedocs";
-
-interface PackageIdentity {
-  name: string;
-  version: string;
-}
-
-/**
- * Read the identity from the installed package.json rather than hardcoding it,
- * so the hint always names the package the user actually has. A hardcoded name
- * is how `update` ended up advertising an unpublished package.
- */
-function readPackageIdentity(pkgRoot: string): PackageIdentity {
-  try {
-    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
-    const name = typeof pkg.name === "string" && pkg.name.length > 0 ? pkg.name : FALLBACK_PACKAGE;
-    return { name, version: String(pkg.version ?? "unknown") };
-  } catch {
-    return { name: FALLBACK_PACKAGE, version: "unknown" };
-  }
-}
-
-type RegistryLookup =
-  | { status: "ok"; latest: string }
-  | { status: "missing" }
-  | { status: "unreachable" };
-
-function registryBase(): string {
-  const configured = process.env.npm_config_registry || "https://registry.npmjs.org";
-  return configured.endsWith("/") ? configured.slice(0, -1) : configured;
-}
-
-/** Resolve the dist-tag `latest` for a package. Never throws. */
-async function fetchLatest(name: string, timeoutMs = 6000): Promise<RegistryLookup> {
-  const encoded = name.split("/").map(encodeURIComponent).join("/");
-  try {
-    const response = await fetch(`${registryBase()}/${encoded}/latest`, {
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (response.status === 404) return { status: "missing" };
-    if (!response.ok) return { status: "unreachable" };
-    const body = (await response.json()) as { version?: unknown };
-    if (typeof body.version === "string" && body.version.length > 0) {
-      return { status: "ok", latest: body.version };
-    }
-    return { status: "unreachable" };
-  } catch {
-    return { status: "unreachable" };
-  }
-}
-
-/** Numeric version compare, prerelease suffix ignored. */
-function compareVersions(a: string, b: string): number {
-  const parts = (value: string): number[] =>
-    value.split("-")[0].split(".").map((piece) => Number.parseInt(piece, 10) || 0);
-  const left = parts(a);
-  const right = parts(b);
-  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
-    const diff = (left[i] ?? 0) - (right[i] ?? 0);
-    if (diff !== 0) return diff < 0 ? -1 : 1;
-  }
-  return 0;
-}
-
-export async function runUpdate(ctx: CommandContext): Promise<void> {
-  const { name, version } = readPackageIdentity(ctx.pkgRoot);
-  const lookup = await fetchLatest(name);
-  const label = name === BIN_NAME ? `${BIN_NAME} ${version}` : `${BIN_NAME} ${version}  (${name})`;
-  const lines = ["", `  Installed: ${label}`];
-
-  if (lookup.status === "ok") {
-    lines.push(`  Latest:    ${lookup.latest}`);
-  } else if (lookup.status === "missing") {
-    lines.push(`  Latest:    unavailable — the registry has no published ${name}`);
-  } else {
-    lines.push("  Latest:    unknown — could not reach the npm registry");
-  }
-
-  if (lookup.status === "missing") {
-    lines.push(
-      "",
-      "  Nothing can be installed under that name. If the package was renamed",
-      "  or unpublished, check the current one:",
-      "    https://www.npmjs.com/package/@gitpagedocs/cli",
-    );
-  } else if (lookup.status === "ok" && compareVersions(version, lookup.latest) >= 0) {
-    lines.push("", "  Already on the latest published version.");
-  } else {
-    const target = lookup.status === "ok" ? lookup.latest : "latest";
-    lines.push(
-      "",
-      "  To update the global CLI:",
-      `    npm i -g ${name}@${target}`,
-      "  Or, in a project:",
-      `    pnpm add -D ${name}@${target}`,
-    );
-  }
-
-  lines.push("");
-  // eslint-disable-next-line no-console
-  console.log(lines.join("\n"));
-}
+import path from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { defaultConfigLoader } from "@gitpagedocs/tools";
+import type { CommandContext } from "./run-command";
+
+function readVersion(pkgRoot: string): string {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+    return String(pkg.version ?? "unknown");
+  } catch {
+    return "unknown";
+  }
+}
+
+export async function runVersion(ctx: CommandContext): Promise<void> {
+  // eslint-disable-next-line no-console
+  console.log(`gitpagedocs ${readVersion(ctx.pkgRoot)} (node ${process.version})`);
+}
+
+function probe(label: string, command: string): { label: string; ok: boolean; detail: string } {
+  try {
+    const out = execSync(command, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    return { label, ok: true, detail: out.split("\n")[0] };
+  } catch {
+    return { label, ok: false, detail: "not found" };
+  }
+}
+
+export async function runDoctor(ctx: CommandContext): Promise<void> {
+  const checks: Array<{ label: string; ok: boolean; detail: string }> = [];
+  checks.push({ label: "node", ok: true, detail: process.version });
+  checks.push(probe("git", "git --version"));
+  checks.push(probe("gh (GitHub CLI)", "gh --version"));
+  checks.push(probe("pnpm", "pnpm --version"));
+
+  const configPath = await defaultConfigLoader.resolveConfigPath(ctx.cwd);
+  checks.push({
+    label: "gitpagedocs config",
+    ok: Boolean(configPath),
+    detail: configPath ? path.relative(ctx.cwd, configPath) : "not found (run `gitpagedocs init`)",
+  });
+  checks.push({
+    label: "gitpagedocs/ directory",
+    ok: existsSync(path.join(ctx.cwd, "gitpagedocs")),
+    detail: existsSync(path.join(ctx.cwd, "gitpagedocs")) ? "present" : "missing",
+  });
+
+  // eslint-disable-next-line no-console
+  console.log("\n  gitpagedocs doctor\n");
+  for (const c of checks) {
+    // eslint-disable-next-line no-console
+    console.log(`  ${c.ok ? "[ok]" : "[x] "} ${c.label.padEnd(22)} ${c.detail}`);
+  }
+  const failed = checks.filter((c) => !c.ok && c.label !== "gh (GitHub CLI)").length;
+  // eslint-disable-next-line no-console
+  console.log(`\n  ${failed === 0 ? "All required checks passed." : `${failed} check(s) need attention.`}\n`);
+}
+
+/** Used only when package.json is unreadable — the CLI's published name. */
+const FALLBACK_PACKAGE = "@gitpagedocs/cli";
+/** The bin this package installs; shown alongside the package name. */
+const BIN_NAME = "gitpagedocs";
+
+interface PackageIdentity {
+  name: string;
+  version: string;
+}
+
+/**
+ * Read the identity from the installed package.json rather than hardcoding it,
+ * so the hint always names the package the user actually has. A hardcoded name
+ * is how `update` ended up advertising an unpublished package.
+ */
+function readPackageIdentity(pkgRoot: string): PackageIdentity {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+    const name = typeof pkg.name === "string" && pkg.name.length > 0 ? pkg.name : FALLBACK_PACKAGE;
+    return { name, version: String(pkg.version ?? "unknown") };
+  } catch {
+    return { name: FALLBACK_PACKAGE, version: "unknown" };
+  }
+}
+
+type RegistryLookup =
+  | { status: "ok"; latest: string }
+  | { status: "missing" }
+  | { status: "unreachable" };
+
+function registryBase(): string {
+  const configured = process.env.npm_config_registry || "https://registry.npmjs.org";
+  return configured.endsWith("/") ? configured.slice(0, -1) : configured;
+}
+
+/** Resolve the dist-tag `latest` for a package. Never throws. */
+async function fetchLatest(name: string, timeoutMs = 6000): Promise<RegistryLookup> {
+  const encoded = name.split("/").map(encodeURIComponent).join("/");
+  try {
+    const response = await fetch(`${registryBase()}/${encoded}/latest`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 404) return { status: "missing" };
+    if (!response.ok) return { status: "unreachable" };
+    const body = (await response.json()) as { version?: unknown };
+    if (typeof body.version === "string" && body.version.length > 0) {
+      return { status: "ok", latest: body.version };
+    }
+    return { status: "unreachable" };
+  } catch {
+    return { status: "unreachable" };
+  }
+}
+
+/** Numeric version compare, prerelease suffix ignored. */
+function compareVersions(a: string, b: string): number {
+  const parts = (value: string): number[] =>
+    value.split("-")[0].split(".").map((piece) => Number.parseInt(piece, 10) || 0);
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+export async function runUpdate(ctx: CommandContext): Promise<void> {
+  const { name, version } = readPackageIdentity(ctx.pkgRoot);
+  const lookup = await fetchLatest(name);
+  const label = name === BIN_NAME ? `${BIN_NAME} ${version}` : `${BIN_NAME} ${version}  (${name})`;
+  const lines = ["", `  Installed: ${label}`];
+
+  if (lookup.status === "ok") {
+    lines.push(`  Latest:    ${lookup.latest}`);
+  } else if (lookup.status === "missing") {
+    lines.push(`  Latest:    unavailable — the registry has no published ${name}`);
+  } else {
+    lines.push("  Latest:    unknown — could not reach the npm registry");
+  }
+
+  if (lookup.status === "missing") {
+    lines.push(
+      "",
+      "  Nothing can be installed under that name. If the package was renamed",
+      "  or unpublished, check the current one:",
+      "    https://www.npmjs.com/package/@gitpagedocs/cli",
+    );
+  } else if (lookup.status === "ok" && compareVersions(version, lookup.latest) >= 0) {
+    lines.push("", "  Already on the latest published version.");
+  } else {
+    const target = lookup.status === "ok" ? lookup.latest : "latest";
+    lines.push(
+      "",
+      "  To update the global CLI:",
+      `    npm i -g ${name}@${target}`,
+      "  Or, in a project:",
+      `    pnpm add -D ${name}@${target}`,
+    );
+  }
+
+  lines.push("");
+  // eslint-disable-next-line no-console
+  console.log(lines.join("\n"));
+}

package/presentation/commands/docs.ts

@@ -1,37 +1,37 @@
-import {
-  FileService,
-  DocUpdater,
-  providersSection,
-  cliCommandsSection,
-  devWorkflowSection,
-  securityNoteSection,
-  CLI_COMMANDS,
-} from "@gitpagedocs/tools";
-import type { CommandContext } from "./run-command";
-
-/**
- * `gitpagedocs docs` — refresh the managed regions of the standard docs files
- * with deterministic content. Idempotent and marker-bounded: manual content
- * outside `<!-- gitpagedocs:start/end -->` is preserved; missing files are
- * created. Covers README, CONTRIBUTING and SECURITY (master-spec docs set).
- */
-export async function runDocs(ctx: CommandContext): Promise<void> {
-  const updater = new DocUpdater(new FileService(ctx.cwd));
-
-  const updates = [
-    { path: "README.md", generated: `${providersSection()}\n\n${cliCommandsSection(CLI_COMMANDS)}` },
-    { path: "CONTRIBUTING.md", generated: `${devWorkflowSection()}\n\n${cliCommandsSection(CLI_COMMANDS)}` },
-    { path: "SECURITY.md", generated: securityNoteSection() },
-  ];
-
-  const results = await updater.updateManagedFiles(updates);
-  // eslint-disable-next-line no-console
-  console.log("");
-  for (const r of results) {
-    const state = r.changed ? (r.replaced ? "managed region updated" : "managed region added") : "already up to date";
-    // eslint-disable-next-line no-console
-    console.log(`  ${r.path}: ${state}.`);
-  }
-  // eslint-disable-next-line no-console
-  console.log("");
-}
+import {
+  FileService,
+  DocUpdater,
+  providersSection,
+  cliCommandsSection,
+  devWorkflowSection,
+  securityNoteSection,
+  CLI_COMMANDS,
+} from "@gitpagedocs/tools";
+import type { CommandContext } from "./run-command";
+
+/**
+ * `gitpagedocs docs` — refresh the managed regions of the standard docs files
+ * with deterministic content. Idempotent and marker-bounded: manual content
+ * outside `<!-- gitpagedocs:start/end -->` is preserved; missing files are
+ * created. Covers README, CONTRIBUTING and SECURITY (master-spec docs set).
+ */
+export async function runDocs(ctx: CommandContext): Promise<void> {
+  const updater = new DocUpdater(new FileService(ctx.cwd));
+
+  const updates = [
+    { path: "README.md", generated: `${providersSection()}\n\n${cliCommandsSection(CLI_COMMANDS)}` },
+    { path: "CONTRIBUTING.md", generated: `${devWorkflowSection()}\n\n${cliCommandsSection(CLI_COMMANDS)}` },
+    { path: "SECURITY.md", generated: securityNoteSection() },
+  ];
+
+  const results = await updater.updateManagedFiles(updates);
+  // eslint-disable-next-line no-console
+  console.log("");
+  for (const r of results) {
+    const state = r.changed ? (r.replaced ? "managed region updated" : "managed region added") : "already up to date";
+    // eslint-disable-next-line no-console
+    console.log(`  ${r.path}: ${state}.`);
+  }
+  // eslint-disable-next-line no-console
+  console.log("");
+}

package/presentation/commands/mcp.ts

@@ -1,20 +1,20 @@
-import type { CommandContext } from "./run-command";
-
-/**
- * `gitpagedocs mcp start` — entry point for the MCP server. The server package
- * (@gitpagedocs/mcp) is implemented in Phase 7; this command is wired to launch
- * it there. Until then it reports status honestly rather than failing silently.
- */
-export async function runMcp(ctx: CommandContext): Promise<void> {
-  const sub = ctx.args[1] ?? "start";
-  if (sub !== "start") {
-    // eslint-disable-next-line no-console
-    console.log(`\n  Unknown mcp subcommand: ${sub}\n  Usage: gitpagedocs mcp start\n`);
-    return;
-  }
-  // stderr only: stdout is the MCP stdio channel and must stay protocol-clean.
-  console.error("[gitpagedocs] Starting MCP server over stdio (Ctrl-C to stop)...");
-  // Dynamic import keeps the MCP SDK out of the frontend bundle.
-  const { startMcpServer } = await import("@gitpagedocs/mcp");
-  await startMcpServer(ctx.cwd);
-}
+import type { CommandContext } from "./run-command";
+
+/**
+ * `gitpagedocs mcp start` — entry point for the MCP server. The server package
+ * (@gitpagedocs/mcp) is implemented in Phase 7; this command is wired to launch
+ * it there. Until then it reports status honestly rather than failing silently.
+ */
+export async function runMcp(ctx: CommandContext): Promise<void> {
+  const sub = ctx.args[1] ?? "start";
+  if (sub !== "start") {
+    // eslint-disable-next-line no-console
+    console.log(`\n  Unknown mcp subcommand: ${sub}\n  Usage: gitpagedocs mcp start\n`);
+    return;
+  }
+  // stderr only: stdout is the MCP stdio channel and must stay protocol-clean.
+  console.error("[gitpagedocs] Starting MCP server over stdio (Ctrl-C to stop)...");
+  // Dynamic import keeps the MCP SDK out of the frontend bundle.
+  const { startMcpServer } = await import("@gitpagedocs/mcp");
+  await startMcpServer(ctx.cwd);
+}

package/presentation/commands/pages.ts

@@ -1,101 +1,101 @@
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import type { CommandContext } from "./run-command";
-import { askConfirm } from "../ui/clack";
-import { askOwnerRepo, interactivePromptsAvailable } from "../ui/prompts";
-// @ts-expect-error .mjs runtime module
-import { detectRepoFromGit, getCurrentGitBranch, tryConfigurePagesToGitHubActions } from "../../runtime/git-ops.mjs";
-
-/** Read `--name value` (or `--name=value`) from a raw arg list. */
-function readFlag(args: string[], name: string): string {
-  const eq = args.find((a) => a.startsWith(`${name}=`));
-  if (eq) return eq.slice(name.length + 1).trim();
-  const i = args.indexOf(name);
-  if (i >= 0 && args[i + 1] && !args[i + 1].startsWith("--")) return args[i + 1].trim();
-  return "";
-}
-
-/**
- * `gitpagedocs pages actions` / `--pages-actions` — switch the repository's
- * GitHub Pages source to GitHub Actions. Detects owner/repo/branch from git,
- * validates the gh CLI, and confirms before changing anything (no silent
- * overwrite). Does NOT generate docs or push (that is `pages deploy`).
- */
-export async function runPagesActions(ctx: CommandContext): Promise<void> {
-  let repo = detectRepoFromGit(ctx.cwd) as { owner: string; repo: string } | null;
-  if (!repo) {
-    if (!interactivePromptsAvailable()) {
-      // eslint-disable-next-line no-console
-      console.log("\n  Could not detect a GitHub repo from the git 'origin' remote.\n  Add a remote or use `--push --owner <o> --repo <r>`.\n");
-      return;
-    }
-    repo = await askOwnerRepo(null);
-  }
-  const branch = getCurrentGitBranch(ctx.cwd) as string;
-  // eslint-disable-next-line no-console
-  console.log(`\n  Detected ${repo.owner}/${repo.repo} (branch ${branch}).`);
-  const ok = await askConfirm(`Switch GitHub Pages source to GitHub Actions for ${repo.owner}/${repo.repo}?`, false);
-  if (!ok) {
-    // eslint-disable-next-line no-console
-    console.log("  Aborted. No changes made.\n");
-    return;
-  }
-  tryConfigurePagesToGitHubActions(repo.owner, repo.repo, branch, ctx.cwd);
-}
-
-/**
- * `gitpagedocs pages deploy` — the full documented deploy flow: resolve
- * owner/repo (from --owner/--repo or the git remote), confirm, then run the
- * proven `--push` path (generate docs + workflow → commit → push → configure
- * Pages→Actions) and print the final site URL. Reuses the legacy push verbatim
- * (spawned), so `--push` behavior stays byte-identical.
- */
-export async function runPagesDeploy(ctx: CommandContext): Promise<void> {
-  let owner = readFlag(ctx.args, "--owner");
-  let repo = readFlag(ctx.args, "--repo");
-  const docsPath = readFlag(ctx.args, "--path");
-
-  if (!owner || !repo) {
-    const detected = detectRepoFromGit(ctx.cwd) as { owner: string; repo: string } | null;
-    if (detected) {
-      owner = owner || detected.owner;
-      repo = repo || detected.repo;
-    }
-  }
-  if (!owner || !repo) {
-    if (!interactivePromptsAvailable()) {
-      // eslint-disable-next-line no-console
-      console.log("\n  Could not determine owner/repo. Pass `--owner <o> --repo <r>` or add a git 'origin' remote.\n");
-      return;
-    }
-    const answered = await askOwnerRepo(null, { owner, repo });
-    owner = answered.owner;
-    repo = answered.repo;
-  }
-
-  // eslint-disable-next-line no-console
-  console.log(`\n  Deploy ${owner}/${repo} to GitHub Pages via Actions${docsPath ? ` (path: ${docsPath})` : ""}.`);
-  const ok = await askConfirm(
-    `Generate docs + workflow, commit, push, and switch Pages to Actions for ${owner}/${repo}?`,
-    false,
-  );
-  if (!ok) {
-    // eslint-disable-next-line no-console
-    console.log("  Aborted. No changes made.\n");
-    return;
-  }
-
-  // pkgRoot is the cli package root (cli/), where the bin lives as index.mjs.
-  const bin = path.join(ctx.pkgRoot, "index.mjs");
-  const pushArgs = ["--push", "--owner", owner, "--repo", repo, ...(docsPath ? ["--path", docsPath] : [])];
-  const result = spawnSync(process.execPath, [bin, ...pushArgs], { stdio: "inherit", cwd: ctx.cwd, env: process.env });
-
-  if (result.status === 0) {
-    const seg = docsPath ? `/${docsPath.replace(/^\/+|\/+$/g, "")}` : "";
-    // eslint-disable-next-line no-console
-    console.log(`\n  Deployed. Final URL: https://${owner}.github.io/${repo}${seg}/\n`);
-  } else {
-    // eslint-disable-next-line no-console
-    console.log("\n  Deploy did not complete (push step failed). See output above.\n");
-  }
-}
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import type { CommandContext } from "./run-command";
+import { askConfirm } from "../ui/clack";
+import { askOwnerRepo, interactivePromptsAvailable } from "../ui/prompts";
+// @ts-expect-error .mjs runtime module
+import { detectRepoFromGit, getCurrentGitBranch, tryConfigurePagesToGitHubActions } from "../../runtime/git-ops.mjs";
+
+/** Read `--name value` (or `--name=value`) from a raw arg list. */
+function readFlag(args: string[], name: string): string {
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  if (eq) return eq.slice(name.length + 1).trim();
+  const i = args.indexOf(name);
+  if (i >= 0 && args[i + 1] && !args[i + 1].startsWith("--")) return args[i + 1].trim();
+  return "";
+}
+
+/**
+ * `gitpagedocs pages actions` / `--pages-actions` — switch the repository's
+ * GitHub Pages source to GitHub Actions. Detects owner/repo/branch from git,
+ * validates the gh CLI, and confirms before changing anything (no silent
+ * overwrite). Does NOT generate docs or push (that is `pages deploy`).
+ */
+export async function runPagesActions(ctx: CommandContext): Promise<void> {
+  let repo = detectRepoFromGit(ctx.cwd) as { owner: string; repo: string } | null;
+  if (!repo) {
+    if (!interactivePromptsAvailable()) {
+      // eslint-disable-next-line no-console
+      console.log("\n  Could not detect a GitHub repo from the git 'origin' remote.\n  Add a remote or use `--push --owner <o> --repo <r>`.\n");
+      return;
+    }
+    repo = await askOwnerRepo(null);
+  }
+  const branch = getCurrentGitBranch(ctx.cwd) as string;
+  // eslint-disable-next-line no-console
+  console.log(`\n  Detected ${repo.owner}/${repo.repo} (branch ${branch}).`);
+  const ok = await askConfirm(`Switch GitHub Pages source to GitHub Actions for ${repo.owner}/${repo.repo}?`, false);
+  if (!ok) {
+    // eslint-disable-next-line no-console
+    console.log("  Aborted. No changes made.\n");
+    return;
+  }
+  tryConfigurePagesToGitHubActions(repo.owner, repo.repo, branch, ctx.cwd);
+}
+
+/**
+ * `gitpagedocs pages deploy` — the full documented deploy flow: resolve
+ * owner/repo (from --owner/--repo or the git remote), confirm, then run the
+ * proven `--push` path (generate docs + workflow → commit → push → configure
+ * Pages→Actions) and print the final site URL. Reuses the legacy push verbatim
+ * (spawned), so `--push` behavior stays byte-identical.
+ */
+export async function runPagesDeploy(ctx: CommandContext): Promise<void> {
+  let owner = readFlag(ctx.args, "--owner");
+  let repo = readFlag(ctx.args, "--repo");
+  const docsPath = readFlag(ctx.args, "--path");
+
+  if (!owner || !repo) {
+    const detected = detectRepoFromGit(ctx.cwd) as { owner: string; repo: string } | null;
+    if (detected) {
+      owner = owner || detected.owner;
+      repo = repo || detected.repo;
+    }
+  }
+  if (!owner || !repo) {
+    if (!interactivePromptsAvailable()) {
+      // eslint-disable-next-line no-console
+      console.log("\n  Could not determine owner/repo. Pass `--owner <o> --repo <r>` or add a git 'origin' remote.\n");
+      return;
+    }
+    const answered = await askOwnerRepo(null, { owner, repo });
+    owner = answered.owner;
+    repo = answered.repo;
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`\n  Deploy ${owner}/${repo} to GitHub Pages via Actions${docsPath ? ` (path: ${docsPath})` : ""}.`);
+  const ok = await askConfirm(
+    `Generate docs + workflow, commit, push, and switch Pages to Actions for ${owner}/${repo}?`,
+    false,
+  );
+  if (!ok) {
+    // eslint-disable-next-line no-console
+    console.log("  Aborted. No changes made.\n");
+    return;
+  }
+
+  // pkgRoot is the cli package root (cli/), where the bin lives as index.mjs.
+  const bin = path.join(ctx.pkgRoot, "index.mjs");
+  const pushArgs = ["--push", "--owner", owner, "--repo", repo, ...(docsPath ? ["--path", docsPath] : [])];
+  const result = spawnSync(process.execPath, [bin, ...pushArgs], { stdio: "inherit", cwd: ctx.cwd, env: process.env });
+
+  if (result.status === 0) {
+    const seg = docsPath ? `/${docsPath.replace(/^\/+|\/+$/g, "")}` : "";
+    // eslint-disable-next-line no-console
+    console.log(`\n  Deployed. Final URL: https://${owner}.github.io/${repo}${seg}/\n`);
+  } else {
+    // eslint-disable-next-line no-console
+    console.log("\n  Deploy did not complete (push step failed). See output above.\n");
+  }
+}