@yaawn/workflow 0.3.1 → 0.5.0

package/dist/display/palette.js

@@ -0,0 +1,61 @@
+import process from "node:process";
+const RESET_FOREGROUND = "\u001b[39m";
+const BOLD = "\u001b[1m";
+const RESET_BOLD_FAINT = "\u001b[22m";
+const FAINT = "\u001b[2m";
+const YELLOW = "\u001b[33m";
+const TRUE_COLOR_DEPTH = 2 ** 24;
+const ANSI_256_DEPTH = 256;
+const HEX_COLOR = /^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/;
+const plain = (text) => text;
+/** Styles for the installer output; every style degrades to plain text on terminals without colour. */
+export class Palette {
+    title;
+    brand;
+    muted;
+    warning;
+    constructor(brandColor, target, env = process.env) {
+        const colors = supportsColor(target, env);
+        const brandCode = colors ? foregroundCode(brandColor, target) : undefined;
+        this.brand = brandCode === undefined ? plain : wrap(brandCode, RESET_FOREGROUND);
+        this.title = colors ? (text) => wrap(BOLD, RESET_BOLD_FAINT)(this.brand(text)) : plain;
+        this.muted = colors ? wrap(FAINT, RESET_BOLD_FAINT) : plain;
+        this.warning = colors ? wrap(YELLOW, RESET_FOREGROUND) : plain;
+    }
+}
+function supportsColor(target, env) {
+    const noColor = env["NO_COLOR"];
+    if (noColor !== undefined && noColor !== "") {
+        return false;
+    }
+    return target.isTTY === true && target.hasColors?.() === true;
+}
+function foregroundCode(hex, target) {
+    const rgb = parseHex(hex);
+    if (rgb === undefined) {
+        return undefined;
+    }
+    if (target.hasColors?.(TRUE_COLOR_DEPTH) === true) {
+        return `\u001b[38;2;${rgb.join(";")}m`;
+    }
+    if (target.hasColors?.(ANSI_256_DEPTH) === true) {
+        return `\u001b[38;5;${toAnsi256(rgb)}m`;
+    }
+    return undefined;
+}
+function parseHex(hex) {
+    const match = HEX_COLOR.exec(hex);
+    if (match === null) {
+        return undefined;
+    }
+    const [, red = "", green = "", blue = ""] = match;
+    return [Number.parseInt(red, 16), Number.parseInt(green, 16), Number.parseInt(blue, 16)];
+}
+/** Maps a colour onto the 6×6×6 cube of the 256-colour palette. */
+function toAnsi256(rgb) {
+    const [red, green, blue] = rgb.map((channel) => Math.round((channel / 255) * 5));
+    return 16 + 36 * (red ?? 0) + 6 * (green ?? 0) + (blue ?? 0);
+}
+function wrap(open, close) {
+    return (text) => (text === "" ? text : `${open}${text}${close}`);
+}

package/dist/display/renderer.js

