devskill 2.0.2

package/scripts/cli.ts

@@ -0,0 +1,556 @@
+import { execSync } from 'node:child_process'
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import * as p from '@clack/prompts'
+import { collections, manual, submodules, vendors } from '../meta.ts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const root = join(__dirname, '..')
+
+function exec(cmd: string, cwd = root): string {
+  return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+}
+
+function execSafe(cmd: string, cwd = root): string | null {
+  try {
+    return exec(cmd, cwd)
+  }
+  catch {
+    return null
+  }
+}
+
+function getGitSha(dir: string): string | null {
+  return execSafe('git rev-parse HEAD', dir)
+}
+
+function submoduleExists(path: string): boolean {
+  const gitmodules = join(root, '.gitmodules')
+  if (!existsSync(gitmodules))
+    return false
+  const content = readFileSync(gitmodules, 'utf-8')
+  return content.includes(`path = ${path}`)
+}
+
+const RE_SUBMODULE_PATH = /path\s*=\s*(.+)/g
+
+function getExistingSubmodulePaths(): string[] {
+  const gitmodules = join(root, '.gitmodules')
+  if (!existsSync(gitmodules))
+    return []
+  const content = readFileSync(gitmodules, 'utf-8')
+  const matches = content.matchAll(RE_SUBMODULE_PATH)
+  return Array.from(matches, match => match[1].trim())
+}
+
+function removeSubmodule(submodulePath: string): void {
+  execSafe(`git submodule deinit -f ${submodulePath}`)
+  const gitModulesPath = join(root, '.git', 'modules', submodulePath)
+  if (existsSync(gitModulesPath)) {
+    rmSync(gitModulesPath, { recursive: true })
+  }
+  exec(`git rm -f ${submodulePath}`)
+}
+
+interface Project {
+  name: string
+  url: string
+  type: 'source' | 'vendor'
+  path: string
+}
+
+interface VendorConfig {
+  source: string
+  skills: Record<string, string>
+}
+
+async function initSubmodules(skipPrompt = false) {
+  const allProjects: Project[] = [
+    ...Object.entries(submodules).map(([name, url]) => ({
+      name,
+      url,
+      type: 'source' as const,
+      path: `sources/${name}`,
+    })),
+    ...Object.entries(vendors).map(([name, config]) => ({
+      name,
+      url: (config as VendorConfig).source,
+      type: 'vendor' as const,
+      path: `vendor/${name}`,
+    })),
+  ]
+
+  const spinner = p.spinner()
+
+  const existingSubmodulePaths = getExistingSubmodulePaths()
+  const expectedPaths = new Set(allProjects.map(p => p.path))
+  const extraSubmodules = existingSubmodulePaths.filter(path => !expectedPaths.has(path))
+
+  if (extraSubmodules.length > 0) {
+    p.log.warn(`Found ${extraSubmodules.length} submodule(s) not in meta.ts:`)
+    for (const path of extraSubmodules) {
+      p.log.message(`  - ${path}`)
+    }
+
+    const shouldRemove = skipPrompt
+      ? true
+      : await p.confirm({
+          message: 'Remove these extra submodules?',
+          initialValue: true,
+        })
+
+    if (p.isCancel(shouldRemove)) {
+      p.cancel('Cancelled')
+      return
+    }
+
+    if (shouldRemove) {
+      for (const submodulePath of extraSubmodules) {
+        spinner.start(`Removing submodule: ${submodulePath}`)
+        try {
+          removeSubmodule(submodulePath)
+          spinner.stop(`Removed: ${submodulePath}`)
+        }
+        catch (e) {
+          spinner.stop(`Failed to remove ${submodulePath}: ${e}`)
+        }
+      }
+    }
+  }
+
+  const newProjects = allProjects.filter(p => !submoduleExists(p.path))
+
+  if (newProjects.length === 0) {
+    p.log.info('All submodules already initialized')
+    return
+  }
+
+  const selected = skipPrompt
+    ? newProjects
+    : await p.multiselect({
+        message: 'Select projects to initialize',
+        options: newProjects.map(project => ({
+          value: project,
+          label: `${project.name} (${project.type})`,
+          hint: project.url,
+        })),
+        initialValues: newProjects,
+      })
+
+  if (p.isCancel(selected)) {
+    p.cancel('Cancelled')
+    return
+  }
+
+  for (const project of selected as Project[]) {
+    spinner.start(`Adding submodule: ${project.name}`)
+
+    const parentDir = join(root, dirname(project.path))
+    if (!existsSync(parentDir)) {
+      mkdirSync(parentDir, { recursive: true })
+    }
+
+    try {
+      exec(`git submodule add ${project.url} ${project.path}`)
+      spinner.stop(`Added: ${project.name}`)
+    }
+    catch (e) {
+      spinner.stop(`Failed to add ${project.name}: ${e}`)
+    }
+  }
+
+  p.log.success('Submodules initialized')
+}
+
+async function syncSubmodules() {
+  const spinner = p.spinner()
+
+  spinner.start('Updating submodules...')
+  try {
+    exec('git submodule update --remote --merge')
+    spinner.stop('Submodules updated')
+  }
+  catch (e) {
+    spinner.stop(`Failed to update submodules: ${e}`)
+    return
+  }
+
+  for (const [vendorName, config] of Object.entries(vendors)) {
+    const vendorConfig = config as VendorConfig
+    const vendorPath = join(root, 'vendor', vendorName)
+    const vendorSkillsPath = join(vendorPath, 'skills')
+
+    if (!existsSync(vendorPath)) {
+      p.log.warn(`Vendor submodule not found: ${vendorName}. Run init first.`)
+      continue
+    }
+
+    if (!existsSync(vendorSkillsPath)) {
+      p.log.warn(`No skills directory in vendor/${vendorName}/skills/`)
+      continue
+    }
+
+    for (const [sourceSkillName, outputSkillName] of Object.entries(vendorConfig.skills)) {
+      const sourceSkillPath = join(vendorSkillsPath, sourceSkillName)
+      const outputPath = join(root, 'skills', outputSkillName)
+
+      if (!existsSync(sourceSkillPath)) {
+        p.log.warn(`Skill not found: vendor/${vendorName}/skills/${sourceSkillName}`)
+        continue
+      }
+
+      spinner.start(`Syncing skill: ${sourceSkillName} → ${outputSkillName}`)
+
+      if (existsSync(outputPath)) {
+        rmSync(outputPath, { recursive: true })
+      }
+      mkdirSync(outputPath, { recursive: true })
+
+      const files = readdirSync(sourceSkillPath, { recursive: true, withFileTypes: true })
+      for (const file of files) {
+        if (file.isFile()) {
+          const fullPath = join(file.parentPath, file.name)
+          const relativePath = fullPath.replace(sourceSkillPath, '')
+          const destPath = join(outputPath, relativePath)
+          const destDir = dirname(destPath)
+          if (!existsSync(destDir)) {
+            mkdirSync(destDir, { recursive: true })
+          }
+          cpSync(fullPath, destPath)
+        }
+      }
+
+      const licenseNames = ['LICENSE', 'LICENSE.md', 'LICENSE.txt']
+      for (const licenseName of licenseNames) {
+        const licensePath = join(vendorPath, licenseName)
+        if (existsSync(licensePath)) {
+          cpSync(licensePath, join(outputPath, 'LICENSE.md'))
+          break
+        }
+      }
+
+      const sha = getGitSha(vendorPath)
+      const syncPath = join(outputPath, 'SYNC.md')
+      const date = new Date().toISOString().split('T')[0]
+      writeFileSync(syncPath, `# Sync Info\n\n- **Source:** \`vendor/${vendorName}/skills/${sourceSkillName}\`\n- **Git SHA:** \`${sha}\`\n- **Synced:** ${date}\n`)
+
+      spinner.stop(`Synced: ${sourceSkillName} → ${outputSkillName}`)
+    }
+  }
+
+  p.log.success('All skills synced')
+}
+
+async function checkUpdates() {
+  const spinner = p.spinner()
+  spinner.start('Fetching remote changes...')
+
+  try {
+    exec('git submodule foreach git fetch')
+    spinner.stop('Fetched remote changes')
+  }
+  catch {
+    spinner.stop('No submodules to fetch (or not a git repo)')
+    return
+  }
+
+  const updates: { name: string, type: string, behind: number }[] = []
+
+  for (const name of Object.keys(submodules)) {
+    const path = join(root, 'sources', name)
+    if (!existsSync(path))
+      continue
+    const behind = execSafe('git rev-list HEAD..@{u} --count', path)
+    const count = behind ? Number.parseInt(behind) : 0
+    if (count > 0)
+      updates.push({ name, type: 'source', behind: count })
+  }
+
+  for (const [name, config] of Object.entries(vendors)) {
+    const vendorConfig = config as VendorConfig
+    const path = join(root, 'vendor', name)
+    if (!existsSync(path))
+      continue
+    const behind = execSafe('git rev-list HEAD..@{u} --count', path)
+    const count = behind ? Number.parseInt(behind) : 0
+    if (count > 0) {
+      const skillNames = Object.values(vendorConfig.skills).join(', ')
+      updates.push({ name: `${name} (${skillNames})`, type: 'vendor', behind: count })
+    }
+  }
+
+  if (updates.length === 0) {
+    p.log.success('All submodules are up to date')
+  }
+  else {
+    p.log.info('Updates available:')
+    for (const update of updates) {
+      p.log.message(`  ${update.name} (${update.type}): ${update.behind} commits behind`)
+    }
+  }
+}
+
+function getExpectedSkillNames(): Set<string> {
+  const expected = new Set<string>()
+  for (const name of Object.keys(submodules))
+    expected.add(name)
+  for (const config of Object.values(vendors)) {
+    const vendorConfig = config as VendorConfig
+    for (const outputName of Object.values(vendorConfig.skills))
+      expected.add(outputName)
+  }
+  for (const name of manual)
+    expected.add(name)
+  return expected
+}
+
+function getExistingSkillNames(): string[] {
+  const skillsDir = join(root, 'skills')
+  if (!existsSync(skillsDir))
+    return []
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+}
+
+async function cleanup(skipPrompt = false) {
+  const spinner = p.spinner()
+  let hasChanges = false
+
+  const existingSkills = getExistingSkillNames()
+  const expectedSkills = getExpectedSkillNames()
+  const extraSkills = existingSkills.filter(name => !expectedSkills.has(name))
+
+  if (extraSkills.length > 0) {
+    p.log.warn(`Found ${extraSkills.length} skill(s) not in meta.ts:`)
+    for (const name of extraSkills) {
+      p.log.message(`  - skills/${name}`)
+    }
+
+    const shouldRemove = skipPrompt
+      ? true
+      : await p.confirm({
+          message: 'Remove these extra skills?',
+          initialValue: false,
+        })
+
+    if (p.isCancel(shouldRemove)) {
+      p.cancel('Cancelled')
+      return
+    }
+
+    if (shouldRemove) {
+      hasChanges = true
+      for (const skillName of extraSkills) {
+        spinner.start(`Removing skill: ${skillName}`)
+        try {
+          rmSync(join(root, 'skills', skillName), { recursive: true })
+          spinner.stop(`Removed: skills/${skillName}`)
+        }
+        catch (e) {
+          spinner.stop(`Failed to remove skills/${skillName}: ${e}`)
+        }
+      }
+    }
+  }
+
+  if (!hasChanges && extraSkills.length === 0) {
+    p.log.success('Everything is clean')
+  }
+  else if (hasChanges) {
+    p.log.success('Cleanup completed')
+  }
+}
+
+async function installSkills() {
+  const spinner = p.spinner()
+  
+  const allCollections: Record<string, string[]> = { ...collections }
+  for (const [vendorName, config] of Object.entries(vendors)) {
+    const vendorConfig = config as VendorConfig
+    allCollections[vendorName] = Object.values(vendorConfig.skills)
+  }
+
+  if (Object.keys(allCollections).length === 0) {
+    p.log.warn('No collections or vendors defined in meta.ts')
+    return
+  }
+
+  const selectedCollectionNames = await p.multiselect({
+    message: 'Select collections to install',
+    options: Object.keys(allCollections).map(name => ({
+      value: name,
+      label: name,
+      hint: `${allCollections[name].length} skills`
+    }))
+  })
+
+  if (p.isCancel(selectedCollectionNames)) {
+    p.cancel('Cancelled')
+    return
+  }
+
+  if (selectedCollectionNames.length === 0) {
+    p.log.warn('No collections selected')
+    return
+  }
+
+  const targetProject = await p.text({
+    message: 'Enter target project directory path (relative or absolute)',
+    initialValue: process.cwd(),
+    placeholder: process.cwd(),
+    validate: (value) => {
+      if (!value) return 'Path is required'
+      if (!existsSync(value)) return 'Directory does not exist'
+    }
+  })
+
+  if (p.isCancel(targetProject)) {
+    p.cancel('Cancelled')
+    return
+  }
+
+  const skillsDirName = await p.text({
+    message: 'Name of the skills directory inside target project?',
+    initialValue: 'skills',
+    placeholder: 'skills'
+  })
+
+  if (p.isCancel(skillsDirName)) {
+    p.cancel('Cancelled')
+    return
+  }
+
+  const selectedSkills = Array.from(new Set(
+    (selectedCollectionNames as string[]).flatMap(name => allCollections[name])
+  ))
+  const targetDir = join(targetProject as string, skillsDirName as string)
+
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true })
+  }
+
+  spinner.start(`Installing ${selectedSkills.length} skills to ${targetDir}...`)
+
+  let successCount = 0;
+  for (const skill of selectedSkills) {
+    const sourcePath = join(root, 'skills', skill)
+    if (!existsSync(sourcePath)) {
+      p.log.warn(`Skill not found: ${skill}`)
+      continue
+    }
+
+    const destPath = join(targetDir, skill)
+    if (existsSync(destPath)) {
+      rmSync(destPath, { recursive: true })
+    }
+    
+    mkdirSync(destPath, { recursive: true })
+    
+    const files = readdirSync(sourcePath, { recursive: true, withFileTypes: true })
+    for (const file of files) {
+      if (file.isFile()) {
+        const fullPath = join(file.parentPath, file.name)
+        const relativePath = fullPath.replace(sourcePath, '')
+        const dp = join(destPath, relativePath)
+        const dd = dirname(dp)
+        if (!existsSync(dd)) {
+          mkdirSync(dd, { recursive: true })
+        }
+        cpSync(fullPath, dp)
+      }
+    }
+    successCount++;
+  }
+
+  spinner.stop(`Installed ${successCount}/${selectedSkills.length} skills to target project`)
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const skipPrompt = args.includes('-y') || args.includes('--yes')
+  const command = args.find(arg => !arg.startsWith('-'))
+
+  if (command === 'init') {
+    p.intro('Skills Manager - Init')
+    await initSubmodules(skipPrompt)
+    p.outro('Done')
+    return
+  }
+
+  if (command === 'sync') {
+    p.intro('Skills Manager - Sync')
+    await syncSubmodules()
+    p.outro('Done')
+    return
+  }
+
+  if (command === 'check') {
+    p.intro('Skills Manager - Check')
+    await checkUpdates()
+    p.outro('Done')
+    return
+  }
+
+  if (command === 'cleanup') {
+    p.intro('Skills Manager - Cleanup')
+    await cleanup(skipPrompt)
+    p.outro('Done')
+    return
+  }
+
+  if (command === 'install') {
+    p.intro('Skills Manager - Install')
+    await installSkills()
+    p.outro('Done')
+    return
+  }
+
+  if (skipPrompt) {
+    p.log.error('Command required when using -y flag')
+    p.log.info('Available commands: install, init, sync, check, cleanup')
+    process.exit(1)
+  }
+
+  p.intro('Skills Manager')
+
+  const action = await p.select({
+    message: 'What would you like to do?',
+    options: [
+      { value: 'install', label: 'Install collections', hint: 'Copy skill collections to a local project' },
+      { value: 'sync', label: 'Sync submodules', hint: 'Pull latest and sync Type 2 skills' },
+      { value: 'init', label: 'Init submodules', hint: 'Add new submodules from meta.ts' },
+      { value: 'check', label: 'Check updates', hint: 'See available updates' },
+      { value: 'cleanup', label: 'Cleanup', hint: 'Remove skills not listed in meta.ts' },
+    ],
+  })
+
+  if (p.isCancel(action)) {
+    p.cancel('Cancelled')
+    process.exit(0)
+  }
+
+  switch (action) {
+    case 'install':
+      await installSkills()
+      break
+    case 'init':
+      await initSubmodules()
+      break
+    case 'sync':
+      await syncSubmodules()
+      break
+    case 'check':
+      await checkUpdates()
+      break
+    case 'cleanup':
+      await cleanup()
+      break
+  }
+
+  p.outro('Done')
+}
+
+main().catch(console.error)

