@neutrome-labs/merchantduo 0.0.2

package/README.md

@@ -0,0 +1,19 @@
+# MerchantDuo CLI
+Simple terminal interface to deploy Magento 2 stores onto the Cloudflare Edge.
+
+# How To Use
+
+pnpx @neutrome-labs/merchantduo help
+
+```
+MerchantDuo developer CLI
+
+Options:
+  -h, --help         display help for command
+
+Commands:
+  ping               Ping the API to check if it's available
+  sandbox [options]  Provision fresh Magento instance in the Cloudflare Cloud
+  clone [options]    Clone current Magento installation into Cloudflare Cloud
+  help [command]     display help for command
+```

package/dist/index.js

@@ -0,0 +1,457 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { config } from "dotenv";
+
+// src/logging.ts
+import {
+  configureSync,
+  getConsoleSink,
+  getLogger,
+  getTextFormatter
+} from "@logtape/logtape";
+function configureCliLogging() {
+  configureSync({
+    sinks: {
+      console: getConsoleSink({
+        formatter: getTextFormatter({
+          timestamp: "time",
+          level: "full",
+          category: "."
+        })
+      })
+    },
+    loggers: [
+      {
+        category: ["merchantduo", "cli"],
+        sinks: ["console"],
+        lowestLevel: "info"
+      }
+    ]
+  });
+}
+function cliLogger(category) {
+  return getLogger([
+    "merchantduo",
+    "cli",
+    ...Array.isArray(category) ? category : [category]
+  ]);
+}
+
+// src/program.ts
+import { Command } from "commander";
+
+// src/http.ts
+var apiBaseUrl = void 0;
+var logger = cliLogger("http");
+function getApiBaseUrl() {
+  if (!apiBaseUrl) {
+    apiBaseUrl = process.env["API_BASE_URL"];
+    if (!apiBaseUrl) {
+      return "https://api.merchantduo.com";
+    }
+    apiBaseUrl = apiBaseUrl.replace(/\/$/, "");
+    logger.info("configured API base URL", { apiBaseUrl });
+  }
+  return apiBaseUrl;
+}
+async function getText(url3) {
+  return requestText(url3, { method: "GET" });
+}
+async function requestText(url3, init) {
+  const requestUrl = getApiBaseUrl() + url3;
+  logger.debug("sending text request", { url: requestUrl, init });
+  const startedAt = Date.now();
+  const response = await fetch(requestUrl, {
+    ...init,
+    headers: {
+      accept: "text/plain",
+      ...init.headers
+    }
+  });
+  logger.debug("received text response", {
+    url: requestUrl,
+    status: response.status,
+    statusText: response.statusText,
+    durationMs: Date.now() - startedAt
+  });
+  if (!response.ok) {
+    logger.warn("text request failed", {
+      url: requestUrl,
+      status: response.status,
+      statusText: response.statusText
+    });
+    throw new Error(
+      `Request failed with ${response.status} ${response.statusText}`
+    );
+  }
+  return await response.text();
+}
+async function getJson(url3) {
+  return requestJson(url3, { method: "GET" });
+}
+async function postJson(url3, payload) {
+  return requestJson(url3, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(payload)
+  });
+}
+async function requestJson(url3, init) {
+  const requestUrl = getApiBaseUrl() + url3;
+  logger.debug("sending JSON request", { url: requestUrl, init });
+  const startedAt = Date.now();
+  const response = await fetch(requestUrl, {
+    ...init,
+    headers: {
+      accept: "application/json",
+      ...init.headers
+    }
+  });
+  const responseText = await response.text();
+  const responseBody = parseJsonResponse(responseText);
+  logger.debug("received JSON response", {
+    url: requestUrl,
+    status: response.status,
+    statusText: response.statusText,
+    durationMs: Date.now() - startedAt,
+    responseText
+  });
+  if (!response.ok) {
+    const details = typeof responseBody === "object" && responseBody !== null ? JSON.stringify(responseBody) : responseText;
+    logger.warn("JSON request failed", {
+      url: requestUrl,
+      status: response.status,
+      statusText: response.statusText,
+      details
+    });
+    throw new Error(
+      `Request failed with ${response.status} ${response.statusText}${details ? `: ${details}` : ""}`
+    );
+  }
+  return responseBody ?? responseText;
+}
+function parseJsonResponse(text) {
+  if (!text) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/commands/ping.ts
+var logger2 = cliLogger(["command", "ping"]);
+function registerPingCommand(program) {
+  program.command("ping").description("Ping the API to check if it's available").action(async () => {
+    logger2.info("ping command started");
+    const response = await getText("/");
+    logger2.info("ping command completed");
+    console.log(response);
+  });
+}
+
+// src/commands/sandbox.ts
+import { appendFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z as z6 } from "zod";
+
+// ../provisioner/types/provision.ts
+import * as z5 from "zod";
+
+// ../../src/templates/index.ts
+import * as z from "zod";
+var TemplatesSchema = z.enum(["magento24"]);
+
+// ../../src/types/instance.ts
+import * as z4 from "zod";
+
+// ../../src/types/service-mysql.ts
+import * as z2 from "zod";
+var BundledMysqlServiceConfigSchema = z2.object({
+  kind: z2.literal("bundled")
+});
+var HyperdriveMysqlConfigSchema = z2.object({
+  kind: z2.literal("hyperdrive"),
+  connectionString: z2.string()
+});
+var MysqlServiceConfigSchema = z2.union([
+  BundledMysqlServiceConfigSchema,
+  HyperdriveMysqlConfigSchema
+]);
+
+// ../../src/types/service-opensearch.ts
+import * as z3 from "zod";
+var BundledOpensearchServiceConfigSchema = z3.object({
+  kind: z3.literal("bundled")
+});
+var RemoteOpensearchConfigSchema = z3.object({
+  kind: z3.literal("remote"),
+  url: z3.url(),
+  port: z3.number().optional(),
+  username: z3.string().optional(),
+  password: z3.string().optional()
+}).transform((x) => {
+  const url3 = new URL(x.url);
+  return {
+    ...x,
+    port: x.port ?? Number(url3.port || (url3.protocol === "https:" ? 443 : 80))
+  };
+});
+var OpensearchServiceConfigSchema = z3.union([
+  BundledOpensearchServiceConfigSchema,
+  RemoteOpensearchConfigSchema
+]);
+
+// ../../src/types/instance.ts
+var InstanceGradeSchema = z4.enum(["sandbox", "instance"]);
+var InstanceConfigSchema = z4.object({
+  instanceId: z4.string(),
+  baseUrl: z4.url().optional(),
+  grade: InstanceGradeSchema.default("sandbox"),
+  template: TemplatesSchema,
+  deadline: z4.date().optional().describe("deadline for the instance"),
+  services: z4.object({
+    mysql: MysqlServiceConfigSchema,
+    opensearch: OpensearchServiceConfigSchema
+  }),
+  snapshots: z4.object({
+    fs: z4.string().describe("filesystem (src) snapshot reference").optional(),
+    app: z4.string().describe("app (db) snapshot reference").optional()
+  }).optional(),
+  mounts: z4.object({
+    media: z4.string().describe("path to the pub/media r2 mount")
+  }).optional(),
+  tools: z4.object({
+    codeserver: z4.boolean().default(false),
+    phpMyAdmin: z4.boolean().default(false),
+    opencode: z4.boolean().default(false)
+  }).optional()
+});
+var InstanceStateSchema = z4.enum([
+  "stopped",
+  "scheduled",
+  "booting",
+  "provision/deps",
+  "provision/deploy",
+  "provision/install",
+  "starting",
+  "ready",
+  "hibernating",
+  "failed"
+]);
+
+// ../provisioner/types/provision.ts
+var ProvisionRequestSchema = z5.object({
+  grade: InstanceGradeSchema.default("sandbox"),
+  template: TemplatesSchema,
+  base64AuthJson: z5.string().optional()
+});
+var ProvisionResponseSchema = z5.object({
+  jobId: z5.string()
+});
+var JobStatusResponseSchema = z5.object({
+  jobId: z5.string(),
+  status: z5.enum([
+    "queued",
+    "running",
+    "paused",
+    "errored",
+    "terminated",
+    "complete",
+    "waiting",
+    "waitingForPause",
+    "unknown"
+  ]),
+  logs: z5.array(z5.string()),
+  error: z5.string().optional(),
+  instanceId: z5.string(),
+  instanceState: InstanceStateSchema.optional(),
+  urls: z5.record(z5.string(), z5.string()).optional()
+});
+
+// src/commands/sandbox.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "complete",
+  "errored",
+  "terminated"
+]);
+var logger3 = cliLogger(["command", "sandbox"]);
+function registerSandboxCommand(program) {
+  program.command("sandbox").description("Provision fresh Magento instance in the Cloudflare Cloud").option("--template <name>", "Template to provision", "magento24").option("--base64AuthJson <value>", "Base64-encoded auth.json content").option(
+    "--poll-interval <ms>",
+    "Job polling interval in milliseconds",
+    "30000"
+  ).action(async (options) => {
+    logger3.info("sandbox command started", { options });
+    await provision(options);
+  });
+}
+async function provision(options) {
+  logger3.debug("parsing sandbox command options", { options });
+  const pollIntervalMs = parsePollInterval(options.pollInterval);
+  const payload = ProvisionRequestSchema.parse({
+    grade: "sandbox",
+    template: options.template,
+    ...options.base64AuthJson ? { base64AuthJson: options.base64AuthJson } : {}
+  });
+  logger3.debug("provision request payload prepared", { payload });
+  const responseBody = ProvisionResponseSchema.parse(
+    await postJson("/v1/provision", payload)
+  );
+  logger3.info("provision job created", { jobId: responseBody.jobId });
+  const logFile = join(
+    tmpdir(),
+    `merchantduo-provision-${responseBody.jobId}.log`
+  );
+  await writeFile(logFile, "");
+  logger3.info("provision log file initialized", { logFile });
+  console.log(`Provision job started: ${responseBody.jobId}`);
+  let previousJob;
+  while (!previousJob || !TERMINAL_STATUSES.has(previousJob.status)) {
+    logger3.debug("polling provision job", {
+      jobId: responseBody.jobId,
+      pollIntervalMs
+    });
+    const job = JobStatusResponseSchema.parse(
+      await getJson(`/v1/job/${encodeURIComponent(responseBody.jobId)}`)
+    );
+    await writeJobDiff(previousJob, job, logFile);
+    previousJob = job;
+    if (!TERMINAL_STATUSES.has(previousJob.status)) {
+      logger3.debug("provision job still running", {
+        jobId: previousJob.jobId,
+        status: previousJob.status,
+        instanceState: previousJob.instanceState
+      });
+      await sleep(pollIntervalMs);
+    }
+  }
+  console.log(logFile);
+  logger3.info("provision job reached terminal status", {
+    jobId: previousJob.jobId,
+    status: previousJob.status,
+    instanceState: previousJob.instanceState,
+    logFile
+  });
+  if (previousJob.status !== "complete") {
+    logger3.error("provision job failed", {
+      jobId: previousJob.jobId,
+      status: previousJob.status,
+      error: previousJob.error
+    });
+    throw new Error(
+      `Provision job ${previousJob.jobId} ended with ${previousJob.status}${previousJob.error ? `: ${previousJob.error}` : ""}`
+    );
+  }
+}
+function parsePollInterval(value) {
+  const pollIntervalMs = z6.coerce.number().int().positive().parse(value);
+  logger3.debug("parsed poll interval", { value, pollIntervalMs });
+  return pollIntervalMs;
+}
+async function writeJobDiff(previousJob, job, logFile) {
+  if (!previousJob || previousJob.status !== job.status) {
+    logger3.info("job status changed", {
+      previous: previousJob?.status,
+      current: job.status
+    });
+    console.log(`Job status: ${job.status}`);
+  }
+  if (!previousJob || previousJob.instanceState !== job.instanceState) {
+    logger3.info("instance state changed", {
+      previous: previousJob?.instanceState,
+      current: job.instanceState
+    });
+    console.log(`Instance state: ${job.instanceState ?? "unknown"}`);
+  }
+  if (job.error && previousJob?.error !== job.error) {
+    logger3.error("job reported error", {
+      jobId: job.jobId,
+      error: job.error
+    });
+    console.error(`Job error: ${job.error}`);
+  }
+  printUrlDiff(previousJob?.urls, job.urls);
+  await appendLogDiff(previousJob?.logs ?? [], job.logs, logFile);
+}
+function printUrlDiff(previousUrls, currentUrls) {
+  if (!currentUrls) {
+    return;
+  }
+  for (const [port, url3] of Object.entries(currentUrls)) {
+    if (previousUrls?.[port] !== url3) {
+      logger3.info("job URL changed", { port, url: url3 });
+      console.log(`URL ${port}: ${url3}`);
+    }
+  }
+}
+async function appendLogDiff(previousLogs, currentLogs, logFile) {
+  const firstChangedIndex = currentLogs.findIndex(
+    (log, index) => previousLogs[index] !== log
+  );
+  if (firstChangedIndex === -1) {
+    logger3.debug("no new provision logs to append", { logFile });
+    return;
+  }
+  const text = currentLogs.slice(firstChangedIndex).map((log) => log.endsWith("\n") ? log : `${log}
+`).join("");
+  await appendFile(logFile, text);
+  logger3.debug("appended provision logs", {
+    logFile,
+    firstChangedIndex,
+    appendedCount: currentLogs.length - firstChangedIndex,
+    bytes: text.length
+  });
+}
+async function sleep(ms) {
+  logger3.debug("sleeping before next poll", { ms });
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/commands/clone.ts
+var logger4 = cliLogger(["command", "clone"]);
+function registerCloneCommand(program) {
+  program.command("clone").description("Clone current Magento installation into Cloudflare Cloud").option("--with-database", "Clone database", true).option("--with-media", "Clone media", false).option("--with-catalog", "Clone catalog", true).option("--with-customers", "Clone customers", false).option("--with-sales", "Clone sales", false).option("--ttl <TTL>", "Instance deadline: 1h, 1d, 3d, 7d, infinite", "1h").option(
+    "--poll-interval <ms>",
+    "Job polling interval in milliseconds",
+    "2000"
+  ).action(async (options) => {
+    logger4.info("clone command started", { options });
+    await clone(options);
+  });
+}
+async function clone(options) {
+  logger4.warn("clone command is not implemented", { options });
+}
+
+// src/program.ts
+function createCli() {
+  cliLogger("program").debug("creating command tree");
+  const program = new Command();
+  program.name("merchantduo").description("MerchantDuo developer CLI").showHelpAfterError().showSuggestionAfterError();
+  registerPingCommand(program);
+  registerSandboxCommand(program);
+  registerCloneCommand(program);
+  cliLogger("program").debug("registered commands", {
+    commands: program.commands.map((command) => command.name())
+  });
+  return program;
+}
+
+// src/index.ts
+try {
+  config({ quiet: true });
+  configureCliLogging();
+  cliLogger("startup").debug("starting CLI", { argv: process.argv });
+  await createCli().parseAsync(process.argv);
+} catch (error) {
+  cliLogger("startup").error("CLI command failed", { error });
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@neutrome-labs/merchantduo",
+  "version": "0.0.2",
+  "description": "",
+  "main": "dist/index.js",
+  "bin": {
+    "merchantduo": "dist/index.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "proprietary",
+  "type": "module",
+  "dependencies": {
+    "@logtape/logtape": "2.1.1",
+    "commander": "14.0.3",
+    "dotenv": "17.4.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.1",
+    "esbuild": "0.27.3",
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit && esbuild src/index.ts --bundle --packages=external --platform=node --format=esm --target=node22 --outfile=dist/index.js && chmod +x dist/index.js",
+    "dev": "pnpm run build && node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/commands/clone.ts

@@ -0,0 +1,40 @@
+import type { Command } from "commander";
+import { z } from "zod";
+import { getJson, postJson } from "../http";
+import { cliLogger } from "../logging";
+
+const logger = cliLogger(["command", "clone"]);
+
+interface CloneOptions {
+  withDatabase: boolean;
+  withMedia: boolean;
+  withCatalog: boolean;
+  withCustomers: boolean;
+  withSales: boolean;
+  pollInterval: string;
+}
+
+export function registerCloneCommand(program: Command): void {
+  program
+    .command("clone")
+    .description("Clone current Magento installation into Cloudflare Cloud")
+    .option("--with-database", "Clone database", true)
+    .option("--with-media", "Clone media", false)
+    .option("--with-catalog", "Clone catalog", true)
+    .option("--with-customers", "Clone customers", false)
+    .option("--with-sales", "Clone sales", false)
+    .option("--ttl <TTL>", "Instance deadline: 1h, 1d, 3d, 7d, infinite", "1h")
+    .option(
+      "--poll-interval <ms>",
+      "Job polling interval in milliseconds",
+      "2000",
+    )
+    .action(async (options: CloneOptions) => {
+      logger.info("clone command started", { options });
+      await clone(options);
+    });
+}
+
+async function clone(options: CloneOptions): Promise<void> {
+  logger.warn("clone command is not implemented", { options });
+}

package/src/commands/ping.ts

@@ -0,0 +1,17 @@
+import type { Command } from "commander";
+import { getText } from "../http";
+import { cliLogger } from "../logging";
+
+const logger = cliLogger(["command", "ping"]);
+
+export function registerPingCommand(program: Command): void {
+  program
+    .command("ping")
+    .description("Ping the API to check if it's available")
+    .action(async () => {
+      logger.info("ping command started");
+      const response = await getText("/");
+      logger.info("ping command completed");
+      console.log(response);
+    });
+}

package/src/commands/sandbox.ts

@@ -0,0 +1,201 @@
+import { appendFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Command } from "commander";
+import { z } from "zod";
+import {
+  JobStatusResponseSchema,
+  ProvisionRequestSchema,
+  ProvisionResponseSchema,
+  type JobStatusResponse,
+} from "../../../provisioner/types/provision";
+import { getJson, postJson } from "../http";
+import { cliLogger } from "../logging";
+
+const TERMINAL_STATUSES = new Set<JobStatusResponse["status"]>([
+  "complete",
+  "errored",
+  "terminated",
+]);
+
+interface SandboxOptions {
+  template?: string;
+  base64AuthJson?: string;
+  pollInterval: string;
+}
+
+const logger = cliLogger(["command", "sandbox"]);
+
+export function registerSandboxCommand(program: Command): void {
+  program
+    .command("sandbox")
+    .description("Provision fresh Magento instance in the Cloudflare Cloud")
+    .option("--template <name>", "Template to provision", "magento24")
+    .option("--base64AuthJson <value>", "Base64-encoded auth.json content")
+    .option(
+      "--poll-interval <ms>",
+      "Job polling interval in milliseconds",
+      "30000",
+    )
+    .action(async (options: SandboxOptions) => {
+      logger.info("sandbox command started", { options });
+      await provision(options);
+    });
+}
+
+async function provision(options: SandboxOptions): Promise<void> {
+  logger.debug("parsing sandbox command options", { options });
+  const pollIntervalMs = parsePollInterval(options.pollInterval);
+  const payload = ProvisionRequestSchema.parse({
+    grade: "sandbox",
+    template: options.template,
+    ...(options.base64AuthJson
+      ? { base64AuthJson: options.base64AuthJson }
+      : {}),
+  });
+  logger.debug("provision request payload prepared", { payload });
+
+  const responseBody = ProvisionResponseSchema.parse(
+    await postJson("/v1/provision", payload),
+  );
+  logger.info("provision job created", { jobId: responseBody.jobId });
+  const logFile = join(
+    tmpdir(),
+    `merchantduo-provision-${responseBody.jobId}.log`,
+  );
+  await writeFile(logFile, "");
+  logger.info("provision log file initialized", { logFile });
+
+  console.log(`Provision job started: ${responseBody.jobId}`);
+
+  let previousJob: JobStatusResponse | undefined;
+  while (!previousJob || !TERMINAL_STATUSES.has(previousJob.status)) {
+    logger.debug("polling provision job", {
+      jobId: responseBody.jobId,
+      pollIntervalMs,
+    });
+    const job = JobStatusResponseSchema.parse(
+      await getJson(`/v1/job/${encodeURIComponent(responseBody.jobId)}`),
+    );
+
+    await writeJobDiff(previousJob, job, logFile);
+    previousJob = job;
+
+    if (!TERMINAL_STATUSES.has(previousJob.status)) {
+      logger.debug("provision job still running", {
+        jobId: previousJob.jobId,
+        status: previousJob.status,
+        instanceState: previousJob.instanceState,
+      });
+      await sleep(pollIntervalMs);
+    }
+  }
+
+  console.log(logFile);
+  logger.info("provision job reached terminal status", {
+    jobId: previousJob.jobId,
+    status: previousJob.status,
+    instanceState: previousJob.instanceState,
+    logFile,
+  });
+
+  if (previousJob.status !== "complete") {
+    logger.error("provision job failed", {
+      jobId: previousJob.jobId,
+      status: previousJob.status,
+      error: previousJob.error,
+    });
+    throw new Error(
+      `Provision job ${previousJob.jobId} ended with ${previousJob.status}${
+        previousJob.error ? `: ${previousJob.error}` : ""
+      }`,
+    );
+  }
+}
+
+function parsePollInterval(value: string): number {
+  const pollIntervalMs = z.coerce.number().int().positive().parse(value);
+  logger.debug("parsed poll interval", { value, pollIntervalMs });
+  return pollIntervalMs;
+}
+
+async function writeJobDiff(
+  previousJob: JobStatusResponse | undefined,
+  job: JobStatusResponse,
+  logFile: string,
+): Promise<void> {
+  if (!previousJob || previousJob.status !== job.status) {
+    logger.info("job status changed", {
+      previous: previousJob?.status,
+      current: job.status,
+    });
+    console.log(`Job status: ${job.status}`);
+  }
+
+  if (!previousJob || previousJob.instanceState !== job.instanceState) {
+    logger.info("instance state changed", {
+      previous: previousJob?.instanceState,
+      current: job.instanceState,
+    });
+    console.log(`Instance state: ${job.instanceState ?? "unknown"}`);
+  }
+
+  if (job.error && previousJob?.error !== job.error) {
+    logger.error("job reported error", {
+      jobId: job.jobId,
+      error: job.error,
+    });
+    console.error(`Job error: ${job.error}`);
+  }
+
+  printUrlDiff(previousJob?.urls, job.urls);
+  await appendLogDiff(previousJob?.logs ?? [], job.logs, logFile);
+}
+
+function printUrlDiff(
+  previousUrls: JobStatusResponse["urls"] | undefined,
+  currentUrls: JobStatusResponse["urls"] | undefined,
+): void {
+  if (!currentUrls) {
+    return;
+  }
+
+  for (const [port, url] of Object.entries(currentUrls)) {
+    if (previousUrls?.[port] !== url) {
+      logger.info("job URL changed", { port, url });
+      console.log(`URL ${port}: ${url}`);
+    }
+  }
+}
+
+async function appendLogDiff(
+  previousLogs: string[],
+  currentLogs: string[],
+  logFile: string,
+): Promise<void> {
+  const firstChangedIndex = currentLogs.findIndex(
+    (log, index) => previousLogs[index] !== log,
+  );
+
+  if (firstChangedIndex === -1) {
+    logger.debug("no new provision logs to append", { logFile });
+    return;
+  }
+
+  const text = currentLogs
+    .slice(firstChangedIndex)
+    .map((log) => (log.endsWith("\n") ? log : `${log}\n`))
+    .join("");
+  await appendFile(logFile, text);
+  logger.debug("appended provision logs", {
+    logFile,
+    firstChangedIndex,
+    appendedCount: currentLogs.length - firstChangedIndex,
+    bytes: text.length,
+  });
+}
+
+async function sleep(ms: number): Promise<void> {
+  logger.debug("sleeping before next poll", { ms });
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/http.ts

@@ -0,0 +1,123 @@
+import { cliLogger } from "./logging";
+
+let apiBaseUrl: string | undefined = undefined;
+const logger = cliLogger("http");
+
+function getApiBaseUrl(): string {
+  if (!apiBaseUrl) {
+    apiBaseUrl = process.env["API_BASE_URL"];
+    if (!apiBaseUrl) {
+      return "https://api.merchantduo.com";
+    }
+    apiBaseUrl = apiBaseUrl.replace(/\/$/, "");
+    logger.info("configured API base URL", { apiBaseUrl });
+  }
+  return apiBaseUrl;
+}
+
+export async function getText(url: string): Promise<string> {
+  return requestText(url, { method: "GET" });
+}
+
+async function requestText(url: string, init: RequestInit): Promise<string> {
+  const requestUrl = getApiBaseUrl() + url;
+  logger.debug("sending text request", { url: requestUrl, init });
+  const startedAt = Date.now();
+  const response = await fetch(requestUrl, {
+    ...init,
+    headers: {
+      accept: "text/plain",
+      ...init.headers,
+    },
+  });
+  logger.debug("received text response", {
+    url: requestUrl,
+    status: response.status,
+    statusText: response.statusText,
+    durationMs: Date.now() - startedAt,
+  });
+
+  if (!response.ok) {
+    logger.warn("text request failed", {
+      url: requestUrl,
+      status: response.status,
+      statusText: response.statusText,
+    });
+    throw new Error(
+      `Request failed with ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return await response.text();
+}
+
+export async function getJson(url: string): Promise<unknown> {
+  return requestJson(url, { method: "GET" });
+}
+
+export async function postJson(
+  url: string,
+  payload: unknown,
+): Promise<unknown> {
+  return requestJson(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  });
+}
+
+async function requestJson(url: string, init: RequestInit): Promise<unknown> {
+  const requestUrl = getApiBaseUrl() + url;
+  logger.debug("sending JSON request", { url: requestUrl, init });
+  const startedAt = Date.now();
+  const response = await fetch(requestUrl, {
+    ...init,
+    headers: {
+      accept: "application/json",
+      ...init.headers,
+    },
+  });
+
+  const responseText = await response.text();
+  const responseBody = parseJsonResponse(responseText);
+  logger.debug("received JSON response", {
+    url: requestUrl,
+    status: response.status,
+    statusText: response.statusText,
+    durationMs: Date.now() - startedAt,
+    responseText,
+  });
+
+  if (!response.ok) {
+    const details =
+      typeof responseBody === "object" && responseBody !== null
+        ? JSON.stringify(responseBody)
+        : responseText;
+
+    logger.warn("JSON request failed", {
+      url: requestUrl,
+      status: response.status,
+      statusText: response.statusText,
+      details,
+    });
+    throw new Error(
+      `Request failed with ${response.status} ${response.statusText}${details ? `: ${details}` : ""}`,
+    );
+  }
+
+  return responseBody ?? responseText;
+}
+
+function parseJsonResponse(text: string): unknown {
+  if (!text) {
+    return undefined;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { config } from "dotenv";
+import { configureCliLogging, cliLogger } from "./logging";
+import { createCli } from "./program";
+
+try {
+  config({ quiet: true });
+  configureCliLogging();
+  cliLogger("startup").debug("starting CLI", { argv: process.argv });
+  await createCli().parseAsync(process.argv);
+} catch (error) {
+  cliLogger("startup").error("CLI command failed", { error });
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/src/logging.ts

@@ -0,0 +1,35 @@
+import {
+  configureSync,
+  getConsoleSink,
+  getLogger,
+  getTextFormatter,
+} from "@logtape/logtape";
+
+export function configureCliLogging(): void {
+  configureSync({
+    sinks: {
+      console: getConsoleSink({
+        formatter: getTextFormatter({
+          timestamp: "time",
+          level: "full",
+          category: ".",
+        }),
+      }),
+    },
+    loggers: [
+      {
+        category: ["merchantduo", "cli"],
+        sinks: ["console"],
+        lowestLevel: "info",
+      },
+    ],
+  });
+}
+
+export function cliLogger(category: string | string[]) {
+  return getLogger([
+    "merchantduo",
+    "cli",
+    ...(Array.isArray(category) ? category : [category]),
+  ]);
+}

package/src/program.ts

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { registerPingCommand } from "./commands/ping";
+import { registerSandboxCommand } from "./commands/sandbox";
+import { registerCloneCommand } from "./commands/clone";
+import { cliLogger } from "./logging";
+
+export function createCli(): Command {
+  cliLogger("program").debug("creating command tree");
+  const program = new Command();
+
+  program
+    .name("merchantduo")
+    .description("MerchantDuo developer CLI")
+    .showHelpAfterError()
+    .showSuggestionAfterError();
+
+  registerPingCommand(program);
+  registerSandboxCommand(program);
+  registerCloneCommand(program);
+  cliLogger("program").debug("registered commands", {
+    commands: program.commands.map((command) => command.name()),
+  });
+
+  return program;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}