trakt-tools 1.5.1

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 trakt-tools
+```
+
+## 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,42 @@
+{
+  "id": "trakt-tools",
+  "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"
+      }
+    },
+    "additionalProperties": false
+  },
+  "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,47 @@
+{
+  "name": "trakt-tools",
+  "version": "1.5.1",
+  "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"
+  },
+  "dependencies": {
+    "openclaw": "^2026.3.23"
+  },
+  "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" }] }`
+- `--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,311 @@
+/**
+ * OpenClaw plugin entry for trakt-cli.
+ *
+ * Registers tools that shell out to the `trakt-cli` binary.
+ * Each tool maps to a CLI subcommand (search, history, watchlist, progress).
+ */
+
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { Type } from '@sinclair/typebox';
+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);
+
+interface PluginConfig {
+	cliPath?: string;
+	clientId?: string;
+	clientSecret?: string;
+}
+
+interface ToolDef {
+	name: string;
+	command: string;
+	subcommand?: string;
+	description: string;
+	parameters: ReturnType<typeof Type.Object>;
+}
+
+// Tool metadata — each maps to a CLI subcommand
+const TOOLS: ToolDef[] = [
+	{
+		name: 'trakt_search',
+		command: 'search',
+		description:
+			'Search Trakt.tv for movies and TV shows. Returns title, year, trakt_id, and imdb.',
+		parameters: Type.Object({
+			query: Type.String({ description: 'Search query (movie or show title)' }),
+			type: Type.Optional(
+				Type.Union(
+					[Type.Literal('movie'), Type.Literal('show'), Type.Literal('movie,show')],
+					{ description: 'Filter by type (default: movie,show)' }
+				)
+			),
+		}),
+	},
+	{
+		name: 'trakt_history',
+		command: 'history',
+		description:
+			'View Trakt.tv watch history. Returns recently watched movies and episodes with timestamps.',
+		parameters: Type.Object({
+			type: Type.Optional(
+				Type.Union([Type.Literal('movies'), Type.Literal('shows')], {
+					description: 'Filter by type',
+				})
+			),
+			limit: Type.Optional(Type.Number({ description: 'Items per page (default 10)' })),
+			page: Type.Optional(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({
+			titles: Type.Array(Type.String(), { description: 'Title(s) to mark as watched' }),
+			type: Type.Optional(
+				Type.Union([Type.Literal('movie'), Type.Literal('show')], {
+					description: 'Content type (default: show)',
+				})
+			),
+			watched_at: Type.Optional(
+				Type.String({
+					description: 'When watched (YYYY-MM-DD or RFC3339, defaults to now)',
+				})
+			),
+		}),
+	},
+	{
+		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({
+			type: Type.Optional(
+				Type.Union([Type.Literal('movies'), Type.Literal('shows')], {
+					description: 'Filter by type',
+				})
+			),
+			limit: Type.Optional(Type.Number({ description: 'Items per page (default 10)' })),
+			page: Type.Optional(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({
+			all: Type.Optional(
+				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({}),
+	},
+];
+
+/** Helper to build a tool result with the required content + details shape. */
+function toolResult(text: string) {
+	return {
+		content: [{ type: 'text' as const, text }],
+		details: undefined,
+	};
+}
+
+/**
+ * Look up a binary on PATH, cross-platform.
+ */
+function whichBinary(name: string): string | null {
+	const cmd = process.platform === 'win32' ? 'where.exe' : 'which';
+	try {
+		const result = execFileSync(cmd, [name], { encoding: 'utf8' }).trim();
+		const first = result.split('\n')[0]?.trim();
+		return first || null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve the CLI binary path:
+ * 1. Plugin config cliPath
+ * 2. Env var TRAKT_CLI_PATH
+ * 3. PATH lookup (try both `trakt-cli` and `trakt-plugin`)
+ */
+function resolveCliPath(config?: PluginConfig): string {
+	if (config?.cliPath && existsSync(config.cliPath)) {
+		return config.cliPath;
+	}
+
+	const envPath = process.env.TRAKT_CLI_PATH;
+	if (envPath && existsSync(envPath)) {
+		return envPath;
+	}
+
+	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.'
+	);
+}
+
+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];
+
+	if (command === 'auth') {
+		if (config?.clientId) args.push('--client-id', config.clientId);
+		if (config?.clientSecret) args.push('--client-secret', config.clientSecret);
+		return args;
+	}
+
+	if (subcommand) args.push(subcommand);
+
+	if (command === 'search') {
+		if (params.query) args.push(String(params.query));
+	}
+
+	if (command === 'history' && subcommand === 'add') {
+		const titles = params.titles as string[] | undefined;
+		if (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;
+		}
+	}
+
+	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));
+		}
+	}
+
+	args.push('--json');
+	return args;
+}
+
+export default definePluginEntry({
+	id: 'trakt-tools',
+	name: 'Trakt',
+	description: 'Track movies and TV shows using trakt.tv',
+
+	register(api) {
+		const config = api.pluginConfig as PluginConfig | undefined;
+
+		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) {
+				api.registerTool({
+					name: tool.name,
+					label: tool.name,
+					description: tool.description,
+					parameters: tool.parameters,
+					async execute() {
+						return toolResult(
+							JSON.stringify({ success: false, error: errorMessage }, null, 2)
+						);
+					},
+				});
+			}
+			return;
+		}
+
+		for (const tool of TOOLS) {
+			api.registerTool({
+				name: tool.name,
+				label: tool.name,
+				description: tool.description,
+				parameters: tool.parameters,
+
+				async execute(_id: string, params: Record<string, unknown>) {
+					if (tool.command !== 'auth' && !isAuthConfigured()) {
+						return toolResult(
+							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,
+						});
+
+						let result: unknown;
+						try {
+							result = JSON.parse(stdout);
+						} catch {
+							result = { output: stdout.trim() };
+						}
+
+						return toolResult(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 toolResult(
+							JSON.stringify({ success: false, error: errorOutput }, null, 2)
+						);
+					}
+				},
+			});
+		}
+	},
+});