@pipelex/create-method-app 0.4.0

package/lib/templates.mjs

@@ -0,0 +1,60 @@
+/**
+ * The table of templates this initializer serves, read from `templates.json`
+ * at the package's root, and the flags derived from it.
+ *
+ * The table is JSON rather than code so that the family's root can read every
+ * initializer's table whatever its language: a root test fails when a template
+ * of the family is served by no initializer or by more than one, and another
+ * holds `create` to the `make create` contract every template forwards.
+ *
+ * Each create variable is a flag named after it: `NAME` is `--name`,
+ * `AUTHOR_EMAIL` is `--author-email`, and a switch such as `DRY_RUN` is
+ * `--dry-run`, taking no value. Those are also the flags of a template's own
+ * `npm run create`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The initializer package's root: the directory holding `package.json`. */
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export const TABLE_FILE = path.join(PACKAGE_ROOT, "templates.json");
+
+/** `AUTHOR_EMAIL` → `--author-email`. */
+export function flagOf(variable) {
+  return `--${variable.toLowerCase().replaceAll("_", "-")}`;
+}
+
+/** The table, with every flag it implies. */
+export function loadTable(file = TABLE_FILE) {
+  const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+  const switches = new Set(raw.create.switches);
+  /** Every create variable any template takes, by its flag. */
+  const variables = new Map();
+  for (const variable of raw.create.shared) variables.set(flagOf(variable), variable);
+  for (const template of Object.values(raw.templates)) {
+    for (const variable of template.extras) variables.set(flagOf(variable), variable);
+  }
+  return {
+    ecosystem: raw.ecosystem,
+    defaultTemplate: raw.default,
+    templates: raw.templates,
+    required: raw.create.required,
+    shared: raw.create.shared,
+    switches,
+    variables,
+    otherEcosystems: raw.otherEcosystems,
+    /** The variables one template's `make create` takes, in the order they are forwarded. */
+    variablesOf(template) {
+      return [...raw.create.shared, ...raw.templates[template].extras];
+    },
+    /** The command serving another ecosystem's template, or null. The suffix is the family's naming rule. */
+    otherEcosystemOf(template) {
+      const language = /-([a-z0-9]+)$/.exec(template)?.[1];
+      if (language === undefined || language === raw.ecosystem) return null;
+      return Object.hasOwn(raw.otherEcosystems, language) ? raw.otherEcosystems[language] : null;
+    },
+  };
+}

package/lib/verdict.mjs

@@ -0,0 +1,46 @@
+/**
+ * The verdicts. A run ends with one line whose first word is stable —
+ * `created`, `copied`, `refused: <why>` or `failed: <what>` — and that line is
+ * the last one printed, so a caller reads the verdict from the last line. The
+ * exit code is presentation: 0 for `created` and `copied`, 1 otherwise.
+ *
+ *   created <dir>            the copy, the git outcome, and a green make create
+ *   copied <dir>             --no-create or --dry-run: the copy and the git outcome only
+ *   refused: <why>           the preflight stopped, and nothing was written
+ *   failed: write            the copy failed or was interrupted, and what it created was removed
+ *   failed: commit           git refused the pristine commit; the copy stands
+ *   failed: create           make create did not succeed; the copy and the commit stand, and its
+ *                            own message says what to run next
+ */
+
+export const EXIT_OK = 0;
+export const EXIT_STOPPED = 1;
+
+/** A run's end, thrown from wherever it is decided and printed once by the orchestration. */
+export class Verdict extends Error {
+  constructor(word, detail, exitCode) {
+    super(`${word} — ${detail}`);
+    this.name = "Verdict";
+    this.word = word;
+    this.detail = detail;
+    this.exitCode = exitCode;
+  }
+
+  static refused(why, detail) {
+    return new Verdict(`refused: ${why}`, detail, EXIT_STOPPED);
+  }
+
+  static failed(what, detail) {
+    return new Verdict(`failed: ${what}`, detail, EXIT_STOPPED);
+  }
+
+  /** The line printed last. */
+  get line() {
+    return this.message;
+  }
+}
+
+/** Quote a word for a line a person may paste into a shell. */
+export function shellQuote(word) {
+  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}

package/lib/write.mjs