package/skills/builderx_api-contexts/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: builderx_api-contexts
+description: Guide to Context logic structure in builderx_api.
+metadata:
+  author: AI Assistant
+  version: "2026.03.23"
+  source: Source code builderx_api
+---
+
+# BuilderX API Contexts
+
+> Conventions and structure for Ecto Contexts in the builderx_api project.
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Transactions and Outbox | Using Ecto.Multi for complex logic and logging Outbox messages | [core-multi-outbox](references/core-multi-outbox.md) |
+
+## Quick Reference
+
+```elixir
+defmodule BuilderxApi.SomeContext do
+  alias BuilderxApi.Citus, as: Repo
+  alias BuilderxApi.{Tools, Outbox}
+  alias Ecto.Multi
+
+  def create_something(attrs \\ %{}) do
+    multi =
+      Multi.new()
+      |> Multi.run(:changeset, fn _, _ ->
+        # Generate changeset
+        {:ok, Something.changeset(%Something{}, attrs)}
+      end)
+      |> Multi.run(:insert, fn _, %{changeset: changeset} ->
+        # Handle insert
+        Repo.insert(changeset, returning: true)
+      end)
+      |> Multi.run(:changelog, fn _, %{changeset: changeset, insert: insert_res} ->
+        # Write outbox log
+        %{
+          queue: "sync_to_questdb",
+          args: %{
+            action: "something_changelog",
+            data: %{
+              id: Ecto.UUID.generate(),
+              action: "CREATE",
+              changes: changeset.changes,
+              record_id: insert_res.id,
+              site_id: insert_res.site_id,
+            }
+          }
+        }
+        |> Outbox.new()
+      end)
+
+    case Repo.transaction(multi) do
+      {:ok, res} -> {:ok, res.insert}
+      err -> {:error, err}
+    end
+  end
+end
+```

