@picoai/tickets 0.1.0 → 0.3.0

package/src/lib/claims.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { CLAIM_ACTION_VALUES } from "./constants.js";
+import { readJsonl } from "./util.js";
+
+function claimEventsForLog(logPath) {
+  return readJsonl(logPath)
+    .filter((entry) => entry.event_type === "claim" && entry.claim && typeof entry.claim === "object")
+    .map((entry) => ({ ...entry, log_path: logPath }));
+}
+
+export function loadClaimEvents(logsDir) {
+  if (!fs.existsSync(logsDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(logsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+    .map((entry) => path.join(logsDir, entry.name))
+    .sort((a, b) => a.localeCompare(b))
+    .flatMap((logPath) => claimEventsForLog(logPath))
+    .sort((a, b) => `${a.ts ?? ""}:${a.run_started ?? ""}`.localeCompare(`${b.ts ?? ""}:${b.run_started ?? ""}`));
+}
+
+export function deriveActiveClaim(entries, now = new Date()) {
+  let active = null;
+
+  for (const entry of entries) {
+    const claim = entry.claim;
+    if (!claim || !CLAIM_ACTION_VALUES.includes(claim.action)) {
+      continue;
+    }
+
+    if (claim.action === "release") {
+      if (active && (!claim.claim_id || claim.claim_id === active.claim_id)) {
+        active = null;
+      }
+      continue;
+    }
+
+    active = {
+      claim_id: claim.claim_id,
+      action: claim.action,
+      holder_id: claim.holder_id,
+      holder_type: claim.holder_type,
+      reason: claim.reason ?? "",
+      ttl_minutes: claim.ttl_minutes,
+      expires_at: claim.expires_at,
+      supersedes_claim_id: claim.supersedes_claim_id ?? null,
+      ts: entry.ts,
+    };
+  }
+
+  if (!active) {
+    return null;
+  }
+
+  const expiresAt = active.expires_at ? Date.parse(active.expires_at) : Number.NaN;
+  if (!Number.isNaN(expiresAt) && expiresAt <= now.getTime()) {
+    return null;
+  }
+
+  return active;
+}

package/src/lib/config.js

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import yaml from "yaml";
+
+import {
+  DEFAULT_CLAIM_TTL_MINUTES,
+  PLANNING_NODE_TYPES,
+  WORKFLOW_MODE_VALUES,
+} from "./constants.js";
+import { packageRoot, repoRoot, ticketsDir } from "./util.js";
+
+const DEFAULT_PROFILE_RELATIVE_PATH = path.join(".tickets", "spec", "profile", "defaults.yml");
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepMerge(base, override) {
+  if (!isObject(base) || !isObject(override)) {
+    return override;
+  }
+
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (isObject(value) && isObject(base[key])) {
+      merged[key] = deepMerge(base[key], value);
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+export function defaultProfilePath() {
+  return path.join(packageRoot(), DEFAULT_PROFILE_RELATIVE_PATH);
+}
+
+export function repoConfigPath(root = repoRoot()) {
+  return path.join(root, ".tickets", "config.yml");
+}
+
+export function loadDefaultProfile() {
+  return yaml.parse(fs.readFileSync(defaultProfilePath(), "utf8")) ?? {};
+}
+
+export function loadRepoConfig(root = repoRoot()) {
+  const configPath = repoConfigPath(root);
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+  const parsed = yaml.parse(fs.readFileSync(configPath, "utf8")) ?? {};
+  if (!isObject(parsed)) {
+    throw new Error("Repo config must be a mapping");
+  }
+  return parsed;
+}
+
+export function loadWorkflowProfile(root = repoRoot()) {
+  return deepMerge(loadDefaultProfile(), loadRepoConfig(root));
+}
+
+export function buildInitialRepoConfig(profile = loadDefaultProfile()) {
+  return {
+    workflow: {
+      mode: profile.workflow?.mode ?? "auto",
+    },
+    defaults: {
+      planning: {
+        node_type: profile.defaults?.planning?.node_type ?? "work",
+      },
+      claims: {
+        ttl_minutes: profile.defaults?.claims?.ttl_minutes ?? DEFAULT_CLAIM_TTL_MINUTES,
+      },
+    },
+    semantics: {
+      terms: profile.semantics?.terms ?? {},
+    },
+    views: profile.views ?? {},
+  };
+}
+
+export function renderRepoConfig(profile = loadDefaultProfile()) {
+  const body = yaml.stringify(buildInitialRepoConfig(profile)).trimEnd();
+  return [
+    "# Repo-local @picoai/tickets overrides",
+    "# This file is authoritative for local semantic mapping and defaults.",
+    "# Safe to customize. `init --apply` will not overwrite it.",
+    "",
+    body,
+    "",
+  ].join("\n");
+}
+
+export function validateRepoConfig(root = repoRoot()) {
+  const issues = [];
+  const configPath = repoConfigPath(root);
+
+  if (!fs.existsSync(configPath)) {
+    return issues;
+  }
+
+  let config;
+  try {
+    config = loadRepoConfig(root);
+  } catch (error) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_INVALID",
+      message: String(error.message ?? error),
+      config_path: configPath,
+    });
+    return issues;
+  }
+
+  const mode = config.workflow?.mode;
+  if (mode !== undefined && !WORKFLOW_MODE_VALUES.includes(mode)) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_WORKFLOW_MODE_INVALID",
+      message: `workflow.mode must be one of ${WORKFLOW_MODE_VALUES.join(", ")}`,
+      config_path: configPath,
+    });
+  }
+
+  const nodeType = config.defaults?.planning?.node_type;
+  if (nodeType !== undefined && !PLANNING_NODE_TYPES.includes(nodeType)) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_DEFAULT_NODE_TYPE_INVALID",
+      message: `defaults.planning.node_type must be one of ${PLANNING_NODE_TYPES.join(", ")}`,
+      config_path: configPath,
+    });
+  }
+
+  const ttlMinutes = config.defaults?.claims?.ttl_minutes;
+  if (ttlMinutes !== undefined && (!Number.isInteger(ttlMinutes) || ttlMinutes <= 0)) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_CLAIM_TTL_INVALID",
+      message: "defaults.claims.ttl_minutes must be a positive integer",
+      config_path: configPath,
+    });
+  }
+
+  const terms = config.semantics?.terms;
+  if (terms !== undefined && !isObject(terms)) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TERMS_INVALID",
+      message: "semantics.terms must be a mapping",
+      config_path: configPath,
+    });
+  }
+
+  return issues;
+}
+
+export function ensureTicketsRoot(root = repoRoot()) {
+  fs.mkdirSync(ticketsDir(), { recursive: true });
+  fs.mkdirSync(path.dirname(repoConfigPath(root)), { recursive: true });
+}

