@vellumai/assistant 0.5.0 → 0.5.2

package/src/memory/app-store.ts

@@ -3,10 +3,14 @@
  *
  * Directory layout:
  *   ~/.vellum/apps/
- *     <app-id>.json            # app definition
- *     <app-id>/
+ *     <dirName>.json            # app definition
+ *     <dirName>/
  *       records/
  *         <record-id>.json     # individual record
+ *
+ * `dirName` is a human-readable slug derived from the app name at creation
+ * time and frozen thereafter (renaming an app does NOT rename its directory).
+ * Pre-migration apps (no `dirName` in JSON) fall back to using `id` (UUID).
  */
 
 import { randomUUID } from "node:crypto";
@@ -43,12 +47,14 @@ export interface AppDefinition {
   schemaJson: string;
   htmlDefinition: string;
   version?: string;
-  /** Additional pages keyed by filename (e.g. "settings.html" → HTML content). */
+  /** Additional pages keyed by filename (e.g. "settings.html" -> HTML content). */
   pages?: Record<string, string>;
   createdAt: number;
   updatedAt: number;
   /** App format version. undefined or 1 = legacy single-HTML, 2 = multi-file TSX. */
   formatVersion?: number;
+  /** Filesystem directory/file stem. Frozen at creation -- never changes on rename. */
+  dirName?: string;
 }
 
 /**
@@ -78,6 +84,29 @@ function validateId(id: string): void {
   }
 }
 
+/**
+ * Validate a dirName read from persisted JSON.
+ * Superset of validateId rules plus git pathspec metacharacters,
+ * since dirName is used directly in git pathspecs by app-git-service.
+ */
+export function validateDirName(dirName: string): void {
+  if (
+    !dirName ||
+    dirName.includes("/") ||
+    dirName.includes("\\") ||
+    dirName.includes("..") ||
+    dirName !== dirName.trim()
+  ) {
+    throw new Error(`Invalid dirName: ${dirName}`);
+  }
+  // Reject git pathspec metacharacters
+  if (/[*?[\]:()]/.test(dirName)) {
+    throw new Error(
+      `Invalid dirName: contains git pathspec characters: ${dirName}`,
+    );
+  }
+}
+
 /**
  * Validate a page filename to prevent path traversal and ensure it is a safe
  * relative filename (e.g. "settings.html").
@@ -103,6 +132,121 @@ export function getAppsDir(): string {
   return dir;
 }
 
+// ---------------------------------------------------------------------------
+// Slug generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a name to a filesystem-safe slug.
+ * - Lowercase
+ * - Replace non-alphanumeric (except hyphens) with hyphens
+ * - Collapse consecutive hyphens, trim leading/trailing
+ * - Truncate to 60 chars (re-trim trailing hyphen)
+ * - Fall back to "app-<random>" if result is empty (e.g. emoji-only names)
+ */
+export function slugify(name: string): string {
+  let slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  if (slug.length > 60) {
+    slug = slug.slice(0, 60).replace(/-+$/, "");
+  }
+
+  if (!slug) {
+    slug = `app-${randomUUID().slice(0, 8)}`;
+  }
+
+  return slug;
+}
+
+/**
+ * Generate a unique directory name from an app name.
+ * Appends -2, -3, etc. if the base slug collides with existing names.
+ */
+export function generateAppDirName(
+  name: string,
+  existingNames: Set<string>,
+): string {
+  const base = slugify(name);
+  if (!existingNames.has(base)) return base;
+  let counter = 2;
+  while (existingNames.has(`${base}-${counter}`)) {
+    counter++;
+  }
+  return `${base}-${counter}`;
+}
+
+// ---------------------------------------------------------------------------
+// App directory resolution (id -> dirName)
+// ---------------------------------------------------------------------------
+
+/** Cache of id -> dirName mappings to avoid repeated filesystem scans. */
+const idToDirNameCache = new Map<string, string>();
+
+/**
+ * Resolve an app's directory name and path from its ID.
+ * Scans JSON files if not cached. Falls back to `id` for pre-migration apps.
+ */
+export function resolveAppDir(id: string): {
+  dirName: string;
+  appDir: string;
+} {
+  validateId(id);
+
+  // Check cache first
+  const cached = idToDirNameCache.get(id);
+  if (cached) {
+    return { dirName: cached, appDir: join(getAppsDir(), cached) };
+  }
+
+  const dir = getAppsDir();
+  const entries = readdirSync(dir);
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const filePath = join(dir, entry);
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(raw) as { id?: string; dirName?: string };
+      if (parsed.id === id) {
+        const dirName = parsed.dirName || id;
+        if (parsed.dirName) {
+          validateDirName(dirName);
+        }
+        idToDirNameCache.set(id, dirName);
+        return { dirName, appDir: join(dir, dirName) };
+      }
+    } catch {
+      // skip malformed files
+    }
+  }
+
+  // If no JSON file found, fall back to id (backward compat)
+  idToDirNameCache.set(id, id);
+  return { dirName: id, appDir: join(dir, id) };
+}
+
+/** Convenience wrapper: returns the app directory path for the given app ID. */
+export function getAppDirPath(appId: string): string {
+  return resolveAppDir(appId).appDir;
+}
+
+/** Invalidate the id->dirName cache for a specific app or all apps. */
+function invalidateDirNameCache(appId?: string): void {
+  if (appId) {
+    idToDirNameCache.delete(appId);
+  } else {
+    idToDirNameCache.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File path validation
+// ---------------------------------------------------------------------------
+
 /**
  * Validate a relative file path within an app directory.
  * Prevents path traversal and access to protected directories.
@@ -123,7 +267,7 @@ function validateFilePath(appId: string, path: string): string {
   if (normalized === "records" || normalized.startsWith("records/")) {
     throw new Error(`Invalid file path: 'records/' directory is protected`);
   }
-  const appDir = join(getAppsDir(), appId);
+  const appDir = getAppDirPath(appId);
   const resolved = resolve(appDir, path);
   // Ensure the resolved path is still within the app directory
   if (!resolved.startsWith(appDir + "/") && resolved !== appDir) {
@@ -132,7 +276,7 @@ function validateFilePath(appId: string, path: string): string {
   // Follow symlinks to the real path so a symlink inside the app directory
   // cannot escape the boundary. For non-existent paths, walk up to the
   // nearest existing ancestor and resolve it, then re-append trailing
-  // components — catches symlinked parent directories on new file writes.
+  // components -- catches symlinked parent directories on new file writes.
   let realResolved: string;
   if (existsSync(resolved)) {
     realResolved = realpathSync(resolved);
@@ -163,9 +307,13 @@ function validateFilePath(appId: string, path: string): string {
   return resolved;
 }
 
-/** Persist pages as individual files under ~/.vellum/apps/{appId}/pages/. */
-function savePages(appId: string, pages: Record<string, string>): void {
-  const pagesDir = join(getAppsDir(), appId, "pages");
+// ---------------------------------------------------------------------------
+// Pages helpers
+// ---------------------------------------------------------------------------
+
+/** Persist pages as individual files under the app's pages/ subdirectory. */
+function savePages(appDirPath: string, pages: Record<string, string>): void {
+  const pagesDir = join(appDirPath, "pages");
   mkdirSync(pagesDir, { recursive: true });
   for (const [filename, content] of Object.entries(pages)) {
     validatePageFilename(filename);
@@ -179,8 +327,8 @@ function savePages(appId: string, pages: Record<string, string>): void {
 }
 
 /** Load pages from disk. Returns undefined if no pages directory exists. */
-function loadPages(appId: string): Record<string, string> | undefined {
-  const pagesDir = join(getAppsDir(), appId, "pages");
+function loadPages(appDirPath: string): Record<string, string> | undefined {
+  const pagesDir = join(appDirPath, "pages");
   if (!existsSync(pagesDir)) return undefined;
   const entries = readdirSync(pagesDir);
   if (entries.length === 0) return undefined;
@@ -191,6 +339,33 @@ function loadPages(appId: string): Record<string, string> | undefined {
   return pages;
 }
 
+// ---------------------------------------------------------------------------
+// Existing dirName collector (for dedup)
+// ---------------------------------------------------------------------------
+
+/** Scan all JSON files and build a set of existing dirName values. */
+function collectExistingDirNames(): Set<string> {
+  const dir = getAppsDir();
+  const entries = readdirSync(dir);
+  const names = new Set<string>();
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    try {
+      const raw = readFileSync(join(dir, entry), "utf-8");
+      const parsed = JSON.parse(raw) as { id?: string; dirName?: string };
+      // Use dirName if present, otherwise fall back to id (pre-migration)
+      names.add(parsed.dirName ?? parsed.id ?? entry.replace(/\.json$/, ""));
+    } catch {
+      // skip malformed
+    }
+  }
+  return names;
+}
+
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+
 export function createApp(params: {
   name: string;
   description?: string;
@@ -204,6 +379,11 @@ export function createApp(params: {
 }): AppDefinition {
   const dir = getAppsDir();
   const now = Date.now();
+
+  // Generate a unique dirName from the app name
+  const existingNames = collectExistingDirNames();
+  const dirName = generateAppDirName(params.name, existingNames);
+
   const app: AppDefinition = {
     id: randomUUID(),
     name: params.name,
@@ -216,10 +396,11 @@ export function createApp(params: {
     createdAt: now,
     updatedAt: now,
     formatVersion: params.formatVersion,
+    dirName,
   };
 
-  // Write htmlDefinition to {appId}/index.html on disk
-  const appDir = join(dir, app.id);
+  // Write htmlDefinition to {dirName}/index.html on disk
+  const appDir = join(dir, dirName);
   mkdirSync(appDir, { recursive: true });
   if (typeof params.htmlDefinition !== "string") {
     throw new Error(
@@ -230,21 +411,24 @@ export function createApp(params: {
 
   // Write preview to companion file to keep the JSON small
   if (params.preview) {
-    writeFileSync(join(dir, `${app.id}.preview`), params.preview, "utf-8");
+    writeFileSync(join(dir, `${dirName}.preview`), params.preview, "utf-8");
   }
 
-  // Strip htmlDefinition, pages, and preview from the JSON file — only store metadata
+  // Strip htmlDefinition, pages, and preview from the JSON file -- only store metadata
   const {
     htmlDefinition: _html,
     pages: _pages,
     preview: _preview,
     ...jsonDef
   } = app;
-  writeFileSync(join(dir, `${app.id}.json`), JSON.stringify(jsonDef, null, 2));
+  writeFileSync(join(dir, `${dirName}.json`), JSON.stringify(jsonDef, null, 2));
+
+  // Update cache
+  idToDirNameCache.set(app.id, dirName);
 
   // Persist additional pages as separate files
   if (params.pages && Object.keys(params.pages).length > 0) {
-    savePages(app.id, params.pages);
+    savePages(appDir, params.pages);
     app.pages = params.pages;
   }
 
@@ -253,26 +437,27 @@ export function createApp(params: {
 
 export function getApp(id: string): AppDefinition | null {
   validateId(id);
+  const { dirName, appDir } = resolveAppDir(id);
   const dir = getAppsDir();
-  const filePath = join(dir, `${id}.json`);
+  const filePath = join(dir, `${dirName}.json`);
   if (!existsSync(filePath)) return null;
   const raw = readFileSync(filePath, "utf-8");
   const app = JSON.parse(raw) as AppDefinition;
 
-  // Read htmlDefinition from {appId}/index.html on disk
-  const indexPath = join(dir, id, "index.html");
+  // Read htmlDefinition from {dirName}/index.html on disk
+  const indexPath = join(appDir, "index.html");
   app.htmlDefinition = existsSync(indexPath)
     ? readFileSync(indexPath, "utf-8")
     : (app.htmlDefinition ?? "");
 
   // Load preview from companion file
-  const previewPath = join(dir, `${id}.preview`);
+  const previewPath = join(dir, `${dirName}.preview`);
   if (existsSync(previewPath)) {
     app.preview = readFileSync(previewPath, "utf-8");
   }
 
   // Load pages from disk
-  const pages = loadPages(id);
+  const pages = loadPages(appDir);
   if (pages) {
     app.pages = pages;
   }
@@ -286,8 +471,9 @@ export function getApp(id: string): AppDefinition | null {
  */
 export function getAppPreview(id: string): string | null {
   validateId(id);
+  const { dirName } = resolveAppDir(id);
   const dir = getAppsDir();
-  const previewPath = join(dir, `${id}.preview`);
+  const previewPath = join(dir, `${dirName}.preview`);
   if (existsSync(previewPath)) {
     return readFileSync(previewPath, "utf-8");
   }
@@ -334,6 +520,8 @@ export function updateApp(
   const existing = getApp(id);
   if (!existing) throw new Error(`App not found: ${id}`);
 
+  const { dirName, appDir } = resolveAppDir(id);
+
   // Extract pages, htmlDefinition, and preview before spreading into the JSON-persisted definition
   const {
     pages,
@@ -348,9 +536,8 @@ export function updateApp(
     updatedAt: Date.now(),
   };
 
-  // Write htmlDefinition to {appId}/index.html if provided in updates
+  // Write htmlDefinition to {dirName}/index.html if provided in updates
   const dir = getAppsDir();
-  const appDir = join(dir, id);
   if (htmlUpdate !== undefined) {
     updated.htmlDefinition = htmlUpdate;
     mkdirSync(appDir, { recursive: true });
@@ -360,29 +547,29 @@ export function updateApp(
   // Write preview to companion file
   if (previewUpdate !== undefined) {
     updated.preview = previewUpdate;
-    writeFileSync(join(dir, `${id}.preview`), previewUpdate, "utf-8");
+    writeFileSync(join(dir, `${dirName}.preview`), previewUpdate, "utf-8");
   }
 
-  // Don't persist htmlDefinition, pages, or preview in the JSON file — they live as separate files
+  // Don't persist htmlDefinition, pages, or preview in the JSON file -- they live as separate files
   const {
     pages: _existingPages,
     htmlDefinition: _html,
     preview: _preview,
     ...jsonDef
   } = updated;
-  writeFileSync(join(dir, `${id}.json`), JSON.stringify(jsonDef, null, 2));
+  writeFileSync(join(dir, `${dirName}.json`), JSON.stringify(jsonDef, null, 2));
 
   // Clear existing pages directory before writing new pages to prevent stale files
   if (pages && Object.keys(pages).length > 0) {
-    const pagesDir = join(getAppsDir(), id, "pages");
+    const pagesDir = join(appDir, "pages");
     if (existsSync(pagesDir)) {
       rmSync(pagesDir, { recursive: true, force: true });
     }
-    savePages(id, pages);
+    savePages(appDir, pages);
   }
 
   // Re-attach pages to the returned object
-  const loadedPages = loadPages(id);
+  const loadedPages = loadPages(appDir);
   if (loadedPages) {
     updated.pages = loadedPages;
   }
@@ -392,17 +579,18 @@ export function updateApp(
 
 export function deleteApp(id: string): void {
   validateId(id);
+  const { dirName, appDir } = resolveAppDir(id);
   const dir = getAppsDir();
-  const filePath = join(dir, `${id}.json`);
+  const filePath = join(dir, `${dirName}.json`);
   if (existsSync(filePath)) {
     unlinkSync(filePath);
   }
-  const previewPath = join(dir, `${id}.preview`);
+  const previewPath = join(dir, `${dirName}.preview`);
   if (existsSync(previewPath)) {
     unlinkSync(previewPath);
   }
-  const appDir = join(dir, id);
   rmSync(appDir, { recursive: true, force: true });
+  invalidateDirNameCache(id);
 }
 
 export function createAppRecord(
@@ -412,7 +600,7 @@ export function createAppRecord(
   validateId(appId);
   const app = getApp(appId);
   if (!app) throw new Error(`App not found: ${appId}`);
-  const recordsDir = join(getAppsDir(), appId, "records");
+  const recordsDir = join(getAppDirPath(appId), "records");
   mkdirSync(recordsDir, { recursive: true });
   const now = Date.now();
   const record: AppRecord = {
@@ -435,7 +623,7 @@ export function getAppRecord(
 ): AppRecord | null {
   validateId(appId);
   validateId(recordId);
-  const filePath = join(getAppsDir(), appId, "records", `${recordId}.json`);
+  const filePath = join(getAppDirPath(appId), "records", `${recordId}.json`);
   if (!existsSync(filePath)) return null;
   const raw = readFileSync(filePath, "utf-8");
   return JSON.parse(raw) as AppRecord;
@@ -443,7 +631,7 @@ export function getAppRecord(
 
 export function queryAppRecords(appId: string): AppRecord[] {
   validateId(appId);
-  const recordsDir = join(getAppsDir(), appId, "records");
+  const recordsDir = join(getAppDirPath(appId), "records");
   if (!existsSync(recordsDir)) return [];
   const entries = readdirSync(recordsDir);
   const records: AppRecord[] = [];
@@ -474,7 +662,7 @@ export function updateAppRecord(
     updatedAt: Date.now(),
   };
   writeFileSync(
-    join(getAppsDir(), appId, "records", `${recordId}.json`),
+    join(getAppDirPath(appId), "records", `${recordId}.json`),
     JSON.stringify(updated, null, 2),
   );
   return updated;
@@ -483,7 +671,7 @@ export function updateAppRecord(
 export function deleteAppRecord(appId: string, recordId: string): void {
   validateId(appId);
   validateId(recordId);
-  const filePath = join(getAppsDir(), appId, "records", `${recordId}.json`);
+  const filePath = join(getAppDirPath(appId), "records", `${recordId}.json`);
   if (existsSync(filePath)) {
     unlinkSync(filePath);
   }
@@ -494,12 +682,13 @@ export function deleteAppRecord(appId: string, recordId: string): void {
 // ---------------------------------------------------------------------------
 
 /**
- * Recursively list all files under `{appId}/`, excluding `records/` subdirectory
- * and `app.json`. Returns relative paths like `index.html`, `styles.css`, `js/app.js`.
+ * Recursively list all files under the app's directory, excluding `records/`
+ * subdirectory and `app.json`. Returns relative paths like `index.html`,
+ * `styles.css`, `js/app.js`.
  */
 export function listAppFiles(appId: string): string[] {
   validateId(appId);
-  const appDir = join(getAppsDir(), appId);
+  const appDir = getAppDirPath(appId);
   if (!existsSync(appDir)) return [];
 
   const results: string[] = [];