trekoon 0.1.7 → 0.1.8

package/src/commands/task.ts

@@ -1,4 +1,12 @@
-import { hasFlag, parseArgs, parseStrictPositiveInt, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
+import {
+  hasFlag,
+  parseArgs,
+  parseStrictNonNegativeInt,
+  parseStrictPositiveInt,
+  readEnumOption,
+  readMissingOptionValue,
+  readOption,
+} from "./arg-parser";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -16,6 +24,51 @@ const VIEW_MODES = ["table", "compact", "tree", "detail"] as const;
 const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_TASK_LIST_LIMIT = 10;
 const DEFAULT_OPEN_TASK_STATUSES = ["in_progress", "in-progress", "todo"] as const;
+const READY_REASON_READY = "all_dependencies_done";
+const READY_REASON_BLOCKED = "blocked_by_dependencies";
+
+interface DependencyBlocker {
+  readonly id: string;
+  readonly kind: "task" | "subtask";
+  readonly status: string;
+}
+
+interface TaskReadyCandidate {
+  readonly task: TaskRecord;
+  readonly readiness: {
+    readonly isReady: boolean;
+    readonly reason: typeof READY_REASON_READY | typeof READY_REASON_BLOCKED;
+  };
+  readonly blockerSummary: {
+    readonly totalDependencies: number;
+    readonly blockedByCount: number;
+    readonly blockedBy: ReadonlyArray<DependencyBlocker>;
+  };
+  readonly ranking: {
+    readonly statusPriority: number;
+    readonly blockerCount: number;
+    readonly createdAt: number;
+    readonly id: string;
+    readonly rank: number;
+  };
+}
+
+type ReadyReason = typeof READY_REASON_READY | typeof READY_REASON_BLOCKED;
+
+interface TaskReadinessSummary {
+  readonly totalOpenTasks: number;
+  readonly readyCount: number;
+  readonly returnedCount: number;
+  readonly appliedLimit: number | null;
+  readonly blockedCount: number;
+  readonly unresolvedDependencyCount: number;
+}
+
+interface TaskReadinessResult {
+  readonly candidates: readonly TaskReadyCandidate[];
+  readonly blocked: readonly TaskReadyCandidate[];
+  readonly summary: TaskReadinessSummary;
+}
 
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
@@ -51,20 +104,149 @@ function taskStatusPriority(status: string): number {
   return 2;
 }
 
+function buildTaskReadiness(domain: TrackerDomain, epicId: string | undefined): TaskReadinessResult {
+  const openStatuses = new Set<string>(DEFAULT_OPEN_TASK_STATUSES);
+  const openTasks = domain.listTasks(epicId).filter((task) => openStatuses.has(task.status));
+  const assessed = openTasks
+    .map((task) => {
+      const blockers: DependencyBlocker[] = [];
+      const dependencies = domain.listDependencies(task.id);
+      for (const dependency of dependencies) {
+        const dependencyStatus =
+          dependency.dependsOnKind === "task"
+            ? domain.getTaskOrThrow(dependency.dependsOnId).status
+            : domain.getSubtaskOrThrow(dependency.dependsOnId).status;
+
+        if (dependencyStatus !== "done") {
+          blockers.push({
+            id: dependency.dependsOnId,
+            kind: dependency.dependsOnKind,
+            status: dependencyStatus,
+          });
+        }
+      }
+
+      const blockerCount = blockers.length;
+      const readinessReason: ReadyReason = blockerCount === 0 ? READY_REASON_READY : READY_REASON_BLOCKED;
+      return {
+        task,
+        readiness: {
+          isReady: blockerCount === 0,
+          reason: readinessReason,
+        },
+        blockerSummary: {
+          totalDependencies: dependencies.length,
+          blockedByCount: blockerCount,
+          blockedBy: blockers,
+        },
+        ranking: {
+          statusPriority: taskStatusPriority(task.status),
+          blockerCount,
+          createdAt: task.createdAt,
+          id: task.id,
+        },
+      };
+    })
+    .sort((left, right) => {
+      const byStatus = left.ranking.statusPriority - right.ranking.statusPriority;
+      if (byStatus !== 0) {
+        return byStatus;
+      }
+
+      const byBlockers = left.ranking.blockerCount - right.ranking.blockerCount;
+      if (byBlockers !== 0) {
+        return byBlockers;
+      }
+
+      const byCreatedAt = left.ranking.createdAt - right.ranking.createdAt;
+      if (byCreatedAt !== 0) {
+        return byCreatedAt;
+      }
+
+      return left.ranking.id.localeCompare(right.ranking.id);
+    })
+    .map((item, index) => ({
+      ...item,
+      ranking: {
+        ...item.ranking,
+        rank: index + 1,
+      },
+    }));
+
+  const candidates = assessed.filter((item) => item.readiness.isReady);
+  const blocked = assessed.filter((item) => !item.readiness.isReady);
+  return {
+    candidates,
+    blocked,
+    summary: {
+      totalOpenTasks: assessed.length,
+      readyCount: candidates.length,
+      returnedCount: candidates.length,
+      appliedLimit: null,
+      blockedCount: blocked.length,
+      unresolvedDependencyCount: blocked.reduce((total, item) => total + item.blockerSummary.blockedByCount, 0),
+    },
+  };
+}
+
+function formatTaskReadyCandidateLine(candidate: TaskReadyCandidate): string {
+  return `${candidate.ranking.rank}. ${formatTask(candidate.task)} | reason=${candidate.readiness.reason} | blockers=${candidate.blockerSummary.blockedByCount}/${candidate.blockerSummary.totalDependencies}`;
+}
+
+function formatTaskReadyHumanOutput(result: TaskReadinessResult): string {
+  if (result.candidates.length === 0) {
+    return `No ready tasks found. Open=${result.summary.totalOpenTasks}, ready=${result.summary.readyCount}, returned=${result.summary.returnedCount}, blocked=${result.summary.blockedCount}, unresolvedDependencies=${result.summary.unresolvedDependencyCount}.`;
+  }
+
+  const lines = result.candidates.map(formatTaskReadyCandidateLine);
+  lines.push(
+    `Summary: ready=${result.summary.readyCount}, returned=${result.summary.returnedCount}, blocked=${result.summary.blockedCount}, unresolvedDependencies=${result.summary.unresolvedDependencyCount}.`,
+  );
+  return lines.join("\n");
+}
+
 function filterSortAndLimitTasks(
   tasks: readonly TaskRecord[],
   statuses: readonly string[] | undefined,
   limit: number | undefined,
-): TaskRecord[] {
+  cursor: number,
+): { tasks: TaskRecord[]; pagination: { hasMore: boolean; nextCursor: string | null } } {
   const allowedStatuses = statuses === undefined ? undefined : new Set(statuses);
   const filtered = allowedStatuses === undefined ? [...tasks] : tasks.filter((task) => allowedStatuses.has(task.status));
-  const sorted = [...filtered].sort((left, right) => taskStatusPriority(left.status) - taskStatusPriority(right.status));
+  const sorted = [...filtered].sort((left, right) => {
+    const byStatus = taskStatusPriority(left.status) - taskStatusPriority(right.status);
+    if (byStatus !== 0) {
+      return byStatus;
+    }
+
+    const byCreatedAt = left.createdAt - right.createdAt;
+    if (byCreatedAt !== 0) {
+      return byCreatedAt;
+    }
+
+    return left.id.localeCompare(right.id);
+  });
 
   if (limit === undefined) {
-    return sorted;
+    return {
+      tasks: sorted,
+      pagination: {
+        hasMore: false,
+        nextCursor: null,
+      },
+    };
   }
 
-  return sorted.slice(0, limit);
+  const pagedTasks = sorted.slice(cursor, cursor + limit);
+  const nextIndex = cursor + pagedTasks.length;
+  const hasMore = nextIndex < sorted.length;
+  return {
+    tasks: pagedTasks,
+    pagination: {
+      hasMore,
+      nextCursor: hasMore ? `${nextIndex}` : null,
+    },
+  };
 }
 
 function appendLine(existing: string, line: string): string {
@@ -227,6 +409,7 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           readMissingOptionValue(parsed.missingOptionValues, "view") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
           readMissingOptionValue(parsed.missingOptionValues, "limit", "l") ??
+          readMissingOptionValue(parsed.missingOptionValues, "cursor") ??
           readMissingOptionValue(parsed.missingOptionValues, "epic", "e");
         if (missingListOption !== undefined) {
           return failMissingOptionValue("task.list", missingListOption);
@@ -237,6 +420,7 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         const includeAll = hasFlag(parsed.flags, "all");
         const rawStatuses = readOption(parsed.options, "status", "s");
         const rawLimit = readOption(parsed.options, "limit", "l");
+        const rawCursor = readOption(parsed.options, "cursor");
 
         if (rawView !== undefined && view === undefined) {
           return failResult({
@@ -286,6 +470,18 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           });
         }
 
+        if (includeAll && rawCursor !== undefined) {
+          return failResult({
+            command: "task.list",
+            human: "Use either --all or --cursor, not both.",
+            data: { code: "invalid_input", flags: ["all", "cursor"] },
+            error: {
+              code: "invalid_input",
+              message: "--all and --cursor are mutually exclusive",
+            },
+          });
+        }
+
         const statuses = parseStatusCsv(rawStatuses);
         if (rawStatuses !== undefined && statuses !== undefined && statuses.length === 0) {
           return failResult({
@@ -312,6 +508,19 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           });
         }
 
+        const parsedCursor = parseStrictNonNegativeInt(rawCursor);
+        if (Number.isNaN(parsedCursor)) {
+          return failResult({
+            command: "task.list",
+            human: "Invalid --cursor value. Use an integer >= 0.",
+            data: { code: "invalid_input", cursor: rawCursor },
+            error: {
+              code: "invalid_input",
+              message: "Invalid --cursor value",
+            },
+          });
+        }
+
         const epicId: string | undefined = readOption(parsed.options, "epic", "e");
         const selectedStatuses = includeAll
           ? undefined
@@ -319,7 +528,8 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         const selectedLimit = includeAll
           ? undefined
           : parsedLimit ?? DEFAULT_TASK_LIST_LIMIT;
-        const tasks = filterSortAndLimitTasks(domain.listTasks(epicId), selectedStatuses, selectedLimit);
+        const listed = filterSortAndLimitTasks(domain.listTasks(epicId), selectedStatuses, selectedLimit, parsedCursor ?? 0);
+        const tasks = listed.tasks;
         const listView = view ?? "table";
         const human = tasks.length === 0 ? "No tasks found." : listView === "compact" ? tasks.map(formatTask).join("\n") : formatTaskListTable(tasks);
 
@@ -327,6 +537,7 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           command: "task.list",
           human,
           data: { tasks },
+          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
         });
       }
       case "show": {
@@ -401,6 +612,87 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           data: { task: taskTree, includeAll: true, subtasksCount: taskTree.subtasks.length },
         });
       }
