@forgecart/cli 1.1.0 → 2.1.0

package/dist/src/commands/placeholders.js

@@ -0,0 +1,109 @@
+import { Command } from 'commander';
+import { print } from '../output.js';
+/**
+ * Commands whose behaviour ships with the publish pipeline. They are registered
+ * now so the command surface and `--help` text exist, but their actions only
+ * announce that the implementation is not yet wired in v2.
+ */
+function notImplemented(command) {
+    print(`\`forgecart ${command}\` is not implemented yet in v2. ` +
+        'It arrives with the publish pipeline.');
+}
+/** `init:application` — add a NestJS application to an existing project. */
+export function createInitApplicationCommand() {
+    return new Command('init:application')
+        .description('Add a NestJS application to an existing ForgeCart project')
+        .action(() => {
+        notImplemented('init:application');
+    });
+}
+/** `deploy` — deploy the current project. */
+export function createDeployCommand() {
+    return new Command('deploy')
+        .description('Deploy the current ForgeCart project')
+        .option('--skip-build', 'Skip the build step')
+        .action(() => {
+        notImplemented('deploy');
+    });
+}
+/** `list` — list deployments for the channel. */
+export function createListCommand() {
+    return new Command('list')
+        .alias('ls')
+        .description('List all deployments for this channel')
+        .action(() => {
+        notImplemented('list');
+    });
+}
+/** `status [type]` — show deployment status. */
+export function createStatusCommand() {
+    return new Command('status')
+        .description('Show detailed deployment status')
+        .argument('[type]', 'Deployment type (storefront or application)')
+        .action(() => {
+        notImplemented('status');
+    });
+}
+/** `logs [type]` — view deployment logs. */
+export function createLogsCommand() {
+    return new Command('logs')
+        .description('View deployment logs')
+        .argument('[type]', 'Deployment type (storefront or application)', 'storefront')
+        .option('-f, --follow', 'Follow log output')
+        .option('-n, --lines <number>', 'Number of lines to show', '100')
+        .action(() => {
+        notImplemented('logs');
+    });
+}
+/** `delete <type>` — delete a deployment. */
+export function createDeleteCommand() {
+    return new Command('delete')
+        .description('Delete a deployment')
+        .argument('<type>', 'Deployment type (storefront or application)')
+        .option('-f, --force', 'Skip confirmation prompt')
+        .action(() => {
+        notImplemented('delete');
+    });
+}
+/** `scale <type> <instances>` — scale a deployment. */
+export function createScaleCommand() {
+    return new Command('scale')
+        .description('Scale a deployment')
+        .argument('<type>', 'Deployment type (storefront or application)')
+        .argument('<instances>', 'Number of instances (0-10)')
+        .action(() => {
+        notImplemented('scale');
+    });
+}
+/** `env` — manage environment variables (get/set/unset). */
+export function createEnvCommand() {
+    const cmd = new Command('env').description('Manage deployment environment variables');
+    cmd
+        .command('get <type>')
+        .description('Get environment variables for a deployment')
+        .action(() => {
+        notImplemented('env get');
+    });
+    cmd
+        .command('set <type> <key> <value>')
+        .description('Set an environment variable')
+        .action(() => {
+        notImplemented('env set');
+    });
+    cmd
+        .command('unset <type> <key>')
+        .description('Remove an environment variable')
+        .action(() => {
+        notImplemented('env unset');
+    });
+    return cmd;
+}
+/** `whoami` — show current channel information. */
+export function createWhoamiCommand() {
+    return new Command('whoami')
+        .description('Show current channel information')
+        .action(() => {
+        notImplemented('whoami');
+    });
+}
+//# sourceMappingURL=placeholders.js.map

package/dist/src/commands/placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.js","sourceRoot":"","sources":["../../../src/commands/placeholders.ts"],"names":[],"mappings":"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"}

