Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

13.5 KB
Raw Blame
import { existsSync } from 'node:fs';
import { relative, resolve, sep } from 'node:path';
import {
  pathspecArgs,
  RENAMED_PACK_SKILLS,
  type SkillReimportSuccessSchema,
} from '@inkeep/open-knowledge-core';
import {
  acquiredBundleTooLarge,
  packMarkerOf,
  parseSkillDir,
  type SkillLockEntry,
  type SkillsLock,
  upsertLockEntry,
} from '@inkeep/open-knowledge-core/skills-catalog';
import simpleGit from 'simple-git';
import type { z } from 'zod';
import {
  applySkillBundleFileDelete,
  applySkillBundleFileWrite,
  applySkillWrite,
  skillMutationErrorStatus,
  validateSkillMutationPath,
} from '../content/skills-write.ts';
import type { extractActorIdentity } from '../extract-actor-identity.ts';
import { mutateSkillsLock } from '../skills-lock-store.ts';
import { importedBundleLimitError, SKILL_IMPORT_WRITE_LIMITS } from './skill-import.ts';

type ActorIdentity = ReturnType<typeof extractActorIdentity>;

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

export interface SkillReimportDeps {
  contentDir: string;
  skillsHome: string;
  projectDir?: string;
  legacyStoreRoot: string;
  effectiveSkillRoot: (
    scope: 'project' | 'global',
    name: string,
  ) => { root: string; dirRel: string; realDir: 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;
  skillArtifactKey: (name: string) => string;
  captureAndCloseDocuments: (docNames: string[], status: 'deleted-upstream') => Promise<unknown>;
  projectImportedSkillCopy: (args: {
    skillsRoot: string;
    name: string;
    scope: 'project' | 'global';
    hasScripts: boolean;
    handler: string;
  }) => Promise<void>;
  signalFiles: () => void;
}

export type RecordedFolderUpdate =
  | { readonly kind: 'set'; readonly subpath: string }
  | { readonly kind: 'clear' };

function withRecordedFolder(
  entry: SkillLockEntry,
  folder: RecordedFolderUpdate | undefined,
): SkillLockEntry {
  if (folder === undefined) return entry;
  const { subpath: _replaced, ...rest } = entry;
  return folder.kind === 'set' ? { ...rest, subpath: folder.subpath } : rest;
}

export interface SkillReimportService {
  runSkillReimport(params: {
    acquiredDir: string;
    name: string;
    scope: 'project' | 'global';
    entry: SkillLockEntry;
    lockPath: string;
    ref?: string;
    folder?: RecordedFolderUpdate;
    actor: ActorIdentity;
    dryRun?: boolean;
  }): Promise<SkillReimportOutcome>;
}

interface ReimportPickOptions {
  recordedSkill?: string;
  localName: string;
  frontmatterNameOf: (dir: string) => string | undefined;
}

export function pickReimportDir<T extends { name: string; dir: string }>(
  dirs: readonly T[],
  opts: ReimportPickOptions,
): T | undefined {
  return reimportCandidates(dirs, opts)[0];
}

export function reimportCandidates<T extends { name: string; dir: string }>(
  dirs: readonly T[],
  opts: ReimportPickOptions,
): T[] {
  const { recordedSkill, localName, frontmatterNameOf } = opts;
  const renamed = RENAMED_PACK_SKILLS[recordedSkill ?? localName];
  const rules: Array<(d: T) => boolean> = [
    (d) => recordedSkill !== undefined && recordedSkill !== '' && d.name === recordedSkill,
    (d) => d.name === localName,
    (d) => frontmatterNameOf(d.dir) === localName,
    (d) => renamed !== undefined && d.name === renamed,
  ];
  for (const rule of rules) {
    const matches = dirs.filter(rule);
    if (matches.length > 0) return matches;
  }
  return dirs.length === 1 ? [...dirs] : [];
}

export function planReimportDiff(input: {
  upstreamHash: string;
  upstreamFiles: readonly string[];
  entry: Pick<SkillLockEntry, 'contentHash' | 'files' | 'localHash'>;
  local: { contentHash: string; files: readonly string[] } | null;
}): { upToDate: boolean; removedUpstream: string[] } {
  const upstreamPaths = new Set(input.upstreamFiles);
  const localPaths = new Set(input.local?.files ?? []);
  const priorUpstreamPaths =
    input.entry.files ??
    (input.entry.localHash !== undefined && input.local?.contentHash === input.entry.localHash
      ? [...localPaths]
      : []);
  const removedUpstream = priorUpstreamPaths
    .filter((path) => !upstreamPaths.has(path))
    .filter((path) => localPaths.has(path));
  return {
    upToDate: input.upstreamHash === input.entry.contentHash && removedUpstream.length === 0,
    removedUpstream,
  };
}

export function groupReimportNamesBySource(
  names: readonly string[],
  entryFor: (name: string) => SkillLockEntry | null,
): { bySource: { source: string; names: string[] }[]; unrecorded: string[] } {
  const bySource = new Map<string, string[]>();
  const unrecorded: string[] = [];
  for (const name of new Set(names)) {
    const entry = entryFor(name);
    if (!entry) {
      unrecorded.push(name);
      continue;
    }
    const bucket = bySource.get(entry.source);
    if (bucket) bucket.push(name);
    else bySource.set(entry.source, [name]);
  }
  return {
    bySource: [...bySource].map(([source, sourceNames]) => ({ source, names: sourceNames })),
    unrecorded,
  };
}

export function createSkillReimportService(deps: SkillReimportDeps): SkillReimportService {
  return {
    async runSkillReimport(params) {
      const { acquiredDir, name, scope, entry, lockPath, ref, folder, actor } = params;
      const reimportBase = scope === 'global' ? deps.skillsHome : deps.contentDir;
      const {
        root: skillsRoot,
        dirRel: skillDirRel,
        realDir,
      } = deps.effectiveSkillRoot(scope, name);
      const inPlaceSkill = !skillDirRel.startsWith(`${deps.legacyStoreRoot}/`);
      if (realDir === null || !existsSync(resolve(reimportBase, skillDirRel, 'SKILL.md'))) {
        return {
          ok: false,
          status: 404,
          urn: 'urn:ok:error:not-found',
          title: 'Skill is not installed.',
          detail: 'SKILL_ABSENT',
        };
      }

      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 localBefore = parseSkillDir(resolve(skillsRoot, name));
      const { upToDate, removedUpstream } = planReimportDiff({
        upstreamHash: acquired.contentHash,
        upstreamFiles: acquired.files.map((f) => f.relPath),
        entry,
        local: localBefore
          ? { contentHash: localBefore.contentHash, files: localBefore.files.map((f) => f.relPath) }
          : null,
      });
      if (upToDate) {
        return {
          ok: true,
          body: { name, updated: false, source: entry.source, warnings: [], warningCodes: [] },
        };
      }

      const acquiredDoc = deps.parseFrontmatterDoc(acquired.skillMd);
      const skillBody = acquiredDoc.body;
      const acquiredPack = packMarkerOf(acquiredDoc.frontmatter);

      const skillDir = resolve(skillsRoot, name);
      for (const relPath of [
        'SKILL.md',
        ...acquired.files.map((f) => f.relPath),
        ...removedUpstream,
      ]) {
        const pathCheck = validateSkillMutationPath(
          reimportBase,
          skillDir,
          resolve(skillDir, relPath),
        );
        if (!pathCheck.ok) {
          const status = skillMutationErrorStatus(pathCheck.error.code);
          return {
            ok: false,
            status,
            urn:
              status === 500
                ? 'urn:ok:error:internal-server-error'
                : 'urn:ok:error:invalid-request',
            title: pathCheck.error.message,
            detail: `${relPath}: ${pathCheck.error.code}`,
            cause: pathCheck.error.cause ?? new Error(pathCheck.error.message),
          };
        }
      }

      if (params.dryRun) {
        let gitTracked: boolean | undefined;
        if (scope === 'project' && deps.projectDir) {
          try {
            const pg = simpleGit({ baseDir: deps.projectDir, timeout: { block: 15_000 } });
            const rel = relative(deps.projectDir, resolve(skillsRoot, name)).split(sep).join('/');
            gitTracked = (await pg.raw('ls-files', ...pathspecArgs([rel]))).trim().length > 0;
          } catch {
            gitTracked = undefined;
          }
        }
        return {
          ok: true,
          body: {
            name,
            updated: true,
            source: entry.source,
            localBody: deps.parseFrontmatterDoc(localBefore?.skillMd ?? '').body,
            upstreamBody: skillBody,
            ...(gitTracked !== undefined ? { gitTracked } : {}),
            warnings: [],
            warningCodes: [],
          },
        };
      }

      if (scope === 'project') {
        const removedMarkdownDocs = removedUpstream
          .filter((path) => /\.mdx?$/i.test(path))
          .map((path) => `${skillDirRel}/${path.replace(/\.mdx?$/i, '')}`);
        if (removedMarkdownDocs.length > 0) {
          await deps.captureAndCloseDocuments(removedMarkdownDocs, 'deleted-upstream');
        }
      }
      const wr = applySkillWrite({
        boundary: reimportBase,
        skillsRoot,
        name,
        body: skillBody,
        frontmatter: {
          name,
          description: acquired.description,
          ...(acquiredPack !== undefined ? { metadata: { pack: acquiredPack } } : {}),
        },
      });
      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: reimportBase,
          skillsRoot,
          name,
          relPath: f.relPath,
          content: f.content,
          bytes: f.bytes,
          limits: SKILL_IMPORT_WRITE_LIMITS,
        });
        if (!br.ok) {
          return {
            ok: false,
            status: 500,
            urn: 'urn:ok:error:internal-server-error',
            title: 'Failed to write the complete refreshed skill bundle.',
            detail: `${f.relPath}: ${br.error.code}`,
            cause: new Error(br.error.message),
          };
        }
      }
      for (const relPath of removedUpstream) {
        const deleted = applySkillBundleFileDelete({
          boundary: reimportBase,
          skillsRoot,
          name,
          relPath,
        });
        if (!deleted.ok) {
          return {
            ok: false,
            status: 500,
            urn: 'urn:ok:error:internal-server-error',
            title: 'Failed to reconcile files removed upstream.',
            detail: `${relPath}: ${deleted.error.code}`,
            cause: new Error(deleted.error.message),
          };
        }
      }

