@getquick/site 0.0.0-stage → 0.1.1

package/src/ops/ploi-api-command.mjs

@@ -0,0 +1,225 @@
+import { readFile } from "node:fs/promises";
+import { printValue } from "./output.mjs";
+import { createPloiClient } from "./providers/ploi.mjs";
+import { ploiCatalog } from "./providers/ploi-endpoints.mjs";
+import { confirmMutation, withSpinner } from "./ui.mjs";
+
+export const PLOI_API_OPTIONS = [
+  "server",
+  "site",
+  "path",
+  "query",
+  "data",
+  "dataFile",
+  "page",
+  "perPage",
+  "maxPages",
+  "all",
+  "yes",
+  "dryRun",
+];
+
+export function isPloiApiCommand(command) {
+  return command[0] === "ploi" && command[1] === "api";
+}
+
+export function validatePloiApiCommand(parsed) {
+  const action = parsed.command[2];
+  if (!action) {
+    throw new Error(
+      "Usage: gq ploi api <operation-id>, gq ploi api list, or gq ploi api describe <operation-id>.",
+    );
+  }
+  if (action === "list") {
+    if (parsed.command.length !== 3) {
+      throw new Error("gq ploi api list does not accept positional arguments.");
+    }
+    rejectOptionsExcept(parsed, ["group", "search"]);
+    return;
+  }
+  if (action === "describe") {
+    if (parsed.command.length !== 4) {
+      throw new Error("gq ploi api describe requires an operation ID.");
+    }
+    rejectOptionsExcept(parsed, []);
+    return;
+  }
+  if (parsed.command.length !== 3) {
+    throw new Error(`Unknown Ploi API command: ${parsed.command.join(" ")}.`);
+  }
+  rejectOptionsExcept(parsed, PLOI_API_OPTIONS);
+}
+
+export function runPloiApiCatalogCommand(parsed, io) {
+  const action = parsed.command[2];
+  if (action === "list") {
+    const endpoints = ploiCatalog.list({
+      group: parsed.group,
+      search: parsed.search,
+    });
+    printValue(
+      io,
+      endpoints.map(({ id, method, path, summary }) => ({
+        id,
+        method,
+        path,
+        summary,
+      })),
+      parsed,
+    );
+    return true;
+  }
+  if (action === "describe") {
+    const endpoint = ploiCatalog.get(parsed.command[3]);
+    printValue(
+      io,
+      {
+        ...endpoint,
+        pathParameters: pathParameterNames(endpoint.path).join(", "),
+        mutationRequiresConfirmation: endpoint.method !== "GET",
+      },
+      parsed,
+    );
+    return true;
+  }
+  return false;
+}
+
+export async function runPloiApiCommand({ context, parsed, fetch, io, interactive }) {
+  const endpoint = ploiCatalog.get(parsed.command[2]);
+  const pathParameters = parseNameValues(parsed.path, "--path");
+  const query = parseNameValues(parsed.query, "--query", { repeated: true });
+  applyContextPathDefaults(endpoint, pathParameters, parsed, context);
+  if (parsed.page) query.page = positiveInteger(parsed.page, "--page");
+  if (parsed.perPage) query.per_page = positiveInteger(parsed.perPage, "--per-page");
+
+  const body = await readBody(parsed, context);
+  const client = createPloiClient({
+    token: context.env.PLOI_API_TOKEN,
+    fetchImplementation: fetch,
+  });
+  const request = client.prepareEndpoint(endpoint, {
+    pathParameters,
+    query,
+    body,
+  });
+
+  if (parsed.dryRun) {
+    printValue(
+      io,
+      {
+        operation: endpoint.id,
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+      { json: true },
+    );
+    return;
+  }
+
+  if (endpoint.method !== "GET" && !parsed.yes) {
+    if (!interactive) {
+      throw new Error(
+        `${endpoint.id} changes remote state. Re-run with --yes or inspect it with --dry-run.`,
+      );
+    }
+    const confirmed = await confirmMutation({
+      operation: endpoint.id,
+      method: request.method,
+      url: request.url,
+    });
+    if (!confirmed) return;
+  }
+
+  const result = await withSpinner(
+    `Running ${endpoint.id}`,
+    () =>
+      client.executeEndpoint(endpoint, {
+        pathParameters,
+        query,
+        body,
+        paginate: parsed.all,
+        maxPages: parsed.maxPages ? positiveInteger(parsed.maxPages, "--max-pages") : undefined,
+      }),
+    interactive,
+  );
+  printValue(io, result, { json: true });
+}
+
+async function readBody(parsed, context) {
+  if (parsed.data !== undefined && parsed.dataFile !== undefined) {
+    throw new Error("Use either --data or --data-file, not both.");
+  }
+  if (parsed.data !== undefined) return parseJson(parsed.data, "--data");
+  if (parsed.dataFile !== undefined) {
+    const path = context.resolvePath(parsed.dataFile);
+    return parseJson(await readFile(path, "utf8"), path);
+  }
+  return undefined;
+}
+
+function applyContextPathDefaults(endpoint, values, parsed, context) {
+  const placeholders = new Set(pathParameterNames(endpoint.path));
+  if (placeholders.has("server") && values.server === undefined) {
+    values.server = parsed.server || context.env.PLOI_SERVER_ID || context.config.ploi?.serverId;
+  }
+  if (placeholders.has("site") && values.site === undefined) {
+    values.site = parsed.site || context.env.PLOI_SITE_ID || context.config.ploi?.siteId;
+  }
+}
+
+function pathParameterNames(path) {
+  return [...new Set([...path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]))];
+}
+
+function parseNameValues(entries, option, { repeated = false } = {}) {
+  const result = {};
+  for (const entry of entries || []) {
+    const separator = entry.indexOf("=");
+    if (separator <= 0) {
+      throw new Error(`${option} must use name=value syntax.`);
+    }
+    const name = entry.slice(0, separator);
+    const value = entry.slice(separator + 1);
+    if (!repeated && Object.hasOwn(result, name)) {
+      throw new Error(`${option} ${name} was provided more than once.`);
+    }
+    if (repeated && Object.hasOwn(result, name)) {
+      result[name] = Array.isArray(result[name]) ? [...result[name], value] : [result[name], value];
+    } else {
+      result[name] = value;
+    }
+  }
+  return result;
+}
+
+function parseJson(value, source) {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${source} must contain valid JSON: ${error.message}`, {
+      cause: error,
+    });
+  }
+}
+
+function positiveInteger(value, option) {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new Error(`${option} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function rejectOptionsExcept(parsed, allowed) {
+  const globals = new Set(["command", "help", "json", "project", "config"]);
+  const accepted = new Set(allowed);
+  for (const key of Object.keys(parsed)) {
+    if (!globals.has(key) && !accepted.has(key)) {
+      throw new Error(
+        `--${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)} is not valid for ${parsed.command.join(" ")}.`,
+      );
+    }
+  }
+}

package/src/ops/project-context.mjs

@@ -0,0 +1,103 @@
+import { access, readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { readEnvFile } from "./env.mjs";
+
+export const CONFIG_FILENAME = "gq.ops.json";
+
+export async function findProjectConfig(startDirectory) {
+  let directory = await realpath(resolve(startDirectory));
+
+  while (true) {
+    const candidate = join(directory, CONFIG_FILENAME);
+    if (await exists(candidate)) return candidate;
+    if (await exists(join(directory, ".git"))) return null;
+
+    const parent = dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+// `cwd` and `env` are the run() seam's; nothing here reads the process's own.
+export async function loadProjectContext(options) {
+  const configPath = await resolveConfigPath(options);
+  if (!configPath) {
+    throw new Error(
+      `No ${CONFIG_FILENAME} found from ${resolve(options.cwd)}. ` +
+        "Run inside a configured project or pass --project/--config.",
+    );
+  }
+
+  const canonicalConfigPath = await realpath(configPath);
+  const projectRoot = dirname(canonicalConfigPath);
+  const config = validateConfig(await readConfig(canonicalConfigPath));
+  const machineEnvPath = getMachineEnvPath(options.env);
+  const [machineEnv, projectEnv] = await Promise.all([
+    machineEnvPath ? readEnvFile(machineEnvPath) : {},
+    readEnvFile(join(projectRoot, ".env")),
+  ]);
+
+  return {
+    config,
+    configPath: canonicalConfigPath,
+    projectRoot,
+    invocationDirectory: await realpath(resolve(options.cwd)),
+    machineEnvPath,
+    env: {
+      ...machineEnv,
+      ...projectEnv,
+      ...options.env,
+    },
+    resolvePath(path) {
+      return isAbsolute(path) ? path : resolve(projectRoot, path);
+    },
+  };
+}
+
+async function resolveConfigPath(options) {
+  if (options.config) return resolve(options.cwd, options.config);
+  if (options.project) {
+    const project = resolve(options.cwd, options.project);
+    return project.endsWith(CONFIG_FILENAME) ? project : join(project, CONFIG_FILENAME);
+  }
+  return findProjectConfig(options.cwd);
+}
+
+async function readConfig(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`${path} is not valid JSON: ${error.message}`, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}
+
+function validateConfig(config) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`${CONFIG_FILENAME} must contain a configuration object.`);
+  }
+  if (typeof config.project !== "string" || !config.project.trim()) {
+    throw new Error(`${CONFIG_FILENAME} must define a non-empty project name.`);
+  }
+  return config;
+}
+
+// Without XDG_CONFIG_HOME or HOME there is no machine file to read.
+function getMachineEnvPath(environment) {
+  const configHome =
+    environment.XDG_CONFIG_HOME || (environment.HOME ? join(environment.HOME, ".config") : null);
+  return configHome ? join(configHome, "gq", "ops.env") : null;
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/ops/providers/cloudflare.mjs

@@ -0,0 +1,95 @@
+import { requestJson } from "./http.mjs";
+
+const API_BASE_URL = "https://api.cloudflare.com/client/v4";
+
+export function createCloudflareClient(options) {
+  const token = required(options.token, "CLOUDFLARE_API_TOKEN");
+  const fetchImplementation = options.fetchImplementation;
+
+  async function request(path, query = {}) {
+    const url = toApiUrl(path);
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== "") url.searchParams.set(key, value);
+    }
+
+    const payload = await requestJson(url, {
+      fetchImplementation,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+      },
+      errorMessage(response, data) {
+        return (
+          data.errors
+            ?.map((error) => error.message)
+            .filter(Boolean)
+            .join("; ") || `Cloudflare request failed with HTTP ${response.status}.`
+        );
+      },
+    });
+
+    if (payload.success === false) {
+      throw new Error(
+        payload.errors
+          ?.map((error) => error.message)
+          .filter(Boolean)
+          .join("; ") || "Cloudflare reported an unsuccessful request.",
+      );
+    }
+    return payload;
+  }
+
+  async function list(path, query = {}) {
+    const items = [];
+    let page = 1;
+
+    while (true) {
+      if (page > 100) throw new Error("Cloudflare pagination exceeded 100 pages.");
+      const payload = await request(path, {
+        ...query,
+        page: String(page),
+        per_page: "50",
+      });
+      if (Array.isArray(payload.result)) items.push(...payload.result);
+      const pageInfo = payload.result_info || {};
+      const perPage = Number(pageInfo.per_page) || 50;
+      const totalPages =
+        Number(pageInfo.total_pages) ||
+        Math.max(1, Math.ceil((Number(pageInfo.total_count) || items.length) / perPage));
+      if (page >= totalPages) return items;
+      page += 1;
+    }
+  }
+
+  return {
+    async listAccounts() {
+      return list("/accounts");
+    },
+    async listZones(filters = {}) {
+      return list("/zones", filters);
+    },
+    async getZone(zoneId) {
+      return unwrap(await request(`/zones/${encodeURIComponent(zoneId)}`));
+    },
+    async listDnsRecords(zoneId, filters = {}) {
+      return list(`/zones/${encodeURIComponent(zoneId)}/dns_records`, filters);
+    },
+  };
+}
+
+function toApiUrl(path) {
+  const url = new URL(`${API_BASE_URL}/${path.replace(/^\/+/, "")}`);
+  if (url.origin !== new URL(API_BASE_URL).origin || !url.pathname.startsWith("/client/v4/")) {
+    throw new Error("Cloudflare request resolved outside the expected API.");
+  }
+  return url;
+}
+
+function unwrap(payload) {
+  return payload.result ?? payload;
+}
+
+function required(value, environmentName) {
+  if (!value?.trim()) throw new Error(`${environmentName} is required.`);
+  return value.trim();
+}

