@jxsuite/create 0.34.0 → 0.35.0

package/cli-args.ts

@@ -0,0 +1,36 @@
+/** Argument parsing for the create-jxsuite CLI, split out so it can be unit-tested in isolation. */
+
+export interface CliArgs {
+  /** Destination directory (first non-flag argument). */
+  dest?: string;
+  /** Starter template id from `--template <id>` / `--template=<id>`. */
+  template?: string;
+}
+
+/**
+ * Parse the create-jxsuite argument list: the first non-flag token is the destination directory;
+ * `--template <id>` or `--template=<id>` selects a starter template.
+ *
+ * @param {string[]} argv — arguments after the node/script path (i.e. process.argv.slice(2))
+ * @returns {CliArgs}
+ */
+export function parseCliArgs(argv: string[]): CliArgs {
+  const positional: string[] = [];
+  let template: string | undefined;
+  for (let i = 0; i < argv.length; i += 1) {
+    // Safe: i < argv.length. The cast sheds `undefined` from noUncheckedIndexedAccess.
+    const arg = argv[i] as string;
+    if (arg === "--template") {
+      template = argv[i + 1];
+      i += 1;
+    } else if (arg.startsWith("--template=")) {
+      template = arg.slice("--template=".length);
+    } else {
+      positional.push(arg);
+    }
+  }
+  return {
+    ...(positional[0] !== undefined ? { dest: positional[0] } : {}),
+    ...(template !== undefined ? { template } : {}),
+  };
+}

package/generate.ts

@@ -1,22 +1,67 @@
 /** Shared project generation logic. Used by both the CLI scaffolder and the Studio server endpoint. */
 
