@portosaur/cli 0.1.0

package/src/utils/interaction.mjs

@@ -0,0 +1,24 @@
+/**
+ * Determines if the CLI should run in interactive mode based on provided options.
+ *
+ * Providing any configuration flag forces non-interactive mode.
+ *
+ * @param {Object} options - Command options (flags).
+ * @returns {boolean}
+ */
+export function isInteractive(options = {}) {
+  // Flags that trigger non-interactive mode
+  const hasConfigOptions = Object.keys(options).some((key) => {
+    if (key === "install") {
+      return false;
+    }
+    return options[key] !== undefined && options[key] !== null;
+  });
+
+  if (hasConfigOptions) {
+    return false;
+  }
+
+  // Otherwise, default to interactive
+  return true;
+}

package/src/utils/packageManager.mjs

@@ -0,0 +1,85 @@
+/**
+ * Package manager detection and CLI utility (ESM)
+ */
+import fs from "fs";
+import path from "path";
+
+/**
+ * Returns a package manager object for the given directory.
+ * Detects by lockfile, environment, or runtime.
+ * @param {string} dir - The directory to check.
+ * @returns {{ name: string, install: string, run: string, exec: string }} Package manager info.
+ */
+export function getPackageManager(dir) {
+  let name = null;
+
+  // Detect by lockfile
+  if (
+    fs.existsSync(path.join(dir, "bun.lock")) ||
+    fs.existsSync(path.join(dir, "bun.lockb"))
+  ) {
+    name = "bun";
+  } else if (fs.existsSync(path.join(dir, "pnpm-lock.yaml"))) {
+    name = "pnpm";
+  } else if (fs.existsSync(path.join(dir, "yarn.lock"))) {
+    name = "yarn";
+  } else if (fs.existsSync(path.join(dir, "package-lock.json"))) {
+    name = "npm";
+  }
+
+  // Detect by environment
+  else if (process.env.npm_config_user_agent) {
+    if (process.env.npm_config_user_agent.includes("bun")) name = "bun";
+    else if (process.env.npm_config_user_agent.includes("pnpm")) name = "pnpm";
+    else if (process.env.npm_config_user_agent.includes("yarn")) name = "yarn";
+    else if (process.env.npm_config_user_agent.includes("npm")) name = "npm";
+  }
+
+  // Detect by runtime
+  else if (typeof process !== "undefined" && process.versions?.bun) {
+    name = "bun";
+  }
+
+  if (!name) {
+    throw new Error(
+      "Supported package manager (bun, pnpm, yarn, or npm) not detected.",
+    );
+  }
+
+  const exec = { npm: "npx", bun: "bunx", pnpm: "pnpm dlx", yarn: "yarn dlx" }[
+    name
+  ];
+
+  return { name, install: `${name} install`, run: `${name} run`, exec };
+}
+
+/**
+ * Resolves the command to run Docusaurus based on the package manager and project state.
+ * @param {string} UserRoot - The project root directory.
+ * @returns {{ command: string, args: string[], packageManager: string }} Docusaurus command info.
+ */
+export function getDocuCmd(UserRoot) {
+  const pm = getPackageManager(UserRoot);
+
+  // Check for node_modules/.bin/docusaurus
+  const localDocusaurus = path.join(
+    UserRoot,
+    "node_modules",
+    ".bin",
+    "docusaurus",
+  );
+
+  if (fs.existsSync(localDocusaurus)) {
+    const local = {
+      bun: { command: "bun", args: ["docusaurus"] },
+      npm: { command: "npm", args: ["run", "docusaurus", "--"] },
+      pnpm: { command: "pnpm", args: ["docusaurus"] },
+      yarn: { command: "yarn", args: ["docusaurus"] },
+    }[pm.name];
+
+    return { ...local, packageManager: pm.name };
+  }
+
+  // Fallback to npx/bunx if not found locally
+  return { command: pm.exec, args: ["docusaurus"], packageManager: pm.name };
+}

package/src/utils/paths.mjs

