@pipelex/create-method-app 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evotis S.A.S.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @pipelex/create-method-app
+
+Start an app that runs an [MTHDS](https://mthds.ai) method through the [Pipelex](https://pipelex.com) API, with the method you already have:
+
+```bash
+export PIPELEX_API_KEY=…                               # from app.pipelex.com
+export PIPELEX_BASE_URL=https://api-dev.pipelex.com    # for now, see the template's README
+npm create @pipelex/method-app@latest my-app -- --method ./receipt_review.mthds
+make -C my-app serve
+```
+
+The first command writes the [`webapp-js`](https://github.com/Pipelex/pipelex-method-apps/tree/main/webapp-js) template of [`pipelex-method-apps`](https://github.com/Pipelex/pipelex-method-apps) into `my-app/`, commits it as it came, and runs the copy's own `make create`, which scaffolds the method, names the project after it and runs `make all`. The second starts the dev server in the background, proves that the page answers, and prints its URL; `make stop` stops it. `make dev` runs the same server in the foreground instead.
+
+`--method` takes a `.mthds` file or a directory of them, a method id from your organization's catalog (`mt_…`), or a published package address (`github.com/Pipelex/methods/text_stats@v0.1.1`). A path is read from where you typed the command.
+
+## What it needs
+
+- **Node.js** at or above the template's floor (22.12 for `webapp-js`), `make`, and `git` unless you pass `--no-git`.
+- **`PIPELEX_API_KEY`** in the environment, since a fresh copy has no `.env.local` for `make create` to read it from. `make create` copies it into the project's `.env.local`. The initializer only checks that it is set, and never prints it.
+- **A directory that is missing, empty, or holds only `.git`.** Anything else, `.DS_Store` included, is refused, and nothing is written.
+
+The package has no dependency. It carries the template inside it, packed from the family's repository at the commit it was published from, so `@X.Y.Z` writes exactly the X.Y.Z template and nothing is fetched from GitHub.
+
+## Options
+
+| Option                                                                                             | What it does                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--method <m>`                                                                                     | The method the app runs. Required unless `--no-create`.                                                                                                  |
+| `--name`, `--title`, `--description`                                                               | The project's package name, title and description, which `make create` otherwise derives from the method.                                                |
+| `--pipe`, `--method-name`, `--label`                                                               | The pipe to run, the method's directory name and its tab label, when the method does not settle them.                                                    |
+| `--author-name`, `--author-email`, `--repo-url`, `--license`, `--license-holder`, `--license-year` | What the project says about who made it. Nothing is invented.                                                                                            |
+| `--dry-run`                                                                                        | `make create` plans and prints the identity without changing a file. The copy and its commit stand, and the verdict names the real `make create` to run. |
+| `--no-create`                                                                                      | Write the template and commit it, then stop. The verdict names the `make create` to run, after writing `.env.local` yourself, for instance.              |
+| `--no-git`                                                                                         | Make no repository and no commit.                                                                                                                        |
+| `--quiet`                                                                                          | Write `make create`'s output to a log and print its path, so the summary stays in view.                                                                  |
+| `--template <name>`                                                                                | The template to write. `webapp-js` is the default and the only one.                                                                                      |
+
+Each create option is named after the `make create` variable it sets (`--author-email` is `AUTHOR_EMAIL`), and reaches `make create` as one argument, so no value needs quoting beyond what your shell needs. A blank value is not passed on. Nothing is ever asked: a missing value is a refusal naming the option.
+
+## Git
+
+The initializer reads git before it writes anything:
+
+| The destination                                                                                  | What happens                                                                                                                     |
+| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Inside no repository                                                                             | A new repository on `main`, then the pristine commit                                                                             |
+| A repository with no commit yet (a `git init` by hand, or a clone of an empty GitHub repository) | The pristine commit, as its first                                                                                                |
+| A repository with no commit whose index already holds a file, added and then deleted             | Refused: the commit would record that file beside the template                                                                   |
+| A repository with commits, holding only `.git`                                                   | Refused: every tracked file would show as deleted, and the commit would record that                                              |
+| Inside another repository's work tree                                                            | No repository and no commit: the project is new files in that repository. `--no-create` lets you commit the template there first |
+| Inside a checkout of `pipelex-method-apps` or of a starter                                       | Refused, `--no-git` included whenever git is on the PATH                                                                         |
+
+A commit needs a git identity, and a missing one is refused before anything is written. When git shows none outside a repository, the initializer asks again inside a throwaway repository at the destination, which it removes before going on, so an identity given only by an `includeIf "gitdir:…"` section is found.
+
+The pristine commit reads `Start from Pipelex/pipelex-method-apps/webapp-js <version> (<sha>)`, so `make create`'s changes are a diff you can read before committing them. `make create` itself commits nothing.
+
+## What it prints
+
+A run ends with one verdict line, the last line of its output, whose first word is stable:
+
+| Verdict                                                                                                                                             | Meaning                                                                                                                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `created <dir>; next: cd <dir> && make serve`                                                                                                       | The copy, the git outcome, and a green `make create`                                                                                                                                                              |
+| `copied <dir>; next: …`                                                                                                                             | With `--no-create` or `--dry-run`: the copy and the git outcome, and the `make create` to run next                                                                                                                |
+| `refused: not-empty`                                                                                                                                | The destination holds something other than a lone `.git`; nothing was written                                                                                                                                     |
+| `refused: unusable-destination`                                                                                                                     | The destination cannot be read: a file stands where a directory of its path should be, or a directory on it cannot be read; nothing was written                                                                   |
+| `refused: repository-has-history`, `refused: repository-has-staged-files`, `refused: inside-template-checkout`                                      | The git reading above; nothing was written                                                                                                                                                                        |
+| `refused: no-method`, `no-key`, `missing-tool`, `node-too-old`, `no-git-identity`, `unknown-option`, `unknown-template`, `other-ecosystem`, `usage` | The preflight; nothing was written, and the line names the fix                                                                                                                                                    |
+| `failed: write`                                                                                                                                     | The copy failed or was interrupted, and everything the initializer had created was removed; nothing else was touched                                                                                              |
+| `failed: commit`                                                                                                                                    | Git refused the pristine commit, for instance through a global hook; the copy stands, and the line says how to commit it and what to run next                                                                     |
+| `failed: create`                                                                                                                                    | `make create` did not succeed; the copy and its commit stand, and `make create`'s own message says what to run next: a refusal before it wrote anything can be fixed and run again, and a failure after it cannot |
+
+Before the verdict come the warnings `make create` printed, each once, and the git outcome. The exit code is 0 for `created` and `copied` and 1 otherwise, but the verdict is the line to read.
+
+A Python template gets its own initializer, run with `uvx create-pipelex-method-app`, and this one refuses it with `refused: other-ecosystem`.
+
+## License
+
+[MIT](LICENSE). The template it writes carries its own license, MIT, which the project can change with `--license`.

package/bin/create-method-app.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * `npm create @pipelex/method-app@latest <dir> -- --method …` runs this. The
+ * behavior lives in `lib/main.mjs`; this file catches SIGINT and SIGTERM, so an
+ * interruption ends in a verdict rather than a dead process, and sets the exit
+ * code.
+ */
+import process from "node:process";
+
+import { run } from "../lib/main.mjs";
+
+const controller = new AbortController();
+const interrupt = (signal) => controller.abort(signal);
+process.on("SIGINT", interrupt);
+process.on("SIGTERM", interrupt);
+
+process.exitCode = await run(process.argv.slice(2), { signal: controller.signal });

package/lib/args.mjs

@@ -0,0 +1,116 @@
+/**
+ * The command line:
+ *
+ *   create-method-app <dir> --method <bundle | mt_… | address> [create options]
+ *                     [--template <name>] [--no-create] [--no-git] [--quiet]
+ *
+ * Each create option is a flag named after its make variable, taking its value
+ * as the next word or after `=`; a switch such as `--dry-run` takes none. A
+ * blank value is not given, as the Makefile's `given` ignores one. Nothing is
+ * ever asked: a missing value is a refusal naming the flag.
+ */
+
+import { Verdict } from "./verdict.mjs";
+
+export const USAGE =
+  "usage: npm create @pipelex/method-app@latest <dir> -- --method <path/to/bundle | mt_… | github.com/owner/repo[/package][@tag]> " +
+  "[--name <package>] [--title <title>] [--description <text>] [--pipe <pipe_code>] " +
+  "[--author-name <name>] [--author-email <email>] [--repo-url <url>] [--license <mit|proprietary|spdx>] " +
+  "[--license-holder <holder>] [--license-year <year>] [--dry-run] [--method-name <dir-name>] [--label <label>] " +
+  "[--template webapp-js] [--no-create] [--no-git] [--quiet]";
+
+/** Appended to a refusal of the command line, which stays one line. */
+export const HELP_HINT = "(--help lists the options)";
+
+const OWN_SWITCHES = { "--no-create": "noCreate", "--no-git": "noGit", "--quiet": "quiet" };
+
+/**
+ * Parse `argv` against the table. Returns
+ * `{ help, version, dir, template, values, given, noCreate, noGit, quiet }`,
+ * `values` holding each create variable given, by name, and `given` the flag
+ * each came from; throws a `Verdict` refusal otherwise.
+ */
+export function parseArgs(argv, table) {
+  const parsed = {
+    help: false,
+    version: false,
+    dir: undefined,
+    template: undefined,
+    values: {},
+    given: {},
+    noCreate: false,
+    noGit: false,
+    quiet: false,
+  };
+  const seen = new Set();
+  const once = (flag) => {
+    if (seen.has(flag)) throw Verdict.refused("usage", `${flag} is given twice. ${HELP_HINT}`);
+    seen.add(flag);
+  };
+
+  let options = true;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (options && arg === "--") {
+      options = false;
+      continue;
+    }
+    if (!options || !arg.startsWith("-") || arg === "-") {
+      if (parsed.dir !== undefined) {
+        throw Verdict.refused(
+          "usage",
+          `${JSON.stringify(arg)} is a second directory; the template is written into one. ${HELP_HINT}`,
+        );
+      }
+      parsed.dir = arg;
+      continue;
+    }
+
+    const eq = arg.indexOf("=");
+    const flag = eq > 0 ? arg.slice(0, eq) : arg;
+    const inline = eq > 0 ? arg.slice(eq + 1) : undefined;
+    const noValue = () => {
+      if (inline !== undefined)
+        throw Verdict.refused("usage", `${flag} takes no value. ${HELP_HINT}`);
+    };
+    const value = () => {
+      if (inline !== undefined) return inline;
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        throw Verdict.refused("usage", `${flag} needs a value. ${HELP_HINT}`);
+      }
+      i += 1;
+      return next;
+    };
+
+    if (flag === "--help" || flag === "-h") {
+      parsed.help = true;
+    } else if (flag === "--version") {
+      parsed.version = true;
+    } else if (flag in OWN_SWITCHES) {
+      noValue();
+      once(flag);
+      parsed[OWN_SWITCHES[flag]] = true;
+    } else if (flag === "--template") {
+      once(flag);
+      parsed.template = value().trim() || undefined;
+    } else if (table.variables.has(flag)) {
+      once(flag);
+      const variable = table.variables.get(flag);
+      if (table.switches.has(variable)) {
+        noValue();
+        parsed.values[variable] = true;
+      } else {
+        const given = value();
+        if (given.trim() !== "") parsed.values[variable] = given;
+      }
+      parsed.given[variable] = flag;
+    } else {
+      throw Verdict.refused(
+        "unknown-option",
+        `${flag} is not an option of this initializer. ${HELP_HINT}`,
+      );
+    }
+  }
+  return parsed;
+}

package/lib/destination.mjs

@@ -0,0 +1,53 @@
+/**
+ * The destination rule, which is the scaffold skill's: a directory that is
+ * missing, empty, or holds only `.git` is accepted, and anything else is
+ * refused. The lone `.git` is a ruling about `.git` and nothing else, so
+ * `.DS_Store`, an editor's settings and every other entry refuse, because
+ * judging which of a user's files matter is exactly what the rule forbids.
+ *
+ * The destination is resolved to an absolute path first, so `.` works, and it
+ * is read twice: in the preflight, and again immediately before the first
+ * write.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * What stands at the destination: `missing`, `empty`, `lone-git`, a
+ * `not-empty` directory with some of what it holds, or a `not-directory`.
+ */
+export function readDestination(dir) {
+  let stat;
+  try {
+    stat = fs.statSync(dir);
+  } catch (error) {
+    if (error.code === "ENOENT") return { kind: "missing" };
+    throw error;
+  }
+  if (!stat.isDirectory()) return { kind: "not-directory" };
+  const entries = fs.readdirSync(dir).sort();
+  if (entries.length === 0) return { kind: "empty" };
+  if (entries.length === 1 && entries[0] === ".git") return { kind: "lone-git" };
+  return { kind: "not-empty", entries: entries.filter((entry) => entry !== ".git") };
+}
+
+/** The refusal's explanation of what stands there, or null when the rule accepts it. */
+export function destinationProblem(dir, found) {
+  if (found.kind === "not-directory") return `${dir} exists and is not a directory`;
+  if (found.kind !== "not-empty") return null;
+  const shown = found.entries.slice(0, 3).join(", ");
+  const more = found.entries.length > 3 ? ` and ${found.entries.length - 3} more` : "";
+  return `${dir} already holds ${shown}${more}; the template is written only into a directory that is missing, empty or holds nothing but .git`;
+}
+
+/** The nearest ancestor of `dir`, itself included, that exists. */
+export function nearestExisting(dir) {
+  let at = dir;
+  while (!fs.existsSync(at)) {
+    const parent = path.dirname(at);
+    if (parent === at) return at;
+    at = parent;
+  }
+  return at;
+}

package/lib/git.mjs

@@ -0,0 +1,205 @@
+/**
+ * Git, read before anything is written, and one outcome for each case:
+ *
+ *   inside no work tree                    → a new repository on main, then the pristine commit
+ *   the root of a repository with no commit → the pristine commit, its first
+ *     … whose index already holds an entry → refused: repository-has-staged-files
+ *   the root of a repository with history  → refused: repository-has-history
+ *   inside another repository's work tree  → no repository and no commit
+ *   inside a checkout of a template        → refused: inside-template-checkout
+ *
+ * A directory holding only `.git` whose repository has commits is one whose
+ * working tree shows every tracked file deleted, and landing the template on it
+ * would fold that deletion into the commit. One with no commit can still hold
+ * staged entries, a file added and then deleted from the directory, and the
+ * pristine commit would record them beside the template. A repository planted
+ * inside another one's work tree makes the enclosing one fail `git add -A`
+ * until the nested one has a commit, and then see an embedded repository, so
+ * the project becomes new files in the enclosing repository instead, as
+ * `create-next-app` does.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The repositories whose checkouts are templates, read from `origin`: the
+ * family's own, and the starters. Running the initializer inside one would
+ * make a project of a template's checkout.
+ */
+export const TEMPLATE_ORIGINS =
+  /[/:](pipelex\/(pipelex-method-apps|pipelex-starter-js|pipelex-starter-python)|mthds-ai\/mthds-starter-js)(\.git)?\/?$/i;
+
+/**
+ * Variables that point git at a repository other than the one it would find
+ * from the directory it runs in. A hook or a wrapper can leave them set, and
+ * the reading must be about the destination.
+ */
+const REDIRECTING = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_COMMON_DIR",
+  "GIT_NAMESPACE",
+  "GIT_PREFIX",
+];
+
+export function gitEnv(env) {
+  const clean = { ...env };
+  for (const name of REDIRECTING) delete clean[name];
+  return clean;
+}
+
+/** Run git, returning its status and trimmed output. */
+export function git(args, { cwd, env }) {
+  const result = spawnSync("git", args, { cwd, env: gitEnv(env), encoding: "utf8" });
+  if (result.error) return { status: null, stdout: "", stderr: result.error.message };
+  return { status: result.status, stdout: result.stdout.trim(), stderr: result.stderr.trim() };
+}
+
+/**
+ * Read git at the destination. `from` is the destination when it exists, or
+ * its nearest existing ancestor. Returns one of:
+ *
+ *   { kind: "outside" }
+ *   { kind: "template-checkout", origin }
+ *   { kind: "root", history: boolean, staged: string[] }   `staged` is read only when there is no history
+ *   { kind: "inside", toplevel }
+ *   { kind: "unreadable-git" }   the destination holds a `.git` git does not read as its repository
+ */
+export function readGit({ dest, from, destExists, destHasGit, env }) {
+  const top = git(["rev-parse", "--show-toplevel"], { cwd: from, env });
+  if (top.status !== 0) return destHasGit ? { kind: "unreadable-git" } : { kind: "outside" };
+
+  const origin = templateOrigin({ from, env });
+  if (origin !== null) return { kind: "template-checkout", origin };
+
+  // `--show-prefix` prints nothing at a repository's root, which needs no path
+  // comparison and so survives symlinks and letter case.
+  if (destExists) {
+    const prefix = git(["rev-parse", "--show-prefix"], { cwd: dest, env });
+    if (prefix.status === 0 && prefix.stdout === "") {
+      const head = git(["rev-parse", "-q", "--verify", "HEAD"], { cwd: dest, env });
+      if (head.status === 0) return { kind: "root", history: true, staged: [] };
+      const index = git(["ls-files", "-z"], { cwd: dest, env });
+      return { kind: "root", history: false, staged: index.stdout.split("\0").filter(Boolean) };
+    }
+    if (destHasGit) return { kind: "unreadable-git" };
+  }
+  return { kind: "inside", toplevel: top.stdout };
+}
+
+/** The `origin` of the repository `from` stands in when it is a template's own, or null. */
+export function templateOrigin({ from, env }) {
+  const origin = git(["remote", "get-url", "origin"], { cwd: from, env });
+  return origin.status === 0 && TEMPLATE_ORIGINS.test(origin.stdout) ? origin.stdout : null;
+}
+
+/** Whether git can name an author and a committer, as a commit needs. */
+export function hasIdentity({ cwd, env }) {
+  return (
+    git(["var", "GIT_AUTHOR_IDENT"], { cwd, env }).status === 0 &&
+    git(["var", "GIT_COMMITTER_IDENT"], { cwd, env }).status === 0
+  );
+}
+
+/**
+ * Whether git can name an author and a committer for the commit in the
+ * repository about to be made at `dest`, which `from`, the destination or its
+ * nearest existing ancestor, stands outside of. Outside a repository git reads
+ * no `includeIf "gitdir:…"` section, so an identity given only to the
+ * repositories under a directory is invisible from `from`. When that reading
+ * finds none, the question is asked again inside a throwaway repository made
+ * at `dest`, and what the probe made is removed before the answer is returned.
+ *
+ * It removes only what it made, as the write does. Each missing directory and
+ * the `.git` are made without `recursive`, so a path that stands there already,
+ * a dangling symlink the reading took for missing, or one another process
+ * creates meanwhile fails the probe instead of being taken over and removed.
+ * The directories go deepest first and only while empty, so what another
+ * process writes into one meanwhile stays. A probe that cannot be made
+ * answers no.
+ */
+export function hasIdentityForInit({ dest, from, env }) {
+  if (hasIdentity({ cwd: from, env })) return true;
+  const missing = [];
+  for (let at = dest; at !== from && path.dirname(at) !== at; at = path.dirname(at)) {
+    missing.unshift(at);
+  }
+  const probe = path.join(dest, ".git");
+  const made = [];
+  let probeMade = false;
+  try {
+    for (const dir of missing) {
+      fs.mkdirSync(dir);
+      made.push(dir);
+    }
+    fs.mkdirSync(probe);
+    probeMade = true;
+    return git(["init", "-q"], { cwd: dest, env }).status === 0 && hasIdentity({ cwd: dest, env });
+  } catch {
+    return false;
+  } finally {
+    if (probeMade) fs.rmSync(probe, { recursive: true, force: true });
+    for (const dir of made.reverse()) {
+      try {
+        fs.rmdirSync(dir);
+      } catch {
+        // Not empty: another process wrote into it, and what it wrote stays.
+      }
+    }
+  }
+}
+
+/** The pristine commit's message, in the scaffold skill's format. */
+export function pristineMessage({ template, version, source }) {
+  return `Start from Pipelex/pipelex-method-apps/${template} ${version} (${source})`;
+}
+
+/**
+ * Initialize when asked, then make the pristine commit of exactly `paths`, the
+ * files the write created. Returns the commit's SHA, or throws with git's own
+ * message. Git's output is not shown on success.
+ *
+ * The repository is born on `main` through `symbolic-ref` rather than
+ * `init -b`, which git before 2.28 does not know. The paths are added with
+ * `--force` and read literally: a user's `core.excludesFile` or the
+ * repository's `info/exclude` must not silently drop a file of the template
+ * from a commit that claims to hold it as it came, and the template ignores
+ * none of its own files.
+ */
+export function commitPristine({ dest, init, paths, message, env }) {
+  const steps = [
+    ...(init
+      ? [
+          ["init", ["init", "-q"]],
+          ["symbolic-ref", ["symbolic-ref", "HEAD", "refs/heads/main"]],
+        ]
+      : []),
+    ["add", ["--literal-pathspecs", "add", "--force", "--", ...paths]],
+    ["commit", ["commit", "-q", "-m", message]],
+  ];
+  for (const [name, args] of steps) {
+    const result = git(args, { cwd: dest, env });
+    if (result.status !== 0) {
+      const said = [result.stderr, result.stdout].filter(Boolean).join("\n");
+      throw new Error(`git ${name} failed${said ? `:\n${said}` : ""}`);
+    }
+  }
+  return git(["rev-parse", "HEAD"], { cwd: dest, env }).stdout;
+}
+
+/**
+ * The commands a person runs to make the pristine commit by hand, once the
+ * copy stands, joined with `&&` for a shell. `quote` quotes one word.
+ */
+export function pristineByHand({ dest, init, message, quote }) {
+  const at = `git -C ${quote(dest)}`;
+  return [
+    ...(init ? [`${at} init -q`, `${at} symbolic-ref HEAD refs/heads/main`] : []),
+    `${at} add --force -A`,
+    `${at} commit -m ${quote(message)}`,
+  ].join(" && ");
+}