+      case "ready": {
+        const missingReadyOption =
+          readMissingOptionValue(parsed.missingOptionValues, "limit", "l") ??
+          readMissingOptionValue(parsed.missingOptionValues, "epic", "e");
+        if (missingReadyOption !== undefined) {
+          return failMissingOptionValue("task.ready", missingReadyOption);
+        }
+
+        const rawLimit = readOption(parsed.options, "limit", "l");
+        const parsedLimit = parseStrictPositiveInt(rawLimit);
+        if (Number.isNaN(parsedLimit)) {
+          return failResult({
+            command: "task.ready",
+            human: "Invalid --limit value. Use an integer >= 1.",
+            data: { code: "invalid_input", limit: rawLimit },
+            error: {
+              code: "invalid_input",
+              message: "Invalid --limit value",
+            },
+          });
+        }
+
+        const epicId = readOption(parsed.options, "epic", "e");
+        const readiness = buildTaskReadiness(domain, epicId);
+        const limit = parsedLimit ?? readiness.candidates.length;
+        const candidates = readiness.candidates.slice(0, limit);
+        const summary = {
+          ...readiness.summary,
+          returnedCount: candidates.length,
+          appliedLimit: parsedLimit ?? null,
+        };
+
+        return okResult({
+          command: "task.ready",
+          human: formatTaskReadyHumanOutput({
+            ...readiness,
+            candidates,
+            summary,
+          }),
+          data: {
+            candidates,
+            blocked: readiness.blocked.map((item) => ({
+              task: item.task,
+              readiness: item.readiness,
+              blockerSummary: item.blockerSummary,
+              ranking: item.ranking,
+            })),
+            summary: {
+              ...summary,
+            },
+          },
+        });
+      }
+      case "next": {
+        const missingNextOption = readMissingOptionValue(parsed.missingOptionValues, "epic", "e");
+        if (missingNextOption !== undefined) {
+          return failMissingOptionValue("task.next", missingNextOption);
+        }
+
+        const epicId = readOption(parsed.options, "epic", "e");
+        const readiness = buildTaskReadiness(domain, epicId);
+        const candidate = readiness.candidates[0] ?? null;
+
+        return okResult({
+          command: "task.next",
+          human:
+            candidate === null
+              ? formatTaskReadyHumanOutput(readiness)
+              : `${formatTaskReadyCandidateLine(candidate)}\nSummary: ready=${readiness.summary.readyCount}, blocked=${readiness.summary.blockedCount}, unresolvedDependencies=${readiness.summary.unresolvedDependencyCount}.`,
+          data: {
+            candidate,
+            summary: readiness.summary,
+            blocked: readiness.blocked.map((item) => ({
+              task: item.task,
+              readiness: item.readiness,
+              blockerSummary: item.blockerSummary,
+              ranking: item.ranking,
+            })),
+          },
+        });
+      }
       case "update": {
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
@@ -538,7 +830,7 @@ export async function runTask(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "task",
-          human: "Usage: trekoon task <create|list|show|update|delete>",
+          human: "Usage: trekoon task <create|list|show|ready|next|update|delete>",
           data: {
             args: context.args,
           },

package/src/domain/tracker-domain.ts

@@ -9,12 +9,14 @@ import {
   type EpicRecord,
   type EpicTree,
   type NodeKind,
+  type ReverseDependencyNode,
   type SubtaskRecord,
   type TaskTreeDetailed,
   type TaskRecord,
 } from "./types";
 
 const DEFAULT_STATUS = "todo";
+const DEPENDENCY_GATED_STATUSES = new Set<string>(["in_progress", "in-progress", "done"]);
 
 interface EpicRow {
   id: string;
@@ -43,6 +45,18 @@ interface DependencyRow {
   updated_at: number;
 }
 
+interface ReverseDependencyRow {
+  node_id: string;
+  node_kind: "task" | "subtask";
+  min_distance: number;
+}
+
+interface UnresolvedDependencyBlocker {
+  readonly id: string;
+  readonly kind: "task" | "subtask";
+  readonly status: string;
+}
+
 function assertNonEmpty(field: string, value: string | undefined | null): string {
   const normalized: string = (value ?? "").trim();
   if (!normalized) {
@@ -136,7 +150,7 @@ export class TrackerDomain {
 
   listEpics(): readonly EpicRecord[] {
     const rows = this.#db
-      .query("SELECT id, title, description, status, created_at, updated_at FROM epics ORDER BY created_at ASC;")
+      .query("SELECT id, title, description, status, created_at, updated_at FROM epics ORDER BY created_at ASC, id ASC;")
       .all() as EpicRow[];
     return rows.map(mapEpic);
   }
@@ -208,14 +222,14 @@ export class TrackerDomain {
       this.getEpicOrThrow(epicId);
       const rows = this.#db
         .query(
-          "SELECT id, epic_id, title, description, status, created_at, updated_at FROM tasks WHERE epic_id = ? ORDER BY created_at ASC;",
+          "SELECT id, epic_id, title, description, status, created_at, updated_at FROM tasks WHERE epic_id = ? ORDER BY created_at ASC, id ASC;",
         )
         .all(epicId) as TaskRow[];
       return rows.map(mapTask);
     }
 
     const rows = this.#db
-      .query("SELECT id, epic_id, title, description, status, created_at, updated_at FROM tasks ORDER BY created_at ASC;")
+      .query("SELECT id, epic_id, title, description, status, created_at, updated_at FROM tasks ORDER BY created_at ASC, id ASC;")
       .all() as TaskRow[];
     return rows.map(mapTask);
   }
@@ -249,6 +263,7 @@ export class TrackerDomain {
     const nextDescription: string =
       input.description !== undefined ? assertNonEmpty("description", input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
+    this.assertNoUnresolvedDependenciesForStatusTransition(id, "task", existing.status, nextStatus);
     const now: number = Date.now();
 
     this.#db
@@ -289,7 +304,7 @@ export class TrackerDomain {
       this.getTaskOrThrow(taskId);
       const rows = this.#db
         .query(
-          "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks WHERE task_id = ? ORDER BY created_at ASC;",
+          "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks WHERE task_id = ? ORDER BY created_at ASC, id ASC;",
         )
         .all(taskId) as SubtaskRow[];
       return rows.map(mapSubtask);
@@ -297,7 +312,7 @@ export class TrackerDomain {
 
     const rows = this.#db
       .query(
-        "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks ORDER BY created_at ASC;",
+        "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks ORDER BY created_at ASC, id ASC;",
       )
       .all() as SubtaskRow[];
     return rows.map(mapSubtask);
@@ -332,6 +347,7 @@ export class TrackerDomain {
     const nextDescription: string =
       input.description !== undefined ? assertNonEmpty("description", input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
+    this.assertNoUnresolvedDependenciesForStatusTransition(id, "subtask", existing.status, nextStatus);
     const now: number = Date.now();
 
     this.#db
@@ -352,7 +368,7 @@ export class TrackerDomain {
     const taskIds = new Set(tasks.map((task) => task.id));
     const subtasks = this.#db
       .query(
-        "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks WHERE task_id IN (SELECT id FROM tasks WHERE epic_id = ?) ORDER BY created_at ASC;",
+        "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks WHERE task_id IN (SELECT id FROM tasks WHERE epic_id = ?) ORDER BY created_at ASC, id ASC;",
       )
       .all(epicId) as SubtaskRow[];
 
@@ -496,13 +512,46 @@ export class TrackerDomain {
 
     const rows = this.#db
       .query(
-        "SELECT id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at FROM dependencies WHERE source_id = ? ORDER BY created_at ASC;",
+        "SELECT id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at FROM dependencies WHERE source_id = ? ORDER BY created_at ASC, id ASC;",
       )
       .all(normalizedSourceId) as DependencyRow[];
 
     return rows.map(mapDependency);
   }
 
+  listReverseDependencies(nodeId: string): readonly ReverseDependencyNode[] {
+    const normalizedNodeId: string = assertNonEmpty("nodeId", nodeId);
+    this.resolveNodeKind(normalizedNodeId);
+
+    const rows = this.#db
+      .query(
+        `
+        WITH RECURSIVE reverse_paths(node_id, node_kind, distance, visited) AS (
+          SELECT d.source_id, d.source_kind, 1, ',' || d.source_id || ','
+          FROM dependencies d
+          WHERE d.depends_on_id = ?
+          UNION ALL
+          SELECT d.source_id, d.source_kind, rp.distance + 1, rp.visited || d.source_id || ','
+          FROM dependencies d
+          INNER JOIN reverse_paths rp ON d.depends_on_id = rp.node_id
+          WHERE instr(rp.visited, ',' || d.source_id || ',') = 0
+        )
+        SELECT node_id, node_kind, MIN(distance) AS min_distance
+        FROM reverse_paths
+        GROUP BY node_id, node_kind
+        ORDER BY min_distance ASC, node_kind ASC, node_id ASC;
+        `,
+      )
+      .all(normalizedNodeId) as ReverseDependencyRow[];
+
+    return rows.map((row) => ({
+      id: row.node_id,
+      kind: row.node_kind,
+      distance: row.min_distance,
+      isDirect: row.min_distance === 1,
+    }));
+  }
+
   private getDependencyOrThrow(id: string): DependencyRecord {
     const row = this.#db
       .query(
@@ -542,6 +591,63 @@ export class TrackerDomain {
 
     return row !== null;
   }
+
+  private assertNoUnresolvedDependenciesForStatusTransition(
+    id: string,
+    kind: "task" | "subtask",
+    existingStatus: string,
+    nextStatus: string,
+  ): void {
+    if (existingStatus === nextStatus) {
+      return;
+    }
+
+    if (!DEPENDENCY_GATED_STATUSES.has(nextStatus)) {
+      return;
+    }
+
+    const unresolvedDependencies = this.listUnresolvedDependencyBlockers(id);
+    if (unresolvedDependencies.length === 0) {
+      return;
+    }
+
+    throw new DomainError({
+      code: "dependency_blocked",
+      message: `${kind} cannot transition to ${nextStatus} while dependencies are unresolved`,
+      details: {
+        entity: kind,
+        id,
+        status: nextStatus,
+        unresolvedDependencyCount: unresolvedDependencies.length,
+        unresolvedDependencyIds: unresolvedDependencies.map((dependency) => dependency.id),
+        unresolvedDependencies,
+      },
+    });
+  }
+
+  private listUnresolvedDependencyBlockers(sourceId: string): readonly UnresolvedDependencyBlocker[] {
+    const dependencies = this.listDependencies(sourceId);
+    const unresolved: UnresolvedDependencyBlocker[] = [];
+
+    for (const dependency of dependencies) {
+      const dependencyStatus =
+        dependency.dependsOnKind === "task"
+          ? this.getTaskOrThrow(dependency.dependsOnId).status
+          : this.getSubtaskOrThrow(dependency.dependsOnId).status;
+
+      if (dependencyStatus === "done") {
+        continue;
+      }
+
+      unresolved.push({
+        id: dependency.dependsOnId,
+        kind: dependency.dependsOnKind,
+        status: dependencyStatus,
+      });
+    }
+
+    return unresolved;
+  }
 }
 
 export function parseNodeKind(kind: string): NodeKind {

package/src/domain/types.ts

@@ -39,6 +39,13 @@ export interface DependencyRecord {
   readonly updatedAt: number;
 }
 
+export interface ReverseDependencyNode {
+  readonly id: string;
+  readonly kind: Extract<NodeKind, "task" | "subtask">;
+  readonly distance: number;
+  readonly isDirect: boolean;
+}
+
 export interface EpicTree {
   readonly id: string;
   readonly title: string;

package/src/runtime/cli-shell.ts

@@ -12,8 +12,7 @@ import { runTask } from "../commands/task";
 import { runWipe } from "../commands/wipe";
 import { failResult, okResult, renderResult } from "../io/output";
 import { type CliContext, type CliResult, type OutputMode } from "./command-types";
-
-const CLI_VERSION = "0.1.0";
+import { CLI_VERSION } from "./version";
 
 const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "help",

package/src/runtime/version.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+
+interface PackageManifest {
+  readonly version?: string;
+}
+
+function readCliVersion(): string {
+  const packageJsonPath = new URL("../../package.json", import.meta.url);
+  const packageJsonContent: string = readFileSync(packageJsonPath, "utf8");
+  const packageManifest: PackageManifest = JSON.parse(packageJsonContent) as PackageManifest;
+  const version: string | undefined = packageManifest.version;
+
+  if (typeof version !== "string" || version.length === 0) {
+    throw new Error("package.json is missing a valid version field.");
+  }
+
+  return version;
+}
+
+export const CLI_VERSION: string = readCliVersion();