@zjaaal/artemis 0.0.0-stage → 0.1.1

package/dist/constants.d.ts

@@ -0,0 +1,94 @@
+/** Exit codes: 0 success, 1 the command failed, 2 the command line was wrong. */
+export declare const EXIT_CODE: {
+    readonly OK: 0;
+    readonly FAILED: 1;
+    readonly USAGE: 2;
+};
+/** The exit codes of a failure: a failed run never exits with OK. */
+export declare const FAILURE_CODES: readonly [1, 2];
+export declare const COMMAND_TAG: unique symbol;
+export declare const TOPIC_TAG: unique symbol;
+export declare const COMMAND_ERROR_TAG: unique symbol;
+export declare const USAGE_ERROR_TAG: unique symbol;
+export declare const FLAG_TYPES: readonly ["boolean", "string"];
+/** A short flag is a single character (`-s`); the parser rejects anything else. */
+export declare const SHORT_FLAG_LENGTH = 1;
+/** The flags every command gets. Their names and shorts are reserved. */
+export declare const GLOBAL_FLAGS: {
+    readonly help: {
+        readonly type: "boolean";
+        readonly short: "h";
+        readonly description: "Show help for the command";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Print the result (or the error) as JSON on stdout";
+    };
+    readonly yes: {
+        readonly type: "boolean";
+        readonly short: "y";
+        readonly description: "Never prompt; use flags, saved values or defaults";
+    };
+};
+export declare const RESERVED_FLAGS: readonly string[];
+/** The global flags as typed on a command line: `--json`, `-y`, ... */
+export declare const GLOBAL_FLAG_TOKENS: readonly string[];
+export declare const RESERVED_SHORTS: readonly string[];
+export declare const HELP_WORD = "help";
+/** Ends the flags: everything after it is a plain argument. */
+export declare const TERMINATOR = "--";
+export declare const JSON_FLAG = "--json";
+export declare const FLAG_PREFIX = "-";
+/** Files and folders starting with one of these are private: helpers, data, the topic file. */
+export declare const PRIVATE_PREFIXES: readonly ["_", "."];
+export declare const COMMAND_EXTENSION = ".js";
+export declare const TOPIC_FILE = "_topic.js";
+/** Words of a command id are joined with this ("uve config set"); "uve:config:set" also works. */
+export declare const ID_SEPARATOR = " ";
+export declare const ALIAS_SEPARATOR = ":";
+/** Node appends a paragraph about "--" to unknown option errors; the first sentence is the useful part. */
+export declare const ERROR_SENTENCE_SEPARATOR = ". ";
+/** A typo is suggested when it is within this many edits, or a third of the name's length. */
+export declare const SUGGEST_MIN_DISTANCE = 2;
+export declare const SUGGEST_LENGTH_DIVISOR = 3;
+export declare const ANSI_ESCAPE = "\u001B[";
+export declare const ANSI_RESET = 0;
+/** SGR codes of each style. */
+export declare const STYLE_CODES: {
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly red: 31;
+    readonly green: 32;
+    readonly yellow: 33;
+    readonly cyan: 36;
+};
+export declare const DEFAULT_COLOR_ENV = "NO_COLOR";
+export declare const NOT_INTERACTIVE_MESSAGE = "This command needs input, but it is not running interactively.";
+export declare const NOT_INTERACTIVE_HINT = "Pass --yes to run without questions, or pass the flags that answer them (see --help).";
+export declare const CANCELLED_MESSAGE = "Cancelled.";
+export declare const TABLE_INDENT = "  ";
+export declare const TABLE_GAP = "  ";
+export declare const SECTION_SEPARATOR = "\n\n";
+export declare const NOTE_SEPARATOR = "; ";
+export declare const NO_COMMAND: null;
+/** Node system error codes the framework reacts to. */
+export declare const ERROR_CODE: {
+    readonly EXISTS: "EEXIST";
+    readonly MISSING: "ENOENT";
+    readonly PERMISSION_DENIED: "EPERM";
+    readonly MODULE_NOT_FOUND: "ERR_MODULE_NOT_FOUND";
+};
+/** The package a command file imports the framework from. */
+export declare const PACKAGE_NAME = "@zjaaal/artemis";
+/** The shipped binary finds its project through the nearest package.json. */
+export declare const MANIFEST_FILE = "package.json";
+export declare const CONFIG_KEY = "artemis";
+/** Where npm puts an installed package: a tool in here is always its own package, whatever it holds. */
+export declare const NODE_MODULES = "node_modules";
+export declare const SCOPE_FOLDER_PREFIX = "@";
+export declare const DEFAULT_COMMANDS_FOLDER = "commands";
+export declare const DEFAULT_BIN_NAME = "art";
+/** npm names the command of a string `bin` after the package, without its `@scope/`. */
+export declare const SCOPE_PREFIX: RegExp;
+/** A string that is a URL, such as `file:///app/bin.js` or `http://x`, and not a path (`C:\\x` is a path). */
+export declare const URL_LIKE: RegExp;

