@yaawn/workflow 0.4.0 → 0.5.0

package/dist/sync/index.js

@@ -0,0 +1,7 @@
+export { applySync, SyncApplyError } from "./apply.js";
+export { planFileChanges, writeFileChanges, } from "./changes.js";
+export { applyInstall, InstallError, planInstall, } from "./install.js";
+export { allLanguageTags, detectLanguages, expandLanguages, installedLanguageTags, languageLabel, } from "./languages.js";
+export { planSync } from "./plan.js";
+export { captureProjects, findProjectsLine, mergeProjects, parseFlowList, } from "./projects.js";
+export { applyUninstall, isUninstallPlanEmpty, isYaawnInstalled, PLANS_DIR, planUninstall, uninstallEntries, UninstallError, } from "./uninstall.js";

package/dist/sync/install.js

@@ -0,0 +1,57 @@
+import { applySync, SyncApplyError } from "./apply.js";
+import { planFileChanges, writeFileChanges } from "./changes.js";
+import { planSync } from "./plan.js";
+import { captureProjects, mergeProjects } from "./projects.js";
+/** A failed install step; result holds what was done before the failure. */
+export class InstallError extends Error {
+    stage;
+    result;
+    name = "InstallError";
+    constructor(stage, result, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.stage = stage;
+        this.result = result;
+    }
+}
+const NO_PROJECTS = { updated: [], skipped: [] };
+/**
+ * Captures the issue templates' project names, plans the sync and
+ * validates the wizard's file changes. It only reads, so any error here
+ * leaves the project untouched.
+ */
+export async function planInstall(config, packageRoot, projectRoot, input) {
+    return {
+        packageRoot,
+        projectRoot,
+        capture: await captureProjects(config, projectRoot),
+        sync: await planSync(config, packageRoot, projectRoot, input.languages),
+        changes: planFileChanges(projectRoot, input.changes),
+        projectNames: [...input.projectNames],
+    };
+}
+/**
+ * Syncs the payload, restores the issue templates' project names merged
+ * with the entered ones and writes the wizard changes, in that order.
+ * Stops at the first failure with an InstallError. Saving the agent and
+ * linking are left to the caller.
+ */
+export async function applyInstall(config, plan) {
+    const sync = await runStage("sync", () => applySync(plan.sync), (error) => syncSoFar(plan, error));
+    const projects = await runStage("projects", () => mergeProjects(config, plan.projectRoot, plan.capture, plan.projectNames), () => ({ sync, projects: NO_PROJECTS, changes: [] }));
+    const changes = await runStage("changes", () => writeFileChanges(plan.projectRoot, plan.changes), () => ({ sync, projects, changes: [] }));
+    return { sync, projects, changes };
+}
+async function runStage(stage, action, resultSoFar) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        throw new InstallError(stage, resultSoFar(error), error);
+    }
+}
+function syncSoFar(plan, error) {
+    const sync = error instanceof SyncApplyError
+        ? error.result
+        : { targets: [], languages: plan.sync.languages, hasLanguageFiles: plan.sync.hasLanguageFiles };
+    return { sync, projects: NO_PROJECTS, changes: [] };
+}

package/dist/sync/languages.js

