@vellumai/assistant 0.8.1 → 0.8.3

package/src/cli/commands/changelog.ts

@@ -43,9 +43,20 @@ interface GitHubRelease {
   prerelease: boolean;
 }
 
+/**
+ * Cache shape persisted under `<workspace>/data/changelog-cache.json`.
+ *
+ * - `recent` holds the most recent stable releases, capped at
+ *   `CACHE_STABLE_LIMIT`. TTL-gated via `fetchedAt`.
+ * - `byTag` is a content-addressed slot for single-tag lookups. Release
+ *   tags are immutable once published, so entries here are kept without a
+ *   TTL — first `show <tag>` populates, subsequent calls short-circuit
+ *   the fetch.
+ */
 interface CacheStore {
   fetchedAt: string;
-  releases: GitHubRelease[];
+  recent: GitHubRelease[];
+  byTag: Record<string, GitHubRelease>;
 }
 
 // ── Config ───────────────────────────────────────────────────────────
@@ -54,6 +65,19 @@ const REPO = "vellum-ai/vellum-assistant";
 const LIST_TTL_MS = 60 * 60 * 1000;
 const DEFAULT_LIST_LIMIT = 30;
 const MAX_LIST_LIMIT = 100;
+/**
+ * Maximum number of stable releases we persist in the rolling `recent` slot.
+ * Most callers only ever read the latest one or two; capping the cache keeps
+ * the file small and the network round-trip predictable.
+ */
+const CACHE_STABLE_LIMIT = 5;
+/**
+ * When fetching, request a page size that comfortably covers the caller's
+ * requested limit plus a small buffer to absorb the occasional draft or
+ * pre-release without forcing a second round-trip.
+ */
+const STABLE_BUFFER = 5;
+const MIN_FETCH_PAGE_SIZE = 30;
 const FETCH_TIMEOUT_MS = 10_000;
 const USER_AGENT = "vellum-assistant-cli";
 
@@ -72,7 +96,9 @@ function readCache(): CacheStore | null {
     ) as Partial<CacheStore>;
     if (
       typeof parsed.fetchedAt !== "string" ||
-      !Array.isArray(parsed.releases)
+      !Array.isArray(parsed.recent) ||
+      typeof parsed.byTag !== "object" ||
+      parsed.byTag === null
     ) {
       return null;
     }
@@ -122,8 +148,20 @@ function describeGithubError(status: number, body: string): string {
   return `GitHub API error ${status}: ${body || "(no body)"}`;
 }
 
