@rudderhq/server 0.5.2-canary.2 → 0.6.0

package/dist/services/knowledge-portability/organization-skills.js

@@ -2,6 +2,7 @@ import { readRudderSkillSyncPreference, writeRudderSkillSyncPreference } from "@
 import { agents as agentRows, organizationSkills } from "@rudderhq/db";
 import { getActiveRudderBundledSkillSlugs, getBundledRudderSkillSlug, isRetiredRudderCreationSkillReference, toBundledRudderSkillKey, } from "@rudderhq/shared";
 import { and, asc, eq } from "drizzle-orm";
+import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { conflict, notFound, unprocessable } from "../../errors.js";
@@ -11,9 +12,12 @@ import { agentService } from "../agents.js";
 import { resolveBrowserCapability, resolveBrowserCapabilityDeployment, } from "../browser-capability.js";
 import { instanceSettingsService } from "../instance-settings.js";
 import { projectService } from "../projects.js";
-import { ADAPTER_SKILL_HOME_DEFINITIONS, COMMUNITY_PRESET_SKILLS, COMMUNITY_PRESET_SKILL_SLUGS, applyDesiredSelectionsToCatalog, arraysEqual, asString, buildAgentPrivateSkillEntry, buildAgentSelectionKey, buildBundledSelectionKey, buildDraftSkillMarkdown, buildGlobalSelectionKey, buildOrganizationSelectionKey, buildSkillRuntimeName, compareOrganizationSkillListItems, deriveCanonicalSkillKey, deriveSkillSourceInfo, enrichSkill, findMissingLocalSkillIds, getRequiredBundledSkillKeys, getSkillMeta, inferLanguageFromPath, isBundledRudderSkillKey, isBundledRudderSourceKind, isMarkdownPath, isPlainRecord, listLegacyUserHomeLocalScanSkillIds, listStaleBundledSkillIds, listStaleCommunityPresetSkillIds, normalizeGitHubSkillDirectory, normalizePackageFileMap, normalizePortablePath, normalizeSelectionRef, normalizeSkillDescription, normalizeSkillDirectory, normalizeSkillSlug, parseSelectionKey, readAdapterSkillCatalogEntries, readDiscoveredSkillEntries, resolveConfiguredHomeDir, resolveLocalSkillFilePath, resolveManagedSkillsRoot, resolveRequestedSkillKeysOrThrow, resolveWorkspaceEditPath, serializeFileInventory, skillInventoryRefreshPromises, sortUniqueSelectionRefs, statPath, toCompanySkill, toCompanySkillListItem, uniqueImportedSkillKey, uniqueSkillSlug } from "./organization-skills.catalog.js";
+import { ADAPTER_SKILL_HOME_DEFINITIONS, COMMUNITY_PRESET_SKILLS, COMMUNITY_PRESET_SKILL_SLUGS, applyDesiredSelectionsToCatalog, arraysEqual, asString, buildAgentPrivateSkillEntry, buildAgentSelectionKey, buildBundledSelectionKey, buildDraftSkillMarkdown, buildGlobalSelectionKey, buildOrganizationSelectionKey, buildSkillRuntimeName, compareOrganizationSkillListItems, deriveCanonicalSkillKey, deriveSkillSourceInfo, enrichSkill, findMissingLocalSkillIds, getRequiredBundledSkillKeys, getSkillMeta, inferLanguageFromPath, isBundledRudderSkillKey, isBundledRudderSourceKind, isMarkdownPath, isPlainRecord, listLegacyUserHomeLocalScanSkillIds, listStaleBundledSkillIds, listStaleCommunityPresetSkillIds, normalizePackageFileMap, normalizePortablePath, normalizeSafeRelativeSkillPath, normalizeSelectionRef, normalizeSkillDescription, normalizeSkillDirectory, normalizeSkillSlug, parseSelectionKey, readAdapterSkillCatalogEntries, readDiscoveredSkillEntries, resolveConfiguredHomeDir, resolveLocalSkillFilePath, resolveManagedSkillsRoot, resolveRequestedSkillKeysOrThrow, resolveWorkspaceEditPath, serializeFileInventory, skillInventoryRefreshPromises, sortUniqueSelectionRefs, statPath, toCompanySkill, toCompanySkillListItem, uniqueImportedSkillKey, uniqueSkillSlug } from "./organization-skills.catalog.js";
 import { createOrganizationSkillScanHandlers } from "./organization-skills.scans.js";
-import { fetchText, parseFrontmatterMarkdown, parseSkillImportSourceInput, readCommunityPresetFallbackImport, readInlineSkillImports, readLocalSkillImportFromDirectory, readLocalSkillImports, readUrlSkillImports, resolveBundledSkillsRoot, resolveCommunityPresetSkillsRoot, resolveGitHubCommitSha, resolveRawGitHubUrl, } from "./organization-skills.sources.js";
+import { parseFrontmatterMarkdown, parseSkillImportSourceInput, readCommunityPresetFallbackImport, readInlineSkillImports, readLocalSkillImportFromDirectory, readLocalSkillImports, readUrlSkillImports, resolveBundledSkillsRoot, resolveCommunityPresetSkillsRoot, resolveGitHubCommitSha, } from "./organization-skills.sources.js";
+const ORGANIZATION_SKILL_INSTALLATION_VERSION = 1;
+const skillInstallationPromises = new Map();
+const skillMutationLocks = new Map();
 export function organizationSkillService(db, options = {}) {
     const deploymentMode = resolveBrowserCapabilityDeployment(db, options.deploymentMode);
     const agents = agentService(db);
@@ -25,6 +29,318 @@ export function organizationSkillService(db, options = {}) {
         projects,
         upsertImportedSkills,
     });
