@spindlecommerce/storefront-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The SpindleCommerce authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @spindlecommerce/storefront-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Page builder components defined in a [SpindleCommerce](https://spindlecommerce.com) storefront's code: deploy them to the platform, and generate TypeScript types for their content.
+
+```bash
+pnpm add -D @spindlecommerce/storefront-cli
+
+spindle-storefront components pull --out components.json        # export the platform's library
+spindle-storefront components push components.json [--prune]   # deploy definitions
+spindle-storefront components types --from components.json --out lib/builder-components.ts
+```
+
+`push` updates components by code and marks them as managed in code; the admin warns before anyone edits those. `--prune` deletes code-managed components missing from the file, and is refused while pages use them. The whole push is one transaction.
+
+The commands call the Admin API with an admin API key: `content:read` to pull, `content:write` to push. Pass `--url` and `--key`, or set `SPINDLE_API_URL` and `SPINDLE_API_KEY`. `--env-file .env.local` also reads them from that file, if it exists.
+
+`generateTypes(definitions)` is also exported, for build scripts.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { generateTypes } from "./generate.js";
+const usage = `Usage:
+  spindle-storefront components pull  [--out components.json]
+  spindle-storefront components push  [components.json] [--prune]
+  spindle-storefront components types [--from components.json] [--out builder-components.ts]
+Options:
+  --url <url>        The platform (SPINDLE_API_URL), by default http://localhost:4000
+  --key <key>        An admin API key (SPINDLE_API_KEY): content:read to pull, content:write to push
+  --env-file <path>  Also read those variables from this file, if it exists`;
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        url: { type: "string" },
+        key: { type: "string" },
+        out: { type: "string" },
+        from: { type: "string" },
+        prune: { type: "boolean", default: false },
+        "env-file": { type: "string" },
+        help: { type: "boolean", short: "h", default: false },
+    },
+});
+const envFile = values["env-file"];
+if (envFile && existsSync(envFile))
+    process.loadEnvFile(envFile);
+const url = (values.url ?? process.env.SPINDLE_API_URL ?? "http://localhost:4000").replace(/\/+$/, "");
+const key = values.key ?? process.env.SPINDLE_API_KEY;
+const [group, command, file] = positionals;
+const admin = async (query, variables = {}) => {
+    if (!key)
+        throw new Error("Pass an admin API key with --key or SPINDLE_API_KEY (System › API keys in the admin).");
+    const response = await fetch(`${url}/admin/graphql`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+        body: JSON.stringify({ query, variables }),
+    });
+    const body = (await response.json().catch(() => null));
+    if (!response.ok || !body || body.errors?.length)
+        throw new Error(`The API refused the request: ${body?.errors?.map((e) => e.message).join("; ") ?? `HTTP ${response.status}`}`);
+    return body.data;
+};
+const pullDefinitions = async () => (await admin(`{ components { definition } }`)).components.map((c) => c.definition);
+const readDefinitions = async (path) => {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const list = Array.isArray(parsed) ? parsed : parsed.components;
+    if (!Array.isArray(list))
+        throw new Error(`${path} should hold an array of component definitions (or { "components": [...] })`);
+    return list;
+};
+const run = async () => {
+    if (values.help || !group)
+        return console.log(usage);
+    if (group !== "components")
+        throw new Error(`Unknown command ${group}.\n${usage}`);
+    if (command === "pull") {
+        const definitions = await pullDefinitions();
+        const json = `${JSON.stringify(definitions, null, 2)}\n`;
+        if (values.out) {
+            await writeFile(values.out, json);
+            console.log(`Wrote ${definitions.length} definitions to ${values.out}.`);
+        }
+        else
+            process.stdout.write(json);
+        return;
+    }
+    if (command === "push") {
+        const path = file ?? "components.json";
+        const definitions = await readDefinitions(path);
+        const { componentsSync: result } = await admin(`mutation($d: JSON!, $p: Boolean) { componentsSync(definitions: $d, prune: $p) { __typename ... on ComponentsSyncPayload { created updated unchanged removed } ... on Error { message } ... on ValidationError { fieldErrors { path message } } } }`, { d: definitions, p: values.prune });
+        if (result.__typename !== "ComponentsSyncPayload") {
+            const details = result.fieldErrors?.map((f) => `  ${f.path.join(".")}: ${f.message}`).join("\n");
+            throw new Error(`${result.message ?? result.__typename}${details ? `\n${details}` : ""}`);
+        }
+        const count = (codes) => codes?.length ?? 0;
+        console.log(`Deployed ${definitions.length} definitions from ${path}: ${count(result.created)} created, ${count(result.updated)} updated, ${count(result.unchanged)} unchanged, ${count(result.removed)} removed.`);
+        for (const [label, codes] of [["created", result.created], ["updated", result.updated], ["removed", result.removed]])
+            if (codes?.length)
+                console.log(`  ${label}: ${codes.join(", ")}`);
+        return;
+    }
+    if (command === "types") {
+        const definitions = values.from ? await readDefinitions(values.from) : await pullDefinitions();
+        const source = generateTypes(definitions);
+        if (values.out) {
+            await writeFile(values.out, source);
+            console.log(`Wrote types for ${definitions.length} components to ${values.out}.`);
+        }
+        else
+            process.stdout.write(source);
+        return;
+    }
+    throw new Error(`Unknown command components ${command ?? ""}.\n${usage}`);
+};
+run().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/definitions.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Component definitions as the admin API takes and returns them (componentsSync, components). The
+ * platform's own model must stay assignable to these: test/unit/page-builder.test.ts checks it.
+ */
+export type FieldType = "text" | "richText" | "number" | "boolean" | "select" | "color" | "image" | "link" | "date" | "product" | "products" | "category" | "blocks" | "list";
+export type TemplateFor = "product" | "category";
+export type FieldOption = {
+    value: string;
+    label: string;
+};
+export type FieldDefinition = {
+    key: string;
+    type: FieldType;
+    label: string;
+    description?: string;
+    required?: boolean;
+    /** Text and rich text only: one value per locale. */
+    localized?: boolean;
+    /** Inspector tab, e.g. "Content", "Style". */
+    group?: string;
+    /** Only shown for these variations; all when absent. */
+    variations?: string[];
+    placeholder?: string;
+    multiline?: boolean;
+    options?: FieldOption[];
+    /** Numbers: value range. Text: length. blocks, list, products: item count. */
+    min?: number;
+    max?: number;
+    /** blocks only: component codes allowed here; empty allows every component. */
+    allowedComponents?: string[];
+    /** list only: the fields of each item. */
+    fields?: FieldDefinition[];
+    defaultValue?: unknown;
+};
+export type Variation = {
+    code: string;
+    name: string;
+    description?: string;
+    previewImageUrl?: string;
+};
+export type ComponentDefinition = {
+    code: string;
+    kind: "content_type" | "component";
+    name: string;
+    description?: string | null;
+    groupName?: string | null;
+    icon?: string | null;
+    previewImageUrl?: string | null;
+    fields: FieldDefinition[];
+    variations: Variation[];
+    routable?: boolean;
+    singleton?: boolean;
+    /** A content type with it is a product or category template; a component with it shows that object's data. */
+    templateFor?: TemplateFor | null;
+    /** Content types only: pages of this type are one product's or category's own sections. */
+    sectionsFor?: TemplateFor | null;
+};