package/dist/src/output.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal stdout/stderr writers for the CLI.
+ *
+ * A publishable CLI legitimately prints to standard streams, but the repo lint
+ * rules forbid `console.*`. These helpers centralise process stream access so
+ * the rest of the CLI never touches `console`.
+ */
+/** Write a line to standard output. */
+export declare function print(message?: string): void;
+/** Write a line to standard error. */
+export declare function printError(message: string): void;

package/dist/src/output.js

@@ -0,0 +1,16 @@
+/**
+ * Minimal stdout/stderr writers for the CLI.
+ *
+ * A publishable CLI legitimately prints to standard streams, but the repo lint
+ * rules forbid `console.*`. These helpers centralise process stream access so
+ * the rest of the CLI never touches `console`.
+ */
+/** Write a line to standard output. */
+export function print(message = '') {
+    process.stdout.write(`${message}\n`);
+}
+/** Write a line to standard error. */
+export function printError(message) {
+    process.stderr.write(`${message}\n`);
+}
+//# sourceMappingURL=output.js.map

package/dist/src/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uCAAuC;AACvC,MAAM,UAAU,KAAK,CAAC,OAAO,GAAG,EAAE;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/package.json

@@ -1,30 +1,40 @@
 {
   "name": "@forgecart/cli",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "type": "module",
-  "description": "CLI tool for deploying applications to ForgeCart",
-  "main": "dist/index.js",
+  "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {
-    "forgecart": "./bin/forgecart.js"
+    "forgecart": "./dist/bin/forgecart.js"
   },
-  "dependencies": {
-    "@forgecart/sdk": "1.2.5"
+  "main": "./dist/src/cli.js",
+  "types": "./dist/src/cli.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/cli.d.ts",
+      "import": "./dist/src/cli.js",
+      "default": "./dist/src/cli.js"
+    }
   },
   "files": [
     "dist",
-    "bin",
     "templates"
   ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "forgecart",
     "cli",
-    "deploy",
-    "paas",
-    "nodejs"
+    "storefront",
+    "scaffold",
+    "nextjs"
   ],
   "author": "ForgeCart",
   "license": "MIT"
-}
+}

package/templates/storefront/.env.example

@@ -0,0 +1,12 @@
+# ForgeCart channel credentials.
+#
+# `forgecart init` writes the real values to `.env.local` for you. This file
+# documents the variables the storefront reads. Both are required and used
+# server-side only (never exposed to the browser).
+
+# The channel token identifies which ForgeCart channel this storefront serves.
+# It is sent as the `forgecart-token` header on every shop API request.
+FORGECART_CHANNEL_TOKEN=
+
+# Base URL of the ForgeCart shop GraphQL API (the shop-api endpoint).
+FORGECART_SHOP_API_URL=https://api.forgecart.com/shop-api

package/templates/storefront/.forgecartignore

@@ -0,0 +1,2 @@
+node_modules
+.next

package/templates/storefront/Procfile

@@ -0,0 +1 @@
+web: npm run start

package/templates/storefront/README.md

