@vellumai/assistant 0.8.1 → 0.8.2

package/src/cli/lib/list-installed-plugins.ts

@@ -0,0 +1,137 @@
+/**
+ * Enumerate plugins materialized under `<workspaceDir>/plugins/`.
+ *
+ * The CLI command `assistant plugins list` is a thin wrapper. Downstream
+ * callers (the daemon's diagnostics surface, a future TUI, scripted
+ * audits) can call {@link listInstalledPlugins} directly without going
+ * through commander.
+ *
+ * Designed to be lenient: a malformed `package.json` is reported as an
+ * error on that one entry rather than failing the whole listing. The
+ * daemon makes the same call on boot via `external-plugin-loader.ts`
+ * and we want both surfaces to agree on what's present.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+
+/** Minimal manifest fields surfaced to the CLI. */
+export interface PluginPackageMetadata {
+  readonly name?: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly peerDependencies?: Record<string, string>;
+}
+
+/** One installed plugin entry. */
+export interface InstalledPluginInfo {
+  /** Directory name under `<workspaceDir>/plugins/`. */
+  readonly name: string;
+  /** Absolute path to the plugin directory. */
+  readonly target: string;
+  /** Parsed `package.json` content, when present and parseable. */
+  readonly packageJson: PluginPackageMetadata | null;
+  /**
+   * Non-fatal issues with this entry (missing `package.json`, malformed
+   * JSON, unexpected type, etc.). Empty when the entry parses cleanly.
+   */
+  readonly issues: readonly string[];
+}
+
+/** Options accepted by {@link listInstalledPlugins}. */
+export interface ListInstalledPluginsOptions {
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/**
+ * Return one entry per directory under the workspace plugins directory,
+ * sorted alphabetically by name. Hidden entries (`.`-prefixed) and
+ * non-directory entries are skipped silently — the daemon's loader does
+ * the same. Returns `[]` if the plugins directory does not exist.
+ */
+export function listInstalledPlugins(
+  opts: ListInstalledPluginsOptions = {},
+): InstalledPluginInfo[] {
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  if (!existsSync(pluginsDir)) return [];
+
+  const entries = readdirSync(pluginsDir, { withFileTypes: true })
+    .filter((e) => !e.name.startsWith("."))
+    .filter((e) => {
+      if (e.isDirectory()) return true;
+      if (!e.isSymbolicLink()) return false;
+      // Resolve the symlink and only keep it if it points to a directory.
+      try {
+        return statSync(join(pluginsDir, e.name)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .map((e) => e.name)
+    .sort();
+
+  return entries.map((name) => readPluginEntry(pluginsDir, name));
+}
+
+function readPluginEntry(
+  pluginsDir: string,
+  name: string,
+): InstalledPluginInfo {
+  const target = join(pluginsDir, name);
+  const pkgJsonPath = join(target, "package.json");
+  const issues: string[] = [];
+
+  if (!existsSync(pkgJsonPath)) {
+    issues.push("missing package.json");
+    return { name, target, packageJson: null, issues };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(pkgJsonPath, "utf8");
+  } catch (err) {
+    issues.push(
+      `package.json unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { name, target, packageJson: null, issues };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    issues.push(
+      `package.json invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { name, target, packageJson: null, issues };
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    issues.push("package.json is not an object");
+    return { name, target, packageJson: null, issues };
+  }
+
+  const meta = parsed as Record<string, unknown>;
+  const packageJson: PluginPackageMetadata = {
+    name: typeof meta.name === "string" ? meta.name : undefined,
+    version: typeof meta.version === "string" ? meta.version : undefined,
+    description:
+      typeof meta.description === "string" ? meta.description : undefined,
+    peerDependencies:
+      typeof meta.peerDependencies === "object" &&
+      meta.peerDependencies !== null &&
+      !Array.isArray(meta.peerDependencies)
+        ? (meta.peerDependencies as Record<string, string>)
+        : undefined,
+  };
+
+  return { name, target, packageJson, issues };
+}

package/src/cli/lib/uninstall-plugin.ts

@@ -0,0 +1,82 @@
+/**
+ * Remove a plugin previously materialized under `<workspaceDir>/plugins/`.
+ *
+ * Symmetric to {@link ./install-from-github.installPlugin}. The CLI
+ * command `assistant plugins uninstall <name>` is a thin wrapper that
+ * supplies the live workspace directory and formats the result.
+ *
+ * The operation is destructive — a successful return means the plugin
+ * directory and everything beneath it have been removed from disk.
+ * Callers needing a confirmation prompt should run it before invoking
+ * this function (the CLI command does this via `--force`).
+ */
+
+import { existsSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  InvalidPluginNameError,
+  sanitizePluginName,
+} from "./install-from-github.js";
+
+/** Plugin is not present in the workspace plugins directory. */
+export class PluginNotInstalledError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly target: string,
+  ) {
+    super(`Plugin "${pluginName}" is not installed at ${target}.`);
+    this.name = "PluginNotInstalledError";
+  }
+}
+
+/** Options accepted by {@link uninstallPlugin}. */
+export interface UninstallPluginOptions {
+  readonly name: string;
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/** Result of a successful uninstall. */
+export interface UninstallPluginResult {
+  readonly name: string;
+  /** Absolute path that was removed. */
+  readonly target: string;
+}
+
+/**
+ * Validate the name, confirm the plugin exists, then recursively remove
+ * the install target. Throws {@link InvalidPluginNameError} if the name
+ * fails sanitization or {@link PluginNotInstalledError} if no directory
+ * (or symlink to a directory) is present at the resolved target.
+ *
+ * The name check is performed up front so an attacker-supplied
+ * `../../etc/passwd` style argument never reaches `rmSync` — even
+ * though commander typically prevents it at the argv level, defense in
+ * depth.
+ */
+export function uninstallPlugin(
+  opts: UninstallPluginOptions,
+): UninstallPluginResult {
+  const name = sanitizePluginName(opts.name);
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const target = join(pluginsDir, name);
+
+  if (!existsSync(target)) {
+    throw new PluginNotInstalledError(name, target);
+  }
+
+  // `existsSync` follows symlinks; guard against a stray file with the
+  // plugin's name (which would be surprising rather than dangerous —
+  // we'd refuse to delete it).
+  const stats = statSync(target);
+  if (!stats.isDirectory()) {
+    throw new PluginNotInstalledError(name, target);
+  }
+
+  rmSync(target, { recursive: true, force: true });
+  return { name, target };
+}
+
+export { InvalidPluginNameError };

package/src/cli/lib/unknown-command.ts

@@ -0,0 +1,111 @@
+import type { Command } from "commander";
+
+/**
+ * Result of detecting an unknown top-level subcommand. `suggestion` is set
+ * when a near-match is found (Levenshtein distance ≤ 40% of the longer name).
+ */
+export interface UnknownCommandHit {
+  readonly token: string;
+  readonly suggestion?: string;
+}
+
+/**
+ * Collect every top-level subcommand name and alias registered on `program`.
+ */
+export function knownCommandNames(program: Command): Set<string> {
+  const names = new Set<string>();
+  for (const cmd of program.commands) {
+    names.add(cmd.name());
+    for (const alias of cmd.aliases()) {
+      names.add(alias);
+    }
+  }
+  return names;
+}
+
+/**
+ * Pre-parse scan: returns the first positional argv token that doesn't match
+ * any known subcommand/alias, or null when the args look valid.
+ *
+ * Commander processes `--help` / `--version` before any action or hook runs,
+ * so `assistant invalid --help` would otherwise dump the root help instead of
+ * surfacing the unknown command. Callers should run this before `parse()` so
+ * the error wins over the help short-circuit.
+ *
+ * The first non-flag token is treated as the subcommand candidate. Flags are
+ * skipped wholesale; the root program has no value-taking options today.
+ */
+export function detectUnknownCommand(
+  program: Command,
+  argv: readonly string[],
+): UnknownCommandHit | null {
+  const firstPositional = argv.find((token) => !token.startsWith("-"));
+  if (!firstPositional) return null;
+
+  const known = knownCommandNames(program);
+  if (known.has(firstPositional)) return null;
+
+  const suggestion = findClosestCommand(firstPositional, [...known]);
+  return suggestion ? { token: firstPositional, suggestion } : { token: firstPositional };
+}
+
+/**
+ * Format the unknown-command error as a multi-line message. Kept as a pure
+ * function so it can be reused by `default-action`'s in-parse path (when the
+ * user runs `assistant invalid` with no `--help`) and by the pre-parse path.
+ */
+export function formatUnknownCommandMessage(hit: UnknownCommandHit): string {
+  const lines = [`unknown command '${hit.token}'`];
+  if (hit.suggestion) {
+    lines.push(`(Did you mean '${hit.suggestion}'?)`);
+  }
+  lines.push(`Run 'assistant --help' to see a list of available commands.`);
+  return lines.join("\n");
+}
+
+/**
+ * Find the closest matching command name using Levenshtein distance.
+ * Returns the best match if the distance is ≤ 40% of the longer string's
+ * length, otherwise returns undefined.
+ */
+export function findClosestCommand(
+  input: string,
+  candidates: readonly string[],
+): string | undefined {
+  let best: string | undefined;
+  let bestDist = Infinity;
+  const lowered = input.toLowerCase();
+
+  for (const name of candidates) {
+    const dist = levenshtein(lowered, name.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = name;
+    }
+  }
+
+  const maxLen = Math.max(input.length, best?.length ?? 0);
+  if (best && bestDist <= Math.ceil(maxLen * 0.4)) {
+    return best;
+  }
+  return undefined;
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    Array(n + 1).fill(0),
+  );
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}

package/src/cli/program.ts

@@ -5,6 +5,7 @@ import { Command } from "commander";
 import { initFeatureFlagOverrides } from "../config/assistant-feature-flags.js";
 import { getConfigReadOnly } from "../config/loader.js";
 import { isEmailEnabled } from "../email/feature-gate.js";
+import { isExternalPluginsEnabled } from "../plugins/feature-gate.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { APP_VERSION } from "../version.js";
 import { registerAttachmentCommand } from "./commands/attachment.js";
@@ -37,18 +38,22 @@ import { registerNotificationsCommand } from "./commands/notifications.js";
 import { registerOAuthCommand } from "./commands/oauth/index.js";
 import { registerPendingCommand } from "./commands/pending.js";
 import { registerPlatformCommand } from "./commands/platform/index.js";
+import { registerPluginsCommand } from "./commands/plugins.js";
 import { registerRoutesCommand } from "./commands/routes.js";
+import { registerSchedulesCommand } from "./commands/schedules.js";
 import { registerSequenceCommand } from "./commands/sequence.js";
 import { registerSkillsCommand } from "./commands/skills.js";
 import { registerStatusCommand } from "./commands/status.js";
 import { registerSttCommand } from "./commands/stt.js";
 import { registerTaskCommand } from "./commands/task.js";
+import { registerTelemetryCommand } from "./commands/telemetry.js";
 import { registerTrustCommand } from "./commands/trust.js";
 import { registerTtsCommand } from "./commands/tts.js";
 import { registerUiCommand } from "./commands/ui.js";
 import { registerUsageCommand } from "./commands/usage.js";
 import { registerWatchersCommand } from "./commands/watchers.js";
 import { registerWebhooksCommand } from "./commands/webhooks.js";
+import { red } from "./lib/cli-colors.js";
 import { log } from "./logger.js";
 
 /**
@@ -65,6 +70,13 @@ export async function buildCliProgram(): Promise<Command> {
     .version(APP_VERSION)
     .allowExcessArguments(true);
 
+  // Color Commander-emitted error output red (unknown options, missing args,
+  // cmd.error() calls). Plain success output and --help text are untouched.
+  // The `red` helper is a no-op when stderr isn't a TTY or NO_COLOR is set.
+  program.configureOutput({
+    outputError: (str, write) => write(red(str)),
+  });
+
   program.addHelpText(
     "after",
     `
@@ -107,12 +119,17 @@ Examples:
   registerOAuthCommand(program);
   registerPendingCommand(program);
   registerPlatformCommand(program);
+  if (isExternalPluginsEnabled(getConfigReadOnly())) {
+    registerPluginsCommand(program);
+  }
   registerRoutesCommand(program);
+  registerSchedulesCommand(program);
   registerSequenceCommand(program);
   registerStatusCommand(program);
   registerSkillsCommand(program);
   registerSttCommand(program);
   registerTaskCommand(program);
+  registerTelemetryCommand(program);
   registerTrustCommand(program);
   registerTtsCommand(program);
   registerUiCommand(program);
@@ -126,9 +143,28 @@ Examples:
   // remain available even without a workspace.
   // Workspace-independent commands are exempt:
   //   completions — pure shell-script generation, no workspace files needed
-  const workspaceExemptCommands = new Set(["completions", "status"]);
+  //   status     — diagnostic; should run even when the workspace is broken
+  //   changelog  — pure read-only network surface backed by GitHub Releases;
+  //                its on-disk cache is best-effort and tolerates a missing
+  //                workspace dir (see changelog.ts:writeCache)
+  const workspaceExemptCommands = new Set([
+    "completions",
+    "status",
+    "changelog",
+  ]);
+  // An action command's `.name()` returns the leaf (e.g. "show" for
+  // `changelog show <ver>`), so we walk up the parent chain to see whether
+  // any ancestor — typically the top-level subcommand — is exempt.
+  const isExemptFromWorkspaceCheck = (command: Command): boolean => {
+    let current: Command | null | undefined = command;
+    while (current && current !== program) {
+      if (workspaceExemptCommands.has(current.name())) return true;
+      current = current.parent;
+    }
+    return false;
+  };
   program.hook("preAction", (_thisCommand, actionCommand) => {
-    if (workspaceExemptCommands.has(actionCommand.name())) {
+    if (isExemptFromWorkspaceCheck(actionCommand)) {
       return;
     }
     const workspaceDir = getWorkspaceDir();

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -177,27 +177,31 @@ useEffect(() => {
 }, []);
 ```
 
-**File workflow:** Call `app_create` first to create the app record and scaffold, use `file_write` for each source file under `src/`, then call `app_refresh` once to compile and refresh the UI.
+**File workflow:** Pass all source files inline via the `source_files` parameter of `app_create`. This writes and compiles the real app in a single call — no scaffold placeholder, no separate `file_write` or `app_refresh` needed for initial creation. For subsequent edits, use `file_edit`/`file_write` then call `app_refresh` once.
 
 **Allowed third-party packages:** `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`, `lucide`. Import them directly - esbuild resolves them at build time. No CDN imports. Note: `lucide` is the vanilla JS icon library (not `lucide-react`). Use its `createElement` or `createIcons` API, or manually inline SVG - do not import JSX icon components.
 
-**Example - creating a multi-file project** (assuming app slug is `project-tracker`):
+**Example - creating a multi-file project:**
 
 ```
-file_write("{workspaceDir}/data/apps/project-tracker/src/index.html", `<!DOCTYPE html>
+app_create({
+  name: "Project Tracker",
+  description: "Track projects with status and priority",
+  schema_json: '{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string"}},"required":["title"]}',
+  preview: { title: "Project Tracker", icon: "📋" },
+  source_files: {
+    "src/index.html": `<!DOCTYPE html>
 <html lang="en">
 <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Project Tracker</title></head>
 <body><div id="app"></div></body>
-</html>`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/main.tsx", `import { render } from 'preact';
+</html>`,
+    "src/main.tsx": `import { render } from 'preact';
 import { App } from './components/App';
 import './styles.css';
 
-render(<App />, document.getElementById('app')!);`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/components/App.tsx", `import { FunctionComponent } from 'preact';
+render(<App />, document.getElementById('app')!);`,
+    "src/components/App.tsx": `import { FunctionComponent } from 'preact';
 import { useState, useEffect } from 'preact/hooks';
 import { Header } from './Header';
 
@@ -217,9 +221,8 @@ export const App: FunctionComponent = () => {
       {/* ... */}
     </div>
   );
-};`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/components/Header.tsx", `import { FunctionComponent } from 'preact';
+};`,
+    "src/components/Header.tsx": `import { FunctionComponent } from 'preact';
 
 interface HeaderProps {
   title: string;
@@ -231,14 +234,12 @@ export const Header: FunctionComponent<HeaderProps> = ({ title, count }) => (
     <h1>{title}</h1>
     <span className="badge">{count} items</span>
   </header>
-);`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/styles.css", `.app { padding: var(--v-spacing-lg); }
+);`,
+    "src/styles.css": `.app { padding: var(--v-spacing-lg); }
 .header { display: flex; justify-content: space-between; align-items: center; }
