agentplane 0.1.9 → 0.2.0

package/dist/backends/task-backend/redmine-backend.js

@@ -0,0 +1,505 @@
+import { canonicalizeJson } from "@agentplaneorg/core";
+import { isRecord } from "../../shared/guards.js";
+import { appendCommentNotes as appendCommentNotesImpl, normalizeComments as normalizeCommentsImpl, } from "./redmine/comments.js";
+import { requestJson as requestRedmineJson } from "./redmine/client.js";
+import { appendCustomField as appendRedmineCustomField, customFieldValue as redmineCustomFieldValue, setIssueCustomFieldValue as setRedmineIssueCustomFieldValue, } from "./redmine/fields.js";
+import { doneRatioForStatus, issueToTask as issueToTaskImpl, startDateFromTaskId, taskToIssuePayload as taskToIssuePayloadImpl, } from "./redmine/mapping.js";
+import { coerceDocVersion as coerceRedmineDocVersion, maybeParseJson as maybeParseRedmineJson, } from "./redmine/parse.js";
+import { findIssueByTaskId as findIssueByTaskIdImpl, listTasksRemote as listTasksRemoteImpl, } from "./redmine/remote.js";
+import { BackendError, DEFAULT_DOC_UPDATED_BY, DOC_VERSION, RedmineUnavailable, ensureDocMetadata, firstNonEmptyString, generateTaskId, mapLimit, missingTaskIdMessage, nowIso, redmineConfigMissingMessage, redmineIssueIdMissingMessage, sleep, toStringSafe, unknownTaskIdMessage, validateTaskId, writeTasksExportFromTasks, } from "./shared.js";
+export class RedmineBackend {
+    id = "redmine";
+    baseUrl;
+    apiKey;
+    projectId;
+    assigneeId;
+    ownerAgent;
+    statusMap;
+    customFields;
+    batchSize;
+    batchPause;
+    cache;
+    issueCache = new Map();
+    reverseStatus = new Map();
+    constructor(settings, opts) {
+        const envUrl = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_URL);
+        const envApiKey = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_API_KEY);
+        const envProjectId = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_PROJECT_ID);
+        const envAssignee = (process.env.AGENTPLANE_REDMINE_ASSIGNEE_ID ?? "").trim();
+        const envOwner = firstNonEmptyString(process.env.AGENTPLANE_REDMINE_OWNER, process.env.AGENTPLANE_REDMINE_OWNER_AGENT);
+        this.baseUrl = firstNonEmptyString(envUrl, settings.url).replaceAll(/\/+$/gu, "");
+        this.apiKey = firstNonEmptyString(envApiKey, settings.api_key);
+        this.projectId = firstNonEmptyString(envProjectId, settings.project_id);
+        this.assigneeId = envAssignee && /^\d+$/u.test(envAssignee) ? Number(envAssignee) : null;
+        this.statusMap = isRecord(settings.status_map) ? settings.status_map : {};
+        this.customFields = isRecord(settings.custom_fields) ? settings.custom_fields : {};
+        this.batchSize = typeof settings.batch_size === "number" ? settings.batch_size : 20;
+        this.batchPause = typeof settings.batch_pause === "number" ? settings.batch_pause : 0.5;
+        this.ownerAgent = firstNonEmptyString(envOwner, settings.owner_agent, "REDMINE");
+        this.cache = opts.cache ?? null;
+        if (!this.baseUrl || !this.apiKey || !this.projectId) {
+            throw new BackendError(redmineConfigMissingMessage("url, api_key, project_id"), "E_BACKEND");
+        }
+        if (!this.customFields?.task_id) {
+            throw new BackendError(redmineConfigMissingMessage("custom_fields.task_id"), "E_BACKEND");
+        }
+        for (const [key, value] of Object.entries(this.statusMap)) {
+            if (typeof value === "number")
+                this.reverseStatus.set(value, key);
+        }
+    }
+    async generateTaskId(opts) {
+        const length = opts.length;
+        const attempts = opts.attempts;
+        let existingIds = new Set();
+        try {
+            const tasks = await this.listTasksRemote();
+            existingIds = new Set(tasks.map((task) => toStringSafe(task.id)).filter(Boolean));
+        }
+        catch (err) {
+            if (!(err instanceof RedmineUnavailable))
+                throw err;
+            if (!this.cache)
+                throw err;
+            const cached = await this.cache.listTasks();
+            existingIds = new Set(cached.map((task) => toStringSafe(task.id)).filter(Boolean));
+        }
+        return await generateTaskId({
+            length,
+            attempts,
+            isAvailable: (taskId) => !existingIds.has(taskId),
+        });
+    }
+    async listTasks() {
+        try {
+            const tasks = await this.listTasksRemote();
+            for (const task of tasks) {
+                await this.cacheTask(task, false);
+            }
+            return tasks;
+        }
+        catch (err) {
+            if (err instanceof RedmineUnavailable) {
+                if (!this.cache)
+                    throw err;
+                return await this.cache.listTasks();
+            }
+            throw err;
+        }
+    }
+    async exportTasksJson(outputPath) {
+        const tasks = await this.listTasks();
+        await writeTasksExportFromTasks({ outputPath, tasks });
+    }
+    async normalizeTasks() {
+        // Remote backends should avoid expensive downloads; best-effort normalize the local cache if present.
+        if (this.cache?.normalizeTasks)
+            return await this.cache.normalizeTasks();
+        return { scanned: 0, changed: 0 };
+    }
+    async getTask(taskId) {
+        try {
+            const issue = await this.findIssueByTaskId(taskId);
+            if (!issue)
+                return null;
+            const task = this.issueToTask(issue, taskId);
+            if (task)
+                await this.cacheTask(task, false);
+            return task;
+        }
+        catch (err) {
+            if (err instanceof RedmineUnavailable) {
+                if (!this.cache)
+                    throw err;
+                const cached = await this.cache.getTask(taskId);
+                return cached ?? null;
+            }
+            throw err;
+        }
+    }
+    async getTasks(taskIds) {
+        // Use limited parallelism to avoid hammering the Redmine API.
+        return await mapLimit(taskIds, this.batchSize, async (taskId) => await this.getTask(taskId));
+    }
+    async getTaskDoc(taskId) {
+        const task = await this.getTask(taskId);
+        if (!task)
+            throw new Error(unknownTaskIdMessage(taskId));
+        return toStringSafe(task.doc);
+    }
+    async setTaskDoc(taskId, doc, updatedBy) {
+        if (!this.customFields.doc) {
+            throw new BackendError(redmineConfigMissingMessage("custom_fields.doc"), "E_BACKEND");
+        }
+        try {
+            const issue = await this.findIssueByTaskId(taskId);
+            if (!issue)
+                throw new Error(unknownTaskIdMessage(taskId));
+            const issueIdText = toStringSafe(issue.id);
+            if (!issueIdText)
+                throw new Error(redmineIssueIdMissingMessage());
+            const taskDoc = { doc: String(doc ?? "") };
+            ensureDocMetadata(taskDoc, updatedBy);
+            const customFields = [];
+            this.appendCustomField(customFields, "doc", taskDoc.doc);
+            this.appendCustomField(customFields, "doc_version", taskDoc.doc_version);
+            this.appendCustomField(customFields, "doc_updated_at", taskDoc.doc_updated_at);
+            this.appendCustomField(customFields, "doc_updated_by", taskDoc.doc_updated_by);
+            await this.requestJson("PUT", `issues/${issueIdText}.json`, {
+                issue: { custom_fields: customFields },
+            });
+            const task = this.issueToTask(issue, taskId);
+            if (task) {
+                task.doc = taskDoc.doc;
+                task.doc_version = taskDoc.doc_version;
+                task.doc_updated_at = taskDoc.doc_updated_at;
+                task.doc_updated_by = taskDoc.doc_updated_by;
+                await this.cacheTask(task, false);
+            }
+        }
+        catch (err) {
+            if (err instanceof RedmineUnavailable) {
+                if (!this.cache)
+                    throw err;
+                const cached = await this.cache.getTask(taskId);
+                if (!cached)
+                    throw new Error(unknownTaskIdMessage(taskId));
+                cached.doc = String(doc ?? "");
+                ensureDocMetadata(cached, updatedBy);
+                cached.dirty = true;
+                await this.cache.writeTask(cached);
+                return;
+            }
+            throw err;
+        }
+    }
+    async touchTaskDocMetadata(taskId, updatedBy) {
+        try {
+            const issue = await this.findIssueByTaskId(taskId);
+            if (!issue)
+                throw new Error(unknownTaskIdMessage(taskId));
+            const issueIdText = toStringSafe(issue.id);
+            if (!issueIdText)
+                throw new Error(redmineIssueIdMissingMessage());
+            const docValue = this.customFieldValue(issue, this.customFields.doc);
+            const taskDoc = { doc: docValue ?? "" };
+            ensureDocMetadata(taskDoc, updatedBy);
+            const customFields = [];
+            this.appendCustomField(customFields, "doc_version", taskDoc.doc_version);
+            this.appendCustomField(customFields, "doc_updated_at", taskDoc.doc_updated_at);
+            this.appendCustomField(customFields, "doc_updated_by", taskDoc.doc_updated_by);
+            if (customFields.length > 0) {
+                await this.requestJson("PUT", `issues/${issueIdText}.json`, {
+                    issue: { custom_fields: customFields },
+                });
+                const task = this.issueToTask(issue, taskId);
+                if (task) {
+                    task.doc_version = taskDoc.doc_version;
+                    task.doc_updated_at = taskDoc.doc_updated_at;
+                    task.doc_updated_by = taskDoc.doc_updated_by;
+                    await this.cacheTask(task, false);
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof RedmineUnavailable) {
+                if (!this.cache)
+                    throw err;
+                const cached = await this.cache.getTask(taskId);
+                if (!cached)
+                    throw new Error(unknownTaskIdMessage(taskId));
+                ensureDocMetadata(cached, updatedBy);
+                cached.dirty = true;
+                await this.cache.writeTask(cached);
+                return;
+            }
+            throw err;
+        }
+    }
+    async writeTask(task) {
+        const taskId = toStringSafe(task.id).trim();
+        if (!taskId)
+            throw new Error(missingTaskIdMessage());
+        validateTaskId(taskId);
+        try {
+            this.ensureDocMetadata(task);
+            let issue = await this.findIssueByTaskId(taskId);
+            let issueId = issue?.id;
+            let issueIdText = issueId ? toStringSafe(issueId) : "";
+            let existingIssue = issue ?? null;
+            if (issueIdText && !existingIssue) {
+                const payload = await this.requestJson("GET", `issues/${issueIdText}.json`);
+                existingIssue = this.issueFromPayload(payload);
+            }
+            const payload = this.taskToIssuePayload(task, existingIssue ?? undefined);
+            if (issueIdText) {
+                await this.requestJson("PUT", `issues/${issueIdText}.json`, { issue: payload });
+            }
+            else {
+                const createPayload = { ...payload, project_id: this.projectId };
+                const created = await this.requestJson("POST", "issues.json", { issue: createPayload });
+                const createdIssue = this.issueFromPayload(created);
+                issueId = createdIssue?.id;
+                issueIdText = issueId ? toStringSafe(issueId) : "";
+                if (issueIdText) {
+                    const updatePayload = { ...payload };
+                    delete updatePayload.project_id;
+                    await this.requestJson("PUT", `issues/${issueIdText}.json`, { issue: updatePayload });
+                    const refreshed = await this.requestJson("GET", `issues/${issueIdText}.json`);
+                    existingIssue = this.issueFromPayload(refreshed);
+                }
+            }
+            if (issueIdText) {
+                const existingComments = existingIssue && this.customFields.comments
+                    ? this.normalizeComments(this.maybeParseJson(this.customFieldValue(existingIssue, this.customFields.comments)))
+                    : [];
+                const desiredComments = this.normalizeComments(task.comments);
+                await this.appendCommentNotes(issueIdText, existingComments, desiredComments);
+            }
+            task.dirty = false;
+            await this.cacheTask(task, false);
+            this.issueCache.clear();
+        }
+        catch (err) {
+            if (err instanceof RedmineUnavailable) {
+                if (!this.cache)
+                    throw err;
+                task.dirty = true;
+                await this.cacheTask(task, true);
+                return;
+            }
+            throw err;
+        }
+    }
+    async writeTasks(tasks) {
+        for (const [index, task] of tasks.entries()) {
+            await this.writeTask(task);
+            if (this.batchPause && this.batchSize > 0 && (index + 1) % this.batchSize === 0) {
+                await sleep(this.batchPause * 1000);
+            }
+        }
+    }
+    async sync(opts) {
+        if (opts.direction === "push") {
+            await this.syncPush(opts.quiet, opts.confirm);
+            return;
+        }
+        if (opts.direction === "pull") {
+            await this.syncPull(opts.conflict, opts.quiet);
+            return;
+        }
+        throw new BackendError("Invalid sync direction (expected push|pull)", "E_BACKEND");
+    }
+    ensureDocMetadata(task) {
+        if (task.doc === undefined)
+            return;
+        if (task.doc_version !== DOC_VERSION)
+            task.doc_version = DOC_VERSION;
+        task.doc_updated_at ??= nowIso();
+        task.doc_updated_by ??= DEFAULT_DOC_UPDATED_BY;
+    }
+    async syncPush(quiet, confirm) {
+        if (!this.cache) {
+            throw new BackendError("Redmine cache is disabled; sync push is unavailable", "E_BACKEND");
+        }
+        const tasks = await this.cache.listTasks();
+        const dirty = tasks.filter((task) => task.dirty);
+        if (dirty.length === 0) {
+            if (!quiet)
+                process.stdout.write("ℹ️ no local task changes to push\n");
+            return;
+        }
+        if (!confirm) {
+            for (const task of dirty) {
+                process.stdout.write(`- pending push: ${task.id}\n`);
+            }
+            throw new BackendError("Refusing to push without --yes (preview above)", "E_BACKEND");
+        }
+        await this.writeTasks(dirty);
+        if (!quiet)
+            process.stdout.write(`✅ pushed ${dirty.length} task(s) (dirty)\n`);
+    }
+    async syncPull(conflict, quiet) {
+        if (!this.cache) {
+            throw new BackendError("Redmine cache is disabled; sync pull is unavailable", "E_BACKEND");
+        }
+        const remoteTasks = await this.listTasksRemote();
+        const remoteById = new Map();
+        for (const task of remoteTasks) {
+            const taskId = toStringSafe(task.id);
+            if (taskId)
+                remoteById.set(taskId, task);
+        }
+        const localTasks = await this.cache.listTasks();
+        const localById = new Map();
+        for (const task of localTasks) {
+            const taskId = toStringSafe(task.id);
+            if (taskId)
+                localById.set(taskId, task);
+        }
+        for (const [taskId, remoteTask] of remoteById.entries()) {
+            const localTask = localById.get(taskId);
+            if (localTask?.dirty) {
+                if (this.tasksDiffer(localTask, remoteTask)) {
+                    await this.handleConflict(taskId, localTask, remoteTask, conflict);
+                    continue;
+                }
+                localTask.dirty = false;
+                await this.cacheTask(localTask, false);
+                continue;
+            }
+            await this.cacheTask(remoteTask, false);
+        }
+        if (!quiet)
+            process.stdout.write(`✅ pulled ${remoteById.size} task(s) (remote)\n`);
+    }
+    async handleConflict(taskId, localTask, remoteTask, conflict) {
+        if (conflict === "prefer-local") {
+            await this.writeTask(localTask);
+            return;
+        }
+        if (conflict === "prefer-remote") {
+            await this.cacheTask(remoteTask, false);
+            return;
+        }
+        if (conflict === "diff") {
+            const diff = this.diffTasks(localTask, remoteTask);
+            process.stdout.write(`${diff}\n`);
+            throw new BackendError(`Conflict detected for ${taskId}`, "E_BACKEND");
+        }
+        throw new BackendError(`Conflict detected for ${taskId}`, "E_BACKEND");
+    }
+    diffTasks(localTask, remoteTask) {
+        const localText = JSON.stringify(canonicalizeJson(localTask), null, 2).split("\n");
+        const remoteText = JSON.stringify(canonicalizeJson(remoteTask), null, 2).split("\n");
+        const diff = ["--- remote", "+++ local"];
+        const max = Math.max(localText.length, remoteText.length);
+        for (let i = 0; i < max; i++) {
+            const l = localText[i];
+            const r = remoteText[i];
+            if (l === r)
+                continue;
+            if (r !== undefined)
+                diff.push(`- ${r}`);
+            if (l !== undefined)
+                diff.push(`+ ${l}`);
+        }
+        return diff.join("\n");
+    }
+    tasksDiffer(localTask, remoteTask) {
+        const localText = JSON.stringify(canonicalizeJson(localTask));
+        const remoteText = JSON.stringify(canonicalizeJson(remoteTask));
+        return localText !== remoteText;
+    }
+    async cacheTask(task, dirty) {
+        if (!this.cache)
+            return;
+        const next = { ...task, dirty };
+        await this.cache.writeTask(next);
+    }
+    taskIdFieldId() {
+        const fieldId = this.customFields?.task_id;
+        if (fieldId)
+            return fieldId;
+        throw new BackendError(redmineConfigMissingMessage("custom_fields.task_id"), "E_BACKEND");
+    }
+    setIssueCustomFieldValue(issue, fieldId, value) {
+        setRedmineIssueCustomFieldValue(issue, fieldId, value);
+    }
+    async listTasksRemote() {
+        const taskFieldId = this.taskIdFieldId();
+        return await listTasksRemoteImpl({
+            projectId: this.projectId,
+            taskFieldId,
+            issueCache: this.issueCache,
+            requestJson: async (method, reqPath, payload, params) => await this.requestJson(method, reqPath, payload, params),
+            customFieldValue: (issue, fieldId) => this.customFieldValue(issue, fieldId),
+            issueToTask: (issue, taskIdOverride) => this.issueToTask(issue, taskIdOverride),
+        });
+    }
+    issueFromPayload(payload) {
+        return isRecord(payload.issue) ? payload.issue : null;
+    }
+    async findIssueByTaskId(taskId) {
+        const taskFieldId = this.taskIdFieldId();
+        return await findIssueByTaskIdImpl({
+            taskId,
+            projectId: this.projectId,
+            taskFieldId,
+            issueCache: this.issueCache,
+            requestJson: async (method, reqPath, payload, params) => await this.requestJson(method, reqPath, payload, params),
+            customFieldValue: (issue, fieldId) => this.customFieldValue(issue, fieldId),
+            refreshList: async () => {
+                await this.listTasksRemote();
+            },
+        });
+    }
+    issueToTask(issue, taskIdOverride) {
+        return issueToTaskImpl({
+            issue,
+            taskIdOverride,
+            reverseStatus: this.reverseStatus,
+            customFields: this.customFields,
+            ownerAgent: this.ownerAgent,
+            defaultDocVersion: DOC_VERSION,
+        });
+    }
+    taskToIssuePayload(task, existingIssue) {
+        return taskToIssuePayloadImpl({
+            task,
+            existingIssue,
+            statusMap: this.statusMap,
+            assigneeId: this.assigneeId,
+            customFields: this.customFields,
+            appendCustomField: (fields, key, value) => this.appendCustomField(fields, key, value),
+        });
+    }
+    appendCustomField(fields, key, value) {
+        appendRedmineCustomField({ customFields: this.customFields, fields, key, value });
+    }
+    normalizeComments(value) {
+        return normalizeCommentsImpl(value);
+    }
+    async appendCommentNotes(issueId, existingComments, desiredComments) {
+        await appendCommentNotesImpl({
+            issueId,
+            existingComments,
+            desiredComments,
+            requestJson: async (method, reqPath, payload, params) => await this.requestJson(method, reqPath, payload, params),
+        });
+    }
+    startDateFromTaskId(taskId) {
+        return startDateFromTaskId(taskId);
+    }
+    doneRatioForStatus(status) {
+        return doneRatioForStatus(status);
+    }
+    commentsToPairs(comments) {
+        const pairs = [];
+        for (const comment of comments) {
+            const author = toStringSafe(comment.author).trim();
+            const body = toStringSafe(comment.body).trim();
+            if (!author && !body)
+                continue;
+            pairs.push([author, body]);
+        }
+        return pairs;
+    }
+    formatCommentNote(author = "unknown", body = "") {
+        const authorText = author;
+        const bodyText = body;
+        return `[comment] ${authorText}: ${bodyText}`.trim();
+    }
+    customFieldValue(issue, fieldId) {
+        return redmineCustomFieldValue(issue, fieldId);
+    }
+    maybeParseJson(value) {
+        return maybeParseRedmineJson(value);
+    }
+    coerceDocVersion(value) {
+        return coerceRedmineDocVersion(value);
+    }
+    async requestJson(method, reqPath, payload, params, opts) {
+        return await requestRedmineJson({ baseUrl: this.baseUrl, apiKey: this.apiKey }, method, reqPath, payload, params, opts);
+    }
+}