package/dist/constants.js

@@ -0,0 +1,86 @@
+/** Exit codes: 0 success, 1 the command failed, 2 the command line was wrong. */
+export const EXIT_CODE = { OK: 0, FAILED: 1, USAGE: 2 };
+/** The exit codes of a failure: a failed run never exits with OK. */
+export const FAILURE_CODES = [EXIT_CODE.FAILED, EXIT_CODE.USAGE];
+// Symbol.for, so a definition is recognised even if two copies of Artemis end up loaded
+export const COMMAND_TAG = Symbol.for('artemis.command');
+export const TOPIC_TAG = Symbol.for('artemis.topic');
+// Errors are tagged the same way, so an error thrown by another copy of Artemis (a project's own
+// local copy under a global `art`) is still recognised: `instanceof` only knows one copy.
+export const COMMAND_ERROR_TAG = Symbol.for('artemis.command-error');
+export const USAGE_ERROR_TAG = Symbol.for('artemis.usage-error');
+export const FLAG_TYPES = ['boolean', 'string'];
+/** A short flag is a single character (`-s`); the parser rejects anything else. */
+export const SHORT_FLAG_LENGTH = 1;
+/** The flags every command gets. Their names and shorts are reserved. */
+export const GLOBAL_FLAGS = {
+    help: { type: 'boolean', short: 'h', description: 'Show help for the command' },
+    json: { type: 'boolean', description: 'Print the result (or the error) as JSON on stdout' },
+    yes: {
+        type: 'boolean',
+        short: 'y',
+        description: 'Never prompt; use flags, saved values or defaults'
+    }
+};
+export const RESERVED_FLAGS = Object.keys(GLOBAL_FLAGS);
+/** The global flags as typed on a command line: `--json`, `-y`, ... */
+export const GLOBAL_FLAG_TOKENS = Object.entries(GLOBAL_FLAGS).flatMap(([name, flag]) => [`--${name}`, ...('short' in flag ? [`-${flag.short}`] : [])]);
+export const RESERVED_SHORTS = Object.values(GLOBAL_FLAGS).flatMap((flag) => 'short' in flag ? [flag.short] : []);
+export const HELP_WORD = 'help';
+/** Ends the flags: everything after it is a plain argument. */
+export const TERMINATOR = '--';
+export const JSON_FLAG = '--json';
+export const FLAG_PREFIX = '-';
+/** Files and folders starting with one of these are private: helpers, data, the topic file. */
+export const PRIVATE_PREFIXES = ['_', '.'];
+export const COMMAND_EXTENSION = '.js';
+export const TOPIC_FILE = '_topic.js';
+/** Words of a command id are joined with this ("uve config set"); "uve:config:set" also works. */
+export const ID_SEPARATOR = ' ';
+export const ALIAS_SEPARATOR = ':';
+/** Node appends a paragraph about "--" to unknown option errors; the first sentence is the useful part. */
+export const ERROR_SENTENCE_SEPARATOR = '. ';
+/** A typo is suggested when it is within this many edits, or a third of the name's length. */
+export const SUGGEST_MIN_DISTANCE = 2;
+export const SUGGEST_LENGTH_DIVISOR = 3;
+export const ANSI_ESCAPE = '\u001b[';
+export const ANSI_RESET = 0;
+/** SGR codes of each style. */
+export const STYLE_CODES = {
+    bold: 1,
+    dim: 2,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    cyan: 36
+};
+export const DEFAULT_COLOR_ENV = 'NO_COLOR';
+export const NOT_INTERACTIVE_MESSAGE = 'This command needs input, but it is not running interactively.';
+export const NOT_INTERACTIVE_HINT = 'Pass --yes to run without questions, or pass the flags that answer them (see --help).';
+export const CANCELLED_MESSAGE = 'Cancelled.';
+export const TABLE_INDENT = '  ';
+export const TABLE_GAP = '  ';
+export const SECTION_SEPARATOR = '\n\n';
+export const NOTE_SEPARATOR = '; ';
+export const NO_COMMAND = null;
+/** Node system error codes the framework reacts to. */
+export const ERROR_CODE = {
+    EXISTS: 'EEXIST',
+    MISSING: 'ENOENT',
+    PERMISSION_DENIED: 'EPERM',
+    MODULE_NOT_FOUND: 'ERR_MODULE_NOT_FOUND'
+};
+/** The package a command file imports the framework from. */
+export const PACKAGE_NAME = '@zjaaal/artemis';
+/** The shipped binary finds its project through the nearest package.json. */
+export const MANIFEST_FILE = 'package.json';
+export const CONFIG_KEY = 'artemis';
+/** Where npm puts an installed package: a tool in here is always its own package, whatever it holds. */
+export const NODE_MODULES = 'node_modules';
+export const SCOPE_FOLDER_PREFIX = '@';
+export const DEFAULT_COMMANDS_FOLDER = 'commands';
+export const DEFAULT_BIN_NAME = 'art';
+/** npm names the command of a string `bin` after the package, without its `@scope/`. */
+export const SCOPE_PREFIX = /^@[^/]+\//;
+/** A string that is a URL, such as `file:///app/bin.js` or `http://x`, and not a path (`C:\\x` is a path). */
+export const URL_LIKE = /^(file:|[a-z][a-z0-9+.-]*:\/\/)/i;