@@ -0,0 +1,33 @@
+import path from "node:path";
+
+const srcDir = path.resolve(import.meta.dirname, "../");
+const pkgDir = path.resolve(srcDir, "../");
+
+/**
+ * Centralized paths for the CLI package.
+ */
+export const Paths = {
+  /** CLI package root. */
+  root: pkgDir,
+
+  /** CLI src directory. */
+  src: srcDir,
+
+  /** CLI templates directory. */
+  templates: path.join(srcDir, "templates"),
+
+  /** Registry file. */
+  registry: path.join(srcDir, "templates/registry.yml"),
+
+  /** Workflows directory. */
+  workflows: path.join(srcDir, "templates/workflows"),
+
+  /** CLI's package.json file. */
+  packageJson: path.join(pkgDir, "package.json"),
+
+  /** Absolute path to the core package. */
+  core: path.resolve(pkgDir, "../core"),
+
+  /** Absolute path to the theme package. */
+  theme: path.resolve(pkgDir, "../theme"),
+};

package/src/utils/platforms.mjs

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Paths } from "./paths.mjs";
+
+/**
+ * Resolves a platform key from a name or ID.
+ * Supports exact match, case-insensitive ID match, and case-insensitive name match.
+ * @param {Object} platforms - The platforms registry object.
+ * @param {string} platform - The platform name or ID to resolve.
+ * @returns {string|null} The resolved platform key or null if not found.
+ */
+export function resolvePlatformKey(platforms, platform) {
+  if (typeof platform !== "string") {
+    return null;
+  }
+
+  const requested = platform.trim();
+
+  if (!requested) {
+    return null;
+  }
+
+  const requestedLower = requested.toLowerCase();
+
+  // Resolve by direct key match (case-sensitive first)
+  if (Object.prototype.hasOwnProperty.call(platforms, requested)) {
+    return requested;
+  }
+
+  // Resolve by case-insensitive ID
+  const idMatch = Object.keys(platforms).find(
+    (key) => key.toLowerCase() === requestedLower,
+  );
+  if (idMatch) {
+    return idMatch;
+  }
+
+  // Resolve by display name
+  const nameMatch = Object.keys(platforms).find(
+    (key) => platforms[key].name?.toLowerCase() === requestedLower,
+  );
+  if (nameMatch) return nameMatch;
+
+  return null;
+}
+
+/**
+ * Attempts to guess the VCS username from git configuration.
+ * @param {string} vcsProviderId - The ID of the VCS provider (e.g., 'github').
+ * @param {Record<string, string>} [gitConfig={}] - The current git configuration object.
+ * @returns {string} The guessed username or an empty string.
+ */
+export function getPlatformUserGuess(vcsProviderId, gitConfig = {}) {
+  const vcsProvider = vcsProviderId?.toLowerCase();
+
+  const keysByProvider = {
+    github: ["github.user"],
+    gitlab: ["gitlab.user"],
+    codeberg: ["codeberg.user", "forgejo.user"],
+  };
+
+  const hostByProvider = {
+    github: "github.com",
+    gitlab: "gitlab.com",
+    codeberg: "codeberg.org",
+    sourcehut: "git.sr.ht",
+  };
+
+  // Try explicit configuration first
+  for (const key of keysByProvider[vcsProvider] || []) {
+    if (gitConfig[key]) return gitConfig[key];
+  }
+
+  // Fallback to remote URL parsing
+  const host = hostByProvider[vcsProvider];
+
+  if (!host) {
+    return "";
+  }
+
+  for (const [key, value] of Object.entries(gitConfig)) {
+    // Only look at remote URLs
+    if (!key.startsWith("remote.") || !key.endsWith(".url")) continue;
+    if (typeof value !== "string" || !value.includes(host)) continue;
+
+    const escapedHost = host.replace(/\./g, "\\.");
+    const match = value.match(
+      new RegExp(
+        `(?:https?://|ssh://git@|git@)${escapedHost}[:/]([^/]+)(?:/|$)`,
+      ),
+    );
+
+    if (match?.[1]) return match[1];
+  }
+
+  return "";
+}
+
+/**
+ * Dynamically discovers all possible workflow markers (files/dirs) from all available templates.
+ * @param {Object} registry - The platforms registry object.
+ * @returns {string[]} An array of unique file/directory names that serve as CI markers.
+ */
+export function getWorkflowMarkers(registry) {
+  const markers = new Set();
+  const platforms = Object.values(registry.hosting_platforms || {});
+
+  for (const platform of platforms) {
+    const templates =
+      typeof platform.template_dir === "string"
+        ? [platform.template_dir]
+        : Object.values(platform.template_dir || {});
+
+    for (const template of templates) {
+      const templatePath = path.join(Paths.workflows, template);
+
+      if (fs.existsSync(templatePath)) {
+        const contents = fs.readdirSync(templatePath);
+
+        for (const item of contents) {
+          if (item !== "." && item !== "..") {
+            markers.add(item);
+          }
+        }
+      }
+    }
+  }
+
+  return Array.from(markers);
+}