-import { cp, mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+
+import { Buffer } from "node:buffer";
 
 import { existsSync } from "node:fs";
+import { mediaForTemplate } from "./templates";
+import type { TemplateId } from "./templates";
 
 const __dirname = import.meta.dirname;
 const TEMPLATE_DIR = join(__dirname, "template");
+const TEMPLATE_OVERLAYS_DIR = join(__dirname, "templates");
+
+export interface DesignOptions {
+  /** Accent / primary brand color (hex). */
+  accent?: string;
+  /** Page background color (hex). */
+  background?: string;
+  /** Body text color (hex). */
+  text?: string;
+  /** Body font stack. */
+  bodyFont?: string;
+  /** Heading font stack. */
+  headingFont?: string;
+  /** Replaces project.json $media entirely when provided (name → query/width map). */
+  media?: Record<string, string>;
+  /** Logo image written to public/<name>. base64 is the raw file content, no data: prefix. */
+  logo?: { name: string; base64: string };
+}
 
 export interface ProjectOptions {
   name: string;
   description?: string;
   url?: string;
   adapter?: "static" | "cloudflare-pages" | "cloudflare-workers" | "node" | "bun";
+  /**
+   * Id of a starter template to clone (from @jxsuite/starters), or "blank"/undefined for the
+   * built-in minimal template.
+   */
+  starter?: string;
+  /**
+   * Id of a built-in template variant (from ./templates). Ignored when a non-blank starter is
+   * given; undefined means "blank".
+   */
+  template?: TemplateId;
+  /** Design quickstart (colors, fonts, logo, breakpoints) applied on top of the scaffold. */
+  design?: DesignOptions;
 }
 
 const CF_ADAPTERS = new Set(["cloudflare-pages", "cloudflare-workers"]);
 
+// Paths never copied out of a starter tree into a fresh project: build artifacts and the
+// Authoring-only Pexels fetch manifest.
+const STARTER_EXCLUDE = new Set([
+  "node_modules",
+  "dist",
+  ".cache",
+  ".jx-cache",
+  ".git",
+  "images.json",
+]);
+
 /**
  * Generate a new Jx project at the given path.
  *
@@ -24,7 +69,15 @@ const CF_ADAPTERS = new Set(["cloudflare-pages", "cloudflare-workers"]);
  * @param {ProjectOptions} opts
  */
 export async function generateProject(destPath: string, opts: ProjectOptions) {
-  const { name, description = "", url = "", adapter = "static" } = opts;
+  const {
+    name,
+    description = "",
+    url = "",
+    adapter = "static",
+    starter,
+    template = "blank",
+    design,
+  } = opts;
 
   if (existsSync(destPath)) {
     const { readdirSync } = await import("node:fs");
@@ -34,11 +87,26 @@ export async function generateProject(destPath: string, opts: ProjectOptions) {
   }
 
   await mkdir(destPath, { recursive: true });
+
+  if (starter && starter !== "blank") {
+    await scaffoldFromStarter(destPath, starter, {
+      adapter,
+      description,
+      name,
+      url,
+      ...(design !== undefined ? { design } : {}),
+    });
+    return;
+  }
+
   await mkdir(join(destPath, "components"), { recursive: true });
   await mkdir(join(destPath, "public"), { recursive: true });
   await mkdir(join(destPath, "content"), { recursive: true });
 
-  const projectJson = buildProjectJson({ adapter, description, name, url });
+  const projectJson = buildProjectJson({ adapter, description, name, template, url });
+  if (design) {
+    applyDesign(projectJson as unknown as Record<string, unknown>, design, { starter: false });
+  }
   const packageJson = buildPackageJson({ adapter, description, name });
 
   const writes = [
@@ -55,6 +123,187 @@ export async function generateProject(destPath: string, opts: ProjectOptions) {
   }
 
   await Promise.all(writes);
+
+  // The mobile-app variant overlays the shared skeleton with its app-shell layout and home page.
+  // Sequenced after the base copies so the overlay files win.
+  if (template === "mobile-app") {
+    await cp(join(TEMPLATE_OVERLAYS_DIR, "mobile-app"), destPath, {
+      force: true,
+      recursive: true,
+    });
+  }
+
+  if (design?.logo) {
+    await writeLogo(destPath, design.logo);
+  }
+}
+
+/**
+ * Clone a starter template from @jxsuite/starters, then re-stamp the files that carry the new
+ * project's identity: project.json (name/url/description/adapter) and a freshly-built package.json
+ * (current dependency ranges, user's name). Content, components, layouts, and public assets are
+ * copied verbatim.
+ *
+ * @param {string} destPath
+ * @param {string} starter
+ * @param {Required<Pick<ProjectOptions, "name">> &
+ *   Pick<ProjectOptions, "description" | "url" | "adapter">} opts
+ */
+async function scaffoldFromStarter(
+  destPath: string,
+  starter: string,
+  opts: {
+    name: string;
+    description?: string;
+    url?: string;
+    adapter?: ProjectOptions["adapter"];
+    design?: DesignOptions;
+  },
+) {
+  const { name, description = "", url = "", adapter = "static", design } = opts;
+
+  // Resolved lazily so blank projects never load the (large) starters package.
+  const { getStarterDir } = await import("@jxsuite/starters");
+  const srcDir = getStarterDir(starter);
+
+  await cp(srcDir, destPath, {
+    recursive: true,
+    filter: (src) => {
+      const rel = relative(srcDir, src);
+      return rel === "" || !rel.split(sep).some((seg) => STARTER_EXCLUDE.has(seg));
+    },
+  });
+
+  // Re-stamp project.json with the new project's identity, keeping the starter's design tokens,
+  // Content types, image pipeline, and head.
+  const projectPath = join(destPath, "project.json");
+  const project = JSON.parse(await readFile(projectPath, "utf8")) as Record<string, unknown>;
+  project.name = name;
+  if (url) {
+    project.url = url;
+  }
+  applyDescription(project, description);
+  if (adapter && adapter !== "static") {
+    const build = (project.build as Record<string, unknown> | undefined) ?? {};
+    build.adapter = adapter;
+    project.build = build;
+  }
+  if (design) {
+    applyDesign(project, design, { starter: true });
+  }
+  await writeFile(projectPath, `${JSON.stringify(project, null, "\t")}\n`);
+
+  // Rebuild package.json so scaffolded projects get current dep ranges and scripts regardless of
+  // What the in-repo starter pinned.
+  const packageJson = buildPackageJson({ adapter, description, name });
+  await writeFile(join(destPath, "package.json"), `${JSON.stringify(packageJson, null, "  ")}\n`);
+
+  if (adapter && CF_ADAPTERS.has(adapter)) {
+    const wranglerJsonc = buildWranglerJsonc({ adapter, slug: packageJson.name });
+    await writeFile(join(destPath, "wrangler.jsonc"), wranglerJsonc);
+  }
+
+  if (design?.logo) {
+    await writeLogo(destPath, design.logo);
+  }
+}
+
+/**
+ * Apply the design quickstart (colors, fonts, breakpoints) to a project.json object, in place.
+ *
+ * Blank projects own their style block, so values are written directly. Starters are re-themed
+ * best-effort against the conventions the in-repo starters share (`--color-primary`,
+ * `--color-text-primary`, `--font-body`, `--font-heading`, top-level `fontFamily` /
+ * `backgroundColor`): an override only lands on a token key the starter's style already declares
+ * (falling back to the plain CSS property where noted), and is otherwise skipped silently rather
+ * than fighting the starter's layered styles. `--color-primary-hover` is intentionally left alone.
+ *
+ * @param {Record<string, unknown>} project — parsed project.json, mutated in place
+ * @param {DesignOptions} design
+ * @param {{ starter: boolean }} mode — starter clone vs. blank/template scaffold
+ */
+function applyDesign(
+  project: Record<string, unknown>,
+  design: DesignOptions,
+  { starter }: { starter: boolean },
+) {
+  const { accent, background, text, bodyFont, headingFont, media } = design;
+  const style = project.style as Record<string, unknown> | undefined;
+
+  if (style) {
+    if (accent && (!starter || "--color-primary" in style)) {
+      style["--color-primary"] = accent;
+    }
+    if (text) {
+      if (!starter) {
+        style.color = text;
+      } else if ("--color-text-primary" in style) {
+        style["--color-text-primary"] = text;
+      } else if ("color" in style) {
+        style.color = text;
+      }
+    }
+    if (background && (!starter || "backgroundColor" in style)) {
+      style.backgroundColor = background;
+    }
+    if (bodyFont) {
+      if (!starter) {
+        style.fontFamily = bodyFont;
+      } else if ("--font-body" in style) {
+        style["--font-body"] = bodyFont;
+      } else if ("fontFamily" in style) {
+        style.fontFamily = bodyFont;
+      }
+    }
+    if (headingFont && (!starter || "--font-heading" in style)) {
+      style["--font-heading"] = headingFont;
+    }
+  }
+
+  if (media && Object.keys(media).length > 0) {
+    project.$media = media;
+  }
+}
+
+/** File types accepted for the quickstart logo. */
+const LOGO_EXTENSION = /\.(svg|png|jpe?g|webp|gif|ico)$/i;
+
+/**
+ * Write the design-quickstart logo into the project's public/ directory. The provided name is
+ * flattened to its basename (no path segments can escape public/) and must carry an image extension
+ * — this is the only guard between UI input and the filesystem.
+ *
+ * @param {string} destPath — absolute path to the project directory
+ * @param {{ name: string; base64: string }} logo
+ */
+async function writeLogo(destPath: string, logo: { name: string; base64: string }) {
+  const fileName = basename(logo.name);
+  if (!LOGO_EXTENSION.test(fileName)) {
+    throw new Error(
+      `Logo file type not allowed: "${logo.name}" (expected .svg, .png, .jpg, .jpeg, .webp, .gif, or .ico)`,
+    );
+  }
+  const publicDir = join(destPath, "public");
+  await mkdir(publicDir, { recursive: true });
+  await writeFile(join(publicDir, fileName), Buffer.from(logo.base64, "base64"));
+}
+
+/**
+ * Set the `<meta name="description">` content in a project's `$head` (or leave it untouched when
+ * the starter has no such tag or no description was supplied).
+ *
+ * @param {Record<string, unknown>} project
+ * @param {string} description
+ */
+function applyDescription(project: Record<string, unknown>, description: string) {
+  if (!description || !Array.isArray(project.$head)) {
+    return;
+  }
+  for (const tag of project.$head as { tagName?: string; attributes?: Record<string, unknown> }[]) {
+    if (tag.tagName === "meta" && tag.attributes?.name === "description") {
+      tag.attributes.content = description;
+    }
+  }
 }
 
 /**
@@ -86,14 +335,28 @@ function buildWranglerJsonc({ slug, adapter }: { slug: string; adapter: string }
 }
 
 /** @param {ProjectOptions} opts */
-function buildProjectJson({ name, description, url, adapter }: ProjectOptions) {
+function buildProjectJson({ name, description, url, adapter, template = "blank" }: ProjectOptions) {
+  // Mobile-app shells draw under device notches/home bars; viewport-fit=cover makes the safe-area
+  // Insets used by the app-shell layout take effect.
+  const viewport =
+    template === "mobile-app"
+      ? "width=device-width, initial-scale=1, viewport-fit=cover"
+      : "width=device-width, initial-scale=1";
+
   const $head = [
     {
-      attributes: { content: "width=device-width, initial-scale=1", name: "viewport" },
+      attributes: { content: viewport, name: "viewport" },
       tagName: "meta",
     },
   ];
 
+  if (template === "mobile-app") {
+    $head.push({
+      attributes: { content: "#ffffff", name: "theme-color" },
+      tagName: "meta",
+    });
+  }
+
   if (description) {
     $head.push({
       attributes: { content: description, name: "description" },
@@ -113,12 +376,7 @@ function buildProjectJson({ name, description, url, adapter }: ProjectOptions) {
 
   return {
     $head,
-    $media: {
-      "--": "1280px",
-      "--lg": "(max-width: 1024px)",
-      "--md": "(max-width: 768px)",
-      "--sm": "(max-width: 640px)",
-    },
+    $media: mediaForTemplate(template),
     build,
     defaults: {
       lang: "en",

package/index.ts

@@ -8,12 +8,17 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { basename, resolve } from "node:path";
+import { listStarters } from "@jxsuite/starters";
+import { parseCliArgs } from "./cli-args";
 import { generateProject } from "./generate";
+import { isTemplateId, listTemplates } from "./templates";
 import type { ProjectOptions } from "./generate";
+import type { TemplateId } from "./templates";
 
-const [dest] = process.argv.slice(2);
+// The first non-flag arg is the destination; --template <id> selects a starter (skips the prompt).
+const { dest, template: templateFlag } = parseCliArgs(process.argv.slice(2));
 if (!dest) {
-  console.error("Usage: bun create @jxsuite <directory>");
+  console.error("Usage: bun create @jxsuite <directory> [--template <id>]");
   process.exit(1);
 }
 
@@ -32,6 +37,35 @@ async function main() {
   const description = await rl.question("Description: ");
   const url = await rl.question("Production URL (https://example.com): ");
 
+  const starters = listStarters();
+  const templates = listTemplates();
+  let starter = "blank";
+  let template: TemplateId = "blank";
+  if (templateFlag !== undefined) {
+    // Non-interactive: honor --template — built-in template ids win over starter ids, and an
+    // Unknown id falls back to blank.
+    if (isTemplateId(templateFlag)) {
+      template = templateFlag;
+    } else if (starters.some((s) => s.id === templateFlag)) {
+      starter = templateFlag;
+    }
+  } else {
+    console.log("\nStart from a template:");
+    for (const [i, t] of templates.entries()) {
+      console.log(`  ${i + 1}) ${t.name}${i === 0 ? " (default)" : ""}`);
+    }
+    for (const [i, s] of starters.entries()) {
+      console.log(`  ${i + templates.length + 1}) ${s.name} — ${s.tagline}`);
+    }
+    const templateChoice = await rl.question("Template [1]: ");
+    const idx = Math.trunc(Number(templateChoice));
+    if (idx >= 2 && idx <= templates.length) {
+      template = templates[idx - 1]?.id ?? "blank";
+    } else if (idx > templates.length && idx <= templates.length + starters.length) {
+      starter = starters[idx - templates.length - 1]?.id ?? "blank";
+    }
+  }
+
   console.log(`
 Deployment adapter:
   1) static (default)
@@ -52,7 +86,7 @@ Deployment adapter:
   };
   const adapter = adapterMap[adapterChoice] || "static";
 
-  await generateProject(destPath, { adapter, description, name, url });
+  await generateProject(destPath, { adapter, description, name, starter, template, url });
 
   console.log(`
 Project created at ${destPath}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/create",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Scaffold a new Jx project",
   "license": "MIT",
   "repository": {
@@ -14,12 +14,16 @@
   "files": [
     "index.ts",
     "generate.ts",
-    "template/"
+    "cli-args.ts",
+    "templates.ts",
+    "template/",
+    "templates/"
   ],
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./generate": "./generate.ts"
+    "./generate": "./generate.ts",
+    "./templates": "./templates.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -27,5 +31,8 @@
   "scripts": {
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage"
+  },
+  "dependencies": {
+    "@jxsuite/starters": "^0.35.0"
   }
 }

package/templates/mobile-app/layouts/base.json

@@ -0,0 +1,96 @@
+{
+  "tagName": "div",
+  "style": {
+    "margin": "0",
+    "padding": "0",
+    "height": "100dvh",
+    "display": "flex",
+    "flexDirection": "column",
+    "fontFamily": "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+    "lineHeight": "1.6",
+    "color": "#1a1a1a",
+    "backgroundColor": "#ffffff"
+  },
+  "children": [
+    {
+      "tagName": "header",
+      "style": {
+        "padding": "0.75rem 1rem",
+        "paddingTop": "calc(0.75rem + env(safe-area-inset-top))",
+        "borderBottom": "1px solid #e5e5e5",
+        "textAlign": "center"
+      },
+      "children": [
+        {
+          "tagName": "span",
+          "style": {
+            "fontSize": "1.05rem",
+            "fontWeight": "700"
+          },
+          "children": ["My App"]
+        }
+      ]
+    },
+    {
+      "tagName": "main",
+      "style": {
+        "flex": "1",
+        "overflowY": "auto",
+        "padding": "1rem",
+        "width": "100%"
+      },
+      "children": [{ "tagName": "slot" }]
+    },
+    {
+      "tagName": "nav",
+      "style": {
+        "display": "flex",
+        "borderTop": "1px solid #e5e5e5",
+        "paddingBottom": "env(safe-area-inset-bottom)",
+        "backgroundColor": "#ffffff"
+      },
+      "children": [
+        {
+          "tagName": "a",
+          "attributes": { "href": "/" },
+          "style": {
+            "flex": "1",
+            "padding": "0.75rem 0",
+            "textAlign": "center",
+            "textDecoration": "none",
+            "fontSize": "0.8rem",
+            "fontWeight": "600",
+            "color": "#1a1a1a"
+          },
+          "children": ["Home"]
+        },
+        {
+          "tagName": "a",
+          "attributes": { "href": "/explore/" },
+          "style": {
+            "flex": "1",
+            "padding": "0.75rem 0",
+            "textAlign": "center",
+            "textDecoration": "none",
+            "fontSize": "0.8rem",
+            "color": "#666"
+          },
+          "children": ["Explore"]
+        },
+        {
+          "tagName": "a",
+          "attributes": { "href": "/profile/" },
+          "style": {
+            "flex": "1",
+            "padding": "0.75rem 0",
+            "textAlign": "center",
+            "textDecoration": "none",
+            "fontSize": "0.8rem",
+            "color": "#666"
+          },
+          "children": ["Profile"]
+        }
+      ]
+    }
+  ]
+}

package/templates/mobile-app/pages/explore.md

@@ -0,0 +1,7 @@
+---
+title: Explore
+---
+
+# Explore
+
+Add your app's browse/discovery content here, at `pages/explore.md`.

package/templates/mobile-app/pages/index.md

@@ -0,0 +1,8 @@
+---
+title: Home
+---
+
+# Welcome
+
+Your new Jx app is ready. Edit this page at `pages/index.md`, and the app shell (header and bottom
+navigation) at `layouts/base.json`.

package/templates/mobile-app/pages/profile.md

@@ -0,0 +1,7 @@
+---
+title: Profile
+---
+
+# Profile
+
+Add your app's account/profile content here, at `pages/profile.md`.

package/templates.ts

@@ -0,0 +1,74 @@
+/**
+ * Built-in project templates. All are thin variants of the blank skeleton: they share the files in
+ * `template/` and differ in the generated project.json ($media direction, viewport meta) plus, for
+ * mobile-app, an overlay of app-shell files from `templates/mobile-app/`.
+ */
+
+export type TemplateId = "blank" | "desktop-first" | "mobile-first" | "mobile-app";
+
+export interface TemplateMeta {
+  id: TemplateId;
+  name: string;
+  description: string;
+}
+
+export const TEMPLATES: readonly TemplateMeta[] = [
+  {
+    description: "A minimal desktop-first site with a header, footer, and one page.",
+    id: "blank",
+    name: "Blank",
+  },
+  {
+    description: "The blank skeleton with desktop-first breakpoints (max-width media queries).",
+    id: "desktop-first",
+    name: "Desktop First",
+  },
+  {
+    description: "The blank skeleton with mobile-first breakpoints (min-width media queries).",
+    id: "mobile-first",
+    name: "Mobile First",
+  },
+  {
+    description: "A mobile-first app shell with a fixed bottom navigation and scrollable content.",
+    id: "mobile-app",
+    name: "Mobile App",
+  },
+];
+
+/** @returns {TemplateMeta[]} The built-in template list, for pickers and menus */
+export function listTemplates(): TemplateMeta[] {
+  return [...TEMPLATES];
+}
+
+/** @param {string} id */
+export function isTemplateId(id: string): id is TemplateId {
+  return TEMPLATES.some((t) => t.id === id);
+}
+
+// Desktop-first: base canvas is the widest; narrower breakpoints cascade via max-width.
+const DESKTOP_FIRST_MEDIA = {
+  "--": "1280px",
+  "--lg": "(max-width: 1024px)",
+  "--md": "(max-width: 768px)",
+  "--sm": "(max-width: 640px)",
+};
+
+// Mobile-first: base canvas is the narrowest; wider breakpoints cascade via min-width.
+const MOBILE_FIRST_MEDIA = {
+  "--": "375px",
+  "--sm": "(min-width: 640px)",
+  "--md": "(min-width: 768px)",
+  "--lg": "(min-width: 1024px)",
+};
+
+/**
+ * The project.json `$media` map for a template: desktop-first templates use max-width queries with
+ * the widest base; mobile-first templates use min-width queries with the narrowest base.
+ *
+ * @param {TemplateId} id
+ */
+export function mediaForTemplate(id: TemplateId): Record<string, string> {
+  return id === "mobile-first" || id === "mobile-app"
+    ? { ...MOBILE_FIRST_MEDIA }
+    : { ...DESKTOP_FIRST_MEDIA };
+}