@getquick/site 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@getquick/site",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Shared tooling for GETQUICK sites: the gq CLI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "gq": "bin/gq.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs/research/ploi-api.md",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "pnpm format:check && pnpm lint && pnpm test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "test": "node --test \"test/*.test.mjs\"",
+    "release:publish": "node scripts/publish.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "prettier": "^3.8.2",
+    "sigillo": "0.13.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@12.6.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Quick-Release/getquick-site.git"
+  },
+  "keywords": [
+    "getquick",
+    "cloudflare",
+    "ploi",
+    "cli",
+    "operations"
+  ]
+}

package/src/exec.mjs

@@ -0,0 +1,23 @@
+import { spawn } from "node:child_process";
+
+// The real `exec` for run(): runs a command without a shell, optionally
+// writing `input` to its stdin, and resolves with its exit code and output.
+export function exec(command, args, { cwd, env, input } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => {
+      stderr += chunk;
+    });
+    // A child that exits without reading its input closes the pipe (EPIPE);
+    // its exit code, not the write, is the result.
+    child.stdin.on("error", () => {});
+    child.once("error", reject);
+    child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    child.stdin.end(input === undefined ? undefined : String(input));
+  });
+}

package/src/index.mjs

@@ -0,0 +1 @@
+export { run } from "./run.mjs";

package/src/ops/cli.mjs