package/src/ops/providers/github.mjs

@@ -0,0 +1,104 @@
+export async function syncActionsValues({
+  context,
+  env,
+  exec,
+  dryRun = false,
+  yes = false,
+  interactive = false,
+}) {
+  const github = context.config.github;
+  const repository = github?.repository;
+  const environment = github?.environment || "production";
+  const secrets = normalizeEntries(github?.secrets);
+  const variables = normalizeEntries(github?.variables);
+
+  if (!repository) throw new Error("gq.ops.json must define github.repository.");
+  if (!secrets || !variables) {
+    throw new Error("github.secrets and github.variables must be arrays.");
+  }
+
+  const values = context.env;
+  const activeSecrets = configuredEntries(secrets, values);
+  const activeVariables = configuredEntries(variables, values);
+  const missingSecrets = missingValues(secrets, values);
+  const missingVariables = missingValues(variables, values);
+  if (missingSecrets.length > 0 || missingVariables.length > 0) {
+    const missing = [
+      ...missingSecrets.map((name) => `secret ${name}`),
+      ...missingVariables.map((name) => `variable ${name}`),
+    ];
+    throw new Error(`Missing values in .env or the process environment: ${missing.join(", ")}`);
+  }
+
+  const plan = {
+    repository,
+    environment,
+    secrets: activeSecrets.map(({ name }) => name),
+    variables: activeVariables.map(({ name }) => name),
+  };
+  if (dryRun) return { ...plan, applied: false };
+
+  if (!yes && interactive) {
+    const { confirm } = await import("@clack/prompts");
+    const answer = await confirm({
+      message: `Sync ${secrets.length} secrets and ${variables.length} variables to ${repository}/${environment}?`,
+      initialValue: false,
+    });
+    if (answer !== true) throw new Error("GitHub synchronization cancelled.");
+  } else if (!yes && !interactive) {
+    throw new Error("GitHub synchronization requires --yes outside an interactive terminal.");
+  }
+
+  for (const { name } of activeSecrets) {
+    await runGh(["secret", "set", name, "--repo", repository, "--env", environment], values[name], {
+      exec,
+      env,
+      tokens: context.env,
+    });
+  }
+  for (const { name } of activeVariables) {
+    await runGh(
+      ["variable", "set", name, "--repo", repository, "--env", environment],
+      values[name],
+      { exec, env, tokens: context.env },
+    );
+  }
+
+  return { ...plan, applied: true };
+}
+
+// The value goes to gh on stdin, never in its arguments.
+async function runGh(args, input, { exec, env, tokens }) {
+  const { code, stdout, stderr } = await exec("gh", args, {
+    env: {
+      ...env,
+      ...(tokens.GITHUB_TOKEN ? { GH_TOKEN: tokens.GITHUB_TOKEN } : {}),
+      ...(tokens.GH_TOKEN ? { GH_TOKEN: tokens.GH_TOKEN } : {}),
+    },
+    input: String(input),
+  });
+  if (code !== 0) {
+    throw new Error(`gh ${args.slice(0, 3).join(" ")} failed: ${(stderr || stdout).trim()}`);
+  }
+}
+
+function normalizeEntries(entries) {
+  if (!Array.isArray(entries)) return null;
+  return entries.map((entry) => {
+    if (typeof entry === "string") return { name: entry, required: true };
+    if (entry && typeof entry.name === "string") {
+      return { name: entry.name, required: entry.required !== false };
+    }
+    throw new Error("GitHub sync entries must be names or { name, required } objects.");
+  });
+}
+
+function configuredEntries(entries, values) {
+  return entries.filter(({ name }) => values[name] !== undefined && values[name] !== "");
+}
+
+function missingValues(entries, values) {
+  return entries
+    .filter(({ name, required }) => required && (values[name] === undefined || values[name] === ""))
+    .map(({ name }) => name);
+}

