@poe-platform/safe-js 0.1.0

package/dist/task-list/backends/gh-issues-sync.d.ts

@@ -0,0 +1,46 @@
+import { type GhClient } from "./gh-issues-client.js";
+export interface VerifyGhProjectOptions {
+    owner: string;
+    number: number;
+    requiredStates: readonly string[];
+    client?: GhClient;
+    fetch?: typeof fetch;
+    auth?: {
+        token: string;
+    };
+}
+export interface VerifyGhProjectReport {
+    ok: boolean;
+    project: {
+        id: string;
+        number: number;
+        owner: string;
+    } | null;
+    statusField: {
+        id: string;
+        options: readonly string[];
+    } | null;
+    missingProject: boolean;
+    missingStatusField: boolean;
+    missingOptions: readonly string[];
+}
+export interface SyncGhProjectOptions extends VerifyGhProjectOptions {
+    title?: string;
+    yes?: boolean;
+}
+export interface SyncGhProjectReport extends VerifyGhProjectReport {
+    created: readonly string[];
+    updated: readonly string[];
+}
+export declare class GhProjectSyncError extends Error {
+    readonly op: "lookup" | "createProject" | "createField" | "createOption";
+    readonly target: string;
+    constructor(options: {
+        op: "lookup" | "createProject" | "createField" | "createOption";
+        target: string;
+        cause?: unknown;
+        message: string;
+    });
+}
+export declare function verifyGhProject(opts: VerifyGhProjectOptions): Promise<VerifyGhProjectReport>;
+export declare function syncGhProject(opts: SyncGhProjectOptions): Promise<SyncGhProjectReport>;

package/dist/task-list/backends/gh-issues.d.ts

@@ -0,0 +1,21 @@
+import { type StateMachineDef } from "../state-machine.js";
+import type { TaskDefaults, TaskList } from "../types.js";
+export declare const PROJECT_ORGANIZATION_QUERY = "query Project($owner: String!, $number: Int!) {\n  organization(login: $owner) {\n    projectV2(number: $number) {\n      id\n      title\n      field(name: \"Status\") {\n        ... on ProjectV2SingleSelectField {\n          id\n          name\n          options { id name color description }\n        }\n      }\n      fields(first: 100) {\n        nodes {\n          ... on ProjectV2SingleSelectField {\n            id\n            name\n            options { id name color description }\n          }\n        }\n      }\n    }\n  }\n}";
+export declare const PROJECT_USER_QUERY = "query Project($owner: String!, $number: Int!) {\n  user(login: $owner) {\n    projectV2(number: $number) {\n      id\n      title\n      field(name: \"Status\") {\n        ... on ProjectV2SingleSelectField {\n          id\n          name\n          options { id name color description }\n        }\n      }\n      fields(first: 100) {\n        nodes {\n          ... on ProjectV2SingleSelectField {\n            id\n            name\n            options { id name color description }\n          }\n        }\n      }\n    }\n  }\n}";
+export interface GhIssuesBackendDeps {
+    repo: string;
+    project?: {
+        owner: string;
+        number: number;
+    };
+    filter?: string;
+    state?: {
+        labelPrefix?: string;
+    };
+    stateMachine?: StateMachineDef;
+    defaults: Required<TaskDefaults>;
+    token: string;
+    endpoint: string;
+    fetch?: typeof fetch;
+}
+export declare function ghIssuesBackend(deps: GhIssuesBackendDeps): Promise<TaskList>;

package/dist/task-list/index.d.ts

@@ -0,0 +1,9 @@
+export { openTaskList } from "./open.js";
+export { moveTasks } from "./move.js";
+export { assertEvent, assertTransition, defaultStateMachine, type TaskEvent } from "./state.js";
+export { eventsFromState, findEvent, validateMachine, type EventDef, type StateMachineDef } from "./state-machine.js";
+export { AnchorNotFoundError, InvalidTransitionError, MalformedTaskError, OrderMismatchError, TaskAlreadyExistsError, TaskNotFoundError, type ListFilter, type MoveProgressEvent, type MoveResult, type MoveTasksOptions, type MoveAnchor, type OpenGhIssuesOptions, type OpenMarkdownDirOptions, type OpenTaskListOptions, type OpenYamlFileOptions, type Task, type TaskCreate, type TaskDefaults, type TaskFireOptions, type TaskList, type TaskListOptions, type TaskListFs, type TaskOrder, type TaskState, type Tasks, type TaskUpdate } from "./types.js";
+export { resolveAuth } from "./backends/gh-issues-client.js";
+export type { GhClient, GhClientOptions, ResolveAuthOptions, ResolveEndpointOptions } from "./backends/gh-issues-client.js";
+export type { GhIssuesBackendDeps } from "./backends/gh-issues.js";
+export { GhProjectSyncError, syncGhProject, verifyGhProject, type SyncGhProjectOptions, type SyncGhProjectReport, type VerifyGhProjectOptions, type VerifyGhProjectReport } from "./backends/gh-issues-sync.js";

