@howaboua/opencode-roadmap-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 howaboua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @howaboua/opencode-roadmap-plugin
+
+Strategic roadmap planning and multi-agent coordination for OpenCode.
+
+## Installation
+
+Add to your repository `opencode.json` or user-level `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["@howaboua/opencode-roadmap-plugin"]
+}
+```
+
+## How It Works
+
+- `createroadmap`: create or append features/actions while keeping IDs immutable.
+- `updateroadmap`: advance action status forward only (`pending` → `in_progress` → `completed`), optional description update.
+- `readroadmap`: summarize roadmap, optionally filtered by feature/action.
+- Storage: JSON on disk with auto-archive when all actions complete.
+- Validation: Zod schemas enforce shape; errors surface readable templates.
+
+## Development
+
+```bash
+npm run build   # Emit dist/ (ESM + d.ts)
+```
+
+See `AGENTS.md` for coding standards.

package/dist/descriptions/index.d.ts

@@ -0,0 +1 @@
+export { loadDescription } from "./loader";

package/dist/descriptions/index.js

@@ -0,0 +1 @@
+export { loadDescription } from "./loader.js";

package/dist/descriptions/loader.d.ts

@@ -0,0 +1 @@
+export declare function loadDescription(filename: string): Promise<string>;

package/dist/descriptions/loader.js

@@ -0,0 +1,17 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+export async function loadDescription(filename) {
+    // In the compiled output, __dirname is .../dist/descriptions, but the assets are in .../src/descriptions.
+    // This path adjustment ensures the assets are found regardless of the build process.
+    const descriptionsDir = join(__dirname, "..", "..", "src", "descriptions");
+    const filePath = join(descriptionsDir, filename);
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Description file not found: ${filename}. Looked in: ${filePath}. Please ensure asset files are correctly located.`);
+        }
+        throw error;
+    }
+}

package/dist/errors/loader.d.ts

@@ -0,0 +1,2 @@
+export declare function loadErrorTemplate(filename: string): Promise<string>;
+export declare function getErrorMessage(filename: string, params?: Record<string, string>): Promise<string>;

package/dist/errors/loader.js

@@ -0,0 +1,24 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+const ERROR_CACHE = {};
+export async function loadErrorTemplate(filename) {
+    if (ERROR_CACHE[filename])
+        return ERROR_CACHE[filename];
+    const errorsDir = join(__dirname, "..", "..", "src", "errors");
+    const filePath = join(errorsDir, filename + ".txt");
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        ERROR_CACHE[filename] = content.trim();
+        return ERROR_CACHE[filename];
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Error template not found: ${filename} at ${filePath}`);
+        }
+        throw error;
+    }
+}
+export async function getErrorMessage(filename, params = {}) {
+    const template = await loadErrorTemplate(filename);
+    return template.replace(/\{(\w+)\}/g, (_, key) => params[key] || `{${key}}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const RoadmapPlugin: Plugin;
+export default RoadmapPlugin;

package/dist/index.js

@@ -0,0 +1,3 @@
+import { RoadmapPlugin as impl } from "./src/index.js";
+export const RoadmapPlugin = impl;
+export default RoadmapPlugin;

package/dist/src/descriptions/index.d.ts

@@ -0,0 +1 @@
+export { loadDescription } from "./loader.js";

package/dist/src/descriptions/index.js

@@ -0,0 +1 @@
+export { loadDescription } from "./loader.js";

package/dist/src/descriptions/loader.d.ts

@@ -0,0 +1 @@
+export declare function loadDescription(filename: string): Promise<string>;

package/dist/src/descriptions/loader.js

@@ -0,0 +1,17 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+export async function loadDescription(filename) {
+    // In the compiled output, __dirname is .../dist/descriptions, but the assets are in .../src/descriptions.
+    // This path adjustment ensures the assets are found regardless of the build process.
+    const descriptionsDir = join(__dirname, "..", "..", "src", "descriptions");
+    const filePath = join(descriptionsDir, filename);
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Description file not found: ${filename}. Looked in: ${filePath}. Please ensure asset files are correctly located.`);
+        }
+        throw error;
+    }
+}