package/dist/backends/task-backend/shared/concurrency.d.ts

@@ -0,0 +1,3 @@
+export declare function sleep(ms: number): Promise<void>;
+export declare function mapLimit<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/backends/task-backend/shared/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/concurrency.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAkBd"}

package/dist/backends/task-backend/shared/concurrency.js

@@ -0,0 +1,21 @@
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function mapLimit(items, limit, fn) {
+    const bounded = Math.max(1, Math.floor(limit));
+    const out = [];
+    out.length = items.length;
+    let nextIndex = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = nextIndex;
+            nextIndex++;
+            if (i >= items.length)
+                return;
+            out[i] = await fn(items[i], i);
+        }
+    };
+    const workers = Array.from({ length: Math.min(bounded, items.length) }, () => worker());
+    await Promise.all(workers);
+    return out;
+}

package/dist/backends/task-backend/shared/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const TASK_ID_RE: RegExp;
+export declare const DEFAULT_DOC_UPDATED_BY = "agentplane";
+export declare const DOC_VERSION = 2;
+//# sourceMappingURL=constants.d.ts.map

package/dist/backends/task-backend/shared/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,QAA6D,CAAC;AACrF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AACnD,eAAO,MAAM,WAAW,IAAI,CAAC"}

package/dist/backends/task-backend/shared/constants.js