@@ -0,0 +1,87 @@
+# Storefront
+
+A minimal [Next.js 15](https://nextjs.org) (App Router) storefront for a
+ForgeCart channel. It talks to the ForgeCart shop GraphQL API through
+`@forgecart/sdk` and renders product data in Server Components.
+
+This directory is the scaffold copied verbatim into your project by
+`forgecart init`. Nothing here is compiled by the ForgeCart monorepo; it ships
+as-is in the published `@forgecart/cli` package.
+
+## How the channel token + API URL wire in
+
+The storefront reads two environment variables (server-side only):
+
+| Variable                  | Purpose                                                        |
+| ------------------------- | ------------------------------------------------------------- |
+| `FORGECART_CHANNEL_TOKEN` | Identifies the channel; sent as the `forgecart-token` header. |
+| `FORGECART_SHOP_API_URL`  | Base URL of the channel's shop GraphQL API (`.../shop-api`).  |
+
+`forgecart init` writes both to `.env.local` for you. To configure manually,
+copy `.env.example` to `.env.local` and fill them in.
+
+These values are consumed in [`src/lib/forgecart.ts`](src/lib/forgecart.ts),
+which constructs and memoizes a singleton `ForgeCartShopClient`:
+
+```ts
+new ForgeCartShopClient({
+  endpoint: process.env.FORGECART_SHOP_API_URL,
+  channelToken: process.env.FORGECART_CHANNEL_TOKEN,
+});
+```
+
+Because the client is only imported from Server Components, the channel token
+never reaches the browser.
+
+## Running locally
+
+```bash
+npm install
+npm run dev      # next dev  -> http://localhost:3000
+```
+
+A ForgeCart channel workspace serves this app as its live site by running
+`npm run dev` (development) or `npm run build && npm run start` (production; see
+the `Procfile`).
+
+## Project layout
+
+```
+src/
+  lib/
+    forgecart.ts       # shop client singleton + typed product helpers
+    cart-context.tsx   # local (localStorage) cart state for the MVP
+  components/
+    Header.tsx         # top nav: Home / Products / Cart
+    ProductCard.tsx    # product tile
+    AddToCartButton.tsx
+  app/
+    layout.tsx         # html shell + header/footer + CartProvider
+    page.tsx           # home: greeting + featured products
+    products/
+      page.tsx         # product grid
+      [slug]/page.tsx  # product detail
+    cart/page.tsx      # local cart
+```
+
+## Data access
+
+`src/lib/forgecart.ts` exposes typed helpers over the shop client:
+
+- `getProducts({ take, skip })` -> `{ items, totalItems }`
+- `getFeaturedProducts(count)` -> `StorefrontProduct[]`
+- `getProductBySlug(slug)` / `getProductById(id)` -> `StorefrontProduct | null`
+- `getStartingPrice(product)` and `formatPrice(minorUnits, currency)`
+
+The generated typed product operations (`shopClient.product.shopProducts` /
+`.shopProduct`) only select `id` + `optionGroups`, so these helpers use the
+SDK's supported raw-query escape hatch (`shopClient.query<T>(document, vars)`)
+to also fetch `name`, `slug`, `description`, `featuredAsset`, and `variants`
+(price in minor units). Every selected field exists on the shop schema's
+`Product` type — extend the documents in `forgecart.ts` to fetch more.
+
+## Cart
+
+The starter cart (`src/lib/cart-context.tsx` + `app/cart/page.tsx`) keeps state
+in the browser via `localStorage`. To take real orders, wire it to the
+ForgeCart `cart` / `checkout` shop operations exposed by the SDK.

package/templates/storefront/next.config.js

@@ -0,0 +1,14 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Produce a self-contained build so a channel workspace can run the
+  // storefront with `next start` without a full node_modules tree.
+  output: 'standalone',
+  reactStrictMode: true,
+  images: {
+    // The shop API serves product/asset previews from arbitrary hosts, so
+    // allow any remote image. Tighten this to your asset host in production.
+    remotePatterns: [{ protocol: 'https', hostname: '**' }],
+  },
+};
+
+module.exports = nextConfig;

package/templates/storefront/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "storefront",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@forgecart/sdk": "^1.2.6",
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.0"
+  }
+}

