@earendil-works/chord 1.5.0 → 1.5.1

package/dist/node/plugins/index.d.ts

@@ -0,0 +1,11 @@
+export type { BaseInputs } from "./base-inputs.ts";
+export { type AppApi, type BuildInput, type BuildOptions, type BuiltFacet, buildFacet } from "./build.ts";
+export { type Discovery, type DiscoveryOptions, type DiscoveryProblem, discoverPlugins, type Plugin, type PluginRoot, } from "./discover.ts";
+export { type BuiltScript, type EvaluateOptions, evaluateFacet, type HostPackages, pluginFile } from "./evaluate.ts";
+export { type InstallOptions, type InstallPluginOptions, installDependencies, installPlugin, type PluginSource, } from "./install.ts";
+export { type Built, createPlugins, type KindDefinition, type Plugins, type PluginsError, type PluginsOptions, type RolloutHost, type RolloutResult, type RolloutStep, } from "./plugins.ts";
+export { createPluginRuntime, PluginError, type PluginRuntime, type PluginScript, type RuntimeLoad, } from "./runtime.ts";
+export { mapStack } from "./stack.ts";
+export { type TestedPlugin, type TestPluginOptions, testPlugin } from "./testing.ts";
+export type { PluginsState } from "./watcher.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/node/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/plugins/index.ts"],"names":[],"mappings":"AAKA,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1G,OAAO,EACN,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,MAAM,EACX,KAAK,UAAU,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrH,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,mBAAmB,EACnB,aAAa,EACb,KAAK,YAAY,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,KAAK,KAAK,EACV,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,mBAAmB,EACnB,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,WAAW,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACrF,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/node/plugins/index.js

@@ -0,0 +1,13 @@
+// Chord v2's plugins component (`@earendil-works/chord/plugins`; slices 7c, 12): plugin directories and single-file
+// plugins found, built into scripts checked against the app's API, evaluated, loaded and reloaded per plugin, watched,
+// rolled out and installed, and a plugin tested alone. Node-only (`fs`, esbuild, `vm`); esbuild is an optional peer
+// dependency, imported only here.
+export { buildFacet } from "./build.js";
+export { discoverPlugins, } from "./discover.js";
+export { evaluateFacet, pluginFile } from "./evaluate.js";
+export { installDependencies, installPlugin, } from "./install.js";
+export { createPlugins, } from "./plugins.js";
+export { createPluginRuntime, PluginError, } from "./runtime.js";
+export { mapStack } from "./stack.js";
+export { testPlugin } from "./testing.js";
+//# sourceMappingURL=index.js.map

package/dist/node/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/node/plugins/index.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,uHAAuH;AACvH,oHAAoH;AACpH,kCAAkC;AAGlC,OAAO,EAAoE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1G,OAAO,EAIN,eAAe,GAGf,MAAM,eAAe,CAAC;AACvB,OAAO,EAA0C,aAAa,EAAqB,UAAU,EAAE,MAAM,eAAe,CAAC;AACrH,OAAO,EAGN,mBAAmB,EACnB,aAAa,GAEb,MAAM,cAAc,CAAC;AACtB,OAAO,EAEN,aAAa,GAQb,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,mBAAmB,EACnB,WAAW,GAIX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAA6C,UAAU,EAAE,MAAM,cAAc,CAAC","sourcesContent":["// Chord v2's plugins component (`@earendil-works/chord/plugins`; slices 7c, 12): plugin directories and single-file\n// plugins found, built into scripts checked against the app's API, evaluated, loaded and reloaded per plugin, watched,\n// rolled out and installed, and a plugin tested alone. Node-only (`fs`, esbuild, `vm`); esbuild is an optional peer\n// dependency, imported only here.\n\nexport type { BaseInputs } from \"./base-inputs.ts\";\nexport { type AppApi, type BuildInput, type BuildOptions, type BuiltFacet, buildFacet } from \"./build.ts\";\nexport {\n\ttype Discovery,\n\ttype DiscoveryOptions,\n\ttype DiscoveryProblem,\n\tdiscoverPlugins,\n\ttype Plugin,\n\ttype PluginRoot,\n} from \"./discover.ts\";\nexport { type BuiltScript, type EvaluateOptions, evaluateFacet, type HostPackages, pluginFile } from \"./evaluate.ts\";\nexport {\n\ttype InstallOptions,\n\ttype InstallPluginOptions,\n\tinstallDependencies,\n\tinstallPlugin,\n\ttype PluginSource,\n} from \"./install.ts\";\nexport {\n\ttype Built,\n\tcreatePlugins,\n\ttype KindDefinition,\n\ttype Plugins,\n\ttype PluginsError,\n\ttype PluginsOptions,\n\ttype RolloutHost,\n\ttype RolloutResult,\n\ttype RolloutStep,\n} from \"./plugins.ts\";\nexport {\n\tcreatePluginRuntime,\n\tPluginError,\n\ttype PluginRuntime,\n\ttype PluginScript,\n\ttype RuntimeLoad,\n} from \"./runtime.ts\";\nexport { mapStack } from \"./stack.ts\";\nexport { type TestedPlugin, type TestPluginOptions, testPlugin } from \"./testing.ts\";\nexport type { PluginsState } from \"./watcher.ts\";\n"]}

