@jskit-ai/jskit-catalog 0.2.8 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-catalog",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Published metadata catalog for JSKIT package metadata.",
   "type": "module",
   "files": [

package/scripts/build-catalog.mjs

@@ -7,7 +7,7 @@ import {
   assertUniquePatternIds,
   discoverPackagePatterns
 } from "./pattern-assets.mjs";
-import { discoverProjectManifests } from "./project-packages.mjs";
+import { discoverProjectManifests } from "./project-manifests.mjs";
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = path.resolve(path.dirname(SCRIPT_PATH), "..");

package/scripts/files.mjs

@@ -0,0 +1,17 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+async function fileExists(absolutePath) {
+  try {
+    await access(absolutePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function toPosixPath(value = "") {
+  return String(value || "").split(path.sep).join("/");
+}
+
+export { fileExists, toPosixPath };

package/scripts/framework-packages.mjs

@@ -1,17 +1,9 @@
-import { access, readdir, readFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { fileExists } from "./files.mjs";
 
 const BUILTIN_SINGLETON_PACKAGE_IDS = Object.freeze(["@jskit-ai/kernel"]);
 
-async function fileExists(filePath) {
-  try {
-    await access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 // The JSKIT framework packages are the direct children of packagesRoot whose
 // package.json declares `jskit` metadata. The catalog builder and the package
 // verifier both read this one set.

package/scripts/i18n.mjs

@@ -1,5 +1,6 @@
 import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { toPosixPath } from "./files.mjs";
 import { resolveInstalledPackage } from "./project-packages.mjs";
 
 // `jskit i18n export|check <locale>`: an app translates JSKIT by supplying
@@ -225,7 +226,7 @@ function nestCatalog(flat, file) {
 }
 
 function relativeFile(projectRoot, file) {
-  return path.relative(path.resolve(projectRoot), file).split(path.sep).join("/");
+  return toPosixPath(path.relative(path.resolve(projectRoot), file));
 }
 
 // --- export ------------------------------------------------------------------------

package/scripts/pattern-assets.mjs

@@ -1,5 +1,6 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { toPosixPath } from "./files.mjs";
 
 const PATTERN_DOCUMENT_NAME = "PATTERN.md";
 const PATTERN_EXAMPLE_DIRECTORY = "example";
@@ -27,10 +28,6 @@ function normalizeText(value = "") {
   return String(value || "").trim();
 }
 
-function normalizePath(value = "") {
-  return String(value || "").split(path.sep).join("/");
-}
-
 function sortedUniqueStrings(values = []) {
   return [...new Set(values.map(normalizeText).filter(Boolean))]
     .sort((left, right) => left.localeCompare(right));
@@ -156,7 +153,7 @@ async function collectFiles(rootDirectory) {
         continue;
       }
       if (entry.isFile()) {
-        files.push(normalizePath(path.relative(rootDirectory, absolutePath)));
+        files.push(toPosixPath(path.relative(rootDirectory, absolutePath)));
       }
     }
   }
@@ -186,7 +183,7 @@ async function discoverPackagePatterns({ packageRoot, packageJson } = {}) {
   for (const entry of patternDirectories) {
     const patternRoot = path.join(patternsRoot, entry.name);
     const documentPath = path.join(patternRoot, PATTERN_DOCUMENT_NAME);
-    const relativeDocumentPath = normalizePath(path.relative(resolvedPackageRoot, documentPath));
+    const relativeDocumentPath = toPosixPath(path.relative(resolvedPackageRoot, documentPath));
     let source;
     try {
       source = await readFile(documentPath, "utf8");
@@ -220,7 +217,7 @@ async function discoverPackagePatterns({ packageRoot, packageJson } = {}) {
       packageId,
       packageVersion,
       documentPath: relativeDocumentPath,
-      examplePath: normalizePath(path.relative(resolvedPackageRoot, exampleRoot)),
+      examplePath: toPosixPath(path.relative(resolvedPackageRoot, exampleRoot)),
       files: Object.freeze(files)
     }));
   }

package/scripts/project-install.mjs

@@ -0,0 +1,156 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileExists } from "./files.mjs";
+
+// Writing an update's manifests and installing it, each undoable: manifest
+// writes are atomic per file and restorable, and `npm install` runs against a
+// moved-aside node_modules that a rollback puts back.
+
+async function writeManifestUpdates(updates = []) {
+  const temporaryPaths = [];
+  const committed = [];
+  try {
+    for (const [index, update] of updates.entries()) {
+      const temporaryPath = `${update.manifest.absolutePath}.jskit-${process.pid}-${index}.tmp`;
+      await writeFile(temporaryPath, update.contents, "utf8");
+      temporaryPaths.push(temporaryPath);
+    }
+    for (const [index, update] of updates.entries()) {
+      await rename(temporaryPaths[index], update.manifest.absolutePath);
+      committed.push(update);
+    }
+  } catch (error) {
+    for (const update of committed) {
+      await writeFile(update.manifest.absolutePath, update.manifest.contents, "utf8");
+    }
+    throw error;
+  } finally {
+    await Promise.all(temporaryPaths.map((temporaryPath) => rm(temporaryPath, { force: true })));
+  }
+}
+
+async function readOptionalFile(absolutePath) {
+  try {
+    return Object.freeze({
+      contents: await readFile(absolutePath, "utf8"),
+      exists: true
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return Object.freeze({
+        contents: "",
+        exists: false
+      });
+    }
+    throw error;
+  }
+}
+
+async function restoreProjectFiles(updates, packageLockPath, packageLockSnapshot) {
+  const rollbackUpdates = updates.map((update) => Object.freeze({
+    contents: update.manifest.contents,
+    manifest: Object.freeze({
+      ...update.manifest,
+      contents: update.contents
+    })
+  }));
+  await writeManifestUpdates(rollbackUpdates);
+  if (packageLockSnapshot.exists) {
+    const temporaryPath = `${packageLockPath}.jskit-${process.pid}-rollback.tmp`;
+    try {
+      await writeFile(temporaryPath, packageLockSnapshot.contents, "utf8");
+      await rename(temporaryPath, packageLockPath);
+    } finally {
+      await rm(temporaryPath, { force: true });
+    }
+    return;
+  }
+  await rm(packageLockPath, { force: true });
+}
+
+async function spawnNpmInstall(projectRoot) {
+  await new Promise((resolve, reject) => {
+    const child = spawn("npm", ["install"], {
+      cwd: projectRoot,
+      env: process.env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("close", (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`npm install failed (code=${code}, signal=${signal || "none"}).`));
+    });
+  });
+}
+
+async function runNpmInstall(projectRoot) {
+  const nodeModulesPath = path.join(projectRoot, "node_modules");
+  const hadNodeModules = await fileExists(nodeModulesPath);
+  const backupRoot = hadNodeModules
+    ? await mkdtemp(path.join(projectRoot, ".jskit-update-"))
+    : null;
+  // Preserve the dependency directory name so development watchers keep excluding it.
+  const backupPath = backupRoot ? path.join(backupRoot, "node_modules") : null;
+  if (hadNodeModules) {
+    try {
+      await rename(nodeModulesPath, backupPath);
+    } catch (error) {
+      await rm(backupRoot, { force: true, recursive: true });
+      throw error;
+    }
+  }
+
+  let settled = false;
+  const transaction = Object.freeze({
+    async commit() {
+      if (settled) {
+        return;
+      }
+      if (backupRoot) {
+        await rm(backupRoot, { force: true, recursive: true });
+      }
+      settled = true;
+    },
+    async rollback() {
+      if (settled) {
+        return;
+      }
+      try {
+        await rm(nodeModulesPath, { force: true, recursive: true });
+        if (backupPath) {
+          await rename(backupPath, nodeModulesPath);
+        }
+      } catch (error) {
+        if (backupPath) {
+          throw new Error(`Could not restore node_modules; backup retained at ${backupPath}.`, { cause: error });
+        }
+        throw error;
+      }
+      if (backupRoot) {
+        await rm(backupRoot, { force: true, recursive: true });
+      }
+      settled = true;
+    }
+  });
+
+  try {
+    await spawnNpmInstall(projectRoot);
+    return transaction;
+  } catch (error) {
+    try {
+      await transaction.rollback();
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        `npm install failed and the previous node_modules directory could not be restored. ${rollbackError.message}`
+      );
+    }
+    throw error;
+  }
+}
+
+export { readOptionalFile, restoreProjectFiles, runNpmInstall, writeManifestUpdates };

package/scripts/project-manifests.mjs

@@ -0,0 +1,133 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileExists, toPosixPath } from "./files.mjs";
+
+// A JSKIT project's manifests: its root package.json and every workspace
+// package.json it declares, read as records that keep their original text.
+const SKIPPED_DIRECTORY_NAMES = new Set([
+  ".git",
+  ".cache",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "tmp"
+]);
+function normalizeWorkspacePatterns(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (value && typeof value === "object" && Array.isArray(value.packages)) {
+    return value.packages;
+  }
+  return [];
+}
+
+function globToRegExp(pattern = "") {
+  const source = toPosixPath(pattern).replace(/^\.\//u, "").replace(/\/$/u, "");
+  let expression = "^";
+
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index];
+    if (character === "*") {
+      if (source[index + 1] === "*") {
+        index += 1;
+        if (source[index + 1] === "/") {
+          index += 1;
+          expression += "(?:.*/)?";
+        } else {
+          expression += ".*";
+        }
+      } else {
+        expression += "[^/]*";
+      }
+      continue;
+    }
+    if (character === "?") {
+      expression += "[^/]";
+      continue;
+    }
+    expression += /[.+^${}()|[\]\\]/u.test(character) ? `\\${character}` : character;
+  }
+
+  return new RegExp(`${expression}$`, "u");
+}
+
+function createWorkspaceMatcher(workspaces) {
+  const patterns = normalizeWorkspacePatterns(workspaces)
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+  const includes = patterns
+    .filter((entry) => !entry.startsWith("!"))
+    .map(globToRegExp);
+  const excludes = patterns
+    .filter((entry) => entry.startsWith("!"))
+    .map((entry) => globToRegExp(entry.slice(1)));
+
+  return function matchesWorkspace(relativeDirectory = "") {
+    const normalized = toPosixPath(relativeDirectory).replace(/^\.\//u, "").replace(/\/$/u, "");
+    return includes.some((matcher) => matcher.test(normalized)) &&
+      !excludes.some((matcher) => matcher.test(normalized));
+  };
+}
+
+async function readJsonRecord(absolutePath) {
+  const contents = await readFile(absolutePath, "utf8");
+  let value;
+  try {
+    value = JSON.parse(contents);
+  } catch (error) {
+    throw new Error(`${absolutePath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${absolutePath} must contain a JSON object.`);
+  }
+  return { absolutePath, contents, value };
+}
+
+async function collectNestedPackageJsonPaths(directory, results = []) {
+  for (const entry of await readdir(directory, { withFileTypes: true }).catch(() => [])) {
+    if (!entry.isDirectory() || SKIPPED_DIRECTORY_NAMES.has(entry.name) || entry.name.startsWith(".")) {
+      continue;
+    }
+    const childDirectory = path.join(directory, entry.name);
+    const manifestPath = path.join(childDirectory, "package.json");
+    if (await fileExists(manifestPath)) {
+      results.push(manifestPath);
+    }
+    await collectNestedPackageJsonPaths(childDirectory, results);
+  }
+  return results;
+}
+
+async function discoverProjectManifests(projectRoot, additionalManifests = []) {
+  const root = path.resolve(projectRoot);
+  const rootManifestPath = path.join(root, "package.json");
+  if (!(await fileExists(rootManifestPath))) {
+    throw new Error(`JSKIT project root has no package.json: ${root}`);
+  }
+  const rootManifest = await readJsonRecord(rootManifestPath);
+  const matchesWorkspace = createWorkspaceMatcher(rootManifest.value.workspaces);
+  const nestedPaths = await collectNestedPackageJsonPaths(root);
+  const workspacePaths = nestedPaths
+    .filter((manifestPath) => matchesWorkspace(path.relative(root, path.dirname(manifestPath))))
+    .sort((left, right) => left.localeCompare(right));
+  const manifests = [rootManifest];
+  for (const manifestPath of new Set([...workspacePaths, ...additionalManifests.map((file) => path.resolve(root, file))])) {
+    if (manifestPath === rootManifestPath) continue;
+    manifests.push(await readJsonRecord(manifestPath));
+  }
+  return Object.freeze(manifests);
+}
+
+function serializePackageJson(value, originalContents = "") {
+  const indentMatch = /\n([ \t]+)"/u.exec(String(originalContents || ""));
+  const indentation = indentMatch?.[1] || "  ";
+  return `${JSON.stringify(value, null, indentation)}\n`;
+}
+
+export { discoverProjectManifests, readJsonRecord, serializePackageJson };