@yaawn/workflow 0.3.1 → 0.5.0

package/dist/sync/uninstall.js

@@ -0,0 +1,234 @@
+import { readdir, realpath, rm, rmdir, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { contain, installedRenames, PROJECT_DIR } from "../config/index.js";
+import { containEntry, lstatIfExists, pathExists, readSortedDir, toDisplayPath } from "./fs-utils.js";
+/** The project-relative directory holding the user's plans; uninstall never removes it. */
+export const PLANS_DIR = ".yaawn/plans";
+/** A failed removal; result lists everything removed before the failure. There is no rollback. */
+export class UninstallError extends Error {
+    display;
+    result;
+    name = "UninstallError";
+    constructor(display, result, cause) {
+        super(`remove ${display}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.display = display;
+        this.result = result;
+    }
+}
+/** Every planned file entry in removal order: the settings file first, then the target entries. */
+export function uninstallEntries(plan) {
+    return [...plan.settings, ...plan.targets.flatMap((target) => target.entries)];
+}
+/** Reports whether no shipped file exists in the project. */
+export function isUninstallPlanEmpty(plan) {
+    return uninstallEntries(plan).length === 0;
+}
+/**
+ * Reports whether yaawn files are present. A planning error counts as not
+ * installed, so the install runs unchanged and reports the problem itself.
+ */
+export async function isYaawnInstalled(config, packageRoot, projectRoot) {
+    try {
+        return !isUninstallPlanEmpty(await planUninstall(config, packageRoot, projectRoot));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Lists the outermost prefixed entry of every path the package ships, per
+ * sync target, keeping only entries that exist in the project.
+ * Language-tagged files count regardless of the selection. It only reads
+ * the file system and fails when any destination escapes the project root.
+ */
+export async function planUninstall(config, packageRoot, projectRoot) {
+    const absoluteProject = path.resolve(projectRoot);
+    const planner = new UninstallPlanner(config, packageRoot, absoluteProject, await realpath(absoluteProject));
+    for (const [index, target] of config.tasks.syncTargets.entries()) {
+        await planner.planTarget(index, target);
+    }
+    return {
+        projectRoot: absoluteProject,
+        settings: await planSettings(config, absoluteProject),
+        targets: planner.targets,
+        keptPlans: await pathExists(contain(absoluteProject, PLANS_DIR)),
+    };
+}
+/** Lists the agent settings file when it exists as a file or link; a directory of that name is not ours and stays. */
+async function planSettings(config, projectRoot) {
+    const name = config.settings.settingsFileName;
+    const destination = path.join(contain(projectRoot, PROJECT_DIR), name);
+    const info = await lstatIfExists(destination);
+    if (info === undefined || info.isDirectory()) {
+        return [];
+    }
+    return [{ path: destination, display: path.posix.join(PROJECT_DIR, name), parentRelative: PROJECT_DIR, fileOnly: true }];
+}
+class UninstallPlanner {
+    config;
+    packageRoot;
+    projectRoot;
+    realProject;
+    targets = [];
+    seen = new Map();
+    constructor(config, packageRoot, projectRoot, realProject) {
+        this.config = config;
+        this.packageRoot = packageRoot;
+        this.projectRoot = projectRoot;
+        this.realProject = realProject;
+    }
+    async planTarget(index, target) {
+        this.targets.push({ target, targetDir: contain(this.projectRoot, target.target), entries: [] });
+        const sourceDir = contain(this.packageRoot, target.source);
+        if (!(await isDirectory(sourceDir))) {
+            return;
+        }
+        await this.walkPrefixed(index, target, sourceDir, "");
+        for (const name of installedRenames(target)) {
+            await this.addEntry(index, path.posix.join(target.target, name), true);
+        }
+    }
+    async walkPrefixed(index, target, sourceDir, relativeDir) {
+        const dir = relativeDir === "" ? sourceDir : path.join(sourceDir, ...relativeDir.split("/"));
+        for (const entry of (await readSortedDir(dir)) ?? []) {
+            await this.visit(index, target, sourceDir, path.posix.join(relativeDir, entry.name), entry);
+        }
+    }
+    async visit(index, target, sourceDir, relative, entry) {
+        if (!entry.name.startsWith(this.config.settings.filePrefix)) {
+            if (entry.isDirectory()) {
+                await this.walkPrefixed(index, target, sourceDir, relative);
+            }
+            return;
+        }
+        if (entry.isDirectory() || entry.isFile()) {
+            await this.addEntry(index, path.posix.join(target.target, relative), false);
+        }
+    }
+    /**
+     * Contains the entry's parent rather than the entry itself, so a
+     * symlinked entry is planned as the link, never as its target. The same
+     * file reached through a symlinked parent is listed once, preferring the
+     * path without symlinks.
+     */
+    async addEntry(index, relative, fileOnly) {
+        const parentRelative = path.posix.dirname(relative);
+        const destination = containEntry(this.projectRoot, relative);
+        const info = await lstatIfExists(destination);
+        if (info === undefined || (fileOnly && info.isDirectory())) {
+            return;
+        }
+        const realParent = await realpath(path.dirname(destination));
+        const key = path.join(realParent, path.posix.basename(relative));
+        const viaSymlink = realParent !== path.join(this.realProject, ...parentRelative.split("/"));
+        const entry = { path: destination, display: relative, parentRelative, fileOnly };
+        const previous = this.seen.get(key);
+        if (previous !== undefined) {
+            this.preferDirectPath(key, previous, entry, viaSymlink);
+            return;
+        }
+        const target = this.targets[index];
+        if (target === undefined) {
+            return;
+        }
+        this.seen.set(key, { target: index, index: target.entries.length, viaSymlink });
+        target.entries.push(entry);
+    }
+    preferDirectPath(key, previous, entry, viaSymlink) {
+        const entries = this.targets[previous.target]?.entries;
+        if (entries === undefined || !previous.viaSymlink || viaSymlink) {
+            return;
+        }
+        entries[previous.index] = entry;
+        this.seen.set(key, { ...previous, viaSymlink: false });
+    }
+}
+async function isDirectory(target) {
+    try {
+        return (await stat(target)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes the settings file and every planned target entry, pruning the
+ * directories it emptied below each target root. It stops at the first
+ * failure with an UninstallError listing what was removed so far.
+ */
+export async function applyUninstall(plan) {
+    const removed = [];
+    const pruned = [];
+    const resultSoFar = () => ({ removed, pruned, keptPlans: plan.keptPlans });
+    for (const entry of plan.settings) {
+        await attempt(entry.display, resultSoFar, async () => {
+            if (await removeEntry(plan.projectRoot, entry)) {
+                removed.push(entry.display);
+            }
+        });
+    }
+    for (const target of plan.targets) {
+        for (const entry of target.entries) {
+            await attempt(entry.display, resultSoFar, async () => {
+                if (await removeEntry(plan.projectRoot, entry)) {
+                    removed.push(entry.display);
+                }
+            });
+            await attempt(entry.display, resultSoFar, () => pruneEmptyDirs(plan.projectRoot, target.targetDir, path.dirname(entry.path), pruned));
+        }
+    }
+    return resultSoFar();
+}
+async function attempt(display, resultSoFar, action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        throw new UninstallError(display, resultSoFar(), error);
+    }
+}
+/**
+ * Re-checks containment right before removing and removes the entry
+ * itself: a symlink is unlinked, never followed. A directory that took the
+ * place of a file-only entry stays.
+ */
+async function removeEntry(projectRoot, entry) {
+    const destination = containEntry(projectRoot, path.posix.join(entry.parentRelative, path.basename(entry.path)));
+    const info = await lstatIfExists(destination);
+    if (info === undefined) {
+        return false;
+    }
+    if (info.isDirectory()) {
+        if (entry.fileOnly) {
+            return false;
+        }
+        await rm(destination, { recursive: true, force: true });
+        return true;
+    }
+    await unlink(destination);
+    return true;
+}
+/**
+ * Removes dir and its ancestors while they are empty real directories
+ * strictly inside targetDir. Only directories that contained a removed
+ * entry are visited, so directories empty before the run stay.
+ */
+async function pruneEmptyDirs(projectRoot, targetDir, startDir, pruned) {
+    let dir = startDir;
+    while (isStrictlyWithin(targetDir, dir)) {
+        const info = await lstatIfExists(dir);
+        if (info === undefined || !info.isDirectory() || (await readdir(dir)).length > 0) {
+            return;
+        }
+        await rmdir(dir);
+        pruned.push(toDisplayPath(projectRoot, dir));
+        dir = path.dirname(dir);
+    }
+}
+function isStrictlyWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    if (relative === "" || path.isAbsolute(relative)) {
+        return false;
+    }
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`);
+}

package/dist/wizard/build.js

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import { KIND_MULTISELECT, KIND_PROJECTS_LIST, KIND_SINGLE_SELECT, KIND_TEXT_LIST, } from "../config/index.js";
+import { formatFor, parseItems } from "./items.js";
+import { Section } from "./section.js";
+import { Wizard } from "./wizard.js";
+/**
+ * Creates the wizard from the configured sections in wizard.json order.
+ * The multiselect section is left out when there are no options; a
+ * text-list section is left out when its file is missing. The agent
+ * section preselects the requested agent, else the previous choice, else
+ * its configured default. The projects-list section is bound to no file.
+ */
+export function buildWizard(config, input) {
+    const sections = [];
+    const skipped = [];
+    for (const spec of config.wizard.sections) {
+        switch (spec.kind) {
+            case KIND_SINGLE_SELECT:
+                sections.push(newAgentSelect(spec, input));
+                break;
+            case KIND_PROJECTS_LIST:
+                sections.push(new Section(spec));
+                break;
+            case KIND_MULTISELECT:
+                if (input.languages.length > 0) {
+                    sections.push(new Section(spec, { options: input.languages }));
+                }
+                break;
+            case KIND_TEXT_LIST: {
+                const file = seededFileFor(config, spec, input.seededFiles);
+                if (file.content === undefined) {
+                    skipped.push({ id: spec.id, fileName: file.fileName, path: file.path });
+                }
+                else {
+                    sections.push(newTextList(spec, file.fileName, file.path, file.content));
+                }
+                break;
+            }
+        }
+    }
+    return { wizard: new Wizard(sections), skipped };
+}
+function newAgentSelect(spec, input) {
+    const options = spec.options.map((option) => ({ value: option.value, label: option.label, selected: false }));
+    const section = new Section(spec, { options });
+    section.setSelected([input.requestedAgent, input.previousAgent, spec.default]);
+    return section;
+}
+function newTextList(spec, fileName, path, content) {
+    const format = formatFor(spec.targetFile);
+    return new Section(spec, {
+        existing: parseItems(content, format),
+        file: { fileName, path, content, format },
+    });
+}
+function seededFileFor(config, spec, seededFiles) {
+    const missing = { fileName: config.outputFile(spec.targetFile)?.name ?? spec.targetFile, path: "", content: undefined };
+    return seededFiles.get(spec.targetFile) ?? missing;
+}
+/**
+ * Reads the output file of every text-list section from the project,
+ * falling back to the package's seed copy before the first sync. Paths
+ * are contained in their roots; read errors other than a missing file
+ * are thrown so the install fails closed.
+ */
+export function readSeededFiles(config, packageRoot, projectRoot) {
+    const files = new Map();
+    for (const spec of config.wizard.sections.filter((section) => section.kind === KIND_TEXT_LIST)) {
+        const output = config.outputFile(spec.targetFile);
+        if (output === undefined) {
+            continue;
+        }
+        const destination = output.destinationPath(projectRoot);
+        const content = readOptional(destination) ?? readOptional(output.sourcePath(packageRoot));
+        files.set(spec.targetFile, { fileName: output.name, path: destination, content });
+    }
+    return files;
+}
+function readOptional(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/dist/wizard/index.js

@@ -0,0 +1,5 @@
+export { buildWizard, readSeededFiles, } from "./build.js";
+export { appendItems, ChecklistFormat, CommandFormat, formatFor, normalize, parseItems, PlainFormat, } from "./items.js";
+export { clackPrompts, runWizard, } from "./prompts.js";
+export { ControlCharacterError, DuplicateItemError, EmptyItemError, Section, } from "./section.js";
+export { Wizard } from "./wizard.js";

package/dist/wizard/items.js

@@ -0,0 +1,83 @@
+const CHECKLIST_MARKER = "- [ ] ";
+const BULLET_MARKER = "- ";
+// The outputFileNames key whose items are commands rather than checklist tasks.
+const COMMANDS_FILE_KEY = "verificationCommands";
+// The outputFileNames key whose items are plain bullets rather than checklist tasks.
+const USER_ROLES_FILE_KEY = "userRoles";
+const BACKTICK_WRAPPED = /^`([^`]+)`$/;
+const WHITESPACE_RUN = /\s+/;
+/** Writes items as "- [ ] item". */
+export class ChecklistFormat {
+    parse(line) {
+        return line.startsWith(CHECKLIST_MARKER) ? line.slice(CHECKLIST_MARKER.length) : undefined;
+    }
+    format(item) {
+        return CHECKLIST_MARKER + item;
+    }
+}
+/** Writes items as "- `command`", unless the command contains a backtick itself. */
+export class CommandFormat {
+    parse(line) {
+        const item = parseBullet(line);
+        if (item === undefined) {
+            return undefined;
+        }
+        return BACKTICK_WRAPPED.exec(item)?.[1] ?? item;
+    }
+    format(command) {
+        return command.includes("`") ? BULLET_MARKER + command : `${BULLET_MARKER}\`${command}\``;
+    }
+}
+/** Writes items as "- item"; line breaks inside an item are collapsed so one item always stays one bullet. */
+export class PlainFormat {
+    parse(line) {
+        return parseBullet(line);
+    }
+    format(item) {
+        return BULLET_MARKER + collapseWhitespace(item);
+    }
+}
+function parseBullet(line) {
+    if (!line.startsWith(BULLET_MARKER)) {
+        return undefined;
+    }
+    const item = line.slice(BULLET_MARKER.length).trim();
+    return item === "" ? undefined : item;
+}
+function collapseWhitespace(text) {
+    return text
+        .split(WHITESPACE_RUN)
+        .filter((word) => word !== "")
+        .join(" ");
+}
+/** The list format of the output file registered under the given outputFileNames key. */
+export function formatFor(targetFile) {
+    switch (targetFile) {
+        case COMMANDS_FILE_KEY:
+            return new CommandFormat();
+        case USER_ROLES_FILE_KEY:
+            return new PlainFormat();
+        default:
+            return new ChecklistFormat();
+    }
+}
+/** The list items found in content. */
+export function parseItems(content, format) {
+    return content
+        .split("\n")
+        .map((line) => format.parse(line.endsWith("\r") ? line.slice(0, -1) : line))
+        .filter((item) => item !== undefined);
+}
+/** content with the formatted items appended, one per line, ending in a newline; unchanged without items. */
+export function appendItems(content, items, format) {
+    if (items.length === 0) {
+        return content;
+    }
+    const separator = content.endsWith("\n") ? "" : "\n";
+    const lines = items.map((item) => `${format.format(item)}\n`).join("");
+    return content + separator + lines;
+}
+/** The comparison key of an item: backticks removed, surrounding whitespace trimmed, lowercased. */
+export function normalize(item) {
+    return item.replaceAll("`", "").trim().toLowerCase();
+}

