skillex 0.2.1 → 0.2.3

package/dist/fs.d.ts

@@ -48,6 +48,13 @@ export declare function writeText(filePath: string, value: string): Promise<void
  * @param targetPath - File system path to remove.
  */
 export declare function removePath(targetPath: string): Promise<void>;
+/**
+ * Copies a file or directory recursively to a destination path.
+ *
+ * @param sourcePath - Existing source path.
+ * @param targetPath - Destination path.
+ */
+export declare function copyPath(sourcePath: string, targetPath: string): Promise<void>;
 /**
  * Creates a relative symlink and reports whether the caller should fall back to copy mode.
  *

package/dist/fs.js

@@ -89,6 +89,17 @@ export async function writeText(filePath, value) {
 export async function removePath(targetPath) {
     await fs.rm(targetPath, { recursive: true, force: true });
 }
+/**
+ * Copies a file or directory recursively to a destination path.
+ *
+ * @param sourcePath - Existing source path.
+ * @param targetPath - Destination path.
+ */
+export async function copyPath(sourcePath, targetPath) {
+    await ensureDir(path.dirname(targetPath));
+    await removePath(targetPath);
+    await fs.cp(sourcePath, targetPath, { recursive: true, force: true });
+}
 /**
  * Creates a relative symlink and reports whether the caller should fall back to copy mode.
  *
@@ -98,14 +109,16 @@ export async function removePath(targetPath) {
  */
 export async function createSymlink(targetPath, linkPath) {
     const absoluteTarget = path.resolve(targetPath);
+    const relativeTarget = path.relative(path.dirname(linkPath), absoluteTarget) || ".";
     await ensureDir(path.dirname(linkPath));
     await removePath(linkPath);
     try {
-        await fs.symlink(absoluteTarget, linkPath);
+        const stats = await fs.lstat(absoluteTarget);
+        await fs.symlink(relativeTarget, linkPath, stats.isDirectory() ? "dir" : "file");
         return {
             ok: true,
             fallback: false,
-            relativeTarget: absoluteTarget,
+            relativeTarget,
         };
     }
     catch (error) {
@@ -116,7 +129,7 @@ export async function createSymlink(targetPath, linkPath) {
             return {
                 ok: false,
                 fallback: true,
-                relativeTarget: absoluteTarget,
+                relativeTarget,
             };
         }
         throw error;

package/dist/install.d.ts

@@ -15,7 +15,7 @@ interface InstallOptions extends ProjectOptions {
  */
 export declare function initProject(options?: ProjectOptions): Promise<InitProjectResult>;
 /**
- * Installs one or more catalog skills or direct GitHub skills into the local workspace state.
+ * Installs one or more catalog skills or direct GitHub skills into the selected Skillex state.
  *
  * @param requestedSkillIds - Requested skill ids or `owner/repo[@ref]` direct references.
  * @param options - Installation options.
@@ -33,7 +33,7 @@ export declare function installSkills(requestedSkillIds: string[], options?: Ins
  */
 export declare function updateInstalledSkills(requestedSkillIds: string[], options?: InstallOptions): Promise<UpdateInstalledSkillsResult>;
 /**
- * Removes installed skills from the local workspace state.
+ * Removes installed skills from the selected Skillex state.
  *
  * @param requestedSkillIds - Skill ids to remove.
  * @param options - Remove options.
@@ -46,11 +46,11 @@ export declare function removeSkills(requestedSkillIds: string[], options?: Proj
  *
  * @param options - Sync options.
  * @returns Sync command result.
- * @throws {InstallError} When workspace state is missing or invalid.
+ * @throws {InstallError} When the selected install scope is missing or invalid.
  */
 export declare function syncInstalledSkills(options?: ProjectOptions): Promise<SyncCommandResult>;
 /**
- * Reads the local workspace lockfile when it exists.
+ * Reads the selected Skillex lockfile when it exists.
  *
  * @param options - Project lookup options.
  * @returns Normalized lockfile state or `null` when no install exists.

package/dist/install.js

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { DEFAULT_AGENT_SKILLS_DIR, DEFAULT_REF, DEFAULT_REPO, getStatePaths } from "./config.js";
+import { DEFAULT_INSTALL_SCOPE, DEFAULT_REF, DEFAULT_REPO, getScopedStatePaths, } from "./config.js";
 import { confirmAction } from "./confirm.js";
 import { ensureDir, pathExists, readJson, removePath, writeJson, writeText } from "./fs.js";
 import { fetchOptionalJson, fetchOptionalText, fetchText } from "./http.js";
@@ -18,7 +18,7 @@ import { CliError, InstallError } from "./types.js";
 export async function initProject(options = {}) {
     try {
         const cwd = options.cwd || process.cwd();
-        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const statePaths = resolveStatePathsForOptions(cwd, options);
         const now = getNow(options);
         await ensureDir(statePaths.stateDir);
         await ensureDir(statePaths.skillsDirPath);
@@ -41,10 +41,12 @@ export async function initProject(options = {}) {
         }
         lockfile.updatedAt = now();
         await writeJson(statePaths.lockfilePath, lockfile);
-        // Create .gitignore for the state directory on first init
-        const gitignorePath = path.join(statePaths.stateDir, ".gitignore");
-        if (!(await pathExists(gitignorePath))) {
-            await writeText(gitignorePath, ".cache/\n*.log\n");
+        // Create .gitignore for the local state directory on first init.
+        if (statePaths.scope === "local") {
+            const gitignorePath = path.join(statePaths.stateDir, ".gitignore");
+            if (!(await pathExists(gitignorePath))) {
+                await writeText(gitignorePath, ".cache/\n*.log\n");
+            }
         }
         return { created: !existing, statePaths, lockfile };
     }
@@ -53,7 +55,7 @@ export async function initProject(options = {}) {
     }
 }
 /**
- * Installs one or more catalog skills or direct GitHub skills into the local workspace state.
+ * Installs one or more catalog skills or direct GitHub skills into the selected Skillex state.
  *
  * @param requestedSkillIds - Requested skill ids or `owner/repo[@ref]` direct references.
  * @param options - Installation options.
@@ -63,7 +65,7 @@ export async function initProject(options = {}) {
 export async function installSkills(requestedSkillIds, options = {}) {
     try {
         const cwd = options.cwd || process.cwd();
-        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const statePaths = resolveStatePathsForOptions(cwd, options);
         const now = getNow(options);
         const catalogLoader = options.catalogLoader || loadCatalog;
         const downloader = options.downloader || downloadSkill;
@@ -126,6 +128,7 @@ export async function installSkills(requestedSkillIds, options = {}) {
         await writeJson(statePaths.lockfilePath, lockfile);
         const autoSync = await maybeAutoSync(withAgentSkillsDir({
             cwd,
+            scope: options.scope,
             adapter: lockfile.adapters.active,
             enabled: lockfile.settings.autoSync,
             now,
@@ -154,13 +157,15 @@ export async function installSkills(requestedSkillIds, options = {}) {
 export async function updateInstalledSkills(requestedSkillIds, options = {}) {
     try {
         const cwd = options.cwd || process.cwd();
-        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const statePaths = resolveStatePathsForOptions(cwd, options);
         const now = getNow(options);
         const catalogLoader = options.catalogLoader || loadCatalog;
         const downloader = options.downloader || downloadSkill;
         const existing = await readJson(statePaths.lockfilePath, null);
         if (!existing) {
-            throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+            throw new InstallError(statePaths.scope === "global"
+                ? "No global installation found. Run: skillex init --global --adapter <id>"
+                : "No local installation found. Run: skillex init", "LOCKFILE_MISSING");
         }
         const defaultSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
         const lockfile = normalizeLockfile(existing, defaultSource, now);
@@ -211,6 +216,7 @@ export async function updateInstalledSkills(requestedSkillIds, options = {}) {
         await writeJson(statePaths.lockfilePath, lockfile);
         const autoSync = await maybeAutoSync(withAgentSkillsDir({
             cwd,
+            scope: options.scope,
             adapter: lockfile.adapters.active,
             enabled: lockfile.settings.autoSync,
             now,
@@ -229,7 +235,7 @@ export async function updateInstalledSkills(requestedSkillIds, options = {}) {
     }
 }
 /**
- * Removes installed skills from the local workspace state.
+ * Removes installed skills from the selected Skillex state.
  *
  * @param requestedSkillIds - Skill ids to remove.
  * @param options - Remove options.
@@ -239,11 +245,13 @@ export async function updateInstalledSkills(requestedSkillIds, options = {}) {
 export async function removeSkills(requestedSkillIds, options = {}) {
     try {
         const cwd = options.cwd || process.cwd();
-        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const statePaths = resolveStatePathsForOptions(cwd, options);
         const now = getNow(options);
         const existing = await readJson(statePaths.lockfilePath, null);
         if (!existing) {
-            throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+            throw new InstallError(statePaths.scope === "global"
+                ? "No global installation found. Run: skillex init --global --adapter <id>"
+                : "No local installation found. Run: skillex init", "LOCKFILE_MISSING");
         }
         if (!requestedSkillIds.length) {
             throw new InstallError("Provide at least one skill-id to remove.", "REMOVE_REQUIRES_SKILL");
@@ -258,7 +266,7 @@ export async function removeSkills(requestedSkillIds, options = {}) {
                 missingSkills.push(skillId);
                 continue;
             }
-            await removePath(path.resolve(cwd, metadata.path));
+            await removePath(resolveInstalledSkillPath(cwd, metadata.path));
             delete lockfile.installed[skillId];
             removedSkills.push(skillId);
         }
@@ -266,6 +274,7 @@ export async function removeSkills(requestedSkillIds, options = {}) {
         await writeJson(statePaths.lockfilePath, lockfile);
         const autoSync = await maybeAutoSync(withAgentSkillsDir({
             cwd,
+            scope: options.scope,
             adapter: lockfile.adapters.active,
             enabled: lockfile.settings.autoSync,
             now,
@@ -288,16 +297,18 @@ export async function removeSkills(requestedSkillIds, options = {}) {
  *
  * @param options - Sync options.
  * @returns Sync command result.
- * @throws {InstallError} When workspace state is missing or invalid.
+ * @throws {InstallError} When the selected install scope is missing or invalid.
  */
 export async function syncInstalledSkills(options = {}) {
     try {
         const cwd = options.cwd || process.cwd();
-        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const statePaths = resolveStatePathsForOptions(cwd, options);
         const now = getNow(options);
         const existing = await readJson(statePaths.lockfilePath, null);
         if (!existing) {
-            throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+            throw new InstallError(statePaths.scope === "global"
+                ? "No global installation found. Run: skillex init --global --adapter <id>"
+                : "No local installation found. Run: skillex init", "LOCKFILE_MISSING");
         }
         const defaultSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
         const lockfile = normalizeLockfile(existing, defaultSource, now);
@@ -311,9 +322,11 @@ export async function syncInstalledSkills(options = {}) {
         });
         const syncResult = await syncAdapterFiles({
             cwd,
+            scope: statePaths.scope,
             adapterId,
             statePaths,
             skills,
+            previousSkillIds: lockfile.sync?.skillIds || [],
             ...(options.mode ? { mode: options.mode } : {}),
             ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
         });
@@ -335,6 +348,7 @@ export async function syncInstalledSkills(options = {}) {
             adapter: syncResult.adapter,
             targetPath: syncResult.targetPath,
             syncedAt: now(),
+            skillIds: skills.map((skill) => skill.id),
         };
         lockfile.syncMode = syncResult.syncMode;
         lockfile.updatedAt = now();
@@ -354,14 +368,14 @@ export async function syncInstalledSkills(options = {}) {
     }
 }
 /**
- * Reads the local workspace lockfile when it exists.
+ * Reads the selected Skillex lockfile when it exists.
  *
  * @param options - Project lookup options.
  * @returns Normalized lockfile state or `null` when no install exists.
  */
 export async function getInstalledSkills(options = {}) {
     const cwd = options.cwd || process.cwd();
-    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = resolveStatePathsForOptions(cwd, options);
     if (!(await pathExists(statePaths.lockfilePath))) {
         return null;
     }
@@ -380,7 +394,7 @@ export async function getInstalledSkills(options = {}) {
  */
 export async function resolveProjectSource(options = {}) {
     const cwd = options.cwd || process.cwd();
-    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = resolveStatePathsForOptions(cwd, options);
     const existing = await readJson(statePaths.lockfilePath, null);
     return resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
 }
@@ -392,7 +406,7 @@ export async function resolveProjectSource(options = {}) {
  */
 export async function resolveProjectSources(options = {}) {
     const cwd = options.cwd || process.cwd();
-    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = resolveStatePathsForOptions(cwd, options);
     const existing = await readJson(statePaths.lockfilePath, null);
     if (options.repo) {
         return [toLockfileSource(resolveSource(toCatalogSourceInput(options, { repo: options.repo, ref: options.ref })))];
@@ -435,7 +449,7 @@ export async function loadProjectCatalogs(options = {}, catalogLoader = loadCata
  */
 export async function addProjectSource(sourceInput, options = {}) {
     const cwd = options.cwd || process.cwd();
-    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = resolveStatePathsForOptions(cwd, options);
     const now = getNow(options);
     await ensureDir(statePaths.stateDir);
     await ensureDir(statePaths.skillsDirPath);
@@ -461,11 +475,13 @@ export async function addProjectSource(sourceInput, options = {}) {
  */
 export async function removeProjectSource(repo, options = {}) {
     const cwd = options.cwd || process.cwd();
-    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = resolveStatePathsForOptions(cwd, options);
     const now = getNow(options);
     const existing = await readJson(statePaths.lockfilePath, null);
     if (!existing) {
-        throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+        throw new InstallError(statePaths.scope === "global"
+            ? "No global installation found. Run: skillex init --global --adapter <id>"
+            : "No local installation found. Run: skillex init", "LOCKFILE_MISSING");
     }
     const fallbackSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
     const lockfile = normalizeLockfile(existing, fallbackSource, now);
@@ -489,7 +505,7 @@ export async function removeProjectSource(repo, options = {}) {
  */
 export async function listProjectSources(options = {}) {
     const cwd = options.cwd || process.cwd();
-    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = resolveStatePathsForOptions(cwd, options);
     const existing = await readJson(statePaths.lockfilePath, null);
     const fallbackSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
     return getLockfileSources(existing, fallbackSource);
@@ -657,11 +673,14 @@ function normalizeLockfile(existing, source, now) {
         installed: existing.installed || {},
     };
 }
+/** Repos that are known placeholder values written by older versions and must be ignored. */
+const PLACEHOLDER_REPOS = new Set(["owner/repo"]);
 function getLockfileSources(existing, fallbackSource) {
     const legacyCatalog = getLegacyCatalog(existing);
     const configuredSources = Array.isArray(existing?.sources)
         ? existing.sources
             .filter((entry) => Boolean(entry?.repo))
+            .filter((entry) => !PLACEHOLDER_REPOS.has(entry.repo))
             .map((entry) => ({
             repo: entry.repo,
             ref: entry.ref || DEFAULT_REF,
@@ -671,7 +690,7 @@ function getLockfileSources(existing, fallbackSource) {
     if (configuredSources.length > 0) {
         return dedupeSources(configuredSources);
     }
-    if (legacyCatalog?.repo) {
+    if (legacyCatalog?.repo && !PLACEHOLDER_REPOS.has(legacyCatalog.repo)) {
         return dedupeSources([
             {
                 repo: legacyCatalog.repo,
@@ -781,7 +800,9 @@ function buildInstalledMetadata(skill, context) {
     return {
         name: skill.name,
         version: skill.version,
-        path: toPosix(path.relative(context.cwd, path.join(context.statePaths.skillsDirPath, skill.id))),
+        path: context.statePaths.scope === "global"
+            ? toPosix(path.join(context.statePaths.skillsDirPath, skill.id))
+            : toPosix(path.relative(context.cwd, path.join(context.statePaths.skillsDirPath, skill.id))),
         installedAt: context.installedAt,
         compatibility: skill.compatibility,
         tags: skill.tags,
@@ -799,7 +820,7 @@ function resolveInstalledSkillIds(lockfile, requestedSkillIds) {
     const installedSet = new Set(installedIds);
     for (const skillId of requestedSkillIds) {
         if (!installedSet.has(skillId)) {
-            throw new InstallError(`Skill "${skillId}" is not installed locally.`, "SKILL_NOT_INSTALLED");
+            throw new InstallError(`Skill "${skillId}" is not installed in the selected scope.`, "SKILL_NOT_INSTALLED");
         }
     }
     return requestedSkillIds;
@@ -816,6 +837,7 @@ async function maybeAutoSync(options) {
     }
     return syncInstalledSkills({
         cwd: options.cwd,
+        scope: options.scope || DEFAULT_INSTALL_SCOPE,
         ...(options.agentSkillsDir ? { agentSkillsDir: options.agentSkillsDir } : {}),
         ...(options.adapter ? { adapter: options.adapter } : {}),
         ...(options.mode ? { mode: options.mode } : {}),
@@ -853,6 +875,15 @@ function withAgentSkillsDir(options, agentSkillsDir) {
         ...(agentSkillsDir ? { agentSkillsDir } : {}),
     };
 }
+function resolveStatePathsForOptions(cwd, options) {
+    return getScopedStatePaths(cwd, {
+        scope: options.scope || DEFAULT_INSTALL_SCOPE,
+        baseDir: options.agentSkillsDir,
+    });
+}
+function resolveInstalledSkillPath(cwd, skillPath) {
+    return path.isAbsolute(skillPath) ? skillPath : path.resolve(cwd, skillPath);
+}
 async function confirmDirectInstall(skillRef, options) {
     const warning = `Warning: ${skillRef} will be installed directly from GitHub and has not been verified by the active catalog.`;
     (options.warn || console.error)(warning);

package/dist/runner.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import * as path from "node:path";
-import { DEFAULT_AGENT_SKILLS_DIR, getStatePaths } from "./config.js";
+import { DEFAULT_INSTALL_SCOPE, getScopedStatePaths } from "./config.js";
 import { confirmAction } from "./confirm.js";
 import { readJson } from "./fs.js";
 import { CliError } from "./types.js";
@@ -32,16 +32,21 @@ export function parseSkillCommandReference(value) {
  */
 export async function runSkillScript(skillId, commandName, options = {}) {
     const cwd = options.cwd || process.cwd();
-    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = getScopedStatePaths(cwd, {
+        scope: options.scope || DEFAULT_INSTALL_SCOPE,
+        baseDir: options.agentSkillsDir,
+    });
     const lockfile = (await readJson(statePaths.lockfilePath, null)) || null;
     if (!lockfile) {
-        throw new CliError("Nenhuma instalacao local encontrada. Rode: skillex init", "LOCKFILE_MISSING");
+        throw new CliError(statePaths.scope === "global"
+            ? "Nenhuma instalacao global encontrada. Rode: skillex init --global --adapter <id>"
+            : "Nenhuma instalacao local encontrada. Rode: skillex init", "LOCKFILE_MISSING");
     }
     const metadata = lockfile.installed?.[skillId];
     if (!metadata?.path) {
         throw new CliError(`Skill "${skillId}" nao esta instalada.`, "SKILL_NOT_INSTALLED");
     }
-    const skillDir = path.resolve(cwd, metadata.path);
+    const skillDir = path.isAbsolute(metadata.path) ? metadata.path : path.resolve(cwd, metadata.path);
     const manifest = (await readJson(path.join(skillDir, "skill.json"), {})) || {};
     const scripts = manifest.scripts || {};
     const script = scripts[commandName];

package/dist/sync.d.ts

@@ -1,6 +1,6 @@
 import type { InstalledSkillDocument, LockfileState, PreparedSyncResult, SyncOptions, SyncResult } from "./types.js";
 /**
- * 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.
@@ -10,7 +10,7 @@ export declare function loadInstalledSkillDocuments(context: {
     lockfile: LockfileState;
 }): Promise<InstalledSkillDocument[]>;
 /**
- * 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.