@wrongstack/plugins 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ECOSTACK TECHNOLOGY OÜ
+
+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/dist/auto-doc.d.ts

@@ -0,0 +1,13 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * auto-doc plugin — Auto-generates JSDoc/TSDoc comments for source files.
+ *
+ * Tools registered:
+ * - auto_doc: Generate and inject doc comments into JS/TS files
+ * - auto_doc_preview: Preview doc comments without writing them
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };

package/dist/auto-doc.js

@@ -0,0 +1,239 @@
+// src/auto-doc/index.ts
+var AUTO_DOC_API_VERSION = "^0.1.10";
+function parseSource(content) {
+  const entities = [];
+  const lines = content.split("\n");
+  const reFunction = /^(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\((.*?)\)(?:\s*:\s*(.+?))?\s*\{/;
+  const reArrowFn = /^(?:export\s+)?const\s+(\w+)\s*=\s*(?:async\s+)?\((.*?)\)\s*(?::\s*(.+?))?\s*=>/;
+  const reClass = /^(?:export\s+)?class\s+(\w+)/;
+  const reType = /^(?:export\s+)?type\s+(\w+)\s*=\s*\{/;
+  const reInterface = /^(?:export\s+)?interface\s+(\w+)/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    let m = line.match(reFunction);
+    if (m) {
+      entities.push({
+        kind: "function",
+        name: m[1],
+        startLine: i + 1,
+        params: m[2] ? m[2].split(",").map((p) => p.trim().split(":")[0].trim()) : [],
+        returnType: m[3]?.trim()
+      });
+      continue;
+    }
+    m = line.match(reArrowFn);
+    if (m) {
+      entities.push({
+        kind: "function",
+        name: m[1],
+        startLine: i + 1,
+        params: m[2] ? m[2].split(",").map((p) => p.trim().split(":")[0].trim()) : [],
+        returnType: m[3]?.trim()
+      });
+      continue;
+    }
+    m = line.match(reClass);
+    if (m) {
+      entities.push({ kind: "class", name: m[1], startLine: i + 1 });
+      continue;
+    }
+    m = line.match(reType);
+    if (m) {
+      entities.push({ kind: "type", name: m[1], startLine: i + 1 });
+      continue;
+    }
+    m = line.match(reInterface);
+    if (m) {
+      entities.push({ kind: "interface", name: m[1], startLine: i + 1 });
+      continue;
+    }
+  }
+  return entities;
+}
+function generateJSDoc(entity, includeTypes) {
+  switch (entity.kind) {
+    case "function": {
+      const params = entity.params.map((p) => `   * @param ${p} - TODO: describe parameter`).join("\n");
+      const returns = entity.returnType ? `
+   * @returns ${includeTypes ? `{${entity.returnType}} ` : ""}TODO: describe return value` : "";
+      return `/**
+   * TODO: One-line description of ${entity.name}
+${params}${returns}
+   */`;
+    }
+    case "class":
+      return `/**
+   * TODO: Describe class ${entity.name}
+   */`;
+    case "type":
+      return `/**
+   * TODO: Describe type ${entity.name}
+   */`;
+    case "interface":
+      return `/**
+   * TODO: Describe interface ${entity.name}
+   */`;
+  }
+}
+function generateTSDoc(entity, includeTypes) {
+  switch (entity.kind) {
+    case "function": {
+      const params = entity.params.map((p) => `   * @param ${p} - TODO: describe parameter`).join("\n");
+      const returns = entity.returnType ? `
+   * @returns ${includeTypes ? `{${entity.returnType}} ` : ""}TODO: describe return value` : "";
+      return `/**
+   * TODO: One-line description of ${entity.name}
+${params}${returns}
+   */`;
+    }
+    case "class":
+      return `/**
+   * TODO: Describe class ${entity.name}
+   */`;
+    case "type":
+      return `/**
+   * TODO: Describe type ${entity.name}
+   */`;
+    case "interface":
+      return `/**
+   * TODO: Describe interface ${entity.name}
+   */`;
+  }
+}
+function needsDocComment(content, entity) {
+  const lines = content.split("\n");
+  const lineIdx = entity.startLine - 1;
+  if (lineIdx < 1) return true;
+  const prevLine = lines[lineIdx - 1] ?? "";
+  return !/^\s*\/\*\*\s*$/.test(prevLine.trim());
+}
+function injectDocComment(content, entity, doc) {
+  const lines = content.split("\n");
+  const idx = entity.startLine - 1;
+  const codeLine = lines[idx] ?? "";
+  const indent = codeLine.match(/^(\s*)/)?.[1] ?? "";
+  lines.splice(idx, 0, `${indent}${doc} ${codeLine.trim()}`);
+  return lines.join("\n");
+}
+async function runAutoDoc(input, api) {
+  if (!input.files || typeof input.files !== "object" || !Array.isArray(input.files)) {
+    return { ok: false, error: "input.files must be an array of file paths", filesProcessed: 0, changes: [] };
+  }
+  if (input.files.length === 0) {
+    return { ok: false, error: "input.files is empty \u2014 provide at least one file path", filesProcessed: 0, changes: [] };
+  }
+  const style = input.style ?? "tsdoc";
+  const includeTypes = api.config.extensions?.["auto-doc"]?.["includeTypes"] ?? false;
+  const results = [];
+  for (const file of input.files) {
+    try {
+      const { readFileSync, writeFileSync } = await import('fs');
+      let content;
+      try {
+        content = readFileSync(file, "utf-8");
+      } catch {
+        api.log.warn(`auto-doc: could not read file ${file}`);
+        continue;
+      }
+      const entities = parseSource(content);
+      let modified = content;
+      for (const entity of entities) {
+        if (!input.force && !needsDocComment(modified, entity)) continue;
+        const doc = style === "jsdoc" ? generateJSDoc(entity, includeTypes) : generateTSDoc(entity, includeTypes);
+        modified = injectDocComment(modified, entity, doc);
+        results.push({ file, entity: entity.name });
+      }
+      if (!input.dryRun && results.length > 0) {
+        writeFileSync(file, modified, "utf-8");
+        api.log.info(`auto-doc: updated ${file}`);
+      }
+    } catch (err) {
+      api.log.error(`auto-doc: error processing ${file}: ${err}`);
+    }
+  }
+  return { ok: true, filesProcessed: input.files.length, changes: results };
+}
+async function runAutoDocPreview(input, api) {
+  if (!input.files || typeof input.files !== "object" || !Array.isArray(input.files)) {
+    return { ok: false, error: "input.files must be an array of file paths", previews: [] };
+  }
+  if (input.files.length === 0) {
+    return { ok: false, error: "input.files is empty \u2014 provide at least one file path", previews: [] };
+  }
+  const style = input.style ?? "tsdoc";
+  const includeTypes = api.config.extensions?.["auto-doc"]?.["includeTypes"] ?? false;
+  const previews = [];
+  for (const file of input.files) {
+    try {
+      const { readFileSync } = await import('fs');
+      const content = readFileSync(file, "utf-8");
+      const entities = parseSource(content);
+      const generated = entities.filter((e) => !needsDocComment(content, e)).map((e) => style === "jsdoc" ? generateJSDoc(e, includeTypes) : generateTSDoc(e, includeTypes));
+      previews.push({ file, entities: generated });
+    } catch {
+      api.log.warn(`auto-doc-preview: could not read file ${file}`);
+    }
+  }
+  return { ok: true, previews };
+}
+var plugin = {
+  name: "auto-doc",
+  version: "0.1.0",
+  description: "Auto-generates JSDoc/TSDoc comments for functions, classes, types, and interfaces",
+  apiVersion: AUTO_DOC_API_VERSION,
+  capabilities: { tools: true, pipelines: ["toolCall"] },
+  defaultConfig: { style: "tsdoc", includeTypes: false, dryRun: false },
+  configSchema: {
+    type: "object",
+    properties: {
+      style: { type: "string", enum: ["jsdoc", "tsdoc"], default: "tsdoc" },
+      includeTypes: { type: "boolean", default: false },
+      dryRun: { type: "boolean", default: false }
+    }
+  },
+  setup(api) {
+    api.tools.register({
+      name: "auto_doc",
+      description: "Auto-generate JSDoc/TSDoc comments for functions, classes, types, and interfaces in source files",
+      inputSchema: {
+        type: "object",
+        properties: {
+          files: { type: "array", items: { type: "string" }, description: "Source files to document" },
+          style: { type: "string", enum: ["jsdoc", "tsdoc"], default: "tsdoc", description: "Comment style" },
+          force: { type: "boolean", default: false, description: "Overwrite existing docstrings" },
+          dryRun: { type: "boolean", default: false, description: "Preview without writing" }
+        },
+        required: ["files"]
+      },
+      permission: "auto",
+      mutating: true,
+      async execute(input) {
+        return runAutoDoc(input, api);
+      }
+    });
+    api.tools.register({
+      name: "auto_doc_preview",
+      description: "Preview what JSDoc/TSDoc comments would be generated for files, without writing",
+      inputSchema: {
+        type: "object",
+        properties: {
+          files: { type: "array", items: { type: "string" }, description: "Source files to preview" },
+          style: { type: "string", enum: ["jsdoc", "tsdoc"], default: "tsdoc" }
+        },
+        required: ["files"]
+      },
+      permission: "auto",
+      mutating: false,
+      async execute(input) {
+        return runAutoDocPreview(input, api);
+      }
+    });
+    api.log.info("auto-doc plugin loaded", { version: "0.1.0", capabilities: ["auto_doc", "auto_doc_preview"] });
+  },
+  teardown(api) {
+    api.log.info("auto-doc plugin unloaded");
+  }
+};
+var auto_doc_default = plugin;
+
+export { auto_doc_default as default };

package/dist/cost-tracker.d.ts

@@ -0,0 +1,14 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * cost-tracker plugin — Tracks LLM token usage and cost per session.
+ *
+ * Tools registered:
+ * - cost_summary: Show token usage breakdown by model
+ * - cost_reset: Reset tracking counters
+ * - cost_export: Export cost report as JSON or CSV
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };

package/dist/cost-tracker.js

@@ -0,0 +1,209 @@
+// src/cost-tracker/index.ts
+var API_VERSION = "^0.1.10";
+var PRICING = {
+  "gpt-4o": { input: 5, output: 15 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10, output: 30 },
+  "claude-3-5-sonnet": { input: 3, output: 15 },
+  "claude-3-5-haiku": { input: 0.8, output: 4 },
+  "claude-3-opus": { input: 15, output: 75 },
+  "gemini-1.5-pro": { input: 3.5, output: 10.5 },
+  "gemini-1.5-flash": { input: 0.075, output: 0.3 },
+  "default": { input: 5, output: 15 }
+};
+var DEFAULT_PRICING = { input: 5, output: 15 };
+function estimateCost(model, promptTokens, completionTokens) {
+  const pricing = PRICING[model.toLowerCase()] ?? DEFAULT_PRICING;
+  const inputCost = promptTokens / 1e6 * pricing.input;
+  const outputCost = completionTokens / 1e6 * pricing.output;
+  return inputCost + outputCost;
+}
+var plugin = {
+  name: "cost-tracker",
+  version: "0.1.0",
+  description: "Tracks LLM token usage and estimated cost per session with per-model breakdown",
+  apiVersion: API_VERSION,
+  capabilities: { tools: true, pipelines: ["request", "response"] },
+  defaultConfig: {
+    trackPerModel: true,
+    trackPerUser: false,
+    budgetLimit: 0,
+    warningThreshold: 80
+  },
+  configSchema: {
+    type: "object",
+    properties: {
+      trackPerModel: { type: "boolean", default: true },
+      trackPerUser: { type: "boolean", default: false },
+      budgetLimit: { type: "number", default: 0, description: "Budget limit in USD (0 = no limit)" },
+      warningThreshold: { type: "number", default: 80, description: "Warning threshold as percentage of budget" }
+    }
+  },
+  setup(api) {
+    const sessionCost = {
+      requests: [],
+      totalPromptTokens: 0,
+      totalCompletionTokens: 0,
+      totalTokens: 0,
+      totalCostUsd: 0,
+      byModel: {}
+    };
+    api.onEvent("provider.response", (payload) => {
+      const usage = payload.usage;
+      const model = payload.ctx?.model ?? "unknown";
+      const promptTokens = usage.input ?? 0;
+      const completionTokens = usage.output ?? 0;
+      const totalTokens = promptTokens + completionTokens;
+      const costUsd = estimateCost(model, promptTokens, completionTokens);
+      const record = {
+        promptTokens,
+        completionTokens,
+        totalTokens,
+        model,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        costUsd
+      };
+      sessionCost.requests.push(record);
+      sessionCost.totalPromptTokens += promptTokens;
+      sessionCost.totalCompletionTokens += completionTokens;
+      sessionCost.totalTokens += totalTokens;
+      sessionCost.totalCostUsd += costUsd;
+      const slot = sessionCost.byModel[model] ??= { tokens: 0, costUsd: 0, requests: 0 };
+      slot.tokens += totalTokens;
+      slot.costUsd += costUsd;
+      slot.requests += 1;
+      api.metrics.counter("tokens_total", totalTokens, { model });
+      api.metrics.histogram("cost_usd", costUsd, { model });
+    });
+    api.tools.register({
+      name: "cost_summary",
+      description: "Returns the current session's token usage breakdown by model, total cost estimate, and budget status.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      mutating: false,
+      async execute() {
+        const budgetLimit = api.config.extensions?.["cost-tracker"]?.["budgetLimit"] ?? 0;
+        const warningThreshold = api.config.extensions?.["cost-tracker"]?.["warningThreshold"] ?? 80;
+        const usage = {
+          totalRequests: sessionCost.requests.length,
+          totalPromptTokens: sessionCost.totalPromptTokens,
+          totalCompletionTokens: sessionCost.totalCompletionTokens,
+          totalTokens: sessionCost.totalTokens,
+          totalCostUsd: Math.round(sessionCost.totalCostUsd * 1e6) / 1e6,
+          byModel: sessionCost.byModel,
+          recentRequests: sessionCost.requests.slice(-5).map((r) => ({
+            model: r.model,
+            tokens: r.totalTokens,
+            costUsd: r.costUsd,
+            ts: r.timestamp
+          }))
+        };
+        const budgetStatus = budgetLimit > 0 ? {
+          limit: budgetLimit,
+          spent: sessionCost.totalCostUsd,
+          percentUsed: Math.round(sessionCost.totalCostUsd / budgetLimit * 100),
+          warning: sessionCost.totalCostUsd / budgetLimit * 100 >= warningThreshold
+        } : null;
+        return {
+          ok: true,
+          usage,
+          budgetStatus
+        };
+      }
+    });
+    api.tools.register({
+      name: "cost_reset",
+      description: "Resets all token usage and cost counters for the current session.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      mutating: false,
+      async execute() {
+        const prev = {
+          totalTokens: sessionCost.totalTokens,
+          totalCostUsd: sessionCost.totalCostUsd
+        };
+        sessionCost.requests = [];
+        sessionCost.totalPromptTokens = 0;
+        sessionCost.totalCompletionTokens = 0;
+        sessionCost.totalTokens = 0;
+        sessionCost.totalCostUsd = 0;
+        sessionCost.byModel = {};
+        return {
+          ok: true,
+          previousTotals: prev,
+          message: "Cost tracking counters have been reset."
+        };
+      }
+    });
+    api.tools.register({
+      name: "cost_export",
+      description: "Export the cost report as JSON or CSV.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          format: { type: "string", enum: ["json", "csv"], default: "json" },
+          includeModel: { type: "boolean", default: true }
+        }
+      },
+      permission: "auto",
+      mutating: false,
+      async execute(input) {
+        const format = input["format"] ?? "json";
+        const includeModel = input["includeModel"] ?? true;
+        if (format === "csv") {
+          const header = includeModel ? "model,timestamp,prompt_tokens,completion_tokens,total_tokens,cost_usd" : "timestamp,prompt_tokens,completion_tokens,total_tokens,cost_usd";
+          const rows = sessionCost.requests.map(
+            (r) => includeModel ? `${r.model},${r.timestamp},${r.promptTokens},${r.completionTokens},${r.totalTokens},${r.costUsd ?? 0}` : `${r.timestamp},${r.promptTokens},${r.completionTokens},${r.totalTokens},${r.costUsd ?? 0}`
+          );
+          return {
+            ok: true,
+            format: "csv",
+            data: [header, ...rows].join("\n"),
+            summary: {
+              totalTokens: sessionCost.totalTokens,
+              totalCostUsd: sessionCost.totalCostUsd,
+              totalRequests: sessionCost.requests.length
+            }
+          };
+        }
+        return {
+          ok: true,
+          format: "json",
+          data: {
+            summary: {
+              totalTokens: sessionCost.totalTokens,
+              totalPromptTokens: sessionCost.totalPromptTokens,
+              totalCompletionTokens: sessionCost.totalCompletionTokens,
+              totalCostUsd: sessionCost.totalCostUsd,
+              totalRequests: sessionCost.requests.length,
+              byModel: sessionCost.byModel
+            },
+            requests: includeModel ? sessionCost.requests : sessionCost.requests.map(({ promptTokens, completionTokens, totalTokens, costUsd, timestamp }) => ({
+              promptTokens,
+              completionTokens,
+              totalTokens,
+              costUsd,
+              timestamp
+            }))
+          }
+        };
+      }
+    });
+    api.onEvent("session.close", async () => {
+      if (sessionCost.requests.length > 0) {
+        await api.session.append({
+          type: "cost-tracker:session_summary",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          totalTokens: sessionCost.totalTokens,
+          totalCostUsd: sessionCost.totalCostUsd,
+          totalRequests: sessionCost.requests.length,
+          byModel: sessionCost.byModel
+        });
+      }
+    });
+    api.log.info("cost-tracker plugin loaded", { version: "0.1.0" });
+  }
+};
+var cost_tracker_default = plugin;
+
+export { cost_tracker_default as default };

package/dist/cron.d.ts

@@ -0,0 +1,14 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * cron plugin — Schedules recurring tasks via beforeIteration extension hooks.
+ *
+ * Tools registered:
+ * - cron_schedule: Schedule a recurring action
+ * - cron_list: List all scheduled jobs
+ * - cron_cancel: Cancel a scheduled job
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };