@yaawn/workflow 0.4.0 → 0.5.0

package/dist/config/tasks.js

@@ -0,0 +1,77 @@
+import { isFileName, isRelativeDir, isRemovePattern } from "./names.js";
+import { JsonLocation, optional, readArray, readStrictObject, readString, readStringArray, readStringRecord, required, sortedKeys, toRecord, } from "./strict-json.js";
+/** Name of the sync task config file. */
+export const INSTALL_TASKS_FILE = "install-tasks.json";
+const TASKS_KEYS = ["syncTargets"];
+const SYNC_TARGET_KEYS = ["source", "target", "seedOnly", "removeFirst", "languageInstructions", "renames"];
+export function decodeInstallTasks(document) {
+    const at = new JsonLocation(INSTALL_TASKS_FILE);
+    const object = readStrictObject(document, at, TASKS_KEYS);
+    return {
+        syncTargets: required(object, "syncTargets", at, (value, location) => readArray(value, location, decodeSyncTarget)),
+    };
+}
+function decodeSyncTarget(value, at) {
+    const object = readStrictObject(value, at, SYNC_TARGET_KEYS);
+    const languageInstructions = optional(object, "languageInstructions", at, readString, "");
+    return {
+        source: required(object, "source", at, readString),
+        target: required(object, "target", at, readString),
+        seedOnly: optional(object, "seedOnly", at, readStringArray, []),
+        removeFirst: optional(object, "removeFirst", at, readStringArray, []),
+        ...(languageInstructions === "" ? {} : { languageInstructions }),
+        renames: optional(object, "renames", at, readStringRecord, toRecord([])),
+    };
+}
+export function validateInstallTasks(tasks, ownedPrefix) {
+    const at = new JsonLocation(INSTALL_TASKS_FILE).key("syncTargets");
+    if (tasks.syncTargets.length === 0) {
+        throw at.error("must be a non-empty array");
+    }
+    tasks.syncTargets.forEach((target, position) => validateSyncTarget(target, at.index(position), ownedPrefix));
+}
+function validateSyncTarget(target, at, ownedPrefix) {
+    if (!isRelativeDir(target.source)) {
+        throw at.key("source").error("must be a relative directory inside the package");
+    }
+    if (!isRelativeDir(target.target)) {
+        throw at.key("target").error("must be a relative directory inside the project");
+    }
+    validateSeedOnly(target.seedOnly, at.key("seedOnly"));
+    validateRemoveFirst(target.removeFirst, at.key("removeFirst"), ownedPrefix);
+    if (target.languageInstructions !== undefined && !isRelativeDir(target.languageInstructions)) {
+        throw at.key("languageInstructions").error("must be a relative directory name");
+    }
+    validateRenames(target.renames, at.key("renames"));
+}
+function validateSeedOnly(seedOnly, at) {
+    const position = seedOnly.findIndex((name) => !isFileName(name));
+    if (position !== -1) {
+        throw at.index(position).error("must be a plain file name");
+    }
+}
+function validateRemoveFirst(removeFirst, at, ownedPrefix) {
+    const position = removeFirst.findIndex((pattern) => !isRemovePattern(pattern, ownedPrefix));
+    if (position !== -1) {
+        throw at.index(position).error(`must look like "dir/${ownedPrefix}*" (relative, no "..")`);
+    }
+}
+/** Keeps both sides plain file names, so a rename can never point outside the target directory. */
+function validateRenames(renames, at) {
+    const invalidSource = sortedKeys(renames).find((source) => !isFileName(source) || !isFileName(renames[source] ?? ""));
+    if (invalidSource !== undefined) {
+        throw at.key(invalidSource).error("must map a plain file name to a plain file name");
+    }
+}
+/** Reports whether a file with this name is only copied when it is missing in the project. */
+export function isSeedOnly(target, name) {
+    return target.seedOnly.includes(name);
+}
+/** Returns the name a file directly inside the source is installed under. */
+export function installedName(target, name) {
+    return Object.hasOwn(target.renames, name) ? (target.renames[name] ?? name) : name;
+}
+/** Lists the renamed destination names in stable order. */
+export function installedRenames(target) {
+    return sortedKeys(target.renames).map((source) => target.renames[source] ?? source);
+}

package/dist/config/wizard.js