package/dist/context/context.d.ts

@@ -0,0 +1,6 @@
+import type { CreateContextFn } from '../models.js';
+/**
+ * The `ctx` a command receives. It keeps commands honest about their environment: `log` stays
+ * quiet under --json so stdout is parseable, and `prompt` refuses to hang when nobody can answer.
+ */
+export declare const createContext: CreateContextFn;

package/dist/context/context.js

@@ -0,0 +1,35 @@
+import { format } from 'node:util';
+import { CANCELLED_MESSAGE, NOT_INTERACTIVE_HINT, NOT_INTERACTIVE_MESSAGE } from '../constants.js';
+import { askQuestions } from '../edges/prompts.js';
+import { CommandError } from '../errors/errors.js';
+/** `ctx.prompt`: asks the user, or refuses to hang when nobody can answer. */
+const createPrompt = (interactive) => async (questions, { hint } = {}) => {
+    if (!interactive) {
+        throw new CommandError(NOT_INTERACTIVE_MESSAGE, { hint: hint ?? NOT_INTERACTIVE_HINT });
+    }
+    const { answers, cancelled } = await askQuestions(questions);
+    if (cancelled) {
+        throw new CommandError(CANCELLED_MESSAGE);
+    }
+    return answers;
+};
+/**
+ * The `ctx` a command receives. It keeps commands honest about their environment: `log` stays
+ * quiet under --json so stdout is parseable, and `prompt` refuses to hang when nobody can answer.
+ */
+export const createContext = ({ io, global, interactive, style, registry, invoke }) => ({
+    json: global.json,
+    interactive,
+    style,
+    log: (...parts) => {
+        if (!global.json) {
+            io.stdout.write(`${format(...parts)}\n`);
+        }
+    },
+    warn: (...parts) => {
+        io.stderr.write(`${format(...parts)}\n`);
+    },
+    prompt: createPrompt(interactive),
+    commands: [...registry.commands.values()],
+    invoke
+});

package/dist/define/define.d.ts

@@ -0,0 +1,15 @@
+import type { DefineCommandFn, DefineTopicFn, IsCommandFn, IsTopicFn } from '../models.js';
+/**
+ * Declares a command. The file's path inside the commands folder gives it its name
+ * (`commands/setup/uve.js` is `setup uve`), so the definition only describes what it does.
+ *
+ * `args` and `flags` are read as constants, so `run` receives them typed: a required or defaulted
+ * arg is a string, an optional one may be undefined, and `choices` narrow the type.
+ *
+ * @throws {TypeError} when the definition breaks a rule (no description, reserved flag, ...).
+ */
+export declare const defineCommand: DefineCommandFn;
+/** Describes a topic folder. Put it in `_topic.js` inside the folder. */
+export declare const defineTopic: DefineTopicFn;
+export declare const isCommand: IsCommandFn;
+export declare const isTopic: IsTopicFn;