@@ -0,0 +1,169 @@
+import { confirm, intro, isCancel, log, outro, select, spinner } from "@clack/prompts";
+import { fill } from "../config/index.js";
+import { Palette } from "./palette.js";
+import { MODE_INSTALL, MODE_UNINSTALL, } from "./report.js";
+import { sanitize } from "./sanitize.js";
+const LIST_INDENT = "  ";
+/** Throws the same error the guard recognises as a Ctrl+C cancellation. */
+function cancelled() {
+    return Object.assign(new Error("cancelled"), { name: "ExitPromptError" });
+}
+/**
+ * Writes the installer's output with @clack/prompts: the left-rail guide,
+ * step symbols, animated spinner and interactive prompts. Every text comes
+ * from the config messages, and every printed string is sanitized.
+ */
+export class Renderer {
+    messages;
+    palette;
+    output;
+    constructor(messages, brandColor, output) {
+        this.messages = messages;
+        this.palette = new Palette(brandColor, output);
+        this.output = output;
+    }
+    /** Prints the branded title block for the given package version. */
+    intro(version) {
+        const values = { version };
+        intro(this.palette.title(this.text(this.messages.introTitle, values)), { output: this.output });
+        log.message(this.text(this.messages.introSubtitle, values), { output: this.output });
+        log.message(this.text(this.messages.intro, values), { output: this.output });
+    }
+    /** Prints the closing block with the next steps; values fill its placeholders. */
+    outro(values) {
+        outro(this.text(this.messages.outro, values), { output: this.output });
+    }
+    info(text) {
+        log.info(sanitize(text), { output: this.output });
+    }
+    /** Prints a skipped or unexpected step, marked by a symbol as well as colour. */
+    warn(text) {
+        log.warn(sanitize(text), { output: this.output });
+    }
+    /** Runs task behind the "installing" spinner. */
+    async installing(task) {
+        const s = spinner({ output: this.output });
+        s.start(this.text(this.messages.installing));
+        try {
+            const result = await task();
+            s.stop(this.text(this.messages.installing));
+            return result;
+        }
+        catch (error) {
+            s.stop(this.text(this.messages.installing));
+            throw error;
+        }
+    }
+    /** Runs task behind the "removing" spinner. */
+    async uninstalling(task) {
+        const s = spinner({ output: this.output });
+        s.start(this.text(this.messages.uninstalling));
+        try {
+            const result = await task();
+            s.stop(this.text(this.messages.uninstalling));
+            return result;
+        }
+        catch (error) {
+            s.stop(this.text(this.messages.uninstalling));
+            throw error;
+        }
+    }
+    /** Prints the warnings and install output, then the failure or, on success, the outro. */
+    installSummary(summary) {
+        summary.warnings.forEach((warning) => this.warn(warning));
+        summary.lines.forEach((line) => {
+            if (line.warning) {
+                this.warn(line.text);
+            }
+            else {
+                log.step(sanitize(line.text), { output: this.output });
+            }
+        });
+        if (summary.failure !== undefined) {
+            log.error(sanitize(summary.failure), { output: this.output });
+            return;
+        }
+        this.outro(summary.outroValues);
+    }
+    /** Asks whether to install / update or uninstall, with install preselected. Ctrl+C rejects with ExitPromptError. */
+    async chooseMode() {
+        const result = await select({
+            message: this.text(this.messages.modeTitle),
+            options: [
+                { value: MODE_INSTALL, label: this.text(this.messages.modeInstall) },
+                { value: MODE_UNINSTALL, label: this.text(this.messages.modeUninstall) },
+            ],
+            initialValue: MODE_INSTALL,
+            output: this.output,
+        });
+        if (isCancel(result)) {
+            throw cancelled();
+        }
+        return result;
+    }
+    /** Lists entries and asks to remove them, with "No" preselected. Ctrl+C rejects with ExitPromptError. */
+    async confirmUninstall(entries) {
+        log.message(this.palette.title(this.text(this.messages.uninstallHeaderTitle)), { output: this.output });
+        log.message(this.pathList(this.messages.uninstallList, entries), { output: this.output });
+        const result = await confirm({
+            message: this.text(this.messages.uninstallConfirm),
+            active: this.text(this.messages.uninstallYes),
+            inactive: this.text(this.messages.uninstallNo),
+            initialValue: false,
+            output: this.output,
+        });
+        if (isCancel(result)) {
+            throw cancelled();
+        }
+        return result;
+    }
+    uninstallCancelled() {
+        log.warn(this.text(this.messages.uninstallCancelled), { output: this.output });
+    }
+    /** Prints that no yaawn files were found, followed by the npm hint. */
+    nothingToRemove(packageName) {
+        log.info(this.text(this.messages.nothingToRemove), { output: this.output });
+        log.message(this.npmHint(packageName), { output: this.output });
+    }
+    /**
+     * Lists the removed entries, the pruned folders, the kept-plans note and the
+     * npm hint. After a failure it shows the error and what was removed so far
+     * instead, without the npm hint.
+     */
+    uninstallSummary(report) {
+        if (report.failure !== undefined) {
+            log.error(fill(this.messages.uninstallFailed, { error: sanitize(report.failure) }), { output: this.output });
+            this.printPathList(this.messages.uninstallRemovedSoFar, report.summary.removed);
+            this.printPathList(this.messages.uninstallPruned, report.summary.pruned);
+            return;
+        }
+        this.printPathList(this.messages.uninstallRemoved, report.summary.removed);
+        this.printPathList(this.messages.uninstallPruned, report.summary.pruned);
+        if (report.summary.keptPlans) {
+            log.message(this.text(this.messages.uninstallKeptPlans), { output: this.output });
+        }
+        log.message(this.npmHint(report.packageName), { output: this.output });
+    }
+    printPathList(heading, paths) {
+        if (paths.length === 0) {
+            return;
+        }
+        const lines = paths.map((path) => LIST_INDENT + sanitize(path));
+        log.message([this.palette.title(sanitize(heading)), ...lines].join("\n"), { output: this.output });
+    }
+    /** Renders heading and the paths below it, or "" when there are none. */
+    pathList(heading, paths) {
+        if (paths.length === 0) {
+            return "";
+        }
+        const lines = paths.map((path) => LIST_INDENT + sanitize(path));
+        return [this.palette.title(sanitize(heading)), ...lines].join("\n");
+    }
+    npmHint(packageName) {
+        return this.text(this.messages.uninstallNpmHint, { package: packageName });
+    }
+    /** Fills template, then sanitizes the result so neither config nor values can drive the terminal. */
+    text(template, values = {}) {
+        return sanitize(fill(template, values));
+    }
+}