package/dist/wizard/prompts.js

@@ -0,0 +1,167 @@
+import process from "node:process";
+import { isCancel, log, multiselect, select, text } from "@clack/prompts";
+import { fill, isAgent } from "../config/index.js";
+import { sanitize } from "../display/index.js";
+/** Throws the same error the guard recognises as a Ctrl+C cancellation. */
+function cancelled() {
+    return Object.assign(new Error("cancelled"), { name: "ExitPromptError" });
+}
+function toClackOptions(choices) {
+    return choices.map((choice) => ({ value: choice.value, label: sanitize(choice.name) }));
+}
+/** Adapts the wizard's boolean|string validator to clack's string|undefined validator. */
+function adaptValidate(validate) {
+    if (validate === undefined) {
+        return undefined;
+    }
+    return async (value) => {
+        if (value === undefined) {
+            return undefined;
+        }
+        const verdict = await validate(value);
+        if (verdict === true) {
+            return undefined;
+        }
+        return typeof verdict === "string" ? verdict : "Invalid input";
+    };
+}
+function streams(context) {
+    return {
+        input: context?.input,
+        output: context?.output,
+    };
+}
+export const clackPrompts = {
+    async select(config, context) {
+        const result = await select({
+            message: sanitize(config.message),
+            options: toClackOptions(config.choices),
+            initialValue: config.default,
+            ...streams(context),
+        });
+        if (isCancel(result)) {
+            throw cancelled();
+        }
+        return result;
+    },
+    async input(config, context) {
+        const result = await text({
+            message: sanitize(config.message),
+            validate: adaptValidate(config.validate),
+            ...streams(context),
+        });
+        if (isCancel(result)) {
+            throw cancelled();
+        }
+        return result;
+    },
+    async checkbox(config, context) {
+        const result = await multiselect({
+            message: sanitize(config.message),
+            options: config.choices.map((choice) => ({
+                value: choice.value,
+                label: sanitize(choice.name),
+            })),
+            initialValues: config.choices.filter((choice) => choice.checked).map((choice) => choice.value),
+            ...streams(context),
+        });
+        if (isCancel(result)) {
+            throw cancelled();
+        }
+        return result;
+    },
+};
+// No wizard.json message exists for this rejection.
+const CONTROL_CHARACTER_MESSAGE = "Remove the control characters from the item.";
+const ITEM_INDENT = "  ";
+/**
+ * Asks one prompt per section in wizard.json order and returns what was
+ * chosen. Nothing is written; Ctrl+C rejects with an ExitPromptError,
+ * which is passed on unchanged.
+ */
+export async function runWizard(wizard, options) {
+    const session = new PromptSession(options.messages, options.prompts ?? clackPrompts, options.context ?? {});
+    const total = wizard.sections.length;
+    for (const [index, section] of wizard.sections.entries()) {
+        await session.ask(section, index + 1, total);
+    }
+    return wizard.result(options.fallback);
+}
+class PromptSession {
+    messages;
+    prompts;
+    context;
+    output;
+    constructor(messages, prompts, context) {
+        this.messages = messages;
+        this.prompts = prompts;
+        this.context = context;
+        this.output = (context.output ?? process.stdout);
+    }
+    async ask(section, step, total) {
+        this.printHeading(section, step, total);
+        if (section.isSingleSelect()) {
+            await this.askAgent(section);
+        }
+        else if (section.isMultiselect()) {
+            await this.askLanguages(section);
+        }
+        else {
+            await this.askItems(section);
+        }
+    }
+    async askAgent(section) {
+        const choices = section.options.map((option) => ({ value: option.value, name: sanitize(option.label) }));
+        const agent = await this.prompts.select({ message: sanitize(section.title), choices, default: section.selectedValue() }, this.context);
+        if (isAgent(agent)) {
+            section.setSelected([agent]);
+        }
+    }
+    async askLanguages(section) {
+        const choices = section.options.map((option) => ({
+            value: option.value,
+            name: sanitize(option.label),
+            checked: option.selected,
+        }));
+        const selected = await this.prompts.checkbox({ message: sanitize(section.title), choices }, this.context);
+        section.setSelected(selected);
+    }
+    /** Asks for items until an empty submit; duplicates and control characters are rejected in the prompt. */
+    async askItems(section) {
+        this.printItems(section.existing);
+        const validate = (value) => this.validateItem(section, value);
+        for (;;) {
+            const value = await this.prompts.input({ message: sanitize(section.title), validate }, this.context);
+            if (section.checkItem(value).status === "empty") {
+                return;
+            }
+            section.add(value);
+        }
+    }
+    validateItem(section, value) {
+        const check = section.checkItem(value);
+        switch (check.status) {
+            case "duplicate":
+                return fill(this.messages.duplicateItem, { item: sanitize(check.item) });
+            case "control-character":
+                return CONTROL_CHARACTER_MESSAGE;
+            default:
+                return true;
+        }
+    }
+    printHeading(section, step, total) {
+        log.message("", { output: this.output });
+        log.step(`${step}/${total} ${sanitize(section.title)}`, { output: this.output });
+        log.message(sanitize(section.description), { output: this.output });
+    }
+    printItems(items) {
+        if (items.length === 0) {
+            log.message(sanitize(this.messages.noItems), { output: this.output });
+        }
+        else {
+            log.message(sanitize(this.messages.currentItems), { output: this.output });
+            items.forEach((item) => log.message(ITEM_INDENT + sanitize(item), { output: this.output }));
+        }
+        log.message(sanitize(this.messages.emptySubmit), { output: this.output });
+    }
+}