package/skills/builderx_api-contexts/references/core-multi-outbox.md

@@ -0,0 +1,57 @@
+---
+name: core-multi-outbox
+description: Standard usage of Ecto.Multi and Outbox Pattern in builderx_api Contexts.
+---
+
+# Core Contexts - Multi and Outbox
+
+Context objects in `builderx_api` are often very large and contain complex logic requiring multiple steps within a shared transaction.
+
+## 1. Using Ecto.Multi
+
+For any complex create/update action that modifies logs or synchronize data with other systems, we use `Ecto.Multi`. Always separate the logic that creates the `Changeset` into an independent step.
+
+```elixir
+Multi.new()
+|> Multi.run(:changeset, fn _, _ ->
+  {:ok, Product.changeset(%Product{}, attrs)}
+end)
+|> Multi.run(:product, fn _, %{changeset: changeset} ->
+  Repo.insert(changeset, returning: true)
+end)
+```
+
+## 2. Writing Outbox Messages
+
+The project uses `Outbox.new/1` to save messages to PostgreSQL (implementing the Outbox pattern). A background worker will then scan this table to execute the messages.
+
+```elixir
+|> Multi.run(:changelog, fn _, %{changeset: changeset, product: product} ->
+  %{
+    queue: "sync_to_questdb",
+    args: %{
+      action: "products_changelog",
+      data: %{
+        id: Ecto.UUID.generate(),
+        action: "CREATE", # or "UPDATE"
+        changes: changeset.changes,
+        record_id: product.id,
+        site_id: product.site_id,
+        account_id: Process.get(:account_id),
+        stacktrace: BuilderxApi.Tools.get_stacktrace(),
+        inserted_at: product.updated_at
+      }
+    }
+  }
+  |> Outbox.new()
+end)
+```
+
+**Note:** Always pass `account_id` if available (via `Process.get(:account_id)`) and the stacktrace (via `Tools.get_stacktrace()`).
+Use configuration flags like `allow_quest_db` or conditionally build the Outbox struct if the business logic requires it.
+
+## 3. Tools Module
+
+For handling input data, contexts frequently leverage the `Tools` module:
+- `Tools.is_empty?(list_or_map_or_string)`: Check if a data structure is empty.
+- `Tools.to_atom_keys_map(attrs)`: Ensure parameter keys are converted to atoms.