@yaawn/workflow 0.3.1 → 0.5.0

package/dist/cli/main.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { installProcessSafetyNet } from "./errors.js";
+import { run } from "./run.js";
+import { isInteractive } from "./terminal.js";
+installProcessSafetyNet(process.stderr);
+void run(process.argv.slice(2), {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    env: process.env,
+    cwd: () => process.cwd(),
+    isTTY: () => isInteractive(process),
+    entryUrl: import.meta.url,
+}).then((code) => {
+    process.exitCode = code;
+});

package/dist/cli/package-root.js

@@ -0,0 +1,17 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** This file compiles to dist/cli/, two levels below the package root. */
+const compiledDirToPackageRoot = "../../";
+/**
+ * Returns the package root, which holds config/, agents/, yaawn/, github/
+ * and package.json: the --package-root value when given, kept for
+ * compatibility with the old launcher, else the directory two levels above
+ * the compiled entry. Returns undefined when --package-root was given
+ * without a value.
+ */
+export function resolvePackageRoot(flagValue, entryUrl = import.meta.url) {
+    if (flagValue !== undefined) {
+        return flagValue === "" ? undefined : path.resolve(flagValue);
+    }
+    return fileURLToPath(new URL(compiledDirToPackageRoot, entryUrl));
+}

package/dist/cli/project-root.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+import process from "node:process";
+const PROJECT_ROOT_ENV = "INIT_CWD";
+/**
+ * Prefers INIT_CWD, which npm sets to the directory npx was started in,
+ * over the working directory.
+ */
+export function resolveProjectRoot(env = process.env, workingDirectory = process.cwd()) {
+    const initCwd = env[PROJECT_ROOT_ENV];
+    return path.resolve(initCwd !== undefined && initCwd !== "" ? initCwd : workingDirectory);
+}

package/dist/cli/run.js

