@picoai/tickets 0.1.0

package/src/lib/constants.js

@@ -0,0 +1,7 @@
+export const BASE_DIR = ".tickets/spec";
+export const FORMAT_VERSION = 1;
+export const FORMAT_VERSION_URL = "version/20260205-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"];

package/src/lib/listing.js

@@ -0,0 +1,85 @@
+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;
+}

package/src/lib/repair.js

@@ -0,0 +1,338 @@
+import fs from "node:fs";
+import readline from "node:readline/promises";
+
+import yaml from "yaml";
+
+import {
+  FORMAT_VERSION,
+  FORMAT_VERSION_URL,
+  PRIORITY_VALUES,
+} from "./constants.js";
+import {
+  iso8601,
+  loadTicket,
+  newUuidv7,
+  nowUtc,
+  parseIso,
+  writeTicket,
+} from "./util.js";
+
+export function loadIssuesFile(filePath) {
+  return yaml.parse(fs.readFileSync(filePath, "utf8")) ?? {};
+}
+
+export async function applyRepairs(repairs, options = {}) {
+  const includeOptional = options.includeOptional ?? false;
+  const nonInteractive = options.nonInteractive ?? false;
+  const applied = [];
+
+  for (const repair of repairs) {
+    if (repair.optional && !includeOptional) {
+      continue;
+    }
+    if (!repair.enabled) {
+      continue;
+    }
+
+    const action = repair.action;
+    const params = repair.params ?? {};
+    const ticketPath = repair.ticket_path;
+
+    if (action === "set_front_matter_field") {
+      const field = params.field;
+      let value = params.value;
+      if (value == null && params.generate_uuidv7) {
+        value = newUuidv7();
+      }
+      if (value == null) {
+        if (nonInteractive) {
+          throw new Error(`Repair needs value for ${field}`);
+        }
+        throw new Error(`Interactive value required for ${field}`);
+      }
+      setFrontMatterField(ticketPath, field, value);
+      applied.push(`${ticketPath}: set ${field}`);
+      continue;
+    }
+
+    if (action === "add_sections") {
+      addMissingSections(ticketPath);
+      applied.push(`${ticketPath}: added missing sections`);
+      continue;
+    }
+
+    if (action === "normalize_created_at") {
+      normalizeCreatedAt(ticketPath);
+      applied.push(`${ticketPath}: normalized created_at`);
+      continue;
+    }
+
+    if (action === "normalize_labels") {
+      normalizeLabels(ticketPath);
+      applied.push(`${ticketPath}: normalized labels`);
+      continue;
+    }
+
+    if (action === "set_assignment_owner") {
+      setAssignmentOwner(ticketPath, params.value ?? null);
+      applied.push(`${ticketPath}: set assignment.owner`);
+      continue;
+    }
+
+    if (action === "reset_verification_commands") {
+      resetVerificationCommands(ticketPath, Array.isArray(params.commands) ? params.commands : []);
+      applied.push(`${ticketPath}: reset verification.commands`);
+      continue;
+    }
+
+    if (action === "normalize_verification_commands") {
+      normalizeVerificationCommands(ticketPath);
+      applied.push(`${ticketPath}: normalized verification.commands`);
+      continue;
+    }
+
+    if (nonInteractive) {
+      throw new Error(`Unsupported repair action ${action}`);
+    }
+  }
+
+  return applied;
+}
+
+export async function runInteractive(repairs, options = {}) {
+  const includeOptional = options.includeOptional ?? false;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("Interactive mode requires a TTY");
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const prepared = [];
+
+  try {
+    for (const repair of repairs) {
+      if (repair.optional && !includeOptional) {
+        continue;
+      }
+
+      const [description, suggested] = describeRepair(repair);
+      process.stdout.write(`\nRepair ${repair.id}: ${description}\n`);
+      const applyChoice = await promptYesNo(rl, "Apply this repair?", true);
+      if (!applyChoice) {
+        continue;
+      }
+
+      repair.enabled = true;
+      const action = repair.action;
+      const params = repair.params ?? {};
+
+      if (action === "set_front_matter_field") {
+        params.value = await promptValueForField(rl, params.field, repair.ticket_path, suggested);
+      } else if (action === "set_assignment_owner") {
+        params.value = await promptValueForField(rl, "assignment.owner", repair.ticket_path, suggested);
+      } else if (action === "reset_verification_commands") {
+        params.commands = await promptCommands(rl, Array.isArray(suggested) ? suggested : []);
+      }
+
+      repair.params = params;
+      prepared.push(repair);
+    }
+  } finally {
+    rl.close();
+  }
+
+  return applyRepairs(prepared, { nonInteractive: true, includeOptional });
+}
+
+function describeRepair(repair) {
+  const action = repair.action;
+  const field = repair.params?.field;
+  const ticketPath = repair.ticket_path ?? "";
+  const value = repair.params?.value;
+
+  if (action === "add_sections") {
+    return [`Add missing required sections to ${ticketPath}.`, null];
+  }
+  if (action === "normalize_created_at") {
+    return [`Normalize created_at to ISO8601 UTC in ${ticketPath}.`, iso8601(nowUtc())];
+  }
+  if (action === "set_front_matter_field") {
+    if (field === "id") {
+      return ["Set ticket id to a valid UUIDv7 (used to identify the ticket).", newUuidv7()];
+    }
+    if (field === "version") {
+      return ["Set format version (integer, current 1).", FORMAT_VERSION];
+    }
+    if (field === "version_url") {
+      return ["Set version_url (path to the format definition for this version).", FORMAT_VERSION_URL];
+    }
+    if (field === "priority") {
+      return ["Set priority (low|medium|high|critical).", "medium"];
+    }
+    if (field === "labels") {
+      return ["Reset labels to a list of strings (comma-separated).", []];
+    }
+    return [`Set front matter field '${field}'.`, value];
+  }
+  if (action === "normalize_labels") {
+    return ["Normalize labels to strings, dropping invalid entries.", null];
+  }
+  if (action === "set_assignment_owner") {
+    return ["Set assignment.owner (who owns this ticket; freeform handle).", value];
+  }
+  if (action === "reset_verification_commands") {
+    return ["Set verification.commands (commands to verify acceptance).", value ?? []];
+  }
+  if (action === "normalize_verification_commands") {
+    return ["Normalize verification.commands to strings, dropping invalid entries.", null];
+  }
+  return ["Apply repair", value];
+}
+
+async function promptYesNo(rl, message, defaultValue) {
+  const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
+  while (true) {
+    const response = (await rl.question(`${message}${suffix}`)).trim().toLowerCase();
+    if (!response) {
+      return defaultValue;
+    }
+    if (["y", "yes"].includes(response)) {
+      return true;
+    }
+    if (["n", "no"].includes(response)) {
+      return false;
+    }
+    process.stdout.write("Please enter y or n.\n");
+  }
+}
+
+async function promptValueForField(rl, field, ticketPath, defaultValue) {
+  let current = null;
+  if (ticketPath) {
+    try {
+      const [frontMatter] = loadTicket(ticketPath);
+      current = field === "assignment.owner" ? frontMatter.assignment?.owner : frontMatter[field];
+    } catch {
+      current = null;
+    }
+  }
+
+  if (field === "labels") {
+    const labels = Array.isArray(defaultValue)
+      ? defaultValue
+      : Array.isArray(current)
+      ? current
+      : [];
+    return promptLabels(rl, labels);
+  }
+
+  if (field === "priority") {
+    const base = defaultValue ?? current ?? "medium";
+    while (true) {
+      const response = (await rl.question(`Priority [${base}]: `)).trim().toLowerCase();
+      if (!response) {
+        return base;
+      }
+      if (PRIORITY_VALUES.includes(response)) {
+        return response;
+      }
+      process.stdout.write(`Enter one of ${PRIORITY_VALUES.join(", ")}.\n`);
+    }
+  }
+
+  const fallback = defaultValue ?? current;
+  const response = (await rl.question(`${field} [${fallback ?? ""}]: `)).trim();
+  if (!response && fallback != null) {
+    return fallback;
+  }
+  if (field === "id") {
+    return response || newUuidv7();
+  }
+  return response || fallback;
+}
+
+async function promptLabels(rl, defaultLabels) {
+  const existing = defaultLabels.join(", ");
+  const response = (await rl.question(`Labels (comma-separated) [${existing}]: `)).trim();
+  if (!response) {
+    return defaultLabels;
+  }
+  return response
+    .split(",")
+    .map((v) => v.trim())
+    .filter(Boolean);
+}
+
+async function promptCommands(rl, defaultCommands) {
+  const existing = defaultCommands.join("; ");
+  process.stdout.write("Enter verification commands (comma-separated). Leave blank to keep default.\n");
+  const response = (await rl.question(`Commands [${existing}]: `)).trim();
+  if (!response) {
+    return defaultCommands;
+  }
+  return response
+    .split(",")
+    .map((v) => v.trim())
+    .filter(Boolean);
+}
+
+function setFrontMatterField(ticketPath, field, value) {
+  const [frontMatter, body] = loadTicket(ticketPath);
+  frontMatter[field] = value;
+  writeTicket(ticketPath, frontMatter, body);
+}
+
+function addMissingSections(ticketPath) {
+  const [frontMatter, body] = loadTicket(ticketPath);
+  let nextBody = body;
+  for (const section of ["# Ticket", "## Description", "## Acceptance Criteria", "## Verification"]) {
+    if (!nextBody.includes(section)) {
+      nextBody += `\n${section}\n(fill in)\n`;
+    }
+  }
+  writeTicket(ticketPath, frontMatter, nextBody);
+}
+
+function normalizeCreatedAt(ticketPath) {
+  const [frontMatter, body] = loadTicket(ticketPath);
+  if (typeof frontMatter.created_at !== "string" || !parseIso(frontMatter.created_at)) {
+    frontMatter.created_at = iso8601(nowUtc());
+    writeTicket(ticketPath, frontMatter, body);
+  }
+}
+
+function normalizeLabels(ticketPath) {
+  const [frontMatter, body] = loadTicket(ticketPath);
+  const labels = Array.isArray(frontMatter.labels)
+    ? frontMatter.labels.filter((v) => typeof v === "string")
+    : [];
+  frontMatter.labels = labels;
+  writeTicket(ticketPath, frontMatter, body);
+}
+
+function setAssignmentOwner(ticketPath, value) {
+  const [frontMatter, body] = loadTicket(ticketPath);
+  const assignment =
+    frontMatter.assignment && typeof frontMatter.assignment === "object" && !Array.isArray(frontMatter.assignment)
+      ? frontMatter.assignment
+      : {};
+  assignment.owner = value;
+  frontMatter.assignment = assignment;
+  writeTicket(ticketPath, frontMatter, body);
+}
+
+function resetVerificationCommands(ticketPath, commands) {
+  const [frontMatter, body] = loadTicket(ticketPath);
+  frontMatter.verification = { commands };
+  writeTicket(ticketPath, frontMatter, body);
+}
+
+function normalizeVerificationCommands(ticketPath) {
+  const [frontMatter, body] = loadTicket(ticketPath);
+  const rawCommands = Array.isArray(frontMatter.verification?.commands)
+    ? frontMatter.verification.commands
+    : [];
+  frontMatter.verification = {
+    commands: rawCommands.filter((v) => typeof v === "string"),
+  };
+  writeTicket(ticketPath, frontMatter, body);
+}