package/dist/definitions.js

@@ -0,0 +1,5 @@
+/**
+ * Component definitions as the admin API takes and returns them (componentsSync, components). The
+ * platform's own model must stay assignable to these: test/unit/page-builder.test.ts checks it.
+ */
+export {};

package/dist/generate.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentDefinition } from "./definitions.ts";
+/** Types for content as the Storefront API delivers it: one locale, references as global ids. */
+export declare const generateTypes: (definitions: ComponentDefinition[]) => string;

package/dist/generate.js

@@ -0,0 +1,89 @@
+const pascal = (code) => code
+    .split(/[_-]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+const quote = (value) => JSON.stringify(value);
+const fieldType = (field, nodeType, all) => {
+    switch (field.type) {
+        case "text":
+        case "richText":
+        case "color":
+        case "date":
+            return "string | null";
+        case "number":
+            return "number | null";
+        case "boolean":
+            return "boolean";
+        case "select":
+            return `${(field.options ?? []).map((o) => quote(o.value)).join(" | ") || "string"} | null`;
+        case "image":
+            return "BuilderImage | null";
+        case "link":
+            return "BuilderLink | null";
+        case "product":
+        case "category":
+            return "string | null";
+        case "products":
+            return "string[]";
+        case "blocks": {
+            const allowed = field.allowedComponents?.length ? field.allowedComponents : all.filter((c) => c.kind === "component").map((c) => c.code);
+            return `Array<${allowed.map(nodeType).join(" | ") || "never"}>`;
+        }
+        case "list":
+            return `Array<BuilderItem<{ ${(field.fields ?? []).map((f) => `${f.key}: ${fieldType(f, nodeType, all)}`).join("; ")} }>>`;
+    }
+};
+/** Types for content as the Storefront API delivers it: one locale, references as global ids. */
+export const generateTypes = (definitions) => {
+    const nodeType = (code) => `${pascal(code)}Node`;
+    const lines = [
+        "// Generated by `spindle-storefront components types`; regenerate after changing components.",
+        "// Content as the Storefront API delivers it: text in the request locale, links with hrefs,",
+        "// products and categories as global ids (resolve them through Page.references).",
+        "",
+        "export type BuilderImage = { url: string; alt: string | null; width: number | null; height: number | null };",
+        'export type BuilderLink = { kind: "url" | "page" | "product" | "category"; href: string | null; id: string | null; newTab: boolean };',
+        "export type BuilderItem<F> = { id: string; fields: F };",
+        "export type BuilderNode<C extends string, F, V extends string | null = null> = { id: string; component: C; variation: V; fields: F };",
+        "",
+    ];
+    for (const def of [...definitions].sort((a, b) => a.code.localeCompare(b.code))) {
+        const variations = def.variations.length ? def.variations.map((v) => quote(v.code)).join(" | ") : "null";
+        const binding = def.templateFor
+            ? def.kind === "content_type"
+                ? ` A template for ${def.templateFor} pages.`
+                : ` Shows ${def.templateFor} data, so only in ${def.templateFor} templates and sections.`
+            : def.sectionsFor
+                ? ` Belongs to one ${def.sectionsFor}: render it where the ${def.sectionsFor}'s template places its sections.`
+                : "";
+        lines.push(`/** ${def.name}${def.description ? `: ${def.description}` : ""}${binding} */`);
+        if (def.fields.length) {
+            lines.push(`export type ${pascal(def.code)}Fields = {`);
+            for (const field of def.fields) {
+                const optional = field.variations?.length ? "?" : "";
+                const doc = [field.label, field.description, field.variations?.length ? `Only for ${field.variations.join(", ")}.` : ""].filter(Boolean).join(". ");
+                lines.push(`  /** ${doc} */`);
+                lines.push(`  ${field.key}${optional}: ${fieldType(field, nodeType, definitions)};`);
+            }
+            lines.push("};");
+        }
+        else
+            lines.push(`export type ${pascal(def.code)}Fields = Record<string, never>;`);
+        lines.push(`export type ${nodeType(def.code)} = BuilderNode<${quote(def.code)}, ${pascal(def.code)}Fields, ${variations}>;`, "");
+    }
+    const components = definitions.filter((d) => d.kind === "component").map((d) => nodeType(d.code));
+    const contentTypes = definitions.filter((d) => d.kind === "content_type").map((d) => nodeType(d.code));
+    lines.push(`/** Any component that can appear inside a blocks field. */`);
+    lines.push(`export type BuilderComponentNode = ${components.join(" | ") || "never"};`);
+    lines.push(`/** The root of a page, by content type. */`);
+    lines.push(`export type BuilderContentTypeNode = ${contentTypes.join(" | ") || "never"};`);
+    lines.push(`export type BuilderComponentCode = BuilderComponentNode["component"];`);
+    lines.push(`export type BuilderContentTypeCode = BuilderContentTypeNode["component"];`, "");
+    for (const kind of ["product", "category"]) {
+        const codes = definitions.filter((d) => d.kind === "component" && d.templateFor === kind).map((d) => quote(d.code));
+        lines.push(`/** Components that show ${kind} data: they render inside ${kind} templates and a ${kind}'s own sections, with the ${kind}. */`);
+        lines.push(`export type Builder${pascal(kind)}ComponentCode = ${codes.join(" | ") || "never"};`);
+    }
+    lines.push("");
+    return lines.join("\n");
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { ComponentDefinition, FieldDefinition, FieldOption, FieldType, TemplateFor, Variation } from "./definitions.ts";
+export { generateTypes } from "./generate.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export { generateTypes } from "./generate.js";

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@spindlecommerce/storefront-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Deploy a SpindleCommerce storefront's page-builder components from its code, and generate TypeScript types for their content.",
+  "keywords": [
+    "spindlecommerce",
+    "storefront"
+  ],
+  "homepage": "https://github.com/spindlecommerce/storefront-sdk/tree/main/packages/storefront-cli#readme",
+  "bugs": "https://github.com/spindlecommerce/storefront-sdk/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spindlecommerce/storefront-sdk.git",
+    "directory": "packages/storefront-cli"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "spindle-storefront": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }