@dypai-ai/mcp 1.5.19 → 1.5.23

package/src/tools/project-artifacts.js

@@ -0,0 +1,627 @@
+import crypto from "crypto"
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync, rmSync } from "fs"
+import { tmpdir } from "os"
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "path"
+import { fileURLToPath } from "url"
+import { proxyToolCall } from "./proxy.js"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+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 installFolderKey(slug) {
+  return String(slug || "").replace(/^kit-/, "")
+}
+
+function manifestFromModuleContract(contract) {
+  const mount = Array.isArray(contract?.mount_contract?.manifest) ? contract.mount_contract.manifest : []
+  const frontendManifest = []
+  const backendManifest = []
+  const databaseManifest = {}
+  for (const entry of mount) {
+    if (!entry?.source) continue
+    const source = String(entry.source)
+    const role = String(entry.role || "")
+    if (role === "endpoint" || source.includes("/endpoints/")) {
+      backendManifest.push({
+        source,
+        suggestedTarget: entry.target,
+        endpointName: entry.export_name || basename(source).replace(/\.ya?ml$/i, ""),
+      })
+      continue
+    }
+    if (source.endsWith(".sql")) {
+      if (source.includes("schema.sql")) databaseManifest.schema = source
+      if (source.includes("seed.sql")) databaseManifest.seed = source
+      continue
+    }
+    frontendManifest.push({
+      source,
+      suggestedTarget: entry.target,
+      exportName: entry.export_name,
+      importPath: entry.import_path,
+      role,
+    })
+  }
+
+  const shellDeps = contract.requires?.shell_dependencies
+  const dependencies = Array.isArray(shellDeps)
+    ? shellDeps
+    : Array.isArray(contract.requires?.shell_provides)
+      ? contract.requires.shell_provides.filter((item) => typeof item === "string" && !item.startsWith("credential:"))
+      : []
+
+  return {
+    schemaVersion: 1,
+    slug: contract.slug,
+    version: contract.version || "1.0.0",
+    name: contract.name,
+    kitType: contract.module_kind || "feature",
+    category: contract.category,
+    maturity: contract.maturity,
+    description: contract.description,
+    useWhen: contract.selection?.use_when,
+    avoidWhen: contract.selection?.avoid_when,
+    userFacingSummary: contract.agent_brief?.summary,
+    agentInstructions: contract.agent_brief?.instructions,
+    provides: contract.provides?.capabilities || [],
+    requires: dependencies,
+    dependencies,
+    frontendManifest,
+    backendManifest,
+    databaseManifest,
+    install: {
+      requiresExecuteSql: Boolean(databaseManifest.schema || databaseManifest.seed),
+      requiresBackendPublish: backendManifest.length > 0,
+    },
+  }
+}
+
+function appendKitInstallationSql(manifest, artifactDir, contract) {
+  const folderKey = installFolderKey(contract.slug)
+  const ver = contract.version || "1.0.0"
+  const schemaRel = `files/dypai/kit-installations/${folderKey}/${ver}/schema.sql`
+  const seedRel = `files/dypai/kit-installations/${folderKey}/${ver}/seed.sql`
+  if (!isObject(manifest.databaseManifest)) manifest.databaseManifest = {}
+  if (existsSync(join(artifactDir, schemaRel))) manifest.databaseManifest.schema = schemaRel
+  if (existsSync(join(artifactDir, seedRel))) manifest.databaseManifest.seed = seedRel
+  if (manifest.databaseManifest.schema || manifest.databaseManifest.seed) {
+    manifest.install = { ...(manifest.install || {}), requiresExecuteSql: true }
+  }
+}
+
+function loadArtifactFromDir(artifactDir) {
+  const contractPath = join(artifactDir, "module.contract.json")
+  const templatePath = join(artifactDir, "template.contract.json")
+  const contractFile = existsSync(contractPath) ? contractPath : templatePath
+  if (!existsSync(contractFile)) throw new Error(`Missing contract in ${artifactDir}`)
+  const contract = readJson(contractFile)
+  const manifest = manifestFromModuleContract(contract)
+  appendKitInstallationSql(manifest, artifactDir, contract)
+  return { dir: artifactDir, manifest }
+}
+
+async function materializeArtifactFromGithub({ source_repo, source_path, source_ref }) {
+  const repo = String(source_repo || "").trim()
+  if (!repo) {
+    throw new Error("source_repo is required from search_project_artifacts (e.g. dyapps-codes/artifacts).")
+  }
+  const path = String(source_path || "").trim()
+  const ref = String(source_ref || "main").trim() || "main"
+
+  const remote = await proxyToolCall("fetch_project_artifact", {
+    source_repo: repo,
+    source_path: path,
+    source_ref: ref,
+  })
+  if (!isObject(remote) || !remote.ok) {
+    throw new Error(isObject(remote) && remote.error ? remote.error : "fetch_project_artifact failed")
+  }
+
+  const key = crypto.createHash("sha256").update(`${repo}|${path}|${ref}`).digest("hex")
+  const artifactDir = join(tmpdir(), "dypai-artifact-fetch", key)
+  rmSync(artifactDir, { recursive: true, force: true })
+  mkdirSync(artifactDir, { recursive: true })
+
+  for (const file of remote.files || []) {
+    if (!file?.path || typeof file.content !== "string") continue
+    const target = join(artifactDir, String(file.path))
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, file.content)
+  }
+
+  if (isObject(remote.contract)) {
+    const contractPath = join(artifactDir, "module.contract.json")
+    if (!existsSync(contractPath)) {
+      writeFileSync(contractPath, `${JSON.stringify(remote.contract, null, 2)}\n`)
+    }
+  }
+
+  const loaded = loadArtifactFromDir(artifactDir)
+  return {
+    ...loaded,
+    source: "github",
+    source_repo: repo,
+    source_path: path,
+    source_ref: ref,
+    agentNotes: typeof remote.agent_notes === "string" ? remote.agent_notes : undefined,
+    checklist: typeof remote.checklist === "string" ? remote.checklist : undefined,
+  }
+}
+
+async function lookupArtifactGithubSource(slug) {
+  const wanted = String(slug || "").trim()
+  if (!wanted) throw new Error("slug is required.")
+
+  const remote = await proxyToolCall("search_project_artifacts", { query: wanted, limit: 20 })
+  if (!isObject(remote) || remote.ok === false) {
+    throw new Error(isObject(remote) && remote.error ? remote.error : "search_project_artifacts failed")
+  }
+
+  const pools = [remote.artifacts, remote.features, remote.bases].filter(Array.isArray)
+  for (const pool of pools) {
+    const hit = pool.find((item) => isObject(item) && String(item.slug || "").trim() === wanted)
+    if (hit?.source_repo) {
+      return {
+        source_repo: String(hit.source_repo).trim(),
+        source_path: String(hit.source_path || "").trim(),
+        source_ref: String(hit.source_ref || "main").trim() || "main",
+      }
+    }
+  }
+  throw new Error(`Artifact "${wanted}" not found in catalog. Call search_project_artifacts first.`)
+}
+
+async function resolveArtifactInstallation({ slug, source_repo, source_path, source_ref }) {
+  const resolved = String(source_repo || "").trim()
+    ? {
+        source_repo: String(source_repo).trim(),
+        source_path: String(source_path || "").trim(),
+        source_ref: String(source_ref || "main").trim() || "main",
+      }
+    : await lookupArtifactGithubSource(slug)
+  return materializeArtifactFromGithub(resolved)
+}
+
+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 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 resolveArtifactAssetPath(artifactDir, source) {
+  const candidates = [source]
+  if (source.includes("/endpoints/endpoints/")) {
+    candidates.push(source.replace("/endpoints/endpoints/", "/endpoints/"))
+  }
+  const nested = source.match(/^files\/dypai\/endpoints\/([^/]+)\/endpoints\/(.+)$/)
+  if (nested) candidates.push(`files/dypai/endpoints/${nested[1]}/${nested[2]}`)
+  for (const candidate of candidates) {
+    const full = join(artifactDir, candidate)
+    if (existsSync(full)) return full
+  }
+  throw new Error(`Missing artifact asset: ${source}`)
+}
+
+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", "artifacts", "installed.json")
+}
+
+function readInstallRecord(workspaceRoot) {
+  const path = installRecordPath(workspaceRoot)
+  if (!existsSync(path)) return { schemaVersion: 2, artifacts: [] }
+  try {
+    const parsed = readJson(path)
+    if (isObject(parsed) && Array.isArray(parsed.artifacts)) return parsed
+  } catch {}
+  return { schemaVersion: 2, artifacts: [] }
+}
+
+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.artifacts || []) {
+    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 false
+    }
+  }
+
+  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)
+  return true
+}
+
+async function inspectProjectArtifact({ slug, version = "1.0.0", source_repo, source_path, source_ref }) {
+  const { dir, manifest, source, agentNotes, checklist } = await resolveArtifactInstallation({ slug, source_repo, source_path, source_ref })
+  return {
+    ok: true,
+    operation: "inspect",
+    source,
+    artifactRoot: dir,
+    artifact: manifest,
+    assets: assetIndex(dir),
+    agentNotes: agentNotes || (existsSync(join(dir, "agent.md")) ? readFileSync(join(dir, "agent.md"), "utf8") : undefined),
+    checklist: checklist || (existsSync(join(dir, "verification", "checklist.md"))
+      ? readFileSync(join(dir, "verification", "checklist.md"), "utf8")
+      : undefined),
+  }
+}
+
+async function applyProjectArtifact({
+  slug,
+  version = "1.0.0",
+  targetFeature = "",
+  install = {},
+  naming = {},
+  target = {},
+  overwrite = "skip",
+  workspace_root,
+  source_repo,
+  source_path,
+  source_ref,
+}) {
+  const { dir, manifest, source } = await resolveArtifactInstallation({ slug, source_repo, source_path, source_ref })
+  const workspaceRoot = resolveWorkspaceRoot(workspace_root)
+  const record = readInstallRecord(workspaceRoot)
+  const previousEntries = (record.artifacts || []).filter((item) => item.slug === manifest.slug && item.version === manifest.version)
+  const copied = []
+  const copiedByKind = {
+    frontend: [],
+    backend: [],
+    database: [],
+  }
+  const databaseTargetsBySource = new Map()
+  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 = resolveArtifactAssetPath(dir, asset.source)
+      let targetRel = asset.suggestedTarget || defaultTargetForSource(manifest, asset.source, "frontend")
+      if (target.frontendDir) {
+        targetRel = join(target.frontendDir, stripFrontendPrefix(asset.source)).split(sep).join("/")
+      }
+      if (writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "frontend", overwrite, record, copied, skipped })) {
+        copiedByKind.frontend.push(targetRel)
+      }
+    }
+  }
+
+  if (installBackend) {
+    for (const asset of manifest.backendManifest || []) {
+      const sourceAbs = resolveArtifactAssetPath(dir, 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("/")
+      }
+      if (writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "backend", overwrite, record, copied, skipped })) {
+        copiedByKind.backend.push(targetRel)
+      }
+    }
+  }
+
+  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("/")
+      }
+      if (writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "database", overwrite, record, copied, skipped })) {
+        copiedByKind.database.push(targetRel)
+        databaseTargetsBySource.set(source, targetRel)
+      }
+    }
+  }
+
+  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 schemaSource = installDatabase && isObject(manifest.databaseManifest) && typeof manifest.databaseManifest.schema === "string"
+    ? manifest.databaseManifest.schema
+    : ""
+  const seedSource = installDatabase && isObject(manifest.databaseManifest) && typeof manifest.databaseManifest.seed === "string"
+    ? manifest.databaseManifest.seed
+    : ""
+  const schemaFile = schemaSource ? databaseTargetsBySource.get(schemaSource) : undefined
+  const seedFile = seedSource ? databaseTargetsBySource.get(seedSource) : undefined
+
+  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.artifacts = (record.artifacts || []).filter((item) => !(item.slug === manifest.slug && item.version === manifest.version))
+  record.artifacts.push(entry)
+  writeInstallRecord(workspaceRoot, record)
+
+  const dependencies = manifest.dependencies || []
+
+  return {
+    ok: true,
+    operation: "apply",
+    source,
+    slug: manifest.slug,
+    version: manifest.version,
+    workspaceRoot,
+    installed: {
+      files: copied,
+      frontendFiles: copiedByKind.frontend,
+      backendFiles: copiedByKind.backend,
+      databaseFiles: copiedByKind.database,
+      skipped,
+      recordFile: ".dypai/artifacts/installed.json",
+    },
+    imports: imported,
+    backend: {
+      endpoints: backendEndpoints,
+      requiresPublish: Boolean(manifest.install?.requiresBackendPublish || backendEndpoints.length),
+    },
+    database: {
+      tables: databaseTables,
+      sqlFiles: copiedByKind.database,
+      schemaFile,
+      seedFile,
+      requiresExecuteSql: Boolean(manifest.install?.requiresExecuteSql || databaseTables.length),
+      applyWith: "execute_sql",
+      schemaRefresh: "automatic_after_successful_ddl",
+    },
+    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 ? [
+        `Before backend tests, ensure tables exist (${databaseTables.join(", ")}): read ${schemaFile || "the installed schema SQL"} and execute its safe CREATE/ALTER statements with execute_sql. Do not edit dypai/schema.sql; it refreshes automatically.`,
+      ] : []),
+      ...(backendEndpoints.length ? ["Run backend validation and endpoint tests for installed/renamed endpoints."] : []),
+      "Run frontend verification after wiring imports and data callbacks.",
+    ],
+  }
+}
+
+export const manageProjectArtifactTool = {
+  name: "manage_project_artifact",
+  description: "Inspect or install a project artifact into the workspace. Call search_project_artifacts first, then pass the exact slug; the platform resolves GitHub source server-side. 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 artifact files into the workspace." },
+      slug: { type: "string", description: "Exact artifact slug from search_project_artifacts (e.g. kit-pricing-stripe)." },
+      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." },
+    },
+    required: ["operation", "slug"],
+  },
+  async execute(args) {
+    if (args?.operation === "inspect") return inspectProjectArtifact(args)
+    if (args?.operation === "apply") return applyProjectArtifact(args)
+    throw new Error("manage_project_artifact requires operation 'inspect' or 'apply'.")
+  },
+}

