opencode-jobs 0.1.0

package/dist/install.d.ts

@@ -0,0 +1,46 @@
+export declare const PACKAGE_NAME = "opencode-jobs";
+export declare const SKILL_NAME = "opencode-jobs";
+export type ConfigInstall = {
+    status: "added" | "present";
+    configPath: string;
+} | {
+    status: "manual";
+    configPath: string;
+};
+export interface SkillInstall {
+    status: "written" | "unchanged";
+    skillPath: string;
+}
+export interface ProjectInstall {
+    projectDirectory: string;
+    plugin: ConfigInstall;
+    skill: SkillInstall;
+}
+export declare function installPluginConfig(projectDirectory: string): ConfigInstall;
+export declare function installSkill(projectDirectory: string, packageDirectory: string): SkillInstall;
+export declare function installProject(projectDirectory: string, packageDirectory: string): ProjectInstall;
+export type ConfigUninstall = {
+    status: "removed" | "absent";
+    configPath: string;
+} | {
+    status: "manual";
+    configPath: string;
+};
+export interface SkillUninstall {
+    status: "removed" | "absent" | "kept-modified";
+    skillPath: string;
+}
+export interface PurgeResult {
+    paths: string[];
+}
+export interface ProjectUninstall {
+    projectDirectory: string;
+    disabled: boolean;
+    plugin: ConfigUninstall;
+    skill: SkillUninstall;
+    purge?: PurgeResult;
+}
+export declare function uninstallPluginConfig(projectDirectory: string): ConfigUninstall;
+export declare function uninstallSkill(projectDirectory: string, packageDirectory: string): SkillUninstall;
+export declare function purgeProjectData(projectDirectory: string): PurgeResult;
+export declare function uninstallProject(projectDirectory: string, packageDirectory: string, shouldPurge: boolean): ProjectUninstall;

package/dist/internals.d.ts

@@ -0,0 +1,19 @@
+import { deriveScopeId, shQuote, slugify } from "./paths.js";
+import { cronToOnCalendar, describeCron, parseCron } from "./cron.js";
+import { validateGuard, validateRunSpec, validateSession } from "./job.js";
+import { buildOpencodeArguments, runScriptContent, serviceContent, timerContent } from "./systemd.js";
+export declare const internals: {
+    slugify: typeof slugify;
+    shQuote: typeof shQuote;
+    deriveScopeId: typeof deriveScopeId;
+    parseCron: typeof parseCron;
+    cronToOnCalendar: typeof cronToOnCalendar;
+    describeCron: typeof describeCron;
+    validateRunSpec: typeof validateRunSpec;
+    validateGuard: typeof validateGuard;
+    validateSession: typeof validateSession;
+    buildOpencodeArguments: typeof buildOpencodeArguments;
+    runScriptContent: typeof runScriptContent;
+    serviceContent: typeof serviceContent;
+    timerContent: typeof timerContent;
+};

package/dist/job.d.ts

