trekoon 0.2.6 → 0.2.8

package/src/domain/tracker-domain.ts

@@ -12,6 +12,7 @@ import {
   type CompactTaskBatchCreateResult,
   type CompactTaskSpec,
   type DependencyRecord,
+  type DependencyNodeKind,
   DomainError,
   type EpicTreeDetailed,
   type EpicRecord,
@@ -23,6 +24,11 @@ import {
   type SearchFieldMatch,
   type SearchNode,
   type SearchSummary,
+  type StatusCascadeBlocker,
+  type StatusCascadeChange,
+  type StatusCascadePlan,
+  type StatusCascadeRootKind,
+  type StatusCascadeScopeNode,
   type SubtaskRecord,
   type TaskTreeDetailed,
   type TaskRecord,
@@ -66,7 +72,7 @@ interface ReverseDependencyRow {
 
 interface UnresolvedDependencyBlocker {
   readonly id: string;
-  readonly kind: "task" | "subtask";
+  readonly kind: DependencyNodeKind;
   readonly status: string;
 }
 
@@ -132,6 +138,14 @@ function normalizeStatus(value: string | undefined): string {
   return assertNonEmpty("status", value);
 }
 
+function normalizeSubtaskDescription(value: string | undefined): string {
+  if (value === undefined) {
+    return "";
+  }
+
+  return value.trim();
+}
+
 function mapEpic(row: EpicRow): EpicRecord {
   return {
     id: row.id,
@@ -425,7 +439,7 @@ export class TrackerDomain {
     const id: string = randomUUID();
     const taskId: string = assertNonEmpty("taskId", input.taskId);
     const title: string = assertNonEmpty("title", input.title);
-    const description: string = input.description === undefined ? "" : assertNonEmpty("description", input.description);
+    const description: string = normalizeSubtaskDescription(input.description);
     const status: string = normalizeStatus(input.status);
 
     this.getTaskOrThrow(taskId);
@@ -451,7 +465,7 @@ export class TrackerDomain {
         tempKey: assertNonEmpty("tempKey", spec.tempKey),
         taskId,
         title: assertNonEmpty("title", spec.title),
-        description: spec.description === undefined ? "" : assertNonEmpty("description", spec.description),
+        description: normalizeSubtaskDescription(spec.description),
         status: normalizeStatus(spec.status),
       };
     });
@@ -568,7 +582,7 @@ export class TrackerDomain {
     const existing: SubtaskRecord = this.getSubtaskOrThrow(id);
     const nextTitle: string = input.title !== undefined ? assertNonEmpty("title", input.title) : existing.title;
     const nextDescription: string =
-      input.description !== undefined ? assertNonEmpty("description", input.description) : existing.description;
+      input.description !== undefined ? normalizeSubtaskDescription(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();
@@ -656,6 +670,40 @@ export class TrackerDomain {
     };
   }
 
+  planStatusCascade(rootKind: StatusCascadeRootKind, rootId: string, targetStatus: string): StatusCascadePlan {
+    const normalizedTargetStatus = assertNonEmpty("status", targetStatus);
+    const scope = this.#collectStatusCascadeScope(rootKind, rootId);
+    const scopeIdSet = new Set(scope.map((node) => node.id));
+    const orderedChanges = this.#orderStatusCascadeChanges(scope, normalizedTargetStatus);
+    const changedIds = orderedChanges.map((change) => change.id);
+    const changedIdSet = new Set(changedIds);
+    const unchangedIds = scope
+      .filter((node) => !changedIdSet.has(node.id))
+      .map((node) => node.id);
+    const blockers = this.#collectStatusCascadeBlockers(orderedChanges, scopeIdSet, changedIdSet, normalizedTargetStatus);
+
+    return {
+      rootKind,
+      rootId,
+      targetStatus: normalizedTargetStatus,
+      atomic: true,
+      scope,
+      orderedChanges,
+      changedIds,
+      unchangedIds,
+      blockers,
+      counts: {
+        scope: scope.length,
+        changed: orderedChanges.length,
+        unchanged: unchangedIds.length,
+        blockers: blockers.length,
+        changedEpics: orderedChanges.filter((change) => change.kind === "epic").length,
+        changedTasks: orderedChanges.filter((change) => change.kind === "task").length,
+        changedSubtasks: orderedChanges.filter((change) => change.kind === "subtask").length,
+      },
+    };
+  }
+
   collectEpicSearchScope(epicId: string): readonly SearchNode[] {
     const tree = this.buildEpicTreeDetailed(epicId);
 
@@ -1266,9 +1314,217 @@ export class TrackerDomain {
     return row !== null;
   }
 
+  #collectStatusCascadeScope(rootKind: StatusCascadeRootKind, rootId: string): StatusCascadeScopeNode[] {
+    if (rootKind === "task") {
+      const tree = this.buildTaskTreeDetailed(rootId);
+      return [
+        {
+          kind: "task",
+          id: tree.id,
+          parentId: tree.epicId,
+          status: tree.status,
+        },
+        ...tree.subtasks.map((subtask) => ({
+          kind: "subtask" as const,
+          id: subtask.id,
+          parentId: subtask.taskId,
+          status: subtask.status,
+        })),
+      ];
+    }
+
+    const tree = this.buildEpicTreeDetailed(rootId);
+    return [
+      {
+        kind: "epic",
+        id: tree.id,
+        status: tree.status,
+      },
+      ...tree.tasks.flatMap((task) => [
+        {
+          kind: "task" as const,
+          id: task.id,
+          parentId: task.epicId,
+          status: task.status,
+        },
+        ...task.subtasks.map((subtask) => ({
+          kind: "subtask" as const,
+          id: subtask.id,
+          parentId: subtask.taskId,
+          status: subtask.status,
+        })),
+      ]),
+    ];
+  }
+
+  #orderStatusCascadeChanges(scope: readonly StatusCascadeScopeNode[], targetStatus: string): StatusCascadeChange[] {
+    const changes = scope
+      .filter((node) => node.status !== targetStatus)
+      .map((node) => {
+        const change: StatusCascadeChange = {
+          kind: node.kind,
+          id: node.id,
+          previousStatus: node.status,
+          nextStatus: targetStatus,
+          ...(node.parentId === undefined ? {} : { parentId: node.parentId }),
+        };
+        return change;
+      });
+
+    if (targetStatus !== "done") {
+      return changes;
+    }
+
+    return this.#topologicallyOrderDoneCascadeChanges(changes);
+  }
+
+  #topologicallyOrderDoneCascadeChanges(changes: readonly StatusCascadeChange[]): StatusCascadeChange[] {
+    const indexById = new Map<string, number>();
+    const changeById = new Map<string, StatusCascadeChange>();
+    const dependencyTargetsBySource = new Map<string, Set<string>>();
+    const dependents = new Map<string, Set<string>>();
+    const indegree = new Map<string, number>();
+
+    changes.forEach((change, index) => {
+      indexById.set(change.id, index);
+      changeById.set(change.id, change);
+      indegree.set(change.id, 0);
+
+      if (change.kind !== "task" && change.kind !== "subtask") {
+        return;
+      }
+
+      const dependencyTargets = new Set(this.listDependencies(change.id).map((dependency) => dependency.dependsOnId));
+      dependencyTargetsBySource.set(change.id, dependencyTargets);
+    });
+
+    const addEdge = (fromId: string, toId: string): void => {
+      if (fromId === toId || !changeById.has(fromId) || !changeById.has(toId)) {
+        return;
+      }
+
+      const neighbors = dependents.get(fromId) ?? new Set<string>();
+      if (neighbors.has(toId)) {
+        return;
+      }
+
+      neighbors.add(toId);
+      dependents.set(fromId, neighbors);
+      indegree.set(toId, (indegree.get(toId) ?? 0) + 1);
+    };
+
+    for (const change of changes) {
+      const dependencyTargets = dependencyTargetsBySource.get(change.id);
+
+      if (change.kind === "subtask" && change.parentId !== undefined && !dependencyTargets?.has(change.parentId)) {
+        addEdge(change.id, change.parentId);
+      }
+
+      if (change.kind === "task" && change.parentId !== undefined && !dependencyTargets?.has(change.parentId)) {
+        addEdge(change.id, change.parentId);
+      }
+
+      if (change.kind !== "task" && change.kind !== "subtask") {
+        continue;
+      }
+
+      for (const dependencyTargetId of dependencyTargets ?? []) {
+        addEdge(dependencyTargetId, change.id);
+      }
+    }
+
+    const ordered: StatusCascadeChange[] = [];
+    const ready = changes
+      .filter((change) => (indegree.get(change.id) ?? 0) === 0)
+      .sort((left, right) => (indexById.get(left.id) ?? 0) - (indexById.get(right.id) ?? 0));
+
+    while (ready.length > 0) {
+      const next = ready.shift();
+      if (next === undefined) {
+        continue;
+      }
+
+      ordered.push(next);
+      for (const dependentId of dependents.get(next.id) ?? []) {
+        const remaining = (indegree.get(dependentId) ?? 0) - 1;
+        indegree.set(dependentId, remaining);
+        if (remaining !== 0) {
+          continue;
+        }
+
+        const dependent = changeById.get(dependentId);
+        if (dependent === undefined) {
+          continue;
+        }
+
+        ready.push(dependent);
+        ready.sort((left, right) => (indexById.get(left.id) ?? 0) - (indexById.get(right.id) ?? 0));
+      }
+    }
+
+    if (ordered.length !== changes.length) {
+      throw new DomainError({
+        code: "invalid_dependency",
+        message: "unable to determine dependency-safe cascade order",
+        details: {
+          changedIds: changes.map((change) => change.id),
+        },
+      });
+    }
+
+    return ordered;
+  }
+
+  #collectStatusCascadeBlockers(
+    changes: readonly StatusCascadeChange[],
+    scopeIdSet: ReadonlySet<string>,
+    changedIdSet: ReadonlySet<string>,
+    targetStatus: string,
+  ): StatusCascadeBlocker[] {
+    if (!DEPENDENCY_GATED_STATUSES.has(targetStatus)) {
+      return [];
+    }
+
+    const blockers: StatusCascadeBlocker[] = [];
+    for (const change of changes) {
+      if (change.kind !== "task" && change.kind !== "subtask") {
+        continue;
+      }
+
+      for (const dependency of this.listDependencies(change.id)) {
+        const dependencyStatus =
+          dependency.dependsOnKind === "task"
+            ? this.getTaskOrThrow(dependency.dependsOnId).status
+            : this.getSubtaskOrThrow(dependency.dependsOnId).status;
+        const inScope = scopeIdSet.has(dependency.dependsOnId);
+        const willCascade = targetStatus === "done" && changedIdSet.has(dependency.dependsOnId);
+        if (dependencyStatus === "done" || willCascade) {
+          continue;
+        }
+
+        blockers.push({
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+          dependsOnStatus: dependencyStatus,
+          inScope,
+          willCascade,
+        });
+      }
+    }
+
+    return blockers.sort(
+      (left, right) =>
+        left.sourceId.localeCompare(right.sourceId) ||
+        left.dependsOnId.localeCompare(right.dependsOnId) ||
+        left.dependsOnKind.localeCompare(right.dependsOnKind),
+    );
+  }
+
   private assertNoUnresolvedDependenciesForStatusTransition(
     id: string,
-    kind: "task" | "subtask",
+    kind: DependencyNodeKind,
     existingStatus: string,
     nextStatus: string,
   ): void {

package/src/domain/types.ts

@@ -192,6 +192,57 @@ export interface SearchNode {
   readonly description: string;
 }
 
+export type StatusCascadeRootKind = Extract<NodeKind, "epic" | "task">;
+export type DependencyNodeKind = Extract<NodeKind, "task" | "subtask">;
+
+export interface StatusCascadeScopeNode {
+  readonly kind: NodeKind;
+  readonly id: string;
+  readonly parentId?: string;
+  readonly status: string;
+}
+
+export interface StatusCascadeChange {
+  readonly kind: NodeKind;
+  readonly id: string;
+  readonly parentId?: string;
+  readonly previousStatus: string;
+  readonly nextStatus: string;
+}
+
+export interface StatusCascadeBlocker {
+  readonly sourceId: string;
+  readonly sourceKind: DependencyNodeKind;
+  readonly dependsOnId: string;
+  readonly dependsOnKind: DependencyNodeKind;
+  readonly dependsOnStatus: string;
+  readonly inScope: boolean;
+  readonly willCascade: boolean;
+}
+
+export interface StatusCascadeCounts {
+  readonly scope: number;
+  readonly changed: number;
+  readonly unchanged: number;
+  readonly blockers: number;
+  readonly changedEpics: number;
+  readonly changedTasks: number;
+  readonly changedSubtasks: number;
+}
+
+export interface StatusCascadePlan {
+  readonly rootKind: StatusCascadeRootKind;
+  readonly rootId: string;
+  readonly targetStatus: string;
+  readonly atomic: true;
+  readonly scope: ReadonlyArray<StatusCascadeScopeNode>;
+  readonly orderedChanges: ReadonlyArray<StatusCascadeChange>;
+  readonly changedIds: ReadonlyArray<string>;
+  readonly unchangedIds: ReadonlyArray<string>;
+  readonly blockers: ReadonlyArray<StatusCascadeBlocker>;
+  readonly counts: StatusCascadeCounts;
+}
+
 export interface DomainErrorShape {
   readonly code: string;
   readonly message: string;

package/src/runtime/cli-shell.ts

@@ -1,3 +1,4 @@
+import { runBoard } from "../commands/board";
 import { runHelp } from "../commands/help";
 import { runDep } from "../commands/dep";
 import { runEpic } from "../commands/epic";
@@ -19,6 +20,7 @@ import { resolveStoragePaths } from "../storage/path";
 
 const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "help",
+  "board",
   "init",
   "quickstart",
   "session",
@@ -334,6 +336,9 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
     case "help":
       result = await runHelp(context);
       break;
+    case "board":
+      result = await runBoard(context);
+      break;
     case "init":
       result = await runInit(context);
       break;

package/src/storage/path.ts

@@ -4,6 +4,9 @@ import { resolve } from "node:path";
 
 export const TREKOON_STORAGE_DIRNAME = ".trekoon";
 export const TREKOON_DATABASE_FILENAME = "trekoon.db";
+export const TREKOON_BOARD_DIRNAME = "board";
+export const TREKOON_BOARD_ENTRY_FILENAME = "index.html";
+export const TREKOON_BOARD_MANIFEST_FILENAME = "manifest.json";
 
 export function resolveLegacyWorktreeStorageDir(worktreeRoot: string): string {
   return resolve(worktreeRoot, TREKOON_STORAGE_DIRNAME);
@@ -15,6 +18,18 @@ export function resolveLegacyWorktreeDatabaseFile(worktreeRoot: string): string
 
 export type StorageMode = "cwd" | "git_common_dir";
 
+export function resolveBoardStorageDir(storageDir: string): string {
+  return resolve(storageDir, TREKOON_BOARD_DIRNAME);
+}
+
+export function resolveBoardEntryFile(storageDir: string): string {
+  return resolve(resolveBoardStorageDir(storageDir), TREKOON_BOARD_ENTRY_FILENAME);
+}
+
+export function resolveBoardManifestFile(storageDir: string): string {
+  return resolve(resolveBoardStorageDir(storageDir), TREKOON_BOARD_MANIFEST_FILENAME);
+}
+
 export interface StoragePaths {
   readonly invocationCwd: string;
   readonly storageMode: StorageMode;
@@ -23,6 +38,9 @@ export interface StoragePaths {
   readonly sharedStorageRoot: string;
   readonly storageDir: string;
   readonly databaseFile: string;
+  readonly boardDir: string;
+  readonly boardEntryFile: string;
+  readonly boardManifestFile: string;
   readonly diagnostics: StoragePathDiagnostics;
 }
 
@@ -35,6 +53,9 @@ export interface StoragePathIssue {
   readonly worktreeRoot: string;
   readonly sharedStorageRoot: string;
   readonly databaseFile: string;
+  readonly boardDir: string;
+  readonly boardEntryFile: string;
+  readonly boardManifestFile: string;
 }
 
 export interface StoragePathDiagnostics {
@@ -44,6 +65,9 @@ export interface StoragePathDiagnostics {
   readonly worktreeRoot: string;
   readonly sharedStorageRoot: string;
   readonly databaseFile: string;
+  readonly boardDir: string;
+  readonly boardEntryFile: string;
+  readonly boardManifestFile: string;
   readonly warnings: readonly StoragePathIssue[];
   readonly errors: readonly StoragePathIssue[];
 }
@@ -76,6 +100,9 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
   const sharedStorageRoot: string = repoCommonDir ? realpathSync(resolve(repoCommonDir, "..")) : invocationCwd;
   const storageDir: string = resolve(sharedStorageRoot, TREKOON_STORAGE_DIRNAME);
   const databaseFile: string = resolve(storageDir, TREKOON_DATABASE_FILENAME);
+  const boardDir: string = resolveBoardStorageDir(storageDir);
+  const boardEntryFile: string = resolveBoardEntryFile(storageDir);
+  const boardManifestFile: string = resolveBoardManifestFile(storageDir);
   const warnings: StoragePathIssue[] = [];
 
   const createIssue = (code: string, message: string): StoragePathIssue => ({
@@ -87,6 +114,9 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     worktreeRoot,
     sharedStorageRoot,
     databaseFile,
+    boardDir,
+    boardEntryFile,
+    boardManifestFile,
   });
 
   if (invocationCwd !== worktreeRoot) {
@@ -111,6 +141,9 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     worktreeRoot,
     sharedStorageRoot,
     databaseFile,
+    boardDir,
+    boardEntryFile,
+    boardManifestFile,
     warnings,
     errors: [],
   };
@@ -123,6 +156,9 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     sharedStorageRoot,
     storageDir,
     databaseFile,
+    boardDir,
+    boardEntryFile,
+    boardManifestFile,
     diagnostics,
   };
 }