package/dist/define/define.js

@@ -0,0 +1,99 @@
+import { COMMAND_TAG, FLAG_TYPES, RESERVED_FLAGS, RESERVED_SHORTS, SHORT_FLAG_LENGTH, TOPIC_TAG } from '../constants.js';
+import { hasTag } from '../utils/tag.js';
+function fail(message) {
+    throw new TypeError(`defineCommand: ${message}`);
+}
+// A JavaScript caller can hand over a null arg, so the optional chaining is deliberate.
+const isOptional = (arg) => !arg?.required;
+const isRequiredAfterOptional = (arg, index, firstOptional) => Boolean(arg.required) && firstOptional !== -1 && index > firstOptional;
+const isRequiredWithDefault = (arg) => Boolean(arg.required) && arg.default !== undefined;
+function validateArgs(args) {
+    const firstOptional = args.findIndex(isOptional);
+    args.forEach((arg, index) => {
+        if (!arg?.name) {
+            fail('every arg needs a name');
+        }
+        if (isRequiredWithDefault(arg)) {
+            fail(`arg "${arg.name}" cannot be required and have a default`);
+        }
+        if (isRequiredAfterOptional(arg, index, firstOptional)) {
+            fail(`required arg "${arg.name}" cannot come after an optional one`);
+        }
+    });
+}
+const isReservedShort = (flag) => Boolean(flag.short) && RESERVED_SHORTS.includes(flag.short ?? '');
+const isMultiCharacterShort = (flag) => flag.short !== undefined && flag.short.length !== SHORT_FLAG_LENGTH;
+/** What the default of a flag has to be for the parser to accept it. */
+function expectedDefault({ type, multiple }) {
+    if (type === 'boolean') {
+        return 'a boolean';
+    }
+    return multiple ? 'an array of strings' : 'a string';
+}
+function hasDefaultOfWrongType({ type, multiple, default: value }) {
+    if (value === undefined) {
+        return false;
+    }
+    if (type === 'boolean') {
+        return typeof value !== 'boolean';
+    }
+    if (multiple) {
+        return !Array.isArray(value) || value.some((item) => typeof item !== 'string');
+    }
+    return typeof value !== 'string';
+}
+function validateFlag(name, flag) {
+    if (RESERVED_FLAGS.includes(name)) {
+        fail(`flag "--${name}" is reserved by Artemis`);
+    }
+    if (isReservedShort(flag)) {
+        fail(`short flag "-${flag.short}" is reserved by Artemis`);
+    }
+    if (isMultiCharacterShort(flag)) {
+        fail(`short flag "-${flag.short}" of "--${name}" must be a single character`);
+    }
+    if (!FLAG_TYPES.includes(flag.type)) {
+        fail(`flag "--${name}" needs type "boolean" or "string"`);
+    }
+    if (hasDefaultOfWrongType(flag)) {
+        fail(`the default of flag "--${name}" must be ${expectedDefault(flag)}`);
+    }
+}
+/**
+ * Declares a command. The file's path inside the commands folder gives it its name
+ * (`commands/setup/uve.js` is `setup uve`), so the definition only describes what it does.
+ *
+ * `args` and `flags` are read as constants, so `run` receives them typed: a required or defaulted
+ * arg is a string, an optional one may be undefined, and `choices` narrow the type.
+ *
+ * @throws {TypeError} when the definition breaks a rule (no description, reserved flag, ...).
+ */
+export const defineCommand = (definition) => {
+    // A JavaScript caller can pass nothing at all; the checks below then name what is missing.
+    const { description, run, args: declaredArgs, flags: declaredFlags, aliases = [], examples = [], ...extra } = definition ?? {};
+    // Casts, not conversions: an omitted `args` or `flags` is the empty default of the type parameter.
+    const args = (declaredArgs ?? []);
+    const flags = (declaredFlags ?? {});
+    if (typeof description !== 'string' || !description) {
+        fail('a description is required');
+    }
+    if (typeof run !== 'function') {
+        fail('a run function is required');
+    }
+    validateArgs(args);
+    Object.entries(flags).forEach(([name, flag]) => validateFlag(name, flag));
+    return Object.freeze({
+        [COMMAND_TAG]: true,
+        description,
+        run,
+        args,
+        flags,
+        aliases,
+        examples,
+        ...extra
+    });
+};
+/** Describes a topic folder. Put it in `_topic.js` inside the folder. */
+export const defineTopic = ({ description } = {}) => Object.freeze({ [TOPIC_TAG]: true, description: description ?? '' });
+export const isCommand = (value) => hasTag(value, COMMAND_TAG);
+export const isTopic = (value) => hasTag(value, TOPIC_TAG);

