@meistrari/tela-build 1.30.3 → 1.31.0

package/lib/__tests__/doc-generator.test.ts

@@ -26,7 +26,7 @@ describe('generateDocsToDirectory', () => {
 
         expect(parsed.data).toMatchObject({
             name: 'tela-build',
-            description: expect.stringContaining('repository: ask for component props'),
+            description: expect.stringContaining('Ask for component props'),
         })
         expect(skillMd).toContain('description: "')
     })

package/lib/doc-generator.ts

@@ -7,6 +7,7 @@ import { getTypeResolver } from './type-resolver'
 import type { TypeResolver } from './type-resolver'
 import { createVolarExtractor } from './extractors/volar-extract'
 import type { VolarExtractor } from './extractors/volar-extract'
+import { telaBuildSkill } from './tela-build-skill'
 
 const colors = {
     gray: '\x1B[90m',
@@ -516,7 +517,7 @@ export function generateDocsToDirectory(componentDocs: ComponentDoc[], typeResol
     }
 
     // Single Skill: tela-build
-    const skillDir = join(outDir, 'tela-build')
+    const skillDir = join(outDir, telaBuildSkill.name)
     const supportingDir = join(skillDir, 'components')
     if (!existsSync(supportingDir)) {
         mkdirSync(supportingDir, { recursive: true })
@@ -562,27 +563,21 @@ export function generateDocsToDirectory(componentDocs: ComponentDoc[], typeResol
     }
 
     // Create SKILL.md describing Tela Build with links to supporting md
-    const skillDescription = buildTelaBuildSkillDescription()
     const body = dedent`
 # Tela Build
 
 This Skill provides structured documentation for the Tela Build component library (Vue 3 + Nuxt).
 Use it when building, refactoring, or using Tela components — props, events, slots, and examples are included where available.
 
-## Instructions
-
-- IMPORTANT: Before making ANY UI change or introducing NEW UI, ALWAYS consult this Tela Build components index first.
-- Prefer reusing existing Tela components and patterns. Only create new components when a clear gap exists.
-- When a new component is needed, align with existing naming, props, events, and patterns documented here.
-- Keep this documentation current when components are added or changed (update supporting files under \
-  \`components/\`).
-
 ## Components Index
 
 ${componentLinks.join('\n')}${docsSection}
   `
 
-    const skillMd = wrapWithSkillFrontmatter({ name: 'tela-build', description: skillDescription }, body)
+    const skillMd = wrapWithSkillFrontmatter({
+        name: telaBuildSkill.name,
+        description: telaBuildSkill.description,
+    }, body)
     writeFileSync(join(skillDir, 'SKILL.md'), skillMd, 'utf-8')
 }
 
@@ -691,7 +686,7 @@ function wrapWithSkillFrontmatter(meta: { name: string, description: string, all
     const lines: string[] = []
     lines.push('---')
     lines.push(`name: ${sanitizeSkillName(name)}`)
-    lines.push(`description: ${serializeYamlString(sanitizeDescription(description))}`)
+    lines.push(`description: ${quoteFrontmatterString(sanitizeDescription(description))}`)
     if (allowedTools && allowedTools.length > 0) {
         lines.push(`allowed-tools: ${allowedTools.join(', ')}`)
     }
@@ -703,26 +698,18 @@ function wrapWithSkillFrontmatter(meta: { name: string, description: string, all
     return lines.join('\n')
 }
 
-function serializeYamlString(value: string): string {
-    return JSON.stringify(value)
-}
-
 function sanitizeSkillName(name: string): string {
     // Lowercase + hyphens + digits only, max 64 chars
     return name.toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 64).replace(/-{2,}/g, '-')
 }
 
 function sanitizeDescription(desc: string): string {
-    const trimmed = desc.replace(/\s+/g, ' ').trim()
+    const trimmed = desc.replace(/\r\n?/g, '\n').trim()
     return trimmed.slice(0, 1024)
 }
 
-function buildTelaBuildSkillDescription(): string {
-    const base = 'Documentation and usage references for the Tela Build component library (Vue 3 + Nuxt). '
-        + 'Always consult this Tela Build index BEFORE making any UI changes or creating new UI. '
-        + 'Use when working on UI in this repository: ask for component props, events, slots, or examples. '
-        + 'Supporting files under components/ contain per-component details.'
-    return sanitizeDescription(base)
+function quoteFrontmatterString(value: string): string {
+    return JSON.stringify(value)
 }
 
 function toGroupSlugFromKebab(kebab: string): string {

package/lib/tela-build-skill.ts

@@ -0,0 +1,8 @@
+export const telaBuildSkill = {
+    name: 'tela-build',
+    description: [
+        'Use when working on any UI in this repository. Ask for component props, slots, variants, and usage examples.',
+        'Always consult this Tela Build index BEFORE making any UI changes or creating new UI.',
+        'Use it for components, layouts, styling, interactions, and design-token decisions.',
+    ].join('\n'),
+} as const

package/modules/tela-build-docs/__tests__/ensure-claude-symlink.test.ts

@@ -0,0 +1,122 @@
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    mkdtempSync,
+    readlinkSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+    readFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'pathe'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { ensureClaudeSymlink } from '../index'
+
+const tempDirs: string[] = []
+const logger = { log: vi.fn() }
+const colors = { gray: '', orange: '', green: '', cyan: '', yellow: '', purple: '', reset: '' }
+
+function makeTempRoot() {
+    const dir = mkdtempSync(join(tmpdir(), 'claude-symlink-'))
+    tempDirs.push(dir)
+
+    return dir
+}
+
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true })
+    }
+
+    logger.log.mockClear()
+})
+
+describe('ensureClaudeSymlink', () => {
+    it('creates .agents and symlinks .claude → .agents when neither exists', () => {
+        const root = makeTempRoot()
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(existsSync(join(root, '.agents'))).toBe(true)
+        expect(lstatSync(join(root, '.claude')).isSymbolicLink()).toBe(true)
+        expect(readlinkSync(join(root, '.claude'))).toBe('.agents')
+    })
+
+    it('creates .claude symlink when .agents already exists', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents'))
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(lstatSync(join(root, '.claude')).isSymbolicLink()).toBe(true)
+        expect(readlinkSync(join(root, '.claude'))).toBe('.agents')
+    })
+
+    it('does nothing when .claude is already a symlink', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents'))
+        symlinkSync('.agents', join(root, '.claude'))
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(lstatSync(join(root, '.claude')).isSymbolicLink()).toBe(true)
+        expect(logger.log).not.toHaveBeenCalled()
+    })
+
+    it('symlinks .claude/skills → .agents/skills when .claude is a real directory', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents/skills'), { recursive: true })
+        mkdirSync(join(root, '.claude'), { recursive: true })
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        const skillsLink = join(root, '.claude/skills')
+
+        expect(lstatSync(skillsLink).isSymbolicLink()).toBe(true)
+        expect(existsSync(skillsLink)).toBe(true)
+    })
+
+    it('skips skill symlink when .claude/skills already exists', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents/skills'), { recursive: true })
+        mkdirSync(join(root, '.claude/skills'), { recursive: true })
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(lstatSync(join(root, '.claude/skills')).isDirectory()).toBe(true)
+        expect(lstatSync(join(root, '.claude/skills')).isSymbolicLink()).toBe(false)
+    })
+
+    it('creates .agents/skills when .claude is a directory but .agents/skills does not exist', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents'), { recursive: true })
+        mkdirSync(join(root, '.claude'), { recursive: true })
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(existsSync(join(root, '.agents/skills'))).toBe(true)
+        expect(lstatSync(join(root, '.claude/skills')).isSymbolicLink()).toBe(true)
+    })
+
+    it('skill files in .agents/skills are accessible through .claude/skills symlink', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents/skills/tela-build'), { recursive: true })
+        writeFileSync(join(root, '.agents/skills/tela-build/SKILL.md'), '# Test')
+        mkdirSync(join(root, '.claude'), { recursive: true })
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        const content = readFileSync(join(root, '.claude/skills/tela-build/SKILL.md'), 'utf-8')
+
+        expect(content).toBe('# Test')
+    })
+})

