@zjaaal/artemis 0.0.0-stage → 0.1.2

package/dist/cli/constants.js

@@ -0,0 +1,34 @@
+/** A word the shipped `art` handles itself, like `help`: it makes a folder a project. */
+export const INIT_WORD = 'init';
+export const INIT_USAGE_LINE = `${INIT_WORD} [--json]`;
+export const INIT_HELP = `Usage: ${INIT_USAGE_LINE}\n\nMakes the current folder a project: a package.json with an "artemis" key, a commands/ folder and a sample command. Nothing that exists is overwritten. It takes no arguments: go to the folder first.`;
+/** The only flags \`init\` takes: it is a fixed word of the binary, not a command, so it needs no more. */
+export const INIT_FLAGS = { json: '--json', help: '--help', helpShort: '-h' };
+/** What `init` writes for the declaration, and the fields of a package.json it has to create. */
+export const INIT_DECLARATION = { commandsDir: 'commands' };
+export const NEW_MANIFEST_FIELDS = { private: true, type: 'module' };
+/** The command `init` writes so that `art hello` works right away. */
+export const SAMPLE_COMMAND_FILE = 'hello.js';
+export const SAMPLE_COMMAND_SOURCE = `import { defineCommand } from '@zjaaal/artemis';
+
+export default defineCommand({
+    description: 'Say hello',
+    args: [{ name: 'name', description: 'Who to greet', default: 'world' }],
+    run({ args, ctx }) {
+        const greeting = \`hello \${args.name}\`;
+
+        ctx.log(greeting);
+
+        return { greeting };
+    }
+});
+`;
+export const FALLBACK_PACKAGE_NAME = 'project';
+export const DEFAULT_INDENT_SPACES = 2;
+export const INDENT_PATTERN = /^([ \t]+)"/m;
+export const PACKAGE_NAME_INVALID = /[^a-z0-9._-]+/g;
+export const PACKAGE_NAME_EDGES = /^[-._]+|-+$/g;
+export const TYPE_WARNING = 'Your package.json does not say "type": "module". Command files are ES modules, so Node prints a warning for each one until it does.';
+export const SHADOW_WARNING = 'This project has a command or topic called "init", and the init word of this binary hides it: it cannot be run through here. Rename it.';
+export const CRLF = '\r\n';
+export const LF = '\n';

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export type { CliOptions } from '../models.js';
+export { launch as cli } from './launch.js';

package/dist/cli/index.js

@@ -0,0 +1 @@
+export { launch as cli } from './launch.js';

package/dist/cli/init-command.d.ts

@@ -0,0 +1,8 @@
+import type { InitCommandFn } from '../models.js';
+/**
+ * `init [--json]`: makes the current folder a project. Handled by the shipped binary itself, like
+ * `help`, because it has to work where there is no project yet. It is a fixed word and not a command
+ * a person writes, so it takes no arguments and no flags beyond `--json` and `--help`: anything else
+ * is a UsageError (exit 2).
+ */
+export declare const initCommand: InitCommandFn;

package/dist/cli/init-command.js

@@ -0,0 +1,42 @@
+import { EXIT_CODE } from '../constants.js';
+import { UsageError } from '../errors/errors.js';
+import { resolveWorld } from '../run/world.js';
+import { INIT_FLAGS, INIT_HELP, INIT_USAGE_LINE, INIT_WORD } from './constants.js';
+import { initProject } from './init.js';
+const KNOWN_WORDS = Object.values(INIT_FLAGS);
+function describeResult({ created, kept, warnings }) {
+    const lines = [
+        ...created.map((file) => `Created ${file}`),
+        ...kept.map((file) => `Kept    ${file} (already there)`),
+        ...warnings.map((warning) => `Warning: ${warning}`)
+    ];
+    return created.length
+        ? lines.join('\n')
+        : ['Already a project: nothing to create.', ...lines].join('\n');
+}
+/**
+ * `init [--json]`: makes the current folder a project. Handled by the shipped binary itself, like
+ * `help`, because it has to work where there is no project yet. It is a fixed word and not a command
+ * a person writes, so it takes no arguments and no flags beyond `--json` and `--help`: anything else
+ * is a UsageError (exit 2).
+ */
+export const initCommand = (words, options, cwd) => {
+    const unexpected = words.find((word) => !KNOWN_WORDS.includes(word));
+    const { io } = resolveWorld(options);
+    if (unexpected) {
+        throw new UsageError(`${INIT_WORD} takes no arguments, but got "${unexpected}"`, {
+            usage: INIT_USAGE_LINE,
+            hint: 'Go to the folder you want to make a project, then run it.'
+        });
+    }
+    if (words.includes(INIT_FLAGS.help) || words.includes(INIT_FLAGS.helpShort)) {
+        io.stdout.write(`${INIT_HELP}\n`);
+        return EXIT_CODE.OK;
+    }
+    const result = initProject(cwd);
+    const output = words.includes(INIT_FLAGS.json)
+        ? JSON.stringify({ ok: true, command: INIT_WORD, result })
+        : describeResult(result);
+    io.stdout.write(`${output}\n`);
+    return EXIT_CODE.OK;
+};