@@ -0,0 +1,4 @@
+import { TASK_ID_ALPHABET } from "@agentplaneorg/core";
+export const TASK_ID_RE = new RegExp(String.raw `^\d{12}-[${TASK_ID_ALPHABET}]{4,}$`);
+export const DEFAULT_DOC_UPDATED_BY = "agentplane";
+export const DOC_VERSION = 2;

package/dist/backends/task-backend/shared/doc.d.ts

@@ -0,0 +1,11 @@
+import type { TaskData, TaskDocMeta } from "./types.js";
+type ExtractTaskDoc = (body: string) => string;
+type MergeTaskDoc = (body: string, doc: string) => string;
+declare const extractTaskDoc: ExtractTaskDoc;
+declare const mergeTaskDoc: MergeTaskDoc;
+export declare function nowIso(): string;
+export declare function resolveDocUpdatedByFromFrontmatter(frontmatter: Record<string, unknown>, updatedBy: string | undefined, fallback: string): string;
+export declare function resolveDocUpdatedByFromTask(task: TaskData, fallback: string): string;
+export declare function ensureDocMetadata(task: TaskDocMeta & Partial<Pick<TaskData, "comments" | "owner">>, updatedBy?: string): void;
+export { extractTaskDoc, mergeTaskDoc };
+//# sourceMappingURL=doc.d.ts.map