@@ -0,0 +1,80 @@
+import { contain } from "../config/index.js";
+import { compareNames, pathExists, readSortedDir } from "./fs-utils.js";
+/**
+ * Collects the tagged files directly inside every target's
+ * languageInstructions directory. A language counts as installed when one
+ * of its files already exists in the project.
+ */
+export async function detectLanguages(config, packageRoot, projectRoot) {
+    const files = [];
+    const installed = new Set();
+    for (const target of config.tasks.syncTargets) {
+        const found = await targetLanguageFiles(config, target, packageRoot);
+        for (const file of found) {
+            if (await isLanguageFileInstalled(file, projectRoot)) {
+                installed.add(file.tag);
+            }
+        }
+        files.push(...found);
+    }
+    return { files, options: languageOptions(files, installed, config.settings.languageLabels) };
+}
+async function targetLanguageFiles(config, target, packageRoot) {
+    if (target.languageInstructions === undefined) {
+        return [];
+    }
+    const entries = await readSortedDir(contain(packageRoot, target.source, target.languageInstructions));
+    const files = [];
+    for (const entry of entries ?? []) {
+        const tag = languageTag(config, entry.name);
+        if (tag !== undefined && entry.isFile()) {
+            files.push({ target, name: entry.name, tag });
+        }
+    }
+    return files;
+}
+async function isLanguageFileInstalled(file, projectRoot) {
+    const destination = contain(projectRoot, file.target.target, file.target.languageInstructions ?? "", file.name);
+    return pathExists(destination);
+}
+/** The language tag captured from a file name, or undefined for untagged files. */
+export function languageTag(config, name) {
+    const match = config.settings.languageRegExp.exec(name);
+    const tag = match?.[1];
+    return tag === undefined || tag === "" ? undefined : tag;
+}
+function languageOptions(files, installed, labels) {
+    const tags = [...new Set(files.map((file) => file.tag))].sort(compareNames);
+    return tags.map((tag) => ({ tag, label: languageLabel(tag, labels), installed: installed.has(tag) }));
+}
+/** The configured label of tag, or the capitalized tag. */
+export function languageLabel(tag, labels) {
+    if (Object.hasOwn(labels, tag)) {
+        return labels[tag] ?? tag;
+    }
+    return tag.charAt(0).toUpperCase() + tag.slice(1);
+}
+/** Every detected tag, sorted. */
+export function allLanguageTags(languages) {
+    return languages.options.map((option) => option.tag);
+}
+/** The tags already installed in the project; the wizard preselects them. */
+export function installedLanguageTags(languages) {
+    return languages.options.filter((option) => option.installed).map((option) => option.tag);
+}
+/**
+ * Returns selected plus the tags each selected tag implies. Implications
+ * apply one way only: an implied tag never adds the tag that implied it.
+ */
+export function expandLanguages(selected, implications) {
+    const expanded = [...selected];
+    for (const tag of selected) {
+        const implied = Object.hasOwn(implications, tag) ? (implications[tag] ?? []) : [];
+        for (const impliedTag of implied) {
+            if (!expanded.includes(impliedTag)) {
+                expanded.push(impliedTag);
+            }
+        }
+    }
+    return expanded;
+}

package/dist/sync/plan.js