package/dist/cli/init.d.ts

@@ -0,0 +1,23 @@
+import type { AddKeyFn, DetectIndentFn, InitProjectFn, PackageNameForFn, PlanInitFn } from '../models.js';
+/** The indentation a package.json already uses, so editing it does not reformat the whole file. */
+export declare const detectIndent: DetectIndentFn;
+/** A valid npm package name for a folder: lowercase, no spaces or odd characters. */
+export declare const packageNameFor: PackageNameForFn;
+/**
+ * The same JSON object with one more property at the end. Only that changes: every byte before it,
+ * the indentation, inline arrays, key order, line endings (CRLF stays CRLF) and the final newline are
+ * kept, because the text is edited and not parsed and written back.
+ */
+export declare const addKey: AddKeyFn;
+/**
+ * Decides what making a folder a project takes: a package.json with the "artemis" key (created, or
+ * the key added to the one that is there), a commands folder, and a sample command so `hello` works
+ * at once. Pure, and it never overwrites: files are only planned where there is none, the sample only
+ * into a commands folder that is new or empty, and an existing package.json only gains the one key.
+ */
+export declare const planInit: PlanInitFn;
+/**
+ * Makes `dir` a project: reads what is there once, plans, and does it. Running it again changes
+ * nothing. A package.json that cannot be read or parsed is an error: editing it would be guesswork.
+ */
+export declare const initProject: InitProjectFn;

package/dist/cli/init.js