package/dist/discover/discover.d.ts

@@ -0,0 +1,7 @@
+import type { DiscoverFn } from '../models.js';
+/**
+ * Walks the commands folder. Every public `.js` file is a command and every public folder is a
+ * topic, so `commands/uve/config/set.js` becomes the command `uve config set` inside the topics
+ * `uve` and `uve config`.
+ */
+export declare const discover: DiscoverFn;

package/dist/discover/discover.js

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { COMMAND_EXTENSION, ID_SEPARATOR, PRIVATE_PREFIXES, TOPIC_FILE } from '../constants.js';
+import { isCommand, isTopic } from '../define/define.js';
+import { listDirectory, pathExists } from '../edges/files.js';
+import { importDefault } from '../edges/modules.js';
+import { messageOf } from '../utils/error-message.js';
+const createRegistry = () => ({
+    commands: new Map(),
+    topics: new Map(),
+    aliases: new Map(),
+    warnings: []
+});
+// Files and folders starting with "_" or "." are private: helpers, data, the topic file
+const isPublic = (name) => !PRIVATE_PREFIXES.some((prefix) => name.startsWith(prefix));
+const byName = (a, b) => a.name.localeCompare(b.name);
+const isCommandFile = (name) => name.endsWith(COMMAND_EXTENSION);
+/** Loads one command file. A broken file is a warning, so one bad drop-in does not take the CLI down. */
+async function loadCommand({ registry, root }, file, id) {
+    const relative = path.relative(root, file);
+    try {
+        const definition = await importDefault(file);
+        if (!isCommand(definition)) {
+            registry.warnings.push(`${relative} is not a command (default export must come from defineCommand); skipped`);
+            return 0;
+        }
+        registry.commands.set(id, { id, file, definition });
+        return 1;
+    }
+    catch (error) {
+        registry.warnings.push(`${relative} failed to load and was skipped: ${messageOf(error)}`);
+        return 0;
+    }
+}
+// A topic file that fails to load only costs the topic its description; the commands still work.
+const ignoreBrokenTopicFile = () => undefined;
+async function registerTopic({ registry }, dir, parts) {
+    const topicFile = path.join(dir, TOPIC_FILE);
+    const topic = pathExists(topicFile)
+        ? await importDefault(topicFile).catch(ignoreBrokenTopicFile)
+        : undefined;
+    const id = parts.join(ID_SEPARATOR);
+    registry.topics.set(id, { id, description: isTopic(topic) ? topic.description : '' });
+}
+/** Discovers one folder entry and returns how many commands it contributed. */
+async function discoverEntry(context, dir, parts, entry) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory) {
+        return walk(context, file, [...parts, entry.name]);
+    }
+    if (!isCommandFile(entry.name)) {
+        return 0;
+    }
+    const id = [...parts, entry.name.slice(0, -COMMAND_EXTENSION.length)].join(ID_SEPARATOR);
+    return loadCommand(context, file, id);
+}
+/** Walks a folder; a folder that held at least one command becomes a topic. */
+async function walk(context, dir, parts) {
+    const entries = listDirectory(dir)
+        .filter((entry) => isPublic(entry.name))
+        .sort(byName);
+    let found = 0;
+    for (const entry of entries) {
+        found += await discoverEntry(context, dir, parts, entry);
+    }
+    if (parts.length && found) {
+        await registerTopic(context, dir, parts);
+    }
+    return found;
+}
+/** Aliases are claimed after every command is known, so a command name always beats an alias. */
+function registerAliases(registry) {
+    const claims = [...registry.commands.values()].flatMap(({ id, definition }) => definition.aliases.map((alias) => ({ alias, id })));
+    claims.forEach(({ alias, id }) => {
+        const isTaken = registry.commands.has(alias) ||
+            registry.topics.has(alias) ||
+            registry.aliases.has(alias);
+        if (isTaken) {
+            registry.warnings.push(`alias "${alias}" of "${id}" is already taken; ignored`);
+        }
+        else {
+            registry.aliases.set(alias, id);
+        }
+    });
+}
+/**
+ * Walks the commands folder. Every public `.js` file is a command and every public folder is a
+ * topic, so `commands/uve/config/set.js` becomes the command `uve config set` inside the topics
+ * `uve` and `uve config`.
+ */
+export const discover = async (commandsDir) => {
+    const registry = createRegistry();
+    if (!pathExists(commandsDir)) {
+        registry.warnings.push(`commands folder not found: ${commandsDir}`);
+        return registry;
+    }
+    await walk({ registry, root: commandsDir }, commandsDir, []);
+    registerAliases(registry);
+    return registry;
+};

