Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

12.1 KB
Raw Blame
import { existsSync, lstatSync } from 'node:fs';
import { join, resolve } from 'node:path';
import {
  SKILL_IMPORT_MAX_BUNDLE_FILES,
  SKILL_IMPORT_MAX_FILE_BYTES,
  SKILL_IMPORT_MAX_TOTAL_BYTES,
  type SkillImportSuccessSchema,
} from '@inkeep/open-knowledge-core';
import {
  acquiredBundleTooLarge,
  findByContentHash,
  inspectPluginSource,
  packMarkerOf,
  parseSkillDir,
  SKILLS_LOCK_REL,
  upsertLockEntry,
} from '@inkeep/open-knowledge-core/skills-catalog';
import type { z } from 'zod';
import {
  applySkillBundleFileWrite,
  applySkillDelete,
  applySkillWrite,
  skillMutationErrorStatus,
} from '../content/skills-write.ts';
import type { extractActorIdentity } from '../extract-actor-identity.ts';
import { sanitizeFilename } from '../filename-sanitize.ts';
import { resolveDefaultSkillHomeRel, skillHomeCandidateFolders } from '../in-place-skills.ts';
import { getLogger } from '../logger.ts';
import {
  projectInPlaceSkill,
  resolveSkillTargets,
  skillHostDir,
  skillProjectionRoots,
} from '../skill-projection.ts';
import { mutateSkillsLock, readSkillsLockFile } from '../skills-lock-store.ts';

const log = getLogger('skill-import');

type ActorIdentity = ReturnType<typeof extractActorIdentity>;

export const SKILL_IMPORT_WRITE_LIMITS = {
  maxFileBytes: SKILL_IMPORT_MAX_FILE_BYTES,
  maxFiles: SKILL_IMPORT_MAX_BUNDLE_FILES,
} as const;

export function importedBundleLimitError(
  acquired: NonNullable<ReturnType<typeof parseSkillDir>>,
): string | null {
  if (acquired.files.length > SKILL_IMPORT_MAX_BUNDLE_FILES) {
    return `Skill has ${acquired.files.length} dependent files; the import cap is ${SKILL_IMPORT_MAX_BUNDLE_FILES}.`;
  }
  let totalBytes = Buffer.byteLength(acquired.skillMd);
  for (const file of acquired.files) {
    const bytes = file.bytes?.byteLength ?? Buffer.byteLength(file.content ?? '');
    if (bytes > SKILL_IMPORT_MAX_FILE_BYTES) {
      return `${file.relPath} is ${bytes} bytes; the import per-file cap is ${SKILL_IMPORT_MAX_FILE_BYTES}.`;
    }
    totalBytes += bytes;
  }
  return totalBytes > SKILL_IMPORT_MAX_TOTAL_BYTES
    ? `Skill is ${totalBytes} bytes; the import bundle cap is ${SKILL_IMPORT_MAX_TOTAL_BYTES}.`
    : null;
}

export type SkillImportOutcome =
  | { ok: true; body: z.infer<typeof SkillImportSuccessSchema> }
  | {
      ok: false;
      status: 400 | 422 | 500;
      urn: 'urn:ok:error:invalid-request' | 'urn:ok:error:internal-server-error';
      title: string;
      detail?: string;
      cause?: unknown;
    };

export interface SkillImportDeps {
  contentDir: string;
  skillsHome: string;
  projectDir?: string;
  resolveSkillDirForRead: (scope: 'project' | 'global', name: string) => string | null;
  parseFrontmatterDoc: (raw: string) => { frontmatter: Record<string, unknown>; body: string };
  attributeOkArtifactWrite: (actor: ActorIdentity, keyPath: string, summary: string) => void;
  commitOkArtifactWrite: (context: string) => Promise<unknown>;
  shadowHeadSha: (writerId?: string, verifyPathRel?: string) => Promise<string | undefined>;
  artifactWriterId: (actor: ActorIdentity) => string | undefined;
  effectiveInstallMode: (
    scope: 'project' | 'global',
    name: string,
    entry: { hosts: readonly string[]; linkedHosts: readonly string[] },
  ) => 'copy' | 'link';
  signalFiles: () => void;
}