package/dist/node/plugins/install.d.ts

@@ -0,0 +1,38 @@
+import type { Context } from "../../context/index.ts";
+import { type Plugin, type PluginRoot } from "./discover.ts";
+/** What installs take: the npm command (`["npm"]` by default, e.g. `["pnpm"]`); git and tar are run as `git`, `tar`. */
+export type InstallOptions = {
+    readonly npmCommand?: readonly string[];
+};
+/** What `installPlugin` takes besides the source and the root. */
+export type InstallPluginOptions = InstallOptions & {
+    /** The app's facet kinds: a package whose top has a facet file is one plugin (`[]` by default). */
+    readonly kinds?: readonly string[];
+    /** Every root of the app: a new plugin named like one in any of them is refused (`[root]` by default). */
+    readonly roots?: readonly PluginRoot[];
+};
+/** Where `installPlugin` installs from: a git repository at a ref (a branch, tag or commit), or an npm package. */
+export type PluginSource = {
+    readonly git: string;
+    readonly ref: string;
+} | {
+    readonly npm: string;
+    readonly version: string;
+};
+/**
+ * Installs `plugin`'s `dependencies` into its own `node_modules` (`npm install --omit=dev --legacy-peer-deps
+ * --ignore-scripts --no-audit --no-fund` in its real directory; git dependencies with a ref are npm's). Rejects with
+ * the command's output when it fails, and when `context` aborts (the command is killed). A single-file plugin has
+ * nothing to install.
+ */
+export declare function installDependencies(plugin: Plugin, context: Context, options?: InstallOptions): Promise<void>;
+/**
+ * Installs new plugins into `root` from `source`, then their dependencies: from git, a shallow clone of the ref into
+ * `<root>/<repository name>`; from npm, the packed package extracted into `<root>/<name>`. The package's plugins are
+ * its `chord.plugins` folders, else by convention (discovery's rules). Returns their names. Refused: a source option
+ * (`-…`), an invalid name, an existing directory (no updating in place: install another ref, or delete and install), a
+ * package discovery reports a problem in or finds no plugin in, a plugin name another plugin of `options.roots` has.
+ * Only what this install created is removed on failure.
+ */
+export declare function installPlugin(source: PluginSource, root: string, context: Context, options?: InstallPluginOptions): Promise<readonly string[]>;
+//# sourceMappingURL=install.d.ts.map

package/dist/node/plugins/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/node/plugins/install.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EAAoC,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE/F,wHAAwH;AACxH,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEzE,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG;IACnD,mGAAmG;IACnG,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,0GAA0G;IAC1G,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC,CAAC;AAEF,mHAAmH;AACnH,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAKtD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,cAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAClC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,oBAAyB,GAChC,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CA0B5B"}

package/dist/node/plugins/install.js

