jamdesk 1.1.89 → 1.1.90

package/vendored/lib/validate-config.ts

@@ -60,6 +60,10 @@ export interface ValidationResult {
   error?: string;
   errorType?: 'config_error';
   errorSuggestion?: string;
+  /** Populated only on missing-file failures when `repoRoot` was supplied. */
+  discovery?: DocsJsonDiscovery;
+  /** Prose remediation derived from discovery (e.g., "Did you mean docsPath=apps/docs?"). */
+  discoveryHint?: string;
 }
 
 type Schema = Record<string, unknown>;
@@ -297,12 +301,121 @@ export function formatValidationErrors(errors: ErrorObject[] | null | undefined)
   return messages.join('. ');
 }
 
+/** Limits keep worst-case repos (huge monorepos, generated dirs) cheap on failure. */
+const DISCOVER_MAX_DEPTH = 3;
+const DISCOVER_MAX_ENTRIES = 500;
+const DISCOVER_SKIP_DIRS = new Set([
+  'node_modules', '.git', '.next', '.turbo', '.cache',
+  'dist', 'build', 'out', '.vercel', 'coverage',
+]);
+
+export interface DocsJsonDiscovery {
+  /** Repo-relative paths (POSIX separators), sorted, to docs.json files. */
+  foundAt: string[];
+  /** First-level entries at the repo root, sorted. */
+  rootEntries: string[];
+  /** True if the walk hit DISCOVER_MAX_ENTRIES before finishing. */
+  truncated: boolean;
+}
+
+/**
+ * Walk `repoRoot` looking for any `docs.json`. Used only on the failure path —
+ * gives ops a snapshot of what was cloned and lets us suggest the right docsPath.
+ *
+ * Documented behavior (covered by tests):
+ * - Case-sensitive filename match (`docs.json` only, not `Docs.json`). Matches Linux
+ *   prod semantics — macOS dev might see different fs.existsSync behavior but discovery
+ *   is consistent across platforms.
+ * - Skips directories whose name starts with `.` (so `.config/docs.json` is invisible).
+ * - Skips symlinks unconditionally (cycle defense; Windows junctions covered by the
+ *   entry+depth caps as a backstop).
+ * - Output paths use POSIX separators on all platforms.
+ * - `rootEntries` is the raw, sorted listing of the repo's top-level entries — it is
+ *   captured once at depth 0 and is NOT bounded by DISCOVER_MAX_ENTRIES. Persistence
+ *   layers (Firestore writes, structured logs) slice it to a fixed cap on their side.
+ *
+ * Limits: DISCOVER_MAX_DEPTH=3, DISCOVER_MAX_ENTRIES=500.
+ */
+export async function discoverDocsJson(repoRoot: string): Promise<DocsJsonDiscovery> {
+  const foundAt: string[] = [];
+  let rootEntries: string[] = [];
+  let seen = 0;
+  let truncated = false;
+
+  async function walk(absDir: string, relDir: string, depth: number): Promise<void> {
+    if (truncated || depth > DISCOVER_MAX_DEPTH) return;
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    if (depth === 0) {
+      rootEntries = entries.map(e => e.name).sort();
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory() && (DISCOVER_SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))) continue;
+      if (++seen > DISCOVER_MAX_ENTRIES) {
+        truncated = true;
+        return;
+      }
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(path.join(absDir, entry.name), rel, depth + 1);
+      } else if (entry.isFile() && entry.name === 'docs.json') {
+        foundAt.push(rel);
+      }
+    }
+  }
+
+  await walk(repoRoot, '', 0);
+  foundAt.sort();
+  return { foundAt, rootEntries, truncated };
+}
+
+/**
+ * Build the prose remediation hint from a discovery snapshot. Pure function —
+ * separated from validateConfig so it can be unit-tested directly and so the
+ * hint phrasings live in one named place.
+ */
+export function synthesizeDiscoveryHint(
+  foundAt: string[],
+  expectedRel: string,
+  docsPath?: string,
+): string {
+  const elsewhere = foundAt.filter(p => p !== expectedRel);
+  if (elsewhere.length === 1) {
+    // path.posix.dirname returns '.' for files at the root (e.g. 'docs.json' → '.').
+    const dir = path.posix.dirname(elsewhere[0]);
+    if (dir === '.') {
+      return docsPath
+        ? 'We found docs.json at the repository root. You can clear the docs path setting to use it.'
+        : 'We found docs.json at the repository root.';
+    }
+    return `We found docs.json at '${elsewhere[0]}'. Did you mean to set the docs path to '${dir}'?`;
+  }
+  if (elsewhere.length > 1) {
+    const list = elsewhere.slice(0, 3).map(p => `'${p}'`).join(', ');
+    const more = elsewhere.length > 3 ? ` and ${elsewhere.length - 3} more` : '';
+    return `We found docs.json at: ${list}${more}. Update the docs path setting to point at one of these.`;
+  }
+  return 'We could not find a docs.json file anywhere in this commit. '
+    + 'Check that you pushed the right branch and that docs.json is committed.';
+}
+
 /**
- * Validate docs.json configuration
+ * Validate docs.json configuration.
  * @param configPath - Full path to docs.json
- * @param docsPath - Optional monorepo path for better error messages (e.g., "jamdesk")
+ * @param docsPath   - Optional monorepo path for better error messages (e.g., "jamdesk")
+ * @param repoRoot   - Optional repo root; when supplied, missing-file errors include
+ *                    a discovery snapshot and a remediation hint.
  */