-.badge { background: var(--v-accent); color: var(--v-aux-white); padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`)
-
-# After all files are written, compile and refresh:
-app_refresh(app_id)
+.badge { background: var(--v-accent); color: var(--v-aux-white); padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`
+  }
+})
 ```
 
 **Technical constraints (multi-file):**
@@ -329,10 +330,11 @@ Call `app_create` with:
 - `name`: Short descriptive name
 - `description`: One-sentence summary
 - `schema_json`: JSON schema as string
-- `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat
+- `source_files`: Map of relative file paths to contents (e.g. `{"src/main.tsx": "...", "src/styles.css": "..."}`). **Always include this** with the complete app source — it writes, compiles, and opens the real app in a single call.
+- `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat after the app is built. Only fires when real source files are provided (not for scaffold-only apps).
 - `preview`: Always include - `title` (required), `subtitle`, `description`, `icon` (image URL preferred, emoji fallback), `metrics` (up to 3 key-value pills)
 
-Do not pass `html` or `pages` to `app_create`; those single-file shortcuts are retired. After `app_create` returns the app ID, write the real app source under `src/` and call `app_refresh`.
+Do not pass `html` or `pages` to `app_create`; those single-file shortcuts are retired.
 
 The app is NOT opened in a workspace panel automatically - users open it via the 'Open App' button on the inline card.
 

package/src/config/bundled-skills/app-builder/TOOLS.json

@@ -64,6 +64,13 @@
             },
             "required": ["title"]
           },
+          "source_files": {
+            "type": "object",
+            "description": "Map of file paths to file contents to write under the app directory. Supply the real app source here instead of making separate file_write calls. Paths are relative to the app directory (e.g. 'src/main.tsx', 'src/components/App.tsx', 'src/styles.css'). When src/main.tsx is included, no scaffold placeholder is created and the app compiles immediately with real content.",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: add coin flip app', 'fix: correct button alignment'). Used as the version history entry."