@workit-dev/core 0.0.1 → 1.0.0

package/src/core/youtrack-backend.ts

@@ -0,0 +1,288 @@
+// The one seam between Workit and YouTrack (#263). Every Workit YouTrack
+// operation (issue read and create, comments, work items, the marker
+// read-back) goes through `ytrack … --json` (BrainerVirus/youtrack-cli), which
+// keeps its token in the OS keyring. Workit never reads, writes or stores a
+// YouTrack token.
+//
+// ytrack exits 0 ok, 1 failed, 2 cancelled, 4 authentication required. A
+// missing ytrack is `unavailable` with the install as the unblock; exit 4 is
+// `unavailable` with `ytrack auth login --host <host>`.
+import {
+  YTRACK_EXIT,
+  YTRACK_MISSING,
+  ytrackDetail,
+  ytrackLogin,
+  ytrackMissingUnblock,
+  ytrackRunner,
+  type YtrackRun,
+} from "./youtrack-ytrack";
+import { youTrackBaseUrl } from "./youtrack";
+
+export const YT_WRITE_GATE = "WORKIT_YT_WRITE";
+
+type Obj = Record<string, unknown>;
+
+export type IssueComment = {
+  id: string;
+  text: string;
+  author: string | null;
+  created: string | null;
+};
+export type BackendKind = "ytrack";
+export type IssueView = {
+  issueId: string;
+  summary: string;
+  description: string | null;
+  state: string | null;
+  url: string | null;
+  fields: { name: string; value: unknown }[];
+  comments: IssueComment[];
+  source: BackendKind;
+};
+export type Created = {
+  issueId: string;
+  url: string | null;
+  source: BackendKind;
+};
+export type CreateInput = {
+  project: string;
+  summary: string;
+  description?: string;
+};
+export type WorkItemInput = { minutes: number; text: string; dateMs: number };
+
+type FailCode = "unavailable" | "failed" | "not_found" | "blocked";
+export type IssueOutcome<T> =
+  | { ok: true; data: T }
+  | { ok: false; code: FailCode; error: string; unblock?: string };
+
+/** A write's result; `outcome` says whether it surely did not land. */
+export type WriteResult =
+  | { ok: true; data: Obj }
+  | {
+      ok: false;
+      error: string;
+      outcome: "not_applied" | "unknown";
+      unblock?: string;
+    };
+
+/** The texts on an issue; `complete` is false when older items may be missing. */
+export type Texts = { texts: string[]; complete: boolean };
+
+export interface YouTrackBackend {
+  readonly kind: BackendKind;
+  showIssue(issueId: string): Promise<IssueOutcome<IssueView>>;
+  createIssue(input: CreateInput): Promise<IssueOutcome<Created>>;
+  addComment(issueId: string, text: string): Promise<WriteResult>;
+  addWorkItem(issueId: string, item: WorkItemInput): Promise<WriteResult>;
+  /** Comment or work item texts, for the marker read-back; null when unreadable. */
+  texts(issueId: string, where: "comments" | "workItems"): Promise<Texts | null>;
+}
+
+const isObj = (value: unknown): value is Obj =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+const str = (value: unknown): string | null => (typeof value === "string" ? value : null);
+
+/** A field value as one readable scalar: an enum's name, a user's login, a period's text. */
+function plainValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(plainValue);
+  if (!isObj(value)) return value ?? null;
+  for (const key of ["name", "login", "presentation", "text", "fullName"])
+    if (typeof value[key] === "string") return value[key];
+  return null;
+}
+
+const isoTime = (value: unknown): string | null =>
+  typeof value === "number" ? new Date(value).toISOString() : str(value);
+
+function comments(raw: unknown): IssueComment[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((item): item is Obj => isObj(item) && item.deleted !== true)
+    .map((item) => ({
+      id: String(item.id ?? ""),
+      text: str(item.text) ?? "",
+      author: isObj(item.author)
+        ? (str(item.author.login) ?? str(item.author.fullName))
+        : str(item.author),
+      created: isoTime(item.created),
+    }));
+}
+
+function fields(raw: unknown): { name: string; value: unknown }[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((field): field is Obj => isObj(field) && typeof field.name === "string")
+    .map((field) => ({ name: field.name as string, value: plainValue(field.value) }));
+}
+
+/** Normalize `ytrack issue view --json …` into one shape. */
+function issueView(raw: Obj): IssueView {
+  const list = fields(raw.customFields);
+  const issueId = String(raw.idReadable ?? "");
+  const stateField = str(list.find((field) => field.name === "State")?.value);
+  return {
+    issueId,
+    summary: str(raw.summary) ?? "",
+    description: str(raw.description),
+    state: str(plainValue(raw.state)) ?? stateField,
+    url: str(raw.url),
+    fields: list,
+    comments: comments(raw.comments),
+    source: "ytrack",
+  };
+}
+
+/** YYYY-MM-DD of a YouTrack work date (midnight UTC). */
+const workDay = (dateMs: number): string => new Date(dateMs).toISOString().slice(0, 10);
+
+// ---------------------------------------------------------------- ytrack
+
+const VIEW_FIELDS = "idReadable,summary,description,state,url,customFields,comments";
+
+type Ran = { ok: true; json: unknown } | { ok: false; status: number | null; error: string };
+type RanFailure = Extract<Ran, { ok: false }>;
+
+function ranJson(run: YtrackRun, args: string[], input?: string): Ran {
+  const out = run(args, input);
+  const what = `ytrack ${args.slice(0, 2).join(" ")}`;
+  if (out.missing) return { ok: false, status: null, error: `${what}: ${YTRACK_MISSING}` };
+  if (out.status !== YTRACK_EXIT.ok) {
+    const detail = ytrackDetail(out);
+    return {
+      ok: false,
+      status: out.status,
+      error: `${what} failed (exit ${out.status ?? "signal"})${detail ? `: ${detail}` : ""}`,
+    };
+  }
+  try {
+    return { ok: true, json: JSON.parse(out.stdout) as unknown };
+  } catch {
+    return { ok: false, status: out.status, error: `${what} printed invalid JSON` };
+  }
+}
+
+/** The unblock for a failure that sent nothing: install ytrack, or log in to `host`. */
+const unblockFor = (ran: RanFailure, host: string | null): { unblock?: string } =>
+  ran.status === null
+    ? { unblock: ytrackMissingUnblock(host) }
+    : ran.status === YTRACK_EXIT.auth
+      ? { unblock: ytrackLogin(host) }
+      : {};
+
+const readFailure = (ran: RanFailure, host: string | null): IssueOutcome<never> => ({
+  ok: false,
+  code: ran.status === null || ran.status === YTRACK_EXIT.auth ? "unavailable" : "failed",
+  error: ran.error,
+  ...unblockFor(ran, host),
+});
+
+/**
+ * A failed ytrack write: auth (4), cancel (2) and a missing binary sent
+ * nothing; any other failure may have landed, so the caller reads back.
+ */
+const writeFailure = (ran: RanFailure, host: string | null): WriteResult => ({
+  ok: false,
+  error: ran.error,
+  outcome:
+    ran.status === YTRACK_EXIT.auth || ran.status === YTRACK_EXIT.cancelled || ran.status === null
+      ? "not_applied"
+      : "unknown",
+  ...unblockFor(ran, host),
+});
+
+/** The backend over `run`; `host` (youtrack.json's baseUrl) names the login in an unblock. */
+export function ytrackBackend(run: YtrackRun, host: string | null = null): YouTrackBackend {
+  return {
+    kind: "ytrack",
+    async showIssue(issueId) {
+      const ran = ranJson(run, ["issue", "view", issueId, "--json", VIEW_FIELDS]);
+      if (!ran.ok) return readFailure(ran, host);
+      if (!isObj(ran.json)) return { ok: false, code: "failed", error: "ytrack printed no issue" };
+      return { ok: true, data: issueView(ran.json) };
+    },
+    async createIssue(input) {
+      const args = ["issue", "create", "--project", input.project, "--summary", input.summary];
+      if (input.description !== undefined) args.push("--description-file", "-");
+      args.push("--json", "idReadable,url");
+      const ran = ranJson(run, args, input.description);
+      if (!ran.ok) return readFailure(ran, host);
+      const json = isObj(ran.json) ? ran.json : {};
+      return {
+        ok: true,
+        data: { issueId: String(json.idReadable ?? ""), url: str(json.url), source: "ytrack" },
+      };
+    },
+    async addComment(issueId, text) {
+      const ran = ranJson(
+        run,
+        ["issue", "comment", issueId, "--body-file", "-", "--json", "id,url"],
+        text,
+      );
+      if (!ran.ok) return writeFailure(ran, host);
+      return {
+        ok: true,
+        data: { issueId, ...(isObj(ran.json) ? ran.json : {}) },
+      };
+    },
+    async addWorkItem(issueId, item) {
+      const ran = ranJson(run, [
+        "work-item",
+        "add",
+        issueId,
+        "--duration",
+        String(item.minutes),
+        "--date",
+        workDay(item.dateMs),
+        "--text",
+        item.text,
+        "--json",
+        "id,date,duration",
+      ]);
+      if (!ran.ok) return writeFailure(ran, host);
+      const json = isObj(ran.json) ? ran.json : {};
+      return {
+        ok: true,
+        data: { issueId, workItemId: json.id, minutes: item.minutes, dateMs: item.dateMs },
+      };
+    },
+    async texts(issueId, where) {
+      const ran =
+        where === "comments"
+          ? ranJson(run, ["issue", "view", issueId, "--json", "comments"])
+          : ranJson(run, ["work-item", "list", issueId, "--json", "id,text"]);
+      if (!ran.ok) return null;
+      const list = where === "comments" && isObj(ran.json) ? ran.json.comments : ran.json;
+      if (!Array.isArray(list)) return null;
+      // ytrack lists every item (no page cap) and leaves deleted comments out.
+      return {
+        texts: list.flatMap((item) =>
+          isObj(item) && typeof item.text === "string" ? [item.text] : [],
+        ),
+        complete: true,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------- selection
+
+/** ytrack from `env`'s PATH, aimed at youtrack.json's baseUrl when set. */
+export function youTrackBackend(env: NodeJS.ProcessEnv = process.env): YouTrackBackend {
+  const host = youTrackBaseUrl();
+  return ytrackBackend(ytrackRunner(env, host), host);
+}
+
+/** null when YouTrack writes are allowed, else the refusal naming WORKIT_YT_WRITE. */
+export function youTrackWriteGate(
+  env: NodeJS.ProcessEnv,
+  what = "a YouTrack write",
+): Extract<IssueOutcome<never>, { ok: false }> | null {
+  if (env[YT_WRITE_GATE] === "1") return null;
+  return {
+    ok: false,
+    code: "blocked",
+    error: `${what} requires ${YT_WRITE_GATE}=1 (refusing to mutate the tracker)`,
+    unblock: `set ${YT_WRITE_GATE}=1 for this command once the user asked for the write`,
+  };
+}

package/src/core/youtrack-tools.ts

@@ -0,0 +1,260 @@
+import path from "node:path";
+import { fail, ok, type Result } from "../core";
+import { configDir } from "./config";
+import { configDir as workitConfigDir, userHome } from "./workit-paths.mjs";
+import {
+  context as legacyContext,
+  meetingWorkItemText,
+  parseDuration as legacyParseDuration,
+  youTrackWorkDateMs,
+} from "./youtrack";
+import {
+  youTrackBackend,
+  youTrackWriteGate,
+  type WriteResult,
+  type YouTrackBackend,
+} from "./youtrack-backend";
+
+export const ISSUE_RE = /^[A-Z]+-\d+$/;
+export const message = (error: unknown) => (error instanceof Error ? error.message : String(error));
+
+// The config dir comes from core/workit-paths.mjs; default env (no args) routes
+// through configDir(), an explicit env resolves with `home` as its HOME.
+export const configPath = (env: NodeJS.ProcessEnv = process.env, home = userHome(env)) =>
+  path.join(
+    env === process.env ? configDir() : workitConfigDir({ ...env, HOME: home }),
+    "youtrack.json",
+  );
+
+type MaybePromise<T> = T | Promise<T>;
+export type LegacyValue = Record<string, unknown> | void;
+export type NotApplied = {
+  ok: false;
+  error: string;
+  outcome: "not_applied";
+  unblock?: string;
+};
+
+export type YouTrackOperations = {
+  context(input: Record<string, unknown>): MaybePromise<LegacyValue>;
+  parseDuration(text: string, workspaceRoot: string): MaybePromise<LegacyValue>;
+  postComment(issueId: string, markdown: string, workspaceRoot?: string): MaybePromise<LegacyValue>;
+  logTime(input: Record<string, unknown>): MaybePromise<LegacyValue>;
+};
+
+export const unwrap = (value: LegacyValue) => {
+  if (!value) return {};
+  if (value.error) throw new Error(String(value.error));
+  if (value.ok === false) throw new Error(String(value.error ?? "YouTrack operation failed"));
+  return (value.data as Record<string, unknown> | undefined) ?? value;
+};
+
+/**
+ * A write through ytrack (#263), as the legacy value shape, behind the
+ * WORKIT_YT_WRITE gate. A failure that surely did not land (gate, missing
+ * ytrack, logged out) stays a not_applied value with its unblock; any other
+ * failure throws, so callers report an unknown outcome.
+ */
+async function ytrackWrite(
+  write: (backend: YouTrackBackend) => Promise<WriteResult>,
+): Promise<LegacyValue> {
+  const gate = youTrackWriteGate(process.env);
+  if (gate)
+    return {
+      ok: false,
+      error: gate.error,
+      outcome: "not_applied",
+      unblock: gate.unblock,
+    };
+  const result = await write(youTrackBackend());
+  if (result.ok) return unwrap({ ok: true, data: result.data });
+  if (result.outcome === "not_applied")
+    return {
+      ok: false,
+      error: result.error,
+      outcome: "not_applied",
+      ...(result.unblock ? { unblock: result.unblock } : {}),
+    };
+  throw new Error(result.error);
+}
+
+export const defaultOperations: YouTrackOperations = {
+  context: (input) => legacyContext(input as never),
+  parseDuration: (text, workspaceRoot) => legacyParseDuration(text, workspaceRoot),
+  postComment: (issueId, markdown) =>
+    ytrackWrite((backend) => backend.addComment(issueId, markdown)),
+  logTime: (input) =>
+    ytrackWrite(async (backend) => {
+      const date = youTrackWorkDateMs(
+        input.dateMs != null ? String(input.dateMs) : String(input.date ?? "auto"),
+      );
+      if ("error" in date) return { ok: false, error: date.error, outcome: "not_applied" };
+      return backend.addWorkItem(String(input.issueId), {
+        minutes: Number(input.minutes),
+        text: typeof input.text === "string" ? input.text : "workit",
+        dateMs: date.data.dateMs,
+      });
+    }),
+};
+
+type PostInput = {
+  confirmed: boolean;
+  issueId: string;
+  markdown: string;
+  minutes?: number;
+  dateMs?: number;
+  workspace_root?: string;
+};
+
+type PostData = {
+  issueId: string;
+  postedComment: boolean;
+  loggedMinutes: number;
+  outcome?: "unknown" | "not_applied";
+  instructions?: string;
+  retry?: "youtrack.update" | "youtrack.time";
+  unblock?: string;
+};
+
+const notApplied = (value: LegacyValue): value is NotApplied =>
+  value?.ok === false && value.outcome === "not_applied";
+
+export async function postUpdate(
+  input: PostInput,
+  operations: Pick<YouTrackOperations, "postComment" | "logTime"> = defaultOperations,
+): Promise<Result<PostData>> {
+  if (input.confirmed !== true) return fail("confirmed: true required");
+  if (!ISSUE_RE.test(input.issueId)) return fail("invalid issueId");
+  if (!input.markdown?.trim()) return fail("markdown required");
+  if (input.minutes != null && input.minutes <= 0) return fail("minutes must be positive");
+
+  try {
+    const comment = await operations.postComment(
+      input.issueId,
+      input.markdown,
+      input.workspace_root,
+    );
+    if (notApplied(comment))
+      return fail(comment.error, {
+        issueId: input.issueId,
+        postedComment: false,
+        loggedMinutes: 0,
+        outcome: "not_applied",
+        retry: "youtrack.update",
+        ...(comment.unblock ? { unblock: comment.unblock } : {}),
+      });
+    unwrap(comment);
+  } catch (error) {
+    return fail(message(error), {
+      issueId: input.issueId,
+      postedComment: false,
+      loggedMinutes: 0,
+      outcome: "unknown",
+      instructions: "Check YouTrack comments manually; do not retry while the outcome is unknown.",
+    });
+  }
+
+  if (input.minutes != null) {
+    try {
+      const time = await operations.logTime({
+        issueId: input.issueId,
+        minutes: input.minutes,
+        ...(input.dateMs === undefined ? {} : { dateMs: input.dateMs }),
+        text: "workit update",
+        workspace_root: input.workspace_root,
+      });
+      if (notApplied(time))
+        return fail(time.error, {
+          issueId: input.issueId,
+          postedComment: true,
+          loggedMinutes: 0,
+          outcome: "not_applied",
+          retry: "youtrack.time",
+          ...(time.unblock ? { unblock: time.unblock } : {}),
+        });
+      unwrap(time);
+    } catch (error) {
+      return fail(message(error), {
+        issueId: input.issueId,
+        postedComment: true,
+        loggedMinutes: 0,
+        outcome: "unknown",
+        instructions:
+          "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+      });
+    }
+  }
+
+  return ok({
+    issueId: input.issueId,
+    postedComment: true,
+    loggedMinutes: input.minutes ?? 0,
+  });
+}
+
+export async function logTimeUpdate(
+  input: Record<string, unknown>,
+  operation: Pick<YouTrackOperations, "logTime"> = defaultOperations,
+): Promise<Result<Record<string, unknown>>> {
+  try {
+    const value = await operation.logTime(input);
+    if (notApplied(value))
+      return fail(value.error, {
+        issueId: input.issueId,
+        loggedMinutes: 0,
+        outcome: "not_applied",
+        retry: "youtrack.time",
+        ...(value.unblock ? { unblock: value.unblock } : {}),
+      });
+    return ok(unwrap(value));
+  } catch (error) {
+    return fail(message(error), {
+      issueId: input.issueId,
+      loggedMinutes: 0,
+      outcome: "unknown",
+      instructions:
+        "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+    });
+  }
+}
+
+export function normalizeContext(value: LegacyValue, mode?: string): LegacyValue {
+  if (!value || mode !== "meetings" || value.error) return value;
+  // Operations may return the legacy `{ data }` envelope; normalize inside it.
+  if (value.data && typeof value.data === "object" && !Array.isArray(value.data)) {
+    const inner = normalizeContext(value.data as Record<string, unknown>, mode);
+    return inner && inner.error
+      ? { ...value, ...inner, data: undefined }
+      : { ...value, data: inner };
+  }
+  const config = value.config as Record<string, unknown> | undefined;
+  const { meetingIssues: _meetingIssues, ...singleMeetingConfig } = config ?? {};
+  const options = Array.isArray(value.meetingOptions)
+    ? (value.meetingOptions as Array<Record<string, unknown>>)
+    : [];
+  // The meeting issue comes only from youtrack.json — there is no built-in one.
+  const configured = typeof config?.meetingIssue === "string" ? config.meetingIssue : "";
+  const resolved = typeof value.issueId === "string" ? value.issueId : "";
+  const firstOption = typeof options[0]?.issue === "string" ? options[0].issue : "";
+  const issue = configured || resolved || firstOption;
+  if (!issue)
+    return {
+      ...value,
+      error: "no meeting issue configured — set meetingIssue in youtrack.json",
+      requiresIssueInput: true,
+    };
+  const selected = options.find((option) => option.issue === issue) ?? {
+    key: "general",
+    issue,
+    label: issue,
+    workItemText: meetingWorkItemText(config),
+  };
+  return {
+    ...value,
+    config: singleMeetingConfig,
+    meetingOptions: [selected],
+    requiresMeetingChoice: false,
+    issueId: issue,
+    workItemText: meetingWorkItemText(config, selected),
+  };
+}

package/src/core/youtrack-writes.ts

@@ -0,0 +1,73 @@
+// Idempotent YouTrack writes for `workit youtrack note|time|meeting` (S16
+// review M4). Each comment or work item carries a deterministic marker,
+// `<!-- workit-action:<sha256> -->`, derived from the request. Before writing,
+// the issue is read back and a write whose marker is already present is
+// skipped (`already_done`); after a write with an unknown outcome (a timeout
+// after the server applied it), the read-back settles it instead of a retry
+// posting a duplicate.
+import { sha256 } from "./task-contract";
+import { youTrackBaseUrl } from "./youtrack";
+import { youTrackBackend, type YouTrackBackend } from "./youtrack-backend";
+
+export type MarkerWhere = "comments" | "workItems";
+
+/**
+ * The marker for one request. It names youtrack.json's baseUrl (read without
+ * the token file) so two instances never share a marker; with ytrack and no
+ * baseUrl it names ytrack's default host.
+ */
+export const youTrackMarker = (request: Record<string, unknown>): string =>
+  `<!-- workit-action:${sha256({ ...request, baseUrl: youTrackBaseUrl() ?? "ytrack:default" })} -->`;
+
+export const withMarker = (text: string, marker: string): string =>
+  `${text}${text ? "\n\n" : ""}${marker}`;
+
+/** true/false when the read-back is conclusive, null when it is not. */
+export async function markerPresent(
+  issueId: string,
+  marker: string,
+  where: MarkerWhere,
+  backend: YouTrackBackend = youTrackBackend(),
+): Promise<boolean | null> {
+  const read = await backend.texts(issueId, where);
+  if (!read) return null;
+  if (read.texts.some((text) => text.includes(marker))) return true;
+  // A partial read may hide an older match: only a hit is conclusive then.
+  return read.complete ? false : null;
+}
+
+type WriteResult = { ok: boolean; error?: string | null; data?: unknown };
+
+export type OnceOutcome =
+  | {
+      status: "done" | "already_done" | "settled";
+      data?: unknown;
+      /** The pre-write read-back could not rule out an earlier copy (>1 page). */
+      precheck?: "inconclusive";
+    }
+  | { status: "failed" | "unknown"; error: string; data?: unknown };
+
+/** Write at most once: skip when the marker is there, read back an unknown outcome. */
+export async function writeOnce(
+  issueId: string,
+  marker: string,
+  where: MarkerWhere,
+  write: () => Promise<WriteResult>,
+  backend: YouTrackBackend = youTrackBackend(),
+): Promise<OnceOutcome> {
+  const before = await markerPresent(issueId, marker, where, backend);
+  if (before === true) return { status: "already_done" };
+  const precheck = before === null ? { precheck: "inconclusive" as const } : {};
+  const result = await write();
+  if (result.ok) return { status: "done", data: result.data, ...precheck };
+  const outcome = (result.data as { outcome?: unknown } | undefined)?.outcome;
+  if (outcome === "not_applied")
+    return { status: "failed", error: result.error ?? "not applied", data: result.data };
+  const settled = await markerPresent(issueId, marker, where, backend);
+  if (settled === true) return { status: "settled", ...precheck };
+  return {
+    status: settled === false ? "failed" : "unknown",
+    error: result.error ?? "YouTrack write failed",
+    data: result.data,
+  };
+}