@@ -0,0 +1,146 @@
+import { lstat, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { contain, installedName, isSeedOnly, removeDir } from "../config/index.js";
+import { EXEC_MODE, FILE_MODE, pathExists, readSortedDir } from "./fs-utils.js";
+import { detectLanguages, expandLanguages, languageTag } from "./languages.js";
+/**
+ * Computes the sync of every target for the selected language tags. It
+ * only reads the file system and validates every destination, so a
+ * failing plan writes nothing. Untagged files always install, and so do
+ * the files of every tag a selected tag implies.
+ */
+export async function planSync(config, packageRoot, projectRoot, selectedLanguages) {
+    const planner = new SyncPlanner(config, packageRoot, projectRoot, selectedLanguages);
+    const languages = await detectLanguages(config, packageRoot, projectRoot);
+    const targets = [];
+    for (const target of config.tasks.syncTargets) {
+        targets.push(await planner.planTarget(target));
+    }
+    return {
+        projectRoot,
+        targets,
+        languages: selectedOptions(languages, selectedLanguages),
+        hasLanguageFiles: languages.files.length > 0,
+    };
+}
+function selectedOptions(languages, selected) {
+    return languages.options.filter((option) => selected.includes(option.tag));
+}
+class SyncPlanner {
+    config;
+    packageRoot;
+    projectRoot;
+    selected;
+    userOwned;
+    constructor(config, packageRoot, projectRoot, selectedLanguages) {
+        this.config = config;
+        this.packageRoot = packageRoot;
+        this.projectRoot = projectRoot;
+        this.selected = expandLanguages(selectedLanguages, config.settings.languageImplications);
+        this.userOwned = config.userOwnedFiles();
+    }
+    async planTarget(target) {
+        const plan = { target, sourceMissing: false, removals: [], dirs: [], copies: [], seedKept: [] };
+        const sourceDir = contain(this.packageRoot, target.source);
+        contain(this.projectRoot, target.target);
+        if (!(await isDirectory(sourceDir))) {
+            plan.sourceMissing = true;
+            return plan;
+        }
+        plan.removals = await this.planRemovals(target);
+        await this.planCopies(plan, sourceDir, "");
+        return plan;
+    }
+    /** Lists the prefixed entries matched by removeFirst, never seed-only or user-owned files. */
+    async planRemovals(target) {
+        const removals = [];
+        const seen = new Set();
+        for (const pattern of target.removeFirst) {
+            const dirRelative = path.posix.join(target.target, removeDir(pattern));
+            const dir = contain(this.projectRoot, dirRelative);
+            const entries = await readDirOrSkip(dir);
+            if (entries.length === 0) {
+                continue;
+            }
+            const realDir = await realpath(dir);
+            for (const entry of entries) {
+                const key = path.join(realDir, entry.name);
+                if (seen.has(key) || !this.isRemovable(target, entry.name)) {
+                    continue;
+                }
+                seen.add(key);
+                removals.push(path.posix.join(dirRelative, entry.name));
+            }
+        }
+        return removals;
+    }
+    isRemovable(target, name) {
+        return name.startsWith(this.config.settings.filePrefix) && !isSeedOnly(target, name) && !this.userOwned.includes(name);
+    }
+    /** Walks the source without following symlinks; only regular files and directories are synced. */
+    async planCopies(plan, sourceDir, relativeDir) {
+        for (const entry of (await readSortedDir(path.join(sourceDir, ...splitRelative(relativeDir)))) ?? []) {
+            const relative = path.posix.join(relativeDir, entry.name);
+            if (entry.isDirectory()) {
+                plan.dirs.push(this.destination(plan.target, relative));
+                await this.planCopies(plan, sourceDir, relative);
+            }
+            else if (entry.isFile() && !this.isExcludedLanguageFile(plan.target, relative)) {
+                await this.planFile(plan, path.join(sourceDir, ...relative.split("/")), relative, entry);
+            }
+        }
+    }
+    async planFile(plan, source, relative, entry) {
+        const installed = path.posix.dirname(relative) === "." ? installedName(plan.target, relative) : relative;
+        const destination = this.destination(plan.target, installed);
+        if (isSeedOnly(plan.target, entry.name) && (await pathExists(contain(this.projectRoot, destination)))) {
+            plan.seedKept.push(destination);
+            return;
+        }
+        const info = await lstat(source);
+        plan.copies.push({ source, destination, mode: modeFor(info.mode) });
+    }
+    /** The project-relative destination, validated against the project root. */
+    destination(target, relative) {
+        const destination = path.posix.join(target.target, relative);
+        contain(this.projectRoot, destination);
+        return destination;
+    }
+    /**
+     * Reports whether relative is a tagged file directly inside the target's
+     * languageInstructions directory whose language is not selected.
+     */
+    isExcludedLanguageFile(target, relative) {
+        if (target.languageInstructions === undefined) {
+            return false;
+        }
+        if (path.posix.dirname(relative) !== path.posix.normalize(target.languageInstructions)) {
+            return false;
+        }
+        const tag = languageTag(this.config, path.posix.basename(relative));
+        return tag !== undefined && !this.selected.includes(tag);
+    }
+}
+function splitRelative(relative) {
+    return relative === "" ? [] : relative.split("/");
+}
+async function isDirectory(target) {
+    try {
+        return (await stat(target)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Mirrors the Go sync: a removeFirst directory that cannot be read is skipped. */
+async function readDirOrSkip(dir) {
+    try {
+        return (await readSortedDir(dir)) ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function modeFor(sourceMode) {
+    return (sourceMode & 0o111) !== 0 ? EXEC_MODE : FILE_MODE;
+}

package/dist/sync/projects.js

@@ -0,0 +1,294 @@
+import { randomBytes } from "node:crypto";
+import { chmod, lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { contain, removeDir } from "../config/index.js";
+import { readSortedDir, toDisplayPath } from "./fs-utils.js";
+const ISSUE_TEMPLATE_DIR = "ISSUE_TEMPLATE";
+const FRONTMATTER_FENCE = "---";
+const PROJECTS_KEY = "projects:";
+/**
+ * Reads the projects line of every prefixed issue template before the
+ * sync deletes and re-copies them. It only reads; templates it cannot
+ * read are remembered so mergeProjects skips them.
+ */
+export async function captureProjects(config, projectRoot) {
+    const names = new Map();
+    const skipped = new Set();
+    for (const template of await issueTemplates(config, projectRoot)) {
+        const content = await readTemplate(template);
+        const line = content === undefined ? undefined : findProjectsLine(content);
+        if (line === undefined) {
+            skipped.add(template);
+        }
+        else {
+            names.set(template, line.names);
+        }
+    }
+    return { names, skipped };
+}
+/**
+ * Writes the union of each template's current names, the captured names
+ * and the entered names into its projects line. A template is only
+ * written when the merged list differs. Templates skipped at capture are
+ * never written, so their earlier names are not silently replaced; they
+ * are reported as skipped.
+ */
+export async function mergeProjects(config, projectRoot, capture, entered) {
+    const updated = [];
+    const skipped = [];
+    for (const template of await issueTemplates(config, projectRoot)) {
+        const display = toDisplayPath(projectRoot, template);
+        if (capture.skipped.has(template)) {
+            skipped.push(display);
+            continue;
+        }
+        const outcome = await mergeTemplate(template, capture.names.get(template) ?? [], entered);
+        if (outcome === "skipped") {
+            skipped.push(display);
+        }
+        else if (outcome === "updated") {
+            updated.push(display);
+        }
+    }
+    return { updated, skipped };
+}
+async function mergeTemplate(template, captured, entered) {
+    const content = await readTemplate(template);
+    const line = content === undefined ? undefined : findProjectsLine(content);
+    if (content === undefined || line === undefined) {
+        return "skipped";
+    }
+    const merged = unionNames(line.names, captured, entered);
+    if (merged.length === unionNames(line.names).length) {
+        return "unchanged";
+    }
+    const rewritten = content.slice(0, line.start) + renderProjectsLine(merged) + line.ending + content.slice(line.end);
+    await writeTemplate(template, rewritten);
+    return "updated";
+}
+/** Lists the prefixed entries of every removeFirst directory named ISSUE_TEMPLATE, in directory order. */
+async function issueTemplates(config, projectRoot) {
+    const templates = [];
+    for (const dir of issueTemplateDirs(config, projectRoot)) {
+        for (const entry of (await readSortedDir(dir)) ?? []) {
+            const template = path.join(dir, entry.name);
+            if (entry.name.startsWith(config.settings.filePrefix) && !entry.isDirectory() && !templates.includes(template)) {
+                templates.push(template);
+            }
+        }
+    }
+    return templates;
+}
+/** Skips directories that escape the project; the sync plan rejects those itself. */
+function issueTemplateDirs(config, projectRoot) {
+    const dirs = [];
+    for (const target of config.tasks.syncTargets) {
+        for (const pattern of target.removeFirst) {
+            const dir = removeDir(pattern);
+            if (path.posix.basename(dir) !== ISSUE_TEMPLATE_DIR) {
+                continue;
+            }
+            const contained = containOrUndefined(projectRoot, target.target, dir);
+            if (contained !== undefined && !dirs.includes(contained)) {
+                dirs.push(contained);
+            }
+        }
+    }
+    return dirs;
+}
+function containOrUndefined(root, ...elements) {
+    try {
+        return contain(root, ...elements);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Returns undefined when the template is not a regular file, so symlinks are never followed. */
+async function readTemplate(template) {
+    const info = await lstat(template);
+    if (!info.isFile()) {
+        return undefined;
+    }
+    return readFile(template, "utf8");
+}
+/** Replaces the template atomically, keeping its file mode, so a failed write never leaves a half-written template. */
+async function writeTemplate(template, content) {
+    const info = await lstat(template);
+    const temp = path.join(path.dirname(template), `.${path.basename(template)}.${randomBytes(6).toString("hex")}`);
+    try {
+        await writeFile(temp, content, { flag: "wx", mode: info.mode & 0o777 });
+        await chmod(temp, info.mode & 0o777);
+        await rename(temp, template);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+/** Locates the first projects line inside the leading frontmatter block; undefined when there is none or it does not parse. */
+export function findProjectsLine(content) {
+    let lineStart = 0;
+    for (let index = 0; lineStart < content.length; index++) {
+        const { body, ending, next } = splitLine(content, lineStart);
+        const isFence = body.trim() === FRONTMATTER_FENCE;
+        if ((index === 0 && !isFence) || (index > 0 && isFence)) {
+            return undefined;
+        }
+        if (body.startsWith(PROJECTS_KEY)) {
+            const names = parseFlowList(body.slice(PROJECTS_KEY.length).trim());
+            return names === undefined ? undefined : { start: lineStart, end: next, ending, names };
+        }
+        lineStart = next;
+    }
+    return undefined;
+}
+/** Returns the line starting at start without its ending, the ending ("\n", "\r\n" or "") and the start of the next line. */
+function splitLine(content, start) {
+    const end = content.indexOf("\n", start);
+    if (end < 0) {
+        return { body: content.slice(start), ending: "", next: content.length };
+    }
+    const body = content.slice(start, end);
+    if (body.endsWith("\r")) {
+        return { body: body.slice(0, -1), ending: "\r\n", next: end + 1 };
+    }
+    return { body, ending: "\n", next: end + 1 };
+}
+/** Parses a YAML flow sequence of scalars such as ["A", 'B', C]; undefined for anything else. */
+export function parseFlowList(value) {
+    if (!value.startsWith("[") || !value.endsWith("]") || value.length < 2) {
+        return undefined;
+    }
+    const names = [];
+    let rest = value.slice(1, -1).trim();
+    while (rest !== "") {
+        const item = parseFlowItem(rest);
+        if (item === undefined) {
+            return undefined;
+        }
+        names.push(item.name);
+        rest = item.remainder.trim();
+        if (rest === "") {
+            break;
+        }
+        if (!rest.startsWith(",")) {
+            return undefined;
+        }
+        rest = rest.slice(1).trim();
+        if (rest === "") {
+            return undefined;
+        }
+    }
+    return names;
+}
+function parseFlowItem(item) {
+    if (item.startsWith('"')) {
+        return parseDoubleQuoted(item);
+    }
+    if (item.startsWith("'")) {
+        return parseSingleQuoted(item);
+    }
+    const comma = item.indexOf(",");
+    const end = comma < 0 ? item.length : comma;
+    const name = item.slice(0, end).trim();
+    if (name === "" || /["'[\]{}#]/.test(name)) {
+        return undefined;
+    }
+    return { name, remainder: item.slice(end) };
+}
+function parseDoubleQuoted(item) {
+    for (let index = 1; index < item.length; index++) {
+        if (item[index] === "\\") {
+            index++;
+        }
+        else if (item[index] === '"') {
+            const name = unquoteDouble(item.slice(1, index));
+            return name === undefined ? undefined : { name, remainder: item.slice(index + 1) };
+        }
+    }
+    return undefined;
+}
+const SIMPLE_ESCAPES = {
+    a: "\u0007",
+    b: "\b",
+    f: "\f",
+    n: "\n",
+    r: "\r",
+    t: "\t",
+    v: "\v",
+    "\\": "\\",
+    '"': '"',
+    "/": "/",
+};
+const HEX_ESCAPE_LENGTHS = { x: 2, u: 4, U: 8 };
+/** Decodes the body of a double-quoted scalar; undefined for an invalid escape or a raw line break. */
+function unquoteDouble(body) {
+    let decoded = "";
+    for (let index = 0; index < body.length; index++) {
+        const character = body.charAt(index);
+        if (character === "\n" || character === "\r") {
+            return undefined;
+        }
+        if (character !== "\\") {
+            decoded += character;
+            continue;
+        }
+        const escape = body.charAt(index + 1);
+        const simple = Object.hasOwn(SIMPLE_ESCAPES, escape) ? SIMPLE_ESCAPES[escape] : undefined;
+        if (simple !== undefined) {
+            decoded += simple;
+            index++;
+            continue;
+        }
+        const length = Object.hasOwn(HEX_ESCAPE_LENGTHS, escape) ? (HEX_ESCAPE_LENGTHS[escape] ?? 0) : 0;
+        const hex = body.slice(index + 2, index + 2 + length);
+        if (length === 0 || !/^[0-9a-fA-F]+$/.test(hex) || hex.length !== length) {
+            return undefined;
+        }
+        const codePoint = Number.parseInt(hex, 16);
+        if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+            return undefined;
+        }
+        decoded += String.fromCodePoint(codePoint);
+        index += 1 + length;
+    }
+    return decoded;
+}
+/** Reads a YAML single-quoted scalar, where a doubled quote stands for one quote. */
+function parseSingleQuoted(item) {
+    let name = "";
+    for (let index = 1; index < item.length; index++) {
+        if (item[index] !== "'") {
+            name += item.charAt(index);
+            continue;
+        }
+        if (item[index + 1] === "'") {
+            name += "'";
+            index++;
+            continue;
+        }
+        return { name, remainder: item.slice(index + 1) };
+    }
+    return undefined;
+}
+/** The comparison key of a project name; matches the wizard's duplicate check. */
+function normalizeName(name) {
+    return name.replaceAll("`", "").trim().toLowerCase();
+}
+/** Merges the lists in order, dropping blanks and case-insensitive duplicates. */
+function unionNames(...lists) {
+    const names = [];
+    const seen = new Set();
+    for (const name of lists.flat().map((entry) => entry.trim())) {
+        const key = normalizeName(name);
+        if (key !== "" && !seen.has(key)) {
+            seen.add(key);
+            names.push(name);
+        }
+    }
+    return names;
+}
+/** Double-quotes and escapes every name, so no name can break out of the sequence. */
+function renderProjectsLine(names) {
+    return `${PROJECTS_KEY} [${names.map((name) => JSON.stringify(name)).join(", ")}]`;
+}