package/src/lib/constants.js

@@ -1,7 +1,13 @@
 export const BASE_DIR = ".tickets/spec";
-export const FORMAT_VERSION = 1;
-export const FORMAT_VERSION_URL = "version/20260205-tickets-spec.md";
+export const FORMAT_VERSION = 3;
+export const FORMAT_VERSION_URL = "version/20260317-tickets-spec.md";
 
 export const STATUS_VALUES = ["todo", "doing", "blocked", "done", "canceled"];
 export const PRIORITY_VALUES = ["low", "medium", "high", "critical"];
 export const ASSIGNMENT_MODE_VALUES = ["human_only", "agent_only", "mixed"];
+export const PLANNING_NODE_TYPES = ["work", "group", "checkpoint"];
+export const RESOLUTION_VALUES = ["completed", "merged", "dropped"];
+export const CLAIM_ACTION_VALUES = ["acquire", "renew", "release", "override"];
+export const WORKFLOW_MODE_VALUES = ["auto", "doc_first", "skill_first"];
+export const GRAPH_VIEW_VALUES = ["dependency", "sequence", "portfolio", "all"];
+export const DEFAULT_CLAIM_TTL_MINUTES = 60;

package/src/lib/listing.js

@@ -1,85 +1,22 @@
-import fs from "node:fs";
-import path from "node:path";
-
-import { readJsonl } from "./util.js";
-import { collectTicketPaths, validateTicket } from "./validation.js";
-
-export function listTickets(filters) {
-  const rows = [];
-
-  for (const ticketPath of collectTicketPaths(null)) {
-    const [, frontMatter] = validateTicket(ticketPath);
-    if (!frontMatter || Object.keys(frontMatter).length === 0) {
-      continue;
-    }
-    if (!passesFilters(frontMatter, filters)) {
-      continue;
-    }
-
-    rows.push({
-      id: frontMatter.id ?? "",
-      title: frontMatter.title ?? "",
-      status: frontMatter.status ?? "",
-      priority: frontMatter.priority ?? "",
-      owner: frontMatter.assignment?.owner,
-      mode: frontMatter.assignment?.mode,
-      last_updated: lastUpdated(path.dirname(ticketPath)),
-    });
-  }
-
-  return rows;
-}
-
-function passesFilters(frontMatter, filters) {
-  if (filters.status && frontMatter.status !== filters.status) {
-    return false;
-  }
-  if (filters.priority && frontMatter.priority !== filters.priority) {
-    return false;
-  }
-  if (filters.mode && frontMatter.assignment?.mode !== filters.mode) {
-    return false;
-  }
-  if (filters.owner && frontMatter.assignment?.owner !== filters.owner) {
-    return false;
-  }
-  if (filters.label) {
-    const labels = Array.isArray(frontMatter.labels) ? frontMatter.labels : [];
-    if (!labels.includes(filters.label)) {
-      return false;
-    }
-  }
-  if (filters.text) {
-    const text = String(filters.text).toLowerCase();
-    const haystack = `${frontMatter.title ?? ""}\n${frontMatter.description ?? ""}`.toLowerCase();
-    if (!haystack.includes(text)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-function lastUpdated(ticketDir) {
-  const logsDir = path.join(ticketDir, "logs");
-  let latest = "";
-
-  if (!fs.existsSync(logsDir)) {
-    return latest;
-  }
-
-  const logFiles = fs
-    .readdirSync(logsDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-    .map((entry) => path.join(logsDir, entry.name));
-
-  for (const logFile of logFiles) {
-    for (const entry of readJsonl(logFile)) {
-      const ts = entry.ts;
-      if (typeof ts === "string" && (latest === "" || ts > latest)) {
-        latest = ts;
-      }
-    }
-  }
-
-  return latest;
+import { listPlanningRows } from "./planning.js";
+
+export function listTickets(filters, options = {}) {
+  return listPlanningRows(filters, options).map((row) => ({
+    id: row.id,
+    title: row.title,
+    status: row.status,
+    priority: row.priority ?? "",
+    owner: row.owner,
+    mode: row.mode,
+    node_type: row.planning.node_type,
+    lane: row.planning.lane,
+    rank: row.planning.rank,
+    horizon: row.planning.horizon,
+    group_ids: row.planning.group_ids,
+    precedes: row.planning.precedes,
+    resolution: row.resolution,
+    ready: row.ready,
+    active_claim: row.active_claim,
+    last_updated: row.last_updated,
+  }));
 }

package/src/lib/planning.js

@@ -0,0 +1,355 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { loadWorkflowProfile } from "./config.js";
+import { deriveActiveClaim, loadClaimEvents } from "./claims.js";
+import { collectTicketPaths } from "./validation.js";
+import { loadTicket, readJsonl } from "./util.js";
+
+const TERMINAL_STATUSES = new Set(["done", "canceled"]);
+
+function isTerminal(status) {
+  return TERMINAL_STATUSES.has(status);
+}
+
+function lastUpdated(ticketDir) {
+  const logsDir = path.join(ticketDir, "logs");
+  let latest = "";
+
+  if (!fs.existsSync(logsDir)) {
+    return latest;
+  }
+
+  const logFiles = fs
+    .readdirSync(logsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+    .map((entry) => path.join(logsDir, entry.name));
+
+  for (const logFile of logFiles) {
+    for (const entry of readJsonl(logFile)) {
+      const ts = entry.ts;
+      if (typeof ts === "string" && (latest === "" || ts > latest)) {
+        latest = ts;
+      }
+    }
+  }
+
+  return latest;
+}
+
+function normalizePlanning(frontMatter, profile) {
+  const planning = frontMatter.planning ?? {};
+  return {
+    node_type: planning.node_type ?? profile.defaults?.planning?.node_type ?? "work",
+    group_ids: Array.isArray(planning.group_ids) ? planning.group_ids : [],
+    lane: typeof planning.lane === "string" && planning.lane.trim() ? planning.lane.trim() : null,
+    rank: Number.isInteger(planning.rank) ? planning.rank : null,
+    horizon: typeof planning.horizon === "string" && planning.horizon.trim() ? planning.horizon.trim() : null,
+    precedes: Array.isArray(planning.precedes) ? planning.precedes : [],
+  };
+}
+
+function collectGroupLeaves(groupId, membersByGroup, nodesById, seen = new Set(), leaves = new Set()) {
+  if (seen.has(groupId)) {
+    return leaves;
+  }
+  seen.add(groupId);
+
+  for (const childId of membersByGroup.get(groupId) ?? []) {
+    const child = nodesById.get(childId);
+    if (!child) {
+      continue;
+    }
+    if (child.planning.node_type === "work") {
+      leaves.add(child.id);
+    } else {
+      collectGroupLeaves(child.id, membersByGroup, nodesById, seen, leaves);
+    }
+  }
+
+  return leaves;
+}
+
+function computeRollup(row, membersByGroup, nodesById) {
+  if (!["group", "checkpoint"].includes(row.planning.node_type)) {
+    return null;
+  }
+
+  const leafIds = [...collectGroupLeaves(row.id, membersByGroup, nodesById)];
+  const leafRows = leafIds.map((id) => nodesById.get(id)).filter(Boolean);
+  const merged = leafRows.filter((leaf) => leaf.resolution === "merged").length;
+  const dropped = leafRows.filter((leaf) => leaf.resolution === "dropped").length;
+  const activeLeafRows = leafRows.filter((leaf) => !["merged", "dropped"].includes(leaf.resolution ?? ""));
+  const doneCompleted = activeLeafRows.filter(
+    (leaf) => leaf.resolution === "completed" || (leaf.status === "done" && !leaf.resolution),
+  ).length;
+
+  return {
+    total_leaf: leafRows.length,
+    active_leaf: activeLeafRows.length,
+    todo: activeLeafRows.filter((leaf) => leaf.status === "todo").length,
+    doing: activeLeafRows.filter((leaf) => leaf.status === "doing").length,
+    blocked: activeLeafRows.filter((leaf) => leaf.status === "blocked").length,
+    done_completed: doneCompleted,
+    merged,
+    dropped,
+    percent_complete: activeLeafRows.length === 0 ? 0 : doneCompleted / activeLeafRows.length,
+  };
+}
+
+function passesFilters(row, filters) {
+  if (filters.status && row.status !== filters.status) {
+    return false;
+  }
+  if (filters.priority && row.priority !== filters.priority) {
+    return false;
+  }
+  if (filters.mode && row.mode !== filters.mode) {
+    return false;
+  }
+  if (filters.owner && row.owner !== filters.owner) {
+    return false;
+  }
+  if (filters.label && !row.labels.includes(filters.label)) {
+    return false;
+  }
+  if (filters.text) {
+    const needle = String(filters.text).toLowerCase();
+    const haystack = `${row.title}\n${row.body}`.toLowerCase();
+    if (!haystack.includes(needle)) {
+      return false;
+    }
+  }
+  if (filters.nodeType && row.planning.node_type !== filters.nodeType) {
+    return false;
+  }
+  if (filters.group && !row.planning.group_ids.includes(filters.group)) {
+    return false;
+  }
+  if (filters.lane && row.planning.lane !== filters.lane) {
+    return false;
+  }
+  if (filters.horizon && row.planning.horizon !== filters.horizon) {
+    return false;
+  }
+  if (filters.claimed && !row.active_claim) {
+    return false;
+  }
+  if (filters.claimedBy && row.active_claim?.holder_id !== filters.claimedBy) {
+    return false;
+  }
+  if (filters.ready && !row.ready) {
+    return false;
+  }
+  return true;
+}
+
+export function buildPlanningSnapshot(options = {}) {
+  const profile = options.profile ?? loadWorkflowProfile();
+  const paths = collectTicketPaths(null);
+  const rows = [];
+
+  for (const ticketPath of paths) {
+    try {
+      const [frontMatter, body] = loadTicket(ticketPath);
+      const ticketDir = path.dirname(ticketPath);
+      const activeClaim = deriveActiveClaim(loadClaimEvents(path.join(ticketDir, "logs")));
+
+      rows.push({
+        id: frontMatter.id ?? "",
+        title: frontMatter.title ?? "",
+        status: frontMatter.status ?? "",
+        priority: frontMatter.priority ?? "",
+        owner: frontMatter.assignment?.owner ?? null,
+        mode: frontMatter.assignment?.mode ?? null,
+        labels: Array.isArray(frontMatter.labels) ? frontMatter.labels.filter((label) => typeof label === "string") : [],
+        body: body ?? "",
+        path: ticketPath,
+        dependencies: Array.isArray(frontMatter.dependencies) ? frontMatter.dependencies : [],
+        blocks: Array.isArray(frontMatter.blocks) ? frontMatter.blocks : [],
+        related: Array.isArray(frontMatter.related) ? frontMatter.related : [],
+        planning: normalizePlanning(frontMatter, profile),
+        resolution: frontMatter.resolution ?? null,
+        active_claim: activeClaim,
+        last_updated: lastUpdated(ticketDir),
+      });
+    } catch {
+      // Invalid tickets are surfaced by `validate`; views skip them.
+    }
+  }
+
+  const nodesById = new Map(rows.map((row) => [row.id, row]));
+  const predecessorsById = new Map();
+  const membersByGroup = new Map();
+
+  for (const row of rows) {
+    for (const successorId of row.planning.precedes) {
+      if (!predecessorsById.has(successorId)) {
+        predecessorsById.set(successorId, []);
+      }
+      predecessorsById.get(successorId).push(row.id);
+    }
+    for (const groupId of row.planning.group_ids) {
+      if (!membersByGroup.has(groupId)) {
+        membersByGroup.set(groupId, []);
+      }
+      membersByGroup.get(groupId).push(row.id);
+    }
+  }
+
+  for (const row of rows) {
+    const depsSatisfied = row.dependencies.every((id) => {
+      const dependency = nodesById.get(id);
+      return dependency ? isTerminal(dependency.status) : false;
+    });
+    const predecessorsSatisfied = (predecessorsById.get(row.id) ?? []).every((id) => {
+      const predecessor = nodesById.get(id);
+      return predecessor ? isTerminal(predecessor.status) : false;
+    });
+
+    row.ready =
+      row.planning.node_type === "work" &&
+      !isTerminal(row.status) &&
+      row.mode !== "human_only" &&
+      depsSatisfied &&
+      predecessorsSatisfied;
+    row.rollup = computeRollup(row, membersByGroup, nodesById);
+  }
+
+  return {
+    profile,
+    rows,
+    nodesById,
+    predecessorsById,
+    membersByGroup,
+  };
+}
+
+export function listPlanningRows(filters = {}, options = {}) {
+  const snapshot = buildPlanningSnapshot(options);
+  return snapshot.rows.filter((row) => passesFilters(row, filters));
+}
+
+export function buildGraphData(snapshot, options = {}) {
+  const view = options.view ?? "dependency";
+  const includeRelated = options.includeRelated ?? false;
+  const rootId = options.ticket ?? null;
+  const edgeMap = new Map();
+  const nodes = new Map(snapshot.rows.map((row) => [row.id, row]));
+
+  function addEdge(type, from, to) {
+    const key = `${type}:${from}:${to}`;
+    if (!edgeMap.has(key)) {
+      edgeMap.set(key, { type, from, to });
+    }
+  }
+
+  for (const row of snapshot.rows) {
+    if (["dependency", "all"].includes(view)) {
+      for (const dependency of row.dependencies) {
+        addEdge("dependency", dependency, row.id);
+      }
+      for (const blocked of row.blocks) {
+        addEdge("blocks", row.id, blocked);
+      }
+      if (includeRelated) {
+        for (const related of row.related) {
+          addEdge("related", row.id, related);
+        }
+      }
+    }
+
+    if (["sequence", "portfolio", "all"].includes(view)) {
+      for (const successor of row.planning.precedes) {
+        addEdge("precedes", row.id, successor);
+      }
+    }
+
+    if (["portfolio", "all"].includes(view)) {
+      for (const groupId of row.planning.group_ids) {
+        addEdge("contains", groupId, row.id);
+      }
+    }
+  }
+
+  let nodeIds = new Set(nodes.keys());
+  if (rootId) {
+    const queue = [rootId];
+    const seen = new Set();
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (!current || seen.has(current)) {
+        continue;
+      }
+      seen.add(current);
+      for (const edge of edgeMap.values()) {
+        if (edge.from === current && !seen.has(edge.to)) {
+          queue.push(edge.to);
+        }
+        if (edge.to === current && !seen.has(edge.from)) {
+          queue.push(edge.from);
+        }
+      }
+    }
+    nodeIds = seen;
+  }
+
+  const filteredEdges = [...edgeMap.values()].filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+  const filteredNodes = [...nodeIds].map((id) => nodes.get(id)).filter(Boolean);
+
+  return {
+    root_id: rootId,
+    nodes: filteredNodes,
+    edges: filteredEdges,
+  };
+}
+
+export function buildPlanSummary(options = {}) {
+  const snapshot = buildPlanningSnapshot(options);
+  let rows = snapshot.rows;
+
+  if (options.group) {
+    rows = rows.filter((row) => row.id === options.group || row.planning.group_ids.includes(options.group));
+  }
+  if (options.horizon) {
+    rows = rows.filter((row) => row.planning.horizon === options.horizon);
+  }
+
+  const groups = rows.filter((row) => ["group", "checkpoint"].includes(row.planning.node_type));
+  const ready = rows
+    .filter((row) => row.ready)
+    .sort((a, b) => {
+      const lane = String(a.planning.lane ?? "").localeCompare(String(b.planning.lane ?? ""));
+      if (lane !== 0) {
+        return lane;
+      }
+      const rankA = a.planning.rank ?? Number.MAX_SAFE_INTEGER;
+      const rankB = b.planning.rank ?? Number.MAX_SAFE_INTEGER;
+      if (rankA !== rankB) {
+        return rankA - rankB;
+      }
+      return a.title.localeCompare(b.title);
+    });
+
+  return {
+    generated_at: new Date().toISOString(),
+    workflow_mode: snapshot.profile.workflow?.mode ?? "auto",
+    semantics: snapshot.profile.semantics?.terms ?? {},
+    ready: ready.map((row) => ({
+      id: row.id,
+      title: row.title,
+      lane: row.planning.lane,
+      rank: row.planning.rank,
+      horizon: row.planning.horizon,
+      active_claim: row.active_claim,
+    })),
+    groups: groups.map((row) => ({
+      id: row.id,
+      title: row.title,
+      node_type: row.planning.node_type,
+      lane: row.planning.lane,
+      horizon: row.planning.horizon,
+      rollup: row.rollup,
+    })),
+  };
+}