@dk/jolly 0.1.11 → 0.2.0

package/README.md

@@ -4,9 +4,13 @@ Ahoy, agent. Go build a store.
 
 Jolly is a homepage + `npx` CLI + agent setup workflow that helps a customer's own agent set up and iterate on an end-to-end Saleor Cloud storefront.
 
+Jolly is a tool by Dmytri Kleiner that helps agents set up a store quickly using
+Saleor, Vercel and Stripe. It is not an official product of Saleor, Vercel, or
+Stripe. The package is `@dk/jolly`; the homepage is https://jolly.cool.
+
 ## Agent workflow
 
-This repository uses Shipshape for its three-role, spec-driven agent workflow.
+This repository uses [Shipshape](https://github.com/dmytri/shipshape) for its three-role, spec-driven agent workflow.
 
 Before substantive agent work, install or load Shipshape:
 

package/assets/skills/jolly/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: jolly
+description: End-to-end playbook for setting up a Saleor Cloud storefront with Jolly — teaches the customer's own agent to drive the official CLIs (Vercel, @saleor/configurator, git, pnpm) plus Jolly's thin helpers, from `jolly start` to a live, deployed store.
+---
+
+# Jolly setup playbook
+
+You are the customer's own agent. **Jolly does not replace you** — it gives you a thin CLI
+for plumbing (auth, store provisioning, secret writing, diagnostics) and this playbook. You
+run the official CLIs yourself. Jolly never shells out to the Vercel CLI or
+`@saleor/configurator`; you do.
+
+Reach the goal — a real, deployed, working storefront (browsing, cart, and checkout to the
+Stripe test payment step) — in as few human interruptions as possible. Pause only for the
+unavoidable human steps: new-account creation, browser OAuth/login consent, and pasting secret
+values. Everything else, automate.
+
+> Exact upstream commands and flags (Vercel CLI, `@saleor/configurator`, Paper's
+> `saleor/storefront`) change over time. Re-check the current upstream docs/`--help` at run
+> time rather than trusting memorized invocations. The Jolly skill describes the *flow*; the
+> tools own the *specifics*.
+
+## Before each action
+
+Every Jolly command emits one structured envelope (`command`, `status`, `summary`, `data`,
+`checks`, `nextSteps`, `errors`) and, before any create/modify/deploy action, a `riskContext`
+(`action`, `target`, `riskLevel`, `categories`, `reversible`, `sideEffects`, `dryRunAvailable`).
+**You** decide whether to seek the customer's approval based on that risk context and the
+customer's policies — Jolly never hardcodes the decision. Parse `--json` output to branch.
+
+## Stages
+
+1. **Bootstrap** — the customer ran `jolly start` (or you did). It installed this skill and the
+   Saleor agent-skills via `npx skills add`, wrote `.mcp.json` (local mcp-graphql against the
+   customer's own endpoint), scaffolded, ran `jolly doctor`, and emitted the playbook. Read its
+   `data` and `nextSteps`.
+
+2. **Authenticate to Saleor Cloud** — if not already authed, run `jolly login`. It prefers the
+   browser OAuth flow and falls back to a pasted token; pause for the human's browser consent.
+   The Saleor Cloud token is stored as `JOLLY_SALEOR_CLOUD_TOKEN` in `.env`.
+
+3. **Provision the store** — run `jolly create store` (creates/reuses the Saleor Cloud
+   organization, project, and environment via the Cloud API). For a brand-new Saleor account,
+   direct the human to sign up at cloud.saleor.io first, then resume with the store URL.
+
+4. **App token** — run `jolly create app-token` to acquire a Saleor app token (all permissions
+   in v1) for configuration.
+
+5. **Storefront** — clone the Paper template yourself:
+   `git clone https://github.com/saleor/storefront.git ./storefront` (the `main` branch),
+   remove the upstream `.git`, run `git init`, `cp .env.example .env`, and `pnpm install`. If the
+   local Node version is incompatible with Paper, tell the human (don't switch Node yourself). In
+   the storefront's `.env`, set `NEXT_PUBLIC_SALEOR_API_URL` to your store's GraphQL endpoint and
+   `NEXT_PUBLIC_DEFAULT_CHANNEL=us` (the channel the starter recipe creates).
+
+6. **Configure the store** — the Jolly starter recipe ships with this skill as `recipe.yml`
+   (alongside this `SKILL.md`): a pirate-themed US/USD/English catalog with shipping and the `us`
+   channel Paper points at. Copy it into the storefront repo as `saleor-config.yml` (keep it
+   version-controlled and reviewable), then apply it with `@saleor/configurator`'s safe
+   workflow — `diff` to preview, then `deploy` — passing
+   `--url "$NEXT_PUBLIC_SALEOR_API_URL" --token "$JOLLY_SALEOR_APP_TOKEN" --config saleor-config.yml`
+   (or set `SALEOR_URL`/`SALEOR_TOKEN`). Add `--fail-on-breaking` on `deploy`. Show the diff and
+   seek the customer's approval before deploying writes. Jolly never runs the configurator; you do.
+
+7. **Stripe (test mode)** — get the test keys the fast way, via the official Stripe CLI's
+   browser OAuth login (no hunting through the Dashboard):
+   - Run `npx @stripe/cli login` — it prints a URL; have the human open it and approve in the
+     browser (one click). If they have no Stripe account, send them to
+     https://dashboard.stripe.com/register first (test mode works immediately after signup —
+     no business details needed). The CLI cannot create the account; that signup is the human's.
+   - Read the test-mode keys from the CLI config (`npx @stripe/cli config --list` /
+     `~/.config/stripe/config.toml`): `test_mode_pub_key` (`pk_test_…`) and `test_mode_api_key`
+     (`sk_test_…`). Pass them to `jolly create stripe --publishable-key … --secret-key …`, which
+     writes them to `.env` (never printed). Jolly never runs the Stripe CLI itself — you do.
+   - **These CLI-issued keys are test-mode and expire (~90 days — see `test_mode_key_expires_at`).**
+     That is the right tradeoff to get started fast, but the expiry is yours to handle: before it
+     hits, generate durable keys in the Stripe Dashboard (Developers → API keys), re-run
+     `jolly create stripe`, and update the Saleor Stripe app config. Flag the expiry date to the
+     human now and own the follow-up — do not let checkout silently break at the 90-day mark.
+   - Durable-from-the-start alternative: if the human prefers, skip the CLI and paste standard
+     Dashboard keys straight into `jolly create stripe`. Live mode (out of v1 scope) always uses
+     Dashboard keys.
+   Then configure Saleor's **Stripe app** — the Saleor-supported payment path, *not* the
+   configurator (which manages catalog only): in the Saleor Dashboard → Extensions, install or
+   open the Stripe app, add a configuration with those keys, and **map it to the `us` channel**.
+   The Stripe app registers its own Stripe webhooks automatically. This Dashboard step needs the
+   human's click — guide them through it.
+
+8. **Deploy to Vercel** — deploy with the official Vercel CLI: `npx vercel`. Authentication is
+   the Vercel CLI's own `vercel login` session — if `npx vercel whoami` fails, pause and have
+   the human run `npx vercel login` (browser), then resume. Set the project's env vars
+   (`NEXT_PUBLIC_SALEOR_API_URL`, `NEXT_PUBLIC_DEFAULT_CHANNEL=us`) with the Vercel CLI
+   (`npx vercel env add …`), deploy to production (`npx vercel --prod`), and capture the deployed
+   URL. Do not use any other deployment mechanism.
+
+9. **Wire trusted origins** — update Saleor's allowed/trusted origins to include the deployed
+   storefront URL.
+
+10. **Verify** — run `jolly doctor` (all groups) to confirm operational readiness: Saleor
+    connectivity, storefront env, deployment reachability, and that checkout reaches the Stripe
+    test payment step. Report the live URL, the doctor results, and any remaining manual steps.
+
+## If a step fails or you're unsure
+
+Run `npx @dk/jolly doctor` — it tells you what is wrong and the concrete next action (a
+command to run, a CLI to authenticate, a value to ask your human for). Fix that, then
+continue. Re-running `jolly start` is safe: Jolly detects what you (and it) already did —
+the cloned storefront, the configured store, the deployment — and resumes from the first
+outstanding step rather than redoing work. Never treat a failed command as success.
+
+## Honesty
+
+Never claim a step succeeded that you did not actually perform and confirm. If a CLI is missing
+or unauthenticated, stop and tell the human exactly what to do (e.g. `npx vercel login`) — do
+not fabricate success or invent a fallback. Jolly's own commands follow the same rule.

package/assets/skills/jolly/recipe.yml

@@ -0,0 +1,307 @@
+# Jolly starter recipe — a @saleor/configurator config that turns a freshly
+# created Saleor Cloud environment into a working, browsable, checkout-ready
+# storefront for the Paper template. Playful pirate-themed demo catalog, single
+# US / USD / English market (v1).
+#
+# This file ships with the Jolly skill. The agent copies it into the cloned
+# storefront repo (keep it version-controlled and reviewable) and applies it
+# with the official Configurator safe workflow — Jolly never runs Configurator:
+#
+#   npx @saleor/configurator diff   --url "$NEXT_PUBLIC_SALEOR_API_URL" \
+#       --token "$JOLLY_SALEOR_APP_TOKEN" --config saleor-config.yml
+#   npx @saleor/configurator deploy --url "$NEXT_PUBLIC_SALEOR_API_URL" \
+#       --token "$JOLLY_SALEOR_APP_TOKEN" --config saleor-config.yml --fail-on-breaking
+#
+# Then point the Paper storefront at this channel: NEXT_PUBLIC_DEFAULT_CHANNEL=us
+#
+# Customize freely — rename the shop, swap in your own catalog. If Configurator
+# rejects a field, re-check its current example.yml schema; the tool owns the
+# specifics, this recipe owns the starting point.
+
+shop:
+  defaultMailSenderName: "Jolly Roger Outfitters"
+  displayGrossPrices: true
+  trackInventoryByDefault: false        # demo catalog sells without stock counts
+  defaultWeightUnit: KG
+
+# Single US / USD market. CHARGE flow so test-mode Stripe captures immediately.
+channels:
+  - name: United States
+    slug: us
+    currencyCode: USD
+    defaultCountry: US
+    isActive: true
+    settings:
+      automaticallyConfirmAllNewOrders: true
+      markAsPaidStrategy: TRANSACTION_FLOW
+      defaultTransactionFlowStrategy: CHARGE
+    taxConfiguration:
+      taxCalculationStrategy: FLAT_RATES
+      chargeTaxes: false
+      displayGrossPrices: true
+      pricesEnteredWithTax: true
+
+# One simple shippable product type — no custom attributes to keep the happy
+# path robust. Add attributes/variants later when you customize.
+productTypes:
+  - name: Pirate Goods
+    isShippingRequired: true
+
+categories:
+  - name: Weapons
+    slug: weapons
+  - name: Navigation
+    slug: navigation
+  - name: Apparel
+    slug: apparel
+  - name: Treasure
+    slug: treasure
+  - name: Ship Supplies
+    slug: ship-supplies
+
+warehouses:
+  - name: Port Royal Warehouse
+    slug: port-royal
+    email: quartermaster@jolly.example
+    isPrivate: false
+    clickAndCollectOption: DISABLED
+    address:
+      streetAddress1: "1 Mallory Square"
+      city: Key West
+      postalCode: "33040"
+      country: US
+      countryArea: FL
+      companyName: "Jolly Roger Outfitters"
+
+# A default US shipping zone so checkout can reach the payment step.
+shippingZones:
+  - name: United States
+    description: "Shipping within the United States"
+    default: true
+    countries:
+      - US
+    warehouses:
+      - port-royal
+    channels:
+      - us
+    shippingMethods:
+      - name: Standard Shipping
+        type: PRICE
+        minimumDeliveryDays: 3
+        maximumDeliveryDays: 7
+        channelListings:
+          - channel: us
+            price: 5.00
+            minimumOrderPrice: 0
+      - name: Free Shipping
+        type: PRICE
+        minimumDeliveryDays: 5
+        maximumDeliveryDays: 10
+        channelListings:
+          - channel: us
+            price: 0
+            minimumOrderPrice: 50
+
+# Pirate catalog — single-variant products, each published and priced in USD so
+# Paper can list, cart, and check them out immediately.
+products:
+  - name: "Cutlass"
+    slug: cutlass
+    description: "A trusty curved blade, forged for close-quarters boarding actions."
+    productType: Pirate Goods
+    category: weapons
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: CUTLASS-001
+        channelListings:
+          - channel: us
+            price: 89.00
+
+  - name: "Flintlock Pistol"
+    slug: flintlock-pistol
+    description: "One shot, one chance — make it count, then swing the cutlass."
+    productType: Pirate Goods
+    category: weapons
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: FLINTLOCK-001
+        channelListings:
+          - channel: us
+            price: 149.00
+
+  - name: "Brass Spyglass"
+    slug: brass-spyglass
+    description: "Spot the king's frigates — and the merchantmen — long before they spot you."
+    productType: Pirate Goods
+    category: navigation
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: SPYGLASS-001
+        channelListings:
+          - channel: us
+            price: 59.00
+
+  - name: "Pirate's Compass"
+    slug: pirates-compass
+    description: "Points not north, but toward what your heart wants most. Usually rum."
+    productType: Pirate Goods
+    category: navigation
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: COMPASS-001
+        channelListings:
+          - channel: us
+            price: 39.00
+
+  - name: "Tricorne Hat"
+    slug: tricorne-hat
+    description: "Three corners of pure intimidation. Feather not included."
+    productType: Pirate Goods
+    category: apparel
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: TRICORNE-001
+        channelListings:
+          - channel: us
+            price: 45.00
+
+  - name: "Leather Eyepatch"
+    slug: leather-eyepatch
+    description: "Keeps one eye dark-adapted for going below decks. Also: very dashing."
+    productType: Pirate Goods
+    category: apparel
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: EYEPATCH-001
+        channelListings:
+          - channel: us
+            price: 12.00
+
+  - name: "Treasure Map (Authentic Replica)"
+    slug: treasure-map
+    description: "X marks the spot. We make no guarantees about what's under the X."
+    productType: Pirate Goods
+    category: treasure
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: MAP-001
+        channelListings:
+          - channel: us
+            price: 25.00
+
+  - name: "Pieces of Eight (Coin Set)"
+    slug: pieces-of-eight
+    description: "A handful of gleaming doubloons. Spend them, bury them, bite them to check."
+    productType: Pirate Goods
+    category: treasure
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: COINS-001
+        channelListings:
+          - channel: us
+            price: 30.00
+
+  - name: "Oak Rum Barrel"
+    slug: oak-rum-barrel
+    description: "Provisions for a long voyage. The most important supply on any ship."
+    productType: Pirate Goods
+    category: ship-supplies
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: RUMBARREL-001
+        channelListings:
+          - channel: us
+            price: 120.00
+
+  - name: "Jolly Roger Flag"
+    slug: jolly-roger-flag
+    description: "Run it up the mast and watch the prices — and the prizes — surrender."
+    productType: Pirate Goods
+    category: ship-supplies
+    channelListings:
+      - channel: us
+        isPublished: true
+        visibleInListings: true
+        isAvailableForPurchase: true
+    variants:
+      - name: Default
+        sku: FLAG-001
+        channelListings:
+          - channel: us
+            price: 35.00
+
+# A featured collection for Paper's storefront merchandising.
+collections:
+  - name: "Crew Favorites"
+    slug: crew-favorites
+    description: "What every well-equipped pirate carries aboard."
+    products:
+      - cutlass
+      - brass-spyglass
+      - tricorne-hat
+      - jolly-roger-flag
+    channelListings:
+      - channelSlug: us
+        isPublished: true
+
+menus:
+  - name: Main Navigation
+    slug: main-nav
+    items:
+      - name: Weapons
+        category: weapons
+      - name: Navigation
+        category: navigation
+      - name: Apparel
+        category: apparel
+      - name: Treasure
+        category: treasure
+      - name: Ship Supplies
+        category: ship-supplies
+      - name: Crew Favorites
+        collection: crew-favorites

package/bin/jolly

@@ -1,2 +1,49 @@
-#!/usr/bin/env bun
-import "../src/index.ts";
+#!/usr/bin/env node
+"use strict";
+
+// Jolly CLI launcher (feature 006, decision 2026-06-12): the published Jolly
+// CLI is a Node.js program. This launcher runs `src/index.ts` under
+// Node.js >= 23 via native type stripping and never invokes or requires Bun
+// (Bun is the project's development environment only).
+//
+// Deliberately plain CommonJS-compatible JavaScript so that an old Node can
+// parse it and reach the version guard below instead of dying with a raw
+// syntax or module error.
+
+var MIN_NODE_MAJOR = 23;
+
+var nodeVersion = process.versions.node;
+var nodeMajor = parseInt(nodeVersion.split(".")[0], 10);
+
+if (!(nodeMajor >= MIN_NODE_MAJOR)) {
+  console.error(
+    "jolly requires Node.js >= " +
+      MIN_NODE_MAJOR +
+      ", but this is Node.js " +
+      nodeVersion +
+      ". Please upgrade Node.js (https://nodejs.org) and try again.",
+  );
+  process.exit(1);
+}
+
+import("../src/index.ts").catch(function (error) {
+  if (error && error.code === "ERR_UNKNOWN_FILE_EXTENSION") {
+    // Node >= 23 but before 23.6: type stripping exists behind a flag rather
+    // than by default. Re-run the entry point with the flag enabled.
+    rerunWithStripTypes();
+    return;
+  }
+  throw error;
+});
+
+function rerunWithStripTypes() {
+  var path = require("node:path");
+  var spawnSync = require("node:child_process").spawnSync;
+  var entry = path.join(__dirname, "..", "src", "index.ts");
+  var result = spawnSync(
+    process.execPath,
+    ["--experimental-strip-types", entry].concat(process.argv.slice(2)),
+    { stdio: "inherit" },
+  );
+  process.exit(result.status === null ? 1 : result.status);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dk/jolly",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Ahoy, agent. Go build a Saleor storefront.",
   "type": "module",
   "bin": {
@@ -9,13 +9,14 @@
   "files": [
     "bin/",
     "src/",
+    "assets/skills/",
     "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "bun": ">=1.1.0"
+    "node": ">=23.0.0"
   },
   "scripts": {
     "dev": "bun run --watch src/index.ts",