package/dist/task-list/move.d.ts

@@ -0,0 +1,2 @@
+import type { MoveResult, MoveTasksOptions } from "./types.js";
+export declare function moveTasks(options: MoveTasksOptions): Promise<MoveResult>;

package/dist/task-list/open.d.ts

@@ -0,0 +1,5 @@
+import type { BackendFactory, OpenMarkdownDirOptions, OpenTaskListOptions, OpenYamlFileOptions, TaskList } from "./types.js";
+type FileBackendOptions = OpenMarkdownDirOptions | OpenYamlFileOptions;
+export declare const backendFactories: Record<FileBackendOptions["type"], BackendFactory>;
+export declare function openTaskList(options: OpenTaskListOptions): Promise<TaskList>;
+export {};

package/dist/task-list/state-machine.d.ts

@@ -0,0 +1,16 @@
+import type { Task } from "./types.js";
+export interface StateMachineDef<TState extends string = string, TEvent extends string = string> {
+    readonly initial: TState;
+    readonly states: readonly TState[];
+    readonly events: Readonly<Record<TEvent, EventDef<TState>>>;
+}
+export interface EventDef<TState extends string = string> {
+    readonly from: readonly TState[] | "*";
+    readonly to: TState;
+    readonly guard?: (task: Task) => true | string;
+    readonly onEnter?: (task: Task) => void | Promise<void>;
+    readonly onExit?: (task: Task) => void | Promise<void>;
+}
+export declare function validateMachine(machine: StateMachineDef): void;
+export declare function eventsFromState<TState extends string, TEvent extends string>(machine: StateMachineDef<TState, TEvent>, fromState: TState): readonly TEvent[];
+export declare function findEvent<TState extends string, TEvent extends string>(machine: StateMachineDef<TState, TEvent>, fromState: TState, eventName: TEvent): EventDef<TState> | undefined;

package/dist/task-list/state.d.ts

@@ -0,0 +1,29 @@
+import { type EventDef, type StateMachineDef } from "./state-machine.js";
+import { type TaskState } from "./types.js";
+export type TaskEvent = "plan" | "start" | "complete" | "archive";
+export declare const defaultStateMachine: {
+    readonly initial: "draft";
+    readonly states: readonly ["draft", "planned", "in-progress", "done", "archived"];
+    readonly events: {
+        readonly plan: {
+            readonly from: readonly ["draft"];
+            readonly to: "planned";
+        };
+        readonly start: {
+            readonly from: readonly ["planned"];
+            readonly to: "in-progress";
+        };
+        readonly complete: {
+            readonly from: readonly ["in-progress"];
+            readonly to: "done";
+        };
+        readonly archive: {
+            readonly from: "*";
+            readonly to: "archived";
+        };
+    };
+};
+export declare function resolveStateMachine(stateMachine?: StateMachineDef): StateMachineDef;
+export declare function assertEvent<TState extends string, TEvent extends string>(machine: StateMachineDef<TState, TEvent>, fromState: TState, eventName: TEvent): EventDef<TState>;
+export declare function assertTransition(from: TaskState, to: TaskState): void;
+export declare function assertTransition<TState extends string, TEvent extends string>(machine: StateMachineDef<TState, TEvent>, from: TState, to: TState): void;

package/dist/task-list/types.d.ts

