@howaboua/opencode-roadmap-plugin 0.1.0

package/dist/src/tools/readroadmap.js

@@ -0,0 +1,90 @@
+import { tool } from "@opencode-ai/plugin";
+import { FileStorage, RoadmapValidator } from "../storage.js";
+import { loadDescription } from "../descriptions/index.js";
+import { getErrorMessage } from "../errors/loader.js";
+export async function createReadRoadmapTool(directory) {
+    const description = await loadDescription("readroadmap.txt");
+    return tool({
+        description,
+        args: {
+            actionNumber: tool.schema
+                .string()
+                .optional()
+                .describe('Specific action to read ("1.01", "1.02", etc.). If not provided, reads entire roadmap.'),
+            featureNumber: tool.schema
+                .string()
+                .optional()
+                .describe('Specific feature to read ("1", "2", etc.). Use only if not providing actionNumber.'),
+        },
+        async execute(args) {
+            const storage = new FileStorage(directory);
+            if (!(await storage.exists())) {
+                throw new Error(await getErrorMessage("roadmap_not_found"));
+            }
+            const roadmap = await storage.read();
+            if (!roadmap) {
+                throw new Error(await getErrorMessage("roadmap_corrupted"));
+            }
+            if (args.actionNumber && args.featureNumber) {
+                throw new Error("Cannot specify both actionNumber and featureNumber. Use one or the other, or neither for full roadmap.");
+            }
+            if (args.actionNumber) {
+                const actionNumberError = await RoadmapValidator.validateActionNumber(args.actionNumber);
+                if (actionNumberError) {
+                    throw new Error(`${actionNumberError.message} Use ReadRoadmap to see valid action numbers.`);
+                }
+                for (const feature of roadmap.features) {
+                    const action = feature.actions.find((a) => a.number === args.actionNumber);
+                    if (action) {
+                        return (`Action ${args.actionNumber} from Feature "${feature.title}":\n` +
+                            `Description: ${action.description}\n` +
+                            `Status: ${action.status}\n` +
+                            `Feature: ${feature.number} - ${feature.title}\n` +
+                            `Feature Description: ${feature.description}`);
+                    }
+                }
+                throw new Error(`Action "${args.actionNumber}" not found. Use ReadRoadmap with no arguments to see all available actions.`);
+            }
+            if (args.featureNumber) {
+                const featureNumberError = await RoadmapValidator.validateFeatureNumber(args.featureNumber);
+                if (featureNumberError) {
+                    throw new Error(`${featureNumberError.message} Use ReadRoadmap to see valid feature numbers.`);
+                }
+                const feature = roadmap.features.find((f) => f.number === args.featureNumber);
+                if (!feature) {
+                    throw new Error(`Feature "${args.featureNumber}" not found. Use ReadRoadmap with no arguments to see all available features.`);
+                }
+                const actionList = feature.actions
+                    .map((action) => `  ${action.number}: ${action.description} [${action.status}]`)
+                    .join("\n");
+                const completedCount = feature.actions.filter((a) => a.status === "completed").length;
+                const totalCount = feature.actions.length;
+                return (`Feature ${feature.number}: ${feature.title}\n` +
+                    `Description: ${feature.description}\n` +
+                    `Progress: ${completedCount}/${totalCount} actions completed\n` +
+                    `Actions:\n${actionList}`);
+            }
+            const totalActions = roadmap.features.reduce((sum, feature) => sum + feature.actions.length, 0);
+            const completedActions = roadmap.features.reduce((sum, feature) => sum + feature.actions.filter((a) => a.status === "completed").length, 0);
+            const inProgressActions = roadmap.features.reduce((sum, feature) => sum + feature.actions.filter((a) => a.status === "in_progress").length, 0);
+            const pendingActions = totalActions - completedActions - inProgressActions;
+            let output = `Project Roadmap Overview\n` +
+                `========================\n` +
+                `Features: ${roadmap.features.length}\n` +
+                `Total Actions: ${totalActions}\n` +
+                `Progress: ${completedActions} completed, ${inProgressActions} in progress, ${pendingActions} pending\n\n`;
+            for (const feature of roadmap.features) {
+                const featureCompleted = feature.actions.filter((a) => a.status === "completed").length;
+                const featureTotal = feature.actions.length;
+                output += `Feature ${feature.number}: ${feature.title} (${featureCompleted}/${featureTotal} complete)\n`;
+                output += `  Description: ${feature.description}\n`;
+                for (const action of feature.actions) {
+                    const statusIcon = action.status === "completed" ? "✓" : action.status === "in_progress" ? "→" : "○";
+                    output += `  ${action.number} ${statusIcon} ${action.description} [${action.status}]\n`;
+                }
+                output += "\n";
+            }
+            return output.trim();
+        },
+    });
+}

