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

package/dist/workItemService.d.ts

@@ -0,0 +1,60 @@
+import { type CreateWorkTrackerProviderOptions } from "./workTrackingProviderService.js";
+import type { CreateWorkItemInput, NexusProjectContext, WorkComment, WorkItem, WorkItemPatch, WorkItemQuery, WorkItemRef, WorkStatus, WorkTrackerProvider, WorkTrackingConfig } from "./workTrackingTypes.js";
+export interface WorkItemProjectSelector {
+    project?: string;
+    projectRoot?: string;
+    componentId?: string;
+}
+export interface ResolvedWorkItemProjectContext extends Omit<NexusProjectContext, "workTracking"> {
+    workTracking: WorkTrackingConfig;
+}
+export interface ResolvedWorkItemProviderContext {
+    projectContext: ResolvedWorkItemProjectContext;
+    projectRoot: string;
+    workTracking: WorkTrackingConfig;
+    provider: WorkTrackerProvider;
+}
+export type WorkItemProjectResolver = (selector: WorkItemProjectSelector) => ResolvedWorkItemProjectContext | Promise<ResolvedWorkItemProjectContext>;
+export type WorkItemProviderFactory = (context: ResolvedWorkItemProjectContext) => WorkTrackerProvider;
+export interface WorkItemServiceOptions {
+    resolveProject: WorkItemProjectResolver;
+    providerFactory?: WorkItemProviderFactory;
+    providerOptions?: Omit<CreateWorkTrackerProviderOptions, "projectRoot" | "now">;
+    now?: () => Date | string;
+}
+export type CreateProjectWorkItemInput = WorkItemProjectSelector & Omit<CreateWorkItemInput, "projectRoot">;
+export type ListProjectWorkItemsInput = WorkItemProjectSelector & Omit<WorkItemQuery, "projectRoot">;
+export type GetProjectWorkItemInput = WorkItemProjectSelector & WorkItemRef;
+export interface UpdateProjectWorkItemInput extends WorkItemProjectSelector {
+    ref: WorkItemRef;
+    patch: WorkItemPatch;
+}
+export interface AddProjectWorkItemCommentInput extends WorkItemProjectSelector {
+    ref: WorkItemRef;
+    body: string;
+}
+export interface SetProjectWorkItemStatusInput extends WorkItemProjectSelector {
+    ref: WorkItemRef;
+    status: WorkStatus;
+}
+export declare class WorkItemServiceError extends Error {
+    constructor(message: string);
+}
+export declare function createWorkItemService(options: WorkItemServiceOptions): WorkItemService;
+export declare class WorkItemService {
+    private readonly resolveProject;
+    private readonly providerFactory?;
+    private readonly providerOptions?;
+    private readonly now?;
+    constructor(options: WorkItemServiceOptions);
+    resolveProviderContext(selector: WorkItemProjectSelector): Promise<ResolvedWorkItemProviderContext>;
+    createWorkItem(input: CreateProjectWorkItemInput): Promise<WorkItem>;
+    listWorkItems(input: ListProjectWorkItemsInput): Promise<WorkItem[]>;
+    getWorkItem(input: GetProjectWorkItemInput): Promise<WorkItem>;
+    updateWorkItem(input: UpdateProjectWorkItemInput): Promise<WorkItem>;
+    addComment(input: AddProjectWorkItemCommentInput): Promise<WorkComment>;
+    setStatus(input: SetProjectWorkItemStatusInput): Promise<WorkItem>;
+    private createProvider;
+}
+export declare function normalizeProjectSelector(selector: WorkItemProjectSelector): string;
+export declare function normalizeWorkItemRef(ref: WorkItemRef, provider: string): WorkItemRef;

package/dist/workItemService.js