package/dist/display/report.js

@@ -0,0 +1,15 @@
+/** Records progress lines while the spinner runs, so they print afterwards without garbling it. */
+export class ReportCollector {
+    recorded = [];
+    get lines() {
+        return this.recorded;
+    }
+    info(text) {
+        this.recorded.push({ text, warning: false });
+    }
+    warn(text) {
+        this.recorded.push({ text, warning: true });
+    }
+}
+export const MODE_INSTALL = "install";
+export const MODE_UNINSTALL = "uninstall";

package/dist/display/sanitize.js

@@ -0,0 +1,10 @@
+import { stripVTControlCharacters } from "node:util";
+// eslint-disable-next-line no-control-regex -- matches the C0/C1 control characters that could drive the terminal
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+/**
+ * Strips escape sequences and control characters other than line breaks
+ * and tabs, so text from the user's disk or config cannot drive the terminal.
+ */
+export function sanitize(text) {
+    return stripVTControlCharacters(text).replace(CONTROL_CHARACTERS, "");
+}

package/dist/link/errors.js

@@ -0,0 +1,34 @@
+/** The managed block's start and end markers are incomplete, repeated or out of order. */
+export class MalformedBlockError extends Error {
+    name = "MalformedBlockError";
+    constructor() {
+        super("the yaawn import markers are incomplete or repeated; fix them by hand");
+    }
+}
+/** A memory file larger than the installer reads. */
+export class MemoryTooLargeError extends Error {
+    limit;
+    name = "MemoryTooLargeError";
+    constructor(limit) {
+        super(`file is larger than ${limit} bytes`);
+        this.limit = limit;
+    }
+}
+/** A path that is not one of the memory files yaawn manages an instruction block in. */
+export class UnmanagedFileError extends Error {
+    path;
+    name = "UnmanagedFileError";
+    constructor(path) {
+        super("not a file yaawn manages an instruction block in");
+        this.path = path;
+    }
+}
+/** A path that is not one of the agent folders yaawn links, nor an entry directly inside one. */
+export class UnmanagedLinkError extends Error {
+    path;
+    name = "UnmanagedLinkError";
+    constructor(path) {
+        super("not a link yaawn manages");
+        this.path = path;
+    }
+}

package/dist/link/fs-utils.js