package/dist/edges/files.d.ts

@@ -0,0 +1,25 @@
+import type { CreateExclusiveFn, IsFolderFn, ListDirectoryFn, MakeDirectoryFn, ModifiedAtFn, PathExistsFn, ReadManifestFn, ReadTextIfExistsFn, RealPathFn, RemoveFileFn, WriteTextFn } from '../models.js';
+export declare const listDirectory: ListDirectoryFn;
+export declare const pathExists: PathExistsFn;
+export declare const makeDirectory: MakeDirectoryFn;
+export declare const writeText: WriteTextFn;
+/** Removing a file that is not there is not an error: the goal is that it is gone. */
+export declare const removeFile: RemoveFileFn;
+/** The text of a file, or undefined when it is not there (someone may remove it at any moment). */
+export declare const readTextIfExists: ReadTextIfExistsFn;
+/**
+ * Creates the file with its whole content already in it, or says someone else has it. The text is
+ * written to a staging file that is then hard-linked into place, so the file can never be seen
+ * empty or half written, and the link fails if the file already exists.
+ */
+export declare const createExclusive: CreateExclusiveFn;
+export declare const modifiedAt: ModifiedAtFn;
+/** The real path of a folder; one that does not exist yet has none, so it is resolved as given. */
+export declare const realPathOrResolve: RealPathFn;
+/**
+ * What the package.json of a folder says, or undefined when the folder has none. A file that cannot
+ * be read, is not valid JSON or is not an object is returned as an error, not thrown: whether it
+ * matters depends on whether it turns out to be the project.
+ */
+export declare const readManifest: ReadManifestFn;
+export declare const isFolder: IsFolderFn;

package/dist/edges/files.js

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ERROR_CODE, MANIFEST_FILE } from '../constants.js';
+import { CommandError } from '../errors/errors.js';
+import { messageOf } from '../utils/error-message.js';
+import { isRecord } from '../utils/is-record.js';
+import { codeOf } from '../utils/error-code.js';
+// Edge: the only place the framework and the terminal kit touch the filesystem.
+export const listDirectory = (dir) => fs
+    .readdirSync(dir, { withFileTypes: true })
+    .map((entry) => ({ name: entry.name, isDirectory: entry.isDirectory() }));
+export const pathExists = (path) => fs.existsSync(path);
+export const makeDirectory = (dir) => {
+    fs.mkdirSync(dir, { recursive: true });
+};
+export const writeText = (file, text) => {
+    fs.writeFileSync(file, text);
+};
+/** Removing a file that is not there is not an error: the goal is that it is gone. */
+export const removeFile = (file) => {
+    fs.rmSync(file, { force: true });
+};
+/** The text of a file, or undefined when it is not there (someone may remove it at any moment). */
+export const readTextIfExists = (file) => {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (codeOf(error) === ERROR_CODE.MISSING) {
+            return undefined;
+        }
+        throw error;
+    }
+};
+/**
+ * Creates the file with its whole content already in it, or says someone else has it. The text is
+ * written to a staging file that is then hard-linked into place, so the file can never be seen
+ * empty or half written, and the link fails if the file already exists.
+ */
+export const createExclusive = (file, text) => {
+    const staging = `${file}.${randomUUID()}.tmp`;
+    fs.writeFileSync(staging, text);
+    try {
+        fs.linkSync(staging, file);
+        return true;
+    }
+    catch (error) {
+        if (codeOf(error) === ERROR_CODE.EXISTS) {
+            return false;
+        }
+        throw error;
+    }
+    finally {
+        fs.rmSync(staging, { force: true });
+    }
+};
+export const modifiedAt = (file) => fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs;
+/** The real path of a folder; one that does not exist yet has none, so it is resolved as given. */
+export const realPathOrResolve = (folder) => {
+    try {
+        return fs.realpathSync(folder);
+    }
+    catch {
+        // Nothing to lose: a folder that does not exist yet is used by its resolved path.
+        return path.resolve(folder);
+    }
+};
+/** A package.json that cannot be read: the file is named, and nothing is thrown. */
+const unreadable = (file, error) => ({
+    error: new CommandError(`Cannot read ${file}: ${messageOf(error)}`, {
+        hint: 'Check that it is a readable file, or run from a folder whose package.json is.'
+    })
+});
+function parseManifest(file, text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (isRecord(parsed)) {
+            return { manifest: parsed, text };
+        }
+    }
+    catch (error) {
+        return {
+            error: new CommandError(`${file} is not valid JSON: ${messageOf(error)}`, {
+                hint: 'Fix the file, or run from a folder whose package.json is valid.'
+            })
+        };
+    }
+    return {
+        error: new CommandError(`${file} must contain a JSON object`, {
+            hint: 'A package.json is an object, such as { "name": "my-project" }.'
+        })
+    };
+}
+/**
+ * What the package.json of a folder says, or undefined when the folder has none. A file that cannot
+ * be read, is not valid JSON or is not an object is returned as an error, not thrown: whether it
+ * matters depends on whether it turns out to be the project.
+ */
+export const readManifest = (dir) => {
+    const file = path.join(dir, MANIFEST_FILE);
+    let text;
+    try {
+        text = readTextIfExists(file);
+    }
+    catch (error) {
+        return unreadable(file, error);
+    }
+    return text === undefined ? undefined : parseManifest(file, text);
+};
+export const isFolder = (target) => fs.statSync(target, { throwIfNoEntry: false })?.isDirectory() ?? false;

