@dleangen/cage-issues 0.0.1 → 0.1.0

package/dist/fs.d.ts

@@ -0,0 +1,20 @@
+import type { Backlog, Config, Issue, Topic } from './schema';
+export declare function readYaml<T>(filePath: string): T;
+export declare function writeYaml(filePath: string, data: unknown): void;
+export declare function configPath(root: string): string;
+export declare function topicPath(root: string, topicId: string): string;
+export declare function backlogPath(root: string, topicId: string): string;
+export declare function issueDir(root: string, topicId: string): string;
+export declare function issuePath(root: string, issueId: string): string;
+export declare function readConfig(root: string): Config;
+export declare function readTopic(root: string, topicId: string): Topic;
+export declare function writeTopic(root: string, topic: Topic): void;
+export declare function readBacklog(root: string, topicId: string): Backlog;
+export declare function writeBacklog(root: string, topicId: string, backlog: Backlog): void;
+export declare function readIssue(root: string, issueId: string): Issue;
+export declare function writeIssue(root: string, issue: Issue): void;
+export declare function topicExists(root: string, topicId: string): boolean;
+export declare function issueExists(root: string, issueId: string): boolean;
+export declare function listTopicIds(root: string): string[];
+export declare function listIssueIds(root: string, topicId: string): string[];
+export declare function nextIssueId(root: string, topicId: string): string;

