@krl-grn/wande 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# wande CLI
+
+Command-line interface for automating your Wande Task Manager workspace through bot tokens.
+
+## Requirements
+
+- Node.js 18+
+- A valid bot token generated in **Settings -> Bot API**
+- Your Convex HTTP URL (for example: `https://<deployment>.convex.site`)
+
+## Install
+
+```bash
+npm i -g @krl-grn/wande
+```
+
+## Quick start
+
+```bash
+wande login <BOT_TOKEN>
+wande whoami --json
+```
+
+## Core commands
+
+### Tasks
+
+```bash
+wande tasks:list --limit 20 --json
+wande tasks:create --title "Task from CLI" --status new --json
+wande tasks:status --id <TASK_ID> --status done --json
+```
+
+### Routines
+
+```bash
+wande routines:list --limit 20 --json
+wande routines:create --title "Routine from CLI" --status new --json
+wande routines:status --id <ROUTINE_ID> --status done --json
+```
+
+### Projects
+
+```bash
+wande projects:list --json
+wande projects:create --title "CLI Project" --json
+```
+
+### Queue instances
+
+```bash
+wande queue:list --date 2026-02-23 --json
+wande queue:create --date 2026-02-23 --entity-id e1 --entity-type task --title "Queue item" --status new --json
+wande queue:status --instance-id <INSTANCE_ID> --status done --json
+```
+
+## Security notes
+
+- Bot tokens are shown only once when created. Save them securely.
+- If a token is exposed, revoke it immediately in **Settings -> Bot API** and create a new one.
+- The CLI stores token config locally for your user profile.
+
+## API behavior and limits
+
+- Supported entities: `tasks`, `routines`, `projects`, `queueInstances`
+- Bot is allowed to:
+  - read tasks/routines/projects/queueInstances
+  - create tasks/routines/projects/queueInstances
+  - update status for tasks/routines/queueInstances
+- Bot is not allowed to:
+  - delete entities
+  - reorder entities
+  - change date/time/order for existing queue instances
+- Rate limits (server-side):
+  - `60 req/min` per token
+  - `20 create/min` per token
+  - `200 create/day` per token
+
+## Troubleshooting
+
+- `401 UNAUTHORIZED`: token is invalid, expired, or revoked.
+- `403 FORBIDDEN`: token is missing required scopes.
+- `429 RATE_LIMITED`: you exceeded rate limits; retry later.
+- `Could not find public function ...`: run Convex dev/deploy so bot functions are available.
+- `login` resolves URL automatically from `https://wande.app/api/cli/config`. If needed, override with `--url`.
+
+## Development
+
+From repository root:
+
+```bash
+npm run cli:install
+npm run cli:build
+node packages/cli/dist/index.js --help
+```

package/dist/client.js

@@ -0,0 +1,27 @@
+export class BotApiClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async request(path, options) {
+        const headers = {
+            Authorization: `Bearer ${options.token}`,
+            "Content-Type": "application/json",
+        };
+        if (options.idempotencyKey) {
+            headers["X-Idempotency-Key"] = options.idempotencyKey;
+        }
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: options.method ?? "GET",
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        });
+        const raw = await response.text();
+        const parsed = raw ? JSON.parse(raw) : null;
+        if (!response.ok) {
+            const message = parsed?.error?.message ?? parsed?.message ?? `Request failed (${response.status})`;
+            throw new Error(message);
+        }
+        return parsed;
+    }
+}

package/dist/config.js