+/**
+ * Compute the per-page size for a fetch that needs to cover `limit` stable
+ * releases. The buffer absorbs drafts/prereleases without paginating; we cap
+ * at `MAX_LIST_LIMIT` because that's GitHub's per-page maximum.
+ */
+function pageSizeFor(limit: number): number {
+  return Math.min(
+    MAX_LIST_LIMIT,
+    Math.max(limit + STABLE_BUFFER, MIN_FETCH_PAGE_SIZE),
+  );
+}
+
 async function fetchReleaseList(limit: number): Promise<GitHubRelease[]> {
-  const url = `https://api.github.com/repos/${REPO}/releases?per_page=${limit}`;
+  const url = `https://api.github.com/repos/${REPO}/releases?per_page=${pageSizeFor(limit)}`;
   const res = await githubFetch(url);
   if (!res.ok) {
     const text = await res.text().catch(() => "");
@@ -150,28 +188,72 @@ interface LoadOpts {
   limit: number;
 }
 
+/**
+ * Persist the rolling list of stable releases. Cap at `CACHE_STABLE_LIMIT`.
+ * Mirror each entry into `byTag` so single-tag lookups short-circuit fetches
+ * for any tag that appears in the rolling list. Preserves any existing
+ * tag-keyed entries (which never expire).
+ */
+function persistRecent(stable: GitHubRelease[]): void {
+  const previous = readCache();
+  const recent = stable.slice(0, CACHE_STABLE_LIMIT);
+  const byTag: Record<string, GitHubRelease> = { ...(previous?.byTag ?? {}) };
+  for (const r of recent) {
+    byTag[r.tag_name] = r;
+  }
+  writeCache({ fetchedAt: new Date().toISOString(), recent, byTag });
+}
+
+/**
+ * Persist a single tag fetched via `show <tag>`. Tags are immutable; this
+ * entry survives subsequent list refreshes.
+ */
+function persistByTag(release: GitHubRelease): void {
+  const previous = readCache();
+  writeCache({
+    fetchedAt: previous?.fetchedAt ?? new Date().toISOString(),
+    recent: previous?.recent ?? [],
+    byTag: { ...(previous?.byTag ?? {}), [release.tag_name]: release },
+  });
+}
+
+/**
+ * Returns up to `opts.limit` stable releases, newest first. Uses the cached
+ * rolling list when fresh and large enough; otherwise fetches a single page
+ * sized via `pageSizeFor` and filters stable. The cached rolling list is
+ * capped at `CACHE_STABLE_LIMIT` even if the caller asks for more.
+ */
 async function loadReleases(opts: LoadOpts): Promise<GitHubRelease[]> {
   if (!opts.noCache) {
     const cache = readCache();
-    if (cache && !isStale(cache) && cache.releases.length >= opts.limit) {
-      return cache.releases.slice(0, opts.limit);
+    if (cache && !isStale(cache) && cache.recent.length >= opts.limit) {
+      return cache.recent.slice(0, opts.limit);
     }
   }
-  const releases = await fetchReleaseList(opts.limit);
-  writeCache({ fetchedAt: new Date().toISOString(), releases });
-  return releases;
+  const raw = await fetchReleaseList(opts.limit);
+  const stable = stableReleases(raw);
+  persistRecent(stable);
+  return stable.slice(0, opts.limit);
 }
 
+/**
+ * Returns the release for a specific tag. Prefers the cached `byTag` slot
+ * (immutable, no TTL), then the rolling recent list, then the network.
+ * Persists fetched results into `byTag` so subsequent lookups short-circuit.
+ */
 async function loadReleaseByTag(
   tag: string,
   opts: { noCache: boolean },
 ): Promise<GitHubRelease | null> {
   if (!opts.noCache) {
     const cache = readCache();
-    const hit = cache?.releases.find((r) => r.tag_name === tag);
+    const hit =
+      cache?.byTag[tag] ?? cache?.recent.find((r) => r.tag_name === tag);
     if (hit) return hit;
   }
-  return fetchReleaseByTag(tag);
+  const release = await fetchReleaseByTag(tag);
+  if (release) persistByTag(release);
+  return release;
 }
 
 // ── Filtering / version utilities ────────────────────────────────────
@@ -264,11 +346,12 @@ interface DefaultOpts extends CommonOpts {
 async function runDefault(opts: DefaultOpts): Promise<void> {
   const noCache = opts.cache === false;
   const useJson = opts.json === true;
-  const limit = parseLimit(opts.limit, DEFAULT_LIST_LIMIT);
 
   if (opts.since) {
+    // --since needs the full rolling list so we can filter by tag.
+    const limit = parseLimit(opts.limit, DEFAULT_LIST_LIMIT);
     const floor = normalizeTag(opts.since);
-    const all = stableReleases(await loadReleases({ noCache, limit }));
+    const all = await loadReleases({ noCache, limit });
     const newer = all
       .filter((r) => compareTags(r.tag_name, floor) > 0)
       .sort((a, b) => compareTags(b.tag_name, a.tag_name));
@@ -285,7 +368,10 @@ async function runDefault(opts: DefaultOpts): Promise<void> {
     return;
   }
 
-  const releases = stableReleases(await loadReleases({ noCache, limit }));
+  // Bare default action only needs the latest stable release. Asking for 1
+  // means a populated cache (even with a single entry) is enough to short-
+  // circuit the network round-trip.
+  const releases = await loadReleases({ noCache, limit: 1 });
   if (releases.length === 0) {
     emitError("No releases found.");
   }
@@ -310,10 +396,7 @@ async function runList(opts: CommonOpts): Promise<void> {
   const noCache = opts.cache === false;
   const useJson = opts.json === true;
   const limit = parseLimit(opts.limit, DEFAULT_LIST_LIMIT);
-  const releases = stableReleases(await loadReleases({ noCache, limit })).slice(
-    0,
-    limit,
-  );
+  const releases = await loadReleases({ noCache, limit });
   if (useJson) {
     emit(JSON.stringify({ releases }, null, 2));
     return;
@@ -335,15 +418,17 @@ export function registerChangelogCommand(program: Command): void {
   registerCommand(program, {
     name: "changelog",
     transport: "local",
-    description: "Show release notes (fetched on demand from GitHub Releases)",
+    description:
+      "Show release notes of the Vellum Assistant to see what new capabilities you have!",
     build: (cmd) => {
       cmd.addHelpText(
         "after",
         `
 Release notes are fetched on demand from the public GitHub Releases of
-${REPO}. Results are cached locally for ${LIST_TTL_MS / 60_000} minutes;
-pass --no-cache to bypass the cache. Specific tags are cached without TTL
-because release tags are immutable.
+${REPO}. The most recent ${CACHE_STABLE_LIMIT} stable releases are cached
+locally for ${LIST_TTL_MS / 60_000} minutes; pass --no-cache to bypass.
+Specific tags are cached indefinitely once seen because release tags are
+immutable.
 
 Examples:
   $ assistant changelog                       Show the latest release
@@ -391,24 +476,3 @@ Examples:
     },
   });
 }
-
-// ── Test-only exports ────────────────────────────────────────────────
-
-/**
- * Internal helpers exported for unit tests only. Not part of the public CLI
- * contract — do not import from outside `cli/commands/__tests__`.
- */
-export const __testing = {
-  compareTags,
-  normalizeTag,
-  stableReleases,
-  renderRelease,
-  renderList,
-  parseLimit,
-  readCache,
-  writeCache,
-  isStale,
-  loadReleases,
-  loadReleaseByTag,
-  getCachePath,
-};

package/src/cli/commands/conversations.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
@@ -7,6 +9,98 @@ import { log } from "../logger.js";
 import { registerConversationsDeferCommand } from "./conversations-defer.js";
 import { registerConversationsImportCommand } from "./conversations-import.js";
 
+type ConversationSeedMessage = {
+  role: "user" | "assistant";
+  content: string;
+};
+
+function readSeedMessages(
+  contentFile?: string,
+): ConversationSeedMessage[] | undefined {
+  if (!contentFile) return undefined;
+  if (!existsSync(contentFile)) {
+    log.error(`Error: content file not found: ${contentFile}`);
+    process.exitCode = 1;
+    return undefined;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(contentFile, "utf-8"));
+  } catch (err) {
+    log.error(
+      `Error: failed to read content file: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exitCode = 1;
+    return undefined;
+  }
+
+  if (!Array.isArray(parsed)) {
+    log.error("Error: content file must contain an array of messages");
+    process.exitCode = 1;
+    return undefined;
+  }
+
+  const messages: ConversationSeedMessage[] = [];
+  for (const [index, value] of parsed.entries()) {
+    if (
+      typeof value !== "object" ||
+      value === null ||
+      !("role" in value) ||
+      !("content" in value)
+    ) {
+      log.error(`Error: message ${index} must include role and content`);
+      process.exitCode = 1;
+      return undefined;
+    }
+    const role = (value as { role?: unknown }).role;
+    const content = (value as { content?: unknown }).content;
+    if (
+      (role !== "user" && role !== "assistant") ||
+      typeof content !== "string"
+    ) {
+      log.error(
+        `Error: message ${index} must have role user|assistant and string content`,
+      );
+      process.exitCode = 1;
+      return undefined;
+    }
+    messages.push({ role, content });
+  }
+
+  return messages;
+}
+
+async function createConversationCli(
+  title: string | undefined,
+  opts?: { contentFile?: string },
+): Promise<void> {
+  const messages = readSeedMessages(opts?.contentFile);
+  if (process.exitCode) return;
+
+  const result = await cliIpcCall<{
+    id: string;
+    title: string;
+    conversationKey: string;
+    messagesInserted: number;
+  }>("conversation_create_cli", {
+    body: {
+      title,
+      messages,
+    },
+  });
+
+  if (!result.ok) return exitFromIpcResult(result);
+
+  const conversation = result.result!;
+  const seedSuffix = conversation.messagesInserted
+    ? `, seeded ${conversation.messagesInserted} messages`
+    : "";
+  log.info(
+    `Created conversation: ${conversation.title} (${conversation.id}), conversation key: ${conversation.conversationKey}${seedSuffix}`,
+  );
+}
+
 export function registerConversationsCommand(program: Command): void {
   registerCommand(program, {
     name: "conversations",
@@ -85,6 +179,7 @@ Examples:
       conversations
         .command("new [title]")
         .description("Create a new conversation")
+        .option("--content-file <path>", "Seed messages from a JSON file")
         .addHelpText(
           "after",
           `
@@ -92,26 +187,18 @@ Arguments:
   title   Optional conversation title (string). If omitted, a default title is
           assigned by the assistant.
 
-Creates a new conversation and prints its title and ID.
+The content file must be a JSON array of { role, content } messages.
+
+Creates a new conversation and prints its title, ID, and generated conversation
+key.
 
 Examples:
   $ assistant conversations new
   $ assistant conversations new "Project planning"
+  $ assistant conversations new --content-file /tmp/seed.json
   $ assistant conversations new "Bug triage 2026-03-05"`,
         )
-        .action(async (title?: string) => {
-          const result = await cliIpcCall<{ id: string; title: string }>(
-            "conversation_create_cli",
-            { body: { title } },
-          );
-
-          if (!result.ok) return exitFromIpcResult(result);
-
-          const conversation = result.result!;
-          log.info(
-            `Created conversation: ${conversation.title} (${conversation.id})`,
-          );
-        });
+        .action(createConversationCli);
 
       // -------------------------------------------------------------------
       // rename
@@ -278,9 +365,7 @@ Examples:
 
           if (!result.ok) return exitFromIpcResult(result);
 
-          log.info(
-            `Cleared ${result.result!.cleared} conversations. Done.`,
-          );
+          log.info(`Cleared ${result.result!.cleared} conversations. Done.`);
         });
 
       // -------------------------------------------------------------------

package/src/cli/commands/default-action.ts

@@ -3,6 +3,10 @@ import type { Command } from "commander";
 import { startCli } from "../../cli.js";
 import { shouldAutoStartDaemon } from "../../daemon/connection-policy.js";
 import { ensureDaemonRunning } from "../../daemon/daemon-control.js";
+import {
+  findClosestCommand,
+  formatUnknownCommandMessage,
+} from "../lib/unknown-command.js";
 
 export function registerDefaultAction(program: Command): void {
   program.action(async (_options: unknown, cmd: Command) => {
@@ -10,16 +14,16 @@ export function registerDefaultAction(program: Command): void {
     // args instead of raising an error. Detect this case and fail with a
     // helpful message so users don't silently get the interactive CLI when
     // they mistype a command name.
+    //
+    // The `assistant <unknown> --help` path is intercepted earlier (see
+    // src/index.ts) because Commander's `--help` short-circuit fires before
+    // this action runs. This branch covers `assistant <unknown>` with no
+    // `--help` flag.
     if (cmd.args.length > 0) {
       const unknown = cmd.args[0];
       const available = cmd.commands.map((c) => c.name());
       const suggestion = findClosestCommand(unknown, available);
-      const lines = [`unknown command '${unknown}'`];
-      if (suggestion) {
-        lines.push(`(Did you mean '${suggestion}'?)`);
-      }
-      lines.push(`Run 'assistant --help' to see a list of available commands.`);
-      cmd.error(lines.join("\n"), {
+      cmd.error(formatUnknownCommandMessage({ token: unknown, suggestion }), {
         code: "commander.unknownCommand",
         exitCode: 1,
       });
@@ -32,50 +36,3 @@ export function registerDefaultAction(program: Command): void {
     await startCli();
   });
 }
-
-/**
- * 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.
- */
-function findClosestCommand(
-  input: string,
-  candidates: string[],
-): string | undefined {
-  let best: string | undefined;
-  let bestDist = Infinity;
-
-  for (const name of candidates) {
-    const dist = levenshtein(input.toLowerCase(), name.toLowerCase());
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = name;
-    }
-  }
-
-  // Only suggest if the edit distance is at most 40% of the longer string
-  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];
-}