@dk/jolly 0.1.11 → 0.2.1

package/dist/index.js

@@ -0,0 +1,1826 @@
+// src/index.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+// src/lib/cloud-api.ts
+var DEFAULT_CLOUD_API_BASE = "https://cloud.saleor.io/platform/api";
+function cloudApiBase() {
+  const override = process.env["JOLLY_SALEOR_CLOUD_API_URL"];
+  if (override && override.trim().length > 0) {
+    return override.trim().replace(/\/+$/, "");
+  }
+  return DEFAULT_CLOUD_API_BASE;
+}
+var POLL_INTERVAL_MS = 5000;
+var POLL_TIMEOUT_MS = 480000;
+
+class CloudApiError extends Error {
+  code;
+  httpStatus;
+  constructor(message, code, httpStatus) {
+    super(message);
+    this.name = "CloudApiError";
+    this.code = code;
+    this.httpStatus = httpStatus;
+  }
+}
+async function cloudFetch(url, token, options = {}) {
+  return await fetch(url, {
+    ...options,
+    headers: {
+      Authorization: `Token ${token}`,
+      "Content-Type": "application/json",
+      ...options.headers ?? {}
+    }
+  });
+}
+async function listOrganizations(token) {
+  const response = await cloudFetch(`${cloudApiBase()}/organizations/`, token);
+  if (!response.ok) {
+    throw new CloudApiError(`Failed to list organizations: HTTP ${response.status} ${await response.text()}`, "CLOUD_API_ERROR", response.status);
+  }
+  return await response.json();
+}
+async function listProjects(token, organizationSlug) {
+  const response = await cloudFetch(`${cloudApiBase()}/organizations/${organizationSlug}/projects/`, token);
+  if (!response.ok) {
+    throw new CloudApiError(`Failed to list projects: HTTP ${response.status} ${await response.text()}`, "CLOUD_API_ERROR", response.status);
+  }
+  return await response.json();
+}
+async function createProject(token, organizationSlug, body) {
+  const response = await cloudFetch(`${cloudApiBase()}/organizations/${organizationSlug}/projects/`, token, { method: "POST", body: JSON.stringify(body) });
+  if (!response.ok) {
+    throw new CloudApiError(`Failed to create project: HTTP ${response.status} ${await response.text()}`, "PROJECT_CREATE_FAILED", response.status);
+  }
+  return await response.json();
+}
+async function listProjectServices(token, organizationSlug, projectSlug) {
+  const response = await cloudFetch(`${cloudApiBase()}/organizations/${organizationSlug}/projects/${projectSlug}/services/`, token);
+  if (!response.ok)
+    return [];
+  return await response.json();
+}
+function pickService(services, region = "us-east-1") {
+  const sandbox = services.filter((s) => String(s.service_type ?? "").toUpperCase() === "SANDBOX");
+  const inRegion = sandbox.find((s) => s.region === region);
+  const chosen = inRegion ?? sandbox[0] ?? services[0];
+  return chosen?.name ?? "saleor";
+}
+async function createEnvironment(token, organizationSlug, body) {
+  const response = await cloudFetch(`${cloudApiBase()}/organizations/${organizationSlug}/environments/`, token, { method: "POST", body: JSON.stringify(body) });
+  if (!response.ok) {
+    const text = await response.text();
+    if (response.status >= 400 && response.status < 500 && /domain/i.test(text) && /taken|exists|already|unique|in use|duplicate/i.test(text)) {
+      throw new CloudApiError(`The Cloud API rejected the environment creation: the domain label ` + `"${body.domain_label}" is already taken (HTTP ${response.status}).`, "DOMAIN_LABEL_TAKEN", response.status);
+    }
+    if (response.status >= 400 && response.status < 500 && /limit|quota|exceed/i.test(text)) {
+      throw new CloudApiError("The organization's sandbox environment limit is reached. " + "Delete an unused environment or upgrade the plan, then re-run " + "`jolly create store --create-environment`.", "ENVIRONMENT_LIMIT_REACHED", response.status);
+    }
+    throw new CloudApiError(`Failed to create environment: HTTP ${response.status} ${text}`, "ENVIRONMENT_CREATE_FAILED", response.status);
+  }
+  return await response.json();
+}
+async function listEnvironments(token, organizationSlug) {
+  const response = await cloudFetch(`${cloudApiBase()}/organizations/${organizationSlug}/environments/`, token);
+  if (!response.ok)
+    return [];
+  return await response.json();
+}
+async function getEnvironment(token, organizationSlug, environmentKey) {
+  const response = await cloudFetch(`${cloudApiBase()}/organizations/${organizationSlug}/environments/${environmentKey}/`, token);
+  if (!response.ok)
+    return;
+  return await response.json();
+}
+function taskStatusUrl(taskId) {
+  return `${cloudApiBase()}/service/task-status/${taskId}/`;
+}
+async function pollTaskStatus(taskId, timeoutMs = POLL_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  const url = taskStatusUrl(taskId);
+  for (;; ) {
+    const response = await fetch(url, {
+      headers: { "Content-Type": "application/json" }
+    });
+    if (!response.ok) {
+      throw new CloudApiError(`Task status check failed: HTTP ${response.status} ${await response.text()}`, "TASK_STATUS_FAILED", response.status);
+    }
+    const task = await response.json();
+    const status = String(task.status ?? "").toUpperCase();
+    if (status === "SUCCEEDED")
+      return task;
+    if (status === "FAILED" || status === "ERROR") {
+      throw new CloudApiError(`Environment provisioning task ${taskId} failed: ${JSON.stringify(task)}`, "TASK_FAILED");
+    }
+    if (Date.now() + POLL_INTERVAL_MS > deadline) {
+      throw new CloudApiError(`Environment provisioning task ${taskId} did not reach SUCCEEDED within ${Math.round(timeoutMs / 1000)}s (last status: ${status || "unknown"})`, "TASK_TIMEOUT");
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+}
+function extractDomainUrl(task, environment, domainLabel) {
+  const candidates = [];
+  if (task) {
+    const result = task.result;
+    candidates.push(result?.domain, task.domain, environment?.domain);
+  } else {
+    candidates.push(environment?.domain);
+  }
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.length > 0) {
+      const domain = candidate.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+      return `https://${domain}/graphql/`;
+    }
+  }
+  return `https://${domainLabel}.saleor.cloud/graphql/`;
+}
+async function graphqlFetch(graphqlUrl, token, query, variables) {
+  const response = await fetch(graphqlUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(variables ? { query, variables } : { query })
+  });
+  if (!response.ok) {
+    throw new CloudApiError(`GraphQL request to the Saleor instance failed: HTTP ${response.status}`, "GRAPHQL_HTTP_ERROR", response.status);
+  }
+  const body = await response.json();
+  if (body.errors) {
+    throw new CloudApiError(`GraphQL errors: ${JSON.stringify(body.errors)}`, "GRAPHQL_ERROR");
+  }
+  return body.data ?? {};
+}
+async function queryGetApps(graphqlUrl, token) {
+  const data = await graphqlFetch(graphqlUrl, token, `query GetApps { apps(first: 100) { edges { node { id name } } } }`);
+  const apps = data.apps;
+  const edges = apps?.edges ?? [];
+  return edges.map((edge) => edge.node);
+}
+async function queryPermissionEnum(graphqlUrl, token) {
+  const data = await graphqlFetch(graphqlUrl, token, `query { __type(name: "PermissionEnum") { enumValues { name } } }`);
+  const type = data.__type;
+  const values = type?.enumValues ?? [];
+  return values.map((value) => String(value.name));
+}
+async function createAppToken(graphqlUrl, token, appId) {
+  const data = await graphqlFetch(graphqlUrl, token, `mutation AppTokenCreate($app: ID!) {
+      appTokenCreate(input: { app: $app }) {
+        authToken
+        errors { field message }
+      }
+    }`, { app: appId });
+  const result = data.appTokenCreate;
+  const errors = result?.errors ?? [];
+  if (errors.length > 0) {
+    throw new CloudApiError(`appTokenCreate failed: ${errors.map((e) => e.message).join("; ")}`, "APP_TOKEN_CREATE_FAILED");
+  }
+  const authToken = result?.authToken;
+  if (typeof authToken !== "string" || authToken.length === 0) {
+    throw new CloudApiError("appTokenCreate did not return an authToken", "APP_TOKEN_CREATE_FAILED");
+  }
+  return { authToken };
+}
+async function createLocalApp(graphqlUrl, token, name, permissions) {
+  const data = await graphqlFetch(graphqlUrl, token, `mutation AppCreate($input: AppInput!) {
+      appCreate(input: $input) {
+        authToken
+        app { id name }
+        errors { field message }
+      }
+    }`, { input: { name, permissions } });
+  const result = data.appCreate;
+  const errors = result?.errors ?? [];
+  if (errors.length > 0) {
+    throw new CloudApiError(`appCreate failed: ${errors.map((e) => e.message).join("; ")}`, "APP_CREATE_FAILED");
+  }
+  const app = result?.app;
+  const authToken = result?.authToken;
+  if (typeof authToken !== "string" || authToken.length === 0) {
+    throw new CloudApiError("appCreate did not return an authToken", "APP_CREATE_FAILED");
+  }
+  return { appId: String(app?.id ?? ""), authToken };
+}
+async function acquireAppToken(graphqlUrl, token, appName) {
+  const apps = await withRetries(() => queryGetApps(graphqlUrl, token));
+  if (apps.length > 0) {
+    const { authToken: authToken2 } = await createAppToken(graphqlUrl, token, apps[0].id);
+    return authToken2;
+  }
+  const permissions = await queryPermissionEnum(graphqlUrl, token);
+  const { authToken } = await createLocalApp(graphqlUrl, token, appName, permissions);
+  return authToken;
+}
+async function withRetries(fn, attempts = 5, delayMs = 5000) {
+  let lastError;
+  for (let attempt = 0;attempt < attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt < attempts - 1)
+        await sleep(delayMs);
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/lib/env-file.ts
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+var ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/;
+function loadEnvValues(projectDir) {
+  const path = join(projectDir, ".env");
+  if (!existsSync(path))
+    return {};
+  const values = {};
+  for (const line of readFileSync(path, "utf8").split(`
+`)) {
+    const match = ENV_LINE.exec(line);
+    if (match)
+      values[match[1]] = match[2];
+  }
+  return values;
+}
+function ensureEnvIgnored(projectDir) {
+  const path = join(projectDir, ".gitignore");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const alreadyIgnored = existing.split(`
+`).some((line) => line.trim() === ".env");
+  if (alreadyIgnored)
+    return;
+  const prefix = existing.length > 0 && !existing.endsWith(`
+`) ? `${existing}
+` : existing;
+  writeFileSync(path, `${prefix}.env
+`);
+}
+function writeEnvValues(projectDir, values) {
+  ensureEnvIgnored(projectDir);
+  const path = join(projectDir, ".env");
+  const lines = existsSync(path) ? readFileSync(path, "utf8").split(`
+`) : [];
+  while (lines.length > 0 && lines[lines.length - 1] === "")
+    lines.pop();
+  const pending = { ...values };
+  const updated = lines.map((line) => {
+    const match = ENV_LINE.exec(line);
+    if (match && match[1] in pending) {
+      const replacement = `${match[1]}=${pending[match[1]]}`;
+      delete pending[match[1]];
+      return replacement;
+    }
+    return line;
+  });
+  for (const [name, value] of Object.entries(pending)) {
+    updated.push(`${name}=${value}`);
+  }
+  writeFileSync(path, `${updated.join(`
+`)}
+`);
+  return loadEnvValues(projectDir);
+}
+
+// src/lib/saleor-url.ts
+var CLARIFICATION = "That doesn't look like a Saleor URL I can use. Could you paste your Saleor Dashboard URL, " + "GraphQL API URL, or root Saleor Cloud URL (for example https://your-store.eu.saleor.cloud)?";
+function normalizeSaleorUrl(input) {
+  let url;
+  try {
+    url = new URL(input.trim());
+  } catch {
+    return { endpoint: null, clarification: CLARIFICATION };
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    return { endpoint: null, clarification: CLARIFICATION };
+  }
+  const path = url.pathname.replace(/\/+$/, "");
+  const recognized = path === "" || path === "/graphql" || path === "/dashboard" || /^\/dashboard\//.test(url.pathname);
+  if (!recognized) {
+    return { endpoint: null, clarification: CLARIFICATION };
+  }
+  return { endpoint: `${url.protocol}//${url.host}/graphql/` };
+}
+
+// src/index.ts
+var VALUE_FLAGS = new Set([
+  "token",
+  "url",
+  "name",
+  "domain-label",
+  "region",
+  "organization",
+  "mock-organizations",
+  "publishable-key",
+  "secret-key"
+]);
+function parseArgs(argv) {
+  const positionals = [];
+  const options = {};
+  const flags = new Set;
+  let json = false;
+  let quiet = false;
+  let yes = false;
+  let dryRun = false;
+  let help = false;
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json")
+      json = true;
+    else if (arg === "--quiet")
+      quiet = true;
+    else if (arg === "--yes" || arg === "-y")
+      yes = true;
+    else if (arg === "--dry-run")
+      dryRun = true;
+    else if (arg === "--help" || arg === "-h")
+      help = true;
+    else if (arg.startsWith("--")) {
+      const body = arg.slice(2);
+      const eq = body.indexOf("=");
+      if (eq >= 0) {
+        options[body.slice(0, eq)] = body.slice(eq + 1);
+      } else if (VALUE_FLAGS.has(body) && i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+        options[body] = argv[++i];
+      } else {
+        flags.add(body);
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, json, quiet, yes, dryRun, help, options, flags };
+}
+function envelope(partial) {
+  return {
+    command: partial.command,
+    status: partial.status,
+    summary: partial.summary,
+    data: partial.data ?? {},
+    checks: partial.checks ?? [],
+    nextSteps: partial.nextSteps ?? [],
+    errors: partial.errors ?? []
+  };
+}
+function errorEnvelope(command, summary, errors, extra = {}) {
+  return envelope({
+    command,
+    status: "error",
+    summary,
+    errors,
+    ...extra
+  });
+}
+function statusGlyph(status) {
+  if (status === "success")
+    return "ok";
+  if (status === "warning")
+    return "warn";
+  return "error";
+}
+function checkGlyph(status) {
+  switch (status) {
+    case "pass":
+      return "pass";
+    case "warning":
+      return "warn";
+    case "fail":
+      return "fail";
+    case "skipped":
+      return "skip";
+    default:
+      return "?";
+  }
+}
+function emit(env, args) {
+  if (args.json) {
+    process.stdout.write(JSON.stringify(env) + `
+`);
+  } else {
+    const lines = [];
+    lines.push(`jolly ${env.command}: [${statusGlyph(env.status)}] ${env.summary}`);
+    if (!args.quiet) {
+      for (const check of env.checks) {
+        lines.push(`  - [${checkGlyph(check.status)}] ${check.id}${check.description ? `: ${check.description}` : ""}`);
+      }
+      for (const step of env.nextSteps) {
+        lines.push(`  next: ${step.description}${step.command ? ` (\`${step.command}\`)` : ""}`);
+      }
+      for (const err of env.errors) {
+        lines.push(`  error[${err.code}]: ${err.message}${err.remediation ? ` — ${err.remediation}` : ""}`);
+      }
+    }
+    process.stdout.write(lines.join(`
+`) + `
+`);
+    process.stdout.write(JSON.stringify(env) + `
+`);
+  }
+  return env.status === "error" ? 1 : 0;
+}
+function projectDir() {
+  return process.cwd();
+}
+function envFilePath() {
+  return join2(projectDir(), ".env");
+}
+var DEFAULT_SKILLS = [
+  { id: "jolly", ref: "dmytri/jolly", description: "The Jolly end-to-end playbook" },
+  { id: "saleor-storefront", ref: "saleor/saleor-storefront", description: "Saleor storefront guidance" },
+  { id: "saleor-configurator", ref: "saleor/saleor-configurator", description: "Configuration-as-code guidance" },
+  { id: "storefront-builder", ref: "saleor/storefront-builder", description: "Storefront build guidance" },
+  { id: "saleor-core", ref: "saleor/saleor-core", description: "Saleor core concepts" },
+  { id: "saleor-app", ref: "saleor/saleor-app", description: "Saleor app development guidance" }
+];
+function skillsBaseDir() {
+  return join2(projectDir(), ".claude", "skills");
+}
+function skillInstalledOnDisk(skill) {
+  const dir = join2(skillsBaseDir(), skill.id);
+  return existsSync2(join2(dir, "SKILL.md")) || existsSync2(dir);
+}
+var TOKEN_PAGE = "https://cloud.saleor.io/tokens";
+function loginRiskContext(dryRunAvailable = true) {
+  return {
+    action: "login",
+    target: cloudApiBase(),
+    riskLevel: "medium",
+    categories: ["credential handling"],
+    reversible: true,
+    sideEffects: ["Writes JOLLY_SALEOR_CLOUD_TOKEN to .env when verification permits"],
+    dryRunAvailable
+  };
+}
+async function commandLogin(args) {
+  const command = "login";
+  const token = args.options["token"];
+  const browser = args.flags.has("browser");
+  if (browser) {
+    if (args.dryRun) {
+      return loginBrowserDryRun(command);
+    }
+    return errorEnvelope(command, "Browser-based login is not available in this environment.", [
+      {
+        code: "BROWSER_LOGIN_UNAVAILABLE",
+        message: "No native browser or Playwright callback flow is available to complete browser OAuth.",
+        remediation: `Create a token at ${TOKEN_PAGE} and run \`jolly login --token <value>\`.`
+      }
+    ], { data: { riskContext: loginRiskContext() } });
+  }
+  if (!token) {
+    return errorEnvelope(command, "No token provided and browser login is not available here.", [
+      {
+        code: "NO_LOGIN_METHOD",
+        message: "jolly login needs `--token <value>` in this environment (no browser/Playwright callback flow).",
+        remediation: `Create a token at ${TOKEN_PAGE} and run \`jolly login --token <value>\`.`
+      }
+    ], {
+      nextSteps: [
+        {
+          description: `Create a Saleor Cloud token at ${TOKEN_PAGE}, then run jolly login --token <value>.`,
+          command: "jolly login --token <value>"
+        }
+      ],
+      data: { riskContext: loginRiskContext() }
+    });
+  }
+  if (args.dryRun) {
+    return envelope({
+      command,
+      status: "success",
+      summary: "Previewed token login; nothing was written.",
+      data: { riskContext: loginRiskContext(), dryRun: true },
+      nextSteps: [
+        {
+          description: "Run jolly login --token <value> to verify and store the token.",
+          command: "jolly login --token <value>"
+        }
+      ]
+    });
+  }
+  let orgs;
+  let verificationFailure;
+  try {
+    orgs = await listOrganizations(token);
+  } catch (err) {
+    verificationFailure = err;
+  }
+  if (verificationFailure instanceof CloudApiError && (verificationFailure.httpStatus === 401 || verificationFailure.httpStatus === 403)) {
+    return errorEnvelope(command, "The token was rejected by the Cloud API. Nothing was written.", [
+      {
+        code: "INVALID_TOKEN",
+        message: "Saleor Cloud rejected the token (HTTP 401/403). It was not stored.",
+        remediation: `Create a new token at ${TOKEN_PAGE} and try again.`
+      }
+    ], {
+      checks: [
+        {
+          id: "cloud-token-verification",
+          status: "fail",
+          description: "Token rejected by the Cloud API."
+        }
+      ],
+      data: { riskContext: loginRiskContext() },
+      nextSteps: [
+        { description: `Create a new token at ${TOKEN_PAGE}.`, command: `open ${TOKEN_PAGE}` }
+      ]
+    });
+  }
+  if (verificationFailure) {
+    writeEnvValues(projectDir(), { JOLLY_SALEOR_CLOUD_TOKEN: token });
+    return envelope({
+      command,
+      status: "warning",
+      summary: "Token stored, not verified — the Cloud API was unreachable.",
+      data: {
+        cloudTokenStored: true,
+        verified: false,
+        verification: "stored, not verified",
+        riskContext: loginRiskContext()
+      },
+      checks: [
+        {
+          id: "cloud-token-verification",
+          status: "unknown",
+          description: "stored, not verified — the Cloud API was unreachable."
+        }
+      ],
+      nextSteps: [
+        {
+          description: "Re-run jolly login when the Cloud API is reachable to verify the token.",
+          command: "jolly login --token <value>"
+        }
+      ]
+    });
+  }
+  const orgName = resolveOrgName(orgs ?? []);
+  const values = { JOLLY_SALEOR_CLOUD_TOKEN: token };
+  if (orgName)
+    values["JOLLY_SALEOR_ORGANIZATION"] = orgName;
+  writeEnvValues(projectDir(), values);
+  return envelope({
+    command,
+    status: "success",
+    summary: orgName ? `Token verified and stored. Authenticated as "${orgName}".` : "Token verified and stored.",
+    data: {
+      cloudTokenStored: true,
+      verified: true,
+      accountContext: orgName ?? "unknown",
+      riskContext: loginRiskContext()
+    },
+    checks: [
+      {
+        id: "cloud-token-verification",
+        status: "pass",
+        description: "Token verified against the Cloud API organizations endpoint."
+      }
+    ],
+    nextSteps: [
+      {
+        description: "Run jolly create store to provision a Saleor Cloud environment.",
+        command: "jolly create store --create-environment"
+      }
+    ]
+  });
+}
+function resolveOrgName(orgs) {
+  const first = orgs[0];
+  if (!first)
+    return;
+  const name = first.name ?? first.slug;
+  return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+function base64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function loginBrowserDryRun(command) {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  const state = base64url(randomBytes(16));
+  const redirectUri = "http://127.0.0.1:5375/callback";
+  const authBase = "https://auth.saleor.io/realms/saleor-cloud/protocol/openid-connect/auth";
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: "saleor-cli",
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    state,
+    redirect_uri: redirectUri,
+    scope: "email openid profile"
+  });
+  const authorizationUrl = `${authBase}?${params.toString()}`;
+  const tokenEndpoint = "https://auth.saleor.io/realms/saleor-cloud/protocol/openid-connect/token";
+  const tokensEndpoint = `${cloudApiBase()}/tokens`;
+  const exchangePreview = {
+    tokenExchange: {
+      method: "POST",
+      url: tokenEndpoint,
+      body: {
+        grant_type: "authorization_code",
+        code: "<authorization code from the localhost callback>",
+        code_verifier: "<the PKCE code_verifier>",
+        client_id: "saleor-cli",
+        redirect_uri: redirectUri
+      }
+    },
+    cloudTokenExchange: {
+      method: "POST",
+      url: tokensEndpoint,
+      requestPath: "/platform/api/tokens",
+      body: { id_token: "<the OIDC id_token returned by Keycloak>" }
+    }
+  };
+  return envelope({
+    command,
+    status: "success",
+    summary: "Prepared the browser OAuth authorization URL and code-exchange preview (PKCE). Nothing was written.",
+    data: {
+      dryRun: true,
+      authorizationUrl,
+      pkce: { codeChallengeMethod: "S256", codeChallenge: challenge },
+      state,
+      redirectUri,
+      scope: "email openid profile",
+      clientId: "saleor-cli",
+      responseType: "code",
+      exchangePreview,
+      riskContext: loginRiskContext()
+    },
+    nextSteps: [
+      {
+        description: "Open the authorization URL in a browser to complete OAuth, or use jolly login --token <value>.",
+        command: "jolly login --browser"
+      }
+    ]
+  });
+}
+var MANAGED_AUTH_VARS = [
+  "JOLLY_SALEOR_CLOUD_TOKEN",
+  "JOLLY_SALEOR_APP_TOKEN",
+  "JOLLY_SALEOR_ORGANIZATION"
+];
+function commandLogout(_args) {
+  const command = "logout";
+  const before = loadEnvValues(projectDir());
+  const path = envFilePath();
+  const removed = [];
+  if (existsSync2(path)) {
+    const lineRe = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+    const kept = readFileSync2(path, "utf8").split(`
+`).filter((line) => {
+      const m = lineRe.exec(line);
+      if (m && MANAGED_AUTH_VARS.includes(m[1])) {
+        removed.push(m[1]);
+        return false;
+      }
+      return true;
+    });
+    let text = kept.join(`
+`).replace(/\n+$/, "");
+    text = text.length > 0 ? text + `
+` : "";
+    writeFileSync2(path, text);
+  }
+  return envelope({
+    command,
+    status: "success",
+    summary: removed.length > 0 ? `Removed Jolly-managed Saleor auth values from .env (${[...new Set(removed)].join(", ")}).` : "No Jolly-managed Saleor auth values were present in .env.",
+    data: {
+      removed: [...new Set(removed)],
+      preservedOthers: true
+    },
+    checks: [
+      {
+        id: "auth-cleared",
+        status: "pass",
+        description: "Jolly-managed Saleor auth values are no longer in .env."
+      }
+    ],
+    nextSteps: [
+      {
+        description: "Run jolly login to authenticate again when needed.",
+        command: "jolly login --token <value>"
+      }
+    ]
+  });
+}
+function commandAuthStatus(_args) {
+  const command = "auth status";
+  const values = loadEnvValues(projectDir());
+  const hasCloudToken = Boolean(values["JOLLY_SALEOR_CLOUD_TOKEN"]);
+  const hasAppToken = Boolean(values["JOLLY_SALEOR_APP_TOKEN"]);
+  const org = values["JOLLY_SALEOR_ORGANIZATION"];
+  const accountContext = org && org.length > 0 ? org : "unknown";
+  const checks = [
+    {
+      id: "cloud-token-configured",
+      status: hasCloudToken ? "pass" : "warning",
+      description: hasCloudToken ? "JOLLY_SALEOR_CLOUD_TOKEN is configured in .env." : "JOLLY_SALEOR_CLOUD_TOKEN is not configured."
+    },
+    {
+      id: "app-token-configured",
+      status: hasAppToken ? "pass" : "skipped",
+      description: hasAppToken ? "JOLLY_SALEOR_APP_TOKEN is configured in .env." : "JOLLY_SALEOR_APP_TOKEN is not configured."
+    }
+  ];
+  return envelope({
+    command,
+    status: "success",
+    summary: hasCloudToken ? `Saleor Cloud authentication is configured (account context: ${accountContext}).` : "Saleor Cloud authentication is not configured.",
+    data: {
+      hasCloudToken,
+      hasAppToken,
+      accountContext
+    },
+    checks,
+    nextSteps: hasCloudToken ? [] : [
+      {
+        description: "Run jolly login to configure Saleor Cloud authentication.",
+        command: "jolly login --token <value>"
+      }
+    ]
+  });
+}
+function createStoreRiskContext(target, dryRunAvailable = true) {
+  return {
+    action: "create store",
+    target,
+    riskLevel: "medium",
+    categories: ["billing", "production configuration changes"],
+    reversible: false,
+    sideEffects: [
+      "Creates a Saleor Cloud project and/or environment",
+      "Writes NEXT_PUBLIC_SALEOR_API_URL and JOLLY_SALEOR_APP_TOKEN to .env"
+    ],
+    dryRunAvailable
+  };
+}
+async function commandCreateStore(args) {
+  const command = "create store";
+  const url = args.options["url"];
+  if (url && !args.flags.has("create-environment")) {
+    const normalized = normalizeSaleorUrl(url);
+    if (!normalized.endpoint) {
+      return errorEnvelope(command, "The provided URL could not be normalized to a Saleor GraphQL endpoint.", [
+        {
+          code: "INVALID_SALEOR_URL",
+          message: normalized.clarification ?? "Unrecognized Saleor URL.",
+          remediation: "Paste a Saleor Dashboard, GraphQL, or root Saleor Cloud URL."
+        }
+      ], { data: { riskContext: createStoreRiskContext(url) } });
+    }
+    if (args.dryRun) {
+      return envelope({
+        command,
+        status: "success",
+        summary: "Previewed storing the Saleor endpoint; nothing was written.",
+        data: {
+          dryRun: true,
+          normalizedUrl: normalized.endpoint,
+          riskContext: createStoreRiskContext(normalized.endpoint)
+        },
+        nextSteps: [
+          {
+            description: "Run the command without --dry-run to write the endpoint to .env.",
+            command: `jolly create store --url ${normalized.endpoint}`
+          }
+        ]
+      });
+    }
+    const existingEndpoint = loadEnvValues(projectDir())["NEXT_PUBLIC_SALEOR_API_URL"];
+    if (existingEndpoint && existingEndpoint !== normalized.endpoint && !args.flags.has("yes")) {
+      return envelope({
+        command,
+        status: "warning",
+        summary: "A different NEXT_PUBLIC_SALEOR_API_URL already exists in .env; " + "Jolly paused instead of overwriting it. Re-run with --yes to replace it.",
+        data: {
+          collision: true,
+          existingEndpoint,
+          requestedEndpoint: normalized.endpoint,
+          riskContext: {
+            action: "overwrite Saleor endpoint",
+            target: "NEXT_PUBLIC_SALEOR_API_URL in .env",
+            riskLevel: "medium",
+            categories: ["destructive operations", "production configuration changes"],
+            reversible: false,
+            sideEffects: [
+              `Replaces the existing endpoint "${existingEndpoint}" with "${normalized.endpoint}"`
+            ],
+            dryRunAvailable: true
+          }
+        },
+        checks: [
+          {
+            id: "saleor-endpoint-collision",
+            status: "warning",
+            description: "An existing NEXT_PUBLIC_SALEOR_API_URL would be overwritten; not replaced without --yes."
+          }
+        ],
+        nextSteps: [
+          {
+            description: "Re-run with --yes to overwrite the existing endpoint (the agent decides).",
+            command: `jolly create store --url ${normalized.endpoint} --yes`
+          }
+        ]
+      });
+    }
+    writeEnvValues(projectDir(), { NEXT_PUBLIC_SALEOR_API_URL: normalized.endpoint });
+    return envelope({
+      command,
+      status: "success",
+      summary: "Stored the Saleor GraphQL endpoint as NEXT_PUBLIC_SALEOR_API_URL.",
+      data: {
+        stored: true,
+        envVar: "NEXT_PUBLIC_SALEOR_API_URL",
+        riskContext: createStoreRiskContext(normalized.endpoint)
+      },
+      checks: [
+        {
+          id: "saleor-endpoint-stored",
+          status: "pass",
+          description: "NEXT_PUBLIC_SALEOR_API_URL written to .env."
+        }
+      ],
+      nextSteps: [
+        {
+          description: "Run jolly create app-token to acquire a Saleor app token.",
+          command: "jolly create app-token"
+        }
+      ]
+    });
+  }
+  const token = process.env["JOLLY_SALEOR_CLOUD_TOKEN"];
+  const region = args.options["region"] ?? "us-east-1";
+  const orgOverride = args.options["organization"];
+  const name = args.options["name"];
+  const domainLabel = args.options["domain-label"];
+  if (!token) {
+    return errorEnvelope(command, "No Saleor Cloud token is configured; cannot provision a store.", [
+      {
+        code: "MISSING_CLOUD_TOKEN",
+        message: "JOLLY_SALEOR_CLOUD_TOKEN is required to create a Saleor Cloud store.",
+        remediation: "Run `jolly login --token <value>` first."
+      }
+    ], {
+      data: {
+        riskContext: createStoreRiskContext(`${cloudApiBase()} (organization unresolved)`)
+      },
+      nextSteps: [
+        {
+          description: "Run jolly login to acquire a Saleor Cloud token.",
+          command: "jolly login --token <value>"
+        }
+      ]
+    });
+  }
+  let orgs;
+  const mock = args.flags.has("mock-organizations") ? "" : args.options["mock-organizations"] ?? undefined;
+  if (mock !== undefined) {
+    orgs = (mock.length > 0 ? mock.split(",") : ["org-one", "org-two"]).map((slug) => ({
+      slug: slug.trim()
+    }));
+  } else {
+    try {
+      orgs = await listOrganizations(token);
+    } catch (err) {
+      return cloudErrorEnvelope(command, err, createStoreRiskContext(cloudApiBase()));
+    }
+  }
+  let selectedOrg;
+  let multiOrgWarning = false;
+  if (orgOverride) {
+    selectedOrg = orgOverride;
+  } else if (orgs.length === 0) {
+    return errorEnvelope(command, "The Cloud token has access to no organizations.", [
+      {
+        code: "NO_ORGANIZATIONS",
+        message: "No organizations are accessible with this Cloud token.",
+        remediation: "Confirm the token's permissions at https://cloud.saleor.io/tokens."
+      }
+    ], { data: { riskContext: createStoreRiskContext(cloudApiBase()) } });
+  } else if (orgs.length === 1) {
+    selectedOrg = orgs[0].slug;
+  } else {
+    selectedOrg = orgs[0].slug;
+    multiOrgWarning = true;
+  }
+  const resolvedTarget = `${cloudApiBase()}/organizations/${selectedOrg}/environments/`;
+  const effectiveName = name ?? "jolly-store";
+  const effectiveDomainLabel = domainLabel ?? effectiveName;
+  if (args.dryRun) {
+    const requestBody = {
+      name: effectiveName,
+      project: effectiveName,
+      domain_label: effectiveDomainLabel,
+      database_population: "sample",
+      service: "saleor",
+      region
+    };
+    const env = envelope({
+      command,
+      status: multiOrgWarning ? "warning" : "success",
+      summary: multiOrgWarning ? `Previewed environment creation in "${selectedOrg}" (token has multiple organizations).` : `Previewed environment creation in organization "${selectedOrg}".`,
+      data: {
+        dryRun: true,
+        method: "POST",
+        requestPath: `/platform/api/organizations/${selectedOrg}/environments/`,
+        requestUrl: resolvedTarget,
+        organization: selectedOrg,
+        region,
+        databaseTemplate: "sample",
+        requestBody,
+        riskContext: createStoreRiskContext(resolvedTarget)
+      },
+      nextSteps: [
+        {
+          description: "Run the command without --dry-run to create the environment.",
+          command: "jolly create store --create-environment"
+        }
+      ]
+    });
+    if (multiOrgWarning) {
+      env.data["availableOrganizations"] = orgs.map((o) => o.slug);
+      env.data["selectedOrganization"] = selectedOrg;
+    }
+    return env;
+  }
+  if (multiOrgWarning) {
+    return envelope({
+      command,
+      status: "warning",
+      summary: `The Cloud token has multiple organizations; Jolly selected "${selectedOrg}".`,
+      data: {
+        availableOrganizations: orgs.map((o) => o.slug),
+        selectedOrganization: selectedOrg,
+        riskContext: createStoreRiskContext(resolvedTarget)
+      },
+      checks: [
+        {
+          id: "organization-selection",
+          status: "warning",
+          description: `Selected "${selectedOrg}". Re-run with --organization <slug> if this is wrong.`
+        }
+      ],
+      nextSteps: [
+        {
+          description: `Re-run with --organization <slug> to choose explicitly. Available: ${orgs.map((o) => o.slug).join(", ")}.`,
+          command: `jolly create store --create-environment --organization ${selectedOrg}`
+        }
+      ]
+    });
+  }
+  try {
+    const projects = await listProjects(token, selectedOrg);
+    const existingProject = projects.find((p) => p.name === effectiveName) ?? projects[0];
+    let project;
+    let projectCreated;
+    if (existingProject) {
+      project = existingProject;
+      projectCreated = false;
+    } else {
+      project = await createProject(token, selectedOrg, {
+        name: effectiveName,
+        plan: "dev",
+        region
+      });
+      projectCreated = true;
+    }
+    const projectSlug = project.slug ?? project.name;
+    const existingEnvs = await listEnvironments(token, selectedOrg);
+    const existingEnv = existingEnvs.find((e) => e.domain_label === effectiveDomainLabel || e.name === effectiveName);
+    let domainUrl;
+    let environmentCreated;
+    let environment;
+    if (existingEnv) {
+      domainUrl = extractDomainUrl(undefined, existingEnv, effectiveDomainLabel);
+      environmentCreated = false;
+      environment = existingEnv;
+    } else {
+      const services = await listProjectServices(token, selectedOrg, projectSlug);
+      const service = pickService(services, region);
+      const created = await createEnvironment(token, selectedOrg, {
+        name: effectiveName,
+        project: projectSlug,
+        domain_label: effectiveDomainLabel,
+        database_population: "sample",
+        service,
+        region
+      });
+      const taskId = created.task_id;
+      let task = undefined;
+      if (taskId)
+        task = await pollTaskStatus(String(taskId));
+      const refreshed = created.key ? await getEnvironment(token, selectedOrg, String(created.key)) : created;
+      domainUrl = extractDomainUrl(task, refreshed, effectiveDomainLabel);
+      environmentCreated = true;
+      environment = refreshed ?? created;
+    }
+    const environmentKey = typeof environment.key === "string" ? environment.key : undefined;
+    const environmentName = typeof environment.name === "string" ? environment.name : effectiveName;
+    const values = { NEXT_PUBLIC_SALEOR_API_URL: domainUrl };
+    let appTokenStored = false;
+    try {
+      const appToken = await acquireAppToken(domainUrl, token, "Jolly Setup");
+      values["JOLLY_SALEOR_APP_TOKEN"] = appToken;
+      appTokenStored = true;
+    } catch {}
+    writeEnvValues(projectDir(), values);
+    return envelope({
+      command,
+      status: "success",
+      summary: `Saleor Cloud environment ready in "${selectedOrg}".`,
+      data: {
+        organization: selectedOrg,
+        organizationSlug: selectedOrg,
+        environmentName,
+        ...environmentKey ? { environmentKey } : {},
+        projectCreated,
+        projectReused: !projectCreated,
+        environmentCreated,
+        graphqlEndpointStored: true,
+        appTokenStored,
+        riskContext: createStoreRiskContext(resolvedTarget)
+      },
+      checks: [
+        {
+          id: "environment-provisioned",
+          status: "pass",
+          description: environmentCreated ? "Environment created and verified via task status." : "Existing environment reused."
+        },
+        {
+          id: "app-token-acquired",
+          status: appTokenStored ? "pass" : "unknown",
+          description: appTokenStored ? "App token acquired and stored." : "App token not acquired; run jolly create app-token."
+        }
+      ],
+      nextSteps: appTokenStored ? [] : [
+        {
+          description: "Run jolly create app-token to acquire an app token.",
+          command: "jolly create app-token"
+        }
+      ]
+    });
+  } catch (err) {
+    return cloudErrorEnvelope(command, err, createStoreRiskContext(resolvedTarget));
+  }
+}
+function cloudErrorEnvelope(command, err, riskContext) {
+  const code = err instanceof CloudApiError ? err.code : "CLOUD_API_ERROR";
+  const message = err instanceof Error ? err.message : String(err);
+  return errorEnvelope(command, "The Cloud API request failed. Nothing was created.", [
+    {
+      code,
+      message,
+      remediation: code === "ENVIRONMENT_LIMIT_REACHED" ? "Delete an unused environment or upgrade the plan, then re-run." : code === "DOMAIN_LABEL_TAKEN" ? "Choose a different domain label with --domain-label <label>." : "Confirm the Cloud token and that the Cloud API is reachable."
+    }
+  ], { data: { riskContext } });
+}
+function appTokenRiskContext(target) {
+  return {
+    action: "create app-token",
+    target,
+    riskLevel: "medium",
+    categories: ["credential handling"],
+    reversible: true,
+    sideEffects: [
+      "Creates a Saleor app token via GraphQL",
+      "Writes JOLLY_SALEOR_APP_TOKEN to .env"
+    ],
+    dryRunAvailable: true
+  };
+}
+async function commandCreateAppToken(args) {
+  const command = "create app-token";
+  const token = process.env["JOLLY_SALEOR_CLOUD_TOKEN"];
+  const values = loadEnvValues(projectDir());
+  const instanceUrl = args.options["url"] ?? values["NEXT_PUBLIC_SALEOR_API_URL"] ?? process.env["NEXT_PUBLIC_SALEOR_API_URL"];
+  if (args.dryRun) {
+    return envelope({
+      command,
+      status: "success",
+      summary: "Previewed app token creation; no GraphQL mutation was sent.",
+      data: {
+        dryRun: true,
+        instanceUrl: instanceUrl ?? null,
+        riskContext: appTokenRiskContext(instanceUrl ?? "unresolved Saleor GraphQL endpoint")
+      },
+      nextSteps: [
+        {
+          description: "Run the command without --dry-run to create and store the app token.",
+          command: "jolly create app-token"
+        }
+      ]
+    });
+  }
+  if (!token) {
+    return errorEnvelope(command, "No Saleor Cloud token is configured; cannot acquire an app token.", [
+      {
+        code: "MISSING_CLOUD_TOKEN",
+        message: "JOLLY_SALEOR_CLOUD_TOKEN is required to acquire an app token.",
+        remediation: "Run `jolly login --token <value>` first."
+      }
+    ], { data: { riskContext: appTokenRiskContext(instanceUrl ?? "unresolved") } });
+  }
+  if (!instanceUrl) {
+    return errorEnvelope(command, "No Saleor GraphQL instance URL is available.", [
+      {
+        code: "MISSING_INSTANCE_URL",
+        message: "A Saleor GraphQL endpoint (NEXT_PUBLIC_SALEOR_API_URL) is required.",
+        remediation: "Run `jolly create store` first, or pass --url <graphql-endpoint>."
+      }
+    ], { data: { riskContext: appTokenRiskContext("unresolved") } });
+  }
+  try {
+    const appToken = await acquireAppToken(instanceUrl, token, "Jolly Setup");
+    writeEnvValues(projectDir(), { JOLLY_SALEOR_APP_TOKEN: appToken });
+    return envelope({
+      command,
+      status: "success",
+      summary: "App token acquired and stored as JOLLY_SALEOR_APP_TOKEN.",
+      data: {
+        appTokenStored: true,
+        instanceUrl,
+        riskContext: appTokenRiskContext(instanceUrl)
+      },
+      checks: [
+        {
+          id: "app-token-acquired",
+          status: "pass",
+          description: "App token created via GraphQL and stored."
+        }
+      ]
+    });
+  } catch (err) {
+    const code = err instanceof CloudApiError ? err.code : "APP_TOKEN_ACQUISITION_FAILED";
+    return errorEnvelope(command, "Could not acquire an app token. Nothing was stored.", [
+      {
+        code,
+        message: err instanceof Error ? err.message : String(err),
+        remediation: "Confirm the instance is reachable and the Cloud token has access; or create an app in the Saleor Dashboard."
+      }
+    ], { data: { riskContext: appTokenRiskContext(instanceUrl) } });
+  }
+}
+function stripeRiskContext() {
+  return {
+    action: "create stripe",
+    target: ".env (JOLLY_STRIPE_PUBLISHABLE_KEY, JOLLY_STRIPE_SECRET_KEY)",
+    riskLevel: "medium",
+    categories: ["payment setup", "credential handling"],
+    reversible: true,
+    sideEffects: ["Writes Stripe test-mode keys to .env"],
+    dryRunAvailable: true
+  };
+}
+function commandCreateStripe(args) {
+  const command = "create stripe";
+  const publishable = args.options["publishable-key"];
+  const secret = args.options["secret-key"];
+  if (!publishable || !secret) {
+    return errorEnvelope(command, "Both --publishable-key and --secret-key are required.", [
+      {
+        code: "MISSING_STRIPE_KEYS",
+        message: "create stripe needs --publishable-key <pk_test_...> and --secret-key <sk_test_...>.",
+        remediation: "Copy both test-mode keys from the Stripe Dashboard and pass them as flags."
+      }
+    ], { data: { riskContext: stripeRiskContext() } });
+  }
+  if (args.dryRun) {
+    return envelope({
+      command,
+      status: "success",
+      summary: "Previewed Stripe key storage; nothing was written.",
+      data: { dryRun: true, riskContext: stripeRiskContext() },
+      nextSteps: [
+        {
+          description: "Run the command without --dry-run to write the Stripe keys to .env.",
+          command: "jolly create stripe --publishable-key <pk> --secret-key <sk>"
+        }
+      ]
+    });
+  }
+  writeEnvValues(projectDir(), {
+    JOLLY_STRIPE_PUBLISHABLE_KEY: publishable,
+    JOLLY_STRIPE_SECRET_KEY: secret
+  });
+  return envelope({
+    command,
+    status: "success",
+    summary: "Stored Stripe test-mode keys as JOLLY_STRIPE_PUBLISHABLE_KEY and JOLLY_STRIPE_SECRET_KEY.",
+    data: { stored: true, riskContext: stripeRiskContext() },
+    checks: [
+      { id: "stripe-keys-stored", status: "pass", description: "Stripe test-mode keys written to .env." }
+    ],
+    nextSteps: [
+      {
+        description: "Configure Saleor's Stripe integration via @saleor/configurator, guided by the Jolly skill.",
+        command: "jolly doctor stripe"
+      }
+    ]
+  });
+}
+var CREATE_SUBCOMMANDS = ["store", "app-token", "stripe"];
+function commandCreateHelp() {
+  const command = "create --help";
+  return envelope({
+    command,
+    status: "success",
+    summary: "jolly create exposes the plumbing subcommands store, app-token, and stripe.",
+    data: {
+      subcommands: [
+        {
+          name: "store",
+          description: "Provision a Saleor Cloud store/environment, or store a pasted Saleor URL."
+        },
+        {
+          name: "app-token",
+          description: "Acquire a Saleor app token via GraphQL and write it to .env."
+        },
+        { name: "stripe", description: "Write Stripe test-mode keys to .env." }
+      ],
+      note: "Other setup work is run by your agent via the official CLIs, guided by the Jolly skill."
+    },
+    nextSteps: [
+      {
+        description: "Run jolly create store --create-environment to provision a Saleor Cloud environment.",
+        command: "jolly create store --create-environment"
+      }
+    ]
+  });
+}
+async function commandCreate(args) {
+  const sub = args.positionals[1];
+  if (!sub || args.help || sub === "help") {
+    return commandCreateHelp();
+  }
+  switch (sub) {
+    case "store":
+      return commandCreateStore(args);
+    case "app-token":
+      return commandCreateAppToken(args);
+    case "stripe":
+      return commandCreateStripe(args);
+    default:
+      return errorEnvelope("create", `Unknown create subcommand "${sub}".`, [
+        {
+          code: "UNKNOWN_CREATE_SUBCOMMAND",
+          message: `"${sub}" is not a create subcommand. Valid: ${CREATE_SUBCOMMANDS.join(", ")}.`,
+          remediation: "Run `jolly create --help` to list available subcommands."
+        }
+      ]);
+  }
+}
+function installSkill(skill) {
+  const result = spawnSync("npx", ["--yes", "skills", "add", skill.ref], {
+    cwd: projectDir(),
+    encoding: "utf8",
+    timeout: 60000
+  });
+  return { installed: result.status === 0, stderr: result.stderr ?? undefined };
+}
+function mergeMcpJson() {
+  const path = join2(projectDir(), ".mcp.json");
+  const endpoint = loadEnvValues(projectDir())["NEXT_PUBLIC_SALEOR_API_URL"] ?? process.env["NEXT_PUBLIC_SALEOR_API_URL"] ?? "https://your-store.saleor.cloud/graphql/";
+  const jollyEntry = {
+    command: "npx",
+    args: ["-y", "mcp-graphql"],
+    env: { ENDPOINT: endpoint }
+  };
+  let config = { mcpServers: {} };
+  if (existsSync2(path)) {
+    try {
+      config = JSON.parse(readFileSync2(path, "utf8"));
+    } catch {
+      return { merged: false, warning: "Existing .mcp.json is not valid JSON; left untouched." };
+    }
+  }
+  const servers = config["mcpServers"] && typeof config["mcpServers"] === "object" ? config["mcpServers"] : {};
+  servers["saleor-graphql"] = jollyEntry;
+  config["mcpServers"] = servers;
+  writeFileSync2(path, JSON.stringify(config, null, 2) + `
+`);
+  return { merged: true };
+}
+function mergeAgentsMd() {
+  const path = join2(projectDir(), "AGENTS.md");
+  const begin = "<!-- jolly:begin -->";
+  const end = "<!-- jolly:end -->";
+  const section = `${begin}
+## Jolly
+
+This project uses Jolly to set up a Saleor storefront. Run \`jolly start\` to
+bootstrap, then follow the Jolly skill to drive the official CLIs.
+${end}`;
+  let existing = existsSync2(path) ? readFileSync2(path, "utf8") : "";
+  if (existing.includes(begin) && existing.includes(end)) {
+    existing = existing.replace(new RegExp(`${begin}[\\s\\S]*?${end}`), section);
+  } else {
+    existing = existing.length > 0 ? `${existing.replace(/\n+$/, "")}
+
+${section}
+` : `${section}
+`;
+  }
+  writeFileSync2(path, existing);
+}
+function commandInit(_args) {
+  const command = "init";
+  const checks = [];
+  const installFailures = [];
+  for (const skill of DEFAULT_SKILLS) {
+    const already = skillInstalledOnDisk(skill);
+    if (!already) {
+      installSkill(skill);
+    }
+    const present = skillInstalledOnDisk(skill);
+    checks.push({
+      id: `skill-${skill.id}`,
+      status: present ? "pass" : "fail",
+      description: present ? `${skill.id} present on disk${already ? " (already installed)" : ""}.` : `${skill.id} could not be verified on disk after npx skills add.`
+    });
+    if (!present)
+      installFailures.push(skill.id);
+  }
+  const mcp = mergeMcpJson();
+  checks.push({
+    id: "mcp-config",
+    status: mcp.merged ? "pass" : "warning",
+    description: mcp.merged ? "Merged saleor-graphql entry into .mcp.json." : mcp.warning ?? "Could not merge .mcp.json."
+  });
+  mergeAgentsMd();
+  checks.push({
+    id: "agents-md",
+    status: "pass",
+    description: "Merged the Jolly section into AGENTS.md."
+  });
+  if (installFailures.length > 0) {
+    return errorEnvelope(command, `Some skills could not be verified on disk: ${installFailures.join(", ")}.`, [
+      {
+        code: "SKILL_INSTALL_FAILED",
+        message: `Failed to install or verify: ${installFailures.join(", ")}.`,
+        remediation: "Ensure `npx skills` is available and the network is reachable, then re-run `jolly init`."
+      }
+    ], { checks });
+  }
+  return envelope({
+    command,
+    status: "success",
+    summary: `Installed and verified ${DEFAULT_SKILLS.length} skills; merged .mcp.json and AGENTS.md.`,
+    data: {
+      skills: DEFAULT_SKILLS.map((s) => s.id),
+      mcpMerged: mcp.merged,
+      agentsMdMerged: true
+    },
+    checks,
+    nextSteps: [
+      {
+        description: "Run jolly start to bootstrap setup and get the ordered playbook.",
+        command: "jolly start"
+      }
+    ]
+  });
+}
+var DOCTOR_GROUPS = ["skills", "saleor", "storefront", "deployment", "stripe"];
+function commandDoctor(args) {
+  const group = args.positionals[1];
+  const values = loadEnvValues(projectDir());
+  const checks = [];
+  if (group && !DOCTOR_GROUPS.includes(group)) {
+    return errorEnvelope("doctor", `Unknown doctor group "${group}".`, [
+      {
+        code: "UNKNOWN_DOCTOR_GROUP",
+        message: `"${group}" is not a doctor group. Valid: ${DOCTOR_GROUPS.join(", ")}.`,
+        remediation: "Run `jolly doctor` for all checks or name a valid group."
+      }
+    ]);
+  }
+  const wants = (g) => !group || group === g;
+  if (!group) {
+    checks.push({
+      id: "cli-available",
+      status: "pass",
+      description: `Jolly CLI is available (Node ${process.versions.node}).`
+    });
+  }
+  if (wants("skills")) {
+    for (const skill of DEFAULT_SKILLS) {
+      const present = skillInstalledOnDisk(skill);
+      checks.push({
+        id: `skill-${skill.id}`,
+        status: present ? "pass" : "fail",
+        description: present ? `${skill.id} present.` : `${skill.id} not installed.`,
+        command: present ? undefined : "jolly init"
+      });
+    }
+  }
+  if (wants("saleor")) {
+    const hasCloud = Boolean(values["JOLLY_SALEOR_CLOUD_TOKEN"] ?? process.env["JOLLY_SALEOR_CLOUD_TOKEN"]);
+    const hasEndpoint = Boolean(values["NEXT_PUBLIC_SALEOR_API_URL"] ?? process.env["NEXT_PUBLIC_SALEOR_API_URL"]);
+    const hasApp = Boolean(values["JOLLY_SALEOR_APP_TOKEN"] ?? process.env["JOLLY_SALEOR_APP_TOKEN"]);
+    checks.push({
+      id: "saleor-cloud-token",
+      status: hasCloud ? "pass" : "fail",
+      description: hasCloud ? "JOLLY_SALEOR_CLOUD_TOKEN present." : "No Saleor Cloud token configured.",
+      command: hasCloud ? undefined : "jolly login --token <value>"
+    });
+    checks.push({
+      id: "saleor-endpoint",
+      status: hasEndpoint ? "unknown" : "fail",
+      description: hasEndpoint ? "NEXT_PUBLIC_SALEOR_API_URL is set; live connectivity not verified in this run." : "No Saleor GraphQL endpoint configured.",
+      command: hasEndpoint ? undefined : "jolly create store --url <graphql-endpoint>"
+    });
+    checks.push({
+      id: "saleor-app-token",
+      status: hasApp ? "pass" : "fail",
+      description: hasApp ? "JOLLY_SALEOR_APP_TOKEN present." : "No Saleor app token configured.",
+      command: hasApp ? undefined : "jolly create app-token"
+    });
+  }
+  if (wants("storefront")) {
+    const storefrontPresent = existsSync2(join2(projectDir(), "package.json")) && existsSync2(join2(projectDir(), "src", "app"));
+    checks.push({
+      id: "storefront-present",
+      status: storefrontPresent ? "unknown" : "fail",
+      description: storefrontPresent ? "A project structure exists; Paper storefront readiness not verified in this run." : "No Paper storefront detected locally.",
+      command: storefrontPresent ? undefined : "Clone saleor/storefront (Paper) per the Jolly skill."
+    });
+  }
+  if (wants("deployment")) {
+    checks.push({
+      id: "deployment-status",
+      status: "skipped",
+      description: "Deployment is run by your agent via the Vercel CLI; Jolly does not contact Vercel.",
+      command: "npx vercel"
+    });
+  }
+  if (wants("stripe")) {
+    const hasPub = Boolean(values["JOLLY_STRIPE_PUBLISHABLE_KEY"] ?? process.env["JOLLY_STRIPE_PUBLISHABLE_KEY"]);
+    const hasSecret = Boolean(values["JOLLY_STRIPE_SECRET_KEY"] ?? process.env["JOLLY_STRIPE_SECRET_KEY"]);
+    checks.push({
+      id: "stripe-keys",
+      status: hasPub && hasSecret ? "pass" : "fail",
+      description: hasPub && hasSecret ? "Stripe test-mode keys present in .env." : "Stripe keys not configured.",
+      command: hasPub && hasSecret ? undefined : "jolly create stripe --publishable-key <pk> --secret-key <sk>"
+    });
+  }
+  const hasFail = checks.some((c) => c.status === "fail");
+  const hasWarn = checks.some((c) => c.status === "warning");
+  const status = hasFail ? "error" : hasWarn ? "warning" : "success";
+  const nextSteps = checks.filter((c) => (c.status === "fail" || c.status === "warning") && c.command).map((c) => ({ description: c.description ?? `Address ${c.id}.`, command: c.command }));
+  return envelope({
+    command: group ? `doctor ${group}` : "doctor",
+    status,
+    summary: status === "success" ? "All performed checks passed." : status === "warning" ? "Some checks need attention." : "Some checks failed; see next steps.",
+    data: { group: group ?? "all" },
+    checks,
+    nextSteps,
+    errors: hasFail ? [
+      {
+        code: "DOCTOR_CHECKS_FAILED",
+        message: "One or more diagnostics failed.",
+        remediation: "Address the failing checks listed in nextSteps."
+      }
+    ] : []
+  });
+}
+function commandSkills(args) {
+  const command = "skills";
+  const sub = args.positionals[1];
+  if (sub === "install" || sub === "update") {
+    const checks2 = DEFAULT_SKILLS.map((skill) => {
+      const already = skillInstalledOnDisk(skill);
+      if (!already && sub === "install")
+        installSkill(skill);
+      const present = skillInstalledOnDisk(skill);
+      return {
+        id: `skill-${skill.id}`,
+        status: present ? "pass" : "fail",
+        description: present ? `${skill.id} present.` : `${skill.id} not verified on disk.`
+      };
+    });
+    const failed = checks2.filter((c) => c.status === "fail").map((c) => c.id);
+    return envelope({
+      command: `skills ${sub}`,
+      status: failed.length > 0 ? "warning" : "success",
+      summary: failed.length > 0 ? `Some skills not verified: ${failed.join(", ")}.` : `Skills ${sub === "install" ? "installed" : "checked"}.`,
+      data: { skills: DEFAULT_SKILLS.map((s) => s.id) },
+      checks: checks2
+    });
+  }
+  const checks = DEFAULT_SKILLS.map((skill) => {
+    const present = skillInstalledOnDisk(skill);
+    return {
+      id: `skill-${skill.id}`,
+      status: present ? "pass" : "unknown",
+      description: `${skill.description}${present ? " (installed)" : " (not installed)"}.`
+    };
+  });
+  return envelope({
+    command,
+    status: "success",
+    summary: `Jolly manages ${DEFAULT_SKILLS.length} skills (install via npx skills add).`,
+    data: {
+      skills: DEFAULT_SKILLS.map((s) => ({ id: s.id, ref: s.ref, description: s.description }))
+    },
+    checks,
+    nextSteps: [
+      {
+        description: "Run jolly init (or jolly start) to install the skill set.",
+        command: "jolly init"
+      }
+    ]
+  });
+}
+function commandUpgrade(_args) {
+  const command = "upgrade";
+  const checks = DEFAULT_SKILLS.map((skill) => {
+    const present = skillInstalledOnDisk(skill);
+    return {
+      id: `skill-${skill.id}`,
+      status: present ? "pass" : "skipped",
+      description: present ? `${skill.id} is managed; checked for updates.` : `${skill.id} not installed; skipped.`
+    };
+  });
+  const paperPresent = existsSync2(join2(projectDir(), "paper-version.json"));
+  checks.push({
+    id: "paper-baseline",
+    status: paperPresent ? "unknown" : "skipped",
+    description: paperPresent ? "Paper storefront detected; Jolly plans Paper migrations but does not auto-apply them in v1." : "No Paper storefront detected; nothing to plan."
+  });
+  return envelope({
+    command,
+    status: "success",
+    summary: "Checked Jolly-managed skills and guidance for updates; Paper changes are plan-only.",
+    data: {
+      skillsChecked: DEFAULT_SKILLS.map((s) => s.id),
+      paperBaselineDetected: paperPresent,
+      paperAutoApply: false
+    },
+    checks,
+    nextSteps: paperPresent ? [{ description: "Review the Paper upgrade plan before applying any migration manually." }] : []
+  });
+}
+function startPlan() {
+  return [
+    {
+      stage: "init",
+      effects: {
+        directoriesCreated: [".claude/skills"],
+        filesWritten: [".mcp.json", "AGENTS.md"],
+        networkHostsContacted: ["github.com"],
+        repositoriesCloned: []
+      },
+      riskContext: {
+        action: "init",
+        target: "local project (skills, .mcp.json, AGENTS.md)",
+        riskLevel: "low",
+        categories: [],
+        reversible: true,
+        sideEffects: ["Installs skills, writes .mcp.json and AGENTS.md"],
+        dryRunAvailable: true
+      }
+    },
+    {
+      stage: "auth",
+      effects: {
+        directoriesCreated: [],
+        filesWritten: [".env"],
+        networkHostsContacted: ["cloud.saleor.io", "auth.saleor.io"],
+        repositoriesCloned: []
+      },
+      riskContext: {
+        action: "login",
+        target: cloudApiBase(),
+        riskLevel: "medium",
+        categories: ["credential handling"],
+        reversible: true,
+        sideEffects: ["Acquires and stores a Saleor Cloud token in .env"],
+        dryRunAvailable: true
+      }
+    },
+    {
+      stage: "store",
+      effects: {
+        directoriesCreated: [],
+        filesWritten: [".env"],
+        networkHostsContacted: ["cloud.saleor.io"],
+        repositoriesCloned: []
+      },
+      riskContext: createStoreRiskContext(`${cloudApiBase()}/organizations/{organization}/environments/`)
+    },
+    {
+      stage: "storefront",
+      effects: {
+        directoriesCreated: ["storefront"],
+        filesWritten: [],
+        networkHostsContacted: ["github.com"],
+        repositoriesCloned: ["saleor/storefront"]
+      },
+      riskContext: {
+        action: "clone storefront",
+        target: "saleor/storefront (Paper) → storefront/",
+        riskLevel: "low",
+        categories: [],
+        reversible: true,
+        sideEffects: ["Clones the Saleor Paper storefront repository into storefront/"],
+        dryRunAvailable: true
+      }
+    },
+    {
+      stage: "deploy",
+      effects: {
+        directoriesCreated: [],
+        filesWritten: [],
+        networkHostsContacted: [],
+        repositoriesCloned: []
+      }
+    }
+  ];
+}
+function startPlaybook() {
+  return [
+    {
+      description: "1. Bootstrap: jolly init installed skills, wrote .mcp.json, and ran doctor.",
+      command: "jolly init"
+    },
+    { description: "2. Authenticate Saleor Cloud.", command: "jolly login --token <value>" },
+    {
+      description: "3. Provision a Saleor Cloud store/environment.",
+      command: "jolly create store --create-environment"
+    },
+    { description: "4. Acquire a Saleor app token.", command: "jolly create app-token" },
+    {
+      description: "5. Clone the Paper storefront with git and install with pnpm, guided by the Jolly skill.",
+      command: "git clone https://github.com/saleor/storefront"
+    },
+    {
+      description: "6. Apply the Jolly starter recipe with @saleor/configurator, guided by the Jolly skill."
+    },
+    {
+      description: "7. Deploy with the Vercel CLI under your own vercel login session.",
+      command: "npx vercel"
+    },
+    {
+      description: "8. Provide Stripe test-mode keys.",
+      command: "jolly create stripe --publishable-key <pk> --secret-key <sk>"
+    },
+    { description: "9. Verify operational readiness.", command: "jolly doctor" }
+  ];
+}
+function commandStartDryRun() {
+  const command = "start";
+  const plan = startPlan();
+  return envelope({
+    command,
+    status: "success",
+    summary: "Previewed the jolly start plan. No files were written and no network requests were made.",
+    data: {
+      dryRun: true,
+      plan
+    },
+    checks: [
+      {
+        id: "start-dry-run",
+        status: "skipped",
+        description: "This is a dry-run preview; no stage was executed."
+      }
+    ],
+    nextSteps: [
+      {
+        description: "Run jolly start to execute the plan and get the ordered playbook.",
+        command: "jolly start"
+      }
+    ]
+  });
+}
+function commandStart(args) {
+  if (args.dryRun)
+    return commandStartDryRun();
+  const command = "start";
+  const initEnv = commandInit(args);
+  const doctorEnv = commandDoctor({
+    ...args,
+    positionals: ["doctor"],
+    json: true,
+    dryRun: false
+  });
+  const checks = [
+    ...initEnv.checks.map((c) => ({ ...c, id: `init-${c.id}` })),
+    ...doctorEnv.checks.map((c) => ({ ...c, id: `doctor-${c.id}` }))
+  ];
+  const bootstrapFailed = initEnv.status === "error";
+  const status = bootstrapFailed ? "error" : "warning";
+  return envelope({
+    command,
+    status,
+    summary: bootstrapFailed ? "Bootstrap failed; see errors. No downstream stage was performed." : "Bootstrap complete (skills, scaffold, doctor). Follow the playbook to finish setup.",
+    data: {
+      bootstrap: {
+        skillsInstalled: !bootstrapFailed,
+        mcpMerged: initEnv.data["mcpMerged"] ?? false,
+        agentsMdMerged: initEnv.data["agentsMdMerged"] ?? false,
+        doctorRan: true
+      },
+      playbook: startPlaybook().map((s) => s.description),
+      pendingStages: ["storefront", "recipe", "deploy"]
+    },
+    checks,
+    nextSteps: startPlaybook(),
+    errors: bootstrapFailed ? initEnv.errors : []
+  });
+}
+function commandHelp() {
+  return envelope({
+    command: "help",
+    status: "success",
+    summary: "Jolly — Ahoy, agent. Go build a store. (a tool by Dmytri Kleiner; not an official Saleor/Vercel/Stripe product)",
+    data: {
+      commands: [
+        "login",
+        "logout",
+        "auth status",
+        "init",
+        "start",
+        "doctor",
+        "upgrade",
+        "skills",
+        "create store",
+        "create app-token",
+        "create stripe"
+      ],
+      globalFlags: ["--json", "--quiet", "--yes/-y", "--dry-run"]
+    },
+    nextSteps: [
+      {
+        description: "Run jolly start to bootstrap setup and get the ordered playbook.",
+        command: "jolly start"
+      }
+    ]
+  });
+}
+async function dispatch(args) {
+  const cmd = args.positionals[0];
+  switch (cmd) {
+    case undefined:
+    case "help":
+      return commandHelp();
+    case "login":
+      return commandLogin(args);
+    case "logout":
+      return commandLogout(args);
+    case "auth":
+      if (args.positionals[1] === "status")
+        return commandAuthStatus(args);
+      return errorEnvelope("auth", `Unknown auth subcommand "${args.positionals[1] ?? ""}".`, [
+        {
+          code: "UNKNOWN_AUTH_SUBCOMMAND",
+          message: 'The only auth subcommand is "status".',
+          remediation: "Run `jolly auth status`."
+        }
+      ]);
+    case "create":
+      return commandCreate(args);
+    case "init":
+      return commandInit(args);
+    case "start":
+      return commandStart(args);
+    case "doctor":
+      return commandDoctor(args);
+    case "upgrade":
+      return commandUpgrade(args);
+    case "skills":
+      return commandSkills(args);
+    default:
+      return errorEnvelope(cmd, `Unknown command "${cmd}".`, [
+        {
+          code: "UNKNOWN_COMMAND",
+          message: `"${cmd}" is not a Jolly command.`,
+          remediation: "Run `jolly help` to list available commands."
+        }
+      ]);
+  }
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  let env;
+  try {
+    env = await dispatch(args);
+  } catch (err) {
+    env = errorEnvelope(args.positionals[0] ?? "jolly", "An unexpected error occurred.", [
+      {
+        code: "UNEXPECTED_ERROR",
+        message: err instanceof Error ? err.message : String(err),
+        remediation: "Re-run with --json and report the error code."
+      }
+    ]);
+  }
+  const exitCode = emit(env, args);
+  process.exit(exitCode);
+}
+main();