package/src/utils/projectName.mjs

@@ -0,0 +1,20 @@
+export function looksLikeTestProject(projectName) {
+  const testTerms = [
+    "test",
+    "testing",
+    "spec",
+    "specs",
+    "ci",
+    "demo",
+    "example",
+  ];
+  const n = String(projectName).toLowerCase();
+
+  if (!projectName) {
+    return false;
+  }
+
+  return testTerms.some((t) => n.includes(t));
+}
+
+export default looksLikeTestProject;

package/src/utils/runner.mjs

@@ -0,0 +1,192 @@
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+
+/**
+ * Generates a Docusaurus config shim that loads Portosaur logic.
+ * @param {string} UserRoot - The user's project directory.
+ * @param {Object} portoPaths - Paths to Portosaur assets and core.
+ * @param {Object} [context={}] - Additional context for config generation.
+ * @returns {string} The path to the generated shim file.
+ */
+export function writeConfigShim(UserRoot, portoPaths, context = {}) {
+  const dotDir = path.join(UserRoot, ".docusaurus", "portosaur");
+
+  if (!fs.existsSync(dotDir)) {
+    fs.mkdirSync(dotDir, { recursive: true });
+  }
+
+  // Resolve config file
+  const configYaml = ["config.yaml", "config.yml"].find((file) =>
+    fs.existsSync(path.join(UserRoot, file)),
+  );
+  if (!configYaml) throw new Error("config.yml not found");
+
+  const configYamlAbsolute = path
+    .resolve(UserRoot, configYaml)
+    .replace(/\\/g, "/");
+
+  // Prepare shim template
+  const shimContent = `// Auto-generated by portosaur
+import fs from "fs";
+import yaml from "js-yaml";
+
+export default async function getConfig() {
+  const { buildDocuConfig } = await import("@portosaur/core");
+  const yamlContent = fs.readFileSync("${configYamlAbsolute}", "utf8");
+  const rawConf = yaml.load(yamlContent);
+
+  return buildDocuConfig(rawConf, "${UserRoot.replace(/\\/g, "/")}", {
+    portoPaths: ${JSON.stringify(portoPaths)},
+    portoRoot: "${path.resolve(portoPaths.root).replace(/\\/g, "/")}",
+    ...${JSON.stringify(context)}
+  });
+}
+`;
+
+  // Write and return shim path
+  const shimPath = path.join(dotDir, "docusaurus.config.js");
+  fs.writeFileSync(shimPath, shimContent);
+
+  return shimPath;
+}
+
+/**
+ * Validate that the current directory is a Portosaur project.
+ * @param {string} UserRoot - The directory to validate.
+ * @throws {Error} If config.yml is missing.
+ */
+export function validateProject(UserRoot) {
+  const configPath = ["config.yaml", "config.yml"].find((file) =>
+    fs.existsSync(path.join(UserRoot, file)),
+  );
+
+  if (!configPath) {
+    throw new Error(
+      "config.yml/config.yaml not found. Are you in a Portosaur project directory?",
+    );
+  }
+}
+
+/**
+ * Ensure essential user content directories exist.
+ * @param {string} UserRoot - The project root directory.
+ */
+export function ensureContentDirs(UserRoot) {
+  for (const dir of ["notes", "blog", "static"]) {
+    if (!fs.existsSync(path.join(UserRoot, dir))) {
+      fs.mkdirSync(path.join(UserRoot, dir), { recursive: true });
+    }
+  }
+}
+
+/**
+ * Print deployment tips defined in registry.yml
+ * @param {Object} hostingPlatforms - Hosting platforms registry.
+ * @param {string} hostingPlatformKey - The selected platform key.
+ * @param {Object} logger - The Portosaur logger instance.
+ * @param {Object} [vars={}] - Variables for replacement in tips.
+ */
+export function printWorkflowTips(
+  hostingPlatforms,
+  hostingPlatformKey,
+  logger,
+  vars = {},
+) {
+  const config = hostingPlatforms[hostingPlatformKey];
+  if (config && config.post_setup_tips) {
+    for (let tip of config.post_setup_tips) {
+      if (vars.projectName)
+        tip = tip.replace(/\{\{projectName\}\}/g, vars.projectName);
+      if (vars.userName) tip = tip.replace(/\{\{user\}\}/g, vars.userName);
+      logger.tip(tip);
+    }
+  }
+}
+
+/**
+ * Warn the user if their project name does not match the expected platform repository pattern.
+ * @param {Object} hostingPlatforms - Hosting platforms registry.
+ * @param {string} hostingPlatformKey - The selected platform key.
+ * @param {string} projectName - Current project name.
+ * @param {string} userName - VCS username.
+ * @param {Object} logger - The Portosaur logger instance.
+ * @param {string} [heading] - Warning heading.
+ */
+export function warnIfRepoNameMismatch(
+  hostingPlatforms,
+  hostingPlatformKey,
+  projectName,
+  userName,
+  logger,
+  heading = "Project Name Mismatch",
+) {
+  const config = hostingPlatforms[hostingPlatformKey];
+  if (!config || !config.repo || !config.repo.ideal_name) return;
+
+  const expectedRepo = config.repo.ideal_name
+    .replace("{{user}}", userName || "yourusername")
+    .replace("{{domain}}", config.domain || "");
+
+  if (projectName === expectedRepo || !config.repo.mismatch_msg) return;
+
+  const projectNameForMsg = projectName || "(custom name)";
+
+  const customMsg = config.repo.mismatch_msg
+    .replace(/\{\{user\}\}/g, userName || "yourusername")
+    .replace(/\{\{projectName\}\}/g, projectNameForMsg)
+    .replace(/\{\{domain\}\}/g, config.domain || "")
+    .replace(/\{\{idealName\}\}/g, expectedRepo);
+
+  logger.warn(`[${heading}] ${customMsg}`);
+}
+
+/**
+ * Executes a Docusaurus command.
+ * @param {string} command - Docusaurus command to run (e.g., 'start', 'build').
+ * @param {string} UserRoot - The project directory.
+ * @param {string} configPath - Path to the docusaurus.config.js shim.
+ * @param {string[]} [extraArgs=[]] - Additional CLI arguments.
+ * @returns {Promise<void>}
+ */
+export async function runDocusaurus(
+  command,
+  UserRoot,
+  configPath,
+  extraArgs = [],
+) {
+  const args = [
+    "run",
+    "--bun",
+    "docusaurus",
+    command,
+    UserRoot,
+    "--config",
+    configPath,
+    ...extraArgs,
+  ];
+
+  // Skip actual execution in test mode
+  if (process.env.PORTO_TEST_MODE === "true") {
+    console.log(`[TEST_MODE] Would run docusaurus ${command} in ${UserRoot}`);
+    return Promise.resolve();
+  }
+
+  const child = spawn("bun", args, {
+    stdio: "inherit",
+    cwd: UserRoot,
+    env: { ...process.env, FORCE_COLOR: "true" },
+  });
+
+  return new Promise((resolve, reject) => {
+    child.on("error", reject);
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Docusaurus exited with code ${code}`));
+      }
+    });
+  });
+}