@@ -0,0 +1,349 @@
+import { loadProjectContext } from "./project-context.mjs";
+import { createCloudflareClient } from "./providers/cloudflare.mjs";
+import { syncActionsValues } from "./providers/github.mjs";
+import { createPloiClient } from "./providers/ploi.mjs";
+import { printValue } from "./output.mjs";
+import {
+  isPloiApiCommand,
+  runPloiApiCatalogCommand,
+  runPloiApiCommand,
+  validatePloiApiCommand,
+} from "./ploi-api-command.mjs";
+import { PLOI_ENDPOINTS } from "./providers/ploi-endpoints.mjs";
+import { chooseCommand } from "./ui.mjs";
+import { VERSION } from "../version.mjs";
+
+const COMMAND_OPTIONS = new Map([
+  ["context show", []],
+  ["github actions sync", ["yes", "dryRun"]],
+  ["ploi servers list", []],
+  ["ploi server show", ["server"]],
+  ["ploi sites list", ["server"]],
+  ["ploi site show", ["server", "site"]],
+  ["cloudflare accounts list", []],
+  ["cloudflare zones list", ["account"]],
+  ["cloudflare zone show", ["account", "zone"]],
+  ["cloudflare dns list", ["account", "zone", "name", "type"]],
+]);
+
+export async function runCli(argv, { cwd, env, fetch, exec, io, interactive }) {
+  let effectiveArguments = argv;
+  if (effectiveArguments.length === 0 && interactive) {
+    const selected = await chooseCommand(PLOI_ENDPOINTS);
+    if (!selected) return;
+    effectiveArguments = selected;
+  }
+
+  const parsed = parseArguments(effectiveArguments);
+  if (parsed.version) {
+    io.out(VERSION);
+    return;
+  }
+  if (parsed.help || parsed.command.length === 0) {
+    printHelp(io);
+    return;
+  }
+  validateCommand(parsed);
+  if (isPloiApiCommand(parsed.command) && runPloiApiCatalogCommand(parsed, io)) {
+    return;
+  }
+
+  const context = await loadProjectContext({
+    cwd,
+    env,
+    project: parsed.project,
+    config: parsed.config,
+  });
+  const [provider, resource, action = "list"] = parsed.command;
+
+  if (provider === "context" && resource === "show") {
+    printValue(io, contextSummary(context), parsed);
+    return;
+  }
+
+  if (provider === "github" && resource === "actions" && action === "sync") {
+    printValue(
+      io,
+      await syncActionsValues({
+        context,
+        env,
+        exec,
+        dryRun: parsed.dryRun,
+        interactive,
+        yes: parsed.yes,
+      }),
+      parsed,
+    );
+    return;
+  }
+
+  if (provider === "ploi") {
+    if (resource === "api") {
+      await runPloiApiCommand({ context, parsed, fetch, io, interactive });
+    } else {
+      await runPloi({ context, resource, action, parsed, fetch, io });
+    }
+    return;
+  }
+
+  if (provider === "cloudflare") {
+    await runCloudflare({ context, resource, action, parsed, fetch, io });
+    return;
+  }
+
+  throw new Error(`Unknown command: ${parsed.command.join(" ")}. Run gq --help.`);
+}
+
+async function runPloi({ context, resource, action, parsed, fetch, io }) {
+  const client = createPloiClient({
+    token: context.env.PLOI_API_TOKEN,
+    fetchImplementation: fetch,
+  });
+  const serverId = parsed.server || context.env.PLOI_SERVER_ID || context.config.ploi?.serverId;
+  const siteId = parsed.site || context.env.PLOI_SITE_ID || context.config.ploi?.siteId;
+  let result;
+
+  if (resource === "servers" && action === "list") {
+    result = (await client.listServers()).map(presentPloiServer);
+  } else if (resource === "server" && action === "show") {
+    result = presentPloiServer(await client.getServer(required(serverId, "Ploi server ID")));
+  } else if (resource === "sites" && action === "list") {
+    result = (await client.listSites(required(serverId, "Ploi server ID"))).map(presentPloiSite);
+  } else if (resource === "site" && action === "show") {
+    result = presentPloiSite(
+      await client.getSite(required(serverId, "Ploi server ID"), required(siteId, "Ploi site ID")),
+    );
+  } else {
+    throw new Error(`Unknown Ploi command: ${resource || ""} ${action}. Run gq --help.`);
+  }
+
+  printValue(io, result, parsed);
+}
+
+async function runCloudflare({ context, resource, action, parsed, fetch, io }) {
+  const client = createCloudflareClient({
+    token: context.env.CLOUDFLARE_API_TOKEN,
+    fetchImplementation: fetch,
+  });
+  const accountId =
+    parsed.account || context.env.CLOUDFLARE_ACCOUNT_ID || context.config.cloudflare?.accountId;
+  let zoneId = parsed.zone || context.env.CLOUDFLARE_ZONE_ID || context.config.cloudflare?.zoneId;
+  const zoneName = context.env.CLOUDFLARE_ZONE_NAME || context.config.cloudflare?.zoneName;
+  let result;
+
+  if (resource === "accounts" && action === "list") {
+    result = (await client.listAccounts()).map(presentCloudflareAccount);
+  } else if (resource === "zones" && action === "list") {
+    result = (await client.listZones({ "account.id": accountId, name: zoneName })).map(
+      presentCloudflareZone,
+    );
+  } else if (resource === "zone" && action === "show") {
+    zoneId = await resolveZoneId(client, { zoneId, zoneName, accountId });
+    result = presentCloudflareZone(await client.getZone(zoneId));
+  } else if (resource === "dns" && action === "list") {
+    zoneId = await resolveZoneId(client, { zoneId, zoneName, accountId });
+    result = (
+      await client.listDnsRecords(zoneId, {
+        name: parsed.name,
+        type: parsed.type,
+      })
+    ).map(presentDnsRecord);
+  } else {
+    throw new Error(`Unknown Cloudflare command: ${resource || ""} ${action}. Run gq --help.`);
+  }
+
+  printValue(io, result, parsed);
+}
+
+async function resolveZoneId(client, { zoneId, zoneName, accountId }) {
+  if (zoneId) return zoneId;
+  const zones = await client.listZones({
+    name: zoneName,
+    "account.id": accountId,
+  });
+  if (zones.length !== 1) {
+    throw new Error(
+      `Expected exactly one matching Cloudflare zone, found ${zones.length}. Configure cloudflare.zoneId or pass --zone.`,
+    );
+  }
+  return zones[0].id;
+}
+
+function parseArguments(argv) {
+  const parsed = { command: [] };
+  const valueOptions = new Set([
+    "--project",
+    "--config",
+    "--server",
+    "--site",
+    "--account",
+    "--zone",
+    "--name",
+    "--type",
+    "--group",
+    "--search",
+    "--path",
+    "--query",
+    "--data",
+    "--data-file",
+    "--page",
+    "--per-page",
+    "--max-pages",
+  ]);
+  const repeatedValueOptions = new Set(["--path", "--query"]);
+  const booleanOptions = new Set(["--all", "--dry-run", "--yes"]);
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--help" || argument === "-h" || argument === "help") parsed.help = true;
+    else if (argument === "--version" || argument === "-v") parsed.version = true;
+    else if (argument === "--json") parsed.json = true;
+    else if (booleanOptions.has(argument)) parsed[toOptionKey(argument)] = true;
+    else if (valueOptions.has(argument)) {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${argument} requires a value.`);
+      const key = toOptionKey(argument);
+      if (repeatedValueOptions.has(argument)) {
+        parsed[key] ||= [];
+        parsed[key].push(value);
+      } else {
+        if (parsed[key] !== undefined) throw new Error(`${argument} may only be provided once.`);
+        parsed[key] = value;
+      }
+      index += 1;
+    } else if (argument.startsWith("--")) throw new Error(`Unknown option: ${argument}.`);
+    else parsed.command.push(argument);
+  }
+
+  return parsed;
+}
+
+function toOptionKey(argument) {
+  return argument.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function validateCommand(parsed) {
+  if (isPloiApiCommand(parsed.command)) {
+    validatePloiApiCommand(parsed);
+    return;
+  }
+
+  const command = parsed.command.join(" ");
+  const allowedOptions = COMMAND_OPTIONS.get(command);
+  if (!allowedOptions) throw new Error(`Unknown command: ${command}. Run gq --help.`);
+
+  const globals = new Set(["command", "help", "json", "project", "config"]);
+  for (const key of Object.keys(parsed)) {
+    if (!globals.has(key) && !allowedOptions.includes(key)) {
+      throw new Error(`--${toFlagName(key)} is not valid for ${command}.`);
+    }
+  }
+}
+
+function toFlagName(key) {
+  return key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+function contextSummary(context) {
+  return {
+    project: context.config.project,
+    projectRoot: context.projectRoot,
+    configPath: context.configPath,
+    invocationDirectory: context.invocationDirectory,
+    machineEnvPath: context.machineEnvPath,
+    ploiConfigured: Boolean(context.env.PLOI_API_TOKEN),
+    cloudflareConfigured: Boolean(context.env.CLOUDFLARE_API_TOKEN),
+  };
+}
+
+function presentPloiServer(server) {
+  return {
+    id: server.id,
+    name: server.name,
+    status: server.status,
+    ip: server.ip_address,
+    provider: server.provider,
+    region: server.region,
+  };
+}
+
+function presentPloiSite(site) {
+  return {
+    id: site.id,
+    domain: site.domain,
+    status: site.status,
+    systemUser: site.system_user,
+    projectRoot: site.project_root,
+    webDirectory: site.web_directory,
+    lastDeployAt: site.last_deploy_at,
+  };
+}
+
+function presentCloudflareAccount(account) {
+  return { id: account.id, name: account.name, type: account.type };
+}
+
+function presentCloudflareZone(zone) {
+  return {
+    id: zone.id,
+    name: zone.name,
+    status: zone.status,
+    account: zone.account?.name,
+    accountId: zone.account?.id,
+    plan: zone.plan?.name,
+  };
+}
+
+function presentDnsRecord(record) {
+  return {
+    id: record.id,
+    type: record.type,
+    name: record.name,
+    content: record.content,
+    proxied: record.proxied,
+    ttl: record.ttl,
+  };
+}
+
+function required(value, label) {
+  if (value === undefined || value === null || String(value).trim() === "") {
+    throw new Error(`${label} is required in gq.ops.json, .env, or a CLI flag.`);
+  }
+  return String(value).trim();
+}
+
+function printHelp(io) {
+  io.out(`gq operations CLI
+
+Usage:
+  gq [global options] <command> [command options]
+
+Project:
+  gq context show
+  gq github actions sync [--dry-run] [--yes]
+
+Ploi:
+  gq ploi servers list
+  gq ploi server show [--server <id>]
+  gq ploi sites list [--server <id>]
+  gq ploi site show [--server <id>] [--site <id>]
+  gq ploi api list [--group <group>] [--search <text>]
+  gq ploi api describe <operation-id>
+  gq ploi api <operation-id> [--path <name=value>] [--query <name=value>]
+      [--data <json> | --data-file <file>] [--all] [--dry-run | --yes]
+
+Cloudflare:
+  gq cloudflare accounts list
+  gq cloudflare zones list [--account <id>]
+  gq cloudflare zone show [--zone <id>]
+  gq cloudflare dns list [--zone <id>] [--name <hostname>] [--type <type>]
+
+Global options:
+  --project <directory>  Select a project explicitly
+  --config <file>        Select a configuration file explicitly
+  --json                 Print machine-readable JSON
+  --version, -v          Show the CLI version
+  --help, -h             Show this help
+
+The CLI searches upward from the current directory for gq.ops.json.`);
+}

package/src/ops/env.mjs

@@ -0,0 +1,73 @@
+import { chmod, readFile, writeFile } from "node:fs/promises";
+
+export function parseEnv(content) {
+  const values = {};
+
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match) continue;
+    values[match[1]] = parseValue(match[2]);
+  }
+
+  return values;
+}
+
+export async function readEnvFile(path) {
+  try {
+    return parseEnv(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+export async function mergeEnvFile(path, updates) {
+  let content = "";
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+
+  const seen = new Set();
+  const lines = content.split(/\r?\n/).map((line) => {
+    const match = line.match(/^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*).*$/);
+    if (!match || !(match[2] in updates)) return line;
+    seen.add(match[2]);
+    return `${match[1]}${match[2]}${match[3]}${formatValue(updates[match[2]])}`;
+  });
+
+  for (const [name, value] of Object.entries(updates)) {
+    if (!seen.has(name)) lines.push(`${name}=${formatValue(value)}`);
+  }
+
+  await writeFile(path, `${lines.join("\n").replace(/\n*$/, "")}\n`, {
+    mode: 0o600,
+  });
+  await chmod(path, 0o600);
+}
+
+function formatValue(value) {
+  const stringValue = String(value ?? "");
+  if (stringValue === "" || /^[A-Za-z0-9_./:@-]+$/.test(stringValue)) {
+    return stringValue;
+  }
+  return `"${stringValue.replace(/["\\$`]/g, "\\$&")}"`;
+}
+
+function parseValue(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("'")) {
+    const closing = trimmed.indexOf("'", 1);
+    if (closing !== -1) return trimmed.slice(1, closing);
+  }
+  if (trimmed.startsWith('"')) {
+    const match = trimmed.match(/^"((?:\\.|[^"\\])*)"/);
+    if (match) {
+      return match[1].replace(/\\([nrt"\\])/g, (_, escaped) => {
+        return { n: "\n", r: "\r", t: "\t", '"': '"', "\\": "\\" }[escaped];
+      });
+    }
+  }
+  return trimmed.replace(/\s+#.*$/, "").trim();
+}

