@dypai-ai/mcp 1.5.10 → 1.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.5.10",
+  "version": "1.5.11",
   "description": "DYPAI MCP Server — AI agent toolkit for building and deploying full-stack apps",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -35,6 +35,10 @@ import { manageFrontendTool } from "./tools/frontend.js"
 // import { scaffoldTool } from "./tools/scaffold.js"
 import { manageDomainTool } from "./tools/domains.js"
 import { bulkUpsertTool } from "./tools/bulk-upsert.js"
+import {
+  searchCapabilityKitsTool,
+  manageCapabilityKitTool,
+} from "./tools/capability-kits.js"
 import { uploadFile } from "./tools/storage.js"
 // dypaiTestTool (YAML test-suite runner) is intentionally not imported — deferred to v2.
 // The format works but needs fixtures/auto-rollback/scaffolder + proper docs before being surfaced.
@@ -82,6 +86,9 @@ const LOCAL_TOOLS = [
   manageDomainTool,
   // ── Data ──────────────────────────────────────────────────────────────────
   bulkUpsertTool,
+  // ── Capability kits (local source installer) ──────────────────────────────
+  searchCapabilityKitsTool,
+  manageCapabilityKitTool,
   // ── Git-first source of truth ─────────────────────────────────────────────
   // dypai_describe was merged into dypai_pull (now returns an `overview` block).
   dypaiPullTool,
@@ -538,6 +545,17 @@ forms, calendars, or domain-specific screens), use \`search_design_patterns\`
 with the app/starter/screen/style context. It returns curated recipes; adapt
 them to the project instead of inventing generic starter UI.
 
+For complex reusable capabilities (calendar booking, interactive maps, CRUD
+tables, Kanban boards, upload/document flows, dashboards, rich editors), also
+use \`search_capability_kits\`. If a strong kit matches, inspect it with
+\`manage_capability_kit(operation: "inspect")\` and install it with
+\`manage_capability_kit(operation: "apply")\` instead of building that complex
+component from scratch. Installed kit code is editable workspace source; after
+install, if the tool returns dependencies, add any missing packages to the
+target workspace package.json and install them locally (never globally or in
+the MCP server). Then wire the kit into the app, apply SQL if needed, validate
+endpoints, and verify the frontend.
+
 **The template system exists to save time when the fit is obvious, not to force-match every request.** When in doubt → blank is always correct. Iterating up from blank is cheaper than deleting 80% of a mismatched template.
 
 ## The one legit follow-up question
@@ -1014,6 +1032,8 @@ Each item has \`type\` (\`execution\` | \`execution_failed\` | \`log\`), \`level
 
 DYPAI has NO standalone "edge functions". Every piece of server-side logic (API endpoints, crons, webhooks, AI agents) is a workflow endpoint under \`dypai/endpoints/<name>.yaml\`. A workflow is either a chain of native nodes (\`dypai_database\`, \`http_request\`, \`agent\`, \`stripe\`, etc.) OR a single \`javascript_code\` / \`python_code\` node for custom logic. Mix freely.
 
+Endpoint naming is strict: the YAML \`name\` is the public API slug and must exactly match the file basename. Example: \`dypai/endpoints/list-videos.yaml\` must declare \`name: list-videos\`. Use lowercase letters, numbers, hyphens, or underscores only; never spaces or human titles. Put labels like "Listar videos" in \`description\`, not \`name\`. If \`id\` is present, it must match \`name\`; usually omit \`id\`.
+
 Mental translations: "edge function" → workflow with one code node; "cron" → \`trigger.schedule\` in the YAML; "webhook receiver" → \`trigger.webhook\`; "internal API" → \`trigger.http_api auth_mode:jwt\`.
 
 → Full workflow patterns + YAML shape: \`search_docs("workflow patterns")\` and \`search_docs("trigger model")\`. Node catalog (full input/output schemas): read \`dypai/node-catalog.json\`.
@@ -1039,6 +1059,7 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 5. **Missing \`return: true\`** — endpoint returns \`null\`. Every path that should produce an HTTP response needs one node with \`return: true\`.
 6. **\`tool_ids\` in YAML instead of \`tools\`** — write \`tools: [name1, name2]\`. \`tool_ids\` bypasses the codec and fails silently in prod.
 7. **Putting workflow placeholders inside \`javascript_code.code\`** — code is raw JavaScript, so JS template literals like \`\${where.join(" AND ")}\` are safe and not rendered by DYPAI. Pass workflow values via \`input_data\`, \`ctx.nodes\`, \`ctx.user\`, or \`ctx.env\`; do not write \`\${input.email}\` inside code or set \`code\` from another node output.
+8. **Human endpoint names** — \`name: Listar videos\` in \`list-videos.yaml\` creates a draft the frontend cannot call as \`list-videos\`. \`dypai_validate\` and \`dypai_push\` reject this; fix the slug instead of testing around it.
 
 → Longer list of common pitfalls + fixes: \`search_docs("troubleshooting")\`.
 
@@ -1049,7 +1070,7 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 - **AI chat**: single endpoint with \`agent\` node + \`memory_key: "chat:\${current_user_id}"\`. Frontend \`dypai.api.stream()\`.
 - **Payments (Stripe)**: \`stripe\` node for ops. Webhook endpoint with \`trigger.webhook\` + \`stripe_webhook: true\` (auto-verifies signature).
 - **Cron**: \`trigger.schedule: { cron: "0 9 * * *", timezone: "..." }\`. Same workflow syntax as HTTP endpoints.
-- **File upload**: frontend \`dypai.api.upload(endpoint, file)\`. Endpoint = one \`dypai_storage\` node. SDK handles signed-URL PUT.
+- **File upload**: frontend \`dypai.api.upload(endpoint, file, { params: { operation:'upload', file_path } })\`. Endpoint = one \`dypai_storage\` node with \`return:true\`. SDK handles signed-URL PUT and owns \`confirm\`/\`client_upload\`; never pass those flags from frontend params.
 - **Live dashboard**: normal endpoint + frontend \`useRealtime(table, { onInsert: refetch })\`.
 - **Multi-tenant**: every row has \`org_id\` or \`user_id\`. Every endpoint filters by \`\${current_user_id}\`.
 

package/src/tools/capability-kits.js

@@ -0,0 +1,567 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync } from "fs"
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const DEFAULT_LIMIT = 5
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"))
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+function normalizeList(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim()) : []
+}
+
+function walkUp(start, predicate) {
+  let cursor = resolve(start)
+  for (let i = 0; i < 10; i++) {
+    if (predicate(cursor)) return cursor
+    const parent = dirname(cursor)
+    if (parent === cursor) break
+    cursor = parent
+  }
+  return null
+}
+
+function resolveKitsRoot(inputRoot) {
+  const candidates = [
+    inputRoot,
+    process.env.DYPAI_CAPABILITY_KITS_ROOT,
+  ].filter(Boolean)
+
+  for (const candidate of candidates) {
+    const root = resolve(candidate)
+    if (existsSync(join(root, "kits"))) return root
+  }
+
+  const fromCwd = walkUp(process.cwd(), (dir) => existsSync(join(dir, "dypai-capability-kits", "kits")))
+  if (fromCwd) return join(fromCwd, "dypai-capability-kits")
+
+  const fromThisFile = walkUp(__dirname, (dir) => existsSync(join(dir, "dypai-capability-kits", "kits")))
+  if (fromThisFile) return join(fromThisFile, "dypai-capability-kits")
+
+  throw new Error(
+    "Capability kit repo not found. Set DYPAI_CAPABILITY_KITS_ROOT to the local dypai-capability-kits directory.",
+  )
+}
+
+function resolveWorkspaceRoot(inputRoot) {
+  if (inputRoot) {
+    const root = resolve(inputRoot)
+    mkdirSync(root, { recursive: true })
+    return root
+  }
+
+  const envCandidates = [
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.DYPAI_WORKSPACE_ROOT,
+    process.env.PROJECT_ROOT,
+    process.env.WORKSPACE_FOLDER_PATHS?.split(delimiter)[0],
+  ].filter(Boolean)
+
+  for (const candidate of envCandidates) {
+    const root = resolve(candidate)
+    if (existsSync(root)) return root
+  }
+
+  const fromCwd = walkUp(process.cwd(), (dir) =>
+    existsSync(join(dir, ".git")) ||
+    existsSync(join(dir, "package.json")) ||
+    existsSync(join(dir, "dypai")) ||
+    existsSync(join(dir, "src")),
+  )
+  if (fromCwd) return fromCwd
+
+  throw new Error("Could not determine workspace root. Pass workspace_root as an absolute project path.")
+}
+
+function safeTarget(workspaceRoot, targetPath) {
+  if (!targetPath || typeof targetPath !== "string") throw new Error("Invalid target path")
+  if (isAbsolute(targetPath)) throw new Error(`Target must be workspace-relative, got absolute path: ${targetPath}`)
+  const normalized = targetPath.replace(/\\/g, "/").replace(/^\/+/, "")
+  if (normalized.includes("..")) throw new Error(`Target path cannot contain '..': ${targetPath}`)
+  const full = resolve(workspaceRoot, normalized)
+  const rel = relative(workspaceRoot, full)
+  if (rel.startsWith("..") || rel === "" || isAbsolute(rel)) {
+    throw new Error(`Target escapes workspace root: ${targetPath}`)
+  }
+  return full
+}
+
+function kitDir(kitsRoot, slug, version) {
+  if (!slug || !version) throw new Error("slug and version are required")
+  return join(kitsRoot, "kits", slug, version)
+}
+
+function loadKit(kitsRoot, slug, version) {
+  const dir = kitDir(kitsRoot, slug, version)
+  const manifestPath = join(dir, "kit.json")
+  if (!existsSync(manifestPath)) throw new Error(`Kit not found: ${slug}@${version}`)
+  const manifest = readJson(manifestPath)
+  return { dir, manifest }
+}
+
+function listKits(kitsRoot) {
+  const kitsDir = join(kitsRoot, "kits")
+  const kits = []
+  for (const slug of readdirSync(kitsDir)) {
+    const slugDir = join(kitsDir, slug)
+    if (!existsSync(slugDir) || slug === "index.json") continue
+    for (const version of readdirSync(slugDir)) {
+      const manifestPath = join(slugDir, version, "kit.json")
+      if (!existsSync(manifestPath)) continue
+      kits.push({ dir: join(slugDir, version), manifest: readJson(manifestPath) })
+    }
+  }
+  return kits
+}
+
+function searchText(kit) {
+  const parts = [
+    kit.slug,
+    kit.name,
+    kit.kitType,
+    kit.category,
+    kit.description,
+    kit.useWhen,
+    kit.avoidWhen,
+    kit.userFacingSummary,
+    kit.agentInstructions,
+    ...normalizeList(kit.appTypes),
+    ...normalizeList(kit.screenTypes),
+    ...normalizeList(kit.featureTags),
+    ...normalizeList(kit.visualStyles),
+    ...normalizeList(kit.provides),
+    ...normalizeList(kit.requires),
+    ...normalizeList(kit.dependencies),
+  ]
+  return parts.filter(Boolean).join(" ").toLowerCase()
+}
+
+function matchesFilter(kit, filters = {}) {
+  if (!isObject(filters)) return true
+  if (filters.category && kit.category !== filters.category) return false
+  if (filters.maturity) {
+    const allowed = Array.isArray(filters.maturity) ? filters.maturity : [filters.maturity]
+    if (!allowed.includes(kit.maturity)) return false
+  }
+  const listChecks = [
+    ["app_type", "appTypes"],
+    ["screen_type", "screenTypes"],
+    ["feature_tag", "featureTags"],
+  ]
+  for (const [filterKey, kitKey] of listChecks) {
+    if (filters[filterKey] && !normalizeList(kit[kitKey]).includes(filters[filterKey])) return false
+  }
+  if (Array.isArray(filters.requires)) {
+    const requires = normalizeList(kit.requires)
+    for (const required of filters.requires) {
+      if (!requires.includes(required)) return false
+    }
+  }
+  return true
+}
+
+function scoreKit(query, kit) {
+  const text = searchText(kit)
+  const terms = String(query || "")
+    .toLowerCase()
+    .split(/[^a-z0-9áéíóúñ]+/i)
+    .map((term) => term.trim())
+    .filter((term) => term.length >= 3)
+  if (!terms.length) return 0
+  let score = 0
+  for (const term of terms) {
+    if (kit.slug?.includes(term)) score += 5
+    if (kit.category?.toLowerCase() === term) score += 4
+    if (text.includes(term)) score += 1
+  }
+  return score
+}
+
+function assetIndex(dir) {
+  const out = []
+  function visit(abs, rel = "") {
+    for (const name of readdirSync(abs, { withFileTypes: true })) {
+      const childAbs = join(abs, name.name)
+      const childRel = rel ? `${rel}/${name.name}` : name.name
+      if (name.isDirectory()) visit(childAbs, childRel)
+      else out.push({ logicalPath: childRel, sizeBytes: readFileSync(childAbs).length })
+    }
+  }
+  visit(dir)
+  return out.sort((a, b) => a.logicalPath.localeCompare(b.logicalPath))
+}
+
+function stripFrontendPrefix(source) {
+  return source.replace(/^frontend\/src\//, "")
+}
+
+function defaultTargetForSource(manifest, source, kind) {
+  if (kind === "frontend") return `src/dypai-kits/${manifest.slug}/${stripFrontendPrefix(source)}`
+  if (kind === "backend") return `dypai/endpoints/${manifest.slug}/${source.split("/").pop()}`
+  if (kind === "database") return `dypai/kit-installations/${manifest.slug}/${manifest.version}/${source.split("/").pop()}`
+  return `.dypai/kits/${manifest.slug}/${source.split("/").pop()}`
+}
+
+function pluralize(word) {
+  if (!word) return word
+  if (word.endsWith("s")) return word
+  if (word.endsWith("y")) return `${word.slice(0, -1)}ies`
+  return `${word}s`
+}
+
+function namingContext(manifest, naming = {}) {
+  const adaptation = isObject(manifest.adaptation) ? manifest.adaptation : {}
+  const sourceEntity = adaptation.defaultEntity || normalizeList(adaptation.entityAliases)[0] || ""
+  const sourcePlural = adaptation.defaultEndpointPrefix || pluralize(sourceEntity)
+  const sourceTable = adaptation.defaultTableName || sourcePlural
+  const targetEntity = naming.entity || sourceEntity
+  const targetPlural = naming.endpointPrefix || pluralize(targetEntity)
+  const targetTable = naming.tableName || targetPlural
+  return { sourceEntity, sourcePlural, sourceTable, targetEntity, targetPlural, targetTable }
+}
+
+function replaceWholeWords(text, replacements) {
+  let out = text
+  for (const [from, to] of replacements) {
+    if (!from || !to || from === to) continue
+    out = out.replace(new RegExp(`\\b${from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g"), to)
+  }
+  return out
+}
+
+function adaptText(content, manifest, naming, kind) {
+  const n = namingContext(manifest, naming)
+  if (!n.sourceEntity && !n.sourcePlural && !n.sourceTable) return content
+  if (kind === "frontend") return content
+
+  if (kind === "backend") {
+    const withEndpointName = content.replace(/^name:\s*([a-z0-9-]+)\s*$/m, (_line, endpointName) => {
+      return `name: ${adaptTarget(endpointName, manifest, naming)}`
+    })
+    return replaceWholeWords(withEndpointName, [
+      [n.sourceTable, n.targetTable],
+      [n.sourceEntity, n.targetEntity],
+    ])
+  }
+
+  return replaceWholeWords(content, [
+    [n.sourceTable, n.targetTable],
+    [n.sourcePlural, n.targetTable],
+    [n.sourceEntity, n.targetEntity],
+  ])
+}
+
+function adaptTarget(target, manifest, naming) {
+  const n = namingContext(manifest, naming)
+  return replaceWholeWords(target, [
+    [n.sourcePlural, n.targetPlural],
+    [n.sourceEntity, n.targetEntity],
+    [n.sourceTable, n.targetTable],
+  ])
+}
+
+function installRecordPath(workspaceRoot) {
+  return join(workspaceRoot, ".dypai", "kits", "installed.json")
+}
+
+function readInstallRecord(workspaceRoot) {
+  const path = installRecordPath(workspaceRoot)
+  if (!existsSync(path)) return { schemaVersion: 1, kits: [] }
+  try {
+    const parsed = readJson(path)
+    if (isObject(parsed) && Array.isArray(parsed.kits)) return parsed
+  } catch {}
+  return { schemaVersion: 1, kits: [] }
+}
+
+function writeInstallRecord(workspaceRoot, record) {
+  const path = installRecordPath(workspaceRoot)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`)
+}
+
+function ownedTargets(record, slug, version) {
+  const targets = new Set()
+  for (const item of record.kits || []) {
+    if (item.slug === slug && item.version === version) {
+      for (const file of item.files || []) {
+        if (file.target) targets.add(file.target)
+      }
+    }
+  }
+  return targets
+}
+
+function writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind, overwrite, record, copied, skipped }) {
+  const targetAbs = safeTarget(workspaceRoot, targetRel)
+  const targetExists = existsSync(targetAbs)
+  if (targetExists) {
+    if (overwrite === "fail") throw new Error(`Target already exists: ${targetRel}`)
+    if (overwrite !== "replace" || !ownedTargets(record, manifest.slug, manifest.version).has(targetRel)) {
+      skipped.push(targetRel)
+      return
+    }
+  }
+
+  mkdirSync(dirname(targetAbs), { recursive: true })
+  const isText = /\.(tsx?|jsx?|ya?ml|json|md|sql|css|scss|html)$/i.test(sourceAbs)
+  if (isText) {
+    const content = adaptText(readFileSync(sourceAbs, "utf8"), manifest, naming, kind)
+    writeFileSync(targetAbs, content)
+  } else {
+    copyFileSync(sourceAbs, targetAbs)
+  }
+  copied.push(targetRel)
+}
+
+export const searchCapabilityKitsTool = {
+  name: "search_capability_kits",
+  description: "Search local DYPAI capability kits before building complex UI like calendars, maps, Kanban, upload flows, CRUD tables, dashboards, or editors.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Feature need and app domain, e.g. booking calendar for hotel reservations." },
+      limit: { type: "integer", default: DEFAULT_LIMIT, minimum: 1, maximum: 10 },
+      filters: { type: "object", description: "Optional filters: category, maturity, app_type, screen_type, feature_tag, requires." },
+      kits_root: { type: "string", description: "Optional local path to dypai-capability-kits. Defaults to DYPAI_CAPABILITY_KITS_ROOT or sibling repo." },
+    },
+    required: ["query"],
+  },
+  async execute({ query, limit = DEFAULT_LIMIT, filters = {}, kits_root }) {
+    const root = resolveKitsRoot(kits_root)
+    const kits = listKits(root)
+      .filter(({ manifest }) => matchesFilter(manifest, filters))
+      .map(({ manifest }) => ({ manifest, score: scoreKit(query, manifest) }))
+      .filter((item) => item.score > 0 || !query)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(1, Math.min(Number(limit) || DEFAULT_LIMIT, 10)))
+
+    return {
+      ok: true,
+      source: "local_repo",
+      kitsRoot: root,
+      count: kits.length,
+      kits: kits.map(({ manifest, score }) => ({
+        slug: manifest.slug,
+        version: manifest.version,
+        name: manifest.name,
+        category: manifest.category,
+        maturity: manifest.maturity,
+        description: manifest.description,
+        useWhen: manifest.useWhen,
+        provides: manifest.provides,
+        requires: manifest.requires,
+        dependencies: manifest.dependencies,
+        frontendManifest: manifest.frontendManifest,
+        backendManifest: manifest.backendManifest,
+        databaseManifest: manifest.databaseManifest,
+        score,
+      })),
+    }
+  },
+}
+
+function inspectCapabilityKit({ slug, version = "1.0.0", kits_root }) {
+  const root = resolveKitsRoot(kits_root)
+  const { dir, manifest } = loadKit(root, slug, version)
+  return {
+    ok: true,
+    operation: "inspect",
+    source: "local_repo",
+    kitsRoot: root,
+    kit: manifest,
+    assets: assetIndex(dir),
+    agentNotes: existsSync(join(dir, "agent.md")) ? readFileSync(join(dir, "agent.md"), "utf8") : undefined,
+    checklist: existsSync(join(dir, "verification", "checklist.md"))
+      ? readFileSync(join(dir, "verification", "checklist.md"), "utf8")
+      : undefined,
+  }
+}
+
+async function applyCapabilityKit({
+  slug,
+  version = "1.0.0",
+  targetFeature = "",
+  install = {},
+  naming = {},
+  target = {},
+  overwrite = "skip",
+  workspace_root,
+  kits_root,
+}) {
+  const root = resolveKitsRoot(kits_root)
+  const workspaceRoot = resolveWorkspaceRoot(workspace_root)
+  const { dir, manifest } = loadKit(root, slug, version)
+  const record = readInstallRecord(workspaceRoot)
+  const previousEntries = (record.kits || []).filter((item) => item.slug === manifest.slug && item.version === manifest.version)
+  const copied = []
+  const skipped = []
+
+  const installFrontend = install.frontend !== false
+  const installBackend = install.backend !== false
+  const installDatabase = install.database !== false
+
+  if (installFrontend) {
+    for (const asset of manifest.frontendManifest || []) {
+      const sourceAbs = join(dir, asset.source)
+      if (!existsSync(sourceAbs)) throw new Error(`Missing kit asset: ${asset.source}`)
+      let targetRel = asset.suggestedTarget || defaultTargetForSource(manifest, asset.source, "frontend")
+      if (target.frontendDir) {
+        targetRel = join(target.frontendDir, stripFrontendPrefix(asset.source)).split(sep).join("/")
+      }
+      writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "frontend", overwrite, record, copied, skipped })
+    }
+  }
+
+  if (installBackend) {
+    for (const asset of manifest.backendManifest || []) {
+      const sourceAbs = join(dir, asset.source)
+      if (!existsSync(sourceAbs)) throw new Error(`Missing kit asset: ${asset.source}`)
+      let targetRel = asset.suggestedTarget || defaultTargetForSource(manifest, asset.source, "backend")
+      targetRel = join(dirname(targetRel), adaptTarget(basename(targetRel), manifest, naming)).split(sep).join("/")
+      if (target.endpointDir) {
+        targetRel = join(target.endpointDir, adaptTarget(asset.source.split("/").pop(), manifest, naming)).split(sep).join("/")
+      }
+      writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "backend", overwrite, record, copied, skipped })
+    }
+  }
+
+  if (installDatabase && isObject(manifest.databaseManifest)) {
+    for (const key of ["schema", "seed"]) {
+      const source = manifest.databaseManifest[key]
+      if (!source) continue
+      const sourceAbs = join(dir, source)
+      if (!existsSync(sourceAbs)) throw new Error(`Missing kit asset: ${source}`)
+      let targetRel = defaultTargetForSource(manifest, source, "database")
+      if (target.databaseDir) {
+        targetRel = join(target.databaseDir, source.split("/").pop()).split(sep).join("/")
+      }
+      writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "database", overwrite, record, copied, skipped })
+    }
+  }
+
+  const imported = (manifest.frontendManifest || []).map((asset) => ({
+    name: asset.exportName,
+    from: target.frontendDir
+      ? `@/${join(target.frontendDir, stripFrontendPrefix(asset.source)).replace(/^src\//, "").replace(/\\/g, "/").replace(/\.(tsx?|jsx?)$/, "")}`
+      : asset.importPath,
+  })).filter((item) => item.name && item.from)
+
+  const backendEndpoints = (manifest.backendManifest || []).map((asset) =>
+    adaptTarget(asset.endpointName || asset.source.split("/").pop().replace(/\.ya?ml$/, ""), manifest, naming),
+  )
+  const databaseTables = normalizeList(manifest.databaseManifest?.tables).map((table) =>
+    adaptTarget(table, manifest, naming),
+  )
+
+  const previousFiles = previousEntries.flatMap((item) => Array.isArray(item.files) ? item.files : [])
+  const fileMap = new Map()
+  for (const file of previousFiles) {
+    if (file?.target) fileMap.set(file.target, file)
+  }
+  for (const targetPath of copied) {
+    fileMap.set(targetPath, { target: targetPath })
+  }
+
+  const entry = {
+    slug: manifest.slug,
+    version: manifest.version,
+    installedAt: new Date().toISOString(),
+    targetFeature,
+    files: [...fileMap.values()],
+    skippedFiles: skipped,
+    naming,
+  }
+  record.kits = (record.kits || []).filter((item) => !(item.slug === manifest.slug && item.version === manifest.version))
+  record.kits.push(entry)
+  writeInstallRecord(workspaceRoot, record)
+
+  const dependencies = manifest.dependencies || []
+
+  return {
+    ok: true,
+    operation: "apply",
+    slug: manifest.slug,
+    version: manifest.version,
+    workspaceRoot,
+    installed: {
+      files: copied,
+      skipped,
+      recordFile: ".dypai/kits/installed.json",
+    },
+    imports: imported,
+    backend: {
+      endpoints: backendEndpoints,
+      requiresPublish: Boolean(manifest.install?.requiresBackendPublish || backendEndpoints.length),
+    },
+    database: {
+      tables: databaseTables,
+      requiresExecuteSql: Boolean(manifest.install?.requiresExecuteSql || databaseTables.length),
+    },
+    dependencies,
+    nextSteps: [
+      ...(dependencies.length
+        ? [`Add any missing package dependencies to the target workspace package.json, then install them locally before building: ${dependencies.join(", ")}.`]
+        : []),
+      "Wire installed frontend components into the selected app page or route.",
+      ...(databaseTables.length ? ["Apply the installed schema SQL with execute_sql if the tables do not already exist."] : []),
+      ...(backendEndpoints.length ? ["Run backend validation and endpoint tests for installed/renamed endpoints."] : []),
+      "Run frontend verification after wiring imports and data callbacks.",
+    ],
+  }
+}
+
+export const manageCapabilityKitTool = {
+  name: "manage_capability_kit",
+  description: "Inspect or install a local DYPAI capability kit. Use operation='inspect' after search when you need full manifest details, then operation='apply' to copy editable source into the workspace. Apply never executes SQL, publishes backend, deploys frontend, or installs npm packages.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      operation: { type: "string", enum: ["inspect", "apply"], description: "inspect returns manifest/assets. apply copies kit files into the workspace." },
+      slug: { type: "string" },
+      version: { type: "string", default: "1.0.0" },
+      targetFeature: { type: "string", description: "Domain/feature being built, e.g. hotel reservations." },
+      install: {
+        type: "object",
+        properties: {
+          frontend: { type: "boolean", default: true },
+          backend: { type: "boolean", default: true },
+          database: { type: "boolean", default: true },
+          examples: { type: "boolean", default: false },
+        },
+      },
+      naming: {
+        type: "object",
+        properties: {
+          entity: { type: "string", description: "Singular domain entity, e.g. reservation." },
+          endpointPrefix: { type: "string", description: "Plural endpoint/table-friendly domain name, e.g. reservations." },
+          tableName: { type: "string", description: "Database table name, e.g. reservations." },
+        },
+      },
+      target: {
+        type: "object",
+        properties: {
+          frontendDir: { type: "string" },
+          endpointDir: { type: "string" },
+          databaseDir: { type: "string" },
+        },
+      },
+      overwrite: { type: "string", enum: ["skip", "fail", "replace"], default: "skip" },
+      workspace_root: { type: "string", description: "Optional absolute path to the target app workspace." },
+      kits_root: { type: "string", description: "Optional local path to dypai-capability-kits." },
+    },
+    required: ["operation", "slug"],
+  },
+  async execute(args) {
+    if (args?.operation === "inspect") return inspectCapabilityKit(args)
+    if (args?.operation === "apply") return applyCapabilityKit(args)
+    throw new Error("manage_capability_kit requires operation 'inspect' or 'apply'.")
+  },
+}