@@ -0,0 +1,213 @@
+// Installing (slice 7c §5, decision "Slice 7c's points" (3); slice 12 §5, decision "`chord.plugins` is a package's
+// manifest of plugins"): a plugin's npm dependencies as coding-agent installs a package's (`npm install` in the
+// plugin's real directory without dev dependencies, host peers or lifecycle scripts; the command overridable), and new
+// plugins from git (a shallow clone of a ref) or npm (a packed tarball extracted), each staged in a hidden directory of
+// the root, checked as discovery sees it, then renamed into place. Nothing a source supplies reaches git or npm as an
+// option: refs, URLs and names starting with `-` are refused, and positional arguments follow `--`.
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, readdir, rename, rm, rmdir, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { isPluginName } from "../../host/staging.js";
+import { discoverPackage, discoverPlugins } from "./discover.js";
+/** The install's arguments: production dependencies only, no host peers, no scripts, no audit or funding notes. */
+const INSTALL_ARGS = ["install", "--omit=dev", "--legacy-peer-deps", "--ignore-scripts", "--no-audit", "--no-fund"];
+/**
+ * Installs `plugin`'s `dependencies` into its own `node_modules` (`npm install --omit=dev --legacy-peer-deps
+ * --ignore-scripts --no-audit --no-fund` in its real directory; git dependencies with a ref are npm's). Rejects with
+ * the command's output when it fails, and when `context` aborts (the command is killed). A single-file plugin has
+ * nothing to install.
+ */
+export async function installDependencies(plugin, context, options = {}) {
+    if (plugin.layout === "file")
+        throw new Error(`plugin "${plugin.name}": a single-file plugin has no package.json`);
+    const [command, ...prefix] = npmCommandOf(options);
+    await run(command, [...prefix, ...INSTALL_ARGS], plugin.dir, context, `plugin "${plugin.name}": ${command} install`);
+}
+/**
+ * Installs new plugins into `root` from `source`, then their dependencies: from git, a shallow clone of the ref into
+ * `<root>/<repository name>`; from npm, the packed package extracted into `<root>/<name>`. The package's plugins are
+ * its `chord.plugins` folders, else by convention (discovery's rules). Returns their names. Refused: a source option
+ * (`-…`), an invalid name, an existing directory (no updating in place: install another ref, or delete and install), a
+ * package discovery reports a problem in or finds no plugin in, a plugin name another plugin of `options.roots` has.
+ * Only what this install created is removed on failure.
+ */
+export async function installPlugin(source, root, context, options = {}) {
+    const name = targetName(source);
+    await removeStaleStaging(root);
+    const made = await claim(root, name);
+    let staging;
+    try {
+        // Hidden: discovery skips it while it is staged; in the root: the rename stays on one file system.
+        staging = await mkdtemp(join(root, STAGING));
+        const staged = join(staging, "package");
+        if ("git" in source)
+            await clone(source.git, source.ref, staged, context);
+        else
+            await unpack(source.npm, source.version, staged, context, options);
+        await checkPackage(staged, made.target, root, context, options);
+        // The claimed directory is empty: renaming onto it moves the package into place in one step. Windows renames onto
+        // no existing directory: there the claim is released first (a concurrent install of the name may then win).
+        if (process.platform === "win32")
+            await rmdir(made.target);
+        await rename(staged, made.target);
+        const { plugins } = await discoverPackage(made.target, atRoot(root, options), context);
+        for (const plugin of plugins)
+            await installDependencies(plugin, context, options);
+        return plugins.map((plugin) => plugin.name);
+    }
+    catch (error) {
+        await rm(made.target, { recursive: true, force: true });
+        if (made.scope !== undefined)
+            await rmdir(made.scope).catch(() => { });
+        throw error;
+    }
+    finally {
+        if (staging !== undefined)
+            await rm(staging, { recursive: true, force: true });
+    }
+}
+/** The prefix of an install's staging directory in a root (hidden: discovery skips it). */
+const STAGING = ".chord-install-";
+/** How old a staging directory must be to count as left over by a crashed install. */
+const STALE_MS = 60 * 60 * 1000;
+/** Removes staging directories in `root` an install crashed out of (older than an hour). */
+async function removeStaleStaging(root) {
+    const names = await readdir(root).catch(() => []);
+    for (const name of names.filter((each) => each.startsWith(STAGING))) {
+        const path = join(root, name);
+        const info = await stat(path).catch(() => undefined);
+        if (info !== undefined && Date.now() - info.mtimeMs > STALE_MS)
+            await rm(path, { recursive: true, force: true });
+    }
+}
+/** The directory name a source installs into: the repository's name, or the package's (validated) name. */
+function targetName(source) {
+    const option = (value, what) => {
+        if (value === "" || value.startsWith("-"))
+            throw new Error(`installPlugin: ${what} "${value}" is refused`);
+    };
+    if ("git" in source) {
+        option(source.git, "repository");
+        option(source.ref, "ref");
+        const name = basename(source.git.replace(/\/+$/, "")).replace(/\.git$/, "");
+        if (name === "" || name.startsWith(".") || name.startsWith("-")) {
+            throw new Error(`installPlugin: "${source.git}" names no repository directory`);
+        }
+        return name;
+    }
+    option(source.npm, "package");
+    option(source.version, "version");
+    if (!isPluginName(source.npm))
+        throw new Error(`installPlugin: "${source.npm}" is not an npm package name`);
+    return source.npm;
+}
+/**
+ * Creates `<root>/<name>` (and a scope directory `<root>/@scope` it needs) without `recursive`, so an existing one
+ * refuses the install and a concurrent install of the same name loses here; returns what it created.
+ */
+async function claim(root, name) {
+    const target = join(root, name);
+    let scope;
+    if (name.startsWith("@")) {
+        const dir = dirname(target);
+        try {
+            await mkdir(dir);
+            scope = dir;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    try {
+        await mkdir(target);
+    }
+    catch (error) {
+        if (scope !== undefined)
+            await rmdir(scope).catch(() => { });
+        if (error.code === "EEXIST") {
+            throw new Error(`installPlugin: ${target} exists already`);
+        }
+        throw error;
+    }
+    return scope === undefined ? { target } : { target, scope };
+}
+/** The root a package is discovered as part of. */
+function atRoot(root, options) {
+    return { root, required: false, kinds: options.kinds ?? [] };
+}
+/**
+ * Checks the package staged at `staged` (going to `target`): discovery reports no problem in it, finds a plugin, and
+ * none of its plugins' names is taken in the app's roots.
+ */
+async function checkPackage(staged, target, root, context, options) {
+    const { plugins, problems } = await discoverPackage(staged, atRoot(root, options), context);
+    const [problem] = problems;
+    if (problem !== undefined)
+        throw new Error(`installPlugin: ${problem.path.replace(staged, target)}: ${problem.error}`);
+    if (plugins.length === 0)
+        throw new Error(`installPlugin: ${target} holds no plugin`);
+    const installed = await discoverPlugins(options.roots ?? [root], { kinds: options.kinds ?? [] }, context);
+    for (const plugin of plugins) {
+        const other = installed.plugins.find((each) => each.name === plugin.name);
+        if (other !== undefined)
+            throw new Error(`installPlugin: plugin "${plugin.name}" is in ${other.dir} already`);
+    }
+}
+/** The npm command of `options`. */
+function npmCommandOf(options) {
+    const [command, ...prefix] = options.npmCommand ?? ["npm"];
+    if (command === undefined)
+        throw new Error("npmCommand is empty");
+    return [command, ...prefix];
+}
+/** Runs `command` in `cwd`; rejects naming `what` with its output when it fails, and when `context` aborts. */
+async function run(command, args, cwd, context, what) {
+    context.abortSignal?.throwIfAborted();
+    const child = spawn(command, args, {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        signal: context.abortSignal,
+        // Never a prompt for credentials: an install runs unattended.
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    let output = "";
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+        output += chunk.toString();
+        stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+        output += chunk.toString();
+    });
+    const code = await new Promise((resolve, reject) => {
+        child.on("error", reject);
+        child.on("close", resolve);
+    });
+    if (code !== 0)
+        throw new Error(`${what} failed (exit ${code}): ${output.trim()}`);
+    return stdout;
+}
+/** A shallow clone of `ref` (a branch, tag or commit) of `url` into `dir` (made), detached at it. */
+async function clone(url, ref, dir, context) {
+    await mkdir(dir);
+    const what = `git clone of ${url} at ${ref}`;
+    await run("git", ["init", "--quiet"], dir, context, what);
+    await run("git", ["fetch", "--quiet", "--depth", "1", "--", url, ref], dir, context, what);
+    await run("git", ["-c", "advice.detachedHead=false", "checkout", "--quiet", "FETCH_HEAD", "--"], dir, context, what);
+}
+/** npm package `name` at `version` packed (`npm pack`) and extracted into `dir` (made). */
+async function unpack(name, version, dir, context, options) {
+    const [command, ...prefix] = npmCommandOf(options);
+    const packed = await mkdtemp(join(dirname(dir), "pack-"));
+    const what = `${command} pack ${name}@${version}`;
+    const args = [...prefix, "pack", "--json", "--pack-destination", packed, "--", `${name}@${version}`];
+    // npm's own output: a list of the packed tarballs.
+    const [tarball] = JSON.parse(await run(command, args, packed, context, what));
+    if (tarball === undefined)
+        throw new Error(`${what}: packed nothing`);
+    await mkdir(dir);
+    const file = join(packed, basename(tarball.filename));
+    await run("tar", ["-xzf", file, "--strip-components=1", "-C", dir], packed, context, `extracting ${name}`);
+}
+//# sourceMappingURL=install.js.map

package/dist/node/plugins/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../src/node/plugins/install.ts"],"names":[],"mappings":"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","sourcesContent":["// Installing (slice 7c §5, decision \"Slice 7c's points\" (3); slice 12 §5, decision \"`chord.plugins` is a package's\n// manifest of plugins\"): a plugin's npm dependencies as coding-agent installs a package's (`npm install` in the\n// plugin's real directory without dev dependencies, host peers or lifecycle scripts; the command overridable), and new\n// plugins from git (a shallow clone of a ref) or npm (a packed tarball extracted), each staged in a hidden directory of\n// the root, checked as discovery sees it, then renamed into place. Nothing a source supplies reaches git or npm as an\n// option: refs, URLs and names starting with `-` are refused, and positional arguments follow `--`.\n\nimport { spawn } from \"node:child_process\";\nimport { mkdir, mkdtemp, readdir, rename, rm, rmdir, stat } from \"node:fs/promises\";\nimport { basename, dirname, join } from \"node:path\";\nimport type { Context } from \"../../context/index.ts\";\nimport { isPluginName } from \"../../host/staging.ts\";\nimport { discoverPackage, discoverPlugins, type Plugin, type PluginRoot } from \"./discover.ts\";\n\n/** What installs take: the npm command (`[\"npm\"]` by default, e.g. `[\"pnpm\"]`); git and tar are run as `git`, `tar`. */\nexport type InstallOptions = { readonly npmCommand?: readonly string[] };\n\n/** What `installPlugin` takes besides the source and the root. */\nexport type InstallPluginOptions = InstallOptions & {\n\t/** The app's facet kinds: a package whose top has a facet file is one plugin (`[]` by default). */\n\treadonly kinds?: readonly string[];\n\t/** Every root of the app: a new plugin named like one in any of them is refused (`[root]` by default). */\n\treadonly roots?: readonly PluginRoot[];\n};\n\n/** Where `installPlugin` installs from: a git repository at a ref (a branch, tag or commit), or an npm package. */\nexport type PluginSource =\n\t| { readonly git: string; readonly ref: string }\n\t| { readonly npm: string; readonly version: string };\n\n/** The install's arguments: production dependencies only, no host peers, no scripts, no audit or funding notes. */\nconst INSTALL_ARGS = [\"install\", \"--omit=dev\", \"--legacy-peer-deps\", \"--ignore-scripts\", \"--no-audit\", \"--no-fund\"];\n\n/**\n * Installs `plugin`'s `dependencies` into its own `node_modules` (`npm install --omit=dev --legacy-peer-deps\n * --ignore-scripts --no-audit --no-fund` in its real directory; git dependencies with a ref are npm's). Rejects with\n * the command's output when it fails, and when `context` aborts (the command is killed). A single-file plugin has\n * nothing to install.\n */\nexport async function installDependencies(\n\tplugin: Plugin,\n\tcontext: Context,\n\toptions: InstallOptions = {},\n): Promise<void> {\n\tif (plugin.layout === \"file\") throw new Error(`plugin \"${plugin.name}\": a single-file plugin has no package.json`);\n\tconst [command, ...prefix] = npmCommandOf(options);\n\tawait run(command, [...prefix, ...INSTALL_ARGS], plugin.dir, context, `plugin \"${plugin.name}\": ${command} install`);\n}\n\n/**\n * Installs new plugins into `root` from `source`, then their dependencies: from git, a shallow clone of the ref into\n * `<root>/<repository name>`; from npm, the packed package extracted into `<root>/<name>`. The package's plugins are\n * its `chord.plugins` folders, else by convention (discovery's rules). Returns their names. Refused: a source option\n * (`-…`), an invalid name, an existing directory (no updating in place: install another ref, or delete and install), a\n * package discovery reports a problem in or finds no plugin in, a plugin name another plugin of `options.roots` has.\n * Only what this install created is removed on failure.\n */\nexport async function installPlugin(\n\tsource: PluginSource,\n\troot: string,\n\tcontext: Context,\n\toptions: InstallPluginOptions = {},\n): Promise<readonly string[]> {\n\tconst name = targetName(source);\n\tawait removeStaleStaging(root);\n\tconst made = await claim(root, name);\n\tlet staging: string | undefined;\n\ttry {\n\t\t// Hidden: discovery skips it while it is staged; in the root: the rename stays on one file system.\n\t\tstaging = await mkdtemp(join(root, STAGING));\n\t\tconst staged = join(staging, \"package\");\n\t\tif (\"git\" in source) await clone(source.git, source.ref, staged, context);\n\t\telse await unpack(source.npm, source.version, staged, context, options);\n\t\tawait checkPackage(staged, made.target, root, context, options);\n\t\t// The claimed directory is empty: renaming onto it moves the package into place in one step. Windows renames onto\n\t\t// no existing directory: there the claim is released first (a concurrent install of the name may then win).\n\t\tif (process.platform === \"win32\") await rmdir(made.target);\n\t\tawait rename(staged, made.target);\n\t\tconst { plugins } = await discoverPackage(made.target, atRoot(root, options), context);\n\t\tfor (const plugin of plugins) await installDependencies(plugin, context, options);\n\t\treturn plugins.map((plugin) => plugin.name);\n\t} catch (error) {\n\t\tawait rm(made.target, { recursive: true, force: true });\n\t\tif (made.scope !== undefined) await rmdir(made.scope).catch(() => {});\n\t\tthrow error;\n\t} finally {\n\t\tif (staging !== undefined) await rm(staging, { recursive: true, force: true });\n\t}\n}\n\n/** The prefix of an install's staging directory in a root (hidden: discovery skips it). */\nconst STAGING = \".chord-install-\";\n\n/** How old a staging directory must be to count as left over by a crashed install. */\nconst STALE_MS = 60 * 60 * 1000;\n\n/** Removes staging directories in `root` an install crashed out of (older than an hour). */\nasync function removeStaleStaging(root: string): Promise<void> {\n\tconst names = await readdir(root).catch(() => [] as string[]);\n\tfor (const name of names.filter((each) => each.startsWith(STAGING))) {\n\t\tconst path = join(root, name);\n\t\tconst info = await stat(path).catch(() => undefined);\n\t\tif (info !== undefined && Date.now() - info.mtimeMs > STALE_MS) await rm(path, { recursive: true, force: true });\n\t}\n}\n\n/** The directory name a source installs into: the repository's name, or the package's (validated) name. */\nfunction targetName(source: PluginSource): string {\n\tconst option = (value: string, what: string) => {\n\t\tif (value === \"\" || value.startsWith(\"-\")) throw new Error(`installPlugin: ${what} \"${value}\" is refused`);\n\t};\n\tif (\"git\" in source) {\n\t\toption(source.git, \"repository\");\n\t\toption(source.ref, \"ref\");\n\t\tconst name = basename(source.git.replace(/\\/+$/, \"\")).replace(/\\.git$/, \"\");\n\t\tif (name === \"\" || name.startsWith(\".\") || name.startsWith(\"-\")) {\n\t\t\tthrow new Error(`installPlugin: \"${source.git}\" names no repository directory`);\n\t\t}\n\t\treturn name;\n\t}\n\toption(source.npm, \"package\");\n\toption(source.version, \"version\");\n\tif (!isPluginName(source.npm)) throw new Error(`installPlugin: \"${source.npm}\" is not an npm package name`);\n\treturn source.npm;\n}\n\n/**\n * Creates `<root>/<name>` (and a scope directory `<root>/@scope` it needs) without `recursive`, so an existing one\n * refuses the install and a concurrent install of the same name loses here; returns what it created.\n */\nasync function claim(root: string, name: string): Promise<{ readonly target: string; readonly scope?: string }> {\n\tconst target = join(root, name);\n\tlet scope: string | undefined;\n\tif (name.startsWith(\"@\")) {\n\t\tconst dir = dirname(target);\n\t\ttry {\n\t\t\tawait mkdir(dir);\n\t\t\tscope = dir;\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code !== \"EEXIST\") throw error;\n\t\t}\n\t}\n\ttry {\n\t\tawait mkdir(target);\n\t} catch (error) {\n\t\tif (scope !== undefined) await rmdir(scope).catch(() => {});\n\t\tif ((error as NodeJS.ErrnoException).code === \"EEXIST\") {\n\t\t\tthrow new Error(`installPlugin: ${target} exists already`);\n\t\t}\n\t\tthrow error;\n\t}\n\treturn scope === undefined ? { target } : { target, scope };\n}\n\n/** The root a package is discovered as part of. */\nfunction atRoot(root: string, options: InstallPluginOptions) {\n\treturn { root, required: false, kinds: options.kinds ?? [] };\n}\n\n/**\n * Checks the package staged at `staged` (going to `target`): discovery reports no problem in it, finds a plugin, and\n * none of its plugins' names is taken in the app's roots.\n */\nasync function checkPackage(\n\tstaged: string,\n\ttarget: string,\n\troot: string,\n\tcontext: Context,\n\toptions: InstallPluginOptions,\n): Promise<void> {\n\tconst { plugins, problems } = await discoverPackage(staged, atRoot(root, options), context);\n\tconst [problem] = problems;\n\tif (problem !== undefined)\n\t\tthrow new Error(`installPlugin: ${problem.path.replace(staged, target)}: ${problem.error}`);\n\tif (plugins.length === 0) throw new Error(`installPlugin: ${target} holds no plugin`);\n\tconst installed = await discoverPlugins(options.roots ?? [root], { kinds: options.kinds ?? [] }, context);\n\tfor (const plugin of plugins) {\n\t\tconst other = installed.plugins.find((each) => each.name === plugin.name);\n\t\tif (other !== undefined) throw new Error(`installPlugin: plugin \"${plugin.name}\" is in ${other.dir} already`);\n\t}\n}\n\n/** The npm command of `options`. */\nfunction npmCommandOf(options: InstallOptions): readonly [string, ...string[]] {\n\tconst [command, ...prefix] = options.npmCommand ?? [\"npm\"];\n\tif (command === undefined) throw new Error(\"npmCommand is empty\");\n\treturn [command, ...prefix];\n}\n\n/** Runs `command` in `cwd`; rejects naming `what` with its output when it fails, and when `context` aborts. */\nasync function run(\n\tcommand: string,\n\targs: readonly string[],\n\tcwd: string,\n\tcontext: Context,\n\twhat: string,\n): Promise<string> {\n\tcontext.abortSignal?.throwIfAborted();\n\tconst child = spawn(command, args, {\n\t\tcwd,\n\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\tsignal: context.abortSignal,\n\t\t// Never a prompt for credentials: an install runs unattended.\n\t\tenv: { ...process.env, GIT_TERMINAL_PROMPT: \"0\" },\n\t});\n\tlet output = \"\";\n\tlet stdout = \"\";\n\tchild.stdout.on(\"data\", (chunk: Buffer) => {\n\t\toutput += chunk.toString();\n\t\tstdout += chunk.toString();\n\t});\n\tchild.stderr.on(\"data\", (chunk: Buffer) => {\n\t\toutput += chunk.toString();\n\t});\n\tconst code = await new Promise<number | null>((resolve, reject) => {\n\t\tchild.on(\"error\", reject);\n\t\tchild.on(\"close\", resolve);\n\t});\n\tif (code !== 0) throw new Error(`${what} failed (exit ${code}): ${output.trim()}`);\n\treturn stdout;\n}\n\n/** A shallow clone of `ref` (a branch, tag or commit) of `url` into `dir` (made), detached at it. */\nasync function clone(url: string, ref: string, dir: string, context: Context): Promise<void> {\n\tawait mkdir(dir);\n\tconst what = `git clone of ${url} at ${ref}`;\n\tawait run(\"git\", [\"init\", \"--quiet\"], dir, context, what);\n\tawait run(\"git\", [\"fetch\", \"--quiet\", \"--depth\", \"1\", \"--\", url, ref], dir, context, what);\n\tawait run(\"git\", [\"-c\", \"advice.detachedHead=false\", \"checkout\", \"--quiet\", \"FETCH_HEAD\", \"--\"], dir, context, what);\n}\n\n/** npm package `name` at `version` packed (`npm pack`) and extracted into `dir` (made). */\nasync function unpack(\n\tname: string,\n\tversion: string,\n\tdir: string,\n\tcontext: Context,\n\toptions: InstallOptions,\n): Promise<void> {\n\tconst [command, ...prefix] = npmCommandOf(options);\n\tconst packed = await mkdtemp(join(dirname(dir), \"pack-\"));\n\tconst what = `${command} pack ${name}@${version}`;\n\tconst args = [...prefix, \"pack\", \"--json\", \"--pack-destination\", packed, \"--\", `${name}@${version}`];\n\t// npm's own output: a list of the packed tarballs.\n\tconst [tarball] = JSON.parse(await run(command, args, packed, context, what)) as { readonly filename: string }[];\n\tif (tarball === undefined) throw new Error(`${what}: packed nothing`);\n\tawait mkdir(dir);\n\tconst file = join(packed, basename(tarball.filename));\n\tawait run(\"tar\", [\"-xzf\", file, \"--strip-components=1\", \"-C\", dir], packed, context, `extracting ${name}`);\n}\n"]}

package/dist/node/plugins/plugins.d.ts

@@ -0,0 +1,162 @@
+import type { Context } from "../../context/index.ts";
+import type { Principal } from "../../data/index.ts";
+import type { Host, LoadReport, PluginFacet, ReloadReport } from "../../host/index.ts";
+import { type BatchError } from "../../state/internal.ts";
+import type { Watchable } from "../../watch.ts";
+import type { BaseInputs } from "./base-inputs.ts";
+import { type AppApi, type BuiltFacet } from "./build.ts";
+import { type Discovery, type Plugin, type PluginRoot } from "./discover.ts";
+import type { HostPackages } from "./evaluate.ts";
+import { type InstallOptions, type PluginSource } from "./install.ts";
+import { type PluginScript } from "./runtime.ts";
+import { type PluginsState } from "./watcher.ts";
+/** What `createPlugins` takes. */
+export type PluginsOptions = {
+    /**
+     * The directories plugins are listed in, in order: the first root's plugin wins a duplicate name. A root marked
+     * `required` (`{ path, required: true }`, the app's own) makes `load` reject when one of its plugins fails.
+     */
+    readonly roots: readonly PluginRoot[];
+    /**
+     * The app's API (`{ name: "@acme/app", versions: ["v3", "v2"] }`, newest first): plugins import it at a listed
+     * version, its per-kind modules from their kind only, one version per facet, and never Chord directly. Without one,
+     * plugins import the host packages as listed.
+     */
+    readonly api?: AppApi;
+    /**
+     * The app's facet kinds (one file per kind in a plugin), each with where its builds run and the host packages they
+     * keep external: `{ server: { platform: "node", hostPackages: ["@earendil-works/chord", "@app/core"] }, … }`.
+     */
+    readonly kinds: Readonly<Record<string, KindDefinition>>;
+    /**
+     * The server's own base code, files and directories, hashed when the component is created: `base` is set while one
+     * differs from it or a source file is new in one of the directories (the app restarts its hosts; Chord restarts
+     * nothing).
+     */
+    readonly base?: readonly string[];
+    /** Where the app serves browser builds' assets: the URL prefix their imports evaluate to. */
+    readonly publicPath?: string;
+    /** How `installDependencies` runs npm. */
+    readonly install?: InstallOptions;
+    /** The watcher cannot watch (reported once), and the marks' watch listeners that threw. */
+    readonly onError: (error: PluginsError) => void;
+};
+/** One facet kind: Node or browser builds, and the host packages (by specifier) its builds keep external. */
+export type KindDefinition = {
+    readonly platform: "node" | "browser";
+    readonly hostPackages: readonly string[];
+};
+/** What the component reports. */
+export type PluginsError = BatchError | {
+    readonly kind: "watch_failed";
+    readonly error: unknown;
+};
+/**
+ * A build of some plugins, plain data (a clone of it reloads the same): every facet of each, the plugins as its
+ * discovery saw them by name (what a reload evaluates with), and the plugins no longer discovered.
+ */
+export type Built = {
+    readonly facets: readonly BuiltFacet[];
+    readonly plugins: Readonly<Record<string, Plugin>>;
+    readonly removed: readonly string[];
+};
+/**
+ * What a rollout step did on one of its hosts (`host` named by the step): its reload's report; `stopped` when the host
+ * stopped cleanly during the step (it gets the current set at its next start); `error` when it crashed or its reload
+ * failed (every plugin of the step's kinds in the build counts as failed there).
+ */
+export type RolloutHost = {
+    readonly host: string;
+    readonly report: ReloadReport;
+} | {
+    readonly host: string;
+    readonly stopped: true;
+} | {
+    readonly host: string;
+    readonly error: unknown;
+};
+/** What a rollout step does: reloads its hosts with the facets of its kinds, one result per host (D12). */
+export type RolloutStep = {
+    readonly name: string;
+    readonly kinds: readonly string[];
+    reload(built: Built, context: Context): Promise<{
+        readonly hosts: readonly RolloutHost[];
+    }>;
+};
+/** What a rollout did: each step's hosts in order, and the step it stopped at (rejected), if it stopped. */
+export type RolloutResult = {
+    readonly steps: readonly {
+        readonly name: string;
+        readonly hosts: readonly RolloutHost[];
+    }[];
+    readonly stopped: {
+        readonly step: string;
+        readonly error: unknown;
+    } | undefined;
+};
+/** The plugins component. */
+export interface Plugins {
+    /** The marks: `{ dirty, install, set, base }`, a JSON watchable. */
+    readonly state: Watchable<PluginsState>;
+    /** The plugins of the last discovery. */
+    readonly discovery: Discovery;
+    /**
+     * Builds every facet of `names` (and of plugins discovered since the last build; discovery runs again first when
+     * the plugin set changed): plain data. It changes no current set: a rollout ships it.
+     */
+    build(names: readonly string[], context: Context): Promise<Built>;
+    /**
+     * The complete current set of `kind`: every discovered plugin's facet of it (built on first use), as the last
+     * rollout or reload shipping `kind` left it; what a worker starts with.
+     */
+    scripts(kind: string, context: Context): Promise<readonly PluginScript[]>;
+    /**
+     * `kind`'s current set now, synchronously (`undefined` before its first use): a rollout step reads it as the rollout
+     * applied its build, before another rollout can change it.
+     */
+    current(kind: string): readonly PluginScript[] | undefined;
+    /**
+     * Loads `host` with `kind`'s current set, evaluated with `modules` (the host packages, this process's instances, by
+     * specifier; kept for the host's reloads), and `core` (the app's own facets): a plugin whose build or evaluation
+     * fails is left out and reported with the host's report. A required root's plugin failing, and a problem discovery
+     * reported in a required root (missing, an invalid package, a name another root has), reject the load with a
+     * `PluginError` once the host's load settled.
+     */
+    load<P extends Principal>(host: Host<P>, options: {
+        readonly kind: string;
+        readonly core: readonly PluginFacet<P>[];
+        readonly modules: HostPackages;
+    }, context: Context): Promise<LoadReport>;
+    /**
+     * Applies `built` to the current set of `host`'s kind (loaded by `load`) and reloads `host` with that complete set,
+     * after its earlier reloads (`PluginRuntime.reload`). The host's report.
+     */
+    reload<P extends Principal>(host: Host<P>, built: Built, context: Context): Promise<ReloadReport>;
+    /** An in-process rollout step named `name`: `reload(host, built)`, one host named `name`. */
+    step<P extends Principal>(name: string, host: Host<P>): RolloutStep;
+    /**
+     * Runs `steps` in order with `built`, applying it to the current set of each step's kinds right before that step,
+     * and stops at one that rejects; failed plugins and hosts do not stop it. Clears the dirty marks of the built
+     * plugins applied on every host of every step (not failed on any, every built kind of theirs shipped by a step)
+     * that did not change since the build.
+     */
+    rollout(steps: readonly RolloutStep[], built: Built, context: Context): Promise<RolloutResult>;
+    /** Installs plugin `name`'s dependencies (`installDependencies`): its install mark clears, and it is dirty. */
+    installDependencies(name: string, context: Context): Promise<void>;
+    /**
+     * Adds a running base artifact's record (a base bundle's `inputs`, beside `base`): `base` is set while one of its
+     * files differs from the bytes it read or is gone; each is compared once now (settles once those comparisons did).
+     * Files under `node_modules` are never watched.
+     */
+    watchBase(inputs: BaseInputs): Promise<void>;
+    /**
+     * Installs new plugins from git or npm into `root`, one of the roots (`installPlugin`), and marks `set`: the next
+     * build discovers and builds them. Returns their names.
+     */
+    installPlugin(source: PluginSource, root: string, context: Context): Promise<readonly string[]>;
+    /** Stops the watcher. */
+    close(): void;
+}
+/** Creates the plugins component (and its plugin runtime) and starts the watcher. Discovery runs at first use. */
+export declare function createPlugins(options: PluginsOptions, _context: Context): Plugins;
+//# sourceMappingURL=plugins.d.ts.map

package/dist/node/plugins/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../src/node/plugins/plugins.ts"],"names":[],"mappings":"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"}