openclaw-trakt 1.0.0

package/README.md

@@ -0,0 +1,42 @@
+# openclaw-trakt
+
+OpenClaw plugin for [Trakt.tv](https://trakt.tv). Track movies and TV shows, view watch history, manage your watchlist, and check show progress.
+
+## Install
+
+```bash
+openclaw plugins install openclaw-trakt
+```
+
+## Prerequisites
+
+The `trakt-cli` Go binary must be installed and on your PATH:
+
+```bash
+go install github.com/omarshahine/trakt-plugin@latest
+```
+
+Or set `TRAKT_CLI_PATH` environment variable, or configure `cliPath` in plugin settings.
+
+## Configuration
+
+| Setting | Description |
+|---------|-------------|
+| `cliPath` | Path to trakt-cli binary (auto-detected on PATH) |
+| `clientId` | Trakt API client ID (from https://trakt.tv/oauth/applications) |
+| `clientSecret` | Trakt API client secret |
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `trakt_search` | Search for movies and TV shows |
+| `trakt_history` | View watch history |
+| `trakt_history_add` | Mark movies/shows as watched |
+| `trakt_watchlist` | View watchlist |
+| `trakt_progress` | Show watch progress for TV shows |
+| `trakt_auth` | Set up Trakt.tv authentication |
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,41 @@
+{
+  "id": "trakt",
+  "name": "Trakt",
+  "description": "Track movies and TV shows using trakt.tv",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "cliPath": {
+        "type": "string",
+        "description": "Path to trakt-cli binary",
+        "default": "trakt-cli"
+      },
+      "clientId": {
+        "type": "string",
+        "description": "Trakt API client ID (from https://trakt.tv/oauth/applications)"
+      },
+      "clientSecret": {
+        "type": "string",
+        "description": "Trakt API client secret"
+      }
+    }
+  },
+  "uiHints": {
+    "cliPath": {
+      "label": "CLI Path",
+      "help": "Path or command name for the trakt-cli binary. Defaults to finding it on PATH.",
+      "placeholder": "trakt-cli"
+    },
+    "clientId": {
+      "label": "Client ID",
+      "help": "Trakt API client ID from https://trakt.tv/oauth/applications",
+      "sensitive": true
+    },
+    "clientSecret": {
+      "label": "Client Secret",
+      "help": "Trakt API client secret from https://trakt.tv/oauth/applications",
+      "sensitive": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "openclaw-trakt",
+  "version": "1.0.0",
+  "description": "OpenClaw plugin for Trakt.tv - track movies and TV shows",
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "trakt",
+    "movies",
+    "tv-shows",
+    "watchlist"
+  ],
+  "author": {
+    "name": "Omar Shahine",
+    "email": "omar@shahine.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omarshahine/trakt-plugin.git"
+  },
+  "homepage": "https://github.com/omarshahine/trakt-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/omarshahine/trakt-plugin/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/trakt/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: trakt
+description: |
+  Search movies/shows, view watch history, check watchlist, track progress, and mark items as watched on Trakt.tv.
+  Use when the user asks what they've been watching, what's on their watchlist, what's in progress,
+  wants to find a movie or show, mark something as watched, or asks about their Trakt activity.
+license: MIT
+metadata:
+  author: Omar Shahine
+  version: 2.0.0
+  openclaw:
+    requires:
+      bins: [trakt-cli]
+---
+
+# Trakt Skill
+
+View watch history, watchlist, progress, search, and mark items as watched on Trakt.tv.
+
+All commands support `--json` for machine-readable output. **Always use `--json` for data processing.**
+
+## Commands
+
+### Progress (In-Progress Shows)
+
+Shows which watchlist shows are started but not finished, not started, or completed.
+
+```bash
+trakt-cli progress --json
+trakt-cli progress --all --json
+```
+
+- Default: shows only in-progress items + summary counts
+- `--all`: includes not_started and completed lists
+- JSON output: `{ "in_progress": [...], "summary": { "in_progress": N, "not_started": N, "completed": N } }`
+- Each item: `{ "title", "year", "trakt_id", "aired", "watched", "remaining", "percent", "status", "next_episode" }`
+
+### Watchlist
+
+```bash
+trakt-cli watchlist --json
+trakt-cli watchlist --type shows --limit 100 --json
+trakt-cli watchlist --type movies --json
+```
+
+- JSON output: `{ "items": [{ "type", "title", "year", "trakt_id", "added_at" }], "page", "page_count", "item_count" }`
+- `--type`: filter by `movies` or `shows`
+- `--limit`: items per page (default 10)
+- `--page`: page number
+
+### Watch History
+
+```bash
+trakt-cli history --json
+trakt-cli history --type shows --limit 20 --json
+trakt-cli history --type movies --json
+```
+
+- JSON output: `{ "items": [{ "type", "title", "year", "watched_at", "season", "episode", "show_title" }], ... }`
+- Episodes include `show_title`, `season`, `episode` fields
+
+### Mark as Watched
+
+```bash
+trakt-cli history add "Pluribus" --json
+trakt-cli history add "The Sopranos" "The Wire" --json
+trakt-cli history add --type movie "The Godfather" --json
+trakt-cli history add --watched-at 2025-06-15 "Dark" --json
+```
+
+- Searches by name, prefers exact title matches
+- `--type show` (default) or `--type movie`
+- `--watched-at`: RFC3339 or YYYY-MM-DD (defaults to now)
+- Accepts multiple titles in one call
+- JSON output: `{ "added_episodes": N, "added_movies": N, "not_found_movies": N, "not_found_shows": N }`
+
+### Search
+
+```bash
+trakt-cli search "Shogun" --json
+trakt-cli search "Inception" --type movie --json
+```
+
+- JSON output: `{ "items": [{ "type", "title", "year", "trakt_id", "imdb", "score" }] }`
+- `--type`: `movie`, `show`, or `movie,show` (default)
+
+## Notes
+
+- Always use `--json` flag — raw table output is for human use only
+- No shell constructs (pipes, redirects, chaining)
+- Auth stored in `~/.trakt.yaml` (OAuth device flow)
+
+## Changelog
+
+- **v2.0.0** — Add `progress` command, `--json` flag for all commands (agent-friendly output)
+- **v1.1.0** — Add `watchlist` command, `--type` filter for `history`, `history add` with `--watched-at`
+- **v1.0.0** — Initial skill (upstream `history` and `search` only)

package/src/index.ts

@@ -0,0 +1,413 @@
+/**
+ * OpenClaw plugin entry for trakt-cli.
+ *
+ * Registers tool factories that shell out to the `trakt-cli` binary.
+ * Each tool maps to a CLI subcommand (search, history, watchlist, progress).
+ * Uses the factory pattern so each agent gets per-workspace config resolution.
+ */
+
+import { execFileSync, execFile } from 'child_process';
+import { promisify } from 'util';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const execFileAsync = promisify(execFile);
+
+// OpenClaw plugin config (from openclaw.plugin.json configSchema)
+interface PluginConfig {
+	cliPath?: string;
+	clientId?: string;
+	clientSecret?: string;
+}
+
+// OpenClaw tool result content block
+interface TextContent {
+	type: 'text';
+	text: string;
+}
+
+// OpenClaw tool definition
+interface OpenClawToolDefinition {
+	name: string;
+	label: string;
+	description: string;
+	parameters: Record<string, unknown>;
+	execute: (
+		toolCallId: string,
+		params: Record<string, unknown>,
+		signal?: AbortSignal,
+		onUpdate?: (partialResult: unknown) => void
+	) => Promise<{ content: TextContent[] }>;
+}
+
+// Context provided to factory functions
+interface OpenClawPluginToolContext {
+	config?: Record<string, unknown>;
+	workspaceDir?: string;
+	agentDir?: string;
+}
+
+// Factory function type
+type OpenClawPluginToolFactory = (
+	ctx: OpenClawPluginToolContext
+) => OpenClawToolDefinition | OpenClawToolDefinition[] | null | undefined;
+
+// OpenClaw plugin registration interface
+interface OpenClawContext {
+	config?: PluginConfig;
+	registerTool(toolOrFactory: OpenClawToolDefinition | OpenClawPluginToolFactory): void;
+}
+
+// Tool definitions — each maps to a CLI subcommand
+const TOOLS: Array<{
+	name: string;
+	command: string;
+	subcommand?: string;
+	description: string;
+	parameters: Record<string, unknown>;
+}> = [
+	{
+		name: 'trakt_search',
+		command: 'search',
+		description:
+			'Search Trakt.tv for movies and TV shows. Returns title, year, trakt_id, imdb, and relevance score.',
+		parameters: {
+			type: 'object',
+			properties: {
+				query: {
+					type: 'string',
+					description: 'Search query (movie or show title)'
+				},
+				type: {
+					type: 'string',
+					enum: ['movie', 'show', 'movie,show'],
+					description: 'Filter by type (default: movie,show)'
+				}
+			},
+			required: ['query']
+		}
+	},
+	{
+		name: 'trakt_history',
+		command: 'history',
+		description:
+			'View Trakt.tv watch history. Returns recently watched movies and episodes with timestamps.',
+		parameters: {
+			type: 'object',
+			properties: {
+				type: {
+					type: 'string',
+					enum: ['movies', 'shows'],
+					description: 'Filter by type'
+				},
+				limit: {
+					type: 'number',
+					description: 'Items per page (default 10)'
+				},
+				page: {
+					type: 'number',
+					description: 'Page number'
+				}
+			}
+		}
+	},
+	{
+		name: 'trakt_history_add',
+		command: 'history',
+		subcommand: 'add',
+		description:
+			'Mark movies or shows as watched on Trakt.tv. Searches by title and adds to history. Accepts multiple titles.',
+		parameters: {
+			type: 'object',
+			properties: {
+				titles: {
+					type: 'array',
+					items: { type: 'string' },
+					description: 'Title(s) to mark as watched'
+				},
+				type: {
+					type: 'string',
+					enum: ['movie', 'show'],
+					description: 'Content type (default: show)'
+				},
+				watched_at: {
+					type: 'string',
+					description: 'When watched (YYYY-MM-DD or RFC3339, defaults to now)'
+				}
+			},
+			required: ['titles']
+		}
+	},
+	{
+		name: 'trakt_watchlist',
+		command: 'watchlist',
+		description:
+			'View Trakt.tv watchlist. Returns items the user wants to watch, with type, title, year, and added date.',
+		parameters: {
+			type: 'object',
+			properties: {
+				type: {
+					type: 'string',
+					enum: ['movies', 'shows'],
+					description: 'Filter by type'
+				},
+				limit: {
+					type: 'number',
+					description: 'Items per page (default 10)'
+				},
+				page: {
+					type: 'number',
+					description: 'Page number'
+				}
+			}
+		}
+	},
+	{
+		name: 'trakt_progress',
+		command: 'progress',
+		description:
+			'Show progress of watchlist TV shows. Returns in-progress shows with episode counts, percentage, and next episode to watch.',
+		parameters: {
+			type: 'object',
+			properties: {
+				all: {
+					type: 'boolean',
+					description: 'Include not_started and completed shows (default: in-progress only)'
+				}
+			}
+		}
+	},
+	{
+		name: 'trakt_auth',
+		command: 'auth',
+		description:
+			'Set up Trakt.tv authentication. Initiates OAuth device flow using configured client credentials. Only needed for initial setup.',
+		parameters: {
+			type: 'object',
+			properties: {}
+		}
+	}
+];
+
+/**
+ * Look up a binary on PATH, cross-platform.
+ * Uses `which` on Unix and `where.exe` on Windows.
+ */
+function whichBinary(name: string): string | null {
+	const cmd = process.platform === 'win32' ? 'where.exe' : 'which';
+	try {
+		const result = execFileSync(cmd, [name], { encoding: 'utf8' }).trim();
+		// `where.exe` can return multiple lines; take the first
+		const first = result.split('\n')[0]?.trim();
+		return first || null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve the CLI binary path using a discovery chain:
+ * 1. Plugin config cliPath
+ * 2. Env var TRAKT_CLI_PATH
+ * 3. PATH lookup (try both `trakt-cli` and `trakt-plugin`)
+ * 4. Error with helpful message
+ */
+function resolveCliPath(config?: PluginConfig): string {
+	// 1. Plugin config
+	if (config?.cliPath && existsSync(config.cliPath)) {
+		return config.cliPath;
+	}
+
+	// 2. Env var
+	const envPath = process.env.TRAKT_CLI_PATH;
+	if (envPath && existsSync(envPath)) {
+		return envPath;
+	}
+
+	// 3. PATH lookup — try both binary names
+	for (const name of ['trakt-cli', 'trakt-plugin']) {
+		const found = whichBinary(name);
+		if (found) return found;
+	}
+
+	throw new Error(
+		'trakt-cli not found. Install with: go install github.com/omarshahine/trakt-plugin@latest\n' +
+			'Or set TRAKT_CLI_PATH or configure cliPath in plugin settings.'
+	);
+}
+
+/**
+ * Check if Trakt auth is configured (~/.trakt.yaml exists).
+ */
+function isAuthConfigured(): boolean {
+	return existsSync(join(homedir(), '.trakt.yaml'));
+}
+
+/**
+ * Build CLI arguments from tool parameters.
+ * Always appends --json for machine-readable output.
+ */
+function buildCliArgs(
+	command: string,
+	subcommand: string | undefined,
+	params: Record<string, unknown>,
+	config?: PluginConfig
+): string[] {
+	const args: string[] = [command];
+
+	// Handle auth command specially — uses config credentials
+	if (command === 'auth') {
+		if (config?.clientId) args.push('--client-id', config.clientId);
+		if (config?.clientSecret) args.push('--client-secret', config.clientSecret);
+		return args;
+	}
+
+	// Add subcommand if present (e.g., history add)
+	if (subcommand) args.push(subcommand);
+
+	// Handle search: positional query arg
+	if (command === 'search') {
+		if (params.query) args.push(String(params.query));
+	}
+
+	// Handle history add: positional titles
+	if (command === 'history' && subcommand === 'add') {
+		const titles = params.titles as string[] | undefined;
+		if (titles) {
+			// --type and --watched-at go before titles
+			if (params.type) args.push('--type', String(params.type));
+			if (params.watched_at) args.push('--watched-at', String(params.watched_at));
+			for (const title of titles) {
+				args.push(title);
+			}
+			args.push('--json');
+			return args;
+		}
+	}
+
+	// Map remaining params to CLI flags
+	const skipKeys = new Set(['query', 'titles']);
+	for (const [key, value] of Object.entries(params)) {
+		if (skipKeys.has(key) || value === undefined || value === null || value === false) continue;
+
+		const flag = `--${key.replace(/_/g, '-')}`;
+		if (typeof value === 'boolean') {
+			args.push(flag);
+		} else {
+			args.push(flag, String(value));
+		}
+	}
+
+	// Always append --json
+	args.push('--json');
+	return args;
+}
+
+/**
+ * OpenClaw plugin activation function.
+ * Called by the OpenClaw gateway when the plugin is loaded.
+ */
+export default function activate(context: OpenClawContext): void {
+	const config = context.config;
+
+	let cliPath: string;
+
+	try {
+		cliPath = resolveCliPath(config);
+	} catch (error) {
+		// Defer error to tool execution time — plugin still loads
+		const errorMessage = error instanceof Error ? error.message : String(error);
+
+		for (const tool of TOOLS) {
+			context.registerTool(() => ({
+				name: tool.name,
+				label: tool.name,
+				description: tool.description,
+				parameters: tool.parameters,
+				async execute() {
+					return {
+						content: [
+							{
+								type: 'text' as const,
+								text: JSON.stringify({ success: false, error: errorMessage }, null, 2)
+							}
+						]
+					};
+				}
+			}));
+		}
+		return;
+	}
+
+	for (const tool of TOOLS) {
+		context.registerTool((_ctx: OpenClawPluginToolContext) => ({
+			name: tool.name,
+			label: tool.name,
+			description: tool.description,
+			parameters: tool.parameters,
+
+			async execute(
+				_toolCallId: string,
+				params: Record<string, unknown>
+			) {
+				// Check auth for non-auth tools
+				if (tool.command !== 'auth' && !isAuthConfigured()) {
+					return {
+						content: [
+							{
+								type: 'text' as const,
+								text: JSON.stringify({
+									success: false,
+									error: 'Trakt auth not configured. Run trakt_auth first, or manually: trakt-cli auth --client-id X --client-secret Y'
+								}, null, 2)
+							}
+						]
+					};
+				}
+
+				try {
+					const args = buildCliArgs(tool.command, tool.subcommand, params, config);
+					const { stdout } = await execFileAsync(cliPath, args, {
+						encoding: 'utf8',
+						timeout: 30_000,
+						maxBuffer: 1024 * 1024 // 1MB
+					});
+
+					// Try to parse as JSON for structured output
+					let result: unknown;
+					try {
+						result = JSON.parse(stdout);
+					} catch {
+						result = { output: stdout.trim() };
+					}
+
+					return {
+						content: [
+							{
+								type: 'text' as const,
+								text: JSON.stringify(result, null, 2)
+							}
+						]
+					};
+				} catch (error: unknown) {
+					const message = error instanceof Error ? error.message : String(error);
+					const stderr =
+						error && typeof error === 'object' && 'stderr' in error
+							? String((error as { stderr: unknown }).stderr).trim()
+							: '';
+					const errorOutput = stderr ? `${message}\n\nstderr: ${stderr}` : message;
+
+					return {
+						content: [
+							{
+								type: 'text' as const,
+								text: JSON.stringify({ success: false, error: errorOutput }, null, 2)
+							}
+						]
+					};
+				}
+			}
+		}));
+	}
+}