package/modules/tela-build-docs/__tests__/resolve-repository-root.test.ts

@@ -0,0 +1,71 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'pathe'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { resolveRepositoryRoot } from '../index'
+
+const tempDirs: string[] = []
+
+function makeTempRoot() {
+    const dir = mkdtempSync(join(tmpdir(), 'resolve-repository-root-'))
+    tempDirs.push(dir)
+
+    return dir
+}
+
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true })
+    }
+})
+
+describe('resolveRepositoryRoot', () => {
+    it('prefers Nuxt workspaceDir for monorepos running without .git in Docker', () => {
+        const workspaceRoot = makeTempRoot()
+        const appDir = join(workspaceRoot, 'apps/web')
+
+        mkdirSync(appDir, { recursive: true })
+
+        expect(resolveRepositoryRoot(appDir, workspaceRoot)).toBe(workspaceRoot)
+    })
+
+    it('detects workspace roots from .git markers', () => {
+        const workspaceRoot = makeTempRoot()
+        const appDir = join(workspaceRoot, 'apps/web')
+
+        mkdirSync(appDir, { recursive: true })
+        writeFileSync(join(workspaceRoot, '.git'), 'gitdir: ../.git/worktrees/test\n')
+
+        expect(resolveRepositoryRoot(appDir)).toBe(workspaceRoot)
+    })
+
+    it('detects workspace roots from pnpm-workspace.yaml', () => {
+        const workspaceRoot = makeTempRoot()
+        const appDir = join(workspaceRoot, 'apps/web')
+
+        mkdirSync(appDir, { recursive: true })
+        writeFileSync(join(workspaceRoot, 'pnpm-workspace.yaml'), 'packages:\n  - apps/*\n')
+
+        expect(resolveRepositoryRoot(appDir)).toBe(workspaceRoot)
+    })
+
+    it('detects workspace roots from package.json workspaces when workspaceDir is unavailable', () => {
+        const workspaceRoot = makeTempRoot()
+        const appDir = join(workspaceRoot, 'apps/web')
+
+        mkdirSync(appDir, { recursive: true })
+        writeFileSync(join(workspaceRoot, 'package.json'), JSON.stringify({
+            private: true,
+            workspaces: ['apps/*', 'packages/*'],
+        }))
+
+        expect(resolveRepositoryRoot(appDir)).toBe(workspaceRoot)
+    })
+
+    it('falls back to the app root when no repository markers exist', () => {
+        const appDir = makeTempRoot()
+
+        expect(resolveRepositoryRoot(appDir)).toBe(appDir)
+    })
+})