package/dist/src/errors/loader.d.ts

@@ -0,0 +1,2 @@
+export declare function loadErrorTemplate(filename: string): Promise<string>;
+export declare function getErrorMessage(filename: string, params?: Record<string, string>): Promise<string>;

package/dist/src/errors/loader.js

@@ -0,0 +1,24 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+const ERROR_CACHE = {};
+export async function loadErrorTemplate(filename) {
+    if (ERROR_CACHE[filename])
+        return ERROR_CACHE[filename];
+    const errorsDir = join(__dirname, "..", "..", "src", "errors");
+    const filePath = join(errorsDir, filename + ".txt");
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        ERROR_CACHE[filename] = content.trim();
+        return ERROR_CACHE[filename];
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Error template not found: ${filename} at ${filePath}`);
+        }
+        throw error;
+    }
+}
+export async function getErrorMessage(filename, params = {}) {
+    const template = await loadErrorTemplate(filename);
+    return template.replace(/\{(\w+)\}/g, (_, key) => params[key] || `{${key}}`);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const RoadmapPlugin: Plugin;
+export default RoadmapPlugin;

package/dist/src/index.js

@@ -0,0 +1,13 @@
+import { createCreateRoadmapTool } from "./tools/createroadmap.js";
+import { createUpdateRoadmapTool } from "./tools/updateroadmap.js";
+import { createReadRoadmapTool } from "./tools/readroadmap.js";
+export const RoadmapPlugin = async ({ project, directory, worktree, $ }) => {
+    return {
+        tool: {
+            createroadmap: await createCreateRoadmapTool(directory),
+            updateroadmap: await createUpdateRoadmapTool(directory),
+            readroadmap: await createReadRoadmapTool(directory),
+        },
+    };
+};
+export default RoadmapPlugin;

package/dist/src/storage.d.ts

@@ -0,0 +1,25 @@
+import type { Roadmap, RoadmapStorage, ValidationError } from "./types.js";
+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/src/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/src/tools/createroadmap.d.ts

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

package/dist/src/tools/createroadmap.js

@@ -0,0 +1,135 @@
+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 createCreateRoadmapTool(directory) {
+    const description = await loadDescription("createroadmap.txt");
+    return tool({
+        description,
+        args: {
+            features: tool.schema
+                .array(tool.schema.object({
+                number: tool.schema.string().describe('Feature number as string ("1", "2", "3...")'),
+                title: tool.schema.string().describe("Feature title"),
+                description: tool.schema.string().describe("Brief description of what this feature accomplishes"),
+                actions: tool.schema
+                    .array(tool.schema.object({
+                    number: tool.schema
+                        .string()
+                        .describe('Action number as string with two decimals ("1.01", "1.02", etc.)'),
+                    description: tool.schema.string().describe("Action description"),
+                    status: tool.schema.enum(["pending"]).describe('Initial action status (must be "pending")'),
+                }))
+                    .describe("List of actions for this feature in order"),
+            }))
+                .describe("Array of features for roadmap"),
+        },
+        async execute(args) {
+            const storage = new FileStorage(directory);
+            let roadmap;
+            let isUpdate = false;
+            if (await storage.exists()) {
+                const existing = await storage.read();
+                if (!existing) {
+                    throw new Error("Existing roadmap file is corrupted. Please fix manually.");
+                }
+                roadmap = existing;
+                isUpdate = true;
+            }
+            else {
+                roadmap = { features: [] };
+            }
+            if (!args.features || args.features.length === 0) {
+                throw new Error('Roadmap must have at least one feature with at least one action. Example: {"features": [{"number": "1", "title": "Feature 1", "description": "Description", "actions": [{"number": "1.01", "description": "Action 1", "status": "pending"}]}]}');
+            }
+            const validationErrors = [];
+            // First pass: structural validation of input
+            for (const feature of args.features) {
+                if (!feature.actions || feature.actions.length === 0) {
+                    throw new Error(`Feature "${feature.number}" must have at least one action. Each feature needs at least one action to be valid.`);
+                }
+                const titleError = await RoadmapValidator.validateTitle(feature.title, "feature");
+                if (titleError)
+                    validationErrors.push(titleError);
+                const descError = await RoadmapValidator.validateDescription(feature.description, "feature");
+                if (descError)
+                    validationErrors.push(descError);
+                for (const action of feature.actions) {
+                    const actionTitleError = await RoadmapValidator.validateTitle(action.description, "action");
+                    if (actionTitleError)
+                        validationErrors.push(actionTitleError);
+                }
+            }
+            // Validate sequence consistency of input (internal consistency)
+            const sequenceErrors = await RoadmapValidator.validateFeatureSequence(args.features);
+            validationErrors.push(...sequenceErrors);
+            if (validationErrors.length > 0) {
+                const errorMessages = validationErrors.map((err) => err.message).join("\n");
+                throw new Error(`Validation errors:\n${errorMessages}\n\nPlease fix these issues and try again.`);
+            }
+            // Merge Logic
+            for (const inputFeature of args.features) {
+                const existingFeature = roadmap.features.find((f) => f.number === inputFeature.number);
+                if (existingFeature) {
+                    // Feature exists: Validate Immutability
+                    if (existingFeature.title !== inputFeature.title || existingFeature.description !== inputFeature.description) {
+                        const msg = await getErrorMessage("immutable_feature", {
+                            id: inputFeature.number,
+                            oldTitle: existingFeature.title,
+                            oldDesc: existingFeature.description,
+                            newTitle: inputFeature.title,
+                            newDesc: inputFeature.description
+                        });
+                        throw new Error(msg);
+                    }
+                    // Process Actions
+                    for (const inputAction of inputFeature.actions) {
+                        const existingAction = existingFeature.actions.find((a) => a.number === inputAction.number);
+                        if (existingAction) {
+                            // Action exists: skip (immutable)
+                            continue;
+                        }
+                        else {
+                            // New Action: Append
+                            existingFeature.actions.push({
+                                number: inputAction.number,
+                                description: inputAction.description,
+                                status: inputAction.status,
+                            });
+                            // Sort actions to ensure order
+                            existingFeature.actions.sort((a, b) => parseFloat(a.number) - parseFloat(b.number));
+                        }
+                    }
+                }
+                else {
+                    // New Feature: Append
+                    roadmap.features.push({
+                        number: inputFeature.number,
+                        title: inputFeature.title,
+                        description: inputFeature.description,
+                        actions: inputFeature.actions.map((a) => ({
+                            number: a.number,
+                            description: a.description,
+                            status: a.status,
+                        })),
+                    });
+                }
+            }
+            // Final Sort of Features
+            roadmap.features.sort((a, b) => parseInt(a.number) - parseInt(b.number));
+            // Final Validation of the Merged Roadmap
+            const finalErrors = await RoadmapValidator.validateFeatureSequence(roadmap.features);
+            if (finalErrors.length > 0) {
+                throw new Error(`Resulting roadmap would be invalid:\n${finalErrors.map(e => e.message).join("\n")}`);
+            }
+            await storage.write(roadmap);
+            const totalActions = roadmap.features.reduce((sum, feature) => sum + feature.actions.length, 0);
+            const action = isUpdate ? "Updated" : "Created";
+            const summary = `${action} roadmap with ${roadmap.features.length} features and ${totalActions} actions:\n` +
+                roadmap.features
+                    .map((feature) => `  Feature ${feature.number}: ${feature.title} (${feature.actions.length} actions)`)
+                    .join("\n");
+            return summary;
+        },
+    });
+}

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

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