@@ -0,0 +1,134 @@
+/**
+ * The write, which removes exactly what it created when it cannot finish.
+ *
+ * Every directory is made without `recursive` and every file is opened with
+ * `wx`, so something that appears between the reading of the destination and
+ * the write makes the write fail rather than be written over or into. Each
+ * directory and file is recorded the moment it exists, and on a failure or an
+ * interruption the files go first, then the directories, deepest first and
+ * only when empty, the destination itself among them only when this write
+ * made it. Nothing the write did not create is ever removed.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { MODES } from "./pack.mjs";
+import { readDestination } from "./destination.mjs";
+
+/** The write stopped because the run was interrupted. */
+export class Interrupted extends Error {
+  constructor(signal) {
+    super(`${signal ?? "a signal"} interrupted the write`);
+    this.name = "Interrupted";
+  }
+}
+
+/** The destination changed between the preflight's reading and the write. */
+export class DestinationChanged extends Error {
+  constructor(found) {
+    super("the destination changed after it was checked");
+    this.name = "DestinationChanged";
+    this.found = found;
+  }
+}
+
+/** What the write created, in the order it created it. */
+export class Created {
+  dirs = [];
+  files = [];
+}
+
+/** Make `dest` and each missing ancestor, recording each one made. */
+async function makeDest(dest, created) {
+  const missing = [];
+  for (let at = dest; ; at = path.dirname(at)) {
+    try {
+      await fs.stat(at);
+      break;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    missing.push(at);
+    if (path.dirname(at) === at) break;
+  }
+  for (const dir of missing.reverse()) {
+    await fs.mkdir(dir);
+    created.dirs.push(dir);
+  }
+}
+
+/**
+ * Make a directory under the destination with each parent it needs there,
+ * never reusing one this write did not make: a directory that appeared after
+ * the destination was read fails the `mkdir`.
+ */
+async function makeUnder(dir, dest, created, made) {
+  if (dir === dest || made.has(dir)) return;
+  await makeUnder(path.dirname(dir), dest, created, made);
+  await fs.mkdir(dir);
+  created.dirs.push(dir);
+  made.add(dir);
+}
+
+/**
+ * Remove what was created: files, then directories deepest first, each only
+ * while empty. Returns the paths it could not remove, which a report names.
+ */
+export async function removeCreated(created) {
+  const left = [];
+  for (const file of [...created.files].reverse()) {
+    try {
+      await fs.unlink(file);
+    } catch (error) {
+      if (error.code !== "ENOENT") left.push(file);
+    }
+  }
+  const depth = (dir) => dir.split(path.sep).length;
+  for (const dir of [...created.dirs].sort((a, b) => depth(b) - depth(a))) {
+    try {
+      await fs.rmdir(dir);
+    } catch (error) {
+      if (error.code !== "ENOENT") left.push(dir);
+    }
+  }
+  return left;
+}
+
+/**
+ * Write `files` (`[{ path, mode, data }]`, paths relative) under `dest`. The
+ * destination is made when missing, then read again; `signal` is checked
+ * before each file. On any failure what was created is removed, and the error
+ * is rethrown with `created` and `left` attached.
+ */
+export async function writeTree(dest, files, { signal, onFile } = {}) {
+  const created = new Created();
+  const made = new Set();
+  try {
+    await makeDest(dest, created);
+    const found = readDestination(dest);
+    if (found.kind !== "missing" && found.kind !== "empty" && found.kind !== "lone-git") {
+      throw new DestinationChanged(found);
+    }
+
+    for (const [index, file] of files.entries()) {
+      if (signal?.aborted) throw new Interrupted(signal.reason);
+      const full = path.join(dest, ...file.path.split("/"));
+      await makeUnder(path.dirname(full), dest, created, made);
+      const handle = await fs.open(full, "wx", MODES[file.mode]);
+      created.files.push(full);
+      try {
+        await handle.writeFile(file.data);
+      } finally {
+        await handle.close();
+      }
+      await onFile?.(index, full);
+    }
+    if (signal?.aborted) throw new Interrupted(signal.reason);
+    return created;
+  } catch (error) {
+    error.created = created;
+    error.left = await removeCreated(created);
+    throw error;
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@pipelex/create-method-app",
+  "version": "0.4.0",
+  "description": "Start a Pipelex method app: npm create @pipelex/method-app@latest my-app -- --method <bundle | mt_… | address>",
+  "keywords": [
+    "pipelex",
+    "mthds",
+    "create",
+    "template"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-method-app": "bin/create-method-app.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "templates.json"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pipelex/pipelex-method-apps.git",
+    "directory": "initializers/js"
+  },
+  "homepage": "https://github.com/Pipelex/pipelex-method-apps/tree/main/initializers/js#readme",
+  "bugs": "https://github.com/Pipelex/pipelex-method-apps/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "pack-templates": "node scripts/pack-templates.mjs",
+    "prepack": "node scripts/pack-templates.mjs --publish",
+    "test": "node --test \"test/*.test.mjs\""
+  }
+}

package/templates.json

@@ -0,0 +1,30 @@
+{
+  "ecosystem": "js",
+  "default": "webapp-js",
+  "templates": {
+    "webapp-js": {
+      "extras": ["METHOD_NAME", "LABEL"]
+    }
+  },
+  "create": {
+    "required": "METHOD",
+    "shared": [
+      "METHOD",
+      "NAME",
+      "TITLE",
+      "DESCRIPTION",
+      "PIPE",
+      "AUTHOR_NAME",
+      "AUTHOR_EMAIL",
+      "REPO_URL",
+      "LICENSE",
+      "LICENSE_HOLDER",
+      "LICENSE_YEAR",
+      "DRY_RUN"
+    ],
+    "switches": ["DRY_RUN"]
+  },
+  "otherEcosystems": {
+    "python": "uvx create-pipelex-method-app"
+  }
+}