@@ -0,0 +1,153 @@
+import path from 'node:path';
+import { CONFIG_KEY, DEFAULT_COMMANDS_FOLDER, MANIFEST_FILE } from '../constants.js';
+import { createExclusive, isFolder, listDirectory, makeDirectory, pathExists, readManifest, writeText } from '../edges/files.js';
+import { CommandError } from '../errors/errors.js';
+import { CRLF, DEFAULT_INDENT_SPACES, FALLBACK_PACKAGE_NAME, INDENT_PATTERN, INIT_DECLARATION, INIT_WORD, LF, NEW_MANIFEST_FIELDS, PACKAGE_NAME_EDGES, PACKAGE_NAME_INVALID, SAMPLE_COMMAND_FILE, SAMPLE_COMMAND_SOURCE, SHADOW_WARNING, TYPE_WARNING } from './constants.js';
+import { resolveSettings } from './settings.js';
+/** The indentation a package.json already uses, so editing it does not reformat the whole file. */
+export const detectIndent = (text) => INDENT_PATTERN.exec(text)?.[1] ?? ' '.repeat(DEFAULT_INDENT_SPACES);
+/** A valid npm package name for a folder: lowercase, no spaces or odd characters. */
+export const packageNameFor = (dir) => {
+    const name = path
+        .basename(dir)
+        .toLowerCase()
+        .replace(PACKAGE_NAME_INVALID, '-')
+        .replace(PACKAGE_NAME_EDGES, '');
+    return name || FALLBACK_PACKAGE_NAME;
+};
+/** `{ "commandsDir": "commands" }`, on one line, for adding to a file without reformatting it. */
+const declarationText = () => `{ ${Object.entries(INIT_DECLARATION)
+    .map(([key, value]) => `${JSON.stringify(key)}: ${JSON.stringify(value)}`)
+    .join(', ')} }`;
+/**
+ * The same JSON object with one more property at the end. Only that changes: every byte before it,
+ * the indentation, inline arrays, key order, line endings (CRLF stays CRLF) and the final newline are
+ * kept, because the text is edited and not parsed and written back.
+ */
+export const addKey = (text, key, valueText) => {
+    const closing = /^([\s\S]*)\}(\s*)$/.exec(text);
+    const body = (closing?.[1] ?? text).trimEnd();
+    const after = closing?.[2] ?? '';
+    const comma = body.endsWith('{') ? '' : ',';
+    const property = `${JSON.stringify(key)}: ${valueText}`;
+    // A file written on one line stays on one line.
+    if (!text.includes(LF)) {
+        return `${body}${comma} ${property} }${after}`;
+    }
+    const eol = text.includes(CRLF) ? CRLF : LF;
+    return `${body}${comma}${eol}${detectIndent(text)}${property}${eol}}${after}`;
+};
+const newManifest = (dir) => `${JSON.stringify({ name: packageNameFor(dir), ...NEW_MANIFEST_FIELDS, [CONFIG_KEY]: INIT_DECLARATION }, null, ' '.repeat(DEFAULT_INDENT_SPACES))}\n`;
+function planManifest(input, manifestPath, plan) {
+    const { dir, manifest, manifestText } = input;
+    if (manifest === undefined || manifestText === undefined) {
+        plan.steps.push({
+            kind: 'file',
+            mode: 'create',
+            path: manifestPath,
+            text: newManifest(dir)
+        });
+        return;
+    }
+    if (manifest[CONFIG_KEY] !== undefined) {
+        plan.kept.push(manifestPath);
+    }
+    else {
+        plan.steps.push({
+            kind: 'file',
+            mode: 'update',
+            path: manifestPath,
+            text: addKey(manifestText, CONFIG_KEY, declarationText())
+        });
+    }
+    if (manifest.type !== 'module') {
+        plan.warnings.push(TYPE_WARNING);
+    }
+}
+/**
+ * Decides what making a folder a project takes: a package.json with the "artemis" key (created, or
+ * the key added to the one that is there), a commands folder, and a sample command so `hello` works
+ * at once. Pure, and it never overwrites: files are only planned where there is none, the sample only
+ * into a commands folder that is new or empty, and an existing package.json only gains the one key.
+ */
+export const planInit = (input) => {
+    const plan = { steps: [], kept: [], warnings: [] };
+    planManifest(input, path.join(input.dir, MANIFEST_FILE), plan);
+    if (input.commandsDirExists) {
+        plan.kept.push(input.commandsDir);
+    }
+    else {
+        plan.steps.push({ kind: 'folder', path: input.commandsDir });
+    }
+    if (!input.commandsDirExists || input.commandsDirIsEmpty) {
+        plan.steps.push({
+            kind: 'file',
+            mode: 'create',
+            path: path.join(input.commandsDir, SAMPLE_COMMAND_FILE),
+            text: SAMPLE_COMMAND_SOURCE
+        });
+    }
+    if (input.shadowsCommand) {
+        plan.warnings.push(SHADOW_WARNING);
+    }
+    return plan;
+};
+/** Does one step. A file to create is created exclusively: it fails, never overwrites, if it appeared meanwhile. */
+function applyStep(step) {
+    if (step.kind === 'folder') {
+        makeDirectory(step.path);
+        return;
+    }
+    makeDirectory(path.dirname(step.path));
+    if (step.mode === 'update') {
+        writeText(step.path, step.text);
+        return;
+    }
+    if (!createExclusive(step.path, step.text)) {
+        throw new CommandError(`${step.path} already exists`, {
+            hint: 'init never overwrites a file. Move it, or run init in another folder.'
+        });
+    }
+}
+/** A commands path that exists as something other than a folder cannot become one. */
+function assertCommandsDirIsUsable(commandsDir) {
+    if (pathExists(commandsDir) && !isFolder(commandsDir)) {
+        throw new CommandError(`${commandsDir} exists but is not a folder`, {
+            hint: `Move it, or set "${CONFIG_KEY}": { "commandsDir" } in ${MANIFEST_FILE} to another folder.`
+        });
+    }
+}
+/** Whether the project already has a command or topic called `init`, which the init word would hide. */
+const shadowsInit = (commandsDir) => [`${INIT_WORD}.js`, INIT_WORD].some((name) => pathExists(path.join(commandsDir, name)));
+/**
+ * Makes `dir` a project: reads what is there once, plans, and does it. Running it again changes
+ * nothing. A package.json that cannot be read or parsed is an error: editing it would be guesswork.
+ */
+export const initProject = (dir) => {
+    const read = readManifest(dir);
+    if (read && 'error' in read) {
+        throw read.error;
+    }
+    const manifest = read?.manifest;
+    const commandsDir = manifest
+        ? resolveSettings({ root: dir, manifest }, 'shipped').commandsDir
+        : path.join(dir, DEFAULT_COMMANDS_FOLDER);
+    assertCommandsDirIsUsable(commandsDir);
+    const commandsDirExists = isFolder(commandsDir);
+    const plan = planInit({
+        dir,
+        manifest,
+        manifestText: read?.text,
+        commandsDir,
+        commandsDirExists,
+        commandsDirIsEmpty: commandsDirExists && listDirectory(commandsDir).length === 0,
+        shadowsCommand: shadowsInit(commandsDir)
+    });
+    plan.steps.forEach(applyStep);
+    return {
+        root: dir,
+        created: plan.steps.map((step) => step.path),
+        kept: plan.kept,
+        warnings: plan.warnings
+    };
+};

