@cloudy-app/opencode-plugin 0.0.1

package/README.md

@@ -0,0 +1,129 @@
+# @cloudy-app/opencode-plugin
+
+OpenCode plugin for Cloudy — idea management tools with automatic session tracking and file protection.
+
+## Features
+
+- **Idea CRUD tools** — `idea_list`, `idea_create`, `idea_update`, `idea_remove` exposed as OpenCode tools
+- **File protection** — prevents destructive commands on the idea directory
+- **Auto touch** — automatically syncs idea metadata when idea files are written/edited
+
+## Installation
+
+```bash
+# bun (recommended)
+bun add @cloudy-app/opencode-plugin
+
+# npm
+npm install @cloudy-app/opencode-plugin
+```
+
+## Usage
+
+Add the plugin to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@cloudy-app/opencode-plugin"]
+}
+```
+
+### Environment Variables
+
+| Variable                     | Default                 | Description                     |
+| ---------------------------- | ----------------------- | ------------------------------- |
+| `CLOUDY_ASSISTANT_BASE_PATH` | `./base-path`           | Base directory for idea storage |
+| `CLOUDY_API_BASE_PATH`       | `http://localhost:3000` | Cloudy API server URL           |
+
+### Tools
+
+| Tool          | Description                                                       |
+| ------------- | ----------------------------------------------------------------- |
+| `idea_list`   | List ideas with optional filters (status, priority, tags, search) |
+| `idea_create` | Create a new idea with title and metadata                         |
+| `idea_update` | Update idea metadata (title, tags, status, priority)              |
+| `idea_remove` | Delete an idea by path                                            |
+
+### Guards
+
+The plugin automatically blocks:
+
+- Destructive bash commands targeting the idea directory (`rm`, `mv`, `cp`, etc.)
+- Overwriting `index.md` inside idea directories
+
+## Development
+
+```bash
+bun install
+
+# Build
+bun run build
+
+# Test
+bun test
+
+# Lint
+bun run lint:write
+```
+
+## Testing Locally Before Publish
+
+### Option 1: `bun link` (recommended)
+
+```bash
+# Setup — build + create global link
+bun run build
+bun link
+
+# Use in another project
+bun link @cloudy-app/opencode-plugin
+
+# Cleanup when done
+bun unlink @cloudy-app/opencode-plugin
+```
+
+### Option 2: Direct tarball
+
+```bash
+bun run build
+npm pack --dry-run
+```
+
+## Publishing
+
+### Prerequisites
+
+- npm account with publish permission to `@cloudy` org
+- Logged in via `npm login`
+- All changes committed and pushed
+
+### Steps
+
+```bash
+# 1. Build and test
+bun run build
+bun test
+
+# 2. Verify the tarball contents
+npm pack --dry-run
+
+# 3. Bump version
+npm version patch   # 1.0.0 → 1.0.1
+npm version minor   # 1.0.0 → 1.1.0
+npm version major   # 1.0.0 → 2.0.0
+
+# 4. Publish
+npm publish
+```
+
+### CI/CD (Optional)
+
+```yaml
+- run: bun install
+- run: bun run build
+- run: bun test
+- run: npm publish
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { Plugin, ToolDefinition } from '@opencode-ai/plugin';
+
+declare const IdeaPlugin: Plugin;
+
+declare const list: ToolDefinition;
+declare const create: ToolDefinition;
+declare const update: ToolDefinition;
+declare const remove: ToolDefinition;
+
+export { IdeaPlugin, create, list, remove, update };

package/dist/index.js

@@ -0,0 +1,188 @@
+// src/tools/idea.ts
+import { tool } from "@opencode-ai/plugin";
+
+// src/lib/env.ts
+var env = {
+  get CLOUDY_ASSISTANT_BASE_PATH() {
+    return process.env.CLOUDY_ASSISTANT_BASE_PATH || "./base-path";
+  },
+  get CLOUDY_API_BASE_PATH() {
+    return process.env.CLOUDY_ASSISTANT_BASE_PATH || "http://localhost:3000";
+  }
+};
+
+// src/lib/api.ts
+async function ideaApi(path2, options) {
+  const res = await fetch(`${env.CLOUDY_API_BASE_PATH}/api/idea${path2}`, {
+    headers: { "Content-Type": "application/json" },
+    ...options
+  });
+  if (!res.ok) {
+    throw new Error(`API error ${res.status}: ${await res.text()}`);
+  }
+  return res.json();
+}
+async function listIdeas(query) {
+  return ideaApi(query ? `?${query}` : "");
+}
+async function createIdea(body) {
+  return ideaApi("", { method: "POST", body: JSON.stringify(body) });
+}
+async function updateIdeaMeta(ideaPath, body) {
+  return ideaApi(`/${encodeURIComponent(ideaPath)}`, {
+    method: "PATCH",
+    body: JSON.stringify(body)
+  });
+}
+async function deleteIdea(ideaPath) {
+  return ideaApi(`/${encodeURIComponent(ideaPath)}`, { method: "DELETE" });
+}
+async function touchIdea(ideaPath) {
+  return ideaApi(`/${encodeURIComponent(ideaPath)}/touch`, { method: "PATCH" });
+}
+
+// src/tools/idea.ts
+var list = tool({
+  description: "List all ideas with optional filters. Returns idea path, title, status, priority, tags, and content.",
+  args: {
+    q: tool.schema.string().optional().describe("Search query to filter ideas by title/content"),
+    status: tool.schema.enum(["draft", "in-progress", "completed", "archived"]).optional().describe("Filter by status"),
+    priority: tool.schema.enum(["low", "medium", "high"]).optional().describe("Filter by priority"),
+    tags: tool.schema.array(tool.schema.string()).optional().describe("Filter by tags")
+  },
+  async execute(args) {
+    const params = new URLSearchParams();
+    if (args.q) params.set("q", args.q);
+    if (args.status) params.set("status", args.status);
+    if (args.priority) params.set("priority", args.priority);
+    if (args.tags?.length) args.tags.forEach((t) => params.append("tags", t));
+    const ideas = await listIdeas(params.toString());
+    return JSON.stringify(ideas, null, 2);
+  }
+});
+var create = tool({
+  description: "Create a new idea with title and optional metadata. Returns the created idea detail.",
+  args: {
+    title: tool.schema.string().describe("Title of the idea"),
+    content: tool.schema.string().optional().describe("Initial content for the idea (markdown)"),
+    tags: tool.schema.array(tool.schema.string()).optional().describe("Tags for categorization"),
+    status: tool.schema.enum(["draft", "in-progress", "completed", "archived"]).optional().describe("Status (default: draft)"),
+    priority: tool.schema.enum(["low", "medium", "high"]).optional().describe("Priority (default: medium)")
+  },
+  async execute(args) {
+    const result = await createIdea(args);
+    return `Idea created successfully:
+${JSON.stringify(result, null, 2)}`;
+  }
+});
+var update = tool({
+  description: "Update idea metadata (title, tags, status, priority). Use the idea 'path' value as identifier.",
+  args: {
+    path: tool.schema.string().describe("The idea path (identifier, e.g. '1743123456_my-idea')"),
+    title: tool.schema.string().optional().describe("New title"),
+    tags: tool.schema.array(tool.schema.string()).optional().describe("Replace tags"),
+    status: tool.schema.enum(["draft", "in-progress", "completed", "archived"]).optional().describe("New status"),
+    priority: tool.schema.enum(["low", "medium", "high"]).optional().describe("New priority")
+  },
+  async execute(args) {
+    const { path: ideaPath, ...body } = args;
+    const result = await updateIdeaMeta(ideaPath, body);
+    return `Idea updated successfully:
+${JSON.stringify(result, null, 2)}`;
+  }
+});
+var remove = tool({
+  description: "Delete an idea by its path. This removes the idea and all its files permanently.",
+  args: {
+    path: tool.schema.string().describe("The idea path to delete (e.g. '1743123456_my-idea')")
+  },
+  async execute(args) {
+    await deleteIdea(args.path);
+    return `Idea '${args.path}' deleted successfully.`;
+  }
+});
+
+// src/plugins/idea-plugins.ts
+import path from "path";
+function getIdeaDir() {
+  return path.resolve(env.CLOUDY_ASSISTANT_BASE_PATH, "idea");
+}
+var DESTRUCTIVE_COMMANDS = ["rm", "mv", "cp", "rmdir", "chmod", "chown", "ln"];
+function isDestructiveBashOnIdea(command, ideaDir) {
+  const tokens = command.trim().split(/\s+/);
+  const cmd = tokens[0];
+  if (!DESTRUCTIVE_COMMANDS.includes(cmd ?? "")) return false;
+  const normalizedIdeaDir = path.resolve(ideaDir);
+  return tokens.slice(1).some((t) => {
+    const resolved = path.resolve(t);
+    return resolved.startsWith(normalizedIdeaDir + path.sep) || resolved === normalizedIdeaDir;
+  });
+}
+function isFileIdeaFile(filePath, ideaDir = getIdeaDir()) {
+  const normalizedIdeaPath = path.resolve(ideaDir);
+  const normalizedFile = path.resolve(filePath);
+  return normalizedFile.startsWith(normalizedIdeaPath + path.sep);
+}
+function isIdeaIndexMd(filePath, ideaDir = getIdeaDir()) {
+  if (!isFileIdeaFile(filePath, ideaDir)) return false;
+  return path.basename(filePath) === "index.md";
+}
+function extractIdeaPath(filePath, ideaDir = getIdeaDir()) {
+  const normalizedIdeaPath = path.resolve(ideaDir);
+  const normalizedFile = path.resolve(filePath);
+  const relative = normalizedFile.slice(normalizedIdeaPath.length + 1);
+  return relative.split(path.sep)[0] ?? "";
+}
+
+// src/plugins/index.ts
+var IdeaPlugin = async ({
+  project,
+  client,
+  $,
+  directory,
+  worktree
+}) => {
+  return {
+    tool: {
+      idea_list: list,
+      idea_create: create,
+      idea_update: update,
+      idea_remove: remove
+    },
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "bash") {
+        const command = output.args.command ?? "";
+        if (isDestructiveBashOnIdea(command, getIdeaDir())) {
+          throw new Error(`Cannot run destructive command on idea directory`);
+        }
+      }
+      if (input.tool === "write") {
+        const filePath = output.args.filePath;
+        if (isIdeaIndexMd(filePath)) {
+          throw new Error("Cannot overwrite index.md in idea directory");
+        }
+        if (isFileIdeaFile(filePath)) {
+          const ideaPath = extractIdeaPath(filePath);
+          await touchIdea(ideaPath);
+        }
+      }
+      if (input.tool === "edit") {
+        const filePath = output.args.filePath;
+        if (isIdeaIndexMd(filePath)) {
+          throw new Error("Cannot modify index.md in idea directory");
+        }
+        if (isFileIdeaFile(filePath)) {
+          const ideaPath = extractIdeaPath(filePath);
+          await touchIdea(ideaPath);
+        }
+      }
+    }
+  };
+};
+export {
+  IdeaPlugin,
+  create,
+  list,
+  remove,
+  update
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cloudy-app/opencode-plugin",
+  "version": "0.0.1",
+  "description": "OpenCode plugin for Cloudy — idea management tools and session tracking",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "bun run build",
+    "test": "bun test"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "cloudy",
+    "idea",
+    "ai",
+    "llm"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=0.15.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.2.23",
+    "@types/bun": "^1.3.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
+  }
+}