toolcraft 0.0.2 → 0.0.4

package/node_modules/@poe-code/task-list/dist/backends/markdown-dir.js

@@ -0,0 +1,466 @@
+import path from "node:path";
+import { acquireFileLock } from "@poe-code/file-lock";
+import { parseDocument, stringify } from "yaml";
+import taskSchema from "../schema/task.schema.json" with { type: "json" };
+import { eventsFromState, findEvent } from "../state-machine.js";
+import { resolveStateMachine } from "../state.js";
+import { InvalidTransitionError, MalformedTaskError, TaskAlreadyExistsError, TaskNotFoundError } from "../types.js";
+import { hasErrorCode, isRecord, sortStrings, sortTasks, statIfExists, validateTaskId, writeAtomically } from "./utils.js";
+const ARCHIVE_DIRECTORY_NAME = "archive";
+const MARKDOWN_EXTENSION = ".md";
+const TASK_KIND = "task";
+const TASK_VERSION = 1;
+const TASK_SCHEMA_ID = taskSchema.$id;
+const RESERVED_FRONTMATTER_KEYS = new Set([
+    "$schema",
+    "description",
+    "kind",
+    "name",
+    "state",
+    "version"
+]);
+function validateListName(name) {
+    if (name.length === 0 ||
+        name === ARCHIVE_DIRECTORY_NAME ||
+        name.startsWith(".") ||
+        name.includes("/") ||
+        name.includes("\\") ||
+        name.includes("..")) {
+        throw new Error(`Invalid task list name "${name}".`);
+    }
+    return name;
+}
+function parseQualifiedId(qualifiedId) {
+    const separatorIndex = qualifiedId.indexOf("/");
+    if (separatorIndex <= 0 ||
+        separatorIndex !== qualifiedId.lastIndexOf("/") ||
+        separatorIndex === qualifiedId.length - 1) {
+        throw new Error(`Invalid qualified task id "${qualifiedId}".`);
+    }
+    return {
+        list: validateListName(qualifiedId.slice(0, separatorIndex)),
+        id: validateTaskId(qualifiedId.slice(separatorIndex + 1))
+    };
+}
+function listPath(rootPath, list) {
+    return path.join(rootPath, list);
+}
+function archiveDirectoryPath(rootPath, list) {
+    return path.join(listPath(rootPath, list), ARCHIVE_DIRECTORY_NAME);
+}
+function activeTaskPath(rootPath, list, id) {
+    return path.join(listPath(rootPath, list), `${id}${MARKDOWN_EXTENSION}`);
+}
+function archivedTaskPath(rootPath, list, id) {
+    return path.join(archiveDirectoryPath(rootPath, list), `${id}${MARKDOWN_EXTENSION}`);
+}
+function isMarkdownFile(entryName) {
+    return entryName.endsWith(MARKDOWN_EXTENSION);
+}
+function isHiddenEntry(entryName) {
+    return entryName.startsWith(".");
+}
+function isLockFile(entryName) {
+    return entryName.endsWith(".lock");
+}
+function malformedTask(filePath, field) {
+    return new MalformedTaskError(`Malformed task "${filePath}": invalid "${field}".`);
+}
+function stripTrailingCarriageReturn(line) {
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+function splitTaskDocument(content, filePath) {
+    const lines = content.split("\n");
+    if (lines.length === 0 || stripTrailingCarriageReturn(lines[0]) !== "---") {
+        throw malformedTask(filePath, "frontmatter");
+    }
+    let closingIndex = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (stripTrailingCarriageReturn(lines[index]) === "---") {
+            closingIndex = index;
+            break;
+        }
+    }
+    if (closingIndex === -1) {
+        throw malformedTask(filePath, "frontmatter");
+    }
+    const bodyLines = lines.slice(closingIndex + 1);
+    if (bodyLines.length > 0 && stripTrailingCarriageReturn(bodyLines[0]) === "") {
+        bodyLines.shift();
+    }
+    return {
+        frontmatter: lines.slice(1, closingIndex).join("\n"),
+        body: bodyLines.join("\n")
+    };
+}
+function readFrontmatter(frontmatterContent, filePath) {
+    const document = parseDocument(frontmatterContent);
+    if (document.errors.length > 0) {
+        throw malformedTask(filePath, "frontmatter");
+    }
+    const parsed = document.toJS();
+    if (!isRecord(parsed)) {
+        throw malformedTask(filePath, "frontmatter");
+    }
+    return parsed;
+}
+function assertValidTaskRecord(frontmatter, filePath, validStates) {
+    if ("$schema" in frontmatter && frontmatter.$schema !== TASK_SCHEMA_ID) {
+        throw malformedTask(filePath, "$schema");
+    }
+    if ("kind" in frontmatter && frontmatter.kind !== TASK_KIND) {
+        throw malformedTask(filePath, "kind");
+    }
+    if ("version" in frontmatter) {
+        if (typeof frontmatter.version !== "number" ||
+            !Number.isInteger(frontmatter.version) ||
+            frontmatter.version !== TASK_VERSION) {
+            throw malformedTask(filePath, "version");
+        }
+    }
+    if (typeof frontmatter.name !== "string" || frontmatter.name.length === 0) {
+        throw malformedTask(filePath, "name");
+    }
+    if (typeof frontmatter.state !== "string" || !validStates.has(frontmatter.state)) {
+        throw malformedTask(filePath, "state");
+    }
+    if ("description" in frontmatter && typeof frontmatter.description !== "string") {
+        throw malformedTask(filePath, "description");
+    }
+}
+function metadataFromFrontmatter(frontmatter) {
+    const metadata = {};
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (!RESERVED_FRONTMATTER_KEYS.has(key)) {
+            metadata[key] = value;
+        }
+    }
+    return metadata;
+}
+function createTask(list, id, frontmatter, body) {
+    return {
+        list,
+        id,
+        qualifiedId: `${list}/${id}`,
+        name: frontmatter.name,
+        state: frontmatter.state,
+        description: body,
+        metadata: metadataFromFrontmatter(frontmatter)
+    };
+}
+function serializeTaskDocument(frontmatter, description) {
+    return `---\n${stringify(frontmatter)}---\n\n${description}`;
+}
+async function readDirectoryNames(fs, directoryPath) {
+    try {
+        return sortStrings(await fs.readdir(directoryPath));
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return [];
+        }
+        throw error;
+    }
+}
+async function ensureRootPath(deps) {
+    if (deps.create) {
+        await deps.fs.mkdir(deps.path, { recursive: true });
+        return;
+    }
+    await deps.fs.stat(deps.path);
+}
+async function readTaskFile(fs, list, id, filePath, validStates) {
+    const content = await fs.readFile(filePath, "utf8");
+    const document = splitTaskDocument(content, filePath);
+    const frontmatter = readFrontmatter(document.frontmatter, filePath);
+    assertValidTaskRecord(frontmatter, filePath, validStates);
+    return {
+        path: filePath,
+        frontmatter,
+        task: createTask(list, id, frontmatter, document.body)
+    };
+}
+async function findTaskLocation(fs, rootPath, list, id) {
+    const activePath = activeTaskPath(rootPath, list, id);
+    const activeStat = await statIfExists(fs, activePath);
+    if (activeStat?.isFile()) {
+        return {
+            archived: false,
+            path: activePath
+        };
+    }
+    const archivedPath = archivedTaskPath(rootPath, list, id);
+    const archivedStat = await statIfExists(fs, archivedPath);
+    if (archivedStat?.isFile()) {
+        return {
+            archived: true,
+            path: archivedPath
+        };
+    }
+    return undefined;
+}
+async function readTaskAtLocation(fs, rootPath, list, id, validStates) {
+    const location = await findTaskLocation(fs, rootPath, list, id);
+    if (!location) {
+        throw new TaskNotFoundError(`Task "${list}/${id}" not found.`);
+    }
+    return readTaskFile(fs, list, id, location.path, validStates);
+}
+function createdFrontmatter(defaults, input, initialState) {
+    const frontmatter = {
+        $schema: TASK_SCHEMA_ID,
+        kind: TASK_KIND,
+        version: TASK_VERSION,
+        name: input.name,
+        state: initialState
+    };
+    for (const [key, value] of Object.entries(defaults.metadata)) {
+        if (!RESERVED_FRONTMATTER_KEYS.has(key)) {
+            frontmatter[key] = value;
+        }
+    }
+    for (const [key, value] of Object.entries(input.metadata ?? {})) {
+        if (!RESERVED_FRONTMATTER_KEYS.has(key)) {
+            frontmatter[key] = value;
+        }
+    }
+    return frontmatter;
+}
+function updatedFrontmatter(existingFrontmatter, task, patch) {
+    const nextFrontmatter = {
+        ...existingFrontmatter,
+        $schema: existingFrontmatter.$schema ?? TASK_SCHEMA_ID,
+        kind: existingFrontmatter.kind ?? TASK_KIND,
+        version: existingFrontmatter.version ?? TASK_VERSION,
+        name: patch.name ?? task.name,
+        state: task.state
+    };
+    for (const [key, value] of Object.entries(patch.metadata ?? {})) {
+        if (!RESERVED_FRONTMATTER_KEYS.has(key)) {
+            nextFrontmatter[key] = value;
+        }
+    }
+    return nextFrontmatter;
+}
+function transitionedFrontmatter(existingFrontmatter, task, to) {
+    return {
+        ...existingFrontmatter,
+        $schema: existingFrontmatter.$schema ?? TASK_SCHEMA_ID,
+        kind: existingFrontmatter.kind ?? TASK_KIND,
+        version: existingFrontmatter.version ?? TASK_VERSION,
+        name: task.name,
+        state: to
+    };
+}
+function firedFrontmatter(existingFrontmatter, task, to, metadataPatch) {
+    const nextFrontmatter = transitionedFrontmatter(existingFrontmatter, task, to);
+    for (const [key, value] of Object.entries(metadataPatch ?? {})) {
+        if (!RESERVED_FRONTMATTER_KEYS.has(key)) {
+            nextFrontmatter[key] = value;
+        }
+    }
+    return nextFrontmatter;
+}
+function assertCreateDoesNotSetState(input) {
+    if (Object.prototype.hasOwnProperty.call(input, "state")) {
+        throw new Error('Tasks.create() does not accept "state"; new tasks always start at stateMachine.initial.');
+    }
+}
+function assertUpdateDoesNotSetState(patch) {
+    if (Object.prototype.hasOwnProperty.call(patch, "state")) {
+        throw new Error('Tasks.update() does not accept "state"; use fire() to change task state.');
+    }
+}
+function createTasksView(deps, list) {
+    const listDirectoryPath = listPath(deps.path, list);
+    const stateMachine = resolveStateMachine(deps.stateMachine);
+    const validStates = new Set(stateMachine.states);
+    async function listFiles(directoryPath) {
+        const entries = await readDirectoryNames(deps.fs, directoryPath);
+        const tasks = [];
+        for (const entryName of entries) {
+            if (isHiddenEntry(entryName) || isLockFile(entryName) || !isMarkdownFile(entryName)) {
+                continue;
+            }
+            const entryPath = path.join(directoryPath, entryName);
+            const entryStat = await statIfExists(deps.fs, entryPath);
+            if (!entryStat?.isFile()) {
+                continue;
+            }
+            const id = entryName.slice(0, -MARKDOWN_EXTENSION.length);
+            tasks.push((await readTaskFile(deps.fs, list, id, entryPath, validStates)).task);
+        }
+        return sortTasks(tasks);
+    }
+    async function withTaskLock(id, action) {
+        validateTaskId(id);
+        const release = await acquireFileLock(activeTaskPath(deps.path, list, id), {
+            fs: deps.fs,
+            staleMs: deps.lockStaleMs,
+            retries: deps.lockRetries
+        });
+        try {
+            return await action();
+        }
+        finally {
+            await release();
+        }
+    }
+    async function getTaskFile(id) {
+        validateTaskId(id);
+        return readTaskAtLocation(deps.fs, deps.path, list, id, validStates);
+    }
+    function assertFireableTaskEvent(task, eventName) {
+        const event = findEvent(stateMachine, task.state, eventName);
+        if (event === undefined) {
+            throw new InvalidTransitionError({
+                task,
+                event: eventName,
+                to: stateMachine.events[eventName]?.to,
+                reason: `Cannot fire event "${eventName}" from task state "${task.state}".`
+            });
+        }
+        return event;
+    }
+    return {
+        name: list,
+        stateMachine,
+        async all(filter) {
+            const activeTasks = await listFiles(listDirectoryPath);
+            const archivedTasks = filter?.includeArchived
+                ? await listFiles(archiveDirectoryPath(deps.path, list))
+                : [];
+            const combinedTasks = [...activeTasks, ...archivedTasks];
+            if (filter?.state) {
+                return combinedTasks.filter((task) => task.state === filter.state);
+            }
+            return combinedTasks;
+        },
+        async get(id) {
+            return (await getTaskFile(id)).task;
+        },
+        async create(input) {
+            assertCreateDoesNotSetState(input);
+            validateTaskId(input.id);
+            await deps.fs.mkdir(listDirectoryPath, { recursive: true });
+            return withTaskLock(input.id, async () => {
+                const existing = await findTaskLocation(deps.fs, deps.path, list, input.id);
+                if (existing) {
+                    throw new TaskAlreadyExistsError(`Task "${list}/${input.id}" already exists.`);
+                }
+                const targetPath = activeTaskPath(deps.path, list, input.id);
+                const frontmatter = createdFrontmatter(deps.defaults, input, stateMachine.initial);
+                const description = input.description ?? "";
+                await writeAtomically(deps.fs, targetPath, serializeTaskDocument(frontmatter, description));
+                return createTask(list, input.id, frontmatter, description);
+            });
+        },
+        async update(id, patch) {
+            assertUpdateDoesNotSetState(patch);
+            return withTaskLock(id, async () => {
+                const existing = await getTaskFile(id);
+                const nextFrontmatter = updatedFrontmatter(existing.frontmatter, existing.task, patch);
+                const description = patch.description ?? existing.task.description;
+                await writeAtomically(deps.fs, existing.path, serializeTaskDocument(nextFrontmatter, description));
+                return createTask(list, id, nextFrontmatter, description);
+            });
+        },
+        async fire(id, eventName, opts) {
+            return withTaskLock(id, async () => {
+                const existing = await getTaskFile(id);
+                const event = assertFireableTaskEvent(existing.task, eventName);
+                const guardResult = event.guard?.(existing.task) ?? true;
+                if (guardResult !== true) {
+                    throw new InvalidTransitionError({
+                        task: existing.task,
+                        event: eventName,
+                        to: event.to,
+                        reason: guardResult
+                    });
+                }
+                await event.onExit?.(existing.task);
+                const nextFrontmatter = firedFrontmatter(existing.frontmatter, existing.task, event.to, opts?.metadataPatch);
+                const nextTask = createTask(list, id, nextFrontmatter, existing.task.description);
+                const serializedTask = serializeTaskDocument(nextFrontmatter, existing.task.description);
+                if (event.to === "archived") {
+                    const targetPath = archivedTaskPath(deps.path, list, id);
+                    const archivedTargetExists = await statIfExists(deps.fs, targetPath);
+                    if (archivedTargetExists?.isFile()) {
+                        throw new TaskAlreadyExistsError(`Task "${list}/${id}" already exists in archive.`);
+                    }
+                    await writeAtomically(deps.fs, existing.path, serializedTask);
+                    await deps.fs.mkdir(archiveDirectoryPath(deps.path, list), { recursive: true });
+                    await deps.fs.rename(existing.path, targetPath);
+                    await event.onEnter?.(nextTask);
+                    return nextTask;
+                }
+                await writeAtomically(deps.fs, existing.path, serializedTask);
+                await event.onEnter?.(nextTask);
+                return nextTask;
+            });
+        },
+        async canFire(id, eventName) {
+            const task = (await getTaskFile(id)).task;
+            const event = findEvent(stateMachine, task.state, eventName);
+            if (event === undefined) {
+                return false;
+            }
+            return (event.guard?.(task) ?? true) === true;
+        },
+        async events(id) {
+            const task = (await getTaskFile(id)).task;
+            return eventsFromState(stateMachine, task.state);
+        },
+        async delete(id) {
+            await withTaskLock(id, async () => {
+                const location = await findTaskLocation(deps.fs, deps.path, list, id);
+                if (!location) {
+                    throw new TaskNotFoundError(`Task "${list}/${id}" not found.`);
+                }
+                await deps.fs.unlink(location.path);
+            });
+        }
+    };
+}
+export async function markdownDirBackend(deps) {
+    await ensureRootPath(deps);
+    const list = (name) => {
+        const listName = validateListName(name);
+        return createTasksView(deps, listName);
+    };
+    const lists = async () => {
+        const entries = await readDirectoryNames(deps.fs, deps.path);
+        const result = [];
+        for (const entryName of entries) {
+            if (entryName === ARCHIVE_DIRECTORY_NAME ||
+                isHiddenEntry(entryName) ||
+                isLockFile(entryName)) {
+                continue;
+            }
+            const entryPath = path.join(deps.path, entryName);
+            const entryStat = await statIfExists(deps.fs, entryPath);
+            if (entryStat?.isDirectory()) {
+                result.push(entryName);
+            }
+        }
+        return sortStrings(result);
+    };
+    const allTasks = async (filter) => {
+        const allLists = await lists();
+        const tasks = [];
+        for (const taskListName of allLists) {
+            tasks.push(...(await list(taskListName).all(filter)));
+        }
+        return sortTasks(tasks);
+    };
+    const get = async (qualifiedId) => {
+        const { list: listName, id } = parseQualifiedId(qualifiedId);
+        return list(listName).get(id);
+    };
+    return {
+        list,
+        lists,
+        allTasks,
+        get
+    };
+}

