@projectdochelp/s3te 3.0.0 → 3.1.1

package/README.md

@@ -136,9 +136,25 @@ cd mywebsite
 </details>
 
 <details>
-  <summary>2. Scaffold the project once</summary>
+  <summary>2. Install S3TE locally in the project</summary>
 
-If `@projectdochelp/s3te` is already published on npm, scaffold the project once with a temporary `npx` run:
+```bash
+npm install --save-dev @projectdochelp/s3te
+```
+</details>
+
+<details>
+  <summary>3. Scaffold the project</summary>
+
+With the local package installed, initialize the project like this:
+
+```bash
+npx s3te init --project-name mywebsite --base-url example.com
+```
+
+If `npm install` already created a minimal `package.json`, `s3te init` extends it with the missing S3TE defaults and scripts instead of failing.
+
+If you want a one-shot scaffold without installing first, and `@projectdochelp/s3te` is already published on npm, this also works:
 
 ```bash
 npx --package @projectdochelp/s3te s3te init --project-name mywebsite --base-url example.com
@@ -155,7 +171,7 @@ node packages/cli/bin/s3te.mjs init --dir ./mywebsite --project-name mywebsite -
 </details>
 
 <details>
-  <summary>3. What the scaffold creates</summary>
+  <summary>4. What the scaffold creates</summary>
 
 The default scaffold creates:
 
@@ -181,20 +197,6 @@ mywebsite/
 
 </details>
 
-<details>
-  <summary>4. Install S3TE locally in the project</summary>
-
-```bash
-npm install --save-dev @projectdochelp/s3te
-npx s3te --help
-```
-
-This is the recommended everyday setup. From this point on, you run the project-local version with `npx s3te ...`.
-
-If you want to use the built-in test helpers in your own project tests, import them from the same package via `@projectdochelp/s3te/testkit`.
-
-</details>
-
 <details>
   <summary>5. Fill in the real AWS values in <code>s3te.config.json</code></summary>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectdochelp/s3te",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "CLI, render core, AWS adapter, and testkit for S3TemplateEngine projects",
   "repository": {
     "type": "git",

package/packages/cli/src/project.mjs

@@ -125,6 +125,10 @@ async function fileExists(targetPath) {
   }
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 async function writeProjectFile(targetPath, body, force = false) {
   if (!force && await fileExists(targetPath)) {
     throw new Error(`Refusing to overwrite existing file: ${targetPath}`);
@@ -132,6 +136,57 @@ async function writeProjectFile(targetPath, body, force = false) {
   await writeTextFile(targetPath, body);
 }
 
+function mergeProjectPackageJson(existingPackageJson, projectPackageJson) {
+  if (!isPlainObject(existingPackageJson)) {
+    throw new Error("Existing package.json must contain a JSON object.");
+  }
+
+  if (existingPackageJson.scripts !== undefined && !isPlainObject(existingPackageJson.scripts)) {
+    throw new Error("Existing package.json must use an object for scripts.");
+  }
+
+  const mergedPackageJson = { ...existingPackageJson };
+  for (const [key, value] of Object.entries(projectPackageJson)) {
+    if (key === "scripts") {
+      continue;
+    }
+
+    if (mergedPackageJson[key] === undefined) {
+      mergedPackageJson[key] = value;
+    }
+  }
+
+  const mergedScripts = { ...(mergedPackageJson.scripts ?? {}) };
+  for (const [name, command] of Object.entries(projectPackageJson.scripts ?? {})) {
+    if (mergedScripts[name] === undefined) {
+      mergedScripts[name] = command;
+    }
+  }
+
+  if (Object.keys(mergedScripts).length > 0) {
+    mergedPackageJson.scripts = mergedScripts;
+  }
+
+  return mergedPackageJson;
+}
+
+async function writeProjectPackageJson(targetPath, projectPackageJson, force = false) {
+  if (force || !await fileExists(targetPath)) {
+    await writeTextFile(targetPath, JSON.stringify(projectPackageJson, null, 2) + "\n");
+    return;
+  }
+
+  let existingPackageJson;
+  try {
+    existingPackageJson = JSON.parse(await fs.readFile(targetPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Existing package.json is not valid JSON: ${targetPath}`, { cause: error });
+  }
+
+  const mergedPackageJson = mergeProjectPackageJson(existingPackageJson, projectPackageJson);
+  await writeTextFile(targetPath, JSON.stringify(mergedPackageJson, null, 2) + "\n");
+}
+
 async function loadRenderState(projectDir, environment) {
   const statePath = path.join(projectDir, "offline", "S3TELocal", "render-state", `${environment}.json`);
   try {
@@ -268,7 +323,7 @@ export async function scaffoldProject(projectDir, options = {}) {
     }
   };
 
-  await writeProjectFile(path.join(projectDir, "package.json"), JSON.stringify(projectPackageJson, null, 2) + "\n", force);
+  await writeProjectPackageJson(path.join(projectDir, "package.json"), projectPackageJson, force);
   await writeProjectFile(path.join(projectDir, "s3te.config.json"), JSON.stringify(config, null, 2) + "\n", force);
   await writeProjectFile(path.join(projectDir, "offline", "schemas", "s3te.config.schema.json"), JSON.stringify(schemaTemplate(), null, 2) + "\n", force);
   await writeProjectFile(path.join(projectDir, "app", "part", "head.part"), "<meta charset='utf-8'>\n<title>My S3TE Site</title>\n", force);