@@ -0,0 +1,141 @@
+import { agents, fill, loadConfig, readPackageVersion } from "../config/index.js";
+import { MODE_UNINSTALL, Renderer } from "../display/index.js";
+import { clackPrompts } from "../wizard/index.js";
+import { parseArgs } from "./args.js";
+import { describeError, detailTemplates, fallbackMissingPackageRoot, isPromptCancellation, printError, runWithSafetyNet, templatesFrom, } from "./errors.js";
+import { EXIT_ERROR, EXIT_INTERRUPTED, EXIT_OK } from "./exit-codes.js";
+import { Installer } from "./install.js";
+import { resolvePackageRoot } from "./package-root.js";
+import { resolveProjectRoot } from "./project-root.js";
+import { Uninstaller } from "./uninstall.js";
+import { helpText, versionText } from "./version.js";
+/**
+ * Runs the installer with args (without the program name) and returns the
+ * exit code: 0 on success, 1 on any failure, 130 when cancelled. The
+ * config is loaded and validated, and a terminal required, before
+ * anything is written; an escaped error becomes one sanitized stderr line.
+ */
+export function run(args, deps) {
+    return runWithSafetyNet(deps.stderr, () => runChecked(parseArgs(args), deps));
+}
+async function runChecked(options, deps) {
+    const packageRoot = resolvePackageRoot(options.packageRoot, deps.entryUrl);
+    if (packageRoot === undefined) {
+        printError(deps.stderr, fallbackMissingPackageRoot);
+        return EXIT_ERROR;
+    }
+    const config = loadConfig(packageRoot);
+    const messages = config.wizard.messages;
+    const templates = templatesFrom(messages);
+    const version = readVersion(packageRoot, templates, deps.stderr);
+    if (version === undefined) {
+        return EXIT_ERROR;
+    }
+    const early = earlyExit(options, messages, version, deps);
+    if (early !== undefined) {
+        return early;
+    }
+    const createUi = deps.createUi ?? createRenderer;
+    const session = {
+        config,
+        packageRoot,
+        projectRoot: resolveProjectRoot(deps.env, deps.cwd()),
+        version,
+        ui: createUi(messages, config.settings.brandColor, deps.stdout),
+        templates,
+    };
+    const wizardPrompts = {
+        prompts: deps.prompts ?? clackPrompts,
+        context: { input: deps.stdin, output: deps.stdout },
+    };
+    return new Dispatcher(session, wizardPrompts, deps.stderr).dispatch(options);
+}
+function createRenderer(messages, brandColor, output) {
+    return new Renderer(messages, brandColor, output);
+}
+function readVersion(packageRoot, templates, stderr) {
+    try {
+        return readPackageVersion(packageRoot);
+    }
+    catch (error) {
+        printError(stderr, describeError(templates, error));
+        return undefined;
+    }
+}
+/** Handles the runs that end before any flow starts: a removed flag, invalid --agent, help, version and the missing terminal. */
+function earlyExit(options, messages, version, deps) {
+    if (options.removedFlag !== undefined) {
+        printError(deps.stderr, removedFlagMessage(options.removedFlag));
+        return EXIT_ERROR;
+    }
+    if (options.invalidAgent) {
+        printError(deps.stderr, fill(messages.invalidAgent, { agents: agents().join(", ") }));
+        return EXIT_ERROR;
+    }
+    if (options.help) {
+        deps.stdout.write(`${helpText(messages, version)}\n`);
+        return EXIT_OK;
+    }
+    if (options.version) {
+        deps.stdout.write(`${versionText(messages, version)}\n`);
+        return EXIT_OK;
+    }
+    if (!deps.isTTY()) {
+        printError(deps.stderr, options.uninstall ? messages.uninstallNoTerminal : messages.noTerminal);
+        return EXIT_ERROR;
+    }
+    return undefined;
+}
+function removedFlagMessage(flag) {
+    return `workflow: unknown option ${flag} — the installer is interactive only and needs a terminal`;
+}
+/**
+ * Runs the uninstall when asked for by --uninstall or, for a project that
+ * has yaawn installed, by the mode menu; every other run installs.
+ */
+class Dispatcher {
+    session;
+    wizardPrompts;
+    stderr;
+    constructor(session, wizardPrompts, stderr) {
+        this.session = session;
+        this.wizardPrompts = wizardPrompts;
+        this.stderr = stderr;
+    }
+    async dispatch(options) {
+        const uninstaller = new Uninstaller(this.session);
+        if (options.uninstall) {
+            return this.guardUninstall(async () => uninstaller.run(await uninstaller.plan()));
+        }
+        const installed = await uninstaller.findInstalled();
+        if (installed !== undefined) {
+            const uninstalled = await this.guardUninstall(async () => (await this.session.ui.chooseMode()) === MODE_UNINSTALL ? uninstaller.run(installed) : undefined);
+            if (uninstalled !== undefined) {
+                return uninstalled;
+            }
+        }
+        return this.guardInstall(() => new Installer(this.session, this.wizardPrompts, options.agent).run());
+    }
+    guardInstall(action) {
+        const messages = this.session.config.wizard.messages;
+        return this.guard(action, messages.installCancelled, (error) => describeError(this.session.templates, error));
+    }
+    guardUninstall(action) {
+        const messages = this.session.config.wizard.messages;
+        return this.guard(action, messages.uninstallCancelled, (error) => fill(messages.uninstallFailed, { error: describeError(detailTemplates(this.session.templates), error) }));
+    }
+    /** Ctrl+C at a prompt prints cancelledText and exits 130; any other error prints one described line and exits 1. */
+    async guard(action, cancelledText, describe) {
+        try {
+            return await action();
+        }
+        catch (error) {
+            if (isPromptCancellation(error)) {
+                printError(this.stderr, cancelledText);
+                return EXIT_INTERRUPTED;
+            }
+            printError(this.stderr, describe(error));
+            return EXIT_ERROR;
+        }
+    }
+}

package/dist/cli/session.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/terminal.js

@@ -0,0 +1,5 @@
+import process from "node:process";
+/** The installer is interactive only, so both ends must be a terminal. */
+export function isInteractive(streams = process) {
+    return streams.stdin.isTTY === true && streams.stdout.isTTY === true;
+}

package/dist/cli/uninstall.js