package/src/tools/sync/codec.js

@@ -205,6 +205,7 @@ export function serializeEndpoint(row, mapsCtx) {
   }
   if (row.input) doc.input = row.input
   if (row.output) doc.output = row.output
+  if (row.response_cardinality) doc.response_cardinality = row.response_cardinality
   doc.trigger = triggersToYaml(wf.execution_config?.triggers)
 
   const workflow = { nodes }
@@ -354,6 +355,7 @@ export function deserializeEndpoint(doc, mapsCtx) {
     workflow_code,
     input: doc.input || null,
     output: doc.output || null,
+    response_cardinality: doc.response_cardinality || null,
     allowed_roles: doc.allowed_roles || [],
     // Accept both `tool: true` (canonical) and `is_tool: true` (engine-style).
     // Without this, an agent that wrote `is_tool` in YAML would silently get

package/src/tools/sync/pull.js

@@ -194,6 +194,7 @@ input:
 
 # ─── Output schema (optional but recommended) ───────────────────────────────
 # Describes the response shape. Helps the validator + frontend type-checkers.
+# This is the PUBLIC HTTP body (what dypai.api.*().data receives).
 output:
   type: object
   properties:
@@ -201,6 +202,15 @@ output:
     total:    { type: number }
     status:   { type: string }
 
+# ─── Public response cardinality (optional) ───────────────────────────────────
+# Only needed when the return node is dypai_database (SQL row arrays) and
+# output.type is object. The engine unwraps [{...}] -> {...} at the HTTP boundary.
+#   response_cardinality: single      # one row / INSERT RETURNING *
+#   response_cardinality: many        # public body is an array (output.type: array)
+#   response_cardinality: zero_or_one # lookup; [] -> null
+# Prefer set_fields (see build_response below) when composing { items, total, ... }.
+# Node-level output_cardinality is internal-only for \${nodes.<id>.field} placeholders.
+
 # ─── Workflow ───────────────────────────────────────────────────────────────
 # Nodes are the steps. Placeholders wire data flow between them:
 #
@@ -600,7 +610,7 @@ export const dypaiPullTool = {
     const [endpoints, credentials, groups, schemaSql, nodeCatalogResult, realtimePolicies, draftsResult] = await Promise.all([
       execSql(project_id, `
         SELECT id, name, method, description, workflow_code, input, output,
-               allowed_roles, is_tool, tool_description, group_id, is_active, updated_at
+               response_cardinality, allowed_roles, is_tool, tool_description, group_id, is_active, updated_at
         FROM system.endpoints
         ORDER BY name
       `),

package/src/tools/sync/push.js

@@ -57,6 +57,7 @@ function endpointPayload(row) {
   if (row.group_id) p.group_id = row.group_id
   if (row.input) p.input = row.input
   if (row.output) p.output = row.output
+  if (row.response_cardinality) p.response_cardinality = row.response_cardinality
   return p
 }