package/dist/src/tools/updateroadmap.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export declare function createUpdateRoadmapTool(directory: string): Promise<ToolDefinition>;

package/dist/src/tools/updateroadmap.js

@@ -0,0 +1,107 @@
+import { tool } from "@opencode-ai/plugin";
+import { FileStorage, RoadmapValidator } from "../storage.js";
+import { loadDescription } from "../descriptions/index.js";
+import { getErrorMessage } from "../errors/loader.js";
+export async function createUpdateRoadmapTool(directory) {
+    const description = await loadDescription("updateroadmap.txt");
+    return tool({
+        description,
+        args: {
+            actionNumber: tool.schema.string().describe('Action number to update ("1.01", "1.02", "2.01", etc.) - required'),
+            description: tool.schema
+                .string()
+                .optional()
+                .describe("New action description (full overwrite). If not provided, only status is updated."),
+            status: tool.schema
+                .enum(["pending", "in_progress", "completed"])
+                .optional()
+                .describe("New action status - optional if only updating description"),
+        },
+        async execute(args) {
+            const storage = new FileStorage(directory);
+            if (!(await storage.exists())) {
+                throw new Error(await getErrorMessage("roadmap_not_found"));
+            }
+            const roadmap = await storage.read();
+            if (!roadmap) {
+                throw new Error(await getErrorMessage("roadmap_corrupted"));
+            }
+            const actionNumberError = await RoadmapValidator.validateActionNumber(args.actionNumber);
+            if (actionNumberError) {
+                throw new Error(`${actionNumberError.message} Use ReadRoadmap to see valid action numbers.`);
+            }
+            let targetAction = null;
+            let targetFeature = null;
+            let actionFound = false;
+            for (const feature of roadmap.features) {
+                const action = feature.actions.find((a) => a.number === args.actionNumber);
+                if (action) {
+                    targetAction = action;
+                    targetFeature = feature;
+                    actionFound = true;
+                    break;
+                }
+            }
+            if (!actionFound) {
+                throw new Error(await getErrorMessage("action_not_found", { id: args.actionNumber }));
+            }
+            // Validate that at least one field is being updated
+            if (args.description === undefined && args.status === undefined) {
+                throw new Error(await getErrorMessage("no_changes_specified"));
+            }
+            const oldStatus = targetAction.status;
+            const oldDescription = targetAction.description;
+            // Validate description if provided
+            if (args.description !== undefined) {
+                const descError = await RoadmapValidator.validateDescription(args.description, "action");
+                if (descError) {
+                    throw new Error(`${descError.message}`);
+                }
+                targetAction.description = args.description;
+            }
+            // Validate and update status if provided
+            if (args.status !== undefined) {
+                const statusTransitionError = await RoadmapValidator.validateStatusProgression(targetAction.status, args.status);
+                if (statusTransitionError) {
+                    throw new Error(`${statusTransitionError.message} Current status: "${targetAction.status}", requested: "${args.status}"`);
+                }
+                targetAction.status = args.status;
+            }
+            await storage.write(roadmap);
+            const changes = [];
+            if (args.description !== undefined && oldDescription !== args.description) {
+                changes.push(`description updated`);
+            }
+            if (args.status !== undefined && oldStatus !== args.status) {
+                changes.push(`status: "${oldStatus}" → "${args.status}"`);
+            }
+            // Check if all actions are completed
+            let allCompleted = true;
+            for (const feature of roadmap.features) {
+                for (const action of feature.actions) {
+                    if (action.status !== "completed") {
+                        allCompleted = false;
+                        break;
+                    }
+                }
+                if (!allCompleted)
+                    break;
+            }
+            let archiveMsg = "";
+            if (allCompleted) {
+                const archiveName = await storage.archive();
+                archiveMsg = `\n\n🎉 All actions completed! Roadmap archived to "${archiveName}".`;
+            }
+            // Format feature context
+            const featureCompleted = targetFeature.actions.filter((a) => a.status === "completed").length;
+            const featureTotal = targetFeature.actions.length;
+            let featureContext = `\n\nFeature ${targetFeature.number}: ${targetFeature.title} (${featureCompleted}/${featureTotal} complete)\n`;
+            featureContext += `Description: ${targetFeature.description}\n`;
+            for (const action of targetFeature.actions) {
+                const statusIcon = action.status === "completed" ? "✓" : action.status === "in_progress" ? "→" : "○";
+                featureContext += `${action.number} ${statusIcon} ${action.description} [${action.status}]\n`;
+            }
+            return `Updated action ${args.actionNumber} in feature "${targetFeature.title}": ${changes.join(", ")}${featureContext}${archiveMsg}`;
+        },
+    });
+}

