@meistrari/tela-build 1.52.0 → 1.52.1

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

@@ -82,16 +82,65 @@ describe('ensureClaudeSymlink', () => {
         expect(existsSync(skillsLink)).toBe(true)
     })
 
-    it('skips skill symlink when .claude/skills already exists', () => {
+    it('links tela-build individually when .claude/skills already exists as a real directory', () => {
         const root = makeTempRoot()
 
-        mkdirSync(join(root, '.agents/skills'), { recursive: true })
-        mkdirSync(join(root, '.claude/skills'), { recursive: true })
+        mkdirSync(join(root, '.agents/skills/tela-build'), { recursive: true })
+        writeFileSync(join(root, '.agents/skills/tela-build/SKILL.md'), '# Test')
+        // Developer keeps their own real .claude/skills dir with a personal skill.
+        mkdirSync(join(root, '.claude/skills/my-skill'), { recursive: true })
 
         ensureClaudeSymlink(root, logger, colors)
 
-        expect(lstatSync(join(root, '.claude/skills')).isDirectory()).toBe(true)
+        // The real directory is preserved, not replaced by a symlink.
         expect(lstatSync(join(root, '.claude/skills')).isSymbolicLink()).toBe(false)
+        // The developer's own skill is untouched.
+        expect(existsSync(join(root, '.claude/skills/my-skill'))).toBe(true)
+        // The generated skill is linked in and readable through .claude/skills.
+        expect(lstatSync(join(root, '.claude/skills/tela-build')).isSymbolicLink()).toBe(true)
+        expect(readFileSync(join(root, '.claude/skills/tela-build/SKILL.md'), 'utf-8')).toBe('# Test')
+    })
+
+    it('leaves a real .claude/skills/tela-build directory untouched', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents/skills/tela-build'), { recursive: true })
+        // A stale real copy already sits at the destination.
+        mkdirSync(join(root, '.claude/skills/tela-build'), { recursive: true })
+        writeFileSync(join(root, '.claude/skills/tela-build/SKILL.md'), '# Stale')
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(lstatSync(join(root, '.claude/skills/tela-build')).isSymbolicLink()).toBe(false)
+        expect(readFileSync(join(root, '.claude/skills/tela-build/SKILL.md'), 'utf-8')).toBe('# Stale')
+    })
+
+    it('is idempotent when .claude/skills/tela-build is already a symlink', () => {
+        const root = makeTempRoot()
+
+        mkdirSync(join(root, '.agents/skills/tela-build'), { recursive: true })
+        mkdirSync(join(root, '.claude/skills'), { recursive: true })
+        symlinkSync('../../.agents/skills/tela-build', join(root, '.claude/skills/tela-build'))
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(lstatSync(join(root, '.claude/skills/tela-build')).isSymbolicLink()).toBe(true)
+    })
+
+    it('re-points a stale .claude/skills/tela-build symlink at the generated skill', () => {
+        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/skills'), { recursive: true })
+        // A symlink from an earlier setup that points somewhere wrong/broken.
+        symlinkSync('../../.agents/skills/stale-target', join(root, '.claude/skills/tela-build'))
+
+        ensureClaudeSymlink(root, logger, colors)
+
+        expect(lstatSync(join(root, '.claude/skills/tela-build')).isSymbolicLink()).toBe(true)
+        expect(readlinkSync(join(root, '.claude/skills/tela-build'))).toBe('../../.agents/skills/tela-build')
+        expect(readFileSync(join(root, '.claude/skills/tela-build/SKILL.md'), 'utf-8')).toBe('# Test')
     })
 
     it('creates .agents/skills when .claude is a directory but .agents/skills does not exist', () => {

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

@@ -1,5 +1,5 @@
 /* eslint-disable no-console */
-import { existsSync, writeFileSync, mkdirSync, lstatSync, readFileSync, symlinkSync } from 'node:fs'
+import { existsSync, writeFileSync, mkdirSync, lstatSync, readFileSync, symlinkSync, readlinkSync, unlinkSync } from 'node:fs'
 import { defineNuxtModule, createResolver } from 'nuxt/kit'
 import { dirname, resolve } from 'pathe'
 import { collectComponentDocs, generateMarkdown, generateDocsToDirectory } from '../../lib/doc-generator'
@@ -248,6 +248,10 @@ export function ensureClaudeSymlink(
     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}`)
 }
 
+// The single Skill produced by doc generation. Linked individually so it stays
+// discoverable even when the developer keeps their own real .claude/skills dir.
+const GENERATED_SKILL_NAME = 'tela-build'
+
 function ensureSkillSymlinks(
     repositoryRoot: string,
     logger: Pick<Console, 'log'>,
@@ -266,10 +270,58 @@ function ensureSkillSymlinks(
     }
     catch {}
 
-    if (claudeSkillsStats) {
+    // No .claude/skills yet → link the whole directory in one shot.
+    if (!claudeSkillsStats) {
+        symlinkSync('../.agents/skills', claudeSkillsPath)
+        logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Linked .claude/skills → .agents/skills${colors.reset}`)
+        return
+    }
+
+    // Already a symlink (e.g. a previous run linked the whole dir) → the generated
+    // skill resolves through it; nothing to do.
+    if (claudeSkillsStats.isSymbolicLink()) {
+        return
+    }
+
+    // .claude/skills is a real directory the developer manages themselves. Don't
+    // touch it — just drop a per-skill symlink so the generated skill stays
+    // discoverable alongside their own skills.
+    ensureGeneratedSkillSymlink(claudeSkillsPath, logger, colors)
+}
+
+function ensureGeneratedSkillSymlink(
+    claudeSkillsPath: string,
+    logger: Pick<Console, 'log'>,
+    colors: Record<'gray' | 'orange' | 'green' | 'reset', string>,
+): void {
+    const generatedSkillLink = resolve(claudeSkillsPath, GENERATED_SKILL_NAME)
+    const expectedTarget = `../../.agents/skills/${GENERATED_SKILL_NAME}`
+
+    let linkStats: import('node:fs').Stats | null = null
+    try {
+        linkStats = lstatSync(generatedSkillLink)
+    }
+    catch {}
+
+    // Already a symlink → keep it only if it points where we want. A stale or
+    // broken target from an earlier setup gets re-pointed at the generated skill.
+    if (linkStats?.isSymbolicLink()) {
+        if (readlinkSync(generatedSkillLink) === expectedTarget) {
+            return
+        }
+        unlinkSync(generatedSkillLink)
+        linkStats = null
+    }
+
+    // A real directory/file already sits here (e.g. a stale copy). Don't clobber
+    // developer-owned content; surface it instead.
+    if (linkStats) {
+        logger.log(`${colors.gray}[tela/build] ${colors.orange}✗${colors.gray} .claude/skills/${GENERATED_SKILL_NAME} exists and is not a symlink; skipping link${colors.reset}`)
         return
     }
 
-    symlinkSync('../.agents/skills', claudeSkillsPath)
-    logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Linked .claude/skills → .agents/skills${colors.reset}`)
+    // Target is relative to the link's own directory (.claude/skills):
+    // ../../.agents/skills/<skill> → <root>/.agents/skills/<skill>
+    symlinkSync(expectedTarget, generatedSkillLink)
+    logger.log(`${colors.gray}[tela/build] ${colors.green}●${colors.gray} Linked .claude/skills/${GENERATED_SKILL_NAME} → .agents/skills/${GENERATED_SKILL_NAME}${colors.reset}`)
 }

package/package.json

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