@forgecart/cli 2.202610052143.0 → 2.202610060357.0

package/templates/storefront-shadcn/src/server/customer-extras/service/customer-extras.service.ts

@@ -0,0 +1,58 @@
+import 'server-only';
+
+import { randomBytes } from 'node:crypto';
+
+import { Injectable } from '@nestjs/common';
+
+import { BackendMethod } from '../../backend-method.decorator';
+import { BackendError } from '../../types';
+import type { BackendSession } from '../../types';
+
+import type {
+  AssignCustomerHashInput,
+  AssignCustomerHashResult,
+} from '../type/customer-extras.types';
+
+/** ACF definition this store keeps its per-customer extras under. */
+const DEFINITION_CODE = 'customer-extras';
+
+/**
+ * The worked example for the `sdk.backend` gate: mint a random hash for the
+ * signed-in customer and persist it as a custom field — an ACF entry under
+ * the `customer-extras` definition. That is an ADMIN-authority write the
+ * shop API has no surface for, which is exactly what the gate exists to
+ * unlock.
+ *
+ * Precondition: the channel has a `customer-extras` ACF definition with a
+ * `customerId` id field and a `referralHash` string field (Dashboard →
+ * Custom Fields). Without it the createEntry call fails and the typed
+ * envelope carries the API's error to the caller — nothing crashes.
+ */
+@Injectable()
+export class CustomerExtrasService {
+  @BackendMethod()
+  async assignCustomerHash(
+    session: BackendSession,
+    _input: AssignCustomerHashInput,
+  ): Promise<AssignCustomerHashResult> {
+    const { activeCustomer } = await session.shop.customer.activeCustomer();
+    if (!activeCustomer) {
+      // Shopper-invocable ≠ anonymous-invocable: this method is per-customer
+      // by definition, so an anonymous session is a typed business error.
+      throw new BackendError('BACKEND_CUSTOMER_SESSION_REQUIRED');
+    }
+
+    const referralHash = randomBytes(16).toString('hex');
+    await session.admin.acf.entry.acfCreateEntry({
+      definitionCode: DEFINITION_CODE,
+      input: {
+        fields: [
+          { name: 'customerId', idValue: activeCustomer.id },
+          { name: 'referralHash', stringValue: referralHash },
+        ],
+      },
+    });
+
+    return { customerId: activeCustomer.id, referralHash };
+  }
+}

package/templates/storefront-shadcn/src/server/customer-extras/type/customer-extras.types.ts

@@ -0,0 +1,11 @@
+/**
+ * The `assignCustomerHash` backend-method contract (the sdk.backend worked
+ * example). Input is deliberately empty — the method derives everything from
+ * the caller's session; the result echoes the customer and the minted hash.
+ */
+export type AssignCustomerHashInput = Record<string, never>;
+
+export interface AssignCustomerHashResult {
+  customerId: string;
+  referralHash: string;
+}

package/templates/storefront-shadcn/src/server/forge/live-revision.ts

