opencode-cron-job 0.1.0

package/.cron-job/tasks.md

@@ -0,0 +1,5 @@
+# 周期任务
+
+## 喝水提醒
+- cron: 0 */2 * * *
+- prompt: 提醒用户喝水，保持健康

package/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: npm
+      - run: npm ci
+      - run: npm run build

package/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM }}
+
+  release:
+    needs: publish-npm
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Extract release notes from CHANGELOG.md
+        id: changelog
+        uses: release-flow/keep-a-changelog-action@v3
+        with:
+          command: query
+          version: ${{ github.ref_name }}
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.release-notes }}
+          draft: false

package/.opencode/opencode.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://opencode.ai/config.json"
+}

package/AGENTS.md

@@ -0,0 +1,50 @@
+# opencode-cron-job
+
+## Build
+
+```bash
+npm run build        # tsc → dist/index.js
+npm publish          # builds + publishes to npm
+```
+
+After build, copy to plugins dir for local testing:
+```bash
+cp dist/index.js .opencode/plugins/
+```
+
+## Architecture
+
+Single-file TypeScript OpenCode plugin (`src/index.ts`). Exports `CronPlugin` which is auto-discovered when installed as an npm plugin or placed in `.opencode/plugins/`.
+
+### Flow
+
+1. Plugin initializes → reads `.cron-job/tasks.md` from `directory` (project root)
+2. Parses `##` sections → extracts `- cron:` and `- prompt:` fields
+3. Schedules each valid cron expression via `node-cron`
+4. On timer fire → `client.tui.appendPrompt()` → `client.tui.submitPrompt()`
+5. Registers 4 tools: `cron_create`, `cron_list`, `cron_run`, `cron_delete`
+
+### Key constraints
+
+- NOT an MCP server — runs inside OpenCode process (no HTTP API, no sidecar)
+- Tools are defined with `tool()` helper from `@opencode-ai/plugin`, not raw objects
+- Prompt injection uses `client.tui.*` methods (TUI mode only)
+- Cron uses 5-field expressions by default, 6-field if seconds are specified (`*/30 * * * * *`)
+- Jobs are in-memory and volatile — reload via `cron_reload` after editing `.cron-job/tasks.md`
+- `@opencode-ai/plugin` is a peer dependency provided by OpenCode runtime
+- Plugin auto-updates via npm `@latest` tag are unreliable — bump pinned version in config or clear cache manually
+
+### Published API
+
+```json
+{
+  "plugin": ["opencode-cron-job@latest"]
+}
+```
+
+## Gotchas
+
+- `node-cron` v3 accepts 6-field format (seconds included)
+- Plugin runs inside Bun/OpenCode runtime — use `import` syntax, not `require`
+- Build artifact `.opencode/plugins/index.js` is copied from `dist/` — both gitignored
+- `.opencode/package.json` has its own `node_modules/` for local plugin dev — separate from root

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-04
+
+### Added
+
+- Initial release
+- OpenCode plugin that schedules recurring prompts via `.cron-job/tasks.md`
+- Tools: `cron_create`, `cron_list`, `cron_run`, `cron_delete`
+- Auto-load tasks on plugin initialization
+- Prompt injection via `client.tui.appendPrompt()` + `client.tui.submitPrompt()`
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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/PUBLISH.md

