trekoon 0.2.6 → 0.2.8

package/src/board/assets/utils/dom.js

@@ -0,0 +1,308 @@
+export const SCROLL_AUTHORITY = Object.freeze({
+  page: "page",
+  workspace: "workspace",
+  inspector: "inspector",
+  taskModal: "task-modal",
+  subtaskModal: "subtask-modal",
+});
+
+const SCROLL_OWNER_CONFIG = {
+  [SCROLL_AUTHORITY.page]: {
+    containerSelector: ".board-layout",
+    scrollSelectors: [".board-layout"],
+    defaultFocusSelectors: ["#board-search-input", "[data-nav-board]", "[data-open-epic]"],
+  },
+  [SCROLL_AUTHORITY.workspace]: {
+    containerSelector: "[data-scroll-surface='workspace']",
+    scrollSelectors: ["[data-scroll-surface='workspace']"],
+    defaultFocusSelectors: [
+      "[data-task-id][aria-pressed='true']",
+      "[data-task-id]",
+      "#board-search-input",
+      "[data-open-epic][aria-current='true']",
+      "[data-open-epic]",
+    ],
+  },
+  [SCROLL_AUTHORITY.inspector]: {
+    containerSelector: "[data-scroll-surface='inspector']",
+    scrollSelectors: ["[data-scroll-surface='inspector']"],
+    defaultFocusSelectors: ["[data-task-form] [name='title']", "[data-close-task]"],
+  },
+  [SCROLL_AUTHORITY.taskModal]: {
+    containerSelector: "[data-scroll-surface='task-modal']",
+    scrollSelectors: ["[data-scroll-surface='task-modal']"],
+    defaultFocusSelectors: [".board-task-modal [data-task-form] [name='title']", ".board-task-modal [data-close-task]"],
+  },
+  [SCROLL_AUTHORITY.subtaskModal]: {
+    containerSelector: "[data-scroll-surface='subtask-modal']",
+    scrollSelectors: ["[data-scroll-surface='subtask-modal']"],
+    defaultFocusSelectors: ["[data-subtask-form] [name='title']", "[data-close-subtask]"],
+  },
+};
+
+function escapeSelector(value) {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+
+  return String(value).replaceAll(/(["\\])/g, "\\$1");
+}
+
+function buildAttributeSelector(attribute, value) {
+  return `[${attribute}="${escapeSelector(value)}"]`;
+}
+
+function captureFieldSelection(element) {
+  if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
+    return null;
+  }
+
+  return {
+    selectionStart: typeof element.selectionStart === "number" ? element.selectionStart : null,
+    selectionEnd: typeof element.selectionEnd === "number" ? element.selectionEnd : null,
+  };
+}
+
+export function resolveFocusSelector(element) {
+  if (!(element instanceof HTMLElement)) {
+    return null;
+  }
+
+  if (element.id) {
+    return { selector: `#${escapeSelector(element.id)}`, selection: captureFieldSelection(element) };
+  }
+
+  const formField = element.closest("[data-task-form], [data-subtask-form], [data-create-subtask-form], [data-dependency-form]");
+  if (formField instanceof HTMLElement && (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) && element.name) {
+    const attributeName = Array.from(formField.attributes)
+      .find((attribute) => attribute.name.startsWith("data-") && attribute.name.endsWith("-form"))?.name;
+    const attributeValue = attributeName ? formField.getAttribute(attributeName) : null;
+    if (attributeName && attributeValue) {
+      return {
+        selector: `${buildAttributeSelector(attributeName, attributeValue)} [name="${escapeSelector(element.name)}"]`,
+        selection: captureFieldSelection(element),
+      };
+    }
+  }
+
+  const attributeNames = [
+    "data-open-epic",
+    "data-task-id",
+    "data-open-subtask",
+    "data-close-task",
+    "data-close-subtask",
+    "data-nav",
+    "data-nav-board",
+    "data-view",
+    "data-action",
+    "data-delete-subtask",
+    "data-remove-dependency-source",
+  ];
+
+  for (const attributeName of attributeNames) {
+    const owner = element.closest(`[${attributeName}]`);
+    if (!(owner instanceof HTMLElement)) {
+      continue;
+    }
+
+    const attributeValue = owner.getAttribute(attributeName);
+    if (attributeValue === null || attributeValue === "") {
+      return { selector: `[${attributeName}]`, selection: null };
+    }
+
+    return { selector: buildAttributeSelector(attributeName, attributeValue), selection: null };
+  }
+
+  return null;
+}
+
+function captureScrollState(root, owner) {
+  const scrollSelectors = SCROLL_OWNER_CONFIG[owner]?.scrollSelectors ?? [];
+  const scrollState = [];
+
+  for (const selector of scrollSelectors) {
+    const element = root.querySelector(selector);
+    if (element instanceof HTMLElement) {
+      scrollState.push({ selector, top: element.scrollTop, left: element.scrollLeft });
+    }
+  }
+
+  return scrollState;
+}
+
+function resolveOwnerContainer(root, owner) {
+  const selector = SCROLL_OWNER_CONFIG[owner]?.containerSelector;
+  if (!selector) {
+    return null;
+  }
+
+  const element = root.querySelector(selector);
+  return element instanceof HTMLElement ? element : null;
+}
+
+function buildFocusCandidates(owner, runtimeState, focusOverride, fallbackFocusSelectors = []) {
+  const focusCandidates = [];
+
+  if (focusOverride?.selector) {
+    focusCandidates.push({ selector: focusOverride.selector, selection: focusOverride.selection ?? null });
+  }
+
+  if (runtimeState?.focusState?.selector) {
+    focusCandidates.push({ selector: runtimeState.focusState.selector, selection: runtimeState.focusState.selection ?? null });
+  }
+
+  for (const selector of fallbackFocusSelectors) {
+    if (typeof selector === "string" && selector.length > 0) {
+      focusCandidates.push({ selector, selection: null });
+    }
+  }
+
+  for (const selector of SCROLL_OWNER_CONFIG[owner]?.defaultFocusSelectors ?? []) {
+    focusCandidates.push({ selector, selection: null });
+  }
+
+  if (owner === SCROLL_AUTHORITY.workspace || owner === SCROLL_AUTHORITY.page) {
+    if (runtimeState?.fallbackTaskId) {
+      focusCandidates.push({ selector: buildAttributeSelector("data-task-id", runtimeState.fallbackTaskId), selection: null });
+    }
+    if (runtimeState?.fallbackEpicId) {
+      focusCandidates.push({ selector: buildAttributeSelector("data-open-epic", runtimeState.fallbackEpicId), selection: null });
+    }
+    focusCandidates.push({ selector: "#board-search-input", selection: null });
+  }
+
+  return focusCandidates;
+}
+
+export function resolveScrollAuthorityStack(boardState, options = {}) {
+  const useTaskModal = options.useTaskModal === true;
+  if (boardState?.screen !== "tasks") {
+    return [SCROLL_AUTHORITY.page];
+  }
+
+  const stack = [SCROLL_AUTHORITY.workspace];
+  if (boardState?.selectedTask) {
+    stack.push(useTaskModal ? SCROLL_AUTHORITY.taskModal : SCROLL_AUTHORITY.inspector);
+  }
+  if (boardState?.selectedSubtask) {
+    stack.push(SCROLL_AUTHORITY.subtaskModal);
+  }
+  return stack;
+}
+
+export function syncScrollAuthority(root, ownerStack) {
+  if (!(root instanceof HTMLElement)) {
+    return null;
+  }
+
+  const activeOwner = ownerStack.at(-1) ?? SCROLL_AUTHORITY.page;
+  root.dataset.scrollOwner = activeOwner;
+  root.querySelectorAll("[data-scroll-surface]").forEach((element) => {
+    if (!(element instanceof HTMLElement)) {
+      return;
+    }
+
+    element.dataset.scrollActive = element.dataset.scrollSurface === activeOwner ? "true" : "false";
+  });
+  return activeOwner;
+}
+
+export function createScrollAuthorityStack(initialStack = [SCROLL_AUTHORITY.page]) {
+  const runtimeStates = new Map();
+  const returnFocusStates = new Map();
+  let ownerStack = [...initialStack];
+
+  return {
+    capture(root, store) {
+      const activeOwner = ownerStack.at(-1) ?? SCROLL_AUTHORITY.page;
+      const runtimeState = captureRuntimeState(root, store, activeOwner);
+      if (runtimeState) {
+        runtimeStates.set(activeOwner, runtimeState);
+      }
+    },
+    rememberReturnFocus(owner, focusState) {
+      if (!owner || !focusState?.selector) {
+        return;
+      }
+      returnFocusStates.set(owner, focusState);
+    },
+    transition(nextOwnerStack) {
+      ownerStack = Array.isArray(nextOwnerStack) && nextOwnerStack.length > 0
+        ? [...nextOwnerStack]
+        : [SCROLL_AUTHORITY.page];
+      const activeOwner = ownerStack.at(-1) ?? SCROLL_AUTHORITY.page;
+      return {
+        owner: activeOwner,
+        runtimeState: runtimeStates.get(activeOwner) ?? null,
+        returnFocusState: returnFocusStates.get(activeOwner) ?? null,
+      };
+    },
+  };
+}
+
+export function syncOverlayScrollLock(isLocked) {
+  document.documentElement.style.overflow = isLocked ? "hidden" : "";
+  document.body.style.overflow = isLocked ? "hidden" : "";
+}
+
+export function captureRuntimeState(root, store, owner = SCROLL_AUTHORITY.page) {
+  if (!(root instanceof HTMLElement)) {
+    return null;
+  }
+
+  const ownerContainer = resolveOwnerContainer(root, owner);
+  const activeElement = document.activeElement;
+  const focusState = ownerContainer instanceof HTMLElement && ownerContainer.contains(activeElement)
+    ? resolveFocusSelector(activeElement)
+    : null;
+
+  return {
+    owner,
+    focusState,
+    scrollState: captureScrollState(root, owner),
+    fallbackTaskId: store?.selectedTaskId ?? null,
+    fallbackEpicId: store?.selectedEpicId ?? null,
+  };
+}
+
+export function restoreRuntimeState(root, payload) {
+  if (!(root instanceof HTMLElement) || !payload) {
+    return;
+  }
+
+  const owner = payload.owner ?? payload.runtimeState?.owner ?? SCROLL_AUTHORITY.page;
+  const runtimeState = payload.runtimeState ?? payload;
+
+  for (const { selector, top, left } of runtimeState.scrollState ?? []) {
+    const element = root.querySelector(selector);
+    if (element instanceof HTMLElement) {
+      element.scrollTop = top;
+      element.scrollLeft = left;
+    }
+  }
+
+  const ownerContainer = resolveOwnerContainer(root, owner) ?? root;
+  const focusCandidates = buildFocusCandidates(
+    owner,
+    runtimeState,
+    payload.returnFocusState,
+    payload.fallbackFocusSelectors ?? [],
+  );
+
+  for (const candidate of focusCandidates) {
+    const element = root.querySelector(candidate.selector);
+    if (!(element instanceof HTMLElement)) {
+      continue;
+    }
+    if (ownerContainer instanceof HTMLElement && !ownerContainer.contains(element) && owner !== SCROLL_AUTHORITY.page) {
+      continue;
+    }
+
+    element.focus({ preventScroll: true });
+    const selection = candidate.selection;
+    if (selection && (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) && selection.selectionStart !== null) {
+      element.setSelectionRange(selection.selectionStart, selection.selectionEnd ?? selection.selectionStart);
+    }
+    break;
+  }
+}

package/src/board/install.ts

@@ -0,0 +1,196 @@
+import {
+  createHash,
+} from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CLI_VERSION } from "../runtime/version";
+import {
+  resolveStoragePaths,
+  TREKOON_BOARD_ENTRY_FILENAME,
+  TREKOON_BOARD_MANIFEST_FILENAME,
+} from "../storage/path";
+import {
+  BOARD_ASSET_CONTRACT_VERSION,
+  BOARD_BUNDLED_ASSET_DIRNAME,
+  BoardInstallError,
+  type BoardAssetManifest,
+  type BoardInstallAction,
+  type BoardInstallResult,
+  type EnsureBoardInstalledOptions,
+} from "./types";
+
+function resolveBundledBoardAssetRoot(): string {
+  return fileURLToPath(new URL(`./${BOARD_BUNDLED_ASSET_DIRNAME}`, import.meta.url));
+}
+
+function listRelativeFiles(rootPath: string, currentPath: string = rootPath): string[] {
+  const entries = readdirSync(currentPath, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const entryPath: string = join(currentPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listRelativeFiles(rootPath, entryPath));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(relative(rootPath, entryPath));
+    }
+  }
+
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+interface ReadManifestResult {
+  readonly manifest: BoardAssetManifest | null;
+  readonly damaged: boolean;
+}
+
+function readManifest(manifestFile: string): ReadManifestResult {
+  if (!existsSync(manifestFile)) {
+    return {
+      manifest: null,
+      damaged: false,
+    };
+  }
+
+  try {
+    const rawManifest: string = readFileSync(manifestFile, "utf8");
+    return {
+      manifest: JSON.parse(rawManifest) as BoardAssetManifest,
+      damaged: false,
+    };
+  } catch {
+    return {
+      manifest: null,
+      damaged: true,
+    };
+  }
+}
+
+function createAssetDigest(sourceRoot: string, files: readonly string[]): string {
+  const hash = createHash("sha256");
+
+  for (const relativeFile of files) {
+    hash.update(relativeFile);
+    hash.update("\0");
+    hash.update(readFileSync(join(sourceRoot, relativeFile)));
+    hash.update("\0");
+  }
+
+  return hash.digest("hex");
+}
+
+function createManifest(sourceRoot: string, assetVersion: string, files: readonly string[]): BoardAssetManifest {
+  return {
+    contractVersion: BOARD_ASSET_CONTRACT_VERSION,
+    assetVersion,
+    entryFile: TREKOON_BOARD_ENTRY_FILENAME,
+    files,
+    assetDigest: createAssetDigest(sourceRoot, files),
+  };
+}
+
+function installBoardFiles(sourceRoot: string, runtimeRoot: string, manifest: BoardAssetManifest): void {
+  rmSync(runtimeRoot, { recursive: true, force: true });
+  mkdirSync(dirname(runtimeRoot), { recursive: true });
+  cpSync(sourceRoot, runtimeRoot, { recursive: true });
+  writeFileSync(join(runtimeRoot, TREKOON_BOARD_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+function determineAction(
+  runtimeRoot: string,
+  entryFile: string,
+  currentManifest: BoardAssetManifest | null,
+  manifestDamaged: boolean,
+  nextManifest: BoardAssetManifest,
+): BoardInstallAction {
+  if (manifestDamaged) {
+    return "reinstalled";
+  }
+
+  if (!existsSync(runtimeRoot) || !existsSync(entryFile) || currentManifest === null) {
+    return currentManifest === null && !existsSync(runtimeRoot) ? "installed" : "reinstalled";
+  }
+
+  if (
+    currentManifest.contractVersion !== nextManifest.contractVersion ||
+    currentManifest.assetVersion !== nextManifest.assetVersion ||
+    currentManifest.entryFile !== nextManifest.entryFile ||
+    JSON.stringify(currentManifest.files) !== JSON.stringify(nextManifest.files) ||
+    currentManifest.assetDigest !== nextManifest.assetDigest
+  ) {
+    return "updated";
+  }
+
+  for (const relativeFile of nextManifest.files) {
+    if (!existsSync(join(runtimeRoot, relativeFile))) {
+      return "reinstalled";
+    }
+  }
+
+  return "unchanged";
+}
+
+export function ensureBoardInstalled(options: EnsureBoardInstalledOptions = {}): BoardInstallResult {
+  const paths = resolveStoragePaths(options.workingDirectory);
+  const sourceRoot: string = resolve(options.bundledAssetRoot ?? resolveBundledBoardAssetRoot());
+  const runtimeRoot: string = paths.boardDir;
+  const entryFile: string = paths.boardEntryFile;
+  const manifestFile: string = paths.boardManifestFile;
+
+  if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) {
+    throw new BoardInstallError("missing_asset", `Bundled board asset directory not found at ${sourceRoot}`, {
+      sourceRoot,
+    });
+  }
+
+  const sourceFiles: string[] = listRelativeFiles(sourceRoot);
+  if (!sourceFiles.includes(TREKOON_BOARD_ENTRY_FILENAME)) {
+    throw new BoardInstallError("missing_asset", `Bundled board entry file not found at ${join(sourceRoot, TREKOON_BOARD_ENTRY_FILENAME)}`, {
+      sourceRoot,
+      missingFile: TREKOON_BOARD_ENTRY_FILENAME,
+    });
+  }
+
+  const manifest: BoardAssetManifest = createManifest(sourceRoot, options.assetVersion ?? CLI_VERSION, sourceFiles);
+  const currentManifestResult: ReadManifestResult = readManifest(manifestFile);
+  const action: BoardInstallAction = determineAction(
+    runtimeRoot,
+    entryFile,
+    currentManifestResult.manifest,
+    currentManifestResult.damaged,
+    manifest,
+  );
+
+  if (action !== "unchanged") {
+    installBoardFiles(sourceRoot, runtimeRoot, manifest);
+  }
+
+  return {
+    action,
+    paths: {
+      sourceRoot,
+      runtimeRoot,
+      entryFile,
+      manifestFile,
+    },
+    manifest,
+  };
+}
+
+export function updateBoardInstallation(options: EnsureBoardInstalledOptions = {}): BoardInstallResult {
+  return ensureBoardInstalled(options);
+}

package/src/board/open-browser.ts

@@ -0,0 +1,131 @@
+import { spawn } from "node:child_process";
+
+export interface OpenBrowserResult {
+  readonly launched: boolean;
+  readonly url: string;
+  readonly command: string | null;
+  readonly args: readonly string[];
+  readonly errorMessage: string | null;
+}
+
+type BrowserLaunchEvent = "error" | "exit" | "spawn";
+type BrowserLaunchListener = (eventData?: Error | number | null) => void;
+
+interface BrowserLaunchHandle {
+  once(event: BrowserLaunchEvent, listener: BrowserLaunchListener): BrowserLaunchHandle;
+  removeListener(event: BrowserLaunchEvent, listener: BrowserLaunchListener): BrowserLaunchHandle;
+  unref(): void;
+}
+
+type BrowserLauncher = (command: string, args: readonly string[]) => BrowserLaunchHandle;
+
+function spawnBrowserProcess(command: string, args: readonly string[]): BrowserLaunchHandle {
+  const child = spawn(command, [...args], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  return child;
+}
+
+let browserLauncher: BrowserLauncher = spawnBrowserProcess;
+
+function resolveOpenCommand(url: string): { command: string; args: readonly string[] } {
+  if (process.platform === "darwin") {
+    return { command: "open", args: [url] };
+  }
+
+  if (process.platform === "win32") {
+    return { command: "cmd", args: ["/c", "start", "", url] };
+  }
+
+  return { command: "xdg-open", args: [url] };
+}
+
+export function setBrowserLauncherForTests(nextLauncher: BrowserLauncher | null): void {
+  browserLauncher = nextLauncher ?? spawnBrowserProcess;
+}
+
+export async function openBoardInBrowser(url: string): Promise<OpenBrowserResult> {
+  const launch = resolveOpenCommand(url);
+
+  try {
+    const child = browserLauncher(launch.command, launch.args);
+
+    return await new Promise<OpenBrowserResult>((resolve) => {
+      let settled = false;
+      let spawned = false;
+      let launchResultScheduled = false;
+
+      const complete = (result: OpenBrowserResult): void => {
+        if (settled) {
+          return;
+        }
+
+        settled = true;
+        child.removeListener("spawn", handleSpawn);
+        child.removeListener("error", handleError);
+        child.removeListener("exit", handleExit);
+        resolve(result);
+      };
+
+      const resolveLaunchSuccess = (): void => {
+        complete({
+          launched: true,
+          url,
+          command: launch.command,
+          args: launch.args,
+          errorMessage: null,
+        });
+      };
+
+      const handleSpawn = (): void => {
+        spawned = true;
+        if (launchResultScheduled) {
+          return;
+        }
+
+        launchResultScheduled = true;
+        setTimeout(resolveLaunchSuccess, 0);
+      };
+
+      const handleError = (eventData?: Error | number | null): void => {
+        complete({
+          launched: false,
+          url,
+          command: launch.command,
+          args: launch.args,
+          errorMessage: eventData instanceof Error ? eventData.message : "Unknown browser launch failure",
+        });
+      };
+
+      const handleExit = (eventData?: Error | number | null): void => {
+        const exitCode = typeof eventData === "number" ? eventData : Number.NaN;
+
+        if (!spawned || exitCode === 0 || Number.isNaN(exitCode)) {
+          return;
+        }
+
+        complete({
+          launched: false,
+          url,
+          command: launch.command,
+          args: launch.args,
+          errorMessage: `${launch.command} exited with code ${exitCode}`,
+        });
+      };
+
+      child.once("spawn", handleSpawn);
+      child.once("error", handleError);
+      child.once("exit", handleExit);
+    });
+  } catch (error: unknown) {
+    return {
+      launched: false,
+      url,
+      command: launch.command,
+      args: launch.args,
+      errorMessage: error instanceof Error ? error.message : "Unknown browser launch failure",
+    };
+  }
+}