Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

8.5 KB
Raw Blame
export const SYSTEM_DOC_NAME = '__system__';
export const CC1_CONTRACT_VERSION = 1;

export const CONFIG_DOC_NAME_PROJECT = '__config__/project';

export const CONFIG_DOC_NAME_USER = '__user__/config.yml';

export const CONFIG_DOC_NAME_PROJECT_LOCAL = '__local__/project';

export const CONFIG_DOC_NAME_OKIGNORE = '__config__/okignore';

export const CONFIG_DOC_NAMES = Object.freeze([
  CONFIG_DOC_NAME_PROJECT,
  CONFIG_DOC_NAME_PROJECT_LOCAL,
  CONFIG_DOC_NAME_USER,
  CONFIG_DOC_NAME_OKIGNORE,
] as const);
export type ConfigDocName = (typeof CONFIG_DOC_NAMES)[number];

export const MANAGED_ARTIFACT_PREFIX_SKILL = '__skill__/';
export const MANAGED_ARTIFACT_PREFIX_TEMPLATE = '__template__/';

export const MANAGED_ARTIFACT_PREFIX_EXTSKILL = '__extskill__/';

export const MANAGED_ARTIFACT_SCOPES = ['project', 'global'] as const;
export type ManagedArtifactScope = (typeof MANAGED_ARTIFACT_SCOPES)[number];

export function isManagedArtifactDocName(name: string): boolean {
  return (
    name.startsWith(MANAGED_ARTIFACT_PREFIX_SKILL) ||
    name.startsWith(MANAGED_ARTIFACT_PREFIX_TEMPLATE) ||
    name.startsWith(MANAGED_ARTIFACT_PREFIX_EXTSKILL)
  );
}

export function externalSkillLiveDocName(name: string): string {
  return `${MANAGED_ARTIFACT_PREFIX_EXTSKILL}${name}`;
}

export function externalSkillFileLiveDocName(name: string, rel: string): string {
  const relNoExt = stripMdExt(rel);
  return `${MANAGED_ARTIFACT_PREFIX_EXTSKILL}${name}/${relNoExt}`;
}

export function isExternalSkillDocName(name: string): boolean {
  return name.startsWith(MANAGED_ARTIFACT_PREFIX_EXTSKILL);
}

export function parseExternalSkillDocName(
  name: string,
): { name: string; rel: string | null } | null {
  if (!name.startsWith(MANAGED_ARTIFACT_PREFIX_EXTSKILL)) return null;
  const rest = name.slice(MANAGED_ARTIFACT_PREFIX_EXTSKILL.length);
  const slash = rest.indexOf('/');
  const skillName = slash < 0 ? rest : rest.slice(0, slash);
  const rel = slash < 0 ? null : rest.slice(slash + 1);
  if (!/^[a-z0-9-]+$/.test(skillName)) return null;
  return { name: skillName, rel: rel && rel.length > 0 ? rel : null };
}

export function stripMdExt(path: string): string {
  return path.replace(/\.mdx?$/i, '');
}

export const LEGACY_SKILL_STORE_ROOT = '.ok/skills';

export function projectSkillContentDocName(name: string): string {
  return `${LEGACY_SKILL_STORE_ROOT}/${name}/SKILL`;
}

const SKILL_BUNDLE_SUBDIRS = ['references', 'scripts'] as const;

export function resolveSkillSlashTarget(target: string, sourceDocName: string): string | null {
  const trimmed = target.trim();
  if (!trimmed.startsWith('/')) return null;
  const name = trimmed.slice(1);
  if (name === '' || name.includes('/')) return null;

  const projectRoot = /^(\.[A-Za-z0-9_-]+\/skills)\/[^/]+\/(?:SKILL|references\/.+)$/.exec(
    sourceDocName,
  );
  if (projectRoot) return `${projectRoot[1] as string}/${name}/SKILL`;

  const globalSkill = /^__skill__\/(global)\/[^/]+(?:\/references\/.+)?$/.exec(sourceDocName);
  if (globalSkill) return skillLiveDocName('global', name);

  return null;
}

export function resolveSkillBundleWikiTarget(target: string, sourceDocName: string): string | null {
  const skillDirMatch =
    /^(\.[A-Za-z0-9_-]+\/skills\/[^/]+)\/(?:SKILL|references\/.+)$/.exec(sourceDocName) ??
    /^(__skill__\/global\/[^/]+)(?:\/references\/.+)?$/.exec(sourceDocName) ??
    /^(__extskill__\/[^/]+)(?:\/.+)?$/.exec(sourceDocName);
  if (!skillDirMatch) return null;
  const skillDir = skillDirMatch[1] as string;

  const trimmed = target.trim();
  const withoutExt = stripMdExt(trimmed);
  const segments = withoutExt.split('/').filter((s) => s !== '' && s !== '.');
  const [first] = segments;
  if (!first || !(SKILL_BUNDLE_SUBDIRS as readonly string[]).includes(first)) return null;
  if (segments.includes('..')) return null;
  if (segments.length < 2) return null;
  return `${skillDir}/${segments.join('/')}`;
}

export type ParsedProjectSkillBundleDoc =
  | { name: string; kind: 'skill'; rel: null }
  | { name: string; kind: 'reference'; rel: string };