package/src/tools/sync/planner.js

@@ -14,6 +14,8 @@ import YAML from "yaml"
 import { proxyToolCall } from "../proxy.js"
 import { deserializeEndpoint, serializeEndpoint } from "./codec.js"
 
+const ENDPOINT_NAME_RE = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/
+
 // ─── Remote ────────────────────────────────────────────────────────────────
 
 async function execSql(projectId, sql) {
@@ -198,6 +200,76 @@ async function findEndpointYamls(endpointsDir) {
   return out
 }
 
+function endpointFileSlug(rel) {
+  const filename = rel.split("/").pop() || ""
+  return filename.replace(/\.ya?ml$/i, "")
+}
+
+function validateEndpointNameContract(rel, doc) {
+  const expectedName = endpointFileSlug(rel)
+  if (!doc || typeof doc !== "object") {
+    return {
+      rule: "endpoint_yaml_root_invalid",
+      loc: "root",
+      error: "endpoint YAML must parse to an object",
+    }
+  }
+
+  if (typeof doc.name !== "string") {
+    return {
+      rule: "endpoint_missing_name",
+      loc: "name",
+      error: `endpoint name must be a string and must match the file basename '${expectedName}'`,
+      fix_hint: `Set name: ${expectedName}. The endpoint name is the public API slug and must match the file basename.`,
+    }
+  }
+
+  const name = doc.name.trim()
+  if (!name) {
+    return {
+      rule: "endpoint_missing_name",
+      loc: "name",
+      error: `endpoint is missing name; use name: ${expectedName}`,
+      fix_hint: `Set name: ${expectedName}.`,
+    }
+  }
+  if (name !== doc.name || !ENDPOINT_NAME_RE.test(name)) {
+    return {
+      rule: "endpoint_invalid_name_slug",
+      loc: "name",
+      error: `endpoint name '${doc.name}' is not a valid API slug; use lowercase letters, numbers, hyphens, or underscores only, with no spaces`,
+      fix_hint: "Do not put human titles in `name`; use `description` for labels.",
+    }
+  }
+  if (name !== expectedName) {
+    return {
+      rule: "endpoint_name_file_mismatch",
+      loc: "name",
+      error: `endpoint name '${name}' must match file basename '${expectedName}'`,
+      fix_hint: `Use name: ${expectedName}, or rename the file so both match.`,
+    }
+  }
+  if (doc.id != null) {
+    if (typeof doc.id !== "string" || doc.id.trim() !== doc.id || !doc.id.trim()) {
+      return {
+        rule: "endpoint_invalid_id",
+        loc: "id",
+        error: "endpoint id must be a non-empty string without surrounding spaces when present",
+        fix_hint: "Prefer omitting `id` in endpoint YAML. If present, it must exactly match `name`.",
+      }
+    }
+    if (doc.id !== name) {
+      return {
+        rule: "endpoint_id_name_mismatch",
+        loc: "id",
+        error: `endpoint id '${doc.id}' must match name '${name}'`,
+        fix_hint: "Prefer omitting `id` in endpoint YAML. If present, keep id, name, and file basename identical.",
+      }
+    }
+  }
+  return null
+}
+
 export async function readLocalState(rootDir) {
   const endpointsDir = join(rootDir, "endpoints")
   const yamls = await findEndpointYamls(endpointsDir)
@@ -209,8 +281,9 @@ export async function readLocalState(rootDir) {
     try {
       const raw = await readFile(join(endpointsDir, rel), "utf8")
       const doc = YAML.parse(raw)
-      if (!doc?.name) {
-        errors.push({ file: rel, error: "missing 'name' field" })
+      const nameError = validateEndpointNameContract(rel, doc)
+      if (nameError) {
+        errors.push({ file: rel, ...nameError })
         continue
       }
 
@@ -227,7 +300,7 @@ export async function readLocalState(rootDir) {
       )
       const fileMap = Object.fromEntries(refs.map((p, i) => [p, contents[i]]))
 
-      byName[doc.name] = { doc, fileMap }
+      byName[doc.name] = { doc, fileMap, file: rel, group }
     } catch (e) {
       errors.push({ file: rel, error: e.message })
     }

package/src/tools/sync/validate.js

@@ -235,24 +235,26 @@ function isRawCodePlaceholderSource(source, loc) {
 }
 
 /**
- * Extract the first identifier (a-z, A-Z, _, 0-9 — JS-ident shape) from the
- * head of an expression, ignoring any trailing template filter or coalesce
- * operator. Examples:
- *   "input.limit | default(100)"  → "input.limit"
- *   "input.page ?? 1"              → "input.page"
- *   "nodes.foo.bar || 'x'"         → "nodes.foo.bar"
- *   "current_user_id | trim"       → "current_user_id"
- * Returns the trimmed/cleaned head (NOT just the leaf identifier — keeps
- * dotted paths intact so callers that split on '.' still work).
+ * Extract the first runtime path from an already-validated placeholder.
+ * Returns the trimmed/cleaned head (NOT just the leaf identifier), keeping
+ * dotted paths intact so callers that split on '.' still work.
  */
 function stripExprTail(expr) {
-  // Cut at the first character that can't be part of a path/identifier:
-  // whitespace, pipe (jinja-style filter), `?`, or `|`. Bracket access
-  // (e.g. items[0]) is preserved — callers split on '[' if they need to.
+  // Cut at the first character that can't be part of a path/identifier.
+  // Bracket access (e.g. items[0]) is preserved; callers split on '[' if
+  // they need to.
   const m = /^[\s]*([A-Za-z_$][A-Za-z_$0-9.\[\]]*)/.exec(expr)
   return m ? m[1] : expr.trim()
 }
 
+const RUNTIME_PLACEHOLDER_PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_-]*|\[[0-9]+\])*$/
+const RUNTIME_PLACEHOLDER_OPERATOR_RE = /(\|\||&&|\?\?|[?:+*/=<>!()]|\s+\b(?:or|and)\b\s+)/i
+
+function unsupportedRuntimePlaceholder(expr) {
+  const clean = expr.trim()
+  return expr !== clean || RUNTIME_PLACEHOLDER_OPERATOR_RE.test(clean) || !RUNTIME_PLACEHOLDER_PATH_RE.test(clean)
+}
+
 /** Minimal Levenshtein distance, caps at 3 for "did you mean" typo suggestions. */
 function levenshteinSmall(a, b) {
   if (a === b) return 0
@@ -407,11 +409,23 @@ function validateEndpoint(entry, ctx) {
   for (const { source, loc, value } of sources) {
     // --- Placeholder checks ---
     for (const expr of extractPlaceholders(value)) {
-      // Normalize: trim whitespace AND strip any template tail like
-      // ` | default(100)`, ` ?? 1`, ` || 'x'` — we only care about the
-      // path/identifier head. Without this, `${input.limit | default(100)}`
-      // would be parsed as property name "limit | default(100)" → false
-      // positive `input_placeholder_missing`.
+      if (unsupportedRuntimePlaceholder(expr)) {
+        diagnostics.push({
+          severity: "error",
+          rule: "unsupported_placeholder_expression",
+          endpoint: name, file, loc,
+          message: `\${${expr}} is not a simple runtime path the engine can resolve.`,
+          fix_hint:
+            `DYPAI placeholders are not JavaScript expressions. Use a single path like ` +
+            `\${input.file_path}, \${nodes.upload.storage_path}, or \${current_user_id}; ` +
+            `put fallback logic in the caller or split it into workflow nodes.`,
+        })
+        continue
+      }
+
+      // Normalize to the runtime path after rejecting expression syntax above.
+      // This keeps the downstream schema checks focused on the referenced
+      // input/node path instead of trying to interpret template logic.
       const e = stripExprTail(expr)
 
       // ${input.X} or ${input.X.Y}
@@ -1249,7 +1263,7 @@ export async function runValidation(rootDir, projectId) {
     schemaTables,
     catalog: nodeCatalog.schemas,
     knownTypes: nodeCatalog.knownTypes,
-    fileByName: Object.fromEntries(Object.values(local.byName).map(e => [e.doc.name, `endpoints/${e.doc.name}.yaml`])),
+    fileByName: Object.fromEntries(Object.values(local.byName).map(e => [e.doc.name, `endpoints/${e.file || `${e.doc.name}.yaml`}`])),
     // Collected during per-endpoint pass; resolved against the remote AFTER
     // all endpoints are checked (one batch query instead of N).
     suspectedMissingTables: [],
@@ -1329,9 +1343,11 @@ export async function runValidation(rootDir, projectId) {
   for (const err of local.errors || []) {
     diagnostics.push({
       severity: "error",
-      rule: "file_read_error",
+      rule: err.rule || "file_read_error",
       file: err.file,
+      loc: err.loc,
       message: err.error,
+      fix_hint: err.fix_hint,
     })
   }