@portosaur/cli 0.1.0

package/src/commands/initCi.mjs

@@ -0,0 +1,227 @@
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+
+import { runWizard, cancel } from "@portosaur/wizard";
+
+import { logger, colors } from "@portosaur/logger";
+import { mirrorSync, porto } from "@portosaur/core";
+import {
+  Paths,
+  detectVcsProvider,
+  getGitConfig,
+  getWorkflowMarkers,
+  resolvePlatformKey,
+  getPlatformUserGuess,
+  validateProject,
+  printWorkflowTips,
+  warnIfRepoNameMismatch,
+  isInteractive as getInteractivity,
+  looksLikeTestProject,
+} from "../utils/index.mjs";
+
+/**
+ * Initializes CI/CD configuration for an existing Portosaur project.
+ */
+export async function initCiCommand(options = {}) {
+  //
+  //====================== Constants ======================
+
+  const projectDir = process.cwd();
+
+  const registry = yaml.load(fs.readFileSync(Paths.registry, "utf8"));
+
+  const gitConfig = getGitConfig();
+  const vcsProviderId = detectVcsProvider(registry);
+
+  const isInteractive = getInteractivity(options);
+
+  // Validate project existence
+  try {
+    validateProject(projectDir);
+  } catch (error) {
+    logger.error(error.message);
+    process.exit(1);
+  }
+
+  // Detect existing CI configurations based on workflow templates
+  const ciMarkers = getWorkflowMarkers(registry);
+  const detectedMarkers = ciMarkers.filter((marker) =>
+    fs.existsSync(path.join(projectDir, marker)),
+  );
+
+  let state = {
+    hostingPlatform: options.hosting || null,
+  };
+
+  /*
+   * ====================== Interactive mode ======================
+   */
+  if (isInteractive) {
+    const vcs = registry.vcs_providers[vcsProviderId];
+
+    const wizardState = await runWizard({
+      initialState: state,
+
+      intro: "Setting up Portosaur CI/CD",
+      outro: false,
+
+      steps: [
+        {
+          id: "overwrite",
+          type: "confirm",
+          prompt: "Existing CI configuration detected. Overwrite?",
+          hint: `Detected: ${detectedMarkers.join(", ")}`,
+          runIf: () => detectedMarkers.length > 0,
+          initialValue: false,
+        },
+        {
+          id: "hostingPlatform",
+          type: "select",
+          prompt: "Select target hosting platform",
+          hint: "The service where your portfolio will be deployed",
+          options: Object.keys(registry.hosting_platforms).map((key) => ({
+            value: key,
+            label: registry.hosting_platforms[key].name,
+            hint: key === vcs?.default_hosting ? "recommended" : "",
+          })),
+          initialValue: () => vcs?.default_hosting || "none",
+        },
+        {
+          id: "confirm",
+          type: "confirm",
+          prompt: "Are you sure you want to proceed?",
+          hint: (state) =>
+            state.overwrite
+              ? "This will DELETE existing CI files and create new ones"
+              : "This will create CI configuration files",
+          initialValue: true,
+        },
+      ],
+    });
+
+    if (
+      !wizardState.confirm ||
+      (detectedMarkers.length > 0 && wizardState.overwrite === false)
+    ) {
+      cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    state = { ...state, ...wizardState };
+
+    /*
+     * ====================== Non-Interactive Mode ======================
+     */
+  } else {
+    //
+    // Normalize hosting platform
+    if (state.hostingPlatform && state.hostingPlatform !== "none") {
+      state.hostingPlatform =
+        resolvePlatformKey(registry.hosting_platforms, state.hostingPlatform) ||
+        state.hostingPlatform;
+    }
+
+    const vcs = registry.vcs_providers[vcsProviderId];
+
+    state.hostingPlatform =
+      state.hostingPlatform || vcs?.default_hosting || "none";
+
+    if (state.hostingPlatform !== "none") {
+      logger.info(
+        `Detected ${vcs?.name || vcsProviderId} provider, defaulting to ${state.hostingPlatform}.`,
+      );
+    }
+  }
+
+  /*
+   * ====================== Execution ======================
+   */
+
+  // Final canonical resolution
+  const resolved = resolvePlatformKey(
+    registry.hosting_platforms,
+    state.hostingPlatform,
+  );
+
+  if (!resolved || resolved === "none") {
+    logger.error(
+      `Unknown or invalid hosting platform: ${state.hostingPlatform || "none"}`,
+    );
+    process.exit(1);
+  }
+
+  state.hostingPlatform = resolved;
+
+  //--------- Clear the console ----------------
+  logger.resetView();
+  logger.info.box("Portosaur CI/CD Setup", {
+    title: ` v${porto.version} `,
+  });
+
+  // Gather variables for template replacement
+  const isTestProject = looksLikeTestProject(path.basename(projectDir));
+  const portoVer = isTestProject ? "link:portosaur" : porto.version || "0.0.0";
+
+  const userName = getPlatformUserGuess(vcsProviderId, gitConfig) || "user";
+  const fullName = gitConfig["user.name"] || "User";
+
+  const templateVars = {
+    projectName: path.basename(projectDir),
+    userName,
+    fullName,
+    portoVer,
+  };
+
+  const hConfig = registry.hosting_platforms[state.hostingPlatform];
+
+  logger.info(`Configuring CI/CD for ${hConfig.name}...`);
+
+  try {
+    let template = hConfig.template_dir;
+    if (typeof template === "object") {
+      template = template[vcsProviderId] || Object.values(template)[0];
+    }
+
+    const workflowTemplateDir = path.join(Paths.workflows, template);
+
+    if (!fs.existsSync(workflowTemplateDir)) {
+      throw new Error(
+        `Platform template for "${state.hostingPlatform}" not found.`,
+      );
+    }
+
+    // Clean up existing CI files if requested
+    if (state.overwrite) {
+      logger.info("Cleaning up existing CI configuration...");
+
+      for (const marker of detectedMarkers) {
+        const fullPath = path.join(projectDir, marker);
+        if (fs.existsSync(fullPath)) {
+          fs.rmSync(fullPath, { recursive: true, force: true });
+        }
+      }
+    }
+
+    mirrorSync(workflowTemplateDir, projectDir, templateVars, []);
+
+    /*
+     * ====================== Final Output ======================
+     */
+
+    logger.resetView();
+    logger.success.box(`CI/CD successfully configured!`);
+
+    printWorkflowTips(
+      registry.hosting_platforms,
+      state.hostingPlatform,
+      logger,
+      templateVars,
+    );
+
+    logger.newLine();
+  } catch (error) {
+    logger.error(`Configuration failed: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/providers.mjs

@@ -0,0 +1,170 @@
+import { readFileSync } from "fs";
+import yaml from "js-yaml";
+import { colors } from "@portosaur/logger";
+import { Paths } from "../utils/index.mjs";
+
+/**
+ * Displays available VCS providers and hosting platforms.
+ */
+export async function providersCommand(subcommand = null) {
+  const registry = yaml.load(readFileSync(Paths.registry, "utf8"));
+
+  const vcsProviders = registry.vcs_providers || {};
+  const hostingPlatforms = registry.hosting_platforms || {};
+
+  switch (subcommand) {
+    case "vcs":
+      displayVcsProviders(vcsProviders);
+      break;
+
+    case "hosting":
+      displayHostingPlatforms(hostingPlatforms, vcsProviders);
+      break;
+
+    default:
+      displayAll(vcsProviders, hostingPlatforms);
+  }
+}
+
+/**
+ * Format template variables for display (e.g., {{user}} -> <username>).
+ */
+function formatTemplateVars(str) {
+  if (!str) return str;
+  return str.replace(/\{\{(\w+)\}\}/g, "<$1>");
+}
+
+/**
+ * Strip ANSI color codes to get the actual display width.
+ */
+function stripAnsi(str) {
+  return String(str).replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/**
+ * Create a simple ASCII table.
+ */
+function createTable(rows, columns) {
+  const colWidths = columns.map((col) => col.length);
+
+  for (const row of rows) {
+    for (let i = 0; i < columns.length; i++) {
+      const val = stripAnsi(row[i] || "");
+      colWidths[i] = Math.max(colWidths[i], val.length);
+    }
+  }
+
+  const lines = [];
+
+  // Header
+  const headerLine = columns
+    .map((col, i) => colors.bold(col.padEnd(colWidths[i])))
+    .join("  ");
+  lines.push(headerLine);
+
+  // Separator
+  const sepLine = colWidths.map((w) => "─".repeat(w)).join("──");
+  lines.push(colors.dim(sepLine));
+
+  // Rows
+  for (const row of rows) {
+    const line = row
+      .map((val, i) => {
+        const plain = stripAnsi(val || "");
+        const padded = plain.padEnd(colWidths[i]);
+        // If the value is colored, we need to apply color to the padded version
+        const colored = val || "";
+        if (stripAnsi(colored) !== colored) {
+          // Has color codes - reapply coloring after padding
+          const colorCodes = colored.match(/\x1b\[[0-9;]*m/g) || [];
+          const resetCode = "\x1b[0m";
+          return colored + resetCode + padded.slice(plain.length);
+        }
+        return padded;
+      })
+      .join("  ");
+    lines.push(line);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Display all providers and platforms.
+ */
+function displayAll(vcsProviders, hostingPlatforms) {
+  console.log("📦 " + colors.bold("Available Providers"));
+  console.log("");
+
+  displayVcsProviders(vcsProviders);
+  console.log("");
+
+  displayHostingPlatforms(hostingPlatforms, vcsProviders);
+}
+
+/**
+ * Display VCS providers.
+ */
+function displayVcsProviders(vcsProviders) {
+  console.log(colors.bold("VCS Providers:"));
+  console.log("");
+
+  const rows = Object.entries(vcsProviders).map(([id, config]) => [
+    colors.cyan(id),
+    config.name || "N/A",
+    config.domain || "N/A",
+    config.default_hosting || "N/A",
+  ]);
+
+  console.log(createTable(rows, ["ID", "Name", "Domain", "Default Hosting"]));
+}
+
+/**
+ * Display hosting platforms with supported providers.
+ */
+function displayHostingPlatforms(hostingPlatforms, vcsProviders) {
+  console.log(colors.bold("Hosting Platforms:"));
+  console.log("");
+
+  const rows = Object.entries(hostingPlatforms).map(([id, config]) => {
+    const supportedProviders = getSupportedProviders(config, vcsProviders);
+    const idealName = config.repo?.ideal_name
+      ? formatTemplateVars(config.repo.ideal_name)
+      : "N/A";
+
+    return [
+      colors.cyan(id),
+      config.name,
+      config.domain || "N/A",
+      supportedProviders.join(", "),
+      idealName,
+    ];
+  });
+
+  console.log(
+    createTable(rows, [
+      "ID",
+      "Name",
+      "Domain",
+      "Supported Providers",
+      "Ideal Repo Name",
+    ]),
+  );
+}
+
+/**
+ * Get supported providers for a hosting platform.
+ */
+function getSupportedProviders(platform, vcsProviders) {
+  const supportedProviders = platform.supported_providers;
+
+  if (Array.isArray(supportedProviders)) {
+    return supportedProviders;
+  }
+
+  if (supportedProviders === "all") {
+    return Object.keys(vcsProviders);
+  }
+
+  return ["none"];
+}

package/src/commands/schema.mjs

@@ -0,0 +1,208 @@
+import fs from "fs";
+import path from "path";
+import { logger } from "@portosaur/logger";
+
+/**
+ * Portosaur Discovery-Based Schema Generator
+ *
+ * This command "discovers" the configuration schema by parsing the actual
+ * Docusaurus config building logic. Every key accessed via the `get()` helper
+ * is recorded and mapped to a JSON schema.
+ */
+export async function schemaCommand(options = {}) {
+  // Resolve paths for the monorepo structure
+  const pkgDir = path.resolve(import.meta.dirname, "../");
+  const coreDir = path.resolve(pkgDir, "../../core");
+
+  const SOURCE_FILE =
+    typeof options.config === "string"
+      ? path.resolve(process.cwd(), options.config)
+      : path.resolve(coreDir, "src/index.mjs");
+
+  const OUTPUT_FILE =
+    typeof options.output === "string"
+      ? path.resolve(process.cwd(), options.output)
+      : path.resolve(pkgDir, "../../../configSchema.json");
+
+  const discoveredSchema = {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    title: "Portosaur Project Configuration",
+    type: "object",
+    properties: {},
+    required: [],
+    additionalProperties: true,
+  };
+
+  // State for Balanced Parenthesis Walker
+  const getStartRegex = /get\(\s*["']([^"']+)["']\s*,\s*/g;
+  let match;
+
+  try {
+    if (!fs.existsSync(SOURCE_FILE)) {
+      throw new Error(`Source file not found: ${SOURCE_FILE}`);
+    }
+
+    logger.info(`Discovering keys from ${SOURCE_FILE}...`);
+    const sourceCode = fs.readFileSync(SOURCE_FILE, "utf8");
+
+    // Discovery Loop
+    while ((match = getStartRegex.exec(sourceCode)) !== null) {
+      const keyPath = match[1];
+      const startIdx = match.index + match[0].length;
+
+      let braceCount = 1;
+      let currentIdx = startIdx;
+      let defaultValueRaw = "";
+      let inString = null;
+      let inComment = null;
+      let escaped = false;
+
+      // Extract raw default value using balanced parenthesis walker
+      while (braceCount > 0 && currentIdx < sourceCode.length) {
+        const char = sourceCode[currentIdx];
+        const nextChar = sourceCode[currentIdx + 1];
+
+        if (escaped) {
+          escaped = false;
+        } else if (char === "\\") {
+          escaped = true;
+        } else if (!inString && !inComment) {
+          if (char === "'" || char === '"' || char === "`") inString = char;
+          else if (char === "/" && nextChar === "/") inComment = "//";
+          else if (char === "/" && nextChar === "*") inComment = "/*";
+          else if (char === "(") braceCount++;
+          else if (char === ")") braceCount--;
+        } else if (inString) {
+          if (char === inString) inString = null;
+        } else if (inComment === "//") {
+          if (char === "\n") inComment = null;
+        } else if (inComment === "/*") {
+          if (char === "*" && nextChar === "/") {
+            inComment = null;
+            defaultValueRaw += "*/";
+            currentIdx += 2;
+            continue;
+          }
+        }
+
+        if (braceCount > 0) defaultValueRaw += char;
+        currentIdx++;
+      }
+
+      // Extract Documentation Comments
+      const beforeMatch = sourceCode.slice(0, match.index);
+      const currentLineStart = beforeMatch.lastIndexOf("\n");
+      const linesBefore = sourceCode
+        .slice(0, currentLineStart === -1 ? 0 : currentLineStart)
+        .split("\n");
+
+      let i = linesBefore.length - 1;
+      let foundComment = [];
+      let inDocBlock = false;
+
+      while (i >= 0 && foundComment.length < 15) {
+        let line = linesBefore[i].trim();
+        if (!line && !inDocBlock) break;
+        if (line.endsWith("*/")) inDocBlock = true;
+
+        if (inDocBlock) {
+          const content = line.replace(/^\/\*\*?|\*\/|\*/g, "").trim();
+          if (content) foundComment.unshift(content);
+          if (line.startsWith("/*") || line.startsWith("/**"))
+            inDocBlock = false;
+        } else if (line.startsWith("//")) {
+          let content = line.replace(/^\/\/\s?/, "").trim();
+          if (!content.match(/^(TODO|FIXME|NOTE|SECTION|---)/i)) {
+            foundComment.unshift(content);
+          }
+        } else if (line && !line.startsWith("/") && !line.startsWith("*")) {
+          break;
+        }
+        i--;
+      }
+      const description = foundComment.join("\n").trim();
+
+      // Basic Type Inference and Argument Parsing
+      let type = "string";
+      let defaultValue = undefined;
+
+      let args = [];
+      let currentArg = "";
+      let depth = 0;
+      let argInString = null;
+
+      for (let i = 0; i < defaultValueRaw.length; i++) {
+        const c = defaultValueRaw[i];
+        if (!argInString) {
+          if (c === "'" || c === '"' || c === "`") argInString = c;
+          else if (c === "(" || c === "[" || c === "{") depth++;
+          else if (c === ")" || c === "]" || c === "}") depth--;
+          else if (c === "," && depth === 0) {
+            args.push(currentArg.trim());
+            currentArg = "";
+            continue;
+          }
+        } else if (c === argInString && defaultValueRaw[i - 1] !== "\\") {
+          argInString = null;
+        }
+        currentArg += c;
+      }
+      if (currentArg.trim()) args.push(currentArg.trim());
+
+      let val = (args[args.length - 1] || "").trim();
+
+      if (val === "true" || val === "false") {
+        type = "boolean";
+        defaultValue = val === "true";
+      } else if (!isNaN(val) && val !== "") {
+        type = "number";
+        defaultValue = Number(val);
+      } else if (
+        val.startsWith("[") ||
+        val.includes(".map(") ||
+        val.includes(".filter(") ||
+        val.includes(".slice(")
+      ) {
+        type = "array";
+      } else if (val.startsWith("{")) {
+        type = "object";
+      } else if (val) {
+        defaultValue = val.replace(/^["'`](.*)["'`]$/s, "$1").trim();
+      }
+
+      // Map to Discovered Schema Object
+      const parts = keyPath.split(".");
+      let current = discoveredSchema.properties;
+
+      parts.forEach((part, index) => {
+        const isLast = index === parts.length - 1;
+
+        if (!current[part]) {
+          if (isLast) {
+            current[part] = { type };
+            if (description) current[part].description = description;
+            if (defaultValue !== undefined)
+              current[part].default = defaultValue;
+          } else {
+            current[part] = { type: "object", properties: {} };
+          }
+        } else if (!isLast && current[part].type !== "object") {
+          current[part] = { type: "object", properties: {} };
+        }
+
+        if (!isLast) {
+          if (!current[part].properties) current[part].properties = {};
+          current = current[part].properties;
+        }
+      });
+    }
+
+    fs.writeFileSync(OUTPUT_FILE, JSON.stringify(discoveredSchema, null, 2));
+    logger.success(
+      `Successfully discovered and wrote schema to: ${OUTPUT_FILE}`,
+    );
+  } catch (error) {
+    logger.error(`Discovery failed: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/serve.mjs

@@ -0,0 +1,29 @@
+import path from "path";
+import { runDocusaurus, validateProject } from "../utils/index.mjs";
+import { logger } from "@portosaur/logger";
+
+/**
+ * Serves the built Portosaur site locally.
+ *
+ * Note: Docusaurus 'serve' doesn't require a config shim,
+ * as it serves the already built static files from the output directory.
+ */
+export async function serveCommand(siteDir, extraArgs = []) {
+  const UserRoot = siteDir
+    ? path.resolve(process.cwd(), siteDir)
+    : process.cwd();
+
+  // ------- Setup -------
+
+  validateProject(UserRoot);
+
+  try {
+    logger.info("Serving built site...");
+
+    // Docusaurus serve looks for the 'build' directory by default.
+    await runDocusaurus("serve", UserRoot, "", extraArgs);
+  } catch (error) {
+    logger.error(`Failed to serve site: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,49 @@
+export interface InitOptions {
+  /** VCS Provider ID (e.g., "github", "gitlab") */
+  vcsProvider?: string;
+  /** Hosting Platform ID (e.g., "github_pages", "surge") */
+  hosting?: string;
+  /** VCS username */
+  username?: string;
+  /** Full name for the portfolio */
+  name?: string;
+  /** Project name/directory */
+  projectName?: string;
+  /** Whether to install dependencies after initialization (default: true) */
+  install?: boolean;
+}
+
+export interface InitCiOptions {
+  /** Hosting Platform ID */
+  hosting?: string;
+}
+
+/**
+ * Initializes a new Portosaur project.
+ */
+export function initCommand(options?: InitOptions): Promise<void>;
+
+/**
+ * Sets up CI/CD workflows for an existing project.
+ */
+export function initCiCommand(options?: InitCiOptions): Promise<void>;
+
+/**
+ * Starts the Docusaurus development server.
+ */
+export function devCommand(siteDir?: string, extraArgs?: string[]): void;
+
+/**
+ * Builds the Docusaurus static site.
+ */
+export function buildCommand(siteDir?: string, extraArgs?: string[]): void;
+
+/**
+ * Serves the built static site locally.
+ */
+export function serveCommand(siteDir?: string): void;
+
+/**
+ * Generates the config schema.
+ */
+export function schemaCommand(outPath?: string, srcPath?: string): void;

package/src/index.mjs

@@ -0,0 +1,8 @@
+export * from "./commands/init.mjs";
+export * from "./commands/initCi.mjs";
+export * from "./commands/dev.mjs";
+export * from "./commands/build.mjs";
+export * from "./commands/serve.mjs";
+export * from "./commands/schema.mjs";
+export * from "./commands/providers.mjs";
+export * from "./utils/index.mjs";