      if (scope === 'project') {
        deps.attributeOkArtifactWrite(
          actor,
          deps.skillArtifactKey(name),
          `skill-reimport: ${entry.source} -> ${skillDirRel}`,
        );
        await deps.commitOkArtifactWrite('skill-reimport');
      }

      const reimportLocalHash = parseSkillDir(resolve(skillsRoot, name))?.contentHash;
      const reimportBaselineRef =
        scope === 'project'
          ? await deps.shadowHeadSha(deps.artifactWriterId(actor), skillDirRel)
          : undefined;
      await mutateSkillsLock(lockPath, (current: SkillsLock) =>
        upsertLockEntry(current, name, {
          ...withRecordedFolder(current.skills[name] ?? entry, folder),
          contentHash: acquired.contentHash,
          files: acquired.files.map((file) => file.relPath),
          ...(reimportLocalHash !== undefined ? { localHash: reimportLocalHash } : {}),
          ...(reimportBaselineRef !== undefined ? { baselineRef: reimportBaselineRef } : {}),
          ref,
          importedAt: new Date().toISOString(),
        }),
      );

      if (!inPlaceSkill && scope === 'project') {
        await deps.projectImportedSkillCopy({
          skillsRoot,
          name,
          scope: 'project',
          hasScripts: acquired.files.some((f) => f.relPath.startsWith('scripts/')),
          handler: 'skill-reimport',
        });
      }

      deps.signalFiles();
      return {
        ok: true,
        body: {
          name,
          updated: true,
          source: entry.source,
          warnings,
          warningCodes: wr.warningCodes,
        },
      };
    },
  };
}