package/src/ops/output.mjs

@@ -0,0 +1,62 @@
+// Writes lines through io.out, the run() seam's stdout.
+export function printValue(io, value, options = {}) {
+  if (options.json) {
+    io.out(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    printTable(io, value);
+    return;
+  }
+
+  printObject(io, value);
+}
+
+function printObject(io, value) {
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === undefined || entry === null || typeof entry === "object") continue;
+    io.out(`${humanize(key)}: ${sanitize(entry)}`);
+  }
+}
+
+function printTable(io, rows) {
+  if (rows.length === 0) {
+    io.out("No results.");
+    return;
+  }
+
+  const keys = uniqueKeys(rows);
+  const widths = keys.map((key) =>
+    Math.max(key.length, ...rows.map((row) => formatCell(row[key]).length)),
+  );
+  io.out(keys.map((key, index) => key.toUpperCase().padEnd(widths[index])).join("  "));
+  io.out(widths.map((width) => "-".repeat(width)).join("  "));
+  for (const row of rows) {
+    io.out(keys.map((key, index) => formatCell(row[key]).padEnd(widths[index])).join("  "));
+  }
+}
+
+function uniqueKeys(rows) {
+  return [...new Set(rows.flatMap((row) => Object.keys(row)))];
+}
+
+function formatCell(value) {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "object") return sanitize(JSON.stringify(value));
+  return sanitize(value);
+}
+
+function sanitize(value) {
+  return [...String(value)]
+    .map((character) => {
+      const codePoint = character.codePointAt(0);
+      const isControl = codePoint <= 31 || (codePoint >= 127 && codePoint <= 159);
+      return isControl ? `\\u${codePoint.toString(16).padStart(4, "0")}` : character;
+    })
+    .join("");
+}
+
+function humanize(value) {
+  return value.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (letter) => letter.toUpperCase());
+}