+    function normalizeInstalledFilePath(relativePath) {
+        const normalized = normalizeSafeRelativeSkillPath(relativePath);
+        if (!normalized) {
+            throw unprocessable(`Invalid skill file path: ${relativePath}`);
+        }
+        return normalized;
+    }
+    function resolveInstalledSkillDirectory(orgId, key, slug) {
+        const managedRoot = path.resolve(resolveManagedSkillsRoot(orgId));
+        const installedRoot = path.resolve(managedRoot, "__installed__");
+        const target = path.resolve(installedRoot, buildSkillRuntimeName(key, slug));
+        const relative = path.relative(installedRoot, target);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw unprocessable("Invalid organization skill installation path.");
+        }
+        return target;
+    }
+    async function removeInstalledSkillDirectory(orgId, skill) {
+        if (getSkillMeta(skill).installationVersion !== ORGANIZATION_SKILL_INSTALLATION_VERSION)
+            return;
+        await fs.rm(resolveInstalledSkillDirectory(orgId, skill.key, skill.slug), { recursive: true, force: true });
+    }
+    async function mapWithConcurrency(values, concurrency, operation) {
+        let nextIndex = 0;
+        const workers = Array.from({ length: Math.min(Math.max(1, concurrency), values.length) }, async () => {
+            while (nextIndex < values.length) {
+                const index = nextIndex;
+                nextIndex += 1;
+                await operation(values[index]);
+            }
+        });
+        await Promise.all(workers);
+    }
+    async function withSkillMutationLock(orgId, skillKey, operation) {
+        const lockKey = `${orgId}:${skillKey}`;
+        const previous = skillMutationLocks.get(lockKey) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        skillMutationLocks.set(lockKey, current);
+        await previous.catch(() => { });
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (skillMutationLocks.get(lockKey) === current) {
+                skillMutationLocks.delete(lockKey);
+            }
+        }
+    }
+    async function readImportedSkillFiles(skill) {
+        const files = new Map();
+        for (const [rawPath, content] of Object.entries(skill.files ?? {})) {
+            files.set(normalizeInstalledFilePath(rawPath), content);
+        }
+        if (skill.packageDir) {
+            await mapWithConcurrency(skill.fileInventory, 8, async (entry) => {
+                const relativePath = normalizeInstalledFilePath(entry.path);
+                if (files.has(relativePath))
+                    return;
+                files.set(relativePath, await fs.readFile(path.resolve(skill.packageDir, relativePath)));
+            });
+        }
+        for (const entry of skill.fileInventory) {
+            const relativePath = normalizeInstalledFilePath(entry.path);
+            if (!files.has(relativePath)) {
+                throw unprocessable(`Skill source did not provide declared file: ${relativePath}`);
+            }
+        }
+        return files;
+    }
+    async function replaceInstalledSkillDirectory(orgId, skill, files, persist) {
+        const target = resolveInstalledSkillDirectory(orgId, skill.key, skill.slug);
+        const parent = path.dirname(target);
+        const staging = path.join(parent, `.${path.basename(target)}.staging-${randomUUID()}`);
+        const backup = path.join(parent, `.${path.basename(target)}.backup-${randomUUID()}`);
+        let movedExisting = false;
+        async function restorePreviousInstallation(originalError) {
+            const displaced = path.join(parent, `.${path.basename(target)}.rollback-displaced-${randomUUID()}`);
+            let movedCurrentTarget = false;
+            try {
+                if (await fs.stat(target).catch(() => null)) {
+                    await fs.rename(target, displaced);
+                    movedCurrentTarget = true;
+                }
+                await fs.rename(backup, target);
+                movedExisting = false;
+                if (movedCurrentTarget) {
+                    await fs.rm(displaced, { recursive: true, force: true });
+                    movedCurrentTarget = false;
+                }
+            }
+            catch (rollbackError) {
+                if (movedCurrentTarget
+                    && !(await fs.stat(target).catch(() => null))) {
+                    await fs.rename(displaced, target).catch(() => { });
+                }
+                throw conflict("Organization skill installation consistency error: rollback could not restore the previous installation.", {
+                    target,
+                    backup,
+                    originalError: originalError instanceof Error
+                        ? originalError.message
+                        : String(originalError),
+                    rollbackError: rollbackError instanceof Error
+                        ? rollbackError.message
+                        : String(rollbackError),
+                });
+            }
+        }
+        async function removeFailedInstallation(originalError) {
+            try {
+                await fs.rm(target, { recursive: true, force: true });
+            }
+            catch (rollbackError) {
+                throw conflict("Organization skill installation consistency error: rollback could not remove the failed installation.", {
+                    target,
+                    originalError: originalError instanceof Error
+                        ? originalError.message
+                        : String(originalError),
+                    rollbackError: rollbackError instanceof Error
+                        ? rollbackError.message
+                        : String(rollbackError),
+                });
+            }
+        }
+        await fs.mkdir(staging, { recursive: true });
+        try {
+            await mapWithConcurrency(skill.fileInventory, 8, async (entry) => {
+                const relativePath = normalizeInstalledFilePath(entry.path);
+                const targetPath = path.resolve(staging, relativePath);
+                const relativeTarget = path.relative(staging, targetPath);
+                if (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget)) {
+                    throw unprocessable(`Invalid skill file path: ${entry.path}`);
+                }
+                const content = files.get(relativePath);
+                if (content === undefined) {
+                    throw unprocessable(`Skill source did not provide declared file: ${relativePath}`);
+                }
+                await fs.mkdir(path.dirname(targetPath), { recursive: true });
+                await fs.writeFile(targetPath, content);
+            });
+            const skillFile = await fs.stat(path.join(staging, "SKILL.md")).catch(() => null);
+            if (!skillFile?.isFile()) {
+                throw unprocessable("Installed skill is missing SKILL.md.");
+            }
+            await fs.mkdir(parent, { recursive: true });
+            const existing = await fs.stat(target).catch(() => null);
+            if (existing) {
+                await fs.rename(target, backup);
+                movedExisting = true;
+            }
+            try {
+                await fs.rename(staging, target);
+            }
+            catch (error) {
+                if (movedExisting) {
+                    await restorePreviousInstallation(error);
+                }
+                throw error;
+            }
+            let persisted;
+            try {
+                persisted = await persist();
+            }
+            catch (error) {
+                if (movedExisting) {
+                    await restorePreviousInstallation(error);
+                }
+                else {
+                    await removeFailedInstallation(error);
+                }
+                throw error;
+            }
+            if (movedExisting) {
+                await fs.rm(backup, { recursive: true, force: true });
+                movedExisting = false;
+            }
+            return persisted;
+        }
+        finally {
+            await fs.rm(staging, { recursive: true, force: true });
+        }
+    }
+    async function installImportedSkill(orgId, skill, persist) {
+        const sourceKind = asString(skill.metadata?.sourceKind);
+        if (isBundledRudderSourceKind(sourceKind))
+            return persist(skill);
+        const installed = markImportedSkillInstalled(skill);
+        const files = await readImportedSkillFiles(installed);
+        return withSkillMutationLock(orgId, installed.key, () => replaceInstalledSkillDirectory(orgId, installed, files, () => persist(installed)));
+    }
+    function markImportedSkillInstalled(skill) {
+        return {
+            ...skill,
+            metadata: {
+                ...(skill.metadata ?? {}),
+                installationVersion: ORGANIZATION_SKILL_INSTALLATION_VERSION,
+            },
+        };
+    }
+    function hasUnchangedInstallationSource(current, snapshot) {
+        return current.sourceType === snapshot.sourceType
+            && current.sourceLocator === snapshot.sourceLocator
+            && current.sourceRef === snapshot.sourceRef
+            && getSkillMeta(current).installationVersion
+                === getSkillMeta(snapshot).installationVersion
+            && current.updatedAt.getTime() === snapshot.updatedAt.getTime();
+    }
+    async function resolveCurrentSkillDirectory(skill) {
+        const directory = normalizeSkillDirectory(skill);
+        if (directory
+            && (await fs.stat(path.join(directory, "SKILL.md")).catch(() => null))?.isFile()) {
+            return directory;
+        }
+        return null;
+    }
+    function isStrictlyWithinPath(root, target) {
+        const relative = path.relative(root, target);
+        return Boolean(relative)
+            && !relative.startsWith("..")
+            && !path.isAbsolute(relative);
+    }
+    async function resolveValidatedLocalSkillFilePath(skill, relativePath) {
+        const absolutePath = resolveLocalSkillFilePath(skill, relativePath);
+        const skillRoot = normalizeSkillDirectory(skill);
+        if (!absolutePath || !skillRoot)
+            return null;
+        const realRoot = await fs.realpath(skillRoot).catch(() => null);
+        if (!realRoot)
+            return null;
+        const targetEntry = await fs.lstat(absolutePath).catch(() => null);
+        if (targetEntry) {
+            const realTarget = await fs.realpath(absolutePath).catch(() => null);
+            return realTarget && isStrictlyWithinPath(realRoot, realTarget)
+                ? absolutePath
+                : null;
+        }
+        let existingAncestor = path.dirname(absolutePath);
+        while (!(await fs.lstat(existingAncestor).catch(() => null))
+            && existingAncestor !== path.dirname(existingAncestor)) {
+            existingAncestor = path.dirname(existingAncestor);
+        }
+        const realAncestor = await fs.realpath(existingAncestor).catch(() => null);
+        if (!realAncestor
+            || (realAncestor !== realRoot && !isStrictlyWithinPath(realRoot, realAncestor))) {
+            return null;
+        }
+        const projectedTarget = path.resolve(realAncestor, path.relative(existingAncestor, absolutePath));
+        return isStrictlyWithinPath(realRoot, projectedTarget) ? absolutePath : null;
+    }
+    async function assertDirectLocalSourceIsUnmanaged(orgId, skill) {
+        const sourcePath = skill.packageDir ?? skill.sourceLocator;
+        if (!sourcePath)
+            throw unprocessable("Local skill source path is missing.");
+        const sourceDirectory = path.basename(sourcePath).toLowerCase() === "skill.md"
+            ? path.dirname(sourcePath)
+            : sourcePath;
+        const managedInstalledRoot = path.resolve(resolveManagedSkillsRoot(orgId), "__installed__");
+        const [resolvedSource, resolvedManagedRoot] = await Promise.all([
+            fs.realpath(path.resolve(sourceDirectory)).catch(() => path.resolve(sourceDirectory)),
+            fs.realpath(managedInstalledRoot).catch(() => managedInstalledRoot),
+        ]);
+        const relative = path.relative(resolvedManagedRoot, resolvedSource);
+        if (!relative || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+            throw unprocessable("Managed organization skill installations cannot be imported as direct local sources.");
+        }
+    }
+    async function upsertDirectLocalSkill(orgId, skill) {
+        return withSkillMutationLock(orgId, skill.key, async () => {
+            await assertDirectLocalSourceIsUnmanaged(orgId, skill);
+            const existing = await getByKey(orgId, skill.key);
+            if (existing
+                && isBundledRudderSourceKind(asString(getSkillMeta(existing).sourceKind))) {
+                return existing;
+            }
+            const [persisted] = await upsertImportedSkills(orgId, [skill]);
+            if (!persisted)
+                throw notFound("Failed to persist organization skill");
+            // The database transition must succeed before retiring the managed copy so
+            // a failed local-path upsert leaves the previous installation runnable.
+            if (existing
+                && getSkillMeta(existing).installationVersion
+                    === ORGANIZATION_SKILL_INSTALLATION_VERSION) {
+                await removeInstalledSkillDirectory(orgId, existing);
+            }
+            return persisted;
+        });
+    }
+    async function installAndUpsertImportedSkills(orgId, skills) {
+        const out = [];
+        for (const skill of skills) {
+            const existing = await getByKey(orgId, skill.key);
+            if (existing
+                && isBundledRudderSourceKind(asString(getSkillMeta(existing).sourceKind))) {
+                out.push(existing);
+                continue;
+            }
+            if (skill.sourceType === "local_path") {
+                out.push(await upsertDirectLocalSkill(orgId, skill));
+                continue;
+            }
+            out.push(await installImportedSkill(orgId, skill, async (installed) => {
+                const [persisted] = await upsertImportedSkills(orgId, [installed]);
+                if (!persisted)
+                    throw notFound("Failed to persist organization skill");
+                return persisted;
+            }));
+        }
+        return out;
+    }
     async function getAgentWorkspaceRow(orgId, agentId) {
         const row = await db
             .select({
@@ -187,7 +503,9 @@ export function organizationSkillService(db, options = {}) {
             const existing = existingByKey.get(skill.key);
             if (!existing)
                 return true;
-            return asString(existing.metadata?.sourceKind) === "community_preset";
+            const existingMetadata = isPlainRecord(existing.metadata) ? existing.metadata : {};
+            return asString(existingMetadata.sourceKind) === "community_preset"
+                && existingMetadata.installationVersion !== ORGANIZATION_SKILL_INSTALLATION_VERSION;
         });
         const persisted = toPersist.length > 0 ? await upsertImportedSkills(orgId, toPersist) : [];
         const stalePresetIds = listStaleCommunityPresetSkillIds(existingRows, currentCommunityPresetKeys);
@@ -217,7 +535,7 @@ export function organizationSkillService(db, options = {}) {
             await db
                 .delete(organizationSkills)
                 .where(eq(organizationSkills.id, skill.id));
-            await fs.rm(resolveRuntimeSkillMaterializedPath(orgId, skill), { recursive: true, force: true });
+            await removeInstalledSkillDirectory(orgId, skill);
         }
     }
     async function pruneLegacyUserHomeLocalScanSkills(orgId) {
@@ -239,7 +557,7 @@ export function organizationSkillService(db, options = {}) {
             await db
                 .delete(organizationSkills)
                 .where(eq(organizationSkills.id, skill.id));
-            await fs.rm(resolveRuntimeSkillMaterializedPath(orgId, skill), { recursive: true, force: true });
+            await removeInstalledSkillDirectory(orgId, skill);
         }
     }
     async function backfillMissingSkillDescriptions(orgId) {
@@ -574,10 +892,14 @@ export function organizationSkillService(db, options = {}) {
                 if (!skill)
                     continue;
                 let source = normalizeSkillDirectory(skill);
+                if (source
+                    && !(await fs.stat(path.join(source, "SKILL.md")).catch(() => null))?.isFile()) {
+                    source = null;
+                }
                 if (!source) {
                     source = options.materializeMissing === false
-                        ? resolveRuntimeSkillMaterializedPath(orgId, skill)
-                        : await materializeRuntimeSkillFiles(orgId, skill).catch(() => null);
+                        ? null
+                        : await ensureInstalledSkill(orgId, skill).catch(() => null);
                 }
                 if (!source)
                     continue;
@@ -705,15 +1027,18 @@ export function organizationSkillService(db, options = {}) {
         const skill = await getById(skillId);
         if (!skill || skill.orgId !== orgId)
             return null;
-        const normalizedPath = normalizePortablePath(relativePath || "SKILL.md");
+        const normalizedPath = normalizeSafeRelativeSkillPath(relativePath || "SKILL.md");
+        if (!normalizedPath)
+            throw notFound("Skill file not found");
         const fileEntry = skill.fileInventory.find((entry) => entry.path === normalizedPath);
         if (!fileEntry) {
             throw notFound("Skill file not found");
         }
         const source = deriveSkillSourceInfo(skill);
         let content = "";
-        if (skill.sourceType === "local_path" || skill.sourceType === "catalog") {
-            const absolutePath = resolveLocalSkillFilePath(skill, normalizedPath);
+        const localSkillDirectory = normalizeSkillDirectory(skill);
+        if (localSkillDirectory) {
+            const absolutePath = await resolveValidatedLocalSkillFilePath(skill, normalizedPath);
             if (absolutePath) {
                 content = await fs.readFile(absolutePath, "utf8");
             }
@@ -724,26 +1049,11 @@ export function organizationSkillService(db, options = {}) {
                 throw notFound("Skill file not found");
             }
         }
-        else if (skill.sourceType === "github" || skill.sourceType === "skills_sh") {
-            const metadata = getSkillMeta(skill);
-            const owner = asString(metadata.owner);
-            const repo = asString(metadata.repo);
-            const ref = skill.sourceRef ?? asString(metadata.ref) ?? "main";
-            const repoSkillDir = normalizeGitHubSkillDirectory(asString(metadata.repoSkillDir), skill.slug);
-            if (!owner || !repo) {
-                throw unprocessable("Skill source metadata is incomplete.");
-            }
-            const repoPath = normalizePortablePath(path.posix.join(repoSkillDir, normalizedPath));
-            content = await fetchText(resolveRawGitHubUrl(owner, repo, ref, repoPath));
-        }
-        else if (skill.sourceType === "url") {
-            if (normalizedPath !== "SKILL.md") {
-                throw notFound("This skill source only exposes SKILL.md");
-            }
+        else if (normalizedPath === "SKILL.md") {
             content = skill.markdown;
         }
         else {
-            throw unprocessable("Unsupported skill source.");
+            throw notFound("Skill file is not installed yet.");
         }
         return {
             skillId: skill.id,
@@ -810,37 +1120,90 @@ export function organizationSkillService(db, options = {}) {
         if (!skill || skill.orgId !== orgId)
             throw notFound("Skill not found");
         const source = deriveSkillSourceInfo(skill);
-        if (!source.editable || skill.sourceType !== "local_path") {
+        if (!source.editable) {
             throw unprocessable(source.editableReason ?? "This skill cannot be edited.");
         }
-        const normalizedPath = normalizePortablePath(relativePath);
-        const absolutePath = resolveLocalSkillFilePath(skill, normalizedPath);
-        if (!absolutePath)
-            throw notFound("Skill file not found");
-        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-        await fs.writeFile(absolutePath, content, "utf8");
-        if (normalizedPath === "SKILL.md") {
-            const parsed = parseFrontmatterMarkdown(content);
-            await db
-                .update(organizationSkills)
-                .set({
-                name: asString(parsed.frontmatter.name) ?? skill.name,
-                description: normalizeSkillDescription(parsed.frontmatter.description) ?? skill.description,
-                markdown: content,
-                updatedAt: new Date(),
-            })
-                .where(eq(organizationSkills.id, skill.id));
-        }
-        else {
-            await db
-                .update(organizationSkills)
-                .set({ updatedAt: new Date() })
-                .where(eq(organizationSkills.id, skill.id));
-        }
-        const detail = await readFile(orgId, skillId, normalizedPath);
-        if (!detail)
-            throw notFound("Skill file not found");
-        return detail;
+        await ensureInstalledSkill(orgId, skill);
+        return withSkillMutationLock(orgId, skill.key, async () => {
+            const current = await getById(skillId);
+            if (!current || current.orgId !== orgId)
+                throw notFound("Skill not found");
+            const currentSource = deriveSkillSourceInfo(current);
+            if (!currentSource.editable) {
+                throw unprocessable(currentSource.editableReason ?? "This skill cannot be edited.");
+            }
+            const normalizedPath = normalizeSafeRelativeSkillPath(relativePath);
+            if (!normalizedPath)
+                throw notFound("Skill file not found");
+            if (!current.fileInventory.some((entry) => entry.path === normalizedPath)) {
+                throw notFound("Skill file not found");
+            }
+            const absolutePath = await resolveValidatedLocalSkillFilePath(current, normalizedPath);
+            if (!absolutePath)
+                throw notFound("Skill file not found");
+            let previousContent = null;
+            let fileExisted = false;
+            try {
+                previousContent = await fs.readFile(absolutePath);
+                fileExisted = true;
+            }
+            catch (error) {
+                if (!(error instanceof Error)
+                    || !("code" in error)
+                    || error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+            await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+            await fs.writeFile(absolutePath, content, "utf8");
+            try {
+                if (normalizedPath === "SKILL.md") {
+                    const parsed = parseFrontmatterMarkdown(content);
+                    await db
+                        .update(organizationSkills)
+                        .set({
+                        name: asString(parsed.frontmatter.name) ?? current.name,
+                        description: normalizeSkillDescription(parsed.frontmatter.description)
+                            ?? current.description,
+                        markdown: content,
+                        updatedAt: new Date(),
+                    })
+                        .where(eq(organizationSkills.id, current.id));
+                }
+                else {
+                    await db
+                        .update(organizationSkills)
+                        .set({ updatedAt: new Date() })
+                        .where(eq(organizationSkills.id, current.id));
+                }
+            }
+            catch (persistenceError) {
+                try {
+                    if (fileExisted) {
+                        await fs.writeFile(absolutePath, previousContent);
+                    }
+                    else {
+                        await fs.rm(absolutePath, { force: true });
+                    }
+                }
+                catch (rollbackError) {
+                    throw conflict("Organization skill edit consistency error: rollback could not restore the previous file.", {
+                        path: normalizedPath,
+                        persistenceError: persistenceError instanceof Error
+                            ? persistenceError.message
+                            : String(persistenceError),
+                        rollbackError: rollbackError instanceof Error
+                            ? rollbackError.message
+                            : String(rollbackError),
+                    });
+                }
+                throw persistenceError;
+            }
+            const detail = await readFile(orgId, skillId, normalizedPath);
+            if (!detail)
+                throw notFound("Skill file not found");
+            return detail;
+        });
     }
     async function syncWorkspaceFileChange(orgId, workspaceFilePath, content) {
         await ensureSkillInventoryCurrent(orgId);
@@ -890,48 +1253,174 @@ export function organizationSkillService(db, options = {}) {
         if (!matching) {
             throw unprocessable(`Skill ${skill.key} could not be re-imported from its source.`);
         }
-        const imported = await upsertImportedSkills(orgId, [matching]);
-        return imported[0] ?? null;
+        return installImportedSkill(orgId, {
+            ...matching,
+            key: skill.key,
+            slug: skill.slug,
+            sourceType: skill.sourceType,
+            sourceLocator: skill.sourceLocator,
+            metadata: {
+                ...(skill.metadata ?? {}),
+                ...(matching.metadata ?? {}),
+                sourceKind: asString(skill.metadata?.sourceKind)
+                    ?? asString(matching.metadata?.sourceKind),
+            },
+        }, async (installed) => {
+            const current = await getById(skill.id);
+            if (!current)
+                throw conflict(`Skill ${skill.key} no longer exists.`);
+            if (!hasUnchangedInstallationSource(current, skill)) {
+                throw conflict(`Skill ${skill.key} changed while update was downloading.`);
+            }
+            const [persisted] = await upsertImportedSkills(orgId, [installed]);
+            return persisted ?? null;
+        });
     }
-    async function materializeCatalogSkillFiles(orgId, skill, normalizedFiles) {
-        const packageDir = skill.packageDir ? normalizePortablePath(skill.packageDir) : null;
-        if (!packageDir)
-            return null;
-        const catalogRoot = path.resolve(resolveManagedSkillsRoot(orgId), "__catalog__");
-        const skillDir = path.resolve(catalogRoot, buildSkillRuntimeName(skill.key, skill.slug));
-        await fs.rm(skillDir, { recursive: true, force: true });
-        await fs.mkdir(skillDir, { recursive: true });
-        for (const entry of skill.fileInventory) {
-            const sourcePath = entry.path === "SKILL.md"
-                ? `${packageDir}/SKILL.md`
-                : `${packageDir}/${entry.path}`;
-            const content = normalizedFiles[sourcePath];
-            if (typeof content !== "string")
-                continue;
-            const targetPath = path.resolve(skillDir, entry.path);
-            await fs.mkdir(path.dirname(targetPath), { recursive: true });
-            await fs.writeFile(targetPath, content, "utf8");
+    async function ensureInstalledSkill(orgId, skill) {
+        const existingDirectory = normalizeSkillDirectory(skill);
+        if (existingDirectory
+            && (await fs.stat(path.join(existingDirectory, "SKILL.md")).catch(() => null))?.isFile()) {
+            return existingDirectory;
         }
-        return skillDir;
-    }
-    async function materializeRuntimeSkillFiles(orgId, skill) {
-        const runtimeRoot = path.resolve(resolveManagedSkillsRoot(orgId), "__runtime__");
-        const skillDir = path.resolve(runtimeRoot, buildSkillRuntimeName(skill.key, skill.slug));
-        await fs.rm(skillDir, { recursive: true, force: true });
-        await fs.mkdir(skillDir, { recursive: true });
-        for (const entry of skill.fileInventory) {
-            const detail = await readFile(orgId, skill.id, entry.path).catch(() => null);
-            if (!detail)
-                continue;
-            const targetPath = path.resolve(skillDir, entry.path);
-            await fs.mkdir(path.dirname(targetPath), { recursive: true });
-            await fs.writeFile(targetPath, detail.content, "utf8");
+        if (isBundledRudderSourceKind(asString(skill.metadata?.sourceKind))) {
+            throw unprocessable("Bundled Rudder skill files are unavailable.");
+        }
+        const lockKey = `${orgId}:${skill.id}`;
+        const existingInstall = skillInstallationPromises.get(lockKey);
+        if (existingInstall)
+            return existingInstall;
+        const installation = (async () => {
+            const target = resolveInstalledSkillDirectory(orgId, skill.key, skill.slug);
+            if ((await fs.stat(path.join(target, "SKILL.md")).catch(() => null))?.isFile()) {
+                return withSkillMutationLock(orgId, skill.key, async () => {
+                    const current = await getById(skill.id);
+                    if (!current)
+                        throw notFound(`Skill ${skill.key} no longer exists.`);
+                    if (!hasUnchangedInstallationSource(current, skill)) {
+                        const currentDirectory = await resolveCurrentSkillDirectory(current);
+                        if (currentDirectory)
+                            return currentDirectory;
+                        throw conflict(`Skill ${skill.key} changed while installation was prepared.`);
+                    }
+                    if (getSkillMeta(current).installationVersion
+                        !== ORGANIZATION_SKILL_INSTALLATION_VERSION) {
+                        await db
+                            .update(organizationSkills)
+                            .set({
+                            metadata: {
+                                ...(current.metadata ?? {}),
+                                installationVersion: ORGANIZATION_SKILL_INSTALLATION_VERSION,
+                            },
+                            updatedAt: new Date(),
+                        })
+                            .where(eq(organizationSkills.id, current.id));
+                    }
+                    return target;
+                });
+            }
+            let imported = null;
+            if (skill.sourceType === "github"
+                || skill.sourceType === "skills_sh"
+                || skill.sourceType === "url") {
+                if (!skill.sourceLocator) {
+                    throw unprocessable("Skill source locator is missing.");
+                }
+                const skillMetadata = getSkillMeta(skill);
+                const owner = asString(skillMetadata.owner);
+                const repo = asString(skillMetadata.repo);
+                const repoSkillDir = asString(skillMetadata.repoSkillDir);
+                const migrationSource = ((skill.sourceType === "github" || skill.sourceType === "skills_sh")
+                    && skill.sourceRef
+                    && owner
+                    && repo)
+                    ? `https://github.com/${owner}/${repo}/tree/${skill.sourceRef}${repoSkillDir ? `/${repoSkillDir}` : ""}`
+                    : skill.sourceLocator;
+                const parsed = parseSkillImportSourceInput(migrationSource);
+                const result = await readUrlSkillImports(orgId, parsed.resolvedSource, parsed.requestedSkillSlug ?? skill.slug);
+                imported = result.skills.find((entry) => entry.key === skill.key)
+                    ?? result.skills.find((entry) => entry.slug === skill.slug)
+                    ?? result.skills[0]
+                    ?? null;
+            }
+            else if ((skill.sourceType === "local_path" || skill.sourceType === "catalog")
+                && skill.sourceLocator) {
+                const sourceDirectory = path.basename(skill.sourceLocator).toLowerCase() === "skill.md"
+                    ? path.dirname(skill.sourceLocator)
+                    : skill.sourceLocator;
+                imported = {
+                    key: skill.key,
+                    slug: skill.slug,
+                    name: skill.name,
+                    description: skill.description,
+                    markdown: skill.markdown,
+                    packageDir: path.resolve(sourceDirectory),
+                    sourceType: skill.sourceType,
+                    sourceLocator: skill.sourceLocator,
+                    sourceRef: skill.sourceRef,
+                    trustLevel: skill.trustLevel,
+                    compatibility: skill.compatibility,
+                    fileInventory: skill.fileInventory,
+                    metadata: skill.metadata ?? {},
+                };
+            }
+            if (!imported) {
+                throw unprocessable(`Skill ${skill.key} could not be installed from its source.`);
+            }
+            const installed = markImportedSkillInstalled({
+                ...imported,
+                key: skill.key,
+                slug: skill.slug,
+                sourceType: skill.sourceType,
+                sourceLocator: skill.sourceLocator,
+                sourceRef: skill.sourceRef ?? imported.sourceRef,
+                metadata: {
+                    ...(skill.metadata ?? {}),
+                    ...(imported.metadata ?? {}),
+                    sourceKind: asString(skill.metadata?.sourceKind)
+                        ?? asString(imported.metadata?.sourceKind),
+                    trackingRef: asString(skill.metadata?.trackingRef)
+                        ?? asString(imported.metadata?.trackingRef),
+                },
+            });
+            const files = await readImportedSkillFiles(installed);
+            return withSkillMutationLock(orgId, skill.key, async () => {
+                const current = await getById(skill.id);
+                if (!current)
+                    throw notFound(`Skill ${skill.key} no longer exists.`);
+                if (!hasUnchangedInstallationSource(current, skill)) {
+                    const currentDirectory = await resolveCurrentSkillDirectory(current);
+                    if (currentDirectory)
+                        return currentDirectory;
+                    throw conflict(`Skill ${skill.key} changed while installation was prepared.`);
+                }
+                return replaceInstalledSkillDirectory(orgId, installed, files, async () => {
+                    await db
+                        .update(organizationSkills)
+                        .set({
+                        name: installed.name,
+                        description: installed.description,
+                        markdown: installed.markdown,
+                        sourceRef: installed.sourceRef,
+                        trustLevel: installed.trustLevel,
+                        compatibility: installed.compatibility,
+                        fileInventory: serializeFileInventory(installed.fileInventory),
+                        metadata: installed.metadata,
+                        updatedAt: new Date(),
+                    })
+                        .where(eq(organizationSkills.id, skill.id));
+                    return resolveInstalledSkillDirectory(orgId, skill.key, skill.slug);
+                });
+            });
+        })();
+        skillInstallationPromises.set(lockKey, installation);
+        try {
+            return await installation;
+        }
+        finally {
+            if (skillInstallationPromises.get(lockKey) === installation) {
+                skillInstallationPromises.delete(lockKey);
+            }
         }
-        return skillDir;
-    }
-    function resolveRuntimeSkillMaterializedPath(orgId, skill) {
-        const runtimeRoot = path.resolve(resolveManagedSkillsRoot(orgId), "__runtime__");
-        return path.resolve(runtimeRoot, buildSkillRuntimeName(skill.key, skill.slug));
     }
     async function listRuntimeSkillEntries(orgId, options = {}) {
         const skills = await listFull(orgId);
@@ -942,10 +1431,14 @@ export function organizationSkillService(db, options = {}) {
                 continue;
             }
             let source = normalizeSkillDirectory(skill);
+            if (source
+                && !(await fs.stat(path.join(source, "SKILL.md")).catch(() => null))?.isFile()) {
+                source = null;
+            }
             if (!source) {
                 source = options.materializeMissing === false
-                    ? resolveRuntimeSkillMaterializedPath(orgId, skill)
-                    : await materializeRuntimeSkillFiles(orgId, skill).catch(() => null);
+                    ? null
+                    : await ensureInstalledSkill(orgId, skill).catch(() => null);
             }
             if (!source)
                 continue;
@@ -967,12 +1460,22 @@ export function organizationSkillService(db, options = {}) {
         if (importedSkills.length === 0)
             return [];
         for (const skill of importedSkills) {
-            if (skill.sourceType !== "catalog")
+            const packageDir = skill.packageDir ? normalizePortablePath(skill.packageDir) : null;
+            if (!packageDir)
                 continue;
-            const materializedDir = await materializeCatalogSkillFiles(orgId, skill, normalizedFiles);
-            if (materializedDir) {
-                skill.sourceLocator = materializedDir;
+            const packageFiles = {};
+            for (const entry of skill.fileInventory) {
+                const sourcePath = entry.path === "SKILL.md"
+                    ? `${packageDir}/SKILL.md`
+                    : `${packageDir}/${entry.path}`;
+                const content = normalizedFiles[sourcePath];
+                if (typeof content !== "string") {
+                    throw unprocessable(`Skill package did not provide declared file: ${sourcePath}`);
+                }
+                packageFiles[entry.path] = content;
             }
+            skill.files = packageFiles;
+            skill.packageDir = null;
         }
         const conflictStrategy = options?.onConflict ?? "replace";
         const existingSkills = await listFull(orgId);
@@ -1042,7 +1545,7 @@ export function organizationSkillService(db, options = {}) {
         }
         if (toPersist.length === 0)
             return out;
-        const persisted = await upsertImportedSkills(orgId, toPersist);
+        const persisted = await installAndUpsertImportedSkills(orgId, toPersist);
         for (let index = 0; index < prepared.length; index += 1) {
             const persistedSkill = persisted[index];
             const preparedSkill = prepared[index];
@@ -1064,19 +1567,16 @@ export function organizationSkillService(db, options = {}) {
         for (const skill of imported) {
             const existing = await getByKey(orgId, skill.key);
             const existingMeta = existing ? getSkillMeta(existing) : {};
-            const incomingMeta = skill.metadata && isPlainRecord(skill.metadata) ? skill.metadata : {};
-            const incomingOwner = asString(incomingMeta.owner);
-            const incomingRepo = asString(incomingMeta.repo);
-            const incomingKind = asString(incomingMeta.sourceKind);
             if (existing
-                && isBundledRudderSourceKind(asString(existingMeta.sourceKind))
-                && incomingKind === "github"
-                && incomingOwner === "rudder"
-                && incomingRepo === "rudder") {
+                && isBundledRudderSourceKind(asString(existingMeta.sourceKind))) {
                 out.push(existing);
                 continue;
             }
             const metadata = {
+                ...(skill.sourceType !== "local_path"
+                    && existingMeta.installationVersion === ORGANIZATION_SKILL_INSTALLATION_VERSION
+                    ? { installationVersion: ORGANIZATION_SKILL_INSTALLATION_VERSION }
+                    : {}),
                 ...(skill.metadata ?? {}),
                 skillKey: skill.key,
             };
@@ -1147,24 +1647,27 @@ export function organizationSkillService(db, options = {}) {
                 skill.key = deriveCanonicalSkillKey(orgId, skill);
             }
         }
-        const imported = await upsertImportedSkills(orgId, filteredSkills);
+        const imported = await installAndUpsertImportedSkills(orgId, filteredSkills);
         return { imported, warnings };
     }
     async function deleteSkill(orgId, skillId) {
-        const row = await db
-            .select()
-            .from(organizationSkills)
-            .where(and(eq(organizationSkills.id, skillId), eq(organizationSkills.orgId, orgId)))
-            .then((rows) => rows[0] ?? null);
-        if (!row)
+        const initial = await getById(skillId);
+        if (!initial || initial.orgId !== orgId)
             return null;
-        const skill = toCompanySkill(row);
-        await enabledSkills.removeSkillKeys(orgId, [skill.key]);
-        await db
-            .delete(organizationSkills)
-            .where(eq(organizationSkills.id, skillId));
-        await fs.rm(resolveRuntimeSkillMaterializedPath(orgId, skill), { recursive: true, force: true });
-        return skill;
+        return withSkillMutationLock(orgId, initial.key, async () => {
+            const skill = await getById(skillId);
+            if (!skill || skill.orgId !== orgId)
+                return null;
+            if (isBundledRudderSourceKind(asString(getSkillMeta(skill).sourceKind))) {
+                throw unprocessable("Bundled Rudder skills are read-only.");
+            }
+            await enabledSkills.removeSkillKeys(orgId, [skill.key]);
+            await db
+                .delete(organizationSkills)
+                .where(eq(organizationSkills.id, skillId));
+            await removeInstalledSkillDirectory(orgId, skill);
+            return skill;
+        });
     }
     return {
         list,