package/src/ops/providers/http.mjs

@@ -0,0 +1,31 @@
+export async function requestJson(url, options = {}) {
+  const response = await options.fetchImplementation(url, {
+    method: options.method || "GET",
+    signal: options.signal || AbortSignal.timeout(options.timeoutMs || 30_000),
+    headers: options.headers,
+    body: options.body,
+  });
+  const text = await response.text();
+  const parsed = text ? tryParseJson(text) : { ok: true, value: {} };
+
+  const acceptedStatus = options.acceptedStatuses?.includes(response.status);
+  if (!response.ok && !acceptedStatus) {
+    const payload = parsed.ok ? parsed.value : {};
+    throw new Error(
+      options.errorMessage?.(response, payload) || `Request failed with HTTP ${response.status}.`,
+    );
+  }
+  if (!parsed.ok) {
+    throw new Error("Provider returned a response that was not valid JSON.");
+  }
+
+  return parsed.value;
+}
+
+function tryParseJson(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}

package/src/ops/providers/ploi-catalog.mjs

@@ -0,0 +1,49 @@
+export function createPloiCatalog(endpoints) {
+  const byId = new Map();
+
+  for (const endpoint of endpoints) {
+    validateEndpoint(endpoint);
+    if (byId.has(endpoint.id)) {
+      throw new Error(`Duplicate Ploi endpoint ID: ${endpoint.id}.`);
+    }
+    byId.set(endpoint.id, Object.freeze({ ...endpoint }));
+  }
+
+  return Object.freeze({
+    list({ group, search } = {}) {
+      const needle = search?.trim().toLowerCase();
+      return [...byId.values()].filter((endpoint) => {
+        if (group && endpoint.id.split(".", 1)[0] !== group) return false;
+        if (!needle) return true;
+        return [endpoint.id, endpoint.method, endpoint.path, endpoint.summary]
+          .filter(Boolean)
+          .some((value) => value.toLowerCase().includes(needle));
+      });
+    },
+    get(id) {
+      const endpoint = byId.get(id);
+      if (!endpoint) {
+        throw new Error(`Unknown Ploi API operation: ${id}. Run gq ploi api list.`);
+      }
+      return endpoint;
+    },
+  });
+}
+
+function validateEndpoint(endpoint) {
+  if (!endpoint || typeof endpoint !== "object") {
+    throw new Error("Ploi endpoint entries must be objects.");
+  }
+  if (!/^[a-z0-9-]+\.[a-z0-9-]+$/.test(endpoint.id)) {
+    throw new Error(`Invalid Ploi endpoint ID: ${endpoint.id}.`);
+  }
+  if (!new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]).has(endpoint.method)) {
+    throw new Error(`Invalid HTTP method for ${endpoint.id}: ${endpoint.method}.`);
+  }
+  if (!endpoint.path.startsWith("/") || endpoint.path.includes("?")) {
+    throw new Error(`Invalid API path for ${endpoint.id}: ${endpoint.path}.`);
+  }
+  if (!endpoint.sourceUrl.startsWith("https://developers.ploi.io/")) {
+    throw new Error(`Invalid documentation URL for ${endpoint.id}.`);
+  }
+}