package/dist/fs.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readYaml = readYaml;
+exports.writeYaml = writeYaml;
+exports.configPath = configPath;
+exports.topicPath = topicPath;
+exports.backlogPath = backlogPath;
+exports.issueDir = issueDir;
+exports.issuePath = issuePath;
+exports.readConfig = readConfig;
+exports.readTopic = readTopic;
+exports.writeTopic = writeTopic;
+exports.readBacklog = readBacklog;
+exports.writeBacklog = writeBacklog;
+exports.readIssue = readIssue;
+exports.writeIssue = writeIssue;
+exports.topicExists = topicExists;
+exports.issueExists = issueExists;
+exports.listTopicIds = listTopicIds;
+exports.listIssueIds = listIssueIds;
+exports.nextIssueId = nextIssueId;
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function readYaml(filePath) {
+    return js_yaml_1.default.load(node_fs_1.default.readFileSync(filePath, 'utf8'));
+}
+function writeYaml(filePath, data) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    node_fs_1.default.writeFileSync(filePath, js_yaml_1.default.dump(data, { lineWidth: 100 }));
+}
+// Path helpers
+function configPath(root) {
+    return node_path_1.default.join(root, 'config.yaml');
+}
+function topicPath(root, topicId) {
+    return node_path_1.default.join(root, 'topics', topicId, 'topic.yaml');
+}
+function backlogPath(root, topicId) {
+    return node_path_1.default.join(root, 'topics', topicId, 'backlog.yaml');
+}
+function issueDir(root, topicId) {
+    return node_path_1.default.join(root, 'topics', topicId, 'issues');
+}
+function issuePath(root, issueId) {
+    const topicId = issueId.split('-')[0];
+    return node_path_1.default.join(issueDir(root, topicId), `${issueId}.yaml`);
+}
+// Read helpers
+function readConfig(root) {
+    const p = configPath(root);
+    if (!node_fs_1.default.existsSync(p)) {
+        return {
+            priority_labels: { p1: 'p1', p2: 'p2', p3: 'p3', p4: 'p4' },
+            impact_labels: { low: 'low', medium: 'medium', high: 'high', critical: 'critical' },
+            tracks: [],
+        };
+    }
+    return readYaml(p);
+}
+function readTopic(root, topicId) {
+    return readYaml(topicPath(root, topicId));
+}
+function writeTopic(root, topic) {
+    writeYaml(topicPath(root, topic.id), topic);
+}
+function readBacklog(root, topicId) {
+    const p = backlogPath(root, topicId);
+    if (!node_fs_1.default.existsSync(p))
+        return { active: [], up_next: [], deferred: [] };
+    return readYaml(p);
+}
+function writeBacklog(root, topicId, backlog) {
+    writeYaml(backlogPath(root, topicId), backlog);
+}
+function readIssue(root, issueId) {
+    return readYaml(issuePath(root, issueId));
+}
+function writeIssue(root, issue) {
+    writeYaml(issuePath(root, issue.id), issue);
+}
+function topicExists(root, topicId) {
+    return node_fs_1.default.existsSync(topicPath(root, topicId));
+}
+function issueExists(root, issueId) {
+    return node_fs_1.default.existsSync(issuePath(root, issueId));
+}
+// List helpers
+function listTopicIds(root) {
+    const topicsDir = node_path_1.default.join(root, 'topics');
+    if (!node_fs_1.default.existsSync(topicsDir))
+        return [];
+    return node_fs_1.default
+        .readdirSync(topicsDir)
+        .filter((d) => node_fs_1.default.existsSync(node_path_1.default.join(topicsDir, d, 'topic.yaml')));
+}
+function listIssueIds(root, topicId) {
+    const dir = issueDir(root, topicId);
+    if (!node_fs_1.default.existsSync(dir))
+        return [];
+    return node_fs_1.default
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.yaml'))
+        .map((f) => f.replace('.yaml', ''));
+}
+// Sequence generation: {TOPIC}-{YEAR}-{SEQUENCE}
+function nextIssueId(root, topicId) {
+    const year = new Date().getFullYear();
+    const ids = listIssueIds(root, topicId).filter((id) => id.includes(`-${year}-`));
+    if (ids.length === 0)
+        return `${topicId}-${year}-0001`;
+    const sequences = ids.map((id) => Number.parseInt(id.split('-').at(-1) ?? '0', 10));
+    const next = Math.max(...sequences) + 1;
+    return `${topicId}-${year}-${String(next).padStart(4, '0')}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Backlog, BacklogEntry, Config, Issue, IssueClassification, IssueImpact, IssueMaturity, IssuePriority, IssueStatus, IssueWithDerived, Signoff, StatusHistoryEntry, Task, TaskPriority, TaskStatus, Topic, TopicStatus, TrackDefinition, } from './schema';
+export { calculateMaturity } from './maturity';
+export { deriveTrack } from './track';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveTrack = exports.calculateMaturity = void 0;
+var maturity_1 = require("./maturity");
+Object.defineProperty(exports, "calculateMaturity", { enumerable: true, get: function () { return maturity_1.calculateMaturity; } });
+var track_1 = require("./track");
+Object.defineProperty(exports, "deriveTrack", { enumerable: true, get: function () { return track_1.deriveTrack; } });

package/dist/maturity.d.ts

@@ -0,0 +1,2 @@
+import type { Issue, IssueMaturity } from './schema';
+export declare function calculateMaturity(issue: Issue): IssueMaturity;

package/dist/maturity.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateMaturity = calculateMaturity;
+function calculateMaturity(issue) {
+    // draft → defined: add priority + what_to_resolve
+    if (!issue.priority || !issue.what_to_resolve)
+        return 'draft';
+    // defined → ready: add at least one task and one affects entry
+    if ((issue.tasks?.length ?? 0) === 0 || (issue.affects?.length ?? 0) === 0)
+        return 'defined';
+    // ready → verified: add at least one signoff
+    if ((issue.signoffs?.length ?? 0) === 0)
+        return 'ready';
+    return 'verified';
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const issues_1 = require("./tools/issues");
+const topics_1 = require("./tools/topics");
+const backlog_1 = require("./tools/backlog");
+const tracks_1 = require("./tools/tracks");
+function parseRoot() {
+    const idx = process.argv.indexOf('--root');
+    if (idx !== -1 && process.argv[idx + 1])
+        return process.argv[idx + 1];
+    return process.cwd();
+}
+async function main() {
+    const root = parseRoot();
+    const server = new mcp_js_1.McpServer({
+        name: 'cage-issues',
+        version: '0.0.1',
+    });
+    (0, issues_1.registerIssueTools)(server, root);
+    (0, topics_1.registerTopicTools)(server, root);
+    (0, tracks_1.registerTrackTools)(server, root);
+    (0, backlog_1.registerBacklogTools)(server, root);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/mcp/tools/backlog.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerBacklogTools(server: McpServer, root: string): void;

package/dist/mcp/tools/backlog.js

@@ -0,0 +1,194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBacklogTools = registerBacklogTools;
+const zod_1 = require("zod");
+const fsHelper = __importStar(require("../../fs"));
+function entryFromIssue(root, issueId) {
+    const issue = fsHelper.readIssue(root, issueId);
+    return { id: issue.id, title: issue.title, rationale: '' };
+}
+function registerBacklogTools(server, root) {
+    // get_backlog
+    server.tool('get_backlog', 'Get the backlog. If topic is omitted, returns an aggregated view across all topics.', {
+        topic: zod_1.z.string().optional().describe('Topic ID — omit for cross-topic aggregate'),
+        track: zod_1.z.string().optional().describe('Filter entries by derived track'),
+    }, async ({ topic, track }) => {
+        const topicIds = topic ? [topic] : fsHelper.listTopicIds(root);
+        if (topicIds.length === 0) {
+            return { content: [{ type: 'text', text: JSON.stringify({ active: [], up_next: [], deferred: [] }, null, 2) }] };
+        }
+        // Aggregate across topics
+        const aggregate = { active: [], up_next: [], deferred: [] };
+        const config = fsHelper.readConfig(root);
+        for (const tid of topicIds) {
+            if (!fsHelper.topicExists(root, tid))
+                continue;
+            const backlog = fsHelper.readBacklog(root, tid);
+            for (const section of ['active', 'up_next', 'deferred']) {
+                for (const entry of backlog[section]) {
+                    if (track) {
+                        // Apply track filter — derive track from the issue
+                        try {
+                            const issue = fsHelper.readIssue(root, entry.id);
+                            const { deriveTrack } = await Promise.resolve().then(() => __importStar(require('../../track')));
+                            const derived = deriveTrack(issue.affects, config);
+                            if (derived !== track)
+                                continue;
+                        }
+                        catch {
+                            // Issue file missing — include anyway
+                        }
+                    }
+                    aggregate[section].push(entry);
+                }
+            }
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(aggregate, null, 2) }] };
+    });
+    // update_backlog
+    server.tool('update_backlog', 'Modify a topic backlog. Operations: promote (up_next→active or deferred→up_next), defer (active→deferred), reorder (move within section), resolve (remove from backlog entirely).', {
+        topic: zod_1.z.string().describe('Topic ID'),
+        operation: zod_1.z.enum(['promote', 'defer', 'reorder', 'resolve']),
+        issue_id: zod_1.z.string().describe('Issue ID to act on'),
+        position: zod_1.z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe('Target position (0-based) for reorder operation'),
+    }, async ({ topic, operation, issue_id, position }) => {
+        const topicId = topic.toUpperCase();
+        if (!fsHelper.topicExists(root, topicId)) {
+            return { content: [{ type: 'text', text: `Error: topic "${topicId}" not found` }] };
+        }
+        const backlog = fsHelper.readBacklog(root, topicId);
+        const sections = ['active', 'up_next', 'deferred'];
+        let currentSection = null;
+        for (const s of sections) {
+            if (backlog[s].some((e) => e.id === issue_id)) {
+                currentSection = s;
+                break;
+            }
+        }
+        switch (operation) {
+            case 'promote': {
+                if (!currentSection) {
+                    return {
+                        content: [{ type: 'text', text: `Error: issue "${issue_id}" not found in backlog` }],
+                    };
+                }
+                const entry = backlog[currentSection].find((e) => e.id === issue_id);
+                backlog[currentSection] = backlog[currentSection].filter((e) => e.id !== issue_id);
+                if (currentSection === 'deferred') {
+                    backlog.up_next.push(entry);
+                }
+                else if (currentSection === 'up_next') {
+                    backlog.active.push(entry);
+                }
+                else {
+                    return { content: [{ type: 'text', text: `Error: issue "${issue_id}" is already in active` }] };
+                }
+                break;
+            }
+            case 'defer': {
+                if (!currentSection) {
+                    return {
+                        content: [{ type: 'text', text: `Error: issue "${issue_id}" not found in backlog` }],
+                    };
+                }
+                if (currentSection === 'deferred') {
+                    return { content: [{ type: 'text', text: `Error: issue "${issue_id}" is already deferred` }] };
+                }
+                const entry = backlog[currentSection].find((e) => e.id === issue_id);
+                backlog[currentSection] = backlog[currentSection].filter((e) => e.id !== issue_id);
+                backlog.deferred.push(entry);
+                break;
+            }
+            case 'reorder': {
+                if (!currentSection) {
+                    return {
+                        content: [{ type: 'text', text: `Error: issue "${issue_id}" not found in backlog` }],
+                    };
+                }
+                if (position === undefined) {
+                    return { content: [{ type: 'text', text: 'Error: position is required for reorder' }] };
+                }
+                const items = backlog[currentSection];
+                const idx = items.findIndex((e) => e.id === issue_id);
+                const [entry] = items.splice(idx, 1);
+                items.splice(Math.min(position, items.length), 0, entry);
+                break;
+            }
+            case 'resolve': {
+                if (!currentSection) {
+                    // Already removed — idempotent
+                    return { content: [{ type: 'text', text: JSON.stringify(backlog, null, 2) }] };
+                }
+                backlog[currentSection] = backlog[currentSection].filter((e) => e.id !== issue_id);
+                break;
+            }
+        }
+        fsHelper.writeBacklog(root, topicId, backlog);
+        // Also add issue to backlog if it's a new entry (create_issue doesn't add it automatically)
+        return { content: [{ type: 'text', text: JSON.stringify(backlog, null, 2) }] };
+    });
+    // add_to_backlog — convenience tool to add an existing issue to a topic's backlog
+    server.tool('add_to_backlog', 'Add an existing issue to its topic backlog in the specified section.', {
+        issue_id: zod_1.z.string().describe('Issue ID'),
+        section: zod_1.z.enum(['active', 'up_next', 'deferred']),
+        rationale: zod_1.z.string().optional().describe('Why this issue is in this section'),
+    }, async ({ issue_id, section, rationale }) => {
+        const topicId = issue_id.split('-')[0];
+        if (!fsHelper.topicExists(root, topicId)) {
+            return { content: [{ type: 'text', text: `Error: topic "${topicId}" not found` }] };
+        }
+        if (!fsHelper.issueExists(root, issue_id)) {
+            return { content: [{ type: 'text', text: `Error: issue "${issue_id}" not found` }] };
+        }
+        const backlog = fsHelper.readBacklog(root, topicId);
+        // Check not already present
+        const all = [...backlog.active, ...backlog.up_next, ...backlog.deferred];
+        if (all.some((e) => e.id === issue_id)) {
+            return { content: [{ type: 'text', text: `Error: issue "${issue_id}" is already in the backlog` }] };
+        }
+        const entry = entryFromIssue(root, issue_id);
+        if (rationale)
+            entry.rationale = rationale;
+        backlog[section].push(entry);
+        fsHelper.writeBacklog(root, topicId, backlog);
+        return { content: [{ type: 'text', text: JSON.stringify(backlog, null, 2) }] };
+    });
+}

package/dist/mcp/tools/issues.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerIssueTools(server: McpServer, root: string): void;