@@ -0,0 +1,206 @@
+import type { StateMachineDef } from "./state-machine.js";
+export type TaskState = "draft" | "planned" | "in-progress" | "done" | "archived";
+export interface Task {
+    list: string;
+    id: string;
+    qualifiedId: string;
+    name: string;
+    state: string;
+    description: string;
+    metadata: Record<string, unknown>;
+    sourcePath?: string;
+}
+export interface TaskCreate {
+    id?: string;
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskUpdate {
+    name?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    state?: never;
+}
+export interface TaskFireOptions {
+    metadataPatch?: Record<string, unknown>;
+}
+export type TaskOrder = "priority" | "alphabetical" | "created";
+export interface ListFilter {
+    state?: string;
+    includeArchived?: boolean;
+    order?: TaskOrder;
+}
+export type MoveAnchor = {
+    before: string;
+} | {
+    after: string;
+} | {
+    position: "top" | "bottom";
+};
+export interface Tasks {
+    readonly name: string;
+    readonly stateMachine: StateMachineDef;
+    all(filter?: ListFilter): Promise<Task[]>;
+    get(id: string): Promise<Task>;
+    create(input: TaskCreate): Promise<Task>;
+    update(id: string, patch: TaskUpdate): Promise<Task>;
+    fire(id: string, event: string, opts?: TaskFireOptions): Promise<Task>;
+    comment?(id: string, body: string): Promise<void>;
+    canFire(id: string, event: string): Promise<boolean>;
+    events(id: string): Promise<readonly string[]>;
+    delete(id: string): Promise<void>;
+    move(id: string, anchor: MoveAnchor): Promise<Task>;
+    reorder(ids: readonly string[]): Promise<readonly Task[]>;
+}
+export interface TaskList {
+    list(name: string): Tasks;
+    lists(): Promise<string[]>;
+    allTasks(filter?: ListFilter): Promise<Task[]>;
+    get(qualifiedId: string): Promise<Task>;
+    moveBetweenLists(qualifiedId: string, targetList: string): Promise<Task>;
+}
+export interface TaskDefaults {
+    metadata?: Record<string, unknown>;
+}
+export interface TaskListFs {
+    lstat(path: string): Promise<{
+        isSymbolicLink(): boolean;
+    }>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    readdir(path: string): Promise<string[]>;
+    rename(fromPath: string, toPath: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    stat(path: string): Promise<{
+        isDirectory(): boolean;
+        isFile(): boolean;
+        mtimeMs: number;
+    }>;
+    unlink(path: string): Promise<void>;
+    writeFile(path: string, data: string | NodeJS.ArrayBufferView, options?: BufferEncoding | {
+        encoding?: BufferEncoding;
+        flag?: string;
+    }): Promise<void>;
+}
+export type OpenTaskListOptions = OpenMarkdownDirOptions | OpenYamlFileOptions | OpenGhIssuesOptions;
+export type TaskListOptions = OpenTaskListOptions;
+export interface MoveTasksOptions {
+    source: TaskListOptions;
+    target: TaskListOptions;
+    deleteSource?: boolean;
+    limit?: number;
+    rate?: number;
+    dryRun?: boolean;
+    stateMap?: Record<string, string>;
+    onProgress?: (event: MoveProgressEvent) => void;
+}
+export interface MoveResult {
+    created: number;
+    skipped: number;
+    errors: Array<{
+        id: string;
+        error: string;
+    }>;
+}
+export type MoveProgressEvent = {
+    type: "created";
+    id: string;
+    source: Task;
+    target: Task;
+    targetList: string;
+    targetState: string;
+} | {
+    type: "skipped";
+    id: string;
+    source: Task;
+    targetList: string;
+    targetState: string;
+    reason: "dry-run";
+} | {
+    type: "error";
+    id: string;
+    source: Task;
+    error: string;
+};
+export interface OpenMarkdownDirOptions {
+    type: "markdown-dir";
+    path: string;
+    defaults?: TaskDefaults;
+    create?: boolean;
+    singleList?: string;
+    frontmatterMode?: "strict" | "passthrough";
+    fs?: TaskListFs;
+    stateMachine?: StateMachineDef;
+}
+export interface OpenYamlFileOptions {
+    type: "yaml-file";
+    path: string;
+    defaults?: TaskDefaults;
+    create?: boolean;
+    fs?: TaskListFs;
+    stateMachine?: StateMachineDef;
+}
+export interface OpenGhIssuesOptions {
+    type: "gh-issues";
+    repo: string;
+    project?: {
+        owner: string;
+        number: number;
+    };
+    filter?: string;
+    state?: {
+        labelPrefix?: string;
+    };
+    stateMachine?: StateMachineDef;
+    defaults?: TaskDefaults;
+    auth?: {
+        token: string;
+    };
+    fetch?: typeof fetch;
+}
+export interface BackendDeps {
+    path: string;
+    defaults: Required<TaskDefaults>;
+    singleList?: string;
+    frontmatterMode: "strict" | "passthrough";
+    create: boolean;
+    fs: TaskListFs;
+    stateMachine?: StateMachineDef;
+}
+export type BackendFactory = (deps: BackendDeps) => Promise<TaskList>;
+export declare class TaskNotFoundError extends Error {
+    constructor(message?: string);
+}
+export declare class TaskAlreadyExistsError extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidTransitionError extends Error {
+    readonly task?: Task;
+    readonly event?: string;
+    readonly to?: string;
+    readonly reason: string;
+    constructor(messageOrOptions?: string | {
+        task?: Task;
+        event?: string;
+        to?: string;
+        reason: string;
+    });
+}
+export declare class MalformedTaskError extends Error {
+    constructor(message?: string);
+}
+export declare class OrderMismatchError extends Error {
+    readonly missing: readonly string[];
+    readonly extra: readonly string[];
+    constructor(options: {
+        missing: readonly string[];
+        extra: readonly string[];
+    });
+}
+export declare class AnchorNotFoundError extends Error {
+    readonly anchor: string;
+    constructor(anchor: string);
+}