@@ -0,0 +1,163 @@
+import { assertWorkTrackerCapability, createWorkTrackerProvider, WorkTrackingProviderServiceError, } from "./workTrackingProviderService.js";
+export class WorkItemServiceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkItemServiceError";
+    }
+}
+export function createWorkItemService(options) {
+    return new WorkItemService(options);
+}
+export class WorkItemService {
+    resolveProject;
+    providerFactory;
+    providerOptions;
+    now;
+    constructor(options) {
+        this.resolveProject = options.resolveProject;
+        this.providerFactory = options.providerFactory;
+        this.providerOptions = options.providerOptions;
+        this.now = options.now;
+    }
+    async resolveProviderContext(selector) {
+        const normalizedSelector = normalizeProjectSelectorObject(selector);
+        const projectContext = await this.resolveProject(normalizedSelector);
+        const workTracking = projectContext.workTracking;
+        try {
+            return {
+                projectContext,
+                projectRoot: projectContext.projectRoot,
+                workTracking,
+                provider: this.createProvider(projectContext),
+            };
+        }
+        catch (error) {
+            if (error instanceof WorkTrackingProviderServiceError) {
+                throw new WorkItemServiceError(`Project "${projectContext.projectId}" uses work tracking provider ` +
+                    `"${workTracking.provider}", but it is not available: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async createWorkItem(input) {
+        const { project: _project, projectRoot: _projectRoot, componentId: _componentId, ...item } = input;
+        const context = await this.resolveProviderContext(input);
+        assertWorkTrackerCapability(context.provider, "create", "create work items");
+        assertCreateFieldCapabilities(context.provider, item);
+        return context.provider.createWorkItem({
+            ...item,
+            projectRoot: context.projectRoot,
+        });
+    }
+    async listWorkItems(input) {
+        const { project: _project, projectRoot: _projectRoot, componentId: _componentId, ...query } = input;
+        const context = await this.resolveProviderContext(input);
+        assertWorkTrackerCapability(context.provider, "list", "list work items");
+        return context.provider.listWorkItems({
+            ...query,
+            projectRoot: context.projectRoot,
+        });
+    }
+    async getWorkItem(input) {
+        const { project: _project, projectRoot: _projectRoot, componentId: _componentId, ...ref } = input;
+        const context = await this.resolveProviderContext(input);
+        assertWorkTrackerCapability(context.provider, "get", "get work items");
+        return context.provider.getWorkItem(normalizeWorkItemRef(ref, context.provider.provider));
+    }
+    async updateWorkItem(input) {
+        const context = await this.resolveProviderContext(input);
+        assertWorkTrackerCapability(context.provider, "update", "update work items");
+        assertPatchFieldCapabilities(context.provider, input.patch);
+        return context.provider.updateWorkItem(normalizeWorkItemRef(input.ref, context.provider.provider), input.patch);
+    }
+    async addComment(input) {
+        const context = await this.resolveProviderContext(input);
+        assertWorkTrackerCapability(context.provider, "comment", "add comments");
+        return context.provider.addComment(normalizeWorkItemRef(input.ref, context.provider.provider), input.body);
+    }
+    async setStatus(input) {
+        const context = await this.resolveProviderContext(input);
+        assertWorkTrackerCapability(context.provider, "update", "set work item status");
+        const ref = normalizeWorkItemRef(input.ref, context.provider.provider);
+        if (context.provider.setStatus) {
+            return context.provider.setStatus(ref, input.status);
+        }
+        return context.provider.updateWorkItem(ref, { status: input.status });
+    }
+    createProvider(context) {
+        if (this.providerFactory) {
+            return this.providerFactory(context);
+        }
+        return createWorkTrackerProvider(context.workTracking, {
+            ...this.providerOptions,
+            projectRoot: context.projectRoot,
+            now: this.now,
+        });
+    }
+}
+export function normalizeProjectSelector(selector) {
+    const normalizedSelector = normalizeProjectSelectorObject(selector);
+    return normalizedSelector.project ?? normalizedSelector.projectRoot;
+}
+export function normalizeWorkItemRef(ref, provider) {
+    const refProvider = ref.provider ?? ref.externalRef?.provider;
+    if (refProvider && refProvider !== provider) {
+        throw new WorkItemServiceError(`work item ref provider "${refProvider}" does not match configured provider "${provider}"`);
+    }
+    if (!ref.id && !ref.externalRef?.itemId) {
+        throw new WorkItemServiceError("work item id or externalRef.itemId is required");
+    }
+    return {
+        ...ref,
+        provider: refProvider ?? provider,
+    };
+}
+function normalizeProjectSelectorObject(selector) {
+    const project = optionalNonEmptyString(selector.project, "project");
+    const projectRoot = optionalNonEmptyString(selector.projectRoot, "projectRoot");
+    const componentId = optionalNonEmptyString(selector.componentId, "componentId");
+    if (project && projectRoot) {
+        throw new WorkItemServiceError("Provide either project or projectRoot, not both");
+    }
+    if (!project && !projectRoot) {
+        throw new WorkItemServiceError("project or projectRoot is required");
+    }
+    return {
+        ...(project ? { project } : { projectRoot }),
+        ...(componentId ? { componentId } : {}),
+    };
+}
+function assertCreateFieldCapabilities(provider, input) {
+    if (input.labels && input.labels.length > 0) {
+        assertWorkTrackerCapability(provider, "labels", "set labels on created work items");
+    }
+    if (input.assignees && input.assignees.length > 0) {
+        assertWorkTrackerCapability(provider, "assignees", "set assignees on created work items");
+    }
+    if (input.milestone !== undefined && input.milestone !== null) {
+        assertWorkTrackerCapability(provider, "milestones", "set milestones on created work items");
+    }
+}
+function assertPatchFieldCapabilities(provider, patch) {
+    if (patch.labels !== undefined) {
+        assertWorkTrackerCapability(provider, "labels", "set labels on updated work items");
+    }
+    if (patch.assignees !== undefined) {
+        assertWorkTrackerCapability(provider, "assignees", "set assignees on updated work items");
+    }
+    if (patch.milestone !== undefined) {
+        assertWorkTrackerCapability(provider, "milestones", "set milestones on updated work items");
+    }
+}
+function optionalNonEmptyString(value, name) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return requiredNonEmptyString(value, name);
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new WorkItemServiceError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/workTrackingGitHubProvider.d.ts

@@ -0,0 +1,71 @@
+import type { CreateWorkItemInput, GitHubWorkTrackingConfig, TrackerCapabilities, WorkComment, WorkItem, WorkItemPatch, WorkItemQuery, WorkItemRef, WorkStatus, WorkTrackerProvider } from "./workTrackingTypes.js";
+export declare const defaultGitHubApiBaseUrl = "https://api.github.com";
+export declare const defaultGitHubApiVersion = "2026-03-10";
+export declare const githubStatusLabelPrefix = "status:";
+export interface GitHubWorkTrackerProviderOptions {
+    config: GitHubWorkTrackingConfig;
+    token?: string | null;
+    fetch?: typeof fetch;
+    apiBaseUrl?: string | null;
+    graphqlApiUrl?: string | null;
+    apiVersion?: string | null;
+    env?: Record<string, string | undefined>;
+    credentialRunner?: GitCredentialRunner | false;
+    credentialInteractive?: boolean;
+}
+export interface GitCredentialCommandResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export interface GitCredentialRequest {
+    protocol: "https";
+    host: string;
+    path?: string;
+}
+export type GitCredentialRunner = (request: GitCredentialRequest, options: {
+    interactive: boolean;
+}) => GitCredentialCommandResult;
+export declare class GitHubWorkTrackerProviderError extends Error {
+    constructor(message: string);
+}
+export declare const githubWorkTrackerCapabilities: TrackerCapabilities;
+export declare function githubWorkTrackerCapabilitiesForConfig(config: Pick<GitHubWorkTrackingConfig, "board">): TrackerCapabilities;
+export declare function createGitHubWorkTrackerProvider(options: GitHubWorkTrackerProviderOptions): GitHubWorkTrackerProvider;
+export declare class GitHubWorkTrackerProvider implements WorkTrackerProvider {
+    readonly provider = "github";
+    readonly capabilities: TrackerCapabilities;
+    private readonly config;
+    private readonly fetchFn;
+    private readonly apiBaseUrl;
+    private readonly graphqlApiUrl;
+    private readonly apiVersion;
+    private readonly staticAuthorizationHeader?;
+    private readonly credentialRunner?;
+    private readonly credentialInteractive;
+    private credentialAuthorizationHeader;
+    constructor(options: GitHubWorkTrackerProviderOptions);
+    createWorkItem(input: CreateWorkItemInput): Promise<WorkItem>;
+    listWorkItems(query?: WorkItemQuery): Promise<WorkItem[]>;
+    getWorkItem(ref: WorkItemRef): Promise<WorkItem>;
+    updateWorkItem(ref: WorkItemRef, patch: WorkItemPatch): Promise<WorkItem>;
+    addComment(ref: WorkItemRef, body: string): Promise<WorkComment>;
+    setStatus(ref: WorkItemRef, status: WorkStatus): Promise<WorkItem>;
+    private getIssue;
+    private addIssueToConfiguredProject;
+    private issuePath;
+    private requestJson;
+    private graphql;
+    private issueToWorkItem;
+    private commentToWorkComment;
+    private issueExternalRef;
+    private authorizationHeader;
+}
+export declare function normalizeGitHubApiBaseUrl(hostOrApiBaseUrl?: string | null): string;
+export declare function normalizeGitHubGraphQLApiUrl(hostOrApiBaseUrl?: string | null): string;
+export declare function githubCredentialRequest(config: Pick<GitHubWorkTrackingConfig, "host" | "repository">): GitCredentialRequest;
+export declare function normalizeGitHubCredentialHost(hostOrApiBaseUrl?: string | null): string;
+export declare function defaultGitCredentialRunner(request: GitCredentialRequest, options: {
+    interactive: boolean;
+}): GitCredentialCommandResult;