package/templates/storefront/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/templates/storefront/src/app/cart/page.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import Link from 'next/link';
+
+import { useCart } from '../../lib/cart-context';
+import { formatPrice } from '../../lib/forgecart';
+
+export default function CartPage() {
+  const { cart, itemCount, subtotal, setQuantity, remove, pending } = useCart();
+  const lines = cart?.lines ?? [];
+
+  if (itemCount === 0) {
+    return (
+      <div className="space-y-4">
+        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
+        <p className="text-gray-500">Your cart is empty.</p>
+        <Link
+          href="/products"
+          className="inline-block rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
+        >
+          Browse products
+        </Link>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
+
+      <ul className="divide-y divide-gray-200 rounded-lg border border-gray-200 bg-white">
+        {lines.map((line) => (
+          <li key={line.id} className="flex items-center gap-4 p-4">
+            <div className="h-16 w-16 shrink-0 overflow-hidden rounded bg-gray-100">
+              {line.featuredAsset?.preview ? (
+                // eslint-disable-next-line @next/next/no-img-element
+                <img
+                  src={line.featuredAsset.preview}
+                  alt={line.productVariant.name}
+                  className="h-full w-full object-cover"
+                />
+              ) : null}
+            </div>
+
+            <div className="min-w-0 flex-1">
+              <p className="truncate font-medium text-gray-900">{line.productVariant.name}</p>
+              <p className="text-sm text-gray-500">{formatPrice(line.unitPriceWithTax)} each</p>
+            </div>
+
+            <div className="flex items-center gap-2">
+              <label className="sr-only" htmlFor={`qty-${line.id}`}>
+                Quantity
+              </label>
+              <input
+                id={`qty-${line.id}`}
+                type="number"
+                min={1}
+                value={line.quantity}
+                disabled={pending}
+                onChange={(e) => setQuantity(line.id, Number.parseInt(e.target.value, 10) || 1)}
+                className="w-16 rounded border border-gray-300 px-2 py-1 text-sm disabled:opacity-50"
+              />
+            </div>
+
+            <div className="w-24 text-right font-medium text-gray-900">
+              {formatPrice(line.linePriceWithTax)}
+            </div>
+
+            <button
+              type="button"
+              onClick={() => remove(line.id)}
+              disabled={pending}
+              className="text-sm text-gray-400 hover:text-red-600 disabled:opacity-50"
+              aria-label={`Remove ${line.productVariant.name}`}
+            >
+              Remove
+            </button>
+          </li>
+        ))}
+      </ul>
+
+      <div className="flex items-center justify-between rounded-lg border border-gray-200 bg-white p-4">
+        <span className="text-sm text-gray-600">Subtotal ({itemCount} items)</span>
+        <span className="text-lg font-semibold text-gray-900">{formatPrice(subtotal)}</span>
+      </div>
+    </div>
+  );
+}

package/templates/storefront/src/app/globals.css

@@ -0,0 +1,13 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --background: #ffffff;
+  --foreground: #111827;
+}
+
+body {
+  color: var(--foreground);
+  background: var(--background);
+}

package/templates/storefront/src/app/layout.tsx

@@ -0,0 +1,32 @@
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+
+import { Header } from '../components/Header';
+import { getCart } from '../lib/cart-actions';
+import { CartProvider } from '../lib/cart-context';
+
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: 'Storefront',
+  description: 'A ForgeCart channel storefront.',
+};
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const initialCart = await getCart();
+  return (
+    <html lang="en">
+      <body className="min-h-screen bg-gray-50 text-gray-900 antialiased">
+        <CartProvider initialCart={initialCart}>
+          <Header />
+          <main className="mx-auto max-w-6xl px-4 py-8">{children}</main>
+          <footer className="border-t border-gray-200 bg-white">
+            <div className="mx-auto max-w-6xl px-4 py-6 text-sm text-gray-500">
+              Powered by ForgeCart
+            </div>
+          </footer>
+        </CartProvider>
+      </body>
+    </html>
+  );
+}

package/templates/storefront/src/app/page.tsx