@@ -0,0 +1,139 @@
+import { agents, isAgent } from "./agents.js";
+import { decodeMessages } from "./messages.js";
+import { SETTINGS_FILE } from "./settings.js";
+import { JsonLocation, optional, readArray, readStrictObject, readString, required, } from "./strict-json.js";
+/** Name of the wizard config file. */
+export const WIZARD_FILE = "wizard.json";
+export const KIND_TEXT_LIST = "text-list";
+export const KIND_MULTISELECT = "multiselect";
+export const KIND_SINGLE_SELECT = "single-select";
+export const KIND_PROJECTS_LIST = "projects-list";
+const SECTION_KINDS = [KIND_TEXT_LIST, KIND_MULTISELECT, KIND_SINGLE_SELECT, KIND_PROJECTS_LIST];
+const SINGLETON_KINDS = [KIND_MULTISELECT, KIND_SINGLE_SELECT, KIND_PROJECTS_LIST];
+const WIZARD_KEYS = ["sections", "messages"];
+const SECTION_KEYS = ["id", "title", "description", "kind", "targetFile", "placeholder", "options", "default"];
+const OPTION_KEYS = ["value", "label"];
+export function decodeWizard(document) {
+    const at = new JsonLocation(WIZARD_FILE);
+    const object = readStrictObject(document, at, WIZARD_KEYS);
+    return {
+        sections: required(object, "sections", at, (value, location) => readArray(value, location, decodeSection)),
+        messages: required(object, "messages", at, decodeMessages),
+    };
+}
+function decodeSection(value, at) {
+    const object = readStrictObject(value, at, SECTION_KEYS);
+    return {
+        id: required(object, "id", at, readString),
+        title: required(object, "title", at, readString),
+        description: required(object, "description", at, readString),
+        kind: required(object, "kind", at, readSectionKind),
+        targetFile: optional(object, "targetFile", at, readString, ""),
+        placeholder: optional(object, "placeholder", at, readString, ""),
+        options: optional(object, "options", at, (options, location) => readArray(options, location, decodeOption), []),
+        default: optional(object, "default", at, readString, ""),
+    };
+}
+function readSectionKind(value, at) {
+    const kind = readString(value, at);
+    if (!SECTION_KINDS.includes(kind)) {
+        throw at.error(`must be ${SECTION_KINDS.map((name) => `"${name}"`).join(", ")}`);
+    }
+    return kind;
+}
+function decodeOption(value, at) {
+    const object = readStrictObject(value, at, OPTION_KEYS);
+    return {
+        value: required(object, "value", at, readAgent),
+        label: required(object, "label", at, readString),
+    };
+}
+function readAgent(value, at) {
+    const agent = readString(value, at);
+    if (!isAgent(agent)) {
+        throw at.error(`must be one of ${agents().map((name) => `"${name}"`).join(", ")}`);
+    }
+    return agent;
+}
+/** Validates the sections against the settings; messages are complete once decoded. */
+export function validateWizard(wizard, settings) {
+    const at = new JsonLocation(WIZARD_FILE).key("sections");
+    if (wizard.sections.length === 0) {
+        throw at.error("must be a non-empty array");
+    }
+    wizard.sections.forEach((section, position) => validateSection(section, at.index(position), settings));
+    validateUniqueIds(wizard.sections, at);
+    validateSingletonKinds(wizard.sections, at);
+}
+function validateUniqueIds(sections, at) {
+    const seen = new Set();
+    sections.forEach((section, position) => {
+        if (seen.has(section.id)) {
+            throw at.index(position).key("id").error("must be unique");
+        }
+        seen.add(section.id);
+    });
+}
+function validateSingletonKinds(sections, at) {
+    for (const kind of SINGLETON_KINDS) {
+        if (sections.filter((section) => section.kind === kind).length > 1) {
+            throw at.error(`must contain at most one ${kind} section`);
+        }
+    }
+}
+function validateSection(section, at, settings) {
+    validateRequiredTexts(section, at);
+    if (section.kind === KIND_SINGLE_SELECT) {
+        validateSingleSelect(section, at);
+        return;
+    }
+    validateTargetFile(section, at, settings);
+    if (section.options.length > 0 || section.default !== "") {
+        throw at.key("options").error("are only allowed on a single-select section");
+    }
+}
+function validateRequiredTexts(section, at) {
+    for (const name of ["id", "title", "description"]) {
+        if (section[name] === "") {
+            throw at.key(name).error("is required");
+        }
+    }
+}
+function validateTargetFile(section, at, settings) {
+    if (section.kind === KIND_TEXT_LIST) {
+        if (!Object.hasOwn(settings.outputFileNames, section.targetFile)) {
+            throw at.key("targetFile").error(`must name a key of outputFileNames in ${SETTINGS_FILE}`);
+        }
+        return;
+    }
+    if (section.targetFile !== "") {
+        throw at.key("targetFile").error(`must be empty for a ${section.kind} section`);
+    }
+}
+/** Requires a non-empty, unique set of allowed agents and a default that is one of them. */
+function validateSingleSelect(section, at) {
+    if (section.targetFile !== "") {
+        throw at.key("targetFile").error(`must be empty for a ${KIND_SINGLE_SELECT} section`);
+    }
+    if (section.options.length === 0) {
+        throw at.key("options").error("must be a non-empty array");
+    }
+    const seen = new Set();
+    section.options.forEach((option, position) => {
+        const optionAt = at.key("options").index(position);
+        if (seen.has(option.value)) {
+            throw optionAt.key("value").error("must be unique");
+        }
+        seen.add(option.value);
+        if (option.label === "") {
+            throw optionAt.key("label").error("is required");
+        }
+    });
+    if (!seen.has(section.default)) {
+        throw at.key("default").error("must be the value of one of the options");
+    }
+}
+/** Returns the single-select section, if configured. */
+export function singleSelectSection(wizard) {
+    return wizard.sections.find((section) => section.kind === KIND_SINGLE_SELECT);
+}

package/dist/display/index.js

@@ -0,0 +1,3 @@
+export { Renderer } from "./renderer.js";
+export { MODE_INSTALL, MODE_UNINSTALL, ReportCollector, } from "./report.js";
+export { sanitize } from "./sanitize.js";

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];
+}