@vellumai/assistant 0.8.1 → 0.8.2

package/src/cli/commands/plugins.ts

@@ -0,0 +1,185 @@
+/**
+ * `assistant plugins` — manage external plugins installed under
+ * `<workspaceDir>/plugins/`.
+ *
+ * Gated by the `external-plugins` feature flag (see
+ * {@link ../../plugins/feature-gate}). Subcommands delegate the heavy
+ * lifting to dedicated modules under {@link ../lib}.
+ */
+
+import type { Command } from "commander";
+
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import {
+  DEFAULT_PLUGIN_REF,
+  installPlugin,
+  InvalidPluginNameError,
+  PluginAlreadyInstalledError,
+  PluginNotFoundError,
+} from "../lib/install-from-github.js";
+import { listInstalledPlugins } from "../lib/list-installed-plugins.js";
+import { registerCommand } from "../lib/register-command.js";
+import {
+  PluginNotInstalledError,
+  uninstallPlugin,
+} from "../lib/uninstall-plugin.js";
+import { getCliLogger } from "../logger.js";
+
+const log = getCliLogger("plugins");
+
+export function registerPluginsCommand(program: Command): void {
+  registerCommand(program, {
+    name: "plugins",
+    transport: "local",
+    description: "Manage external plugins",
+    build: (plugins) => {
+      plugins.addHelpText(
+        "after",
+        `
+Examples:
+  $ assistant plugins install simple-memory
+  $ assistant plugins install simple-memory --force
+  $ assistant plugins install simple-memory --ref my-feature-branch
+  $ assistant plugins list
+  $ assistant plugins list --json
+  $ assistant plugins uninstall simple-memory`,
+      );
+
+      plugins
+        .command("install <name>")
+        .description(
+          "Install a plugin from vellum-ai/vellum-assistant/experimental/plugins/<name>",
+        )
+        .option("--force", "Overwrite an existing install")
+        .option(
+          "--ref <ref>",
+          `Git ref to fetch from (default: ${DEFAULT_PLUGIN_REF})`,
+        )
+        .action(async (name: string, opts: { force?: boolean; ref?: string }) => {
+          try {
+            const result = await installPlugin(
+              {
+                name,
+                force: opts.force ?? false,
+                ref: opts.ref ?? DEFAULT_PLUGIN_REF,
+              },
+              { fetch: globalThis.fetch.bind(globalThis) },
+            );
+            log.info(
+              {
+                name: result.name,
+                target: result.target,
+                fileCount: result.fileCount,
+                ref: result.ref,
+              },
+              "external plugin installed",
+            );
+            console.log(
+              `Installed plugin "${result.name}" (${result.fileCount} file${result.fileCount === 1 ? "" : "s"}) → ${result.target}`,
+            );
+            console.log("Restart the assistant to pick up the new plugin.");
+          } catch (err) {
+            if (err instanceof PluginAlreadyInstalledError) {
+              console.error(`${err.message}\nPass --force to overwrite.`);
+              process.exitCode = 1;
+              return;
+            }
+            if (err instanceof PluginNotFoundError) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin install failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+
+      plugins
+        .command("list")
+        .description("List plugins installed under <workspaceDir>/plugins/")
+        .option("--json", "Emit machine-readable JSON instead of a table")
+        .action((opts: { json?: boolean }) => {
+          const installed = listInstalledPlugins();
+
+          if (opts.json) {
+            process.stdout.write(JSON.stringify(installed, null, 2) + "\n");
+            return;
+          }
+
+          if (installed.length === 0) {
+            console.log("No plugins installed.");
+            return;
+          }
+
+          const rows = installed.map((p) => ({
+            name: p.name,
+            version: p.packageJson?.version ?? "—",
+            status: p.issues.length === 0 ? "ok" : p.issues.join("; "),
+          }));
+          const nameW = Math.max(4, ...rows.map((r) => r.name.length));
+          const versionW = Math.max(7, ...rows.map((r) => r.version.length));
+          const pad = (s: string, w: number) => s + " ".repeat(w - s.length);
+          console.log(
+            `${pad("NAME", nameW)}  ${pad("VERSION", versionW)}  STATUS`,
+          );
+          for (const r of rows) {
+            console.log(
+              `${pad(r.name, nameW)}  ${pad(r.version, versionW)}  ${r.status}`,
+            );
+          }
+          console.log("");
+          console.log(
+            `${installed.length} plugin${installed.length === 1 ? "" : "s"} installed.`,
+          );
+        });
+
+      plugins
+        .command("uninstall <name>")
+        .description("Remove a plugin from <workspaceDir>/plugins/<name>/")
+        .option("--force", "Skip the confirmation prompt")
+        .action(async (name: string, opts: { force?: boolean }) => {
+          try {
+            if (!opts.force) {
+              const result = await confirmPrompt({
+                question: `Uninstall plugin "${name}"? [y/N] `,
+                isTTY: Boolean(process.stdin.isTTY),
+                refuseNonInteractiveMessage: `Refusing to uninstall "${name}" non-interactively. Pass --force to confirm.`,
+              });
+              if (result === "non-interactive") {
+                process.exitCode = 1;
+                return;
+              }
+              if (result === "denied") {
+                console.log("Uninstall cancelled.");
+                return;
+              }
+            }
+            const result = uninstallPlugin({ name });
+            log.info(
+              { name: result.name, target: result.target },
+              "external plugin uninstalled",
+            );
+            console.log(
+              `Uninstalled plugin "${result.name}" from ${result.target}`,
+            );
+            console.log("Restart the assistant to drop the plugin.");
+          } catch (err) {
+            if (err instanceof InvalidPluginNameError) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            if (err instanceof PluginNotInstalledError) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin uninstall failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+    },
+  });
+}

package/src/cli/commands/schedules.ts

@@ -0,0 +1,391 @@
+import type { Command } from "commander";
+
+import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { registerCommand } from "../lib/register-command.js";
+import { log } from "../logger.js";
+import { writeOutput } from "../output.js";
+
+interface ScheduleRecord {
+  id: string;
+  name: string;
+  enabled: boolean;
+  syntax: string;
+  expression: string | null;
+  cronExpression: string | null;
+  timezone: string | null;
+  message: string;
+  script: string | null;
+  nextRunAt: number;
+  lastRunAt: number | null;
+  lastStatus: string | null;
+  retryCount: number;
+  maxRetries: number;
+  retryBackoffMs: number;
+  description: string | null;
+  mode: string;
+  status: string;
+  routingIntent: string;
+  reuseConversation: boolean;
+  wakeConversationId: string | null;
+  isOneShot: boolean;
+}
+
+interface ListSchedulesResponse {
+  schedules: ScheduleRecord[];
+}
+
+interface ScheduleRunRecord {
+  id: string;
+  jobId: string;
+  status: string;
+  startedAt: number;
+  finishedAt: number | null;
+  durationMs: number | null;
+  output: string | null;
+  error: string | null;
+  conversationId: string | null;
+  createdAt: number;
+}
+
+interface ListScheduleRunsResponse {
+  runs: ScheduleRunRecord[];
+}
+
+export function registerSchedulesCommand(program: Command): void {
+  registerCommand(program, {
+    name: "schedules",
+    transport: "ipc",
+    description: "Manage scheduled jobs",
+    build: (schedules) => {
+      schedules.addHelpText(
+        "after",
+        `
+Schedules are recurring or one-shot jobs run by the assistant daemon.
+
+This CLI namespace is intentionally landing incrementally. Today it supports
+listing schedules, viewing recent run history, and manually executing a schedule
+one time; create, delete, enable/disable, and run inspection will follow as
+separate slices.
+
+Examples:
+  $ assistant schedules list
+  $ assistant schedules list --all
+  $ assistant schedules runs <schedule-id>
+  $ assistant schedules runs <schedule-id> --limit 25 --json
+  $ assistant schedules execute <schedule-id>`,
+      );
+
+      schedules
+        .command("list")
+        .description("List assistant schedules")
+        .option(
+          "--all",
+          "Include deferred schedules that are hidden by default",
+        )
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  --all    Include deferred schedules that are normally hidden.
+  --json   Output the raw schedule list as compact JSON.
+
+Examples:
+  $ assistant schedules list
+  $ assistant schedules list --all
+  $ assistant schedules list --json`,
+        )
+        .action(
+          async (opts: { all?: boolean; json?: boolean }, cmd: Command) => {
+            const queryParams: Record<string, string> = {};
+            if (opts.all) queryParams.include_all = "true";
+
+            const result = await cliIpcCall<ListSchedulesResponse>(
+              "listSchedules",
+              { queryParams },
+            );
+
+            if (!result.ok) {
+              if (opts.json) {
+                writeOutput(cmd, { ok: false, error: result.error });
+              } else {
+                log.error(result.error ?? "Failed to list schedules");
+              }
+              process.exitCode = 1;
+              return;
+            }
+
+            const response = result.result ?? { schedules: [] };
+            const entries = [...response.schedules].sort(
+              (a, b) => a.nextRunAt - b.nextRunAt,
+            );
+
+            if (opts.json) {
+              writeOutput(cmd, { schedules: entries });
+              return;
+            }
+
+            if (entries.length === 0) {
+              log.info("No schedules found.");
+              return;
+            }
+
+            const rows = entries.map((schedule) => ({
+              id: schedule.id,
+              name: schedule.name,
+              enabled: schedule.enabled ? "enabled" : "disabled",
+              mode: schedule.mode,
+              schedule: describeSchedule(schedule),
+              nextRun: formatTimestamp(schedule.nextRunAt),
+              lastStatus: schedule.lastStatus ?? "—",
+            }));
+
+            const headers = [
+              "ID",
+              "NAME",
+              "ENABLED",
+              "MODE",
+              "SCHEDULE",
+              "NEXT RUN",
+              "LAST STATUS",
+            ];
+            const widths = [
+              headers[0].length,
+              headers[1].length,
+              headers[2].length,
+              headers[3].length,
+              headers[4].length,
+              headers[5].length,
+              headers[6].length,
+            ];
+
+            for (const row of rows) {
+              widths[0] = Math.max(widths[0], row.id.length);
+              widths[1] = Math.max(widths[1], row.name.length);
+              widths[2] = Math.max(widths[2], row.enabled.length);
+              widths[3] = Math.max(widths[3], row.mode.length);
+              widths[4] = Math.max(widths[4], row.schedule.length);
+              widths[5] = Math.max(widths[5], row.nextRun.length);
+              widths[6] = Math.max(widths[6], row.lastStatus.length);
+            }
+
+            const pad = (value: string, width: number) => value.padEnd(width);
+            log.info(
+              headers
+                .map((header, index) => pad(header, widths[index]!))
+                .join("  "),
+            );
+            log.info(widths.map((width) => "─".repeat(width)).join("  "));
+            for (const row of rows) {
+              log.info(
+                [
+                  row.id,
+                  row.name,
+                  row.enabled,
+                  row.mode,
+                  row.schedule,
+                  row.nextRun,
+                  row.lastStatus,
+                ]
+                  .map((value, index) => pad(value, widths[index]!))
+                  .join("  "),
+              );
+            }
+          },
+        );
+
+      schedules
+        .command("runs <id>")
+        .description("List recent runs for a schedule")
+        .option("--limit <count>", "Max runs to return (default 10, max 100)")
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  --limit <count>   Max runs to return. The daemon clamps values to 1-100.
+  --json            Output the raw run list as compact JSON.
+
+Arguments:
+  <id>   Schedule ID (UUID) — run 'assistant schedules list' to find it.
+
+Examples:
+  $ assistant schedules runs 9f2c4f3a-3f1a-41e4-88e7-abc123
+  $ assistant schedules runs 9f2c4f3a-3f1a-41e4-88e7-abc123 --limit 25
+  $ assistant schedules runs 9f2c4f3a-3f1a-41e4-88e7-abc123 --json`,
+        )
+        .action(
+          async (
+            id: string,
+            opts: { limit?: string; json?: boolean },
+            cmd: Command,
+          ) => {
+            const scheduleId = id.trim();
+            const queryParams: Record<string, string> = {};
+            if (opts.limit != null) queryParams.limit = opts.limit;
+
+            const result = await cliIpcCall<ListScheduleRunsResponse>(
+              "listScheduleRuns",
+              { pathParams: { id: scheduleId }, queryParams },
+            );
+
+            if (!result.ok) return exitFromIpcResult(result, cmd);
+
+            const response = result.result ?? { runs: [] };
+            if (opts.json) {
+              writeOutput(cmd, response);
+              return;
+            }
+
+            const runs = response.runs;
+            if (runs.length === 0) {
+              log.info(`No runs found for schedule ${scheduleId}.`);
+              return;
+            }
+
+            const rows = runs.map((run) => ({
+              id: run.id,
+              status: run.status,
+              startedAt: formatTimestamp(run.startedAt),
+              finishedAt: formatNullableTimestamp(run.finishedAt),
+              duration: formatDuration(run.durationMs),
+              conversation: run.conversationId ?? "—",
+              error: run.error ?? "—",
+            }));
+
+            const headers = [
+              "ID",
+              "STATUS",
+              "STARTED",
+              "FINISHED",
+              "DURATION",
+              "CONVERSATION",
+              "ERROR",
+            ];
+            const widths = [
+              headers[0].length,
+              headers[1].length,
+              headers[2].length,
+              headers[3].length,
+              headers[4].length,
+              headers[5].length,
+              headers[6].length,
+            ];
+
+            for (const row of rows) {
+              widths[0] = Math.max(widths[0], row.id.length);
+              widths[1] = Math.max(widths[1], row.status.length);
+              widths[2] = Math.max(widths[2], row.startedAt.length);
+              widths[3] = Math.max(widths[3], row.finishedAt.length);
+              widths[4] = Math.max(widths[4], row.duration.length);
+              widths[5] = Math.max(widths[5], row.conversation.length);
+              widths[6] = Math.max(widths[6], row.error.length);
+            }
+
+            const pad = (value: string, width: number) => value.padEnd(width);
+            log.info(
+              headers
+                .map((header, index) => pad(header, widths[index]!))
+                .join("  "),
+            );
+            log.info(widths.map((width) => "─".repeat(width)).join("  "));
+            for (const row of rows) {
+              log.info(
+                [
+                  row.id,
+                  row.status,
+                  row.startedAt,
+                  row.finishedAt,
+                  row.duration,
+                  row.conversation,
+                  row.error,
+                ]
+                  .map((value, index) => pad(value, widths[index]!))
+                  .join("  "),
+              );
+            }
+          },
+        );
+
+      schedules
+        .command("execute <id>")
+        .description("Execute a schedule one time immediately")
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  --json   Output the run-now result as compact JSON.
+
+Arguments:
+  <id>   Schedule ID (UUID) — run 'assistant schedules list' to find it.
+
+Examples:
+  $ assistant schedules execute 9f2c4f3a-3f1a-41e4-88e7-abc123
+  $ assistant schedules execute 9f2c4f3a-3f1a-41e4-88e7-abc123 --json`,
+        )
+        .action(async (id: string, opts: { json?: boolean }, cmd: Command) => {
+          const scheduleId = id.trim();
+          if (!scheduleId) {
+            const error = "Schedule ID is required";
+            if (opts.json) {
+              writeOutput(cmd, { ok: false, error });
+            } else {
+              log.error(error);
+            }
+            process.exitCode = 1;
+            return;
+          }
+
+          const result = await cliIpcCall<ListSchedulesResponse>(
+            "runScheduleNow",
+            { pathParams: { id: scheduleId } },
+          );
+
+          if (!result.ok) return exitFromIpcResult(result, cmd);
+
+          const response = result.result ?? { schedules: [] };
+          const schedule = response.schedules.find(
+            (entry) => entry.id === scheduleId,
+          );
+
+          if (opts.json) {
+            writeOutput(cmd, response);
+            return;
+          }
+
+          if (schedule) {
+            log.info(`Executed schedule: ${schedule.name} (${schedule.id})`);
+            if (schedule.lastStatus) {
+              log.info(`Last status: ${schedule.lastStatus}`);
+            }
+            return;
+          }
+
+          log.info(`Executed schedule: ${scheduleId}`);
+        });
+    },
+  });
+}
+
+function describeSchedule(schedule: ScheduleRecord): string {
+  if (schedule.isOneShot) return "one-shot";
+  const expression = schedule.description ?? schedule.expression ?? "—";
+  return schedule.timezone
+    ? `${expression} (${schedule.timezone})`
+    : expression;
+}
+
+function formatTimestamp(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return "—";
+  return new Date(value).toISOString();
+}
+
+function formatNullableTimestamp(value: number | null): string {
+  return value == null ? "—" : formatTimestamp(value);
+}
+
+function formatDuration(value: number | null): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  return `${value}ms`;
+}

package/src/cli/commands/telemetry.ts

@@ -0,0 +1,40 @@
+import type { Command } from "commander";
+
+import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { registerCommand } from "../lib/register-command.js";
+import { log } from "../logger.js";
+
+export function registerTelemetryCommand(program: Command): void {
+  registerCommand(program, {
+    name: "telemetry",
+    transport: "ipc",
+    description: "Manage telemetry reporting",
+    build: (telemetry) => {
+      telemetry
+        .command("flush")
+        .description(
+          "Force-flush all pending telemetry events to the platform",
+        )
+        .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+          const r = await cliIpcCall<
+            { flushed: true } | { flushed: false; reason: string }
+          >("telemetry_flush", {});
+          if (!r.ok)
+            return exitFromIpcResult({
+              ok: false,
+              error: r.error,
+              statusCode: r.statusCode,
+            }, cmd);
+
+          const result = r.result!;
+          if (result.flushed) {
+            log.info("Telemetry flushed successfully.");
+          } else {
+            log.info(
+              `Telemetry flush skipped: ${result.reason}`,
+            );
+          }
+        });
+    },
+  });
+}

package/src/cli/lib/__tests__/cli-colors.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { red } from "../cli-colors.js";
+
+const originalIsTTY = process.stderr.isTTY;
+const originalNoColor = process.env.NO_COLOR;
+
+function setTTY(value: boolean): void {
+  Object.defineProperty(process.stderr, "isTTY", {
+    configurable: true,
+    value,
+  });
+}
+
+describe("red", () => {
+  afterEach(() => {
+    setTTY(originalIsTTY);
+    if (originalNoColor === undefined) {
+      delete process.env.NO_COLOR;
+    } else {
+      process.env.NO_COLOR = originalNoColor;
+    }
+  });
+
+  it("returns plain text when stderr is not a TTY", () => {
+    setTTY(false);
+    delete process.env.NO_COLOR;
+    expect(red("oops")).toBe("oops");
+  });
+
+  it("wraps text in ANSI red when stderr is a TTY", () => {
+    setTTY(true);
+    delete process.env.NO_COLOR;
+    expect(red("oops")).toBe("\x1b[31moops\x1b[0m");
+  });
+
+  it("respects NO_COLOR even when stderr is a TTY", () => {
+    setTTY(true);
+    process.env.NO_COLOR = "1";
+    expect(red("oops")).toBe("oops");
+  });
+
+  it("treats an empty NO_COLOR as unset (per no-color.org)", () => {
+    setTTY(true);
+    process.env.NO_COLOR = "";
+    expect(red("oops")).toBe("\x1b[31moops\x1b[0m");
+  });
+});