@@ -0,0 +1,49 @@
+import Link from 'next/link';
+
+import { ProductCard } from '../components/ProductCard';
+import { getFeaturedProducts } from '../lib/forgecart';
+
+// Product data changes in the dashboard, so render on each request.
+export const dynamic = 'force-dynamic';
+
+export default async function HomePage() {
+  const products = await getFeaturedProducts(4);
+
+  return (
+    <div className="space-y-12">
+      <section className="rounded-2xl bg-white p-10 shadow-sm">
+        <h1 className="text-3xl font-bold tracking-tight text-gray-900">
+          Welcome to the shop
+        </h1>
+        <p className="mt-3 max-w-2xl text-gray-600">
+          This storefront is served by a ForgeCart channel. Browse the catalog
+          and add products to your cart.
+        </p>
+        <Link
+          href="/products"
+          className="mt-6 inline-block rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
+        >
+          Shop all products
+        </Link>
+      </section>
+
+      <section>
+        <div className="mb-4 flex items-center justify-between">
+          <h2 className="text-xl font-semibold text-gray-900">Featured</h2>
+          <Link href="/products" className="text-sm text-gray-600 hover:text-gray-900">
+            View all
+          </Link>
+        </div>
+        {products.length === 0 ? (
+          <p className="text-gray-500">No products yet. Add some in your dashboard.</p>
+        ) : (
+          <div className="grid grid-cols-2 gap-6 sm:grid-cols-3 lg:grid-cols-4">
+            {products.map((product) => (
+              <ProductCard key={product.id} product={product} />
+            ))}
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}

package/templates/storefront/src/app/products/[slug]/not-found.tsx

@@ -0,0 +1,20 @@
+import Link from 'next/link';
+
+export default function ProductNotFound() {
+  return (
+    <div className="space-y-4">
+      <h1 className="text-2xl font-bold tracking-tight text-gray-900">
+        Product not found
+      </h1>
+      <p className="text-gray-500">
+        We couldn&apos;t find that product. It may have been removed.
+      </p>
+      <Link
+        href="/products"
+        className="inline-block rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
+      >
+        Back to products
+      </Link>
+    </div>
+  );
+}

package/templates/storefront/src/app/products/[slug]/page.tsx

@@ -0,0 +1,61 @@
+import Link from 'next/link';
+import { notFound } from 'next/navigation';
+
+import { ProductPurchase } from '../../../components/ProductPurchase';
+import { getProductBySlug } from '../../../lib/forgecart';
+
+export const dynamic = 'force-dynamic';
+
+// Next.js 15: route params are delivered as a Promise.
+export default async function ProductDetailPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const product = await getProductBySlug(slug);
+
+  if (!product) {
+    notFound();
+  }
+
+  return (
+    <div className="space-y-6">
+      <Link href="/products" className="text-sm text-gray-600 hover:text-gray-900">
+        &larr; Back to products
+      </Link>
+
+      <div className="grid gap-8 md:grid-cols-2">
+        <div className="aspect-square overflow-hidden rounded-lg border border-gray-200 bg-gray-100">
+          {product.featuredAsset ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={product.featuredAsset.preview}
+              alt={product.name}
+              className="h-full w-full object-cover"
+            />
+          ) : (
+            <div className="flex h-full w-full items-center justify-center text-sm text-gray-400">
+              No image
+            </div>
+          )}
+        </div>
+
+        <div className="space-y-4">
+          <h1 className="text-2xl font-bold tracking-tight text-gray-900">{product.name}</h1>
+
+          {product.description && (
+            <div
+              className="prose prose-sm max-w-none text-gray-600"
+              // Product descriptions may contain rich text from the dashboard.
+              dangerouslySetInnerHTML={{ __html: product.description }}
+            />
+          )}
+
+          {/* Pick a variant (Size/Color) -> price + add-to-cart. */}
+          <ProductPurchase product={product} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/storefront/src/app/products/page.tsx

@@ -0,0 +1,27 @@
+import { ProductCard } from '../../components/ProductCard';
+import { getProducts } from '../../lib/forgecart';
+
+export const dynamic = 'force-dynamic';
+
+export default async function ProductsPage() {
+  const { items, totalItems } = await getProducts({ take: 24 });
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-baseline justify-between">
+        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Products</h1>
+        <span className="text-sm text-gray-500">{totalItems} items</span>
+      </div>
+
+      {items.length === 0 ? (
+        <p className="text-gray-500">No products yet. Add some in your dashboard.</p>
+      ) : (
+        <div className="grid grid-cols-2 gap-6 sm:grid-cols-3 lg:grid-cols-4">
+          {items.map((product) => (
+            <ProductCard key={product.id} product={product} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}