@@ -0,0 +1,77 @@
+# 发布指南
+
+## 发布前检查
+
+### 检查 `package.json` 版本号
+
+```json
+{
+  "version": "0.1.0"
+}
+```
+
+确保版本号符合语义化版本规范。
+
+### 检查 CHANGELOG.md 是否需要同步
+
+CHANGELOG.md 是 GitHub Release Notes 的数据源：
+
+- **每次发版前**：在 `[Unreleased]` 下方写好本次版本的变更说明
+- **格式**：遵循 [Keep a Changelog](https://keepachangelog.com/) 规范，分 `Added` / `Changed` / `Fixed` / `Removed` 等分类
+- **日期**：格式为 `YYYY-MM-DD`
+
+### 检查 README.md 是否需要同步
+
+- **功能增减**或**行为变化**时需要同步更新中英文说明
+- 纯 bug 修复不需要更新
+
+### 检查 AGENTS.md 是否需要同步
+
+- **架构变更**、**工具变更**（新增/删除工具）时需要更新
+- Bug 修复或内部重构不需要更新
+
+---
+
+## 发布流程
+
+### 1. 更新 CHANGELOG.md（必做）
+
+将 `[Unreleased]` 改为版本号和日期：
+
+```markdown
+## [0.1.0] - 2026-06-04
+
+### Added
+- 新增功能...
+```
+
+### 2. 更新版本号
+
+编辑 `package.json` 中的 `version` 字段。
+
+### 3. 提交代码并推送 Tag
+
+> ⚠️ 执行前先向用户发送消息确认（已完成以上检查和修改），获得确认后才能执行。
+
+```bash
+git add -A
+git commit -m "release: v0.1.0"
+git tag v0.1.0
+git push origin main --tags
+```
+
+> push 不会自动推送 tags，必须执行 `git push origin --tags` 或 `git push origin v0.1.0`。
+
+### 4. 自动构建与发布
+
+推送 tag 后，GitHub Actions 自动触发 `.github/workflows/release.yml`：
+
+1. **`publish-npm`** — 安装依赖 → 构建 → 发布到 npm
+2. **`release`** — 自动创建带 Release Notes 的 GitHub Release
+
+> **前置条件**：在 GitHub 仓库 Settings → Secrets and variables → Actions 中配置 `NPM` secret，值为 npm Automation Token。
+
+### 5. 检查结果
+
+- 确认 npm 包已更新：`npm view opencode-cron-job`
+- 确认 GitHub Release 已创建

package/README.md

@@ -0,0 +1,160 @@
+# opencode-cron-job
+
+[![npm version](https://img.shields.io/npm/v/opencode-cron-job)](https://www.npmjs.com/package/opencode-cron-job)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**OpenCode plugin** — schedule recurring prompts via a simple markdown file.  
+**OpenCode 插件** — 通过简单的 markdown 文件定时执行 prompt。
+
+> ⚠️ **Alpha** — This is an initial release and has not been extensively tested. Use at your own risk.  
+> ⚠️ **Alpha** — 此为初版，未经充分测试，请谨慎使用。
+
+---
+
+## English
+
+### Overview
+
+`opencode-cron-job` is an OpenCode plugin that automatically reads cron tasks from `.cron-job/tasks.md` in your project root and injects prompts into your session on schedule. No MCP server, no HTTP API, no sidecar — runs entirely inside OpenCode.
+
+### How it works
+
+1. Create `.cron-job/tasks.md` in your project
+2. Write tasks using simple markdown format
+3. OpenCode loads the plugin automatically → reads the file → starts timers
+4. When a timer fires, the prompt is injected into your session
+
+### Install
+
+```json
+{
+  "plugin": ["opencode-cron-job@latest"]
+}
+```
+
+OpenCode auto-installs npm plugins on startup.
+
+### Usage
+
+Edit `.cron-job/tasks.md` to define your cron tasks. The plugin automatically loads them on startup.
+
+To manage scheduled tasks, use natural language with the AI agent:
+
+- "List all my cron jobs"
+- "Run the code review task now"
+- "Delete the backup task"
+- "Reload the cron tasks from the file"
+
+The agent calls the following tools internally — you don't need to use them directly:
+
+| Tool | Description |
+|------|-------------|
+| `cron_create` | Create a cron job (name, schedule, prompt) |
+| `cron_list` | List all scheduled tasks |
+| `cron_run` | Run a task immediately |
+| `cron_delete` | Delete a task |
+
+### Task file format
+
+Create `.cron-job/tasks.md`:
+
+```markdown
+# Cron Tasks
+
+## Daily Code Review
+- cron: 0 9 * * *
+- prompt: Review all changed files and generate a report
+
+## Hourly Backup
+- cron: 0 */1 * * *
+- prompt: Backup the database
+```
+
+Each section starting with `##` is a task. Supported fields:
+- `cron` — standard 5-field cron expression (supports 6-field with seconds)
+- `prompt` — the prompt text to inject when the timer fires
+
+### Update
+
+```bash
+# Clear plugin cache and restart OpenCode
+rm -rf ~/.cache/opencode/node_modules/opencode-cron-job
+```
+
+---
+
+## 中文
+
+### 概述
+
+`opencode-cron-job` 是一个 OpenCode 插件，自动读取项目根目录下的 `.cron-job/tasks.md` 文件，按 cron 表达式定时向当前会话注入 prompt。无需 MCP 服务、无需 HTTP API、无需 sidecar 进程，完全在 OpenCode 内部运行。
+
+### 工作方式
+
+1. 在项目根目录创建 `.cron-job/tasks.md`
+2. 用简单的 markdown 格式编写任务
+3. OpenCode 启动时自动加载插件 → 读取文件 → 启动定时器
+4. 到时间自动向会话注入 prompt
+
+### 安装
+
+```json
+{
+  "plugin": ["opencode-cron-job@latest"]
+}
+```
+
+OpenCode 启动时自动安装 npm 插件。
+
+### 使用方式
+
+编辑 `.cron-job/tasks.md` 定义定时任务，插件启动时自动加载。
+
+要管理任务，直接对 AI 说自然语言即可，例如：
+
+- "列出所有周期任务"
+- "立即执行一下代码检查"
+- "把备份任务删掉"
+- "重新加载任务文件"
+
+Agent 内部会调用以下工具来完成，你不需要直接使用：
+
+| 工具 | 说明 |
+|------|------|
+| `cron_create` | 创建周期任务（名称、cron 表达式、prompt） |
+| `cron_list` | 列出所有任务 |
+| `cron_run` | 立即执行一个任务 |
+| `cron_delete` | 删除任务 |
+
+### 任务文件格式
+
+创建 `.cron-job/tasks.md`：
+
+```markdown
+# 周期任务
+
+## 每日代码检查
+- cron: 0 9 * * *
+- prompt: 检查所有变更文件并生成报告
+
+## 每小时备份
+- cron: 0 */1 * * *
+- prompt: 备份数据库
+```
+
+每个以 `##` 开头的区块为一个任务。支持字段：
+- `cron` — 标准 5 段 cron 表达式（也支持含秒的 6 段格式）
+- `prompt` — 定时触发时注入的 prompt 内容
+
+### 更新
+
+```bash
+# 清除插件缓存后重启 OpenCode
+rm -rf ~/.cache/opencode/node_modules/opencode-cron-job
+```
+
+---
+
+## License / 许可证
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "opencode-cron-job",
+  "version": "0.1.0",
+  "description": "OpenCode plugin - schedule recurring prompts via markdown files",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "node-cron": "^3.0.3"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.15.5",
+    "@types/node": "^22.0.0",
+    "@types/node-cron": "^3.0.11",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+import { readFileSync, existsSync } from "fs"
+import { join } from "path"
+import cron from "node-cron"
+import { tool, type Plugin } from "@opencode-ai/plugin"
+
+interface Job {
+  id: string
+  name: string
+  schedule: string
+  prompt: string
+  task: cron.ScheduledTask | null
+}
+
+function parseTasks(content: string): { name: string; schedule: string; prompt: string }[] {
+  const tasks: { name: string; schedule: string; prompt: string }[] = []
+  const sections = content.split(/^## /m).filter((s) => s.trim())
+  for (const section of sections) {
+    const lines = section.split("\n")
+    const name = lines[0]?.trim()
+    if (!name) continue
+    let schedule = "", prompt = ""
+    for (const line of lines.slice(1)) {
+      const t = line.trim()
+      if (t.startsWith("- cron:")) schedule = t.slice("- cron:".length).trim()
+      else if (t.startsWith("- prompt:")) prompt = t.slice("- prompt:".length).trim()
+    }
+    if (schedule && prompt) tasks.push({ name, schedule, prompt })
+  }
+  return tasks
+}
+
+let jobs: Job[] = []
+let nextId = 1
+
+export const CronPlugin: Plugin = async ({ client, directory }) => {
+  const tasksFile = join(directory, ".cron-job", "tasks.md")
+
+  function fire(job: Job) {
+    client.tui.appendPrompt({ body: { text: job.prompt } })
+      .then(() => client.tui.submitPrompt())
+      .catch(() => {})
+  }
+
+  function schedule(j: Job) {
+    if (cron.validate(j.schedule)) {
+      j.task = cron.schedule(j.schedule, () => fire(j))
+    }
+  }
+
+  // Load from file on startup
+  if (existsSync(tasksFile)) {
+    const items = parseTasks(readFileSync(tasksFile, "utf-8"))
+    for (const item of items) {
+      const job: Job = { ...item, id: String(nextId++), task: null }
+      schedule(job)
+      jobs.push(job)
+    }
+  }
+
+  return {
+    tool: {
+      cron_create: tool({
+        description: "Create a new cron job. The job fires on schedule by injecting the prompt into the user's session. Jobs are ephemeral (in-memory) and lost when OpenCode restarts. To persist a job permanently, also add it to .cron-job/tasks.md so it auto-loads on startup.",
+        args: {
+          name: tool.schema.string().describe("Unique name for this job"),
+          schedule: tool.schema.string().describe("Cron expression. 5-field format (min hour dom mon dow), e.g. '0 9 * * *' for daily at 9am. Supports 6-field with seconds: '*/30 * * * * *' for every 30s."),
+          prompt: tool.schema.string().describe("The prompt text that gets injected into the session when the job fires. The AI will receive this as a user message and act on it."),
+        },
+        async execute(args) {
+          const job: Job = { id: String(nextId++), name: args.name, schedule: args.schedule, prompt: args.prompt, task: null }
+          schedule(job)
+          jobs.push(job)
+          return `Created job: ${job.name} (ID: ${job.id}, cron: ${job.schedule})`
+        },
+      }),
+
+      cron_list: tool({
+        description: "List all scheduled cron jobs",
+        args: {},
+        async execute() {
+          if (jobs.length === 0) return "No jobs scheduled."
+          return jobs.map((j) => `${j.id}  ${j.schedule}  ${j.name}`).join("\n")
+        },
+      }),
+
+      cron_run: tool({
+        description: "Run a job immediately (fire-and-forget). The job fires once right now regardless of its cron schedule. Useful for testing or one-off execution. The job remains scheduled and will continue firing on its normal cron schedule afterwards.",
+        args: {
+          jobId: tool.schema.string().describe("ID of the job to run. Get it from cron_list."),
+        },
+        async execute(args) {
+          const job = jobs.find((j) => j.id === args.jobId)
+          if (!job) return `Job ${args.jobId} not found.`
+          fire(job)
+          return `${job.name}: triggered`
+        },
+      }),
+
+      cron_delete: tool({
+        description: "Delete a cron job. Stops the timer and removes it from memory. This does not modify .cron-job/tasks.md — if the job was defined there, it will reappear after OpenCode restarts.",
+        args: {
+          jobId: tool.schema.string().describe("ID of the job to delete. Get it from cron_list."),
+        },
+        async execute(args) {
+          const idx = jobs.findIndex((j) => j.id === args.jobId)
+          if (idx === -1) return `Job ${args.jobId} not found.`
+          const [job] = jobs.splice(idx, 1)
+          job.task?.stop()
+          return `${job.name}: deleted`
+        },
+      }),
+    },
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+