const PROJECT_SKILL_BUNDLE_DOC_RE = /^\.[A-Za-z0-9_-]+\/skills\/([^/]+)\/(SKILL|references\/.+)$/;

export function parseProjectSkillBundleDoc(docName: string): ParsedProjectSkillBundleDoc | null {
  const match = PROJECT_SKILL_BUNDLE_DOC_RE.exec(docName);
  if (!match) return null;
  const name = match[1] as string;
  const tail = match[2] as string;
  if (tail === 'SKILL') return { name, kind: 'skill', rel: null };
  return { name, kind: 'reference', rel: tail.slice('references/'.length) };
}

export type ParsedGlobalSkillBundleDoc =
  | { name: string; kind: 'skill'; rel: null; host: string | null }
  | { name: string; kind: 'reference'; rel: string; host: string | null };

const GLOBAL_SKILL_BUNDLE_DOC_RE = /^__skill__\/global\/([^/]+)(?:\/(references\/.+))?$/;

export function parseGlobalSkillBundleDoc(docName: string): ParsedGlobalSkillBundleDoc | null {
  const match = GLOBAL_SKILL_BUNDLE_DOC_RE.exec(docName);
  if (!match) return null;
  const { name, host } = splitSkillHostQualifier(match[1] as string);
  const tail = match[2];
  if (tail === undefined) return { name, kind: 'skill', rel: null, host };
  return { name, kind: 'reference', rel: tail.slice('references/'.length), host };
}

export function skillLiveDocName(scope: ManagedArtifactScope, name: string, host?: string): string {
  return scope === 'project'
    ? projectSkillContentDocName(name)
    : `${MANAGED_ARTIFACT_PREFIX_SKILL}${scope}/${name}${host ? `@${host}` : ''}`;
}

export function splitSkillHostQualifier(segment: string): { name: string; host: string | null } {
  const at = segment.indexOf('@');
  if (at < 0) return { name: segment, host: null };
  const host = segment.slice(at + 1);
  return { name: segment.slice(0, at), host: host === '' ? null : host };
}

export function skillFileLiveDocName(
  scope: ManagedArtifactScope,
  name: string,
  rel: string,
  host?: string,
): string {
  const relNoExt = stripMdExt(rel);
  return scope === 'project'
    ? `${LEGACY_SKILL_STORE_ROOT}/${name}/${relNoExt}`
    : `${MANAGED_ARTIFACT_PREFIX_SKILL}${scope}/${name}${host ? `@${host}` : ''}/${relNoExt}`;
}

export type ParsedManagedArtifactName = {
  kind: 'skill';
  scope: ManagedArtifactScope;
  name: string;
  host: string | null;
  rel: string | null;
};

function decodeManagedSegments(encoded: string): string {
  if (encoded === '') return '';
  try {
    return encoded
      .split('/')
      .map((s) => decodeURIComponent(s))
      .join('/');
  } catch {
    return encoded;
  }
}

export function parseManagedArtifactName(name: string): ParsedManagedArtifactName | null {
  if (name.startsWith(MANAGED_ARTIFACT_PREFIX_SKILL)) {
    const rest = name.slice(MANAGED_ARTIFACT_PREFIX_SKILL.length);
    const slash = rest.indexOf('/');
    if (slash < 0) return null;
    const scope = rest.slice(0, slash);
    if (scope !== 'global' && scope !== 'project') return null;
    const encoded = rest.slice(slash + 1);
    if (!encoded) return null;
    const decoded = decodeManagedSegments(encoded);
    const nameEnd = decoded.indexOf('/');
    const segment = nameEnd < 0 ? decoded : decoded.slice(0, nameEnd);
    if (!segment) return null;
    const rel = nameEnd < 0 ? null : decoded.slice(nameEnd + 1);
    const { name: skillName, host } = splitSkillHostQualifier(segment);
    if (!skillName) return null;
    return { kind: 'skill', scope, name: skillName, host, rel };
  }
  return null;
}

const TEMPLATE_FILE_TARGET_RE = /^(?:(.+)\/)?\.ok\/templates\/([^/]+?)(?:\.md)?$/;

export type ParsedTemplateName = { folder: string; name: string };

export function templateContentDocName(folderRel: string, name: string): string {
  const folder = folderRel.replace(/^\/+|\/+$/g, '');
  return folder ? `${folder}/.ok/templates/${name}` : `.ok/templates/${name}`;
}

export function parseTemplateContentDocName(docName: string): ParsedTemplateName | null {
  const match = TEMPLATE_FILE_TARGET_RE.exec(docName);
  if (!match) return null;
  return { folder: (match[1] ?? '').replace(/^\/+|\/+$/g, ''), name: match[2] as string };
}

export function parseLegacyTemplateDocName(name: string): ParsedTemplateName | null {
  if (!name.startsWith(MANAGED_ARTIFACT_PREFIX_TEMPLATE)) return null;
  const rest = name.slice(MANAGED_ARTIFACT_PREFIX_TEMPLATE.length);
  if (!rest) return null;
  const lastSlash = rest.lastIndexOf('/');
  const encodedName = lastSlash < 0 ? rest : rest.slice(lastSlash + 1);
  if (!encodedName) return null;
  const encodedFolder = lastSlash < 0 ? '' : rest.slice(0, lastSlash);
  return {
    folder: decodeManagedSegments(encodedFolder),
    name: decodeManagedSegments(encodedName),
  };
}