-export async function validateConfig(configPath: string, docsPath?: string): Promise<ValidationResult> {
+export async function validateConfig(
+  configPath: string,
+  docsPath?: string,
+  repoRoot?: string,
+): Promise<ValidationResult> {
   // Check file exists
   if (!fs.existsSync(configPath)) {
     // If `mint.json` sits where docs.json should be, the project is mid-migration
@@ -311,13 +424,27 @@ export async function validateConfig(configPath: string, docsPath?: string): Pro
     if (fs.existsSync(mintPath)) {
       return mintlifyMigrationError('Found `mint.json` but no `docs.json`.');
     }
-    const pathHint = docsPath
+
+    const baseError = docsPath
       ? `Missing docs.json at '${docsPath}/docs.json'. Check that your monorepo path is correct.`
       : 'Missing docs.json configuration file. Your repository must have a docs.json file in the root directory.';
-    return {
-      valid: false,
-      error: pathHint,
-    };
+
+    if (!repoRoot) {
+      return { valid: false, error: baseError };
+    }
+
+    const discovery = await discoverDocsJson(repoRoot);
+
+    const normalizedDocsPath = docsPath
+      ? path.posix.normalize(docsPath.replace(/\\/g, '/').replace(/^\.\//, '')).replace(/\/$/, '')
+      : '';
+    const expectedRel = normalizedDocsPath
+      ? path.posix.join(normalizedDocsPath, 'docs.json')
+      : 'docs.json';
+
+    const discoveryHint = synthesizeDiscoveryHint(discovery.foundAt, expectedRel, docsPath);
+
+    return { valid: false, error: baseError, discovery, discoveryHint };
   }
   
   // Read and parse file

package/vendored/shared/status-reporter.ts

@@ -66,8 +66,20 @@ export interface FailureUpdate {
   failedPhase: string;
   timing: TimingSummary | null;
   memory?: MemoryStats;
+  /** docs.json discovery snapshot — populated only on missing-file validate failures. */
+  discovery?: {
+    foundAt: string[];
+    rootEntries: string[];
+    truncated: boolean;
+  };
 }
 
+/**
+ * Cap applied when persisting `FailureUpdate.discovery.rootEntries` to keep
+ * Firestore docs and Cloud Run log payloads bounded on wide repos.
+ */
+export const DISCOVERY_ROOT_ENTRIES_PERSIST_CAP = 30;
+
 export interface ErrorLogData {
   rawOutput: string;
   stderr: string;

package/vendored/workspace-package-lock.json

@@ -2913,9 +2913,9 @@
       }
     },
     "node_modules/dompurify": {
-      "version": "3.4.2",
-      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.2.tgz",
-      "integrity": "sha512-lHeS9SA/IKeIFFyYciHBr2n0v1VMPlSj843HdLOwjb2OxNwdq9Xykxqhk+FE42MzAdHvInbAolSE4mhahPpjXA==",
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.3.tgz",
+      "integrity": "sha512-VVwJidIJcp1hpg2OMXML3ZVRPYSZiq4aX7qBh83BSIpOaRDqI+qxhXjjIWnpzkOXhmp0L81lnoME1mnCc9H48A==",
       "license": "(MPL-2.0 OR Apache-2.0)",
       "optionalDependencies": {
         "@types/trusted-types": "^2.0.7"
@@ -2928,9 +2928,9 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.353",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.353.tgz",
-      "integrity": "sha512-kOrWphBi8TOZyiJZqsgqIle0lw+tzmnQK83pV9dZUd01Nm2POECSyFQMAuarzZdYqQW7FH9RaYOuaRo3h+bQ3w==",
+      "version": "1.5.354",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.354.tgz",
+      "integrity": "sha512-JaBHwWcfIdmSAfWM5l3uwjGd431j8YEMikZ+K/2nXVuBqJKyZ0f+2h4n4JY5AyNiZmnY9qQr2RU3v9DxDmHMNg==",
       "license": "ISC"
     },
     "node_modules/enhanced-resolve": {
@@ -3739,9 +3739,9 @@
       }
     },
     "node_modules/katex": {
-      "version": "0.16.45",
-      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.45.tgz",
-      "integrity": "sha512-pQpZbdBu7wCTmQUh7ufPmLr0pFoObnGUoL/yhtwJDgmmQpbkg/0HSVti25Fu4rmd1oCR6NGWe9vqTWuWv3GcNA==",
+      "version": "0.16.46",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.46.tgz",
+      "integrity": "sha512-WHy4Coo+bGZyH7NwJKHkS04YFsFcarWbAEOAC3EMndzdN6VSZqklLLIgfxzyaW9jDoeGYJX9SWbJPKpecox0Uw==",
       "funding": [
         "https://opencollective.com/katex",
         "https://github.com/sponsors/katex"