@evref-bl/dev-nexus 0.1.0-alpha.0

package/dist/workTrackingLocalProvider.js

@@ -0,0 +1,463 @@
+import fs from "node:fs";
+import path from "node:path";
+export const localWorkTrackingDirectoryName = ".dev-nexus";
+export const localWorkTrackingStoreFileName = "work-items.json";
+export const localWorkTrackingStoreVersion = 1;
+const workStatuses = new Set([
+    "todo",
+    "ready",
+    "in_progress",
+    "blocked",
+    "done",
+    "wont_do",
+]);
+export class LocalWorkTrackerProviderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LocalWorkTrackerProviderError";
+    }
+}
+export const localWorkTrackerCapabilities = {
+    createItem: true,
+    listItems: true,
+    getItem: true,
+    updateItem: true,
+    comment: true,
+    labels: true,
+    assignees: true,
+    milestones: true,
+    board: false,
+    boardStatus: false,
+    draftItems: false,
+    webhooks: false,
+};
+export function defaultLocalWorkTrackingStorePath(projectRoot) {
+    return path.join(resolveProjectRoot(projectRoot), localWorkTrackingDirectoryName, localWorkTrackingStoreFileName);
+}
+export function resolveLocalWorkTrackingStorePath(projectRoot, config) {
+    const configuredStorePath = typeof config === "string" || config === null
+        ? config
+        : config?.storePath;
+    if (!configuredStorePath) {
+        return defaultLocalWorkTrackingStorePath(projectRoot);
+    }
+    return path.isAbsolute(configuredStorePath)
+        ? path.resolve(configuredStorePath)
+        : path.resolve(resolveProjectRoot(projectRoot), configuredStorePath);
+}
+export function createLocalWorkTrackerProvider(options = {}) {
+    return new LocalWorkTrackerProvider(options);
+}
+export class LocalWorkTrackerProvider {
+    provider = "local";
+    capabilities = localWorkTrackerCapabilities;
+    projectRoot;
+    config;
+    storePath;
+    nowProvider;
+    constructor(options = {}) {
+        this.projectRoot = options.projectRoot;
+        this.config = options.config;
+        this.storePath = options.storePath;
+        this.nowProvider = options.now ?? (() => new Date());
+    }
+    async detect(input) {
+        const storePath = this.storePathFor(input.projectRoot);
+        if (!fs.existsSync(storePath)) {
+            return undefined;
+        }
+        return {
+            confidence: "high",
+            config: {
+                provider: "local",
+                storePath: path.relative(resolveProjectRoot(input.projectRoot), storePath),
+            },
+            reason: "Found local DevNexus work item store",
+        };
+    }
+    async ensureProject(context) {
+        const projectRoot = this.resolveProjectRoot(context.projectRoot);
+        const store = this.loadStore(projectRoot);
+        this.saveStore(projectRoot, store);
+        return {
+            provider: "local",
+            id: context.projectId,
+            name: context.projectName,
+            externalRef: {
+                provider: "local",
+                itemId: context.projectId,
+                projectId: context.projectId,
+            },
+        };
+    }
+    async createWorkItem(input) {
+        const projectRoot = this.resolveProjectRoot(input.projectRoot);
+        const store = this.loadStore(projectRoot);
+        const number = store.nextNumber;
+        const id = `local-${number}`;
+        const timestamp = this.now();
+        const status = input.status ?? "todo";
+        assertWorkStatus(status);
+        const item = {
+            id,
+            title: requiredNonEmptyString(input.title, "title"),
+            description: input.description ?? null,
+            status,
+            provider: "local",
+            labels: normalizeStringArray(input.labels, "labels"),
+            assignees: normalizeStringArray(input.assignees, "assignees"),
+            milestone: optionalNullableString(input.milestone, "milestone") ?? null,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            closedAt: isClosedStatus(status) ? timestamp : null,
+            webUrl: null,
+            externalRef: {
+                provider: "local",
+                itemId: id,
+                itemNumber: number,
+            },
+        };
+        store.items.push(item);
+        store.comments[item.id] = [];
+        store.nextNumber += 1;
+        this.saveStore(projectRoot, store);
+        return item;
+    }
+    async listWorkItems(query = {}) {
+        const projectRoot = this.resolveProjectRoot(query.projectRoot);
+        const statuses = query.status === undefined
+            ? undefined
+            : new Set(Array.isArray(query.status) ? query.status : [query.status]);
+        if (statuses) {
+            for (const status of statuses) {
+                assertWorkStatus(status);
+            }
+        }
+        const labels = normalizeStringArray(query.labels, "labels");
+        const assignees = normalizeStringArray(query.assignees, "assignees");
+        const search = query.search?.trim().toLowerCase();
+        const limit = normalizeLimit(query.limit);
+        let items = this.loadStore(projectRoot).items.filter((item) => {
+            if (statuses && !statuses.has(item.status)) {
+                return false;
+            }
+            if (labels.some((label) => !item.labels?.includes(label))) {
+                return false;
+            }
+            if (assignees.some((assignee) => !item.assignees?.includes(assignee))) {
+                return false;
+            }
+            if (search && !matchesSearch(item, search)) {
+                return false;
+            }
+            return true;
+        });
+        if (limit !== undefined) {
+            items = items.slice(0, limit);
+        }
+        return items;
+    }
+    async getWorkItem(ref) {
+        const store = this.loadStore(this.resolveProjectRoot());
+        return findWorkItem(store, ref);
+    }
+    async updateWorkItem(ref, patch) {
+        const projectRoot = this.resolveProjectRoot();
+        const store = this.loadStore(projectRoot);
+        const item = findWorkItem(store, ref);
+        const timestamp = this.now();
+        const updated = {
+            ...item,
+            updatedAt: timestamp,
+        };
+        if (patch.title !== undefined) {
+            updated.title = requiredNonEmptyString(patch.title, "title");
+        }
+        if (patch.description !== undefined) {
+            updated.description = patch.description;
+        }
+        if (patch.status !== undefined) {
+            assertWorkStatus(patch.status);
+            updated.status = patch.status;
+            updated.closedAt = isClosedStatus(patch.status)
+                ? item.closedAt ?? timestamp
+                : null;
+        }
+        if (patch.labels !== undefined) {
+            updated.labels = normalizeStringArray(patch.labels, "labels");
+        }
+        if (patch.assignees !== undefined) {
+            updated.assignees = normalizeStringArray(patch.assignees, "assignees");
+        }
+        if (patch.milestone !== undefined) {
+            updated.milestone = optionalNullableString(patch.milestone, "milestone");
+        }
+        store.items[store.items.indexOf(item)] = updated;
+        this.saveStore(projectRoot, store);
+        return updated;
+    }
+    async addComment(ref, body) {
+        const projectRoot = this.resolveProjectRoot();
+        const store = this.loadStore(projectRoot);
+        const item = findWorkItem(store, ref);
+        const timestamp = this.now();
+        const id = `local-comment-${store.nextCommentNumber}`;
+        const comment = {
+            id,
+            body: requiredNonEmptyString(body, "body"),
+            author: null,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            externalRef: {
+                provider: "local",
+                itemId: id,
+            },
+        };
+        store.nextCommentNumber += 1;
+        store.comments[item.id] = [...(store.comments[item.id] ?? []), comment];
+        item.updatedAt = timestamp;
+        this.saveStore(projectRoot, store);
+        return comment;
+    }
+    async setStatus(ref, status) {
+        return this.updateWorkItem(ref, { status });
+    }
+    resolveProjectRoot(projectRoot) {
+        return resolveProjectRoot(projectRoot ?? this.projectRoot);
+    }
+    storePathFor(projectRoot) {
+        return resolveLocalWorkTrackingStorePath(projectRoot, this.storePath ?? this.config);
+    }
+    loadStore(projectRoot) {
+        return loadLocalWorkTrackingStore(this.storePathFor(projectRoot), this.now());
+    }
+    saveStore(projectRoot, store) {
+        saveLocalWorkTrackingStore(this.storePathFor(projectRoot), {
+            ...store,
+            updatedAt: this.now(),
+        });
+    }
+    now() {
+        const value = this.nowProvider();
+        return typeof value === "string" ? value : value.toISOString();
+    }
+}
+export function loadLocalWorkTrackingStore(storePath, timestamp = new Date().toISOString()) {
+    if (!fs.existsSync(storePath)) {
+        return emptyStore(timestamp);
+    }
+    const raw = JSON.parse(fs.readFileSync(storePath, "utf8").replace(/^\uFEFF/, ""));
+    return validateStore(raw);
+}
+export function saveLocalWorkTrackingStore(storePath, store) {
+    fs.mkdirSync(path.dirname(storePath), { recursive: true });
+    fs.writeFileSync(storePath, `${JSON.stringify(validateStore(store), null, 2)}\n`, "utf8");
+}
+function emptyStore(timestamp) {
+    return {
+        version: localWorkTrackingStoreVersion,
+        nextNumber: 1,
+        nextCommentNumber: 1,
+        updatedAt: timestamp,
+        items: [],
+        comments: {},
+    };
+}
+function resolveProjectRoot(projectRoot) {
+    if (!projectRoot || projectRoot.trim().length === 0) {
+        throw new LocalWorkTrackerProviderError("projectRoot is required");
+    }
+    return path.resolve(projectRoot);
+}
+function validateStore(value) {
+    const record = assertRecord(value, "local work tracking store");
+    if (record.version !== localWorkTrackingStoreVersion) {
+        throw new LocalWorkTrackerProviderError(`local work tracking store.version must be ${localWorkTrackingStoreVersion}`);
+    }
+    const items = record.items;
+    if (!Array.isArray(items)) {
+        throw new LocalWorkTrackerProviderError("local work tracking store.items must be an array");
+    }
+    return {
+        version: localWorkTrackingStoreVersion,
+        nextNumber: positiveInteger(record.nextNumber, "nextNumber"),
+        nextCommentNumber: positiveInteger(record.nextCommentNumber, "nextCommentNumber"),
+        updatedAt: requiredNonEmptyString(record.updatedAt, "updatedAt"),
+        items: items.map(validateWorkItem),
+        comments: validateComments(record.comments),
+    };
+}
+function validateWorkItem(value, index) {
+    const record = assertRecord(value, `items[${index}]`);
+    if (record.provider !== "local") {
+        throw new LocalWorkTrackerProviderError(`items[${index}].provider must be local`);
+    }
+    const status = workStatus(record.status, `items[${index}].status`);
+    return {
+        id: requiredNonEmptyString(record.id, `items[${index}].id`),
+        title: requiredNonEmptyString(record.title, `items[${index}].title`),
+        description: optionalNullableText(record.description, `items[${index}].description`) ??
+            null,
+        status,
+        provider: "local",
+        labels: stringArray(record.labels, `items[${index}].labels`),
+        assignees: stringArray(record.assignees, `items[${index}].assignees`),
+        milestone: optionalNullableString(record.milestone, `items[${index}].milestone`) ??
+            null,
+        createdAt: optionalNullableString(record.createdAt, `items[${index}].createdAt`) ??
+            null,
+        updatedAt: optionalNullableString(record.updatedAt, `items[${index}].updatedAt`) ??
+            null,
+        closedAt: optionalNullableString(record.closedAt, `items[${index}].closedAt`) ??
+            null,
+        webUrl: optionalNullableString(record.webUrl, `items[${index}].webUrl`) ?? null,
+        externalRef: {
+            provider: "local",
+            itemId: requiredNonEmptyString(record.id, `items[${index}].id`),
+            itemNumber: localItemNumber(record),
+        },
+    };
+}
+function validateComments(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const record = assertRecord(value, "comments");
+    const comments = {};
+    for (const [itemId, itemComments] of Object.entries(record)) {
+        if (!Array.isArray(itemComments)) {
+            throw new LocalWorkTrackerProviderError(`comments.${itemId} must be an array`);
+        }
+        comments[itemId] = itemComments.map((comment, index) => validateComment(comment, `comments.${itemId}[${index}]`));
+    }
+    return comments;
+}
+function validateComment(value, pathName) {
+    const record = assertRecord(value, pathName);
+    return {
+        id: requiredNonEmptyString(record.id, `${pathName}.id`),
+        body: requiredNonEmptyString(record.body, `${pathName}.body`),
+        author: optionalNullableString(record.author, `${pathName}.author`) ?? null,
+        createdAt: optionalNullableString(record.createdAt, `${pathName}.createdAt`) ?? null,
+        updatedAt: optionalNullableString(record.updatedAt, `${pathName}.updatedAt`) ?? null,
+        externalRef: {
+            provider: "local",
+            itemId: requiredNonEmptyString(record.id, `${pathName}.id`),
+        },
+    };
+}
+function findWorkItem(store, ref) {
+    if (ref.provider && ref.provider !== "local") {
+        throw new LocalWorkTrackerProviderError(`local provider cannot resolve ${ref.provider} work item refs`);
+    }
+    if (ref.externalRef?.provider && ref.externalRef.provider !== "local") {
+        throw new LocalWorkTrackerProviderError(`local provider cannot resolve ${ref.externalRef.provider} external refs`);
+    }
+    const id = ref.id ?? ref.externalRef?.itemId;
+    if (!id) {
+        throw new LocalWorkTrackerProviderError("work item id is required");
+    }
+    const item = store.items.find((candidate) => candidate.id === id);
+    if (!item) {
+        throw new LocalWorkTrackerProviderError(`Local work item not found: ${id}`);
+    }
+    return item;
+}
+function matchesSearch(item, search) {
+    return [item.id, item.title, item.description ?? ""].some((value) => value.toLowerCase().includes(search));
+}
+function localItemNumber(record) {
+    const externalRef = record.externalRef && typeof record.externalRef === "object"
+        ? record.externalRef
+        : undefined;
+    const itemNumber = externalRef?.itemNumber;
+    return typeof itemNumber === "number" && Number.isInteger(itemNumber)
+        ? itemNumber
+        : null;
+}
+function isClosedStatus(status) {
+    return status === "done" || status === "wont_do";
+}
+function assertWorkStatus(status) {
+    if (!workStatuses.has(status)) {
+        throw new LocalWorkTrackerProviderError(`Invalid work status: ${status}`);
+    }
+}
+function workStatus(value, pathName) {
+    if (typeof value !== "string" || !workStatuses.has(value)) {
+        throw new LocalWorkTrackerProviderError(`${pathName} must be a valid status`);
+    }
+    return value;
+}
+function normalizeLimit(limit) {
+    if (limit === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new LocalWorkTrackerProviderError("limit must be a non-negative integer");
+    }
+    return limit;
+}
+function normalizeStringArray(values, pathName) {
+    if (values === undefined) {
+        return [];
+    }
+    return stringArray(values, pathName);
+}
+function stringArray(value, pathName) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new LocalWorkTrackerProviderError(`${pathName} must be an array`);
+    }
+    const seen = new Set();
+    const result = [];
+    for (const item of value) {
+        const normalized = requiredNonEmptyString(item, pathName);
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            result.push(normalized);
+        }
+    }
+    return result;
+}
+function optionalNullableString(value, pathName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return requiredNonEmptyString(value, pathName);
+}
+function optionalNullableText(value, pathName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        throw new LocalWorkTrackerProviderError(`${pathName} must be a string`);
+    }
+    return value;
+}
+function requiredNonEmptyString(value, pathName) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new LocalWorkTrackerProviderError(`${pathName} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function positiveInteger(value, pathName) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new LocalWorkTrackerProviderError(`${pathName} must be a positive integer`);
+    }
+    return value;
+}
+function assertRecord(value, pathName) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new LocalWorkTrackerProviderError(`${pathName} must be an object`);
+    }
+    return value;
+}

package/dist/workTrackingProviderService.d.ts

@@ -0,0 +1,21 @@
+import { type GitHubWorkTrackerProviderOptions } from "./workTrackingGitHubProvider.js";
+import { type GitLabWorkTrackerProviderOptions } from "./workTrackingGitLabProvider.js";
+import { type JiraWorkTrackerProviderOptions } from "./workTrackingJiraProvider.js";
+import { type VibeWorkTrackerProviderOptions } from "./workTrackingVibeProvider.js";
+import type { WorkTrackerCapabilityName, WorkTrackerCapabilityReport, WorkTrackingConfig, WorkTrackerProvider, TrackerCapabilities } from "./workTrackingTypes.js";
+export interface CreateWorkTrackerProviderOptions {
+    projectRoot?: string;
+    now?: () => Date | string;
+    github?: Omit<GitHubWorkTrackerProviderOptions, "config">;
+    gitlab?: Omit<GitLabWorkTrackerProviderOptions, "config">;
+    jira?: Omit<JiraWorkTrackerProviderOptions, "config">;
+    vibeKanban?: Omit<VibeWorkTrackerProviderOptions, "config">;
+}
+export declare class WorkTrackingProviderServiceError extends Error {
+    constructor(message: string);
+}
+export declare function createWorkTrackerProvider(config: WorkTrackingConfig, options?: CreateWorkTrackerProviderOptions): WorkTrackerProvider;
+export declare function workTrackerCapabilityReportForConfig(config: WorkTrackingConfig): WorkTrackerCapabilityReport;
+export declare function workTrackerCapabilityReport(provider: Pick<WorkTrackerProvider, "provider" | "capabilities">): WorkTrackerCapabilityReport;
+export declare function assertWorkTrackerCapability(provider: Pick<WorkTrackerProvider, "provider" | "capabilities">, capability: WorkTrackerCapabilityName, operation: string): void;
+export declare function workTrackerCapabilitiesForConfig(config: WorkTrackingConfig): TrackerCapabilities;

package/dist/workTrackingProviderService.js

@@ -0,0 +1,117 @@
+import { createGitHubWorkTrackerProvider, githubWorkTrackerCapabilitiesForConfig, } from "./workTrackingGitHubProvider.js";
+import { createGitLabWorkTrackerProvider, gitLabWorkTrackerCapabilities, } from "./workTrackingGitLabProvider.js";
+import { createJiraWorkTrackerProvider, jiraWorkTrackerCapabilitiesForConfig, } from "./workTrackingJiraProvider.js";
+import { createLocalWorkTrackerProvider, localWorkTrackerCapabilities, } from "./workTrackingLocalProvider.js";
+import { createVibeWorkTrackerProvider, vibeWorkTrackerCapabilities, } from "./workTrackingVibeProvider.js";
+export class WorkTrackingProviderServiceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkTrackingProviderServiceError";
+    }
+}
+const workTrackerCapabilityNames = [
+    "create",
+    "list",
+    "get",
+    "update",
+    "comment",
+    "labels",
+    "assignees",
+    "milestones",
+    "board",
+    "boardStatus",
+];
+export function createWorkTrackerProvider(config, options = {}) {
+    const providerName = config.provider;
+    if (config.provider === "local") {
+        return createLocalWorkTrackerProvider({
+            projectRoot: options.projectRoot,
+            config,
+            now: options.now,
+        });
+    }
+    if (config.provider === "vibe-kanban") {
+        if (!options.vibeKanban) {
+            throw new WorkTrackingProviderServiceError("Vibe Kanban provider requires Vibe Kanban API options");
+        }
+        return createVibeWorkTrackerProvider({
+            ...options.vibeKanban,
+            config: config,
+        });
+    }
+    if (config.provider === "github") {
+        return createGitHubWorkTrackerProvider({
+            ...options.github,
+            config: config,
+        });
+    }
+    if (config.provider === "gitlab") {
+        return createGitLabWorkTrackerProvider({
+            ...options.gitlab,
+            config: config,
+        });
+    }
+    if (config.provider === "jira") {
+        return createJiraWorkTrackerProvider({
+            ...options.jira,
+            config: config,
+        });
+    }
+    throw new WorkTrackingProviderServiceError(`Work tracking provider is not available in DevNexus core: ${providerName}`);
+}
+export function workTrackerCapabilityReportForConfig(config) {
+    return workTrackerCapabilityReportFromCapabilities(config.provider, workTrackerCapabilitiesForConfig(config));
+}
+export function workTrackerCapabilityReport(provider) {
+    return workTrackerCapabilityReportFromCapabilities(provider.provider, provider.capabilities);
+}
+export function assertWorkTrackerCapability(provider, capability, operation) {
+    const report = workTrackerCapabilityReport(provider);
+    if (report.capabilities[capability]) {
+        return;
+    }
+    throw new WorkTrackingProviderServiceError(`Work tracking provider "${provider.provider}" cannot ${operation}; ` +
+        `required capability "${capability}" is disabled`);
+}
+export function workTrackerCapabilitiesForConfig(config) {
+    const providerName = config.provider;
+    if (config.provider === "local") {
+        return localWorkTrackerCapabilities;
+    }
+    if (config.provider === "vibe-kanban") {
+        return vibeWorkTrackerCapabilities;
+    }
+    if (config.provider === "github") {
+        return githubWorkTrackerCapabilitiesForConfig(config);
+    }
+    if (config.provider === "gitlab") {
+        return gitLabWorkTrackerCapabilities;
+    }
+    if (config.provider === "jira") {
+        return jiraWorkTrackerCapabilitiesForConfig(config);
+    }
+    throw new WorkTrackingProviderServiceError(`Work tracking provider is not available in DevNexus core: ${providerName}`);
+}
+function workTrackerCapabilityReportFromCapabilities(provider, capabilities) {
+    const actionCapabilities = workTrackerActionCapabilities(capabilities);
+    return {
+        provider,
+        capabilities: actionCapabilities,
+        unsupported: workTrackerCapabilityNames.filter((capability) => !actionCapabilities[capability]),
+    };
+}
+function workTrackerActionCapabilities(capabilities) {
+    const board = capabilities.board;
+    return {
+        create: capabilities.createItem,
+        list: capabilities.listItems,
+        get: capabilities.getItem,
+        update: capabilities.updateItem,
+        comment: capabilities.comment,
+        labels: capabilities.labels,
+        assignees: capabilities.assignees,
+        milestones: capabilities.milestones,
+        board,
+        boardStatus: board && capabilities.boardStatus,
+    };
+}