package/dist/src/types.d.ts

@@ -0,0 +1,151 @@
+import { z } from "zod";
+export declare const ActionStatus: z.ZodEnum<["pending", "in_progress", "completed"]>;
+export type ActionStatus = z.infer<typeof ActionStatus>;
+export declare const Action: z.ZodObject<{
+    number: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+}, "strip", z.ZodTypeAny, {
+    number: string;
+    status: "pending" | "in_progress" | "completed";
+    description: string;
+}, {
+    number: string;
+    status: "pending" | "in_progress" | "completed";
+    description: string;
+}>;
+export type Action = z.infer<typeof Action>;
+export declare const Feature: z.ZodObject<{
+    number: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    actions: z.ZodArray<z.ZodObject<{
+        number: z.ZodString;
+        description: z.ZodString;
+        status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+    }, "strip", z.ZodTypeAny, {
+        number: string;
+        status: "pending" | "in_progress" | "completed";
+        description: string;
+    }, {
+        number: string;
+        status: "pending" | "in_progress" | "completed";
+        description: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    number: string;
+    description: string;
+    title: string;
+    actions: {
+        number: string;
+        status: "pending" | "in_progress" | "completed";
+        description: string;
+    }[];
+}, {
+    number: string;
+    description: string;
+    title: string;
+    actions: {
+        number: string;
+        status: "pending" | "in_progress" | "completed";
+        description: string;
+    }[];
+}>;
+export type Feature = z.infer<typeof Feature>;
+export declare const Roadmap: z.ZodObject<{
+    features: z.ZodArray<z.ZodObject<{
+        number: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        actions: z.ZodArray<z.ZodObject<{
+            number: z.ZodString;
+            description: z.ZodString;
+            status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+        }, "strip", z.ZodTypeAny, {
+            number: string;
+            status: "pending" | "in_progress" | "completed";
+            description: string;
+        }, {
+            number: string;
+            status: "pending" | "in_progress" | "completed";
+            description: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        number: string;
+        description: string;
+        title: string;
+        actions: {
+            number: string;
+            status: "pending" | "in_progress" | "completed";
+            description: string;
+        }[];
+    }, {
+        number: string;
+        description: string;
+        title: string;
+        actions: {
+            number: string;
+            status: "pending" | "in_progress" | "completed";
+            description: string;
+        }[];
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    features: {
+        number: string;
+        description: string;
+        title: string;
+        actions: {
+            number: string;
+            status: "pending" | "in_progress" | "completed";
+            description: string;
+        }[];
+    }[];
+}, {
+    features: {
+        number: string;
+        description: string;
+        title: string;
+        actions: {
+            number: string;
+            status: "pending" | "in_progress" | "completed";
+            description: string;
+        }[];
+    }[];
+}>;
+export type Roadmap = z.infer<typeof Roadmap>;
+export interface RoadmapStorage {
+    read(): Promise<Roadmap | null>;
+    write(roadmap: Roadmap): Promise<void>;
+    exists(): Promise<boolean>;
+    archive(): Promise<string>;
+}
+export interface ValidationError {
+    code: string;
+    message: string;
+    tutorial?: string;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+}
+export interface CreateRoadmapInput {
+    features: Array<{
+        number: string;
+        title: string;
+        description: string;
+        actions: Array<{
+            number: string;
+            description: string;
+            status: "pending";
+        }>;
+    }>;
+}
+export interface UpdateRoadmapInput {
+    actionNumber: string;
+    description?: string;
+    status: ActionStatus;
+}
+export interface ReadRoadmapInput {
+    actionNumber?: string;
+    featureNumber?: string;
+}

package/dist/src/types.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export const ActionStatus = z.enum(["pending", "in_progress", "completed"]);
+export const Action = z.object({
+    number: z
+        .string()
+        .describe('Action number as string with two decimals ("1.01", "1.02", etc.) - canonical ID, never changes'),
+    description: z.string().describe("Action description - MUTABLE (overwrite only)"),
+    status: ActionStatus.describe("Current status of this action - MUTABLE"),
+});
+export const Feature = z.object({
+    number: z.string().describe('Feature number as string ("1", "2", "3...") - canonical ID, never changes'),
+    title: z.string().describe("Feature title"),
+    description: z.string().describe("Brief description of what this feature accomplishes"),
+    actions: z.array(Action).describe("Array of actions for this feature"),
+});
+export const Roadmap = z.object({
+    features: z.array(Feature).describe("Array of features in the roadmap"),
+});

package/dist/storage.d.ts

@@ -0,0 +1,25 @@
+import type { Roadmap, RoadmapStorage, ValidationError } from "./types";
+export declare class FileStorage implements RoadmapStorage {
+    private directory;
+    constructor(directory: string);
+    exists(): Promise<boolean>;
+    read(): Promise<Roadmap | null>;
+    write(roadmap: Roadmap): Promise<void>;
+    archive(): Promise<string>;
+}
+export declare class RoadmapValidator {
+    static validateFeatureNumber(number: string): Promise<ValidationError | null>;
+    static validateActionNumber(number: string): Promise<ValidationError | null>;
+    static validateActionSequence(actions: Array<{
+        number: string;
+    }>, globalSeenNumbers?: Set<string>, featureNumber?: string): Promise<ValidationError[]>;
+    static validateFeatureSequence(features: Array<{
+        number: string;
+        actions: Array<{
+            number: string;
+        }>;
+    }>): Promise<ValidationError[]>;
+    static validateTitle(title: string, fieldType: "feature" | "action"): Promise<ValidationError | null>;
+    static validateDescription(description: string, fieldType: "feature" | "action"): Promise<ValidationError | null>;
+    static validateStatusProgression(currentStatus: string, newStatus: string): Promise<ValidationError | null>;
+}

package/dist/storage.js

@@ -0,0 +1,214 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+import { getErrorMessage } from "./errors/loader.js";
+const ROADMAP_FILE = "roadmap.json";
+export class FileStorage {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async exists() {
+        try {
+            await fs.access(join(this.directory, ROADMAP_FILE));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async read() {
+        try {
+            const filePath = join(this.directory, ROADMAP_FILE);
+            const data = await fs.readFile(filePath, "utf-8");
+            if (!data.trim()) {
+                return null;
+            }
+            const parsed = JSON.parse(data);
+            if (!parsed || typeof parsed !== "object") {
+                throw new Error("Invalid roadmap format: not an object");
+            }
+            if (!Array.isArray(parsed.features)) {
+                throw new Error("Invalid roadmap format: missing or invalid features array");
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error("Roadmap file contains invalid JSON. File may be corrupted.");
+            }
+            if (error instanceof Error && error.message.includes("ENOENT")) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async write(roadmap) {
+        const filePath = join(this.directory, ROADMAP_FILE);
+        const tempPath = join(this.directory, `${ROADMAP_FILE}.tmp.${Date.now()}`);
+        try {
+            const data = JSON.stringify(roadmap, null, 2);
+            await fs.writeFile(tempPath, data, "utf-8");
+            await fs.rename(tempPath, filePath);
+        }
+        catch (error) {
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+    async archive() {
+        const filePath = join(this.directory, ROADMAP_FILE);
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const archiveFilename = `roadmap.archive.${timestamp}.json`;
+        const archivePath = join(this.directory, archiveFilename);
+        await fs.rename(filePath, archivePath);
+        return archiveFilename;
+    }
+}
+export class RoadmapValidator {
+    static async validateFeatureNumber(number) {
+        if (!number || typeof number !== "string") {
+            return {
+                code: "INVALID_FEATURE_NUMBER",
+                message: await getErrorMessage("invalid_feature_id", { id: "undefined" }),
+            };
+        }
+        if (!/^\d+$/.test(number)) {
+            return {
+                code: "INVALID_FEATURE_NUMBER_FORMAT",
+                message: await getErrorMessage("invalid_feature_id", { id: number }),
+            };
+        }
+        return null;
+    }
+    static async validateActionNumber(number) {
+        if (!number || typeof number !== "string") {
+            return {
+                code: "INVALID_ACTION_NUMBER",
+                message: await getErrorMessage("invalid_action_id", { id: "undefined" }),
+            };
+        }
+        if (!/^\d+\.\d{2}$/.test(number)) {
+            return {
+                code: "INVALID_ACTION_NUMBER_FORMAT",
+                message: await getErrorMessage("invalid_action_id", { id: number }),
+            };
+        }
+        return null;
+    }
+    static async validateActionSequence(actions, globalSeenNumbers, featureNumber) {
+        const errors = [];
+        const seenNumbers = new Set();
+        for (let i = 0; i < actions.length; i++) {
+            const action = actions[i];
+            const numberError = await this.validateActionNumber(action.number);
+            if (numberError) {
+                errors.push(numberError);
+                continue;
+            }
+            // Check action-feature mismatch
+            if (featureNumber) {
+                const actionFeaturePrefix = action.number.split('.')[0];
+                if (actionFeaturePrefix !== featureNumber) {
+                    errors.push({
+                        code: "ACTION_FEATURE_MISMATCH",
+                        message: await getErrorMessage("action_mismatch", { action: action.number, feature: featureNumber }),
+                    });
+                }
+            }
+            // Check for duplicates within this feature
+            if (seenNumbers.has(action.number)) {
+                errors.push({
+                    code: "DUPLICATE_ACTION_NUMBER",
+                    message: `Duplicate action ID "${action.number}".`,
+                });
+            }
+            // Check for global duplicates
+            if (globalSeenNumbers?.has(action.number)) {
+                errors.push({
+                    code: "DUPLICATE_ACTION_NUMBER_GLOBAL",
+                    message: `Duplicate action ID "${action.number}" (exists in another feature).`,
+                });
+            }
+            seenNumbers.add(action.number);
+            globalSeenNumbers?.add(action.number);
+        }
+        return errors;
+    }
+    static async validateFeatureSequence(features) {
+        const errors = [];
+        const seenNumbers = new Set();
+        const seenActionNumbers = new Set();
+        for (let i = 0; i < features.length; i++) {
+            const feature = features[i];
+            const numberError = await this.validateFeatureNumber(feature.number);
+            if (numberError) {
+                errors.push(numberError);
+                continue;
+            }
+            if (seenNumbers.has(feature.number)) {
+                errors.push({
+                    code: "DUPLICATE_FEATURE_NUMBER",
+                    message: `Duplicate feature ID "${feature.number}".`,
+                });
+            }
+            seenNumbers.add(feature.number);
+            const actionErrors = await this.validateActionSequence(feature.actions, seenActionNumbers, feature.number);
+            errors.push(...actionErrors);
+        }
+        return errors;
+    }
+    static async validateTitle(title, fieldType) {
+        if (!title || typeof title !== "string") {
+            return {
+                code: "INVALID_TITLE",
+                message: `Invalid ${fieldType} title. Must be non-empty string.`,
+            };
+        }
+        if (title.trim() === "") {
+            return {
+                code: "EMPTY_TITLE",
+                message: `${fieldType.charAt(0).toUpperCase() + fieldType.slice(1)} title cannot be empty.`,
+            };
+        }
+        return null;
+    }
+    static async validateDescription(description, fieldType) {
+        if (!description || typeof description !== "string") {
+            return {
+                code: "INVALID_DESCRIPTION",
+                message: `Invalid ${fieldType} description. Must be non-empty string.`,
+            };
+        }
+        if (description.trim() === "") {
+            return {
+                code: "EMPTY_DESCRIPTION",
+                message: `${fieldType.charAt(0).toUpperCase() + fieldType.slice(1)} description cannot be empty.`,
+            };
+        }
+        return null;
+    }
+    static async validateStatusProgression(currentStatus, newStatus) {
+        const statusFlow = {
+            pending: ["in_progress", "completed"],
+            in_progress: ["completed"],
+            completed: [],
+        };
+        const allowedTransitions = statusFlow[currentStatus] || [];
+        if (!allowedTransitions.includes(newStatus)) {
+            return {
+                code: "INVALID_STATUS_TRANSITION",
+                message: await getErrorMessage("invalid_transition", {
+                    from: currentStatus,
+                    to: newStatus,
+                    allowed: allowedTransitions.length > 0 ? allowedTransitions.join(", ") : "None (terminal state)"
+                }),
+            };
+        }
+        return null;
+    }
+}

package/dist/tools/createroadmap.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export declare function createCreateRoadmapTool(directory: string): Promise<ToolDefinition>;