@jxsuite/create 1.5.5 → 1.7.0

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, isJsonObject, parseJson } from "./scaffold";
+import { adapterNeedsWrangler, buildWranglerJsonc, isJsonObject } from "./scaffold";
 import { basename, join, relative, sep } from "node:path";
 
 import { Buffer } from "node:buffer";
@@ -12,7 +12,12 @@ import type { TemplateId } from "./templates";
 import type { JsonObject } from "./scaffold";
 
 import TEMPLATE_VERSIONS from "./template-versions.json";
-import { PROJECT_FILE_NAME, serializeProjectFile } from "@jxsuite/schema/project-file";
+import {
+  NEW_PROJECT_FILE_NAME,
+  parseProjectSource,
+  serializeProjectFile,
+} from "@jxsuite/schema/project-file";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 const __dirname = import.meta.dirname;
 const TEMPLATE_DIR = join(__dirname, "template");
@@ -200,7 +205,10 @@ async function populateProject(destPath: string, opts: ProjectOptions) {
   const packageJson = buildPackageJson({ adapter, description, name });
 
   const writes = [
-    writeFile(join(destPath, PROJECT_FILE_NAME), serializeProjectFile(projectJson, null)),
+    writeFile(
+      join(destPath, NEW_PROJECT_FILE_NAME),
+      withExtensionsNote(serializeProjectFile(projectJson, null)),
+    ),
     writeFile(join(destPath, "package.json"), `${JSON.stringify(packageJson, null, "  ")}\n`),
     cp(join(TEMPLATE_DIR, "gitignore"), join(destPath, ".gitignore")),
     cp(join(TEMPLATE_DIR, "layouts"), join(destPath, "layouts"), { recursive: true }),
@@ -213,6 +221,7 @@ async function populateProject(destPath: string, opts: ProjectOptions) {
   }
 
   await Promise.all(writes);
+  await writeEditorSupport(destPath);
 
   // The .gitignore, layouts/ and pages/ above are copies too, carrying the template's modes.
   // The overlay below would otherwise fail to `force` over a file that came across read-only.
@@ -272,14 +281,13 @@ async function scaffoldFromStarter(
   // Before the re-stamp below, which writes straight back into the tree that was just copied.
   await makeWritable(destPath);
 
-  // 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_FILE_NAME);
+  // Re-stamp the project file with the new project's identity, keeping the starter's design tokens,
+  // Content types, image pipeline, head, and in a project.jxn its comments.
+  const projectPath = projectFilePath(destPath);
   const starterText = await readFile(projectPath, "utf8");
-  const project = parseJson(starterText);
-  if (!isJsonObject(project)) {
-    throw new TypeError(`Starter "${starter}" has a project.json that is not a JSON object`);
-  }
+  /* SAFETY: both readers answer an object, or throw (a starter whose project file is a list is
+     refused there, naming the file), and every member below is one the re-stamp owns. */
+  const project = parseProjectSource(starterText, projectPath) as JsonObject;
   project.name = name;
   if (url) {
     project.url = url;
@@ -293,7 +301,10 @@ async function scaffoldFromStarter(
   if (design) {
     applyDesign(project, design, { starter: true });
   }
-  await writeFile(projectPath, serializeProjectFile(project, starterText));
+  await writeFile(projectPath, serializeProjectFile(project, starterText, projectPath));
+  await writeEditorSupport(destPath);
+  // Copied from a read-only install as the rest was, so made writable as the rest was.
+  await makeWritable(destPath);
 
   // Rebuild package.json so scaffolded projects get current dep ranges and scripts regardless of
   // What the in-repo starter pinned.
@@ -310,6 +321,36 @@ async function scaffoldFromStarter(
   }
 }
 
+/**
+ * A new project file, with one comment in it saying what `extensions` is for: the line a new user
+ * most needs explained, and the format's main advantage shown rather than described
+ * (`site-architecture.md` §2.4). The canonical form has no comments, so it goes in after.
+ *
+ * @param text The project file in its canonical form.
+ */
+function withExtensionsNote(text: string): string {
+  return text.replace(
+    /^extensions\b/m,
+    "// Extensions add what Jx does not do on its own. @jxsuite/parser reads pages/index.md and\n" +
+      "// every Markdown collection; turn others on in Studio, under Project Settings > Extensions.\n" +
+      "extensions",
+  );
+}
+
+/**
+ * What lets an editor and GitHub read `.jxn` from the first commit: Linguist knows KDL only as
+ * `.kdl`, and VS Code needs telling too. Both cost nothing, and an existing file is kept.
+ *
+ * @param destPath The project's root.
+ */
+async function writeEditorSupport(destPath: string): Promise<void> {
+  await mkdir(join(destPath, ".vscode"), { recursive: true });
+  await Promise.all([
+    cp(join(TEMPLATE_DIR, "gitattributes"), join(destPath, ".gitattributes"), { force: false }),
+    cp(join(TEMPLATE_DIR, "vscode"), join(destPath, ".vscode"), { force: false, recursive: true }),
+  ]);
+}
+
 /**
  * Apply the design quickstart (colors, fonts, breakpoints) to a project.json object, in place.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/create",
-  "version": "1.5.5",
+  "version": "1.7.0",
   "description": "Scaffold a new Jx project",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.3.0",
-    "@jxsuite/starters": "^3.3.1"
+    "@jxsuite/schema": "^5.5.0",
+    "@jxsuite/starters": "^3.4.0"
   }
 }

package/template/gitattributes

@@ -0,0 +1,2 @@
+# Jx Notation is KDL 2, which GitHub highlights only as .kdl
+*.jxn linguist-language=KDL

package/template/vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["kdl-org.kdl"]
+}

package/template/vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "*.jxn": "kdl"
+  }
+}

package/template-versions.json

@@ -1,6 +1,6 @@
 {
-  "parser": "^4.3.1",
-  "compiler": "^8.3.0",
-  "runtime": "^6.2.0",
-  "server": "^8.4.0"
+  "parser": "^4.3.3",
+  "compiler": "^8.5.0",
+  "runtime": "^6.2.2",
+  "server": "^8.6.0"
 }