@@ -0,0 +1,43 @@
+interface RunOptions {
+    agent?: string;
+    model?: string;
+}
+export interface PromptRun extends RunOptions {
+    prompt: string;
+}
+export interface CommandRun extends RunOptions {
+    command: string;
+    arguments?: string;
+}
+export type RunSpec = PromptRun | CommandRun;
+export declare const SESSION_MODES: readonly ["new", "persist", "compact", "compact+last"];
+export type SessionMode = (typeof SESSION_MODES)[number];
+export interface Job {
+    slug: string;
+    name: string;
+    schedule: string;
+    run: RunSpec;
+    session?: SessionMode;
+    guard?: string;
+    timeoutSeconds?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export type JobResult = {
+    ok: true;
+    job: Job;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateRunSpec(run: unknown, context: string): RunSpec;
+export declare function validateSession(value: unknown, context: string): SessionMode;
+export declare function validateTimeout(value: unknown, context: string): number | undefined;
+export declare function validateGuard(value: unknown, context: string): string | undefined;
+export declare function loadJobFile(file: string, expectedSlug?: string): JobResult;
+export declare function loadJobs(workdir: string): {
+    jobs: Job[];
+    errors: string[];
+};
+export declare function saveJob(workdir: string, job: Job): void;
+export {};

package/dist/json.d.ts

@@ -0,0 +1,4 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function stringProperty(record: Record<string, unknown>, key: string): string | undefined;
+export declare function numberProperty(record: Record<string, unknown>, key: string): number | undefined;
+export declare function errorMessage(error: unknown): string;

package/dist/paths.d.ts

@@ -0,0 +1,24 @@
+export declare function configRoot(): string;
+export declare function schedulerDirectory(): string;
+export declare function registryPath(): string;
+export declare function scopeDirectory(scopeId: string): string;
+export declare function runsDirectory(scopeId: string): string;
+export declare function runsFile(scopeId: string, slug: string): string;
+export declare function sessionStateDirectory(scopeId: string): string;
+export declare function sessionStateFile(scopeId: string, slug: string): string;
+export declare function logDirectory(scopeId: string): string;
+export declare function logFile(scopeId: string, slug: string): string;
+export declare function systemdUserDirectory(): string;
+export declare function jobsDirectory(workdir: string): string;
+export declare function unitBase(scopeId: string, slug: string): string;
+export declare function timerUnit(base: string): string;
+export declare function serviceUnit(base: string): string;
+export declare function runScriptPath(scopeId: string, slug: string): string;
+export declare function slugify(input: string): string;
+export declare function shQuote(value: string): string;
+export declare function unitQuote(value: string): string;
+export declare function escapeUnitText(value: string): string;
+export declare function atomicWrite(file: string, content: string): void;
+export declare function atomicWriteExecutable(file: string, content: string): void;
+export declare function nowIso(): string;
+export declare function deriveScopeId(workdir: string): string;

package/dist/project.d.ts

@@ -0,0 +1,2 @@
+export declare function enableProject(workdir: string): string;
+export declare function disableProject(workdir: string): string;

package/dist/registry.d.ts

@@ -0,0 +1,14 @@
+export interface RegistryEntry {
+    scopeId: string;
+    workdir: string;
+    enabledAt: string;
+    updatedAt: string;
+    jobs: string[];
+}
+export interface Registry {
+    version: 1;
+    projects: Record<string, RegistryEntry>;
+}
+export declare function loadRegistry(): Registry;
+export declare function saveRegistry(registry: Registry): void;
+export declare function registryEntry(workdir: string): RegistryEntry | undefined;

package/dist/runs.d.ts

@@ -0,0 +1,16 @@
+export interface RunRecord {
+    runId?: string;
+    slug?: string;
+    scopeId?: string;
+    startedAt?: number;
+    finishedAt?: number;
+    durationMs?: number;
+    status?: string;
+    exitCode?: number;
+    sessionId?: string;
+    startedBy?: string;
+}
+export declare function readRunRecords(scopeId: string, slug: string, limit: number): RunRecord[];
+export declare function lastFinishedRun(records: RunRecord[]): RunRecord | undefined;
+export declare function formatRunLine(record: RunRecord): string;
+export declare function tailFile(file: string, lines: number, maxChars: number): string | undefined;

package/dist/systemd.d.ts

@@ -0,0 +1,26 @@
+import { type Job } from "./job.js";
+export declare function findOpencode(): string;
+export declare function buildOpencodeArguments(job: Job, sessionId?: string): string[];
+export declare function runScriptContent(job: Job, scopeId: string, opencodeBin: string): string;
+export declare function serviceContent(job: Job, options: {
+    workdir: string;
+    runScript: string;
+    log: string;
+    pathEnvironment: string;
+}): string;
+export declare function timerContent(job: Job, onCalendars: string[]): string;
+export interface SystemctlResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+export declare function systemctl(systemctlArguments: string[]): SystemctlResult;
+export declare function systemdHint(stderr: string): string;
+export interface TimerStatus {
+    next: string | undefined;
+    last: string | undefined;
+}
+export declare function timerStatus(base: string): TimerStatus;
+export declare function writeJobUnits(job: Job, workdir: string, scopeId: string, opencodeBin: string, pathEnvironment: string): string;
+export declare function removeJobUnits(scopeId: string, slug: string): void;
+export declare function removeStaleUnits(scopeId: string, expectedSlugs: Set<string>): string[];

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export declare const schedulerTools: Record<string, ToolDefinition>;

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "opencode-jobs",
+  "version": "0.1.0",
+  "description": "opencode plugin that schedules recurring agent jobs as systemd user timers, with git-committable job definitions, run history, and session continuity",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "opencode-jobs": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm --external @opencode-ai/plugin && bun build src/cli.ts --outfile dist/cli.js --target node --format esm && tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "format": "prettier --write .",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit",
+    "check": "prettier --check . && eslint && tsc --noEmit",
+    "smoke": "npm run build && node scripts/smoke.mjs && node scripts/cli-smoke.mjs",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "scheduler",
+    "cron",
+    "jobs",
+    "timers",
+    "systemd",
+    "automation",
+    "agent"
+  ],
+  "author": "Connor Fraser-Grant",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fraser-Grant/opencode-jobs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Fraser-Grant/opencode-jobs/issues"
+  },
+  "homepage": "https://github.com/Fraser-Grant/opencode-jobs#readme",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.18.18"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.2.0",
+    "eslint": "^10.9.0",
+    "eslint-plugin-unicorn": "^73.0.0",
+    "prettier": "^3.9.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.67.0"
+  }
+}

package/skill/opencode-jobs/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: opencode-jobs
+description: Schedule and manage recurring OpenCode agent jobs with project-local definitions and systemd user timers. Use when asked to schedule, inspect, run, enable, disable, or troubleshoot recurring jobs and their logs.
+license: MIT
+compatibility: opencode on Linux with systemd
+---
+
+# OpenCode Jobs
+
+Use the `opencode-jobs` tools instead of editing systemd units or global
+scheduler state directly.
+
+## Workflow
+
+1. Create or update a definition with `schedule_job`. Definitions belong in
+   `.opencode/scheduler/jobs/<slug>.json` and should be committed with the
+   project.
+2. Inspect definitions with `list_jobs` or `get_job`.
+3. Run `enable_project` after the first job is created. Run it again to
+   reconcile timers after externally editing definitions.
+4. Use `run_job` for a manual fire-and-forget run and `job_logs` to inspect
+   its output.
+5. Use `disable_project` to remove timers while retaining definitions,
+   history, and logs. Use `delete_job` only when the definition should also
+   be removed.
+
+## Scheduling Rules
+
+- Schedules are five-field cron expressions: minute, hour, day of month,
+  month, day of week.
+- Set exactly one of `prompt` or `command`. `arguments` only applies to a
+  custom command.
+- Default to `session: new`. Use `persist` when full continuity is needed,
+  `compact` for summary continuity, or `compact+last` when the previous final
+  result must also remain visible.
+- A `guard` is a shell command that must exit zero for the job to run.
+- Scheduled jobs require Linux, a systemd user session, and an `opencode`
+  executable available to the timer environment.
+
+## Project Installation
+
+When the plugin or this skill is missing, install both from a globally
+installed package:
+
+```sh
+opencode-jobs install /path/to/project     # add plugin entry + skill
+opencode-jobs uninstall /path/to/project   # reverse (add --purge to wipe data)
+```
+
+The commands default to the current directory. Restart OpenCode after
+installation so it loads the plugin and discovers the skill.