skillex 0.2.1 → 0.2.2

package/dist/sync.js

@@ -1,6 +1,7 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { createSymlink, ensureDir, readJson, readSymlink, readText, removePath, writeText } from "./fs.js";
 import { getAdapter } from "./adapters.js";
+import { copyPath, createSymlink, ensureDir, pathExists, readJson, readSymlink, readText, removePath, writeText, } from "./fs.js";
 import { normalizeSkillContent, parseSkillFrontmatter } from "./skill.js";
 import { SyncError } from "./types.js";
 const MANAGED_START = "<!-- SKILLEX:START -->";
@@ -12,7 +13,7 @@ const LEGACY_AUTO_INJECT_BLOCKS = [
     { start: "<!-- ASKILL:AUTO-INJECT:START -->", end: "<!-- ASKILL:AUTO-INJECT:END -->" },
 ];
 /**
- * Loads installed skill documents from the local workspace state directory.
+ * Loads installed skill documents from the selected Skillex state directory.
  *
  * @param context - Workspace root and lockfile context.
  * @returns Installed skill documents used for sync rendering.
@@ -21,7 +22,7 @@ export async function loadInstalledSkillDocuments(context) {
     const installedEntries = Object.entries(context.lockfile.installed || {}).sort(([left], [right]) => left.localeCompare(right));
     const documents = [];
     for (const [skillId, metadata] of installedEntries) {
-        const skillDir = path.resolve(context.cwd, metadata.path);
+        const skillDir = resolveInstalledSkillPath(context.cwd, metadata.path);
         const manifest = (await readJson(path.join(skillDir, "skill.json"), {})) || {};
         const entry = manifest.entry || "SKILL.md";
         const rawContent = (await readText(path.join(skillDir, entry), "")) || "";
@@ -40,7 +41,7 @@ export async function loadInstalledSkillDocuments(context) {
     return documents;
 }
 /**
- * Synchronizes installed skills into the target file consumed by an adapter.
+ * Synchronizes installed skills into the target consumed by an adapter.
  *
  * @param options - Sync execution options.
  * @returns Final sync result.
@@ -50,26 +51,50 @@ export async function syncAdapterFiles(options) {
     try {
         const prepared = await prepareSyncAdapterFiles(options);
         if (!options.dryRun) {
-            await ensureDir(path.dirname(prepared.absoluteTargetPath));
-            if (prepared.generatedSourcePath) {
-                await ensureDir(path.dirname(prepared.generatedSourcePath));
-                await writeText(prepared.generatedSourcePath, prepared.nextContent);
-            }
-            if (prepared.syncMode === "symlink" && prepared.generatedSourcePath) {
+            if (prepared.directoryEntries) {
+                await ensureDir(prepared.absoluteTargetPath);
                 const createLink = options.linkFactory || createSymlink;
-                const linkResult = await createLink(prepared.generatedSourcePath, prepared.absoluteTargetPath);
-                if (linkResult.fallback) {
-                    (options.warn || console.error)(`Aviso: symlink indisponivel para ${prepared.targetPath}; usando copia no lugar.`);
-                    await writeText(prepared.absoluteTargetPath, prepared.nextContent);
-                    await removePath(prepared.generatedSourcePath);
-                    prepared.syncMode = "copy";
+                let finalMode = prepared.syncMode;
+                for (const entry of prepared.directoryEntries) {
+                    if (prepared.syncMode === "symlink") {
+                        const linkResult = await createLink(entry.sourcePath, entry.absoluteTargetPath);
+                        if (linkResult.fallback) {
+                            (options.warn || console.error)(`Aviso: symlink indisponivel para ${entry.targetPath}; usando copia no lugar.`);
+                            await copyPath(entry.sourcePath, entry.absoluteTargetPath);
+                            finalMode = "copy";
+                        }
+                    }
+                    else {
+                        await copyPath(entry.sourcePath, entry.absoluteTargetPath);
+                    }
                 }
+                for (const cleanupPath of prepared.cleanupPaths) {
+                    await removePath(cleanupPath);
+                }
+                prepared.syncMode = finalMode;
             }
             else {
-                await writeText(prepared.absoluteTargetPath, prepared.nextContent);
-            }
-            for (const cleanupPath of prepared.cleanupPaths) {
-                await removePath(cleanupPath);
+                await ensureDir(path.dirname(prepared.absoluteTargetPath));
+                if (prepared.generatedSourcePath) {
+                    await ensureDir(path.dirname(prepared.generatedSourcePath));
+                    await writeText(prepared.generatedSourcePath, prepared.nextContent);
+                }
+                if (prepared.syncMode === "symlink" && prepared.generatedSourcePath) {
+                    const createLink = options.linkFactory || createSymlink;
+                    const linkResult = await createLink(prepared.generatedSourcePath, prepared.absoluteTargetPath);
+                    if (linkResult.fallback) {
+                        (options.warn || console.error)(`Aviso: symlink indisponivel para ${prepared.targetPath}; usando copia no lugar.`);
+                        await writeText(prepared.absoluteTargetPath, prepared.nextContent);
+                        await removePath(prepared.generatedSourcePath);
+                        prepared.syncMode = "copy";
+                    }
+                }
+                else {
+                    await writeText(prepared.absoluteTargetPath, prepared.nextContent);
+                }
+                for (const cleanupPath of prepared.cleanupPaths) {
+                    await removePath(cleanupPath);
+                }
             }
         }
         return {
@@ -97,66 +122,80 @@ export async function syncAdapterFiles(options) {
  */
 export async function prepareSyncAdapterFiles(options) {
     const adapter = getAdapter(options.adapterId);
-    const targetPath = path.join(options.cwd, adapter.syncTarget);
-    const relativeTargetPath = toPosix(path.relative(options.cwd, targetPath));
+    const absoluteTargetPath = resolveAdapterTargetPath(adapter, options);
+    const targetPath = toDisplayPath(options.cwd, absoluteTargetPath, options.statePaths.scope);
+    const cleanupPaths = await resolveCleanupPaths(adapter, options, absoluteTargetPath);
+    if (adapter.syncMode === "managed-directory") {
+        return prepareManagedDirectorySync({
+            adapter,
+            absoluteTargetPath,
+            targetPath,
+            cleanupPaths,
+            options,
+        });
+    }
+    if (options.statePaths.scope === "global") {
+        throw new SyncError(`Adapter ${adapter.id} nao suporta sync global no momento. Use --scope local.`, "GLOBAL_SYNC_UNSUPPORTED");
+    }
+    if (!adapter.syncTarget) {
+        throw new SyncError(`Adapter ${adapter.id} nao define um alvo de sync.`, "SYNC_TARGET_MISSING");
+    }
     const body = renderInstalledSkills(options.skills);
     const autoInjectBlock = buildAutoInjectBlock(options.skills);
-    const cleanupPaths = (adapter.legacySyncTargets || [])
-        .map((relativePath) => path.join(options.cwd, relativePath))
-        .filter((absolutePath) => absolutePath !== targetPath);
     if (adapter.syncMode === "managed-block") {
-        const existing = (await readText(targetPath, "")) || "";
+        const existing = (await readText(absoluteTargetPath, "")) || "";
         const nextManaged = upsertManagedBlock(existing, wrapManagedBlock(MANAGED_START, MANAGED_END, body));
         const nextContent = upsertAutoInjectBlock(nextManaged, autoInjectBlock);
         return {
             adapter: adapter.id,
-            absoluteTargetPath: targetPath,
-            targetPath: relativeTargetPath,
+            absoluteTargetPath,
+            targetPath,
             cleanupPaths,
-            changed: normalizeComparableText(existing) !== normalizeComparableText(nextContent),
+            changed: normalizeComparableText(existing) !== normalizeComparableText(nextContent) || cleanupPaths.length > 0,
             currentContent: existing,
             nextContent,
-            diff: createTextDiff(existing, nextContent, relativeTargetPath),
+            diff: createTextDiff(existing, nextContent, targetPath),
             syncMode: "copy",
         };
     }
     const nextContent = buildManagedFileContent(adapter.id, body, autoInjectBlock);
     const requestedMode = options.mode || "symlink";
     if (requestedMode === "copy") {
-        const existing = (await readText(targetPath, "")) || "";
+        const existing = (await readText(absoluteTargetPath, "")) || "";
         return {
             adapter: adapter.id,
-            absoluteTargetPath: targetPath,
-            targetPath: relativeTargetPath,
+            absoluteTargetPath,
+            targetPath,
             cleanupPaths,
-            changed: normalizeComparableText(existing) !== normalizeComparableText(nextContent),
+            changed: normalizeComparableText(existing) !== normalizeComparableText(nextContent) || cleanupPaths.length > 0,
             currentContent: existing,
             nextContent,
-            diff: createTextDiff(existing, nextContent, relativeTargetPath),
+            diff: createTextDiff(existing, nextContent, targetPath),
             syncMode: "copy",
         };
     }
     const generatedSourcePath = path.join(options.statePaths.generatedDirPath, adapter.id, path.basename(adapter.syncTarget));
-    const currentDescriptor = await describeTarget(targetPath);
-    const currentVisibleContent = (await readText(targetPath, "")) || "";
-    const nextDescriptor = `symlink -> ${toPosix(generatedSourcePath)}\n`;
+    const currentDescriptor = await describeTarget(absoluteTargetPath);
+    const currentVisibleContent = (await readText(absoluteTargetPath, "")) || "";
+    const nextDescriptor = `symlink -> ${toPosix(path.relative(path.dirname(absoluteTargetPath), generatedSourcePath))}\n`;
     const descriptorChanged = normalizeComparableText(currentDescriptor) !== normalizeComparableText(nextDescriptor);
     const contentChanged = normalizeComparableText(currentVisibleContent) !== normalizeComparableText(nextContent);
     return {
         adapter: adapter.id,
-        absoluteTargetPath: targetPath,
-        targetPath: relativeTargetPath,
+        absoluteTargetPath,
+        targetPath,
         cleanupPaths,
-        changed: descriptorChanged || contentChanged,
+        changed: descriptorChanged || contentChanged || cleanupPaths.length > 0,
         currentContent: currentDescriptor,
         nextContent,
         diff: createManagedFileDiff({
-            targetPath: relativeTargetPath,
+            targetPath,
             currentDescriptor,
             nextDescriptor,
-            generatedPath: toPosix(generatedSourcePath),
+            generatedPath: toDisplayPath(options.cwd, generatedSourcePath, options.statePaths.scope),
             currentContent: currentVisibleContent,
             nextContent,
+            cleanupPaths: cleanupPaths.map((cleanupPath) => toDisplayPath(options.cwd, cleanupPath, options.statePaths.scope)),
         }),
         syncMode: "symlink",
         generatedSourcePath,
@@ -206,6 +245,77 @@ export function buildAutoInjectBlock(skills) {
     ].join("\n");
     return wrapManagedBlock(AUTO_INJECT_START, AUTO_INJECT_END, body);
 }
+async function prepareManagedDirectorySync(context) {
+    const requestedMode = context.options.mode || "symlink";
+    const directoryEntries = await Promise.all(context.options.skills.map(async (skill) => {
+        const absoluteSkillTargetPath = path.join(context.absoluteTargetPath, skill.id);
+        const targetPath = toDisplayPath(context.options.cwd, absoluteSkillTargetPath, context.options.statePaths.scope);
+        const currentDescriptor = await describeTarget(absoluteSkillTargetPath);
+        const nextDescriptor = requestedMode === "symlink"
+            ? `symlink -> ${toPosix(path.relative(path.dirname(absoluteSkillTargetPath), skill.skillDir))}\n`
+            : "directory\n";
+        return {
+            skillId: skill.id,
+            sourcePath: skill.skillDir,
+            absoluteTargetPath: absoluteSkillTargetPath,
+            targetPath,
+            currentDescriptor,
+            nextDescriptor,
+        };
+    }));
+    const changed = directoryEntries.some((entry) => normalizeComparableText(entry.currentDescriptor) !== normalizeComparableText(entry.nextDescriptor)) || context.cleanupPaths.length > 0;
+    return {
+        adapter: context.adapter.id,
+        absoluteTargetPath: context.absoluteTargetPath,
+        targetPath: context.targetPath,
+        cleanupPaths: context.cleanupPaths,
+        changed,
+        currentContent: "",
+        nextContent: "",
+        diff: createManagedDirectoryDiff({
+            targetPath: context.targetPath,
+            entries: directoryEntries,
+            cleanupPaths: context.cleanupPaths.map((cleanupPath) => toDisplayPath(context.options.cwd, cleanupPath, context.options.statePaths.scope)),
+        }),
+        syncMode: requestedMode,
+        directoryEntries,
+    };
+}
+async function resolveCleanupPaths(adapter, options, absoluteTargetPath) {
+    const cleanupPaths = new Set();
+    for (const legacyTarget of adapter.legacySyncTargets || []) {
+        const resolvedLegacyPath = options.statePaths.scope === "global"
+            ? path.join(absoluteTargetPath, path.basename(legacyTarget))
+            : path.resolve(options.cwd, legacyTarget);
+        if (await pathExists(resolvedLegacyPath)) {
+            cleanupPaths.add(resolvedLegacyPath);
+        }
+    }
+    if (adapter.syncMode === "managed-directory") {
+        const currentSkillIds = new Set(options.skills.map((skill) => skill.id));
+        for (const previousSkillId of options.previousSkillIds || []) {
+            if (!currentSkillIds.has(previousSkillId)) {
+                const stalePath = path.join(absoluteTargetPath, previousSkillId);
+                if (await pathExists(stalePath)) {
+                    cleanupPaths.add(stalePath);
+                }
+            }
+        }
+    }
+    return [...cleanupPaths];
+}
+function resolveAdapterTargetPath(adapter, options) {
+    if (options.statePaths.scope === "global") {
+        if (!adapter.globalSyncTarget) {
+            throw new SyncError(`Adapter ${adapter.id} nao suporta sync global no momento. Use --scope local.`, "GLOBAL_SYNC_UNSUPPORTED");
+        }
+        return path.resolve(adapter.globalSyncTarget);
+    }
+    if (!adapter.syncTarget) {
+        throw new SyncError(`Adapter ${adapter.id} nao define um alvo de sync.`, "SYNC_TARGET_MISSING");
+    }
+    return path.join(options.cwd, adapter.syncTarget);
+}
 function renderSkillSection(skill) {
     const body = skill.body.trim() || "_Sem conteudo._";
     return [`### ${skill.name} (\`${skill.id}@${skill.version}\`)`, "", body].join("\n");
@@ -237,9 +347,6 @@ function buildManagedFileContent(adapterId, body, autoInjectBlock) {
                 "",
             ].join("\n");
         case "cline":
-        case "codex":
-        case "claude":
-        case "gemini":
             return `${sections.join("\n\n")}\n`;
         default:
             throw new SyncError(`Adapter desconhecido: ${adapterId}`, "SYNC_ADAPTER_UNKNOWN");
@@ -279,15 +386,43 @@ async function describeTarget(targetPath) {
     if (linkTarget) {
         return `symlink -> ${toPosix(linkTarget)}\n`;
     }
-    if (!(await readText(targetPath, null))) {
-        return "";
+    try {
+        const stats = await fs.lstat(targetPath);
+        if (stats.isDirectory()) {
+            return "directory\n";
+        }
+        if (stats.isFile()) {
+            return "file\n";
+        }
+        return "path\n";
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return "";
+        }
+        throw error;
     }
-    return "file\n";
+}
+function createManagedDirectoryDiff(context) {
+    const parts = [];
+    for (const entry of context.entries) {
+        if (normalizeComparableText(entry.currentDescriptor) === normalizeComparableText(entry.nextDescriptor)) {
+            continue;
+        }
+        parts.push(createTextDiff(entry.currentDescriptor, entry.nextDescriptor, entry.targetPath).trimEnd());
+    }
+    for (const cleanupPath of context.cleanupPaths) {
+        parts.push(`- remove ${cleanupPath}`);
+    }
+    if (parts.length === 0) {
+        return `Sem alteracoes em ${context.targetPath}.\n`;
+    }
+    return `${parts.join("\n")}\n`;
 }
 function createManagedFileDiff(context) {
     const descriptorChanged = normalizeComparableText(context.currentDescriptor) !== normalizeComparableText(context.nextDescriptor);
     const contentChanged = normalizeComparableText(context.currentContent) !== normalizeComparableText(context.nextContent);
-    if (!descriptorChanged && !contentChanged) {
+    if (!descriptorChanged && !contentChanged && context.cleanupPaths.length === 0) {
         return `Sem alteracoes em ${context.targetPath}.\n`;
     }
     const parts = [];
@@ -297,6 +432,9 @@ function createManagedFileDiff(context) {
     if (contentChanged) {
         parts.push(createTextDiff(context.currentContent, context.nextContent, context.generatedPath).trimEnd());
     }
+    for (const cleanupPath of context.cleanupPaths) {
+        parts.push(`- remove ${cleanupPath}`);
+    }
     return `${parts.join("\n")}\n`;
 }
 function createTextDiff(currentContent, nextContent, targetPath) {
@@ -379,6 +517,12 @@ function diffLines(leftLines, rightLines) {
     }
     return operations;
 }
+function resolveInstalledSkillPath(cwd, skillPath) {
+    return path.isAbsolute(skillPath) ? skillPath : path.resolve(cwd, skillPath);
+}
+function toDisplayPath(cwd, targetPath, scope) {
+    return scope === "local" ? toPosix(path.relative(cwd, targetPath)) : toPosix(targetPath);
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

package/dist/types.d.ts

@@ -4,11 +4,15 @@
 /**
  * Supported sync file rendering modes.
  */
-export type SyncMode = "managed-block" | "managed-file";
+export type SyncMode = "managed-block" | "managed-file" | "managed-directory";
 /**
  * Workspace sync write modes.
  */
 export type SyncWriteMode = "symlink" | "copy";
+/**
+ * Supported install scopes.
+ */
+export type InstallScope = "local" | "global";
 /**
  * Marker used to detect an adapter in a workspace.
  */
@@ -23,7 +27,8 @@ export interface AdapterConfig {
     id: string;
     label: string;
     markers: AdapterMarker[];
-    syncTarget: string;
+    syncTarget?: string;
+    globalSyncTarget?: string;
     legacySyncTargets?: string[];
     syncMode: SyncMode;
 }
@@ -165,6 +170,7 @@ export interface SyncMetadata {
     adapter: string;
     targetPath: string;
     syncedAt: string;
+    skillIds?: string[] | undefined;
 }
 /**
  * Full workspace lockfile structure.
@@ -202,6 +208,7 @@ export interface ResolvedSkillSelection {
  * Common filesystem paths used by the local state manager.
  */
 export interface StatePaths {
+    scope: InstallScope;
     stateDir: string;
     lockfilePath: string;
     skillsDirPath: string;
@@ -212,6 +219,7 @@ export interface StatePaths {
  */
 export interface ProjectOptions extends CatalogSourceInput {
     cwd?: string | undefined;
+    scope?: InstallScope | undefined;
     agentSkillsDir?: string | undefined;
     adapter?: string | undefined;
     autoSync?: boolean | undefined;
@@ -261,6 +269,18 @@ export interface PreparedSyncResult {
     diff: string;
     syncMode: SyncWriteMode;
     generatedSourcePath?: string | undefined;
+    directoryEntries?: PreparedDirectoryEntry[] | undefined;
+}
+/**
+ * Prepared directory entry for directory-native adapter sync.
+ */
+export interface PreparedDirectoryEntry {
+    skillId: string;
+    sourcePath: string;
+    absoluteTargetPath: string;
+    targetPath: string;
+    currentDescriptor: string;
+    nextDescriptor: string;
 }
 /**
  * Dry-run preview returned before a sync writes files.
@@ -286,9 +306,11 @@ export interface SyncResult {
  */
 export interface SyncOptions {
     cwd: string;
+    scope?: InstallScope | undefined;
     adapterId: string;
     statePaths: StatePaths;
     skills: InstalledSkillDocument[];
+    previousSkillIds?: string[] | undefined;
     mode?: SyncWriteMode | undefined;
     dryRun?: boolean | undefined;
     linkFactory?: ((targetPath: string, linkPath: string) => Promise<CreateSymlinkResult>) | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillex",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI to list, install, and synchronize AI agent skills from GitHub-hosted catalogs.",
   "type": "module",
   "repository": {