Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

6.4 KB
Raw Blame
import { createHash } from 'node:crypto';
import { createReadStream, createWriteStream, existsSync, statSync } from 'node:fs';
import { readdir, readFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { basename, join, relative, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
import yazl from 'yazl';
import { BUNDLE_SKILL_NAME, type BundleId } from './skill-bundles.ts';

export type { BundleId };

const MAX_ZIP_BYTES = 102_400;

export interface BuildSkillZipOptions {
  bundle?: BundleId;
  sourceDir?: string;
  outputPath?: string;
  checkDesktop?: boolean;
}

export interface BuildSkillZipResult {
  outputPath: string;
  size: number;
  sha256: string;
}

export interface ResolveBundledSkillDirOptions {
  home?: string;
  platform?: NodeJS.Platform;
  checkDesktop?: boolean;
}

const DESKTOP_SKILLS_REL = 'OpenKnowledge.app/Contents/Resources/cli/dist/assets/skills';

function runsFromSource(moduleUrl: string): boolean {
  return new URL(moduleUrl).pathname.endsWith('.ts');
}

function bundledSkillCandidates(
  which: string,
  moduleUrl: string,
  opts: ResolveBundledSkillDirOptions,
): string[] {
  const platform = opts.platform ?? process.platform;
  const checkDesktop = opts.checkDesktop ?? false;
  const home = opts.home ?? homedir();

  const candidates: string[] = [];
  const underTest = process.env.NODE_ENV === 'test';
  if (checkDesktop && platform === 'darwin') {
    if (!underTest) candidates.push(join('/Applications', DESKTOP_SKILLS_REL, which));
    if (!underTest || opts.home !== undefined) {
      candidates.push(join(home, 'Applications', DESKTOP_SKILLS_REL, which));
    }
  }
  if (runsFromSource(moduleUrl)) {
    candidates.push(fileURLToPath(new URL(`../assets/skills/${which}`, moduleUrl)));
    return candidates;
  }
  candidates.push(fileURLToPath(new URL(`../dist/assets/skills/${which}`, moduleUrl)));
  candidates.push(fileURLToPath(new URL(`../assets/skills/${which}`, moduleUrl)));
  candidates.push(fileURLToPath(new URL(`./assets/skills/${which}`, moduleUrl)));
  return candidates;
}

function missingBundleMessage(which: string, moduleUrl: string, candidates: string[]): string {
  const remedy = runsFromSource(moduleUrl)
    ? 'Running from source, only the source assets are read, so the bundle name is unknown or its directory under packages/server/assets/skills is missing.'
    : 'This usually means the package build did not copy packages/server/assets into dist/assets. Run `pnpm run build` in the package that ships the skills before publishing.';
  return `Bundled skill asset directory not found for bundle '${which}'. Tried: ${candidates.join(', ')}. ${remedy}`;
}

export function resolveBundledSkillDir(
  which: BundleId | (string & {}),
  opts: ResolveBundledSkillDirOptions = {},
): string {
  const candidates = bundledSkillCandidates(which, import.meta.url, opts);
  for (const candidate of candidates) {
    if (existsSync(candidate)) return candidate;
  }
  throw new Error(missingBundleMessage(which, import.meta.url, candidates));
}

async function* walkFiles(dir: string, base: string = dir): AsyncGenerator<string> {
  const entries = await readdir(dir, { withFileTypes: true });
  for (const entry of entries) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) {
      yield* walkFiles(full, base);
    } else if (entry.isFile()) {
      yield relative(base, full);
    }
  }
}

function computeWrapperFolderName(
  sourceDir: string,
  pathBasename: (p: string) => string = basename,
): string {
  return pathBasename(sourceDir) || 'open-knowledge';
}

function toPosixZipPath(rel: string, pathSep: string = sep): string {
  return pathSep === '/' ? rel : rel.split(pathSep).join('/');
}

async function zipDirectory(
  sourceDir: string,
  outputPath: string,
  wrapperFolderName: string = computeWrapperFolderName(sourceDir),
): Promise<void> {
  const zipfile = new yazl.ZipFile();

  zipfile.addEmptyDirectory(`${wrapperFolderName}/`);

  const files: string[] = [];
  for await (const rel of walkFiles(sourceDir)) files.push(rel);
  files.sort();

  for (const rel of files) {
    const absolute = join(sourceDir, rel);
    const entryName = `${wrapperFolderName}/${toPosixZipPath(rel)}`;
    zipfile.addFile(absolute, entryName);
  }
  zipfile.end();

  await new Promise<void>((resolve, reject) => {
    const out = createWriteStream(outputPath);
    zipfile.outputStream.pipe(out);
    out.on('close', () => resolve());
    out.on('error', reject);
    zipfile.outputStream.on('error', reject);
  });
}

async function sha256OfFile(path: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const hash = createHash('sha256');
    const stream = createReadStream(path);
    stream.on('data', (chunk) => hash.update(chunk));
    stream.on('end', () => resolve(hash.digest('hex')));
    stream.on('error', reject);
  });
}

export async function validateSkillZip(
  outputPath: string,
  opts: { bundle?: BundleId; sourceDir?: string } = {},
): Promise<{ size: number; sha256: string }> {
  const bundle: BundleId = opts.bundle ?? 'project';
  const size = statSync(outputPath).size;
  if (size > MAX_ZIP_BYTES) {
    throw new Error(`Built ${outputPath} is ${size} bytes, exceeds ${MAX_ZIP_BYTES}-byte ceiling`);
  }

  const sha256 = await sha256OfFile(outputPath);

  const sourceDir = opts.sourceDir ?? resolveBundledSkillDir(bundle, { checkDesktop: false });
  const skillMd = await readFile(join(sourceDir, 'SKILL.md'), 'utf-8');

  const expectedName = BUNDLE_SKILL_NAME[bundle];
  if (!new RegExp(`^name:\\s+${expectedName}$`, 'm').test(skillMd.slice(0, 1500))) {
    throw new Error(
      `SKILL.md frontmatter \`name:\` does not match '${expectedName}'. ` +
        `Check packages/server/assets/skills/${bundle}/SKILL.md frontmatter.`,
    );
  }

  return { size, sha256 };
}

export async function buildSkillZip(opts: BuildSkillZipOptions = {}): Promise<BuildSkillZipResult> {
  const bundle: BundleId = opts.bundle ?? 'project';
  const sourceDir =
    opts.sourceDir ?? resolveBundledSkillDir(bundle, { checkDesktop: opts.checkDesktop ?? false });
  const outputPath = opts.outputPath ?? join(process.cwd(), 'openknowledge.skill');

  await zipDirectory(sourceDir, outputPath, BUNDLE_SKILL_NAME[bundle]);
  const { size, sha256 } = await validateSkillZip(outputPath, { bundle, sourceDir });

  return { outputPath, size, sha256 };
}

export const __testing = {
  computeWrapperFolderName,
  toPosixZipPath,
  bundledSkillCandidates,
  missingBundleMessage,
};