package/dist/backends/task-backend/shared/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/doc.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,KAAK,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAC/C,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAE1D,QAAA,MAAM,cAAc,EAAE,cAAmC,CAAC;AAC1D,QAAA,MAAM,YAAY,EAAE,YAA+B,CAAC;AAEpD,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAyBD,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,MAAM,CAaR;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CASpF;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,EACjE,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CAUN;AAED,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC"}

package/dist/backends/task-backend/shared/doc.js

@@ -0,0 +1,78 @@
+import { extractTaskDoc as extractTaskDocCore, mergeTaskDoc as mergeTaskDocCore, } from "@agentplaneorg/core";
+import { isRecord } from "../../../shared/guards.js";
+import { DEFAULT_DOC_UPDATED_BY, DOC_VERSION } from "./constants.js";
+const extractTaskDoc = extractTaskDocCore;
+const mergeTaskDoc = mergeTaskDocCore;
+export function nowIso() {
+    return new Date().toISOString();
+}
+function normalizeUpdatedBy(value) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.toLowerCase() === DEFAULT_DOC_UPDATED_BY.toLowerCase())
+        return "";
+    return trimmed;
+}
+function lastCommentAuthor(comments) {
+    if (!Array.isArray(comments))
+        return null;
+    const entries = comments;
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        if (!isRecord(entry))
+            continue;
+        const author = entry.author;
+        if (typeof author === "string") {
+            const trimmed = author.trim();
+            if (trimmed)
+                return trimmed;
+        }
+    }
+    return null;
+}
+export function resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, fallback) {
+    if (updatedBy !== undefined) {
+        const explicit = normalizeUpdatedBy(updatedBy);
+        if (explicit)
+            return explicit;
+    }
+    const author = lastCommentAuthor(frontmatter.comments);
+    if (author)
+        return author;
+    const existing = normalizeUpdatedBy(frontmatter.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(frontmatter.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
+}
+export function resolveDocUpdatedByFromTask(task, fallback) {
+    const author = lastCommentAuthor(task.comments);
+    if (author)
+        return author;
+    const existing = normalizeUpdatedBy(task.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(task.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
+}
+export function ensureDocMetadata(task, updatedBy) {
+    task.doc_version = DOC_VERSION;
+    task.doc_updated_at = nowIso();
+    const explicit = normalizeUpdatedBy(updatedBy);
+    if (updatedBy !== undefined) {
+        task.doc_updated_by =
+            explicit || resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
+        return;
+    }
+    task.doc_updated_by = resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
+}
+export { extractTaskDoc, mergeTaskDoc };

package/dist/backends/task-backend/shared/errors.d.ts

@@ -0,0 +1,10 @@
+export declare class BackendError extends Error {
+    code: "E_BACKEND" | "E_NETWORK";
+    constructor(message: string, code: "E_BACKEND" | "E_NETWORK");
+}
+export declare class RedmineUnavailable extends BackendError {
+    constructor(message: string);
+}
+export declare function redmineConfigMissingMessage(detail: string): string;
+export declare function redmineIssueIdMissingMessage(): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/backends/task-backend/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;IACrC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;gBACpB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,WAAW;CAI7D;AAED,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,EAAE,MAAM;CAG5B;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,4BAA4B,IAAI,MAAM,CAErD"}

package/dist/backends/task-backend/shared/errors.js

@@ -0,0 +1,18 @@
+export class BackendError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export class RedmineUnavailable extends BackendError {
+    constructor(message) {
+        super(message, "E_NETWORK");
+    }
+}
+export function redmineConfigMissingMessage(detail) {
+    return `Missing required Redmine config: ${detail}`;
+}
+export function redmineIssueIdMissingMessage() {
+    return "Missing Redmine issue id for task";
+}