package/modules/tela-build-docs/index.ts

@@ -1,9 +1,9 @@
 /* eslint-disable no-console */
-import { execSync } from 'node:child_process'
-import { existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { existsSync, writeFileSync, mkdirSync, lstatSync, readFileSync, symlinkSync } from 'node:fs'
 import { defineNuxtModule, createResolver } from '@nuxt/kit'
-import { resolve } from 'pathe'
+import { dirname, join, relative, resolve } from 'pathe'
 import { collectComponentDocs, generateMarkdown, generateDocsToDirectory } from '../../lib/doc-generator'
+import { telaBuildSkill } from '../../lib/tela-build-skill'
 import { ensureOverlayTsconfig } from '../../lib/extractors/volar-extract'
 
 export interface TelaBuildDocsOptions {
@@ -13,6 +13,11 @@ export interface TelaBuildDocsOptions {
     enabled?: boolean
 }
 
+interface IgnoreTarget {
+    path: string
+    kind: 'dir' | 'file'
+}
+
 export default defineNuxtModule<TelaBuildDocsOptions>({
     meta: {
         name: 'tela-build-docs',
@@ -20,8 +25,8 @@ export default defineNuxtModule<TelaBuildDocsOptions>({
     },
     defaults: {
         layer: undefined,
-        // Prefer directory output suitable for Claude Skills-style indexing
-        outDir: '.claude/skills',
+        // When omitted, docs are written to `.agents/skills` and `.claude` is linked to `.agents`
+        outDir: undefined,
         // Keep outFile for backward compatibility (used only if explicitly set)
         outFile: undefined,
         enabled: true,
@@ -67,6 +72,16 @@ export default defineNuxtModule<TelaBuildDocsOptions>({
             // Run in background without blocking
             setImmediate(async () => {
                 try {
+                    const repositoryRoot = resolveRepositoryRoot(nuxt.options.rootDir, nuxt.options.workspaceDir)
+                    try {
+                        if (!options.outDir) {
+                            ensureClaudeSymlink(repositoryRoot, logger, colors)
+                        }
+                    }
+                    catch (symlinkError: any) {
+                        logger.log(`${colors.gray}[tela/build] ${colors.orange}✗${colors.gray} Could not create .claude symlink: ${symlinkError.message}${colors.reset}`)
+                    }
+
                     // Prepare tsconfig overlay (safe even if Volar is disabled; creation is idempotent)
                     try {
                         if (nuxt.options.rootDir) {
@@ -83,24 +98,31 @@ export default defineNuxtModule<TelaBuildDocsOptions>({
                     // Generate documentation (directory-first unless outFile explicitly set)
                     logger.log(`${colors.gray}[tela/build] ${colors.orange}◐${colors.gray} Generating documentation for ${componentDocs.length} components${colors.reset}`)
 
-                    const baseDir = findGitRoot(nuxt.options.rootDir) ?? nuxt.options.rootDir
+                    const baseDir = repositoryRoot
 
                     if (options.outFile) {
                         // Single-file mode (legacy)
-                        const outPath = resolve(baseDir, options.outFile)
+                        const outPath = resolve(nuxt.options.rootDir, options.outFile)
                         const outDir = resolve(outPath, '..')
                         if (!existsSync(outDir)) {
                             mkdirSync(outDir, { recursive: true })
                         }
                         const markdown = generateMarkdown(componentDocs, typeResolver)
                         writeFileSync(outPath, markdown, 'utf-8')
+                        // Skip auto-gitignore for legacy outFile — the path is user-managed and may be intentionally tracked
                         logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Documentation complete → ${outPath}${colors.reset}`)
                     }
                     else {
                         // Directory output: single Skill (tela-build) + supporting component pages
-                        const outDir = resolve(baseDir, options.outDir!)
-                        generateDocsToDirectory(componentDocs, typeResolver, outDir, layerPath)
-                        logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Documentation complete → ${outDir}${colors.reset}`)
+                        const outputDirs = resolveOutputDirectories(baseDir, options.outDir)
+                        for (const dir of outputDirs) {
+                            generateDocsToDirectory(componentDocs, typeResolver, dir, layerPath)
+                        }
+                        ensurePathsIgnored(baseDir, outputDirs.map(dir => ({
+                            path: join(dir, telaBuildSkill.name),
+                            kind: 'dir' as const,
+                        })))
+                        logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Documentation complete → ${outputDirs.join(', ')}${colors.reset}`)
                     }
                 }
                 catch (error: any) {
@@ -127,15 +149,6 @@ export default defineNuxtModule<TelaBuildDocsOptions>({
     },
 })
 
-function findGitRoot(cwd: string): string | null {
-    try {
-        return execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim()
-    }
-    catch {
-        return null
-    }
-}
-
 function resolveLayerPath(): string | null {
     // Use createResolver to resolve paths relative to this module
     // This works correctly even when the module is installed from npm/github
@@ -153,3 +166,152 @@ function resolveLayerPath(): string | null {
 
     return null
 }
+
+function resolveOutputDirectories(repositoryRoot: string, outDir?: string): string[] {
+    if (outDir) {
+        return [resolve(repositoryRoot, outDir)]
+    }
+
+    return [resolve(repositoryRoot, '.agents/skills')]
+}
+
+export function resolveRepositoryRoot(startDir: string, workspaceDir?: string): string {
+    if (workspaceDir && existsSync(resolve(workspaceDir))) {
+        return resolve(workspaceDir)
+    }
+
+    let currentDir = resolve(startDir)
+
+    while (true) {
+        if (isRepositoryRoot(currentDir)) {
+            return currentDir
+        }
+
+        const parentDir = dirname(currentDir)
+        if (parentDir === currentDir) {
+            return resolve(startDir)
+        }
+
+        currentDir = parentDir
+    }
+}
+
+function isRepositoryRoot(directory: string): boolean {
+    if (existsSync(resolve(directory, '.git')) || existsSync(resolve(directory, 'pnpm-workspace.yaml'))) {
+        return true
+    }
+
+    const packageJsonPath = resolve(directory, 'package.json')
+    if (!existsSync(packageJsonPath)) {
+        return false
+    }
+
+    try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as { workspaces?: unknown }
+        return packageJson.workspaces !== undefined
+    }
+    catch {
+        return false
+    }
+}
+
+function ensurePathsIgnored(repositoryRoot: string, targets: IgnoreTarget[]): void {
+    const gitignorePath = resolve(repositoryRoot, '.gitignore')
+    const existingLines = existsSync(gitignorePath)
+        ? readFileSync(gitignorePath, 'utf-8').split('\n')
+        : []
+    const existingEntries = new Set(existingLines.map(line => line.trim()).filter(Boolean))
+    const entriesToAdd = targets
+        .map(target => toGitignoreEntry(repositoryRoot, target))
+        .filter(entry => !existingEntries.has(entry))
+
+    if (entriesToAdd.length === 0) {
+        return
+    }
+
+    const nextLines = [...existingLines]
+    if (nextLines.length > 0 && nextLines[nextLines.length - 1] !== '') {
+        nextLines.push('')
+    }
+    nextLines.push(...entriesToAdd)
+
+    writeFileSync(gitignorePath, `${nextLines.join('\n')}\n`, 'utf-8')
+}
+
+function toGitignoreEntry(repositoryRoot: string, target: IgnoreTarget): string {
+    const relativePath = relative(repositoryRoot, target.path).replace(/\\/g, '/')
+    const normalizedPath = relativePath.startsWith('.') ? relativePath : `/${relativePath}`
+    return target.kind === 'dir' ? `${normalizedPath}/` : normalizedPath
+}
+
+export function ensureClaudeSymlink(
+    repositoryRoot: string,
+    logger: Pick<Console, 'log'>,
+    colors: Record<'gray' | 'orange' | 'green' | 'reset', string>,
+): void {
+    const agentsPath = resolve(repositoryRoot, '.agents')
+    const claudePath = resolve(repositoryRoot, '.claude')
+
+    // Use lstatSync (not existsSync) to detect broken symlinks —
+    // existsSync follows symlinks and returns false for broken ones,
+    // which would cause mkdirSync/symlinkSync to misbehave.
+    let agentsExists = false
+    try {
+        lstatSync(agentsPath)
+        agentsExists = true
+    }
+    catch {}
+
+    if (!agentsExists) {
+        mkdirSync(agentsPath, { recursive: true })
+    }
+
+    let claudeStats: import('node:fs').Stats | null = null
+    try {
+        claudeStats = lstatSync(claudePath)
+    }
+    catch {}
+
+    if (!claudeStats) {
+        symlinkSync('.agents', claudePath)
+        logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Created .claude symlink → .agents${colors.reset}`)
+        return
+    }
+
+    if (claudeStats.isSymbolicLink()) {
+        return
+    }
+
+    if (claudeStats.isDirectory()) {
+        ensureSkillSymlinks(repositoryRoot, logger, colors)
+        return
+    }
+
+    logger.log(`${colors.gray}[tela/build] ${colors.orange}✗${colors.gray} .claude exists and is not a symlink or directory; keeping .agents as canonical output${colors.reset}`)
+}
+
+function ensureSkillSymlinks(
+    repositoryRoot: string,
+    logger: Pick<Console, 'log'>,
+    colors: Record<'gray' | 'orange' | 'green' | 'reset', string>,
+): void {
+    const agentsSkillsPath = resolve(repositoryRoot, '.agents/skills')
+    const claudeSkillsPath = resolve(repositoryRoot, '.claude/skills')
+
+    if (!existsSync(agentsSkillsPath)) {
+        mkdirSync(agentsSkillsPath, { recursive: true })
+    }
+
+    let claudeSkillsStats: import('node:fs').Stats | null = null
+    try {
+        claudeSkillsStats = lstatSync(claudeSkillsPath)
+    }
+    catch {}
+
+    if (claudeSkillsStats) {
+        return
+    }
+
+    symlinkSync('../.agents/skills', claudeSkillsPath)
+    logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Linked .claude/skills → .agents/skills${colors.reset}`)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-build",
-  "version": "1.30.3",
+  "version": "1.31.0",
   "type": "module",
   "files": [
     "app.config.ts",