@@ -0,0 +1,79 @@
+import { chmod, lstat, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { contain } from "../config/index.js";
+export const DIR_MODE = 0o755;
+export const FILE_MODE = 0o644;
+const PERMISSION_BITS = 0o777;
+export function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/** The entry's own stats without following a symlink, or undefined when it does not exist. */
+export async function lstatIfExists(target) {
+    try {
+        return await lstat(target);
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function isDirectory(target) {
+    try {
+        return (await stat(target)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Reports whether the slash-separated elements name a directory contained in root. */
+export async function isContainedDirectory(root, ...elements) {
+    try {
+        return await isDirectory(contain(root, ...elements));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Contains the parent of the slash-separated, root-relative entry rather
+ * than the entry itself, so a symlinked entry resolves to the link, never
+ * to its target.
+ */
+export function containEntry(root, relative) {
+    const parent = contain(root, path.posix.dirname(relative));
+    return path.join(parent, path.posix.basename(relative));
+}
+/** The entries of dir sorted by name, in the order the Go installer listed them. */
+export async function readSortedDir(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.sort((left, right) => compareNames(left.name, right.name));
+}
+function compareNames(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}
+export function permissionBits(stats) {
+    return stats.mode & PERMISSION_BITS;
+}
+/**
+ * Writes content to a sibling temp file and renames it over filePath, so
+ * a crash never leaves a half-written file and an entry that replaced
+ * filePath is swapped out rather than written through.
+ */
+export async function writeFileAtomically(filePath, content, mode) {
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    try {
+        await writeFile(tempPath, content, { flag: "wx", mode });
+        await chmod(tempPath, mode);
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+}

package/dist/link/index.js

@@ -0,0 +1,4 @@
+export { MalformedBlockError, MemoryTooLargeError, UnmanagedFileError, UnmanagedLinkError } from "./errors.js";
+export { linkAgent } from "./install.js";
+export { findInstalledLinks, removeLink, removeLinks, } from "./uninstall.js";
+export { AGENTS_DIR, countLinkFailures, failureReason, hasLinkFailure, KIND_IMPORTS, KIND_SYMLINK, LINK_CREATED, LINK_EXISTED, LINK_FAILED, LINK_SKIPPED, } from "./types.js";

package/dist/link/install.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { isAgent, UnknownAgentError } from "../config/index.js";
+import { Linker } from "./linker.js";
+import { writeInstructionBlock } from "./memory.js";
+/**
+ * Links the .agents payload for agent: relative symlinks into .agents
+ * and, for agents without a linked instructions folder, the managed
+ * instruction block in their memory file. A failure is recorded in its
+ * result and the remaining links are still attempted; only an unknown
+ * agent or an unusable project root rejects.
+ */
+export async function linkAgent(projectRoot, prefix, agent) {
+    if (!isAgent(agent)) {
+        throw new UnknownAgentError(agent);
+    }
+    const root = path.resolve(projectRoot);
+    const results = await new Linker(root, prefix).linkAgentFolders(agent);
+    const block = await writeInstructionBlock(root, agent);
+    return block === undefined ? results : [...results, block];
+}

package/dist/link/linker.js

@@ -0,0 +1,137 @@
+import { mkdir, readlink, symlink, unlink } from "node:fs/promises";
+import path from "node:path";
+import { AGENT_CLAUDE, AGENT_COPILOT, AGENT_VIBE, contain } from "../config/index.js";
+import { DIR_MODE, containEntry, isContainedDirectory, lstatIfExists, readSortedDir } from "./fs-utils.js";
+import { isSafeName, isWithin, relativeTarget } from "./names.js";
+import { AGENTS_DIR, KIND_SYMLINK, LINK_CREATED, LINK_EXISTED, LINK_FAILED, LINK_SKIPPED, } from "./types.js";
+/** Vibe has no folder links: it reads .agents/skills natively. */
+const FOLDER_LINKS = {
+    [AGENT_COPILOT]: [
+        { path: ".github/skills", source: "skills", entryIsDir: true },
+        { path: ".github/instructions", source: "instructions", entryIsDir: false },
+    ],
+    [AGENT_CLAUDE]: [{ path: ".claude/skills", source: "skills", entryIsDir: true }],
+    [AGENT_VIBE]: [],
+};
+/** Every folder any agent may have linked, including the legacy .claude/rules link. */
+export const REMOVABLE_FOLDERS = [
+    ".github/skills",
+    ".github/instructions",
+    ".claude/skills",
+    ".claude/rules",
+];
+/**
+ * Places and inspects links into .agents inside one project. It never
+ * removes or overwrites anything that is not a link into .agents.
+ */
+export class Linker {
+    root;
+    prefix;
+    agentsDir;
+    results = [];
+    constructor(root, prefix = "") {
+        this.root = root;
+        this.prefix = prefix;
+        this.agentsDir = path.join(root, AGENTS_DIR);
+    }
+    /** Links every folder of agent; a failure is recorded and the remaining links are still attempted. */
+    async linkAgentFolders(agent) {
+        for (const folder of FOLDER_LINKS[agent]) {
+            await this.linkFolder(folder);
+        }
+        return [...this.results];
+    }
+    async linkFolder(folder) {
+        if (!(await isContainedDirectory(this.root, AGENTS_DIR, folder.source))) {
+            return;
+        }
+        const target = relativeTarget(folder.path, `${AGENTS_DIR}/${folder.source}`);
+        let linkPath;
+        try {
+            linkPath = containEntry(this.root, folder.path);
+        }
+        catch (error) {
+            this.record(LINK_FAILED, folder.path, target, error);
+            return;
+        }
+        await this.place({ linkPath, relative: folder.path, target, type: "dir" }, folder);
+    }
+    /**
+     * Creates a missing link, keeps a link into .agents and skips any other
+     * entry; with inside set, a real folder at the link path gets the yaawn
+     * entries linked one by one.
+     */
+    async place(link, inside) {
+        try {
+            const state = await this.classify(link.linkPath);
+            if (state === "missing") {
+                await createLink(link);
+                this.record(LINK_CREATED, link.relative, link.target);
+            }
+            else if (state === "own") {
+                this.record(LINK_EXISTED, link.relative, link.target);
+            }
+            else if (state === "realDir" && inside !== undefined) {
+                await this.linkEntries(link.linkPath, inside);
+            }
+            else {
+                this.record(LINK_SKIPPED, link.relative, link.target);
+            }
+        }
+        catch (error) {
+            this.record(LINK_FAILED, link.relative, link.target, error);
+        }
+    }
+    /** Links each prefixed yaawn entry of the folder's source into dir, a real folder the user owns. */
+    async linkEntries(dir, folder) {
+        const entries = await readSortedDir(contain(this.root, AGENTS_DIR, folder.source));
+        for (const entry of entries) {
+            const matchesKind = folder.entryIsDir ? entry.isDirectory() : entry.isFile();
+            if (!entry.name.startsWith(this.prefix) || !isSafeName(entry.name) || !matchesKind) {
+                continue;
+            }
+            const relative = `${folder.path}/${entry.name}`;
+            const target = relativeTarget(relative, `${AGENTS_DIR}/${folder.source}/${entry.name}`);
+            const type = folder.entryIsDir ? "dir" : "file";
+            await this.place({ linkPath: path.join(dir, entry.name), relative, target, type });
+        }
+    }
+    record(status, relative, target, error) {
+        const failure = status === LINK_FAILED ? { manualCommand: `ln -s ${target} ${relative}`, error } : {};
+        this.results.push({ kind: KIND_SYMLINK, status, path: relative, target, ...failure });
+    }
+    /** Inspects linkPath itself and never follows it. */
+    async classify(linkPath) {
+        const stats = await lstatIfExists(linkPath);
+        if (stats === undefined) {
+            return "missing";
+        }
+        if (stats.isSymbolicLink()) {
+            return (await this.pointsIntoAgents(linkPath)) ? "own" : "foreign";
+        }
+        return stats.isDirectory() ? "realDir" : "foreign";
+    }
+    /** Resolves the link's target text against the link's folder, without touching the target, and checks it lies in .agents. */
+    async pointsIntoAgents(linkPath) {
+        let target;
+        try {
+            target = await readlink(linkPath);
+        }
+        catch {
+            return false;
+        }
+        return isWithin(this.agentsDir, path.resolve(path.dirname(linkPath), target));
+    }
+    /** Removes the link at linkPath only while it still points into .agents. Reports whether it was removed. */
+    async unlinkOwn(linkPath) {
+        if ((await this.classify(linkPath)) !== "own") {
+            return false;
+        }
+        await unlink(linkPath);
+        return true;
+    }
+}
+async function createLink(link) {
+    await mkdir(path.dirname(link.linkPath), { recursive: true, mode: DIR_MODE });
+    await symlink(link.target.split("/").join(path.sep), link.linkPath, link.type);
+}