@trail-pm/cli 0.1.6 → 0.2.2

package/dist/lib.d.ts

@@ -0,0 +1,378 @@
+import { z } from 'zod';
+
+/**
+ * Walks upward from `startDir` looking for a Trail project root: a directory
+ * that contains `.trail/config.json`.
+ *
+ * @returns The **project root** directory (the parent of the `.trail` folder),
+ *   or `null` if none is found within the walk limit. This is not the path to
+ *   `.trail` itself — use {@link trailPaths} for `.trail`-relative paths.
+ */
+declare function findTrailRoot(startDir: string): string | null;
+interface TrailPaths {
+    root: string;
+    trailDir: string;
+    tasksDir: string;
+    configPath: string;
+    snapshotPath: string;
+    gitignorePath: string;
+}
+/** Resolved paths under a Trail project root (the directory that contains `.trail`). */
+declare function trailPaths(root: string): TrailPaths;
+
+type TrailError = {
+    code: "AUTH_REQUIRED";
+    message: string;
+    hint?: string;
+} | {
+    code: "AUTH_FAILED";
+    message: string;
+} | {
+    code: "NOT_A_TRAIL_REPO";
+    message: string;
+    path?: string;
+} | {
+    code: "VALIDATION_FAILED";
+    message: string;
+    details?: string;
+    issues?: string[];
+} | {
+    code: "GITHUB_API";
+    message: string;
+    status?: number;
+    body?: string;
+} | {
+    code: "SYNC_CONFLICT";
+    message: string;
+    paths?: string[];
+};
+
+declare const TaskSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<["draft", "todo", "in_progress", "in_review", "done", "cancelled"]>;
+    priority: z.ZodOptional<z.ZodEnum<["p0", "p1", "p2", "p3"]>>;
+    type: z.ZodEnum<["feature", "bug", "chore", "epic"]>;
+    assignee: z.ZodOptional<z.ZodString>;
+    milestone: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    parent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    depends_on: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blocks: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    due_date: z.ZodOptional<z.ZodString>;
+    start_date: z.ZodOptional<z.ZodString>;
+    estimate: z.ZodOptional<z.ZodEnum<["xs", "sm", "md", "lg", "xl"]>>;
+    github: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        issue_number: z.ZodNumber;
+        synced_at: z.ZodString;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        issue_number: number;
+        synced_at: string;
+        url: string;
+    }, {
+        issue_number: number;
+        synced_at: string;
+        url: string;
+    }>>>;
+    refs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        type: string;
+    }, {
+        path: string;
+        type: string;
+    }>, "many">>;
+    ai: z.ZodOptional<z.ZodObject<{
+        summary: z.ZodOptional<z.ZodString>;
+        acceptance_criteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        implementation_context: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        test_strategy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        summary?: string | undefined;
+        acceptance_criteria?: string[] | undefined;
+        implementation_context?: string[] | undefined;
+        test_strategy?: string[] | undefined;
+        constraints?: string[] | undefined;
+    }, {
+        summary?: string | undefined;
+        acceptance_criteria?: string[] | undefined;
+        implementation_context?: string[] | undefined;
+        test_strategy?: string[] | undefined;
+        constraints?: string[] | undefined;
+    }>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    status: "draft" | "todo" | "in_progress" | "in_review" | "done" | "cancelled";
+    type: "feature" | "bug" | "chore" | "epic";
+    id: string;
+    title: string;
+    labels: string[];
+    depends_on: string[];
+    blocks: string[];
+    refs: {
+        path: string;
+        type: string;
+    }[];
+    created_at: string;
+    updated_at: string;
+    description?: string | undefined;
+    priority?: "p0" | "p1" | "p2" | "p3" | undefined;
+    assignee?: string | undefined;
+    milestone?: string | undefined;
+    branch?: string | undefined;
+    parent?: string | null | undefined;
+    due_date?: string | undefined;
+    start_date?: string | undefined;
+    estimate?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+    github?: {
+        issue_number: number;
+        synced_at: string;
+        url: string;
+    } | null | undefined;
+    ai?: {
+        summary?: string | undefined;
+        acceptance_criteria?: string[] | undefined;
+        implementation_context?: string[] | undefined;
+        test_strategy?: string[] | undefined;
+        constraints?: string[] | undefined;
+    } | undefined;
+}, {
+    status: "draft" | "todo" | "in_progress" | "in_review" | "done" | "cancelled";
+    type: "feature" | "bug" | "chore" | "epic";
+    id: string;
+    title: string;
+    created_at: string;
+    updated_at: string;
+    description?: string | undefined;
+    priority?: "p0" | "p1" | "p2" | "p3" | undefined;
+    assignee?: string | undefined;
+    milestone?: string | undefined;
+    branch?: string | undefined;
+    labels?: string[] | undefined;
+    parent?: string | null | undefined;
+    depends_on?: string[] | undefined;
+    blocks?: string[] | undefined;
+    due_date?: string | undefined;
+    start_date?: string | undefined;
+    estimate?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+    github?: {
+        issue_number: number;
+        synced_at: string;
+        url: string;
+    } | null | undefined;
+    refs?: {
+        path: string;
+        type: string;
+    }[] | undefined;
+    ai?: {
+        summary?: string | undefined;
+        acceptance_criteria?: string[] | undefined;
+        implementation_context?: string[] | undefined;
+        test_strategy?: string[] | undefined;
+        constraints?: string[] | undefined;
+    } | undefined;
+}>;
+type Task = z.infer<typeof TaskSchema>;
+
+declare function writeTaskFile(filePath: string, task: Task): void;
+/**
+ * Loads all task JSON files from `tasksDir`. Returns an empty array if the directory is missing.
+ * Stops on the first file that fails to parse or validate.
+ */
+declare function loadAllTasks(tasksDir: string): Task[];
+/**
+ * Resolves the task file for `id`: prefers `${id}.json` when it exists and its `id` matches;
+ * otherwise scans `*.json` for a task whose `id` field equals `id`.
+ */
+declare function findTaskFileById(tasksDir: string, id: string): {
+    filePath: string;
+    task: Task;
+} | null;
+
+/** Recompiles `.trail/snapshot.json` from all task files. */
+declare function rebuildSnapshot(paths: TrailPaths, now?: Date): void;
+
+/** Stable draft task id prefix + random suffix (e.g. `draft-a1b2c3d4`). */
+declare function generateDraftId(): string;
+
+declare const TrailConfigSchema: z.ZodObject<{
+    github: z.ZodObject<{
+        owner: z.ZodString;
+        repo: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        owner: string;
+        repo: string;
+    }, {
+        owner: string;
+        repo: string;
+    }>;
+    sync: z.ZodObject<{
+        preset: z.ZodEnum<["collaborative", "solo", "offline"]>;
+        auto_sync_on_command: z.ZodBoolean;
+        ui_poll_interval_seconds: z.ZodNumber;
+        ui_idle_backoff: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        preset: "collaborative" | "solo" | "offline";
+        auto_sync_on_command: boolean;
+        ui_poll_interval_seconds: number;
+        ui_idle_backoff: boolean;
+    }, {
+        preset: "collaborative" | "solo" | "offline";
+        auto_sync_on_command: boolean;
+        ui_poll_interval_seconds: number;
+        ui_idle_backoff: boolean;
+    }>;
+    /** Last successful full sync; useful for future `trail status` and similar. */
+    last_full_sync_at: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    github: {
+        owner: string;
+        repo: string;
+    };
+    sync: {
+        preset: "collaborative" | "solo" | "offline";
+        auto_sync_on_command: boolean;
+        ui_poll_interval_seconds: number;
+        ui_idle_backoff: boolean;
+    };
+    last_full_sync_at?: string | undefined;
+}, {
+    github: {
+        owner: string;
+        repo: string;
+    };
+    sync: {
+        preset: "collaborative" | "solo" | "offline";
+        auto_sync_on_command: boolean;
+        ui_poll_interval_seconds: number;
+        ui_idle_backoff: boolean;
+    };
+    last_full_sync_at?: string | undefined;
+}>;
+type TrailConfig = z.infer<typeof TrailConfigSchema>;
+
+type ResolveTokenResult = {
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    error: TrailError;
+};
+/**
+ * Resolves a GitHub API token from `GITHUB_TOKEN` (trimmed) or `gh auth token`.
+ */
+declare function resolveGitHubToken(env?: NodeJS.ProcessEnv): ResolveTokenResult;
+
+/**
+ * Minimal fields from GitHub REST issue JSON (list and single resource).
+ */
+interface GitHubIssue {
+    number: number;
+    title: string;
+    body: string | null;
+    state: string;
+    labels: {
+        name: string;
+    }[];
+    assignee: {
+        login: string;
+    } | null;
+    milestone: {
+        title: string;
+    } | null;
+    html_url: string;
+    updated_at: string;
+}
+
+declare class GitHubClient {
+    private readonly token;
+    private readonly baseUrl;
+    constructor(token: string, baseUrl?: string);
+    private request;
+    private parseJson;
+    listIssues(owner: string, repo: string, params: {
+        state: "open" | "all" | "closed";
+        per_page: number;
+        page: number;
+    }): Promise<GitHubIssue[]>;
+    getIssue(owner: string, repo: string, issueNumber: number): Promise<GitHubIssue>;
+    updateIssue(owner: string, repo: string, issueNumber: number, patch: Record<string, unknown>): Promise<GitHubIssue>;
+    createIssueComment(owner: string, repo: string, issueNumber: number, body: string): Promise<{
+        id: number;
+    }>;
+    /** Create a new issue. Returns the created issue (same shape as list/get). */
+    createIssue(owner: string, repo: string, input: {
+        title: string;
+        body?: string;
+        labels?: string[];
+    }): Promise<GitHubIssue>;
+}
+
+/**
+ * Maps a GitHub issue to a Trail task. GitHub wins for title, body, labels, assignee, milestone;
+ * local-only fields are preserved from `existing` when present.
+ */
+declare function issueToTask(issue: GitHubIssue, existing: Task | null, now: Date): Task;
+/**
+ * Maps a Trail task to fields for `GitHubClient.updateIssue`.
+ */
+declare function taskToIssueUpdate(task: Task): {
+    title?: string;
+    body?: string;
+    state?: "open" | "closed";
+    labels?: string[];
+};
+
+type SyncProgress = {
+    phase: "pull";
+    page: number;
+    issuesInPage: number;
+    issuesSoFar: number;
+} | {
+    phase: "push";
+    index: number;
+    total: number;
+    taskId: string;
+};
+declare function pullSync(options: {
+    client: GitHubClient;
+    owner: string;
+    repo: string;
+    tasksDir: string;
+    now?: Date;
+    onProgress?: (p: SyncProgress) => void;
+}): Promise<void>;
+declare function fullSync(options: {
+    client: GitHubClient;
+    owner: string;
+    repo: string;
+    tasksDir: string;
+    snapshotPath: string;
+    now?: Date;
+    onProgress?: (p: SyncProgress) => void;
+}): Promise<void>;
+
+declare function writeLastFullSyncAt(paths: TrailPaths, iso: string): void;
+
+/**
+ * Creates a GitHub issue from a draft task, deletes the draft file, and writes
+ * `{issueNumber}.json`. Mirrors `trail promote` without CLI validation.
+ */
+declare function linkDraftToNewGitHubIssue(options: {
+    client: GitHubClient;
+    owner: string;
+    repo: string;
+    draft: Task;
+    draftFilePath: string;
+    tasksDir: string;
+    now: Date;
+}): Promise<Task>;
+
+export { GitHubClient, type SyncProgress, type Task, TaskSchema, type TrailConfig, TrailConfigSchema, type TrailPaths, findTaskFileById, findTrailRoot, fullSync, generateDraftId, issueToTask, linkDraftToNewGitHubIssue, loadAllTasks, pullSync, rebuildSnapshot, resolveGitHubToken, taskToIssueUpdate, trailPaths, writeLastFullSyncAt, writeTaskFile };