specrails-desktop 2.0.0

package/server/dist/terminal-shell-integration.js

@@ -0,0 +1,196 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_SHELL_INTEGRATION = void 0;
+exports.locateBundledShim = locateBundledShim;
+exports.shimDirFor = shimDirFor;
+exports.composeShellIntegrationSpawn = composeShellIntegrationSpawn;
+exports.cleanupSessionShim = cleanupSessionShim;
+exports.cleanupStaleShimDirs = cleanupStaleShimDirs;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+exports.NO_SHELL_INTEGRATION = {
+    args: [],
+    env: {},
+    shimDir: null,
+    shimPath: null,
+};
+const STALE_SHIM_DIR_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Resolve the shell basename for our switch logic. We accept full paths or bare
+ * basenames (e.g. "/bin/zsh", "C:\\Program Files\\PowerShell\\7\\pwsh.exe").
+ */
+function shellBasename(shell) {
+    // Use posix.basename after normalising backslashes so this works on Windows paths.
+    const normalized = shell.replace(/\\/g, '/');
+    return path_1.default.posix.basename(normalized).toLowerCase().replace(/\.exe$/, '');
+}
+/** Source of bundled shims; overridable for tests/packaging. */
+function locateBundledShim(name) {
+    const execDir = path_1.default.dirname(process.execPath);
+    const candidates = [
+        path_1.default.resolve(__dirname, 'shell-integration', name),
+        // Desktop bundle: shims ship under binaries/shell-integration (declared in
+        // tauri.conf.json resources). Windows/Linux install vs macOS .app layout.
+        path_1.default.resolve(execDir, 'binaries', 'shell-integration', name),
+        path_1.default.resolve(execDir, '..', 'Resources', 'binaries', 'shell-integration', name),
+        // Legacy / sibling layouts (kept as existence-gated fallbacks).
+        path_1.default.resolve(execDir, 'shell-integration', name),
+        path_1.default.resolve(execDir, '..', 'shell-integration', name),
+        path_1.default.resolve(process.cwd(), 'server', 'shell-integration', name),
+    ];
+    for (const c of candidates) {
+        try {
+            if (fs_1.default.existsSync(c))
+                return c;
+        }
+        catch { /* ignore */ }
+    }
+    // Observability: a packaging regression that drops the shims would otherwise
+    // silently disable shell integration (no marks/cwd) with no clue why. Warn
+    // once per shim name so it's diagnosable from the server log.
+    warnShimMissingOnce(name);
+    return null;
+}
+const _warnedShims = new Set();
+function warnShimMissingOnce(name) {
+    if (_warnedShims.has(name))
+        return;
+    _warnedShims.add(name);
+    console.warn(`[terminal-shell-integration] bundled shim not found: ${name} — shell integration disabled for this shell`);
+}
+function projectsRoot() {
+    return path_1.default.join(os_1.default.homedir(), '.specrails', 'projects');
+}
+function shimDirFor(projectSlug, sessionId) {
+    return path_1.default.join(projectsRoot(), projectSlug, 'terminals', sessionId);
+}
+function writeFile(target, content) {
+    fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    fs_1.default.writeFileSync(target, content, { mode: 0o600 });
+}
+/**
+ * Compose the env+args needed to spawn the given shell with our shim active.
+ * When integration is disabled or the shell is unsupported, returns
+ * NO_SHELL_INTEGRATION so the caller's spawn proceeds unchanged.
+ */
+function composeShellIntegrationSpawn(shell, sessionId, projectSlug, settings) {
+    if (!settings.shellIntegrationEnabled)
+        return exports.NO_SHELL_INTEGRATION;
+    const base = shellBasename(shell);
+    const shimDir = shimDirFor(projectSlug, sessionId);
+    if (base === 'zsh') {
+        const bundled = locateBundledShim('zsh-shim.zsh');
+        if (!bundled)
+            return exports.NO_SHELL_INTEGRATION;
+        const userZdotdirZshrc = path_1.default.join(shimDir, '.zshrc');
+        const shimContent = `# Specrails auto-generated zsh entry — do not edit\nsource '${bundled.replace(/'/g, `'\\''`)}'\n`;
+        writeFile(userZdotdirZshrc, shimContent);
+        return {
+            args: [],
+            // Pass the user's real ZDOTDIR (default $HOME) so the shim can still source
+            // their ~/.zshenv/.zprofile/.zshrc/.zlogin — the override alone would make
+            // zsh skip the login files and lose PATH/Homebrew/nvm setup.
+            env: { ZDOTDIR: shimDir, SPECRAILS_REAL_ZDOTDIR: process.env.ZDOTDIR ?? '' },
+            shimDir,
+            shimPath: userZdotdirZshrc,
+        };
+    }
+    if (base === 'bash') {
+        const bundled = locateBundledShim('bash-shim.bash');
+        if (!bundled)
+            return exports.NO_SHELL_INTEGRATION;
+        const shimPath = path_1.default.join(shimDir, 'shim.bash');
+        const shimContent = `# Specrails auto-generated bash rcfile — do not edit\nsource '${bundled.replace(/'/g, `'\\''`)}'\n`;
+        writeFile(shimPath, shimContent);
+        return {
+            args: ['--rcfile', shimPath],
+            env: {},
+            shimDir,
+            shimPath,
+        };
+    }
+    if (base === 'fish') {
+        const bundled = locateBundledShim('fish-shim.fish');
+        if (!bundled)
+            return exports.NO_SHELL_INTEGRATION;
+        // Use fish's -C/--init-command, which runs AFTER the user's config.fish and
+        // conf.d, so the user's real fish config is preserved. The previous approach
+        // repointed XDG_CONFIG_HOME at the shim dir, which made fish resolve its
+        // ENTIRE config tree (config.fish, functions, completions) from the shim dir
+        // and silently dropped the user's configuration.
+        return {
+            args: ['-C', `source '${bundled.replace(/'/g, `'\\''`)}'`],
+            env: {},
+            // No per-session dir is written; shimPath (non-null) activates OSC parsing.
+            shimDir: null,
+            shimPath: bundled,
+        };
+    }
+    if (base === 'powershell' || base === 'pwsh') {
+        const bundled = locateBundledShim('powershell-shim.ps1');
+        if (!bundled)
+            return exports.NO_SHELL_INTEGRATION;
+        const shimPath = path_1.default.join(shimDir, 'profile.ps1');
+        const shimContent = `# Specrails auto-generated PowerShell profile — do not edit\n. '${bundled.replace(/'/g, "''")}'\n`;
+        writeFile(shimPath, shimContent);
+        return {
+            args: ['-NoLogo', '-NoExit', '-File', shimPath],
+            env: {},
+            shimDir,
+            shimPath,
+        };
+    }
+    // Unsupported shell — degrade silently.
+    return exports.NO_SHELL_INTEGRATION;
+}
+function cleanupSessionShim(projectSlug, sessionId) {
+    const dir = shimDirFor(projectSlug, sessionId);
+    try {
+        fs_1.default.rmSync(dir, { recursive: true, force: true });
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Sweep stale shim directories on startup. A directory is "stale" when its
+ * mtime is older than 24h. The volatile session registry is empty on cold
+ * start, so we cannot match against live sessions; the age cap prevents us
+ * from removing a directory that just spawned.
+ */
+function cleanupStaleShimDirs(now = Date.now()) {
+    let removed = 0;
+    let projectsDir = [];
+    try {
+        projectsDir = fs_1.default.readdirSync(projectsRoot());
+    }
+    catch {
+        return 0;
+    }
+    for (const slug of projectsDir) {
+        const terminalsRoot = path_1.default.join(projectsRoot(), slug, 'terminals');
+        let entries = [];
+        try {
+            entries = fs_1.default.readdirSync(terminalsRoot);
+        }
+        catch {
+            continue;
+        }
+        for (const sid of entries) {
+            const dir = path_1.default.join(terminalsRoot, sid);
+            try {
+                const stat = fs_1.default.statSync(dir);
+                if (!stat.isDirectory())
+                    continue;
+                if (now - stat.mtimeMs >= STALE_SHIM_DIR_AGE_MS) {
+                    fs_1.default.rmSync(dir, { recursive: true, force: true });
+                    removed++;
+                }
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return removed;
+}

package/server/dist/ticket-broadcast.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.broadcastTicketCreated = broadcastTicketCreated;
+exports.broadcastTicketUpdated = broadcastTicketUpdated;
+exports.broadcastTicketDeleted = broadcastTicketDeleted;
+/**
+ * Broadcast a ticket_created event and suppress the file-watcher echo.
+ * Call this from POST /:projectId/tickets after writing the JSON file.
+ */
+function broadcastTicketCreated(ctx, ticket, newRevision) {
+    ctx.ticketWatcher.notifyDesktopWrite(newRevision);
+    const msg = {
+        type: 'ticket_created',
+        projectId: ctx.project.id,
+        ticket,
+        timestamp: new Date().toISOString(),
+    };
+    ctx.broadcast(msg);
+}
+/**
+ * Broadcast a ticket_updated event and suppress the file-watcher echo.
+ * Call this from PATCH /:projectId/tickets/:id after writing the JSON file.
+ */
+function broadcastTicketUpdated(ctx, ticket, newRevision) {
+    ctx.ticketWatcher.notifyDesktopWrite(newRevision);
+    const msg = {
+        type: 'ticket_updated',
+        projectId: ctx.project.id,
+        ticket,
+        timestamp: new Date().toISOString(),
+    };
+    ctx.broadcast(msg);
+}
+/**
+ * Broadcast a ticket_deleted event and suppress the file-watcher echo.
+ * Call this from DELETE /:projectId/tickets/:id after writing the JSON file.
+ */
+function broadcastTicketDeleted(ctx, ticketId, newRevision) {
+    ctx.ticketWatcher.notifyDesktopWrite(newRevision);
+    const msg = {
+        type: 'ticket_deleted',
+        projectId: ctx.project.id,
+        ticketId,
+        timestamp: new Date().toISOString(),
+    };
+    ctx.broadcast(msg);
+}

package/server/dist/ticket-store.js

@@ -0,0 +1,397 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHORT_SUMMARY_MAX_LEN = exports.CURRENT_SCHEMA_VERSION = void 0;
+exports.clampShortSummary = clampShortSummary;
+exports.resolveTicketStoragePath = resolveTicketStoragePath;
+exports.validateEpicChildIntegrity = validateEpicChildIntegrity;
+exports.readStore = readStore;
+exports.applyJobOutcomeToTickets = applyJobOutcomeToTickets;
+exports.withLock = withLock;
+exports.mutateStore = mutateStore;
+exports.extractTicketIdsFromCommand = extractTicketIdsFromCommand;
+exports.resolveTicketsFromCommand = resolveTicketsFromCommand;
+exports.filterTickets = filterTickets;
+exports.isValidStatus = isValidStatus;
+exports.isValidPriority = isValidPriority;
+exports.validatePriorityForStatus = validatePriorityForStatus;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const VALID_STATUSES = new Set(['draft', 'todo', 'in_progress', 'done', 'cancelled']);
+const VALID_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
+exports.CURRENT_SCHEMA_VERSION = '1.3';
+exports.SHORT_SUMMARY_MAX_LEN = 240;
+/**
+ * Sanitize a `shortSummary` value coming from an AI response or external input.
+ * - Returns `null` for nullish, non-string, or empty-after-trim values.
+ * - Strips control characters, collapses whitespace, trims.
+ * - Hard-caps to `SHORT_SUMMARY_MAX_LEN` characters (server-side safety net).
+ */
+function clampShortSummary(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw !== 'string')
+        return null;
+    // Strip ASCII control chars (except common whitespace) and collapse runs.
+    // eslint-disable-next-line no-control-regex
+    const cleaned = raw.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '').replace(/\s+/g, ' ').trim();
+    if (cleaned.length === 0)
+        return null;
+    if (cleaned.length > exports.SHORT_SUMMARY_MAX_LEN) {
+        return cleaned.slice(0, exports.SHORT_SUMMARY_MAX_LEN);
+    }
+    return cleaned;
+}
+const DEFAULT_STORAGE_PATH = '.specrails/local-tickets.json';
+const LOCK_SUFFIX = '.lock';
+const LOCK_STALE_MS = 10_000; // 10 seconds
+// ─── Path resolution ─────────────────────────────────────────────────────────
+/** True when `candidate` resolves to a path inside (or equal to) `root`. */
+function isContainedIn(root, candidate) {
+    const normalizedRoot = path_1.default.resolve(root);
+    const rel = path_1.default.relative(normalizedRoot, candidate);
+    // Inside the root: relative path is non-empty, does not climb out with '..',
+    // and is not absolute (which path.relative returns when on a different drive).
+    return rel !== '' && !rel.startsWith('..') && !path_1.default.isAbsolute(rel);
+}
+function resolveTicketStoragePath(projectPath) {
+    const fallback = path_1.default.resolve(projectPath, DEFAULT_STORAGE_PATH);
+    // Try to read ticketProvider.storagePath from integration-contract.json
+    const contractPath = path_1.default.join(projectPath, '.claude', 'integration-contract.json');
+    if (fs_1.default.existsSync(contractPath)) {
+        try {
+            const contract = JSON.parse(fs_1.default.readFileSync(contractPath, 'utf-8'));
+            if (contract.ticketProvider?.storagePath) {
+                const resolved = path_1.default.resolve(projectPath, contract.ticketProvider.storagePath);
+                // A2: integration-contract.json is read FROM THE PROJECT REPO and is
+                // therefore untrusted (a hostile repo added as a project). path.resolve
+                // lets an absolute or '../../..'-escaping storagePath redirect the ticket
+                // store to ANY file on disk — and every ticket mutation then overwrites
+                // that file via writeStore(). Reject anything outside the project root
+                // and fall back to the default location.
+                if (isContainedIn(projectPath, resolved)) {
+                    return resolved;
+                }
+                console.warn(`[ticket-store] ignoring out-of-project storagePath from integration-contract.json: ${contract.ticketProvider.storagePath}`);
+            }
+        }
+        catch {
+            // Fall through to default
+        }
+    }
+    return fallback;
+}
+// ─── Advisory file locking ───────────────────────────────────────────────────
+function acquireLock(filePath) {
+    const lockPath = filePath + LOCK_SUFFIX;
+    const maxAttempts = 50;
+    const retryDelay = 50; // ms
+    // Ensure parent directory exists before attempting lock
+    const dir = path_1.default.dirname(lockPath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    for (let i = 0; i < maxAttempts; i++) {
+        try {
+            // O_EXCL ensures atomic create-if-not-exists
+            const fd = fs_1.default.openSync(lockPath, fs_1.default.constants.O_CREAT | fs_1.default.constants.O_EXCL | fs_1.default.constants.O_WRONLY);
+            fs_1.default.writeSync(fd, String(process.pid));
+            fs_1.default.closeSync(fd);
+            return;
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                // Check for stale lock
+                try {
+                    const stat = fs_1.default.statSync(lockPath);
+                    if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+                        fs_1.default.unlinkSync(lockPath);
+                        continue;
+                    }
+                }
+                catch {
+                    // Lock file disappeared, retry
+                    continue;
+                }
+                // Wait and retry
+                const waitUntil = Date.now() + retryDelay;
+                while (Date.now() < waitUntil) { /* busy wait for short duration */ }
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error('Could not acquire lock on ticket store');
+}
+function releaseLock(filePath) {
+    const lockPath = filePath + LOCK_SUFFIX;
+    try {
+        fs_1.default.unlinkSync(lockPath);
+    }
+    catch {
+        // Lock already released or missing
+    }
+}
+// ─── Store operations ────────────────────────────────────────────────────────
+function emptyStore() {
+    return {
+        schema_version: exports.CURRENT_SCHEMA_VERSION,
+        revision: 0,
+        last_updated: new Date().toISOString(),
+        next_id: 1,
+        tickets: {},
+    };
+}
+/**
+ * Normalise a ticket loaded from disk so older stores (schema_version < 1.1)
+ * surface the new fields with sensible defaults. Mutates the input for speed
+ * and returns it.
+ */
+function normalizeTicket(t) {
+    if (!('origin_conversation_id' in t) || t.origin_conversation_id === undefined) {
+        t.origin_conversation_id = null;
+    }
+    if (t.priority === undefined) {
+        // Older stores guaranteed a non-null priority; treat undefined defensively
+        // as null only when status is 'draft', otherwise keep undefined → caller
+        // sees it as TicketPriority|null which it must handle.
+        t.priority = null;
+    }
+    // Schema 1.2 fields (specs-smash).
+    if (!('is_epic' in t) || t.is_epic === undefined) {
+        t.is_epic = false;
+    }
+    if (!('parent_epic_id' in t) || t.parent_epic_id === undefined) {
+        t.parent_epic_id = null;
+    }
+    if (!('execution_order' in t) || t.execution_order === undefined) {
+        t.execution_order = null;
+    }
+    // Schema 1.3 field: AI-generated short summary for postit dashboard view.
+    if (!('short_summary' in t) || t.short_summary === undefined) {
+        t.short_summary = null;
+    }
+    return t;
+}
+/**
+ * Defensive integrity check used after épica/child mutations: every ticket
+ * with parent_epic_id must reference an existing ticket whose is_epic === true.
+ * Returns an array of violation messages (empty when the store is consistent).
+ */
+function validateEpicChildIntegrity(store) {
+    const errors = [];
+    for (const id of Object.keys(store.tickets)) {
+        const t = store.tickets[id];
+        if (t.parent_epic_id === null || t.parent_epic_id === undefined)
+            continue;
+        const parent = store.tickets[String(t.parent_epic_id)];
+        if (!parent) {
+            errors.push(`ticket ${t.id} references missing parent_epic_id=${t.parent_epic_id}`);
+            continue;
+        }
+        if (!parent.is_epic) {
+            errors.push(`ticket ${t.id} parent ${t.parent_epic_id} is not an epic`);
+        }
+    }
+    return errors;
+}
+function readStore(filePath) {
+    if (!fs_1.default.existsSync(filePath)) {
+        return emptyStore();
+    }
+    try {
+        const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Basic validation
+        if (!data.tickets || typeof data.revision !== 'number') {
+            return emptyStore();
+        }
+        // Normalise per-ticket fields added in schema 1.1 without rewriting the
+        // file — version bump only happens on next write via writeStore. Guard each
+        // entry so a single corrupt/non-object value (hand-edit, partial-write
+        // recovery, schema drift) drops only that ticket instead of discarding the
+        // ENTIRE store (which the next mutation would then persist permanently).
+        for (const id of Object.keys(data.tickets)) {
+            const entry = data.tickets[id];
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                delete data.tickets[id];
+                continue;
+            }
+            try {
+                data.tickets[id] = normalizeTicket(entry);
+            }
+            catch {
+                delete data.tickets[id];
+            }
+        }
+        return data;
+    }
+    catch {
+        return emptyStore();
+    }
+}
+function writeStore(filePath, store) {
+    store.last_updated = new Date().toISOString();
+    store.revision++;
+    // Bump schema_version on first write under the new code so consumers can
+    // detect the new shape. Existing 1.0 stores read fine; we only upgrade once
+    // we've actually persisted something (which means normalize ran).
+    store.schema_version = exports.CURRENT_SCHEMA_VERSION;
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    // Atomic write: serialise to a sibling temp file then rename over the target.
+    // A crash mid-write can only leave the (ignored) temp file truncated — the
+    // real store is replaced in one atomic rename, never left half-written. Always
+    // runs under the advisory lock (mutateStore/withLock), so the fixed temp name
+    // cannot collide with a concurrent writer in this process.
+    const tmp = filePath + '.tmp';
+    fs_1.default.writeFileSync(tmp, JSON.stringify(store, null, 2), 'utf-8');
+    fs_1.default.renameSync(tmp, filePath);
+}
+/**
+ * Apply a finished job's outcome to the referenced tickets, in place, and return
+ * the ids that actually changed (so the caller can broadcast just those).
+ *
+ * - `completed`: promote `todo`/`in_progress` → `done` (never resurrect a `draft`
+ *   or a `cancelled` spec into Done); clear any stale `needs_review` flag.
+ * - `failed`/`canceled`/`zombie_terminated`: revert an `in_progress` spec → `todo`
+ *   (back to the Specs column). If the agent had already marked it `done` (its
+ *   Ship phase ran, then the process died), keep it `done` but set `needs_review`
+ *   so the board flags it for review.
+ */
+function applyJobOutcomeToTickets(store, ticketIds, outcome, now) {
+    const changed = [];
+    for (const tid of ticketIds) {
+        const ticket = store.tickets[String(tid)];
+        if (!ticket)
+            continue;
+        if (outcome === 'completed') {
+            const promotable = ticket.status === 'todo' || ticket.status === 'in_progress';
+            const clearWarning = ticket.needs_review === true;
+            if (!promotable && !clearWarning)
+                continue;
+            if (promotable)
+                ticket.status = 'done';
+            if (clearWarning)
+                delete ticket.needs_review;
+            ticket.updated_at = now;
+            changed.push(tid);
+        }
+        else if (ticket.status === 'in_progress') {
+            ticket.status = 'todo';
+            ticket.updated_at = now;
+            changed.push(tid);
+        }
+        else if (ticket.status === 'done' && ticket.needs_review !== true) {
+            ticket.needs_review = true;
+            ticket.updated_at = now;
+            changed.push(tid);
+        }
+    }
+    return changed;
+}
+/** Execute a read-modify-write cycle with advisory locking */
+function withLock(filePath, fn) {
+    acquireLock(filePath);
+    try {
+        return fn(readStore(filePath));
+    }
+    finally {
+        releaseLock(filePath);
+    }
+}
+/** Execute a read-modify-write cycle, writing changes back */
+function mutateStore(filePath, fn) {
+    acquireLock(filePath);
+    try {
+        const store = readStore(filePath);
+        fn(store);
+        writeStore(filePath, store);
+        return store;
+    }
+    finally {
+        releaseLock(filePath);
+    }
+}
+// ─── Query helpers ───────────────────────────────────────────────────────────
+/**
+ * Extract unique ticket ids referenced via `#<digits>` tokens in a command
+ * string, preserving first-occurrence order.
+ */
+function extractTicketIdsFromCommand(command) {
+    const ids = [];
+    const seen = new Set();
+    for (const match of command.matchAll(/#(\d+)/g)) {
+        const id = Number.parseInt(match[1], 10);
+        if (Number.isNaN(id) || seen.has(id))
+            continue;
+        seen.add(id);
+        ids.push(id);
+    }
+    return ids;
+}
+/**
+ * Resolve `#<digits>` ticket references in a command to `{ id, title }` pairs
+ * by reading the project's local ticket store. Tickets that no longer exist
+ * resolve to `title: null`. Returns `[]` when the command has no ticket
+ * references.
+ */
+function resolveTicketsFromCommand(projectPath, command) {
+    const ids = extractTicketIdsFromCommand(command);
+    if (ids.length === 0)
+        return [];
+    const store = readStore(resolveTicketStoragePath(projectPath));
+    return ids.map((id) => ({
+        id,
+        title: store.tickets[String(id)]?.title ?? null,
+    }));
+}
+function filterTickets(tickets, filters) {
+    let result = tickets;
+    if (filters.status) {
+        const statuses = filters.status.split(',').map(s => s.trim());
+        result = result.filter(t => statuses.includes(t.status));
+    }
+    if (filters.label) {
+        const labels = filters.label.split(',').map(l => l.trim().toLowerCase());
+        result = result.filter(t => t.labels.some(tl => labels.includes(tl.toLowerCase())));
+    }
+    if (filters.q) {
+        const query = filters.q.toLowerCase();
+        result = result.filter(t => t.title.toLowerCase().includes(query) ||
+            t.description.toLowerCase().includes(query));
+    }
+    return result;
+}
+// ─── Validation helpers ──────────────────────────────────────────────────────
+function isValidStatus(s) {
+    return typeof s === 'string' && VALID_STATUSES.has(s);
+}
+function isValidPriority(p) {
+    return typeof p === 'string' && VALID_PRIORITIES.has(p);
+}
+/**
+ * Single source of truth for the rule: priority MAY be null only while the
+ * ticket has status='draft'. Returns an error string (suitable for HTTP 400
+ * responses) when the combination is invalid, or `null` when valid.
+ */
+function validatePriorityForStatus(status, priority) {
+    if (status === 'draft') {
+        // null is allowed; non-null must still be a valid priority value.
+        if (priority !== null && !isValidPriority(priority)) {
+            return 'invalid priority value';
+        }
+        return null;
+    }
+    if (priority === null) {
+        return `priority is required when status='${status}'`;
+    }
+    if (!isValidPriority(priority)) {
+        return 'invalid priority value';
+    }
+    return null;
+}