export interface SkillImportService {
  runSkillImport(params: {
    acquiredDir: string;
    scope: 'project' | 'global';
    sourceLabel: string;
    ref?: string;
    publisher?: string;
    upstreamSkill?: string;
    subpath?: string;
    actor: ActorIdentity;
    skipProjection?: boolean;
  }): Promise<SkillImportOutcome>;
}

export function createSkillImportService(deps: SkillImportDeps): SkillImportService {
  function localSkillHash(skillsRoot: string, name: string): string | undefined {
    return parseSkillDir(resolve(skillsRoot, name))?.contentHash;
  }

  return {
    async runSkillImport(params) {
      const { acquiredDir, scope, sourceLabel, ref, publisher, upstreamSkill, subpath, actor } =
        params;
      if (!deps.projectDir) {
        return {
          ok: false,
          status: 400,
          urn: 'urn:ok:error:invalid-request',
          title: 'No project root resolved.',
          detail: 'NO_PROJECT_ROOT',
        };
      }
      const oversize = acquiredBundleTooLarge(acquiredDir);
      if (oversize) {
        return {
          ok: false,
          status: 400,
          urn: 'urn:ok:error:invalid-request',
          title: 'Skill bundle exceeds import limits.',
          detail: oversize,
        };
      }
      const acquired = parseSkillDir(acquiredDir);
      if (!acquired) {
        return {
          ok: false,
          status: 422,
          urn: 'urn:ok:error:invalid-request',
          title: 'Source has no readable skill.',
        };
      }
      const limitError = importedBundleLimitError(acquired);
      if (limitError) {
        return {
          ok: false,
          status: 400,
          urn: 'urn:ok:error:invalid-request',
          title: 'Skill bundle exceeds import limits.',
          detail: limitError,
        };
      }

      const lockPath = join(
        scope === 'project' ? deps.projectDir : deps.skillsHome,
        ...SKILLS_LOCK_REL,
      );
      const lock = readSkillsLockFile(lockPath);
      const importBase = scope === 'project' ? deps.contentDir : deps.skillsHome;
      const importHomeRel = resolveDefaultSkillHomeRel(importBase, scope);
      if (importHomeRel === null) {
        return {
          ok: false,
          status: 400,
          urn: 'urn:ok:error:invalid-request',
          title: `Open Knowledge only writes skills into an agent folder that already exists (${skillHomeCandidateFolders(scope).join(', ')}) and never creates one for you. Create the folder your agent uses, then import again.`,
          detail: 'NO_USABLE_SKILL_HOME',
        };
      }
      const importRoot = resolve(importBase, importHomeRel);
      const dupName = findByContentHash(lock, acquired.contentHash);
      if (dupName && deps.resolveSkillDirForRead(scope, dupName) !== null) {
        return {
          ok: true,
          body: {
            name: dupName,
            path: `${dupName}/SKILL.md`,
            created: false,
            alreadyImported: true,
            provenance: { source: sourceLabel, ref, contentHash: acquired.contentHash, publisher },
            warnings: [],
            warningCodes: [],
          },
        };
      }

      const probeName = sanitizeFilename(acquired.name);
      const nameTaken = (n: string) =>
        deps.resolveSkillDirForRead(scope, n) !== null ||
        existsSync(resolve(importRoot, n, 'SKILL.md'));
      const collided = nameTaken(probeName);
      let targetName = probeName;
      if (collided) {
        targetName = `${probeName}-imported`;
        let n = 2;
        while (nameTaken(targetName)) {
          targetName = `${probeName}-imported-${n}`;
          n += 1;
        }
      }

      const acquiredDoc = deps.parseFrontmatterDoc(acquired.skillMd);
      const skillBody = acquiredDoc.body;
      const pack = packMarkerOf(acquiredDoc.frontmatter);
      const wr = applySkillWrite({
        boundary: importBase,
        skillsRoot: importRoot,
        name: targetName,
        body: skillBody,
        frontmatter: {
          name: targetName,
          description: acquired.description,
          ...(pack !== undefined ? { metadata: { pack } } : {}),
        },
      });
      if (!wr.ok) {
        const status = skillMutationErrorStatus(wr.error.code);
        return {
          ok: false,
          status,
          urn:
            status === 500 ? 'urn:ok:error:internal-server-error' : 'urn:ok:error:invalid-request',
          title: wr.error.message,
          detail: wr.error.code,
          cause: wr.error.cause ?? new Error(wr.error.message),
        };
      }
      const warnings = [...wr.warnings];
      for (const f of acquired.files) {
        const br = applySkillBundleFileWrite({
          boundary: importBase,
          skillsRoot: importRoot,
          name: targetName,
          relPath: f.relPath,
          content: f.content,
          bytes: f.bytes,
          limits: SKILL_IMPORT_WRITE_LIMITS,
        });
        if (!br.ok) {
          const rollback = applySkillDelete({ skillsRoot: importRoot, name: targetName });
          const status = rollback.ok ? skillMutationErrorStatus(br.error.code) : 500;
          return {
            ok: false,
            status,
            urn:
              status === 400
                ? 'urn:ok:error:invalid-request'
                : 'urn:ok:error:internal-server-error',
            title: 'Failed to write the complete imported skill bundle.',
            detail: `${f.relPath}: ${br.error.code}`,
            cause: new Error(
              rollback.ok
                ? br.error.message
                : `${br.error.message}; rollback: ${rollback.error.message}`,
            ),
          };
        }
      }

      if (scope === 'project') {
        deps.attributeOkArtifactWrite(
          actor,
          `${importHomeRel}/${targetName}/SKILL`,
          `skill-import: ${sourceLabel} -> ${importHomeRel}/${targetName}/SKILL.md`,
        );
        await deps.commitOkArtifactWrite('skill-import');
      }

      const importedLocalHash = localSkillHash(importRoot, targetName);
      const importedPlugin = inspectPluginSource(sourceLabel);
      const importedBaselineRef =
        scope === 'project'
          ? await deps.shadowHeadSha(deps.artifactWriterId(actor), `${importHomeRel}/${targetName}`)
          : undefined;
      await mutateSkillsLock(lockPath, (current) =>
        upsertLockEntry(current, targetName, {
          source: sourceLabel,
          ...(importedPlugin ? { pluginProvider: importedPlugin.provider } : {}),
          ref,
          contentHash: acquired.contentHash,
          files: acquired.files.map((file) => file.relPath),
          ...(importedLocalHash !== undefined ? { localHash: importedLocalHash } : {}),
          ...(importedBaselineRef !== undefined ? { baselineRef: importedBaselineRef } : {}),
          publisher,
          importedAt: new Date().toISOString(),
          ...(upstreamSkill !== undefined ? { skill: upstreamSkill } : {}),
          ...(subpath !== undefined ? { subpath } : {}),
        }),
      );

      if (params.skipProjection !== true) {
        try {
          const targets = resolveSkillTargets(importBase);
          if (targets.length > 0) {
            const canonicalAbs = resolve(importRoot, targetName);
            const projectionRoots = skillProjectionRoots(scope);
            const occupied = targets.filter((editor) => {
              const dest = skillHostDir(importBase, editor, targetName, projectionRoots);
              return dest !== null && dest !== canonicalAbs && existsSync(dest);
            });
            const occupiedLinks = occupied.filter((editor) => {
              const dest = skillHostDir(importBase, editor, targetName, projectionRoots);
              try {
                return dest !== null && lstatSync(dest).isSymbolicLink();
              } catch {
                return false;
              }
            });
            projectInPlaceSkill({
              canonicalAbs,
              canonicalHash: parseSkillDir(canonicalAbs)?.contentHash ?? '',
              canonicalRootRel: importHomeRel,
              name: targetName,
              cwd: importBase,
              targets,
              mode: deps.effectiveInstallMode(scope, targetName, {
                hosts: ['<source>', ...occupied],
                linkedHosts: occupiedLinks,
              }),
              roots: skillProjectionRoots(scope),
            });
          }
        } catch (err) {
          log.warn({ err, skill: targetName }, 'post-import editor fan-out failed (import kept)');
        }
      }

      deps.signalFiles();
      return {
        ok: true,
        body: {
          name: targetName,
          path: `${importHomeRel}/${targetName}/SKILL.md`,
          created: wr.created,
          alreadyImported: false,
          ...(collided ? { collisionRenamedFrom: acquired.name } : {}),
          provenance: { source: sourceLabel, ref, contentHash: acquired.contentHash, publisher },
          warnings,
          warningCodes: wr.warningCodes,
        },
      };
    },
  };
}