package/node_modules/@poe-code/task-list/dist/backends/utils.d.ts

@@ -0,0 +1,8 @@
+import type { Task, TaskListFs } from "../types.js";
+export declare function hasErrorCode(error: unknown, code: string): boolean;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function sortStrings(values: string[]): string[];
+export declare function sortTasks(tasks: Task[]): Task[];
+export declare function validateTaskId(id: string): string;
+export declare function statIfExists(fs: TaskListFs, filePath: string): Promise<Awaited<ReturnType<TaskListFs["stat"]>> | undefined>;
+export declare function writeAtomically(fs: TaskListFs, filePath: string, content: string): Promise<void>;

package/node_modules/@poe-code/task-list/dist/backends/utils.js

@@ -0,0 +1,58 @@
+import path from "node:path";
+let tmpFileCounter = 0;
+export function hasErrorCode(error, code) {
+    return (!!error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function sortStrings(values) {
+    return [...values].sort((left, right) => left.localeCompare(right));
+}
+export function sortTasks(tasks) {
+    return [...tasks].sort((left, right) => left.qualifiedId.localeCompare(right.qualifiedId));
+}
+export function validateTaskId(id) {
+    if (id.length === 0 ||
+        id.startsWith(".") ||
+        id.includes("/") ||
+        id.includes("\\") ||
+        id.includes("..")) {
+        throw new Error(`Invalid task id "${id}".`);
+    }
+    return id;
+}
+export async function statIfExists(fs, filePath) {
+    try {
+        return await fs.stat(filePath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function writeAtomically(fs, filePath, content) {
+    const tempPath = `${filePath}.tmp-${process.pid}-${tmpFileCounter}`;
+    tmpFileCounter += 1;
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    try {
+        await fs.writeFile(tempPath, content, { encoding: "utf8", flag: "wx" });
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            await fs.unlink(tempPath);
+        }
+        catch (unlinkError) {
+            if (!hasErrorCode(unlinkError, "ENOENT")) {
+                throw unlinkError;
+            }
+        }
+        throw error;
+    }
+}

package/node_modules/@poe-code/task-list/dist/backends/yaml-file.d.ts

@@ -0,0 +1,2 @@
+import { type BackendDeps, type TaskList } from "../types.js";
+export declare function yamlFileBackend(deps: BackendDeps): Promise<TaskList>;