package/dist/cli/launch.d.ts

@@ -0,0 +1,10 @@
+import type { CliFn } from '../models.js';
+/**
+ * Finds the project and runs the command line against its commands folder. Returns the exit code
+ * and never calls process.exit.
+ *
+ * With `root` (a project's own bin file: `cli({ root: import.meta.url })`) the project is the one
+ * the bin file belongs to, wherever the user is standing. Without it (the shipped `art` and
+ * `artemis`) the project is the one of the current folder, or of `cwd`.
+ */
+export declare const launch: CliFn;

package/dist/cli/launch.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_KEY, DEFAULT_COMMANDS_FOLDER, MANIFEST_FILE, URL_LIKE } from '../constants.js';
+import { isFolder, readManifest } from '../edges/files.js';
+import { currentProcess } from '../edges/process.js';
+import { workingDirectory } from '../edges/system.js';
+import { CommandError } from '../errors/errors.js';
+import { reportError } from '../run/report.js';
+import { run } from '../run/run.js';
+import { resolveWorld } from '../run/world.js';
+import { messageOf } from '../utils/error-message.js';
+import { splitLeadingFlags } from '../resolve/resolve.js';
+import { jsonRequested } from '../utils/terminator.js';
+import { INIT_WORD } from './constants.js';
+import { initCommand } from './init-command.js';
+import { findProject, resolveSettings } from './settings.js';
+/** What `root` stands for as a path, or a CommandError that says what to pass instead. */
+function pathOfRoot(root) {
+    try {
+        if (typeof root === 'string' && root !== '' && !URL_LIKE.test(root)) {
+            return root;
+        }
+        return fileURLToPath(root);
+    }
+    catch (error) {
+        throw new CommandError(`cli({ root }) needs the location of your bin file, but got ${String(root)} (${messageOf(error)})`, {
+            hint: 'Pass import.meta.url from your bin file, or a path.'
+        });
+    }
+}
+/** The folder a bin file is in (`import.meta.url`), or the folder itself when given one. */
+const folderOfRoot = (root) => {
+    const target = pathOfRoot(root);
+    return isFolder(target) ? target : path.dirname(target);
+};
+/** What to do when no project is found: the end user can create one, the author of a tool must declare its bin. */
+const noProjectError = (start, route) => route === 'own'
+    ? new CommandError(`No ${MANIFEST_FILE} with a "bin" field found from ${start} upwards`, {
+        hint: `A published tool is found through the ${MANIFEST_FILE} that declares its "bin" (npm needs it to create the command anyway). If you maintain this tool, declare "bin" there and ship a ${DEFAULT_COMMANDS_FOLDER}/ folder in the package (see "files" in ${MANIFEST_FILE}).`
+    })
+    : new CommandError(`No project found from ${start} upwards`, {
+        hint: `A project is the nearest ${MANIFEST_FILE} with an "${CONFIG_KEY}" key or a ${DEFAULT_COMMANDS_FOLDER}/ folder next to it. Run it inside one, or use its "${INIT_WORD}" command in this folder to create one.`
+    });
+/** Whether the commands folder is already outside the project, so pointing it at a parent is no news. */
+const pointsOutside = (commandsDir, projectRoot) => {
+    const relative = path.relative(projectRoot, commandsDir);
+    return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+};
+/**
+ * The commands folder is missing. For a person running a project: create it, or point `commandsDir`
+ * at a parent's (unless it already points outside). For a published tool the end user cannot fix
+ * anything, so the hint is for its author, and never suggests running another package's commands.
+ */
+const missingCommandsError = (commandsDir, projectRoot, route) => {
+    const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+    const create = `Create ${commandsDir}, or set "${CONFIG_KEY}": { "commandsDir" } in ${manifestPath}.`;
+    const parent = ' If the commands live in a parent folder, point commandsDir at them, for example "../commands".';
+    const author = ` If this is a published tool, its author has to ship the commands folder (add it to "files" in ${MANIFEST_FILE}).`;
+    if (route === 'own') {
+        return new CommandError(`Commands folder not found: ${commandsDir}`, {
+            hint: create + author
+        });
+    }
+    return new CommandError(`Commands folder not found: ${commandsDir}`, {
+        hint: pointsOutside(commandsDir, projectRoot) ? create : create + parent
+    });
+};
+/** The project of a folder and where its commands are, or a CommandError that says what to create. */
+const settingsFor = (start, route) => {
+    // The messages name no binary: it is not known here what the user typed (art, artemis or a tool's name).
+    const project = findProject(start, readManifest, isFolder, route);
+    if (!project) {
+        throw noProjectError(start, route);
+    }
+    const settings = resolveSettings(project, route);
+    if (!isFolder(settings.commandsDir)) {
+        throw missingCommandsError(settings.commandsDir, project.root, route);
+    }
+    return settings;
+};
+/** A setup failure goes out the way any failure does: one object under --json, text otherwise. */
+function reportSetupFailure(argv, error, host) {
+    const { io, style } = resolveWorld(host);
+    return reportError(error, { io, style, json: jsonRequested(argv), commandId: undefined });
+}
+/**
+ * Finds the project and runs the command line against its commands folder. Returns the exit code
+ * and never calls process.exit.
+ *
+ * With `root` (a project's own bin file: `cli({ root: import.meta.url })`) the project is the one
+ * the bin file belongs to, wherever the user is standing. Without it (the shipped `art` and
+ * `artemis`) the project is the one of the current folder, or of `cwd`.
+ */
+export const launch = async (options = {}) => {
+    const { argv = currentProcess().args, cwd, root, ...host } = options;
+    const route = root === undefined ? 'shipped' : 'own';
+    const { leading, rest } = splitLeadingFlags(argv);
+    // `init` is the shipped binary's own word, like `help`: it has to work where there is no project yet.
+    if (route === 'shipped' && rest[0] === INIT_WORD) {
+        try {
+            return initCommand([...leading, ...rest.slice(1)], host, path.resolve(cwd ?? workingDirectory()));
+        }
+        catch (error) {
+            return reportSetupFailure(argv, error, host);
+        }
+    }
+    let settings;
+    try {
+        const start = path.resolve(root === undefined ? (cwd ?? workingDirectory()) : folderOfRoot(root));
+        settings = settingsFor(start, route);
+    }
+    catch (error) {
+        return reportSetupFailure(argv, error, host);
+    }
+    return run(argv, { ...host, ...settings });
+};

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `art` and `artemis` binary. Wiring only: the logic is in launch.ts, settings.ts and resolve-hook.ts.
+import { register } from 'node:module';
+import { launch } from './launch.js';
+// Command files import the framework by its package name; see resolve-hook.ts.
+register('./resolve-hook.js', import.meta.url);
+process.exitCode = await launch();

