@picoai/tickets 0.3.0 → 0.5.0

package/src/lib/config.js

@@ -68,6 +68,8 @@ export function buildInitialRepoConfig(profile = loadDefaultProfile()) {
     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,
@@ -133,6 +135,18 @@ export function validateRepoConfig(root = repoRoot()) {
     });
   }
 
+  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({

package/src/lib/constants.js

@@ -1,13 +1,18 @@
 export const BASE_DIR = ".tickets/spec";
 export const FORMAT_VERSION = 3;
-export const FORMAT_VERSION_URL = "version/20260317-tickets-spec.md";
+export const FORMAT_VERSION_URL = "version/20260317-4-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 COMPLETION_ACCEPTANCE_VALUES = ["met", "not_met"];
+export const COMPLETION_VERIFICATION_VALUES = ["passed", "failed", "not_run"];
 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,7 +1,8 @@
-import { listPlanningRows } from "./planning.js";
+import { listPlanningRows, sortPlanningRows } from "./planning.js";
 
-export function listTickets(filters, options = {}) {
-  return listPlanningRows(filters, options).map((row) => ({
+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,
@@ -16,7 +17,9 @@ export function listTickets(filters, options = {}) {
     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,
   }));
 }