@@ -0,0 +1,158 @@
+/**
+ * The revision this server is SERVING, for the dev-only error beacon (#847).
+ *
+ * A browser error report used to be stamped with whatever revision was live at
+ * the moment the pod RECEIVED it (`storefront-beacon.service.ts`, `atRevision:
+ * this.target.getLiveRevision()`). A promote that advances between serve and
+ * throw therefore made the report blame the NEW revision for the OLD one's
+ * crash, and the receiver's same-revision fold then marked a healthy tree
+ * DEGRADED. The cure is to resolve the revision where the page is RENDERED —
+ * here — stamp it into the HTML, and let the report carry it back.
+ *
+ * WHERE THE RAW VALUE COMES FROM (settled by ruling ANSWER-0425Z-agent-004):
+ * the pod's supervisor publishes the serving sha to a DERIVED, read-only file
+ * inside the workspace's `.forge/` island by the same act that re-publishes its
+ * runtime state, and this module reads that file per request. Explicitly NOT a
+ * beacon hop on the render path, and explicitly NOT an environment variable —
+ * one dev-server process outlives many promotes, so a value handed to it at
+ * spawn time could only ever name the revision it BOOTED at, which is this
+ * module's own bug reintroduced one layer down. The retired
+ * `.forge/liveRevision` sentinel (appendix design law 5, §7.3) is not that file
+ * and is not read here; see `FORGE_SERVING_REVISION_FILE` below.
+ *
+ * The split is still the shape of the feature:
+ *
+ *  - `parseLiveRevision` is PURE and fully specified by vectors. It owns the
+ *    whole question of what counts as a revision, independently of where the
+ *    raw value came from.
+ *  - `readLiveRevisionSource` is the ONE impure line — the file read, and
+ *    nothing else in the template touches the filesystem for this.
+ *
+ * FAIL OPEN, ALWAYS. Every unresolvable case answers `null`, which means no
+ * meta tag, which means an untagged report, which means the receiver keeps its
+ * existing behaviour (confirm probe included). A page must never fail to render
+ * because the revision is unknown, so there is no throw on this path: an
+ * unknown revision is an ordinary, expected state — every non-storefront pod,
+ * and every pod before its bootstrap primes the ref — not a fault.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The meta tag's `name`. The CONTRACT between this module (which resolves the
+ * value), `app/layout.tsx` (which emits the tag) and
+ * `components/ForgeErrorBeacon.tsx` (which reads it back out of the DOM at send
+ * time). The beacon is a CLIENT component and must not import a `src/server/`
+ * module, so it repeats the literal with a comment pointing here — the same way
+ * the `/__forge_beacon` URL is repeated across this feature's three producers
+ * rather than shared through an import.
+ */
+export const FORGE_REVISION_META = 'forge-revision';
+
+/**
+ * The workspace-relative path the pod's supervisor publishes the serving sha to.
+ *
+ * MIRRORS `SERVING_REVISION_FILE` in
+ * `app/workspace-manager/src/supervisor/workspace-supervisor.service.ts`, whose
+ * doc carries the full reasoning for the path — `.forge/` because that island is
+ * the board repo's ignore authority and a file anywhere else would dirty the
+ * serving tree on every publish, and NEITHER retired legacy path, both of which
+ * the pod's own bootstrap deletes at boot. It is repeated here instead of
+ * imported because this template is scaffolding DATA — copied verbatim into a
+ * merchant's project, with its own `package.json` and toolchain, outside that
+ * monorepo's build graph — exactly like the `/__forge_beacon` URL. Nothing in a
+ * compiler connects the two copies: a rename on either side would silently stop
+ * the file from being found and every report would go back to untagged, so
+ * `tool/storefront-template-spec/src/live-revision.spec.ts` compares them.
+ *
+ * Resolved against `process.cwd()`, which IS the workspace root the supervisor
+ * writes into: it spawns `npm run dev` with `cwd` = the configured workspace
+ * path (resolved in `process-supervisor.service.ts`, handed to the child in
+ * `managed-process.ts`), and `npm` runs the script from the package root without
+ * moving it. `lib/seo/scaffolded-routes.ts` already reads a workspace-relative
+ * path this way on a request path.
+ */
+export const FORGE_SERVING_REVISION_FILE = '.forge/serving-revision';
+
+/**
+ * A revision is a full git commit sha and nothing else: exactly 40 hex digits,
+ * case-insensitive, surrounding whitespace trimmed. That is precisely what the
+ * supervisor's source produces — `git rev-parse --verify refs/heads/serving^{commit}`
+ * (`board-git.service.ts`) — so anything else reaching here is not a revision
+ * and must not be stamped.
+ *
+ * The rejections are the load-bearing half, because a stamped non-sha is worse
+ * than no stamp at all: the receiver compares the payload's value to the live
+ * revision by EQUALITY to decide whether to fold without probing, so a
+ * placeholder that could also BE the live value would skip the probe on
+ * evidence that means nothing. `'unversioned'` is the concrete instance of that
+ * hazard — it is literally what the supervisor reports for a pod with no board
+ * repo, so an unversioned pod stamping `'unversioned'` would match itself and
+ * defeat the guard. Rejecting it here is what makes the receiver's equality
+ * check safe.
+ *
+ * @param raw the candidate revision, exactly as obtained from the source
+ * @returns the normalised lowercase sha, or `null` when `raw` is not one
+ */
+export function parseLiveRevision(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (!/^[0-9a-f]{40}$/i.test(trimmed)) return null;
+  return trimmed.toLowerCase();
+}
+
+/**
+ * Obtain the raw revision value — THE ONE impure line in this module.
+ *
+ * A plain read of {@link FORGE_SERVING_REVISION_FILE}, the file the pod's
+ * supervisor re-publishes on every serving advance. There is deliberately NO
+ * environment fallback: the ruling excluded one, and an env value read here
+ * would be strictly worse than nothing, because the only process that could
+ * supply it is the dev-server's own spawn — which happens once and then serves
+ * every later promote under the revision it started at.
+ *
+ * Read per CALL, never captured at module scope, for the same reason:
+ * a value snapshotted at first import would keep stamping the boot revision
+ * forever. `lib/seo/sitemap-cache.ts` carries the same getter-not-a-constant
+ * reasoning.
+ *
+ * SYNCHRONOUS, unlike `lib/seo/scaffolded-routes.ts`, which reads on a request
+ * path asynchronously and explains why. That reasoning does not transfer: it
+ * fans out over a directory of arbitrarily many JSON fragments, whereas this is
+ * ONE page-cached read of at most 41 bytes, sitting beside an awaited channel
+ * read in the same `generateMetadata` that dwarfs it. Going async would cost
+ * `resolveLiveRevision` its synchronous signature for nothing measurable.
+ *
+ * Every failure answers `null`, and the ordinary case IS a failure: the file is
+ * absent on every pod before its first publish, on a non-storefront workspace
+ * that publishes none, and in a merchant's own checkout of this template, where
+ * no supervisor exists at all. Absent, unreadable and garbage all mean the same
+ * thing here — no tag, an untagged report, the receiver's existing behaviour —
+ * so there is nothing worth distinguishing between them and nothing worth
+ * throwing over on a render path.
+ */
+export function readLiveRevisionSource(): string | null {
+  try {
+    return readFileSync(join(process.cwd(), FORGE_SERVING_REVISION_FILE), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The revision to stamp into this response, or `null` when it cannot be
+ * resolved. Composes the source and the acceptance rule and holds no policy of
+ * its own, so the ruling can move the source without touching any caller.
+ *
+ * The DEV-ONLY gate lives at the call site (`app/layout.tsx`), not here — the
+ * placement every other file in this feature uses (`ForgeErrorBeacon.tsx`,
+ * `app/%5F%5Fforge_beacon/route.ts` and `instrumentation.ts` each check
+ * `NODE_ENV` at their own top), which is what lets a production build
+ * dead-code-eliminate the whole path rather than merely reach a function that
+ * answers `null`.
+ */
+export function resolveLiveRevision(): string | null {
+  const raw = readLiveRevisionSource();
+  if (raw === null) return null;
+  return parseLiveRevision(raw);
+}

package/templates/storefront-shadcn/src/server/forgecart/forgecart-client.factory.ts

@@ -0,0 +1,69 @@
+import 'server-only';
+
+import { ForgeCartAdminClient, ForgeCartShopClient } from '@forgecart/sdk';
+import { Injectable } from '@nestjs/common';
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+const ADMIN_SECRET = process.env.FORGECART_ADMIN_SECRET ?? '';
+/** The admin API is the shop API's sibling endpoint on the same host. */
+const ADMIN_API_URL = SHOP_API_URL.replace(/\/shop-api$/, '/admin-api');
+
+/**
+ * SDK clients for backend methods. The generated SDK is graphql-ws, so
+ * every client is a websocket. Two lifetimes on purpose: the ADMIN client is
+ * a process-long singleton (channel-scoped, secret auth); the SESSION shop
+ * client is per-invocation (shopper-scoped authentication — see buildShop).
+ */
+@Injectable()
+export class ForgeCartClientFactory {
+  private admin: ForgeCartAdminClient | null = null;
+
+  /**
+   * Whether the backend gate is fully configured: `forgecart init` wrote all
+   * three env values AND the admin endpoint is derivable from the shop URL.
+   * False during the image-build pre-warm (which renders with no env) — the
+   * runner then answers with a typed envelope instead of driving doomed
+   * clients, keeping the pre-warm contract (serve, never crash) intact.
+   */
+  isConfigured(): boolean {
+    return Boolean(SHOP_API_URL && CHANNEL_TOKEN && ADMIN_SECRET && ADMIN_API_URL !== SHOP_API_URL);
+  }
+
+  /**
+   * The ADMIN socket is a long-lived singleton: admin operations are
+   * channel-scoped (secret auth, no shopper session), so one connection
+   * serves every invocation for the life of the server process — never
+   * disposed per invocation. Session-scoped sockets are the opposite case:
+   * they belong to the shopper's browser, and the ONE server-side exception
+   * is {@link buildShop} below.
+   */
+  getAdmin(): ForgeCartAdminClient {
+    if (!this.admin) {
+      this.admin = new ForgeCartAdminClient({
+        endpoint: ADMIN_API_URL,
+        channelToken: CHANNEL_TOKEN,
+        adminSecret: ADMIN_SECRET,
+      });
+    }
+    return this.admin;
+  }
+
+  /**
+   * Per-invocation SESSION shop client — the deliberate server-side
+   * exception: a backend method must authenticate WHO the shopper is from
+   * the httpOnly session cookie before acting with admin authority (the
+   * browser cannot be trusted to claim an identity for an admin-gated op).
+   * Short-lived by design; the runner disposes it with the invocation.
+   */
+  buildShop(sessionToken: string | undefined): ForgeCartShopClient {
+    const client = new ForgeCartShopClient({
+      endpoint: SHOP_API_URL,
+      channelToken: CHANNEL_TOKEN,
+    });
+    if (sessionToken) {
+      client.setAuthToken(sessionToken);
+    }
+    return client;
+  }
+}

package/templates/storefront-shadcn/src/server/forgecart/forgecart.module.ts

@@ -0,0 +1,9 @@
+import 'server-only';
+
+import { Module } from '@nestjs/common';
+
+import { ForgeCartClientFactory } from './forgecart-client.factory';
+
+/** Provides the SDK client factory to the backend's module graph. */
+@Module({ providers: [ForgeCartClientFactory], exports: [ForgeCartClientFactory] })
+export class ForgeCartModule {}

package/templates/storefront-shadcn/src/server/runner.ts

@@ -0,0 +1,90 @@
+import 'server-only';
+
+import { extractError, type ExtractedError } from '@forgecart/sdk';
+import { cookies } from 'next/headers';
+
+import { UNREACHABLE_ERROR, type ActionResult } from '../lib/action-result';
+import { SESSION_COOKIE } from '../lib/session-cookies';
+import { getBackend } from './bootstrap';
+import { ForgeCartClientFactory } from './forgecart/forgecart-client.factory';
+import { BackendError } from './types';
+import type { BackendSession } from './types';
+
+/** The gate has no env yet (image pre-warm / before `forgecart init`). */
+const NOT_CONFIGURED: ExtractedError = {
+  code: 'BACKEND_NOT_CONFIGURED',
+  variables: {},
+  classification: 'INTERNAL_ERROR',
+};
+
+/**
+ * Dispatch one `sdk.backend` invocation: resolve the booted registry, build
+ * the per-invocation SDK clients, run the method, translate every failure
+ * into the in-band envelope, and dispose both client websockets with the
+ * invocation — the exact contract of `lib/shop-action.ts`, extended with the
+ * admin gate.
+ *
+ * Fail-closed rules: an unknown name (type-cast bypass, or a STALE browser
+ * bundle calling a method a newer deploy removed) answers
+ * BACKEND_METHOD_NOT_FOUND; a boot failure (the api-map drift check)
+ * answers BACKEND_BOOT_FAILED carrying the boot error's message so the
+ * agent sees the actionable text in the envelope too, not only in the logs.
+ */
+export async function invokeBackendMethod(
+  method: string,
+  input: unknown,
+): Promise<ActionResult<unknown>> {
+  let registry: ReadonlyMap<string, (session: BackendSession, input: unknown) => Promise<unknown>>;
+  let factory: ForgeCartClientFactory;
+  try {
+    const runtime = await getBackend();
+    registry = runtime.registry;
+    factory = runtime.ctx.get(ForgeCartClientFactory, { strict: false });
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: 'BACKEND_BOOT_FAILED',
+        variables: { reason: error instanceof Error ? error.message : String(error) },
+        classification: 'INTERNAL_ERROR',
+      },
+    };
+  }
+
+  const fn = registry.get(method);
+  if (!fn) {
+    return {
+      ok: false,
+      error: {
+        code: 'BACKEND_METHOD_NOT_FOUND',
+        variables: { method },
+        classification: 'BAD_USER_INPUT',
+      },
+    };
+  }
+  if (!factory.isConfigured()) {
+    return { ok: false, error: NOT_CONFIGURED };
+  }
+
+  const store = await cookies();
+  const sessionToken = store.get(SESSION_COOKIE)?.value;
+  const admin = factory.getAdmin();
+  const shop = factory.buildShop(sessionToken);
+  const session: BackendSession = { admin, shop, hasSession: Boolean(sessionToken) };
+  try {
+    const data = await fn(session, input);
+    return { ok: true, data };
+  } catch (error) {
+    if (error instanceof BackendError) {
+      return {
+        ok: false,
+        error: { code: error.code, variables: error.variables, classification: 'BAD_USER_INPUT' },
+      };
+    }
+    return { ok: false, error: extractError(error) ?? UNREACHABLE_ERROR };
+  } finally {
+    // Only the session client dies with the invocation — the admin socket is
+    // the factory's process-long singleton.
+    shop.dispose();
+  }
+}

package/templates/storefront-shadcn/src/server/types.ts

@@ -0,0 +1,36 @@
+import 'server-only';
+
+import type { ForgeCartAdminClient, ForgeCartShopClient } from '@forgecart/sdk';
+
+/**
+ * The per-invocation context every backend method receives as its first
+ * argument. Both SDK gates are built fresh for THIS invocation by the runner
+ * and disposed with it (they are per-invocation websockets — same discipline
+ * as `lib/shop-action.ts`), so methods never construct or dispose clients.
+ *
+ * `admin` carries FULL channel authority (FORGECART_ADMIN_SECRET). A backend
+ * method is shopper-invocable, so nothing upstream gates what the admin
+ * client is used for — the method body owns that decision.
+ */
+export interface BackendSession {
+  admin: ForgeCartAdminClient;
+  shop: ForgeCartShopClient;
+  /** True when the request carried a shopper session cookie. */
+  hasSession: boolean;
+}
+
+/**
+ * Typed failure a backend method throws for its own business rules
+ * (missing login, invalid input, unmet precondition). The runner translates
+ * it into the standard `ActionResult` envelope exactly like an SDK error,
+ * so the client renders `code`/`variables` through the same error spine.
+ */
+export class BackendError extends Error {
+  constructor(
+    readonly code: string,
+    readonly variables: Record<string, string> = {},
+  ) {
+    super(code);
+    this.name = 'BackendError';
+  }
+}

package/templates/storefront-shadcn/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}