package/dist/cli/resolve-hook.d.ts

@@ -0,0 +1,9 @@
+import type { ResolveHookFn } from '../models.js';
+/**
+ * A command file imports the framework by its package name, but a globally installed `art` is not
+ * on the module path of a project's files. Normal resolution always goes first, so a copy the
+ * project installed itself wins. Only when that fails with "module not found" for this package (or
+ * one of its subpaths) is the name resolved from inside the running copy, so the project needs
+ * nothing installed. The `Symbol.for` tags keep definitions from two copies compatible.
+ */
+export declare const resolve: ResolveHookFn;

package/dist/cli/resolve-hook.js

@@ -0,0 +1,21 @@
+import { ERROR_CODE, PACKAGE_NAME } from '../constants.js';
+import { codeOf } from '../utils/error-code.js';
+const isOwnPackage = (specifier) => specifier === PACKAGE_NAME || specifier.startsWith(`${PACKAGE_NAME}/`);
+/**
+ * A command file imports the framework by its package name, but a globally installed `art` is not
+ * on the module path of a project's files. Normal resolution always goes first, so a copy the
+ * project installed itself wins. Only when that fails with "module not found" for this package (or
+ * one of its subpaths) is the name resolved from inside the running copy, so the project needs
+ * nothing installed. The `Symbol.for` tags keep definitions from two copies compatible.
+ */
+export const resolve = async (specifier, context, nextResolve) => {
+    try {
+        return await nextResolve(specifier, context);
+    }
+    catch (error) {
+        if (!isOwnPackage(specifier) || codeOf(error) !== ERROR_CODE.MODULE_NOT_FOUND) {
+            throw error;
+        }
+        return nextResolve(specifier, { ...context, parentURL: import.meta.url });
+    }
+};