@@ -0,0 +1,69 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+function configDir() {
+    return path.join(os.homedir(), ".taskmanager-cli");
+}
+function configPath() {
+    return path.join(configDir(), "config.json");
+}
+export async function loadConfig() {
+    try {
+        const raw = await readFile(configPath(), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export async function saveConfig(next) {
+    await mkdir(configDir(), { recursive: true });
+    await writeFile(configPath(), JSON.stringify(next, null, 2), "utf8");
+}
+export async function clearToken() {
+    const cfg = await loadConfig();
+    delete cfg.token;
+    await saveConfig(cfg);
+}
+export function defaultBaseUrl() {
+    return process.env.TASKMANAGER_BOT_BASE_URL ?? "http://127.0.0.1:3210";
+}
+function normalizeBaseUrl(input) {
+    return input.replace(/\/+$/, "");
+}
+function candidateSiteUrls() {
+    const candidates = [
+        process.env.TASKMANAGER_SITE_URL,
+        "https://wande.app",
+    ].filter((value) => Boolean(value && value.trim().length > 0));
+    return Array.from(new Set(candidates.map(normalizeBaseUrl)));
+}
+export async function resolveBotBaseUrl(explicitUrl, existingUrl) {
+    if (explicitUrl) {
+        return normalizeBaseUrl(explicitUrl);
+    }
+    if (existingUrl) {
+        return normalizeBaseUrl(existingUrl);
+    }
+    if (process.env.TASKMANAGER_BOT_BASE_URL) {
+        return normalizeBaseUrl(process.env.TASKMANAGER_BOT_BASE_URL);
+    }
+    for (const siteUrl of candidateSiteUrls()) {
+        try {
+            const response = await fetch(`${siteUrl}/api/cli/config`, {
+                method: "GET",
+            });
+            if (!response.ok) {
+                continue;
+            }
+            const json = (await response.json());
+            if (json.botBaseUrl && json.botBaseUrl.trim().length > 0) {
+                return normalizeBaseUrl(json.botBaseUrl);
+            }
+        }
+        catch {
+            // Ignore bootstrap failures and continue trying fallbacks.
+        }
+    }
+    return defaultBaseUrl();
+}

package/dist/index.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { randomUUID } from "node:crypto";
+import { BotApiClient } from "./client.js";
+import { clearToken, loadConfig, resolveBotBaseUrl, saveConfig } from "./config.js";
+import { printData } from "./output.js";
+async function getRuntime() {
+    const config = await loadConfig();
+    const baseUrl = await resolveBotBaseUrl(undefined, config.baseUrl);
+    const token = config.token;
+    if (!token) {
+        throw new Error("Not authenticated. Run: wande login <token>");
+    }
+    return {
+        config,
+        token,
+        client: new BotApiClient(baseUrl),
+    };
+}
+async function performLogin(token, explicitUrl) {
+    const current = await loadConfig();
+    const baseUrl = await resolveBotBaseUrl(explicitUrl, current.baseUrl);
+    await saveConfig({
+        ...current,
+        token,
+        baseUrl,
+    });
+    console.log(`Saved bot token (base URL: ${baseUrl})`);
+}
+const program = new Command();
+program.name("wande").description("Wande bot CLI");
+program
+    .command("login <token>")
+    .description("Save bot token and auto-resolve API URL")
+    .option("--url <baseUrl>")
+    .action(async (token, options) => {
+    await performLogin(token, options.url);
+});
+program
+    .command("whoami")
+    .description("Show authenticated bot identity")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request("/bot/auth/whoami", {
+        method: "POST",
+        token,
+        body: {},
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("logout")
+    .description("Remove saved bot token")
+    .action(async () => {
+    await clearToken();
+    console.log("Token removed");
+});
+program
+    .command("auth:login")
+    .description("Legacy alias for login")
+    .requiredOption("--token <token>")
+    .option("--url <baseUrl>")
+    .action(async (options) => {
+    await performLogin(options.token, options.url);
+});
+program.command("auth:logout").description("Legacy alias for logout").action(async () => {
+    await clearToken();
+    console.log("Token removed");
+});
+program.command("auth:whoami").description("Legacy alias for whoami").option("--json", "JSON output", false).action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request("/bot/auth/whoami", {
+        method: "POST",
+        token,
+        body: {},
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("tasks:list")
+    .option("--status <status>")
+    .option("--limit <limit>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const params = new URLSearchParams();
+    if (opts.status)
+        params.set("status", String(opts.status));
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    const suffix = params.toString() ? `?${params.toString()}` : "";
+    const res = await client.request(`/bot/tasks${suffix}`, {
+        token,
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("tasks:create")
+    .requiredOption("--title <title>")
+    .option("--content <content>")
+    .option("--project-id <projectId>")
+    .option("--status <status>")
+    .option("--idempotency-key <key>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request("/bot/tasks", {
+        method: "POST",
+        token,
+        idempotencyKey: opts.idempotencyKey ?? randomUUID(),
+        body: {
+            title: opts.title,
+            content: opts.content,
+            project_id: opts.projectId,
+            status: opts.status,
+        },
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("tasks:status")
+    .requiredOption("--id <taskId>")
+    .requiredOption("--status <status>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request(`/bot/tasks/${opts.id}/status`, {
+        method: "POST",
+        token,
+        body: { status: opts.status },
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("routines:list")
+    .option("--status <status>")
+    .option("--limit <limit>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const params = new URLSearchParams();
+    if (opts.status)
+        params.set("status", String(opts.status));
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    const suffix = params.toString() ? `?${params.toString()}` : "";
+    const res = await client.request(`/bot/routines${suffix}`, {
+        token,
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("routines:create")
+    .requiredOption("--title <title>")
+    .option("--content <content>")
+    .option("--project-id <projectId>")
+    .option("--status <status>")
+    .option("--idempotency-key <key>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request("/bot/routines", {
+        method: "POST",
+        token,
+        idempotencyKey: opts.idempotencyKey ?? randomUUID(),
+        body: {
+            title: opts.title,
+            content: opts.content,
+            project_id: opts.projectId,
+            status: opts.status,
+        },
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("routines:status")
+    .requiredOption("--id <routineId>")
+    .requiredOption("--status <status>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request(`/bot/routines/${opts.id}/status`, {
+        method: "POST",
+        token,
+        body: { status: opts.status },
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("projects:list")
+    .option("--limit <limit>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const params = new URLSearchParams();
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    const suffix = params.toString() ? `?${params.toString()}` : "";
+    const res = await client.request(`/bot/projects${suffix}`, {
+        token,
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("projects:create")
+    .requiredOption("--title <title>")
+    .option("--color <color>")
+    .option("--idempotency-key <key>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request("/bot/projects", {
+        method: "POST",
+        token,
+        idempotencyKey: opts.idempotencyKey ?? randomUUID(),
+        body: {
+            title: opts.title,
+            color: opts.color,
+        },
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("queue:list")
+    .option("--date <date>")
+    .option("--limit <limit>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const params = new URLSearchParams();
+    if (opts.date)
+        params.set("date", String(opts.date));
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    const suffix = params.toString() ? `?${params.toString()}` : "";
+    const res = await client.request(`/bot/queue${suffix}`, {
+        token,
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("queue:create")
+    .requiredOption("--date <date>")
+    .requiredOption("--entity-id <entityId>")
+    .requiredOption("--entity-type <entityType>")
+    .requiredOption("--title <title>")
+    .option("--project-id <projectId>")
+    .option("--description <description>")
+    .option("--status <status>", "new")
+    .option("--idempotency-key <key>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request("/bot/queue/instances", {
+        method: "POST",
+        token,
+        idempotencyKey: opts.idempotencyKey ?? randomUUID(),
+        body: {
+            date: opts.date,
+            instance: {
+                entity_id: opts.entityId,
+                entity_type: opts.entityType,
+                title: opts.title,
+                project_id: opts.projectId,
+                description: opts.description,
+                status: opts.status,
+            },
+        },
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program
+    .command("queue:status")
+    .requiredOption("--instance-id <instanceId>")
+    .requiredOption("--status <status>")
+    .option("--json", "JSON output", false)
+    .action(async (opts) => {
+    const { client, token } = await getRuntime();
+    const res = await client.request(`/bot/queue/instances/${opts.instanceId}/status`, {
+        method: "POST",
+        token,
+        body: { status: opts.status },
+    });
+    printData(res.data, Boolean(opts.json));
+});
+program.parseAsync().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/output.js

@@ -0,0 +1,17 @@
+export function printData(payload, asJson) {
+    if (asJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (Array.isArray(payload)) {
+        if (payload.length === 0) {
+            console.log("No items");
+            return;
+        }
+        for (const item of payload) {
+            console.log(JSON.stringify(item));
+        }
+        return;
+    }
+    console.log(JSON.stringify(payload, null, 2));
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@krl-grn/wande",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "wande": "./dist/index.js",
+    "tm": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "node --loader ts-node/esm src/index.ts"
+  },
+  "dependencies": {
+    "commander": "^14.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.20",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}