@quasar/mcp 1.0.0

package/src/project.js

@@ -0,0 +1,189 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * The packages that ship a docs slice in `dist/mcp`, in the order the
+ * server lists them. The slices are generated by the docs site build
+ * (`docs/build/mcp`, `--target`) as the last step of each package's
+ * `prepublishOnly`.
+ */
+export const DOCS_PACKAGES = ['quasar', '@quasar/app-vite']
+
+/**
+ * The first releases that bundle their docs slice; older installs
+ * serve nothing but the ui API JSON, which every quasar release ships.
+ */
+export const BUNDLED_DOCS_SINCE = {
+  quasar: '2.33.0',
+  '@quasar/app-vite': '3.9.0'
+}
+
+/**
+ * @typedef {object} InstalledPackage
+ * @property {string} name
+ * @property {string} version
+ * @property {string} dir The package root inside the project's node_modules.
+ * @property {string | null} docsDir `dist/mcp` when this release bundles its docs.
+ * @property {string | null} apiDir `dist/api` for quasar (the component/plugin/directive JSON descriptors).
+ */
+
+/**
+ * @typedef {object} Project
+ * @property {string} dir The directory served: the start directory, or the app found below it.
+ * @property {string} startDir The directory the server was started in (or given with --project).
+ * @property {string[]} otherApps Other app directories found below `startDir`, not served.
+ * @property {InstalledPackage[]} packages The DOCS_PACKAGES the project has installed.
+ */
+
+/** How deep below the start directory the apps of a workspace are looked for. */
+const SCAN_DEPTH = 4
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.quasar', 'coverage'])
+
+/**
+ * The directories below `root` (itself excluded) that have a docs
+ * package installed, in path order, a few levels deep: the apps of a
+ * pnpm workspace, whose dependencies are not hoisted to the root.
+ * Hidden directories, build output and node_modules are not entered;
+ * neither is an app, once found.
+ *
+ * @param {string} root
+ * @returns {string[]}
+ */
+function findApps(root) {
+  const found = []
+  const walk = (dir, depth) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+    for (const entry of entries) {
+      if (
+        !entry.isDirectory() ||
+        entry.name.startsWith('.') ||
+        SKIP_DIRS.has(entry.name)
+      ) {
+        continue
+      }
+      const child = join(dir, entry.name)
+      const isApp = DOCS_PACKAGES.some(name =>
+        existsSync(join(child, 'node_modules', name, 'package.json'))
+      )
+      if (isApp) {
+        found.push(child)
+      } else if (depth < SCAN_DEPTH) {
+        walk(child, depth + 1)
+      }
+    }
+  }
+  walk(root, 1)
+  return found
+}
+
+/**
+ * Whether a directory is worth looking below: a workspace root has a
+ * manifest, a home directory or a random folder (where a user-scoped
+ * client starts the server) has none, and walking those would be slow
+ * and could pick up an unrelated app.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isWorkspaceRoot(dir) {
+  return ['package.json', 'pnpm-workspace.yaml'].some(file =>
+    existsSync(join(dir, file))
+  )
+}
+
+/**
+ * @param {string} dir
+ * @returns {InstalledPackage[]}
+ */
+function locateAll(dir) {
+  const packages = []
+  for (const name of DOCS_PACKAGES) {
+    const installed = locatePackage(dir, name)
+    if (installed !== null) {
+      packages.push(installed)
+    }
+  }
+  return packages
+}
+
+/**
+ * The package as the project's own code would resolve it: the nearest
+ * `node_modules/<name>` walking up from the project, so a pnpm strict
+ * layout, a hoisted one and a workspace link all land on the copy the
+ * project runs. Symlinks are kept as found: the files read the same
+ * through them.
+ *
+ * @param {string} projectDir
+ * @param {string} name
+ * @returns {InstalledPackage | null}
+ */
+function locatePackage(projectDir, name) {
+  let dir = null
+  for (
+    let current = projectDir, parent = dirname(current);
+    dir === null;
+    current = parent, parent = dirname(current)
+  ) {
+    const candidate = join(current, 'node_modules', name)
+    if (existsSync(join(candidate, 'package.json'))) {
+      dir = candidate
+    } else if (parent === current) {
+      return null
+    }
+  }
+
+  const packageJsonPath = join(dir, 'package.json')
+  const { version } = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+  const docsDir = join(dir, 'dist', 'mcp')
+  const apiDir = join(dir, 'dist', 'api')
+
+  return {
+    name,
+    version,
+    dir,
+    docsDir: existsSync(join(docsDir, 'meta.json')) ? docsDir : null,
+    apiDir: name === 'quasar' && existsSync(apiDir) ? apiDir : null
+  }
+}
+
+/**
+ * The project to serve. The packages resolve from `projectDir` the way
+ * its own code resolves them. When that finds nothing and the directory
+ * was not named explicitly and it has a package.json or a
+ * pnpm-workspace.yaml, the apps below it are looked for (a
+ * workspace opened at its root): the first one, a full app before a
+ * library and in path order otherwise, is served and the others are
+ * reported, for --project to pick.
+ *
+ * @param {string} [projectDir] Defaults to the current working directory.
+ * @param {{ explicit?: boolean }} [opts] `explicit`: the directory was given (--project), serve it as is.
+ * @returns {Project}
+ */
+export function loadProject(
+  projectDir = process.cwd(),
+  { explicit = false } = {}
+) {
+  const startDir = resolve(projectDir)
+  let dir = startDir
+  let packages = locateAll(startDir)
+  let otherApps = []
+  if (packages.length === 0 && !explicit && isWorkspaceRoot(startDir)) {
+    // a full app (ui and CLI) before a package that only depends on
+    // quasar, a component library in the workspace; path order otherwise
+    const apps = findApps(startDir)
+      .map(app => ({ app, packages: locateAll(app) }))
+      .sort((a, b) => b.packages.length - a.packages.length)
+    if (apps.length !== 0) {
+      dir = apps[0].app
+      packages = apps[0].packages
+      otherApps = apps.slice(1).map(({ app }) => app)
+    }
+  }
+  return { dir, startDir, otherApps, packages }
+}