package/dist/cli/settings.d.ts

@@ -0,0 +1,18 @@
+import type { FindProjectFn, ResolveBinNameFn, ResolveSettingsFn } from '../models.js';
+/**
+ * The project of a folder, looking in `cwd` and then each parent. Shipped route: the nearest
+ * package.json with an "artemis" key or a commands folder next to it. Own route (`cli({ root })`):
+ * the nearest one with the identity of a package (a name, a `bin` or an "artemis" key), and never
+ * past the folder of an installed package, so a tool cannot climb into the project that holds it,
+ * with or without a `bin`. A package.json that cannot be read or parsed is an error, never skipped.
+ * Pure: the disk is only looked at through the two edges.
+ */
+export declare const findProject: FindProjectFn;
+/**
+ * The name help and usage lines show. The shipped binary shows `"artemis".bin` or `art`, never the
+ * name of an unrelated CLI the project publishes; a project's own bin file also uses the name of
+ * its own `bin` field.
+ */
+export declare const resolveBinName: ResolveBinNameFn;
+/** The settings of a project: where its commands are (absolute) and what to call the CLI. */
+export declare const resolveSettings: ResolveSettingsFn;

package/dist/cli/settings.js

@@ -0,0 +1,110 @@
+import path from 'node:path';
+import { CONFIG_KEY, DEFAULT_BIN_NAME, DEFAULT_COMMANDS_FOLDER, MANIFEST_FILE, NODE_MODULES, SCOPE_FOLDER_PREFIX, SCOPE_PREFIX } from '../constants.js';
+import { CommandError } from '../errors/errors.js';
+import { isRecord } from '../utils/is-record.js';
+const VALID_SHAPE_HINT = `The key looks like "${CONFIG_KEY}": { "commandsDir": "commands", "bin": "mytool" }, and both fields are optional.`;
+const isNonEmptyText = (value) => typeof value === 'string' && value.length > 0;
+/**
+ * Shipped route: a package.json is the project when it declares itself, with an "artemis" key (what
+ * `init` writes), or follows the convention, with a commands folder next to it.
+ */
+const isProjectOfAPerson = (dir, manifest, isFolder) => manifest[CONFIG_KEY] !== undefined || isFolder(path.join(dir, DEFAULT_COMMANDS_FOLDER));
+/** Whether a package.json declares a `bin`: a string, or an object with at least one command. */
+const declaresBin = ({ bin }) => isRecord(bin) ? Object.keys(bin).length > 0 : isNonEmptyText(bin);
+/**
+ * Own route: a package.json says what a tool's package is when it has a name, declares a `bin`, or has
+ * an "artemis" key. The package.json files above a bin file are a marker or two in its own folders
+ * (no name, no bin, no key), then the tool's package, then the project that holds it, so the first of
+ * these is the tool's own, whether or not it declares a `bin`.
+ */
+const hasToolIdentity = (manifest) => isNonEmptyText(manifest.name) || declaresBin(manifest) || manifest[CONFIG_KEY] !== undefined;
+/** Whether a folder is the folder of a package installed by npm: `node_modules/pkg` or `node_modules/@scope/pkg`. */
+const isInstalledPackageRoot = (dir) => {
+    const parent = path.dirname(dir);
+    const container = path.basename(parent).startsWith(SCOPE_FOLDER_PREFIX)
+        ? path.dirname(parent)
+        : parent;
+    return path.basename(container) === NODE_MODULES;
+};
+const isTheProject = (dir, manifest, isFolder, route) => route === 'own' ? hasToolIdentity(manifest) : isProjectOfAPerson(dir, manifest, isFolder);
+function searchUpwards(dir, readManifest, isFolder, route) {
+    const read = readManifest(dir);
+    // Failing loudly beats silently running the commands of a different project.
+    if (read && 'error' in read) {
+        throw read.error;
+    }
+    if (read && isTheProject(dir, read.manifest, isFolder, route)) {
+        return { root: dir, manifest: read.manifest };
+    }
+    // A tool installed by npm is its own package whatever its package.json holds: never look past it.
+    if (route === 'own' && isInstalledPackageRoot(dir)) {
+        return read ? { root: dir, manifest: read.manifest } : undefined;
+    }
+    const parent = path.dirname(dir);
+    return parent === dir ? undefined : searchUpwards(parent, readManifest, isFolder, route);
+}
+/**
+ * The project of a folder, looking in `cwd` and then each parent. Shipped route: the nearest
+ * package.json with an "artemis" key or a commands folder next to it. Own route (`cli({ root })`):
+ * the nearest one with the identity of a package (a name, a `bin` or an "artemis" key), and never
+ * past the folder of an installed package, so a tool cannot climb into the project that holds it,
+ * with or without a `bin`. A package.json that cannot be read or parsed is an error, never skipped.
+ * Pure: the disk is only looked at through the two edges.
+ */
+export const findProject = (cwd, readManifest, isFolder, route) => searchUpwards(path.resolve(cwd), readManifest, isFolder, route);
+function invalidConfig(project, problem) {
+    const manifestPath = path.join(project.root, MANIFEST_FILE);
+    return new CommandError(`${problem} (in ${manifestPath})`, { hint: VALID_SHAPE_HINT });
+}
+/** The "artemis" key of the manifest, checked field by field. It is only read here. */
+function readConfig(project) {
+    const declared = project.manifest[CONFIG_KEY];
+    if (declared === undefined) {
+        return {};
+    }
+    if (!isRecord(declared)) {
+        throw invalidConfig(project, `"${CONFIG_KEY}" must be an object`);
+    }
+    for (const field of ['commandsDir', 'bin']) {
+        if (declared[field] !== undefined && !isNonEmptyText(declared[field])) {
+            throw invalidConfig(project, `"${CONFIG_KEY}".${field} must be a non-empty string`);
+        }
+    }
+    return declared;
+}
+/**
+ * The command a project's own bin file is known by: the single key of its `bin` object. When `bin`
+ * does not name one command (a string, or several keys) npm names it after the package, so that is
+ * the name, without its `@scope/`. A project with no `bin` at all has no name of its own.
+ */
+function ownBinName(manifest) {
+    const { bin, name } = manifest;
+    const keys = isRecord(bin) ? Object.keys(bin) : [];
+    const [only] = keys;
+    if (keys.length === 1) {
+        return only;
+    }
+    const namesNoSingleCommand = keys.length > 1 || isNonEmptyText(bin);
+    return namesNoSingleCommand && isNonEmptyText(name)
+        ? name.replace(SCOPE_PREFIX, '')
+        : undefined;
+}
+/**
+ * The name help and usage lines show. The shipped binary shows `"artemis".bin` or `art`, never the
+ * name of an unrelated CLI the project publishes; a project's own bin file also uses the name of
+ * its own `bin` field.
+ */
+export const resolveBinName = (config, manifest, route) => {
+    if (config.bin) {
+        return config.bin;
+    }
+    return (route === 'own' ? ownBinName(manifest) : undefined) ?? DEFAULT_BIN_NAME;
+};
+/** The settings of a project: where its commands are (absolute) and what to call the CLI. */
+export const resolveSettings = (project, route) => {
+    const config = readConfig(project);
+    return {
+        bin: resolveBinName(config, project.manifest, route),
+        commandsDir: path.resolve(project.root, config.commandsDir ?? DEFAULT_COMMANDS_FOLDER)
+    };
+};