package/dist/edges/modules.d.ts

@@ -0,0 +1,2 @@
+import type { ImportDefaultFn } from '../models.js';
+export declare const importDefault: ImportDefaultFn;

package/dist/edges/modules.js

@@ -0,0 +1,6 @@
+import { pathToFileURL } from 'node:url';
+// Edge: loads a command file the way Node loads any ES module, and returns its default export.
+export const importDefault = async (file) => {
+    const loaded = await import(pathToFileURL(file).href);
+    return loaded.default;
+};

package/dist/edges/process.d.ts

@@ -0,0 +1,2 @@
+import type { CurrentProcessFn } from '../models.js';
+export declare const currentProcess: CurrentProcessFn;

package/dist/edges/process.js

@@ -0,0 +1,9 @@
+// Edge: the only place a run reads the real process, and only for what the caller did not pass.
+export const currentProcess = () => ({
+    stdout: process.stdout,
+    stderr: process.stderr,
+    env: process.env,
+    args: process.argv.slice(2),
+    stdinIsTTY: Boolean(process.stdin.isTTY),
+    stdoutIsTTY: Boolean(process.stdout.isTTY)
+});

package/dist/edges/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { AskFn } from '../models.js';
+export declare const askQuestions: AskFn;

package/dist/edges/prompts.js

@@ -0,0 +1,14 @@
+// Edge: the only place `prompts` is loaded, and only when a command really asks.
+export const askQuestions = async (questions) => {
+    const { default: prompts } = await import('prompts');
+    let cancelled = false;
+    const answers = await prompts(questions, {
+        // Returning true keeps asking the remaining questions, as the JS version did; the caller
+        // turns the cancellation into an error afterwards.
+        onCancel: () => {
+            cancelled = true;
+            return true;
+        }
+    });
+    return { answers, cancelled };
+};

package/dist/edges/system.d.ts

@@ -0,0 +1,4 @@
+import type { HomeDirectoryFn, ProcessIdFn, WorkingDirectoryFn } from '../models.js';
+export declare const homeDirectory: HomeDirectoryFn;
+export declare const workingDirectory: WorkingDirectoryFn;
+export declare const processId: ProcessIdFn;

package/dist/edges/system.js

@@ -0,0 +1,5 @@
+import os from 'node:os';
+// Edge: where the machine says the user's home is.
+export const homeDirectory = () => os.homedir();
+export const workingDirectory = () => process.cwd();
+export const processId = () => process.pid;