package/src/lib/util.js

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import yaml from "yaml";
+import { v7 as uuidv7, validate as uuidValidate, version as uuidVersion } from "uuid";
+
+import { BASE_DIR } from "./constants.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export function repoRoot() {
+  return process.cwd();
+}
+
+export function packageRoot() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "..");
+}
+
+export function ticketsDir() {
+  return path.join(repoRoot(), ".tickets");
+}
+
+export function baseDir() {
+  return path.join(repoRoot(), BASE_DIR);
+}
+
+export function nowUtc() {
+  return new Date();
+}
+
+export function iso8601(date) {
+  return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+export function isoBasic(date) {
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  const hour = String(date.getUTCHours()).padStart(2, "0");
+  const minute = String(date.getUTCMinutes()).padStart(2, "0");
+  const second = String(date.getUTCSeconds()).padStart(2, "0");
+  const ms = String(date.getUTCMilliseconds()).padStart(3, "0");
+  return `${year}${month}${day}T${hour}${minute}${second}.${ms}Z`;
+}
+
+export function parseIso(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const ts = Date.parse(value);
+  return Number.isNaN(ts) ? null : new Date(ts);
+}
+
+export function isUuidv7(value) {
+  if (typeof value !== "string" || !UUID_RE.test(value)) {
+    return false;
+  }
+  return uuidValidate(value) && uuidVersion(value) === 7;
+}
+
+export function newUuidv7() {
+  return uuidv7();
+}
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function readTemplate(relPath) {
+  const filePath = path.join(packageRoot(), relPath);
+  return fs.readFileSync(filePath, "utf8");
+}
+
+export function loadTicket(ticketPath) {
+  const text = fs.readFileSync(ticketPath, "utf8");
+  if (!text.startsWith("---")) {
+    throw new Error("Missing front matter start '---'");
+  }
+  const match = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    throw new Error("Malformed front matter");
+  }
+  const frontMatter = yaml.parse(match[1]) ?? {};
+  if (typeof frontMatter !== "object" || frontMatter === null || Array.isArray(frontMatter)) {
+    throw new Error("Front matter must be a mapping");
+  }
+  const body = match[2].replace(/^\n+/, "");
+  return [frontMatter, body];
+}
+
+export function writeTicket(ticketPath, frontMatter, body) {
+  const yamlText = yaml.stringify(frontMatter).trimEnd();
+  const out = `---\n${yamlText}\n---\n${body.trimEnd()}\n`;
+  fs.writeFileSync(ticketPath, out);
+}
+
+export function readJsonl(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const entries = [];
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    entries.push(JSON.parse(trimmed));
+  }
+  return entries;
+}
+
+export function appendJsonl(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.appendFileSync(filePath, `${JSON.stringify(value)}\n`);
+}
+
+export function listTicketDirs() {
+  const root = ticketsDir();
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(root, entry.name))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+export function matchesRunFilename(name) {
+  return /^[0-9T:.]+Z-[A-Za-z0-9_-]+\.jsonl$/.test(name);
+}
+
+export function resolveTicketPath(ticketRef) {
+  const explicit = path.resolve(repoRoot(), ticketRef);
+  if (fs.existsSync(explicit)) {
+    if (fs.statSync(explicit).isDirectory()) {
+      return path.join(explicit, "ticket.md");
+    }
+    return explicit;
+  }
+  const candidate = path.join(ticketsDir(), ticketRef, "ticket.md");
+  if (fs.existsSync(candidate)) {
+    return candidate;
+  }
+  throw new Error(`Ticket not found: ${ticketRef}`);
+}