@picoai/tickets 0.2.0 → 0.4.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,176 @@
+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",
+        lane: profile.defaults?.planning?.lane ?? null,
+        horizon: profile.defaults?.planning?.horizon ?? null,
+      },
+      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,
+    });
+  }
+
+  for (const key of ["lane", "horizon"]) {
+    const value = config.defaults?.planning?.[key];
+    if (value !== undefined && value !== null && typeof value !== "string") {
+      issues.push({
+        severity: "error",
+        code: "CONFIG_DEFAULT_PLANNING_SCALAR_INVALID",
+        message: `defaults.planning.${key} must be a string or null`,
+        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,16 @@
 export const BASE_DIR = ".tickets/spec";
-export const FORMAT_VERSION = 2;
-export const FORMAT_VERSION_URL = "version/20260311-tickets-spec.md";
+export const FORMAT_VERSION = 3;
+export const FORMAT_VERSION_URL = "version/20260317-2-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;
+export const LIST_SORT_VALUES = ["ready", "priority", "lane", "rank", "updated", "title"];
+export const PLANNING_INDEX_FORMAT_ID = "0195a1b7-4a17-7c2e-8db2-4d5cb0f0d642";
+export const PLANNING_INDEX_FORMAT_LABEL = "planning-index-2026-03-17";

package/src/lib/index.js

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  FORMAT_VERSION,
+  FORMAT_VERSION_URL,
+  PLANNING_INDEX_FORMAT_ID,
+  PLANNING_INDEX_FORMAT_LABEL,
+} from "./constants.js";
+import { loadClaimEvents, deriveActiveClaim } from "./claims.js";
+import { loadWorkflowProfile, repoConfigPath } from "./config.js";
+import { buildPlanningSnapshotFromRows, normalizePlanning } from "./planning.js";
+import { collectTicketPaths } from "./validation.js";
+import { ensureDir, loadTicket, readJsonl, repoRoot, ticketsDir } from "./util.js";
+
+function fileSignature(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  const stat = fs.statSync(filePath);
+  return `${Math.trunc(stat.mtimeMs)}:${stat.size}`;
+}
+
+function listLogFiles(logsDir) {
+  if (!fs.existsSync(logsDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(logsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function computeLastUpdated(logsDir) {
+  let latest = "";
+
+  for (const name of listLogFiles(logsDir)) {
+    const logPath = path.join(logsDir, name);
+    for (const entry of readJsonl(logPath)) {
+      const ts = entry.ts;
+      if (typeof ts === "string" && (latest === "" || ts > latest)) {
+        latest = ts;
+      }
+    }
+  }
+
+  return latest;
+}
+
+function ticketPathsForRoot(root = repoRoot()) {
+  const previous = process.cwd();
+  try {
+    process.chdir(root);
+    return collectTicketPaths(null);
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+function collectSourceState(root = repoRoot()) {
+  const configPath = repoConfigPath(root);
+  const ticketStates = ticketPathsForRoot(root)
+    .map((ticketPath) => {
+      const ticketDir = path.dirname(ticketPath);
+      const logsDir = path.join(ticketDir, "logs");
+      const logFiles = listLogFiles(logsDir);
+      return {
+        id: path.basename(ticketDir),
+        ticket_path: path.relative(root, ticketPath),
+        ticket_signature: fileSignature(ticketPath),
+        log_count: logFiles.length,
+        logs: logFiles.map((name) => ({
+          name,
+          signature: fileSignature(path.join(logsDir, name)),
+        })),
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    config_fingerprint: fileSignature(configPath),
+    ticket_count: ticketStates.length,
+    tickets: ticketStates,
+  };
+}
+
+function buildRows(root = repoRoot(), profile = loadWorkflowProfile(root)) {
+  const rows = [];
+
+  for (const ticketPath of ticketPathsForRoot(root)) {
+    try {
+      const [frontMatter, body] = loadTicket(ticketPath);
+      const ticketDir = path.dirname(ticketPath);
+      const logsDir = path.join(ticketDir, "logs");
+      const activeClaim = deriveActiveClaim(loadClaimEvents(logsDir));
+
+      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: computeLastUpdated(logsDir),
+      });
+    } catch {
+      // Invalid tickets are surfaced by `validate`; derived views skip them.
+    }
+  }
+
+  return rows;
+}
+
+function indexPath(root = repoRoot()) {
+  return path.join(root, ".tickets", "derived", "planning-index.json");
+}
+
+function serializeMap(map) {
+  return Object.fromEntries([...map.entries()].map(([key, value]) => [key, [...value]]));
+}
+
+function buildIndexDocument(root = repoRoot()) {
+  const profile = loadWorkflowProfile(root);
+  const rows = buildRows(root, profile);
+  const snapshot = buildPlanningSnapshotFromRows(rows, profile);
+
+  return {
+    index_format_id: PLANNING_INDEX_FORMAT_ID,
+    index_format_label: PLANNING_INDEX_FORMAT_LABEL,
+    tool: {
+      format_version: FORMAT_VERSION,
+      format_version_url: FORMAT_VERSION_URL,
+    },
+    source_state: collectSourceState(root),
+    profile,
+    rows: snapshot.rows,
+    predecessors_by_id: serializeMap(snapshot.predecessorsById),
+    members_by_group: serializeMap(snapshot.membersByGroup),
+  };
+}
+
+function readIndex(root = repoRoot()) {
+  const outPath = indexPath(root);
+  if (!fs.existsSync(outPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(outPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isFresh(index, root = repoRoot()) {
+  if (!index) {
+    return false;
+  }
+  if (index.index_format_id !== PLANNING_INDEX_FORMAT_ID) {
+    return false;
+  }
+  if (index.tool?.format_version !== FORMAT_VERSION) {
+    return false;
+  }
+  if (index.tool?.format_version_url !== FORMAT_VERSION_URL) {
+    return false;
+  }
+
+  const currentState = collectSourceState(root);
+  return JSON.stringify(index.source_state ?? null) === JSON.stringify(currentState);
+}
+
+export function planningIndexPath(root = repoRoot()) {
+  return indexPath(root);
+}
+
+export function invalidatePlanningIndex(root = repoRoot()) {
+  const outPath = indexPath(root);
+  if (fs.existsSync(outPath)) {
+    fs.unlinkSync(outPath);
+  }
+}
+
+export function rebuildPlanningIndex(root = repoRoot()) {
+  const outPath = indexPath(root);
+  ensureDir(path.dirname(outPath));
+  const index = buildIndexDocument(root);
+  fs.writeFileSync(outPath, `${JSON.stringify(index, null, 2)}\n`);
+  return buildPlanningSnapshotFromRows(index.rows, index.profile);
+}
+
+export function refreshPlanningIndexIfPresent(root = repoRoot()) {
+  const outPath = indexPath(root);
+  if (!fs.existsSync(outPath)) {
+    return null;
+  }
+
+  try {
+    return rebuildPlanningIndex(root);
+  } catch {
+    invalidatePlanningIndex(root);
+    return null;
+  }
+}
+
+export function loadPlanningSnapshot(options = {}) {
+  const root = options.root ?? repoRoot();
+  const persist = options.persist ?? true;
+  const existing = readIndex(root);
+  if (existing && isFresh(existing, root)) {
+    return buildPlanningSnapshotFromRows(existing.rows ?? [], existing.profile ?? loadWorkflowProfile(root));
+  }
+
+  if (!persist) {
+    const profile = loadWorkflowProfile(root);
+    return buildPlanningSnapshotFromRows(buildRows(root, profile), profile);
+  }
+
+  return rebuildPlanningIndex(root);
+}
+
+export function currentSourceState(root = repoRoot()) {
+  return collectSourceState(root);
+}
+
+export function planningIndexExists(root = repoRoot()) {
+  return fs.existsSync(indexPath(root));
+}

package/src/lib/listing.js

@@ -1,85 +1,25 @@
-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, body] = validateTicket(ticketPath);
-    if (!frontMatter || Object.keys(frontMatter).length === 0) {
-      continue;
-    }
-    if (!passesFilters(frontMatter, body, 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, body, 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${body ?? ""}`.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, sortPlanningRows } from "./planning.js";
+
+export function listTickets(snapshot, filters, options = {}) {
+  const rows = sortPlanningRows(listPlanningRows(snapshot, filters), options.sortBy, options.reverse);
+  return rows.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,
+    blocked_by: row.blocked_by,
+    active_claim: row.active_claim,
+    claim_summary: row.claim_summary,
+    last_updated: row.last_updated,
+  }));
 }