@jxsuite/create 1.3.14 → 1.3.16

package/cli-args.ts

@@ -17,20 +17,24 @@ export interface 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;
+  // One iterator drives the loop, so `--template` can consume its value token with next().
+  const tokens = argv.values();
+  for (const arg of tokens) {
     if (arg === "--template") {
-      template = argv[i + 1];
-      i += 1;
+      template = tokens.next().value;
     } else if (arg.startsWith("--template=")) {
       template = arg.slice("--template=".length);
     } else {
       positional.push(arg);
     }
   }
-  return {
-    ...(positional[0] !== undefined ? { dest: positional[0] } : {}),
-    ...(template !== undefined ? { template } : {}),
-  };
+  const args: CliArgs = {};
+  const [dest] = positional;
+  if (dest !== undefined) {
+    args.dest = dest;
+  }
+  if (template !== undefined) {
+    args.template = template;
+  }
+  return args;
 }

package/generate.ts

@@ -1,7 +1,7 @@
 /** Shared project generation logic. Used by both the CLI scaffolder and the Studio server endpoint. */
 
 import { chmod, cp, lstat, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { adapterNeedsWrangler, buildWranglerJsonc } from "./scaffold";
+import { adapterNeedsWrangler, buildWranglerJsonc, isJsonObject, parseJson } from "./scaffold";
 import { basename, join, relative, sep } from "node:path";
 
 import { Buffer } from "node:buffer";
@@ -9,6 +9,7 @@ import { Buffer } from "node:buffer";
 import { existsSync } from "node:fs";
 import { mediaForTemplate } from "./templates";
 import type { TemplateId } from "./templates";
+import type { JsonObject } from "./scaffold";
 
 import TEMPLATE_VERSIONS from "./template-versions.json";
 
@@ -183,13 +184,7 @@ async function populateProject(destPath: string, opts: ProjectOptions) {
   } = opts;
 
   if (starter && starter !== "blank") {
-    await scaffoldFromStarter(destPath, starter, {
-      adapter,
-      description,
-      name,
-      url,
-      ...(design !== undefined ? { design } : {}),
-    });
+    await scaffoldFromStarter(destPath, starter, { adapter, description, design, name, url });
     return;
   }
 
@@ -199,7 +194,7 @@ async function populateProject(destPath: string, opts: ProjectOptions) {
 
   const projectJson = buildProjectJson({ adapter, description, name, template, url });
   if (design) {
-    applyDesign(projectJson as unknown as Record<string, unknown>, design, { starter: false });
+    applyDesign(projectJson, design, { starter: false });
   }
   const packageJson = buildPackageJson({ adapter, description, name });
 
@@ -256,7 +251,7 @@ async function scaffoldFromStarter(
     description?: string;
     url?: string;
     adapter?: ProjectOptions["adapter"];
-    design?: DesignOptions;
+    design?: DesignOptions | undefined;
   },
 ) {
   const { name, description = "", url = "", adapter = "static", design } = opts;
@@ -279,14 +274,17 @@ async function scaffoldFromStarter(
   // 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>;
+  const project = parseJson(await readFile(projectPath, "utf8"));
+  if (!isJsonObject(project)) {
+    throw new TypeError(`Starter "${starter}" has a project.json that is not a JSON object`);
+  }
   project.name = name;
   if (url) {
     project.url = url;
   }
   applyDescription(project, description);
-  if (adapter && adapter !== "static") {
-    const build = (project.build as Record<string, unknown> | undefined) ?? {};
+  if (adapter !== "static") {
+    const build = isJsonObject(project.build) ? project.build : {};
     build.adapter = adapter;
     project.build = build;
   }
@@ -320,19 +318,19 @@ async function scaffoldFromStarter(
  * (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 {JsonObject} 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>,
+  project: JsonObject,
   design: DesignOptions,
   { starter }: { starter: boolean },
 ) {
   const { accent, background, text, bodyFont, headingFont, media } = design;
-  const style = project.style as Record<string, unknown> | undefined;
+  const { style } = project;
 
-  if (style) {
+  if (isJsonObject(style)) {
     if (accent && (!starter || "--color-primary" in style)) {
       style["--color-primary"] = accent;
     }
@@ -394,25 +392,56 @@ async function writeLogo(destPath: string, logo: { name: string; base64: string
  * 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 {JsonObject} project
  * @param {string} description
  */
-function applyDescription(project: Record<string, unknown>, description: string) {
+function applyDescription(project: JsonObject, 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") {
+  for (const tag of project.$head) {
+    if (
+      isJsonObject(tag) &&
+      tag.tagName === "meta" &&
+      isJsonObject(tag.attributes) &&
+      tag.attributes.name === "description"
+    ) {
       tag.attributes.content = description;
     }
   }
 }
 
 /**
- * Build a wrangler.jsonc for Cloudflare adapters.
- *
- * @param {{ slug: string; adapter: string }} opts
+ * The scaffolded project.json `build` section. Non-static adapters add `adapter` through the
+ * JsonObject index signature; an optional `adapter?: string` member would conflict with that index
+ * under configs without `exactOptionalPropertyTypes` (packages/desktop's typecheck).
  */
+interface BuildSection extends JsonObject {
+  outDir: string;
+  trailingSlash: string;
+}
+
+/** Scaffolded package.json `dependencies`; `hono` joins for adapters with a server worker. */
+interface Dependencies {
+  "@jxsuite/parser": string;
+  hono?: string;
+}
+
+/** Scaffolded package.json `devDependencies`; `wrangler` joins for Cloudflare adapters. */
+interface DevDependencies {
+  "@jxsuite/compiler": string;
+  "@jxsuite/runtime": string;
+  "@jxsuite/server": string;
+  wrangler?: string;
+}
+
+/** Scaffolded package.json `scripts`; `deploy` joins for Cloudflare adapters. */
+interface PackageScripts {
+  build: string;
+  dev: string;
+  preview: string;
+  deploy?: string;
+}
 
 /** @param {ProjectOptions} opts */
 function buildProjectJson({ name, description, url, adapter, template = "blank" }: ProjectOptions) {
@@ -444,7 +473,7 @@ function buildProjectJson({ name, description, url, adapter, template = "blank"
     });
   }
 
-  const build: { outDir: string; trailingSlash: string; adapter?: string } = {
+  const build: BuildSection = {
     outDir: "./dist",
     trailingSlash: "always",
   };
@@ -502,17 +531,17 @@ function buildPackageJson({
   // (release-please-config.json extra-files). Hardcoding them here is what left every scaffolded
   // Project asking for a compiler version that was never published. Never hand-edit the
   // Map; `bun run templates:sync` is the fixer.
-  const dependencies: Record<string, string> = {
+  const dependencies: Dependencies = {
     "@jxsuite/parser": TEMPLATE_VERSIONS.parser,
   };
-  const devDependencies: Record<string, string> = {
+  const devDependencies: DevDependencies = {
     "@jxsuite/compiler": TEMPLATE_VERSIONS.compiler,
     "@jxsuite/runtime": TEMPLATE_VERSIONS.runtime,
     // The `dev` script spawns @jxsuite/server's dev entry (see jx dev in the compiler CLI)
     "@jxsuite/server": TEMPLATE_VERSIONS.server,
   };
 
-  const scripts: Record<string, string> = {
+  const scripts: PackageScripts = {
     build: "jx build",
     dev: "jx dev",
     preview: "jx preview",

package/index.ts

@@ -77,14 +77,14 @@ Deployment adapter:
   const adapterChoice = await rl.question("Adapter [1]: ");
   rl.close();
 
-  const adapterMap: Record<string, ProjectOptions["adapter"]> = {
-    1: "static",
-    2: "cloudflare-pages",
-    3: "node",
-    4: "bun",
-    5: "cloudflare-workers",
-  };
-  const adapter = adapterMap[adapterChoice] || "static";
+  const adapterMap = new Map<string, NonNullable<ProjectOptions["adapter"]>>([
+    ["1", "static"],
+    ["2", "cloudflare-pages"],
+    ["3", "node"],
+    ["4", "bun"],
+    ["5", "cloudflare-workers"],
+  ]);
+  const adapter = adapterMap.get(adapterChoice) ?? "static";
 
   await generateProject(destPath, { adapter, description, name, starter, template, url });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/create",
-  "version": "1.3.14",
+  "version": "1.3.16",
   "description": "Scaffold a new Jx project",
   "license": "MIT",
   "repository": {
@@ -37,6 +37,6 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/starters": "^2.0.1"
+    "@jxsuite/starters": "^3.0.0"
   }
 }

package/scaffold.ts

@@ -6,6 +6,55 @@
 
 const CF_ADAPTERS = new Set(["cloudflare-pages", "cloudflare-workers"]);
 
+/** A JSON primitive. */
+export type JsonPrimitive = string | number | boolean | null;
+/** Any value `JSON.parse` can produce, and `JSON.stringify` can write back unchanged. */
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+/** A JSON object: wrangler.jsonc, project.json and connector binding fragments are all one. */
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+/** The result of patching a wrangler.jsonc: the new text, and whether it was rewritten at all. */
+export interface WranglerPatch {
+  content: string;
+  patched: boolean;
+}
+
+/** A fragment array entry keyed by its `binding` name (`{ binding: "DB", database_id }`). */
+interface BindingEntry extends JsonObject {
+  binding: string;
+}
+
+/** Parse JSON text. Throws the `SyntaxError` `JSON.parse` raises for text that is not JSON. */
+export function parseJson(text: string): JsonValue {
+  // SAFETY: JSON.parse without a reviver can only build objects, arrays, strings, finite numbers,
+  // Booleans and null out of JSON text, which is exactly the JsonValue union.
+  return JSON.parse(text) as JsonValue;
+}
+
+/** True for a JSON object; false for arrays, primitives, null and a missing value. */
+export function isJsonObject(value: JsonValue | undefined): value is JsonObject {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isBindingEntry(value: JsonValue): value is BindingEntry {
+  return isJsonObject(value) && typeof value.binding === "string";
+}
+
+/**
+ * Parse a wrangler.jsonc that can be patched: undefined when it is comment-bearing JSONC (which
+ * `JSON.parse` rejects) or its top level is not an object, so callers leave the file alone.
+ */
+function parseWranglerObject(text: string): JsonObject | undefined {
+  try {
+    const parsed = parseJson(text);
+    return isJsonObject(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** True when the adapter deploys through wrangler (needs a wrangler.jsonc). */
 export function adapterNeedsWrangler(adapter: string | undefined): boolean {
   return Boolean(adapter && CF_ADAPTERS.has(adapter));
@@ -51,24 +100,24 @@ export function buildWranglerJsonc({ slug, adapter }: { slug: string; adapter: s
  * loss.
  *
  * @param {string | null} existing - Current wrangler.jsonc content, or null when absent
- * @param {Record<string, unknown>[]} fragments - Binding fragments, applied in order
- * @returns {{ content: string; patched: boolean }}
+ * @param {JsonObject[]} fragments - Binding fragments, applied in order
+ * @returns {WranglerPatch}
  */
 export function applyBindingFragments(
   existing: string | null,
-  fragments: Record<string, unknown>[],
-): { content: string; patched: boolean } {
+  fragments: JsonObject[],
+): WranglerPatch {
   if (fragments.length === 0) {
     return { content: existing ?? "", patched: false };
   }
-  let config: Record<string, unknown> = {};
+  let config: JsonObject = {};
   if (existing) {
-    try {
-      config = JSON.parse(existing) as Record<string, unknown>;
-    } catch {
-      // Comment-bearing JSONC — leave the user's file alone.
+    const parsed = parseWranglerObject(existing);
+    if (parsed === undefined) {
+      // Comment-bearing JSONC (or a non-object top level) — leave the user's file alone.
       return { content: existing, patched: false };
     }
+    config = parsed;
   }
   for (const fragment of fragments) {
     mergeBindingValue(config, fragment);
@@ -77,15 +126,18 @@ export function applyBindingFragments(
 }
 
 /** Recursively merge one fragment object into the target, per the applyBindingFragments rules. */
-function mergeBindingValue(target: Record<string, unknown>, fragment: Record<string, unknown>) {
+function mergeBindingValue(target: JsonObject, fragment: JsonObject) {
   for (const [key, incoming] of Object.entries(fragment)) {
-    const current = target[key];
+    /* A key the target lacks reads as undefined. Spelled out rather than left to
+       noUncheckedIndexedAccess, which the inferred program this file is linted in does not set
+       (packages/create/tsconfig.json does not include it). */
+    const current = key in target ? target[key] : undefined;
     if (Array.isArray(incoming)) {
       target[key] = mergeBindingArrays(Array.isArray(current) ? current : [], incoming);
       continue;
     }
-    if (isPlainObject(incoming)) {
-      if (isPlainObject(current)) {
+    if (isJsonObject(incoming)) {
+      if (isJsonObject(current)) {
         mergeBindingValue(current, incoming);
       } else if (current === undefined) {
         target[key] = structuredClone(incoming);
@@ -99,10 +151,10 @@ function mergeBindingValue(target: Record<string, unknown>, fragment: Record<str
 }
 
 /** Merge fragment array entries into an existing array, keyed by each entry's `binding`. */
-function mergeBindingArrays(current: unknown[], incoming: unknown[]): unknown[] {
+function mergeBindingArrays(current: JsonValue[], incoming: JsonValue[]): JsonValue[] {
   const merged = [...current];
   for (const entry of incoming) {
-    if (!isPlainObject(entry) || typeof entry.binding !== "string") {
+    if (!isBindingEntry(entry)) {
       // Non-binding-keyed values: append when missing (dedupe by deep equality).
       const exists = merged.some((m) => JSON.stringify(m) === JSON.stringify(entry));
       if (!exists) {
@@ -110,23 +162,19 @@ function mergeBindingArrays(current: unknown[], incoming: unknown[]): unknown[]
       }
       continue;
     }
-    const index = merged.findIndex(
-      (m) => isPlainObject(m) && (m as Record<string, unknown>).binding === entry.binding,
-    );
-    if (index === -1) {
-      merged.push(structuredClone(entry));
-    } else {
+    const index = merged.findIndex((m) => isJsonObject(m) && m.binding === entry.binding);
+    // Undefined when no entry matched (index -1), so a miss appends.
+    const match = merged[index];
+    if (isJsonObject(match)) {
       // Fragment values win for connector-owned keys; user-added extra keys survive.
-      merged[index] = { ...(merged[index] as Record<string, unknown>), ...entry };
+      merged[index] = { ...match, ...entry };
+    } else {
+      merged.push(structuredClone(entry));
     }
   }
   return merged;
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 /**
  * Patch an existing wrangler.jsonc for an adapter change (or a Pages project rename), touching only
  * the adapter-shape keys and preserving everything else the user added. Regenerates from scratch
@@ -137,15 +185,13 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 export function updateWranglerConfig(
   existing: string | null,
   { slug, adapter }: { slug: string; adapter: string },
-): { content: string; patched: boolean } {
+): WranglerPatch {
   if (!existing) {
     return { content: buildWranglerJsonc({ adapter, slug }), patched: true };
   }
-  let config: Record<string, unknown>;
-  try {
-    config = JSON.parse(existing) as Record<string, unknown>;
-  } catch {
-    // Comment-bearing JSONC — leave the user's file alone.
+  const config = parseWranglerObject(existing);
+  if (config === undefined) {
+    // Comment-bearing JSONC (or a non-object top level) — leave the user's file alone.
     return { content: existing, patched: false };
   }
   config["name"] = slug;

package/template-versions.json

@@ -1,6 +1,6 @@
 {
-  "parser": "^2.0.1",
-  "compiler": "^5.1.2",
-  "runtime": "^4.1.0",
-  "server": "^4.5.0"
+  "parser": "^4.0.0",
+  "compiler": "^6.0.1",
+  "runtime": "^5.0.0",
+  "server": "^6.0.0"
 }