@@ -0,0 +1,89 @@
+import { fill, readPackageName } from "../config/index.js";
+import { failureReason, findInstalledLinks, KIND_IMPORTS, removeLinks } from "../link/index.js";
+import { applyUninstall, planUninstall, uninstallEntries, UninstallError } from "../sync/index.js";
+import { describeError, detailTemplates } from "./errors.js";
+import { EXIT_ERROR, EXIT_INTERRUPTED, EXIT_OK } from "./exit-codes.js";
+const FAILURE_SEPARATOR = "; ";
+/**
+ * Runs one uninstall: list everything yaawn installed, ask with "No"
+ * preselected, then remove the agent links first — trying every one —
+ * and the files after them. Nothing is removed without confirmation.
+ */
+export class Uninstaller {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /** Lists the links and files to remove; it only reads the file system. */
+    async plan() {
+        const { config, packageRoot, projectRoot } = this.session;
+        return {
+            links: await findInstalledLinks(projectRoot),
+            files: await planUninstall(config, packageRoot, projectRoot),
+        };
+    }
+    /**
+     * Returns the targets when yaawn is installed. A planning error counts
+     * as not installed, so the install runs unchanged and reports the
+     * problem itself.
+     */
+    async findInstalled() {
+        try {
+            const targets = await this.plan();
+            return this.entries(targets).length > 0 ? targets : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async run(targets) {
+        const { packageRoot, ui } = this.session;
+        const packageName = readPackageName(packageRoot);
+        const entries = this.entries(targets);
+        if (entries.length === 0) {
+            ui.nothingToRemove(packageName);
+            return EXIT_OK;
+        }
+        if (!(await ui.confirmUninstall(entries))) {
+            ui.uninstallCancelled();
+            return EXIT_INTERRUPTED;
+        }
+        const outcome = await ui.uninstalling(() => this.remove(targets));
+        ui.uninstallSummary({ ...outcome, packageName });
+        return outcome.failure === undefined ? EXIT_OK : EXIT_ERROR;
+    }
+    /** The entries shown before asking, in removal order. */
+    entries(targets) {
+        return [
+            ...targets.links.map((entry) => this.linkDisplay(entry)),
+            ...uninstallEntries(targets.files).map((entry) => entry.display),
+        ];
+    }
+    async remove(targets) {
+        const links = await removeLinks(this.session.projectRoot, targets.links);
+        const linkFailures = links.failures.map(({ entry, error }) => `remove ${this.linkDisplay(entry)}: ${failureReason(error)}`);
+        const files = await this.removeFiles(targets.files);
+        const failures = files.failure === undefined ? linkFailures : [...linkFailures, files.failure];
+        const summary = {
+            removed: [...links.removed.map((entry) => this.linkDisplay(entry)), ...files.summary.removed],
+            pruned: files.summary.pruned,
+            keptPlans: files.summary.keptPlans,
+        };
+        return failures.length === 0 ? { summary } : { summary, failure: failures.join(FAILURE_SEPARATOR) };
+    }
+    /** Stops at the first failure; the outcome lists what was removed before it. There is no rollback. */
+    async removeFiles(plan) {
+        try {
+            return { summary: await applyUninstall(plan) };
+        }
+        catch (error) {
+            const summary = error instanceof UninstallError ? error.result : { removed: [], pruned: [], keptPlans: plan.keptPlans };
+            return { summary, failure: describeError(detailTemplates(this.session.templates), error) };
+        }
+    }
+    linkDisplay(entry) {
+        return entry.kind === KIND_IMPORTS
+            ? fill(this.session.config.wizard.messages.uninstallImportsEntry, { path: entry.path })
+            : entry.path;
+    }
+}

package/dist/cli/version.js

@@ -0,0 +1,7 @@
+import { fill } from "../config/index.js";
+export function helpText(messages, version) {
+    return fill(messages.help, { version });
+}
+export function versionText(messages, version) {
+    return fill(messages.version, { version });
+}

package/dist/config/agents.js

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { UnknownAgentError } from "./errors.js";
+/**
+ * Coding agents the installer can set up. They are the only values
+ * accepted for --agent, the wizard's single-select section and the
+ * project's settings file.
+ */
+export const AGENT_COPILOT = "copilot";
+export const AGENT_CLAUDE = "claude";
+export const AGENT_VIBE = "vibe";
+const AGENTS = [AGENT_COPILOT, AGENT_CLAUDE, AGENT_VIBE];
+export const DEFAULT_AGENT = AGENT_COPILOT;
+/** yaawn's runtime directory inside the project; the settings file lives there. */
+export const PROJECT_DIR = ".yaawn";
+/** Caps how much of the settings file is read, so a huge file cannot exhaust memory. */
+export const MAX_SETTINGS_SIZE = 64 * 1024;
+const SETTINGS_DIR_MODE = 0o755;
+const SETTINGS_FILE_MODE = 0o644;
+/** Returns the allowed coding agents in display order. */
+export function agents() {
+    return [...AGENTS];
+}
+export function isAgent(value) {
+    return typeof value === "string" && AGENTS.includes(value);
+}
+/**
+ * Returns the agent saved in the settings file at filePath, or undefined
+ * when the file is missing, not a regular file, oversized, unparsable or
+ * names an agent outside the allow-list, so callers fall back safely.
+ */
+export function readAgentSetting(filePath) {
+    const text = readBoundedText(filePath);
+    if (text === undefined) {
+        return undefined;
+    }
+    const agent = parseAgent(text);
+    return isAgent(agent) ? agent : undefined;
+}
+function readBoundedText(filePath) {
+    try {
+        if (!fs.statSync(filePath).isFile()) {
+            return undefined;
+        }
+        const buffer = readAtMost(filePath, MAX_SETTINGS_SIZE + 1);
+        return buffer.length > MAX_SETTINGS_SIZE ? undefined : buffer.toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function readAtMost(filePath, limit) {
+    const buffer = Buffer.alloc(limit);
+    const descriptor = fs.openSync(filePath, "r");
+    try {
+        let total = 0;
+        let bytesRead = -1;
+        while (total < limit && bytesRead !== 0) {
+            bytesRead = fs.readSync(descriptor, buffer, total, limit - total, null);
+            total += bytesRead;
+        }
+        return buffer.subarray(0, total);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function parseAgent(text) {
+    try {
+        const settings = JSON.parse(text);
+        if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+            return undefined;
+        }
+        return Object.hasOwn(settings, "agent") ? settings.agent : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Writes {"agent":"<agent>"} to filePath, creating its directory. The
+ * content goes to a sibling temp file first and is renamed into place,
+ * so a crash never leaves a half-written settings file. The caller must
+ * have contained filePath inside the project.
+ */
+export function writeAgentSetting(filePath, agent) {
+    if (!isAgent(agent)) {
+        throw new UnknownAgentError(agent);
+    }
+    createSettingsDir(filePath);
+    writeFileAtomically(filePath, `${JSON.stringify({ agent })}\n`);
+}
+/** Creates the directory that holds the settings file at filePath. */
+export function createSettingsDir(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: SETTINGS_DIR_MODE });
+}
+function writeFileAtomically(filePath, content) {
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tempPath, content, { flag: "wx", mode: SETTINGS_FILE_MODE });
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        fs.rmSync(tempPath, { force: true });
+        throw error;
+    }
+}

package/dist/config/config.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { createSettingsDir, DEFAULT_AGENT, isAgent, PROJECT_DIR, readAgentSetting, writeAgentSetting, } from "./agents.js";
+import { UnknownAgentError } from "./errors.js";
+import { contain } from "./paths.js";
+import { decodeSettings, SETTINGS_FILE, settingsError, validateSettings } from "./settings.js";
+import { readJsonDocument, sortedKeys } from "./strict-json.js";
+import { decodeInstallTasks, INSTALL_TASKS_FILE, isSeedOnly, validateInstallTasks } from "./tasks.js";
+import { decodeWizard, singleSelectSection, validateWizard, WIZARD_FILE } from "./wizard.js";
+/** The config directory inside the package root. */
+export const CONFIG_DIR = "config";
+/** A file the wizard appends to: seeded by a sync target and owned by the user afterwards. */
+export class OutputFile {
+    key;
+    name;
+    target;
+    constructor(key, name, target) {
+        this.key = key;
+        this.name = name;
+        this.target = target;
+    }
+    /** The seed copy of the file inside the package. */
+    sourcePath(packageRoot) {
+        return contain(packageRoot, this.target.source, this.name);
+    }
+    /** The file inside the project. */
+    destinationPath(projectRoot) {
+        return contain(projectRoot, this.target.target, this.name);
+    }
+    /** The project-relative, slash-separated path. */
+    displayPath() {
+        return path.posix.join(this.target.target, this.name);
+    }
+}
+/** The three validated config files. */
+export class Config {
+    settings;
+    wizard;
+    tasks;
+    constructor(settings, wizard, tasks) {
+        this.settings = settings;
+        this.wizard = wizard;
+        this.tasks = tasks;
+    }
+    /** Looks up the output file registered under key. */
+    outputFile(key) {
+        if (!Object.hasOwn(this.settings.outputFileNames, key)) {
+            return undefined;
+        }
+        const name = this.settings.outputFileNames[key] ?? "";
+        const target = this.tasks.syncTargets.find((candidate) => isSeedOnly(candidate, name));
+        return target === undefined ? undefined : new OutputFile(key, name, target);
+    }
+    /** The output file names; the sync never deletes them even when a removeFirst pattern matches. */
+    userOwnedFiles() {
+        return sortedKeys(this.settings.outputFileNames).map((key) => this.settings.outputFileNames[key] ?? key);
+    }
+    /** The settings file inside projectRoot; throws PathEscapeError when it would escape. */
+    agentSettingsPath(projectRoot) {
+        return contain(projectRoot, PROJECT_DIR, this.settings.settingsFileName);
+    }
+    /** The agent saved in the project's settings file; undefined whenever it cannot be read safely. */
+    previousAgent(projectRoot) {
+        try {
+            return readAgentSetting(this.agentSettingsPath(projectRoot));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** requested when it is an allowed agent, else the project's previous choice, else the default agent. */
+    resolveAgent(projectRoot, requested) {
+        if (isAgent(requested)) {
+            return requested;
+        }
+        return this.previousAgent(projectRoot) ?? this.agentDefault();
+    }
+    /**
+     * Writes agent to the project's settings file, creating .yaawn/ when
+     * missing. The path is contained before and after the directory is
+     * created, so a symlink planted on the way cannot redirect the write.
+     */
+    saveAgent(projectRoot, agent) {
+        if (!isAgent(agent)) {
+            throw new UnknownAgentError(agent);
+        }
+        createSettingsDir(this.agentSettingsPath(projectRoot));
+        writeAgentSetting(this.agentSettingsPath(projectRoot), agent);
+    }
+    /** The default of the single-select section, or DEFAULT_AGENT without one. */
+    agentDefault() {
+        const fallback = singleSelectSection(this.wizard)?.default;
+        return isAgent(fallback) ? fallback : DEFAULT_AGENT;
+    }
+}
+/** Reads and validates settings.json, wizard.json and install-tasks.json from the config directory of packageRoot. */
+export function loadConfig(packageRoot) {
+    const dir = contain(packageRoot, CONFIG_DIR);
+    const settings = decodeSettings(readJsonDocument(contain(dir, SETTINGS_FILE), SETTINGS_FILE));
+    const wizard = decodeWizard(readJsonDocument(contain(dir, WIZARD_FILE), WIZARD_FILE));
+    const tasks = decodeInstallTasks(readJsonDocument(contain(dir, INSTALL_TASKS_FILE), INSTALL_TASKS_FILE));
+    return createConfig(settings, wizard, tasks);
+}
+/** Validates the three config parts, including the references between them. */
+export function createConfig(settingsDocument, wizard, tasks) {
+    const settings = validateSettings(settingsDocument);
+    validateWizard(wizard, settings);
+    validateInstallTasks(tasks, settings.filePrefix);
+    const config = new Config(settings, wizard, tasks);
+    validateOutputFiles(config);
+    return config;
+}
+/** Requires every output file to be seed-only in a sync target, so it has a known location and is never deleted. */
+function validateOutputFiles(config) {
+    const unseeded = sortedKeys(config.settings.outputFileNames).find((key) => config.outputFile(key) === undefined);
+    if (unseeded !== undefined) {
+        throw settingsError(`outputFileNames.${unseeded}`, `must be listed in a syncTargets seedOnly array of ${INSTALL_TASKS_FILE}`);
+    }
+}

package/dist/config/errors.js

@@ -0,0 +1,45 @@
+/** A config value that breaks the schema, named by file and field path. */
+export class ValidationError extends Error {
+    file;
+    field;
+    problem;
+    name = "ValidationError";
+    constructor(file, field, problem) {
+        super(`${file}: ${field} ${problem}`);
+        this.file = file;
+        this.field = field;
+        this.problem = problem;
+    }
+}
+/** A config file that could not be read. */
+export class LoadError extends Error {
+    file;
+    name = "LoadError";
+    constructor(file, cause) {
+        super(`${file}: ${describeCause(cause)}`, { cause });
+        this.file = file;
+    }
+}
+/** A path that resolves outside its root, directly or through a symlink. */
+export class PathEscapeError extends Error {
+    path;
+    root;
+    name = "PathEscapeError";
+    constructor(path, root) {
+        super(`path ${path} escapes ${root}`);
+        this.path = path;
+        this.root = root;
+    }
+}
+/** An agent outside the allow-list of coding agents. */
+export class UnknownAgentError extends Error {
+    agent;
+    name = "UnknownAgentError";
+    constructor(agent) {
+        super("unknown coding agent");
+        this.agent = agent;
+    }
+}
+function describeCause(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/config/index.js

@@ -0,0 +1,11 @@
+export { AGENT_CLAUDE, AGENT_COPILOT, AGENT_VIBE, DEFAULT_AGENT, MAX_SETTINGS_SIZE, PROJECT_DIR, agents, isAgent, readAgentSetting, writeAgentSetting, } from "./agents.js";
+export { CONFIG_DIR, Config, OutputFile, createConfig, loadConfig } from "./config.js";
+export { LoadError, PathEscapeError, UnknownAgentError, ValidationError } from "./errors.js";
+export { PACKAGE_MANIFEST, readPackageName, readPackageVersion } from "./manifest.js";
+export { fill } from "./messages.js";
+export { isFileName, isRelativeDir, removeDir } from "./names.js";
+export { contain } from "./paths.js";
+export { SETTINGS_FILE } from "./settings.js";
+export { DOCUMENT_FIELD } from "./strict-json.js";
+export { INSTALL_TASKS_FILE, installedName, installedRenames, isSeedOnly, } from "./tasks.js";
+export { KIND_MULTISELECT, KIND_PROJECTS_LIST, KIND_SINGLE_SELECT, KIND_TEXT_LIST, WIZARD_FILE, singleSelectSection, } from "./wizard.js";

package/dist/config/manifest.js

@@ -0,0 +1,28 @@
+import { ValidationError } from "./errors.js";
+import { contain } from "./paths.js";
+import { JsonLocation, readJsonDocument, readObject, readString } from "./strict-json.js";
+/** The package manifest inside the package root. */
+export const PACKAGE_MANIFEST = "package.json";
+const VERSION_PATTERN = /^[0-9A-Za-z.+-]+$/;
+const PACKAGE_NAME_PATTERN = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+/** Reads the version field of the package manifest. */
+export function readPackageVersion(packageRoot) {
+    return readManifestField(packageRoot, "version", VERSION_PATTERN);
+}
+/** Reads the name field of the package manifest; a missing name fails instead of guessing the npm uninstall command. */
+export function readPackageName(packageRoot) {
+    return readManifestField(packageRoot, "name", PACKAGE_NAME_PATTERN);
+}
+function readManifestField(packageRoot, key, pattern) {
+    const manifestPath = contain(packageRoot, PACKAGE_MANIFEST);
+    const at = new JsonLocation(PACKAGE_MANIFEST);
+    const manifest = readObject(readJsonDocument(manifestPath, PACKAGE_MANIFEST), at);
+    const value = Object.hasOwn(manifest, key) ? readString(manifest[key], at.key(key)) : "";
+    if (value === "") {
+        throw new ValidationError(PACKAGE_MANIFEST, key, "is required");
+    }
+    if (!pattern.test(value)) {
+        throw new ValidationError(PACKAGE_MANIFEST, key, "has an invalid format");
+    }
+    return value;
+}