Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

17.7 KB
Raw Blame
import {
  ALL_EDITOR_IDS,
  EDITOR_PROJECT_SKILL_ROOT,
  EDITOR_USER_SKILL_ROOT,
  type EditorId,
  HUB_READER_EDITORS,
  interpretSkillMoveFailure,
  isMarkdownSkillFilePath,
  normalizeApiWarnings,
  SKILL_AUTHORING_WARNING_CODES,
  type SkillMoveFailureOutcome,
  type SkillScope,
} from '@inkeep/open-knowledge-core';
import type { AgentIdentity } from '../agent-identity.ts';
import { resolveSkillPreviewUrl } from './preview-url.ts';
import {
  agentIdentityFields,
  alignWarningCodes,
  errorTextWithDetail,
  hocuspocusNotRunningError,
  httpDelete,
  httpGet,
  httpPost,
  httpPut,
  textPlusStructured,
  textResult,
} from './shared.ts';
import {
  resolveSkillName,
  SKILL_EDIT_CONTROL_ADVICE,
  SKILL_FILE_EDIT_CONTROL_ADVICE,
  SKILL_METADATA_CONTROL_ADVICE,
} from './verb-schemas.ts';
import {
  failedWriteResult,
  leadFor,
  needsAttention,
  refusedDespiteSuccess,
  refusedWriteResult,
  writeOutcomeFields,
  writeOutcomeLine,
  writeOutcomeOf,
} from './write-outcome.ts';

export type { SkillScope };

const KNOWN_AUTHORING_WARNING_CODES: ReadonlySet<string> = new Set(SKILL_AUTHORING_WARNING_CODES);

interface SkillIdentity {
  summary?: string;
  identity?: AgentIdentity;
}

function appendIdentityParams(params: URLSearchParams, identity: AgentIdentity | undefined): void {
  for (const [key, value] of Object.entries(agentIdentityFields(identity))) {
    if (typeof value === 'string' && value.length > 0) params.set(key, value);
  }
}

export async function writeSkill(
  url: string | undefined,
  input: {
    scope?: SkillScope;
    name: string;
    description: string;
    body?: string;
    resubmitted?: 'body-edit' | 'metadata-edit';
    lockDir?: string;
  } & SkillIdentity,
) {
  const resolved = resolveSkillName(input.name);
  if (!resolved.ok) return textResult(`Error: ${resolved.error}`, true);
  if (!url) return textResult(hocuspocusNotRunningError(), true);
  const result = await httpPut(url, '/api/skill', {
    ...(input.scope !== undefined ? { scope: input.scope } : {}),
    name: input.name,
    body: input.body ?? '',
    frontmatter: { name: input.name, description: input.description },
    ...(input.summary !== undefined ? { summary: input.summary } : {}),
    ...agentIdentityFields(input.identity),
  });
  const outcome = writeOutcomeOf(result);
  if (!result.ok)
    return failedWriteResult(
      errorTextWithDetail(
        result,
        input.resubmitted
          ? input.resubmitted === 'metadata-edit'
            ? SKILL_METADATA_CONTROL_ADVICE
            : SKILL_EDIT_CONTROL_ADVICE
          : 'Any body offset refers to the full submitted skill body.',
      ),
      outcome,
    );
  if (refusedDespiteSuccess(outcome)) {
    return refusedWriteResult(`The write of skill "${input.name}"`, outcome);
  }
  const created = result.created === true;
  const path = typeof result.path === 'string' ? result.path : undefined;
  const aligned = alignWarningCodes(
    result.warnings,
    result.warningCodes,
    KNOWN_AUTHORING_WARNING_CODES,
  );
  const outcomeLine = outcome?.outcome === 'applied' ? null : writeOutcomeLine(outcome);
  const lines = [
    leadFor(
      outcome,
      `${created ? 'Created' : 'Updated'} skill "${input.name}"`,
      `${created ? 'Created' : 'Updated'} skill "${input.name}"${path ? ` (${path})` : ''} — live for that folder's agent. Use \`install\` with \`add\` to put it in your other editors.`,
    ),
    ...aligned.warnings,
    ...(outcomeLine ? [outcomeLine] : []),
  ];
  const preview = input.lockDir
    ? resolveSkillPreviewUrl(input.scope ?? 'project', input.name, { lockDir: input.lockDir })
    : null;
  return textPlusStructured(
    lines.join('\n'),
    {
      skill: { ok: true, path, created, ...aligned },
      ...(preview ? { previewUrl: preview.url, previewUrlSource: preview.source } : {}),
      ...writeOutcomeFields(outcome),
    },
    needsAttention(outcome),
  );
}

export async function fetchSkill(
  url: string,
  scope: SkillScope,
  name: string,
): Promise<
  | { ok: true; description: string; body: string; files: Array<{ path: string }> }
  | { ok: false; error: string; notFound: boolean }
> {
  const params = new URLSearchParams({ name, scope });
  const result = await httpGet(url, `/api/skill?${params.toString()}`);
  if (!result.ok)
    return { ok: false, error: String(result.error), notFound: result.httpStatus === 404 };
  const skill = result.skill as
    | {
        frontmatter?: { description?: unknown };
        body?: unknown;
        files?: Array<{ path?: unknown }>;
      }
    | undefined;
  const files = Array.isArray(skill?.files)
    ? skill.files
        .map((f) => (typeof f?.path === 'string' ? { path: f.path } : null))
        .filter((f): f is { path: string } => f !== null)
    : [];
  return {
    ok: true,
    description:
      typeof skill?.frontmatter?.description === 'string' ? skill.frontmatter.description : '',
    body: typeof skill?.body === 'string' ? skill.body : '',
    files,
  };
}

export async function writeSkillFile(
  url: string | undefined,
  input: {
    scope?: SkillScope;
    name: string;
    path: string;
    content: string;
    resubmitted?: true;
  } & SkillIdentity,
) {
  const resolved = resolveSkillName(input.name);
  if (!resolved.ok) return textResult(`Error: ${resolved.error}`, true);
  if (!url) return textResult(hocuspocusNotRunningError(), true);
  const result = await httpPut(url, '/api/skill-file', {
    ...(input.scope !== undefined ? { scope: input.scope } : {}),
    name: input.name,
    path: input.path,
    content: input.content,
    ...(input.summary !== undefined ? { summary: input.summary } : {}),
    ...agentIdentityFields(input.identity),
  });
  const outcome = writeOutcomeOf(result);
  if (!result.ok)
    return failedWriteResult(
      errorTextWithDetail(
        result,
        isMarkdownSkillFilePath(input.path)
          ? input.resubmitted
            ? SKILL_FILE_EDIT_CONTROL_ADVICE
            : 'Any content offset refers to the whole submitted file content, including frontmatter.'
          : undefined,
      ),
      outcome,
    );
  if (refusedDespiteSuccess(outcome)) {
    return refusedWriteResult(`The write of "${input.path}" in skill "${input.name}"`, outcome);
  }
  const created = result.created === true;
  const path = typeof result.path === 'string' ? result.path : input.path;
  const kind = result.kind === 'script' ? 'script' : 'reference';
  const outcomeLine = outcome?.outcome === 'applied' ? null : writeOutcomeLine(outcome);
  return textPlusStructured(
    [
      leadFor(
        outcome,
        `${created ? 'Created' : 'Updated'} skill ${kind} "${input.path}" in "${input.name}"`,
        `${created ? 'Created' : 'Updated'} skill ${kind} "${input.path}" in "${input.name}".`,
      ),
      ...(outcomeLine ? [outcomeLine] : []),
    ].join('\n'),
    { skill: { ok: true, file: { path, kind, created } }, ...writeOutcomeFields(outcome) },
    needsAttention(outcome),
  );
}

export async function readSkillFile(
  url: string,
  scope: SkillScope,
  name: string,
  path: string,
): Promise<
  | { ok: true; path: string; kind: 'reference' | 'script'; text: string }
  | { ok: false; error: string; status: number | undefined }
> {
  const params = new URLSearchParams({ name, scope, path });
  const result = await httpGet(url, `/api/skill-file?${params.toString()}`);
  if (!result.ok)
    return {
      ok: false,
      error: String(result.error),
      status: result.httpStatus as number | undefined,
    };
  return {
    ok: true,
    path: typeof result.path === 'string' ? result.path : path,
    kind: result.kind === 'script' ? 'script' : 'reference',
    text: typeof result.text === 'string' ? result.text : '',
  };
}

export async function deleteSkillFile(
  url: string | undefined,
  input: { scope?: SkillScope; name: string; path: string } & SkillIdentity,
) {
  const resolved = resolveSkillName(input.name);
  if (!resolved.ok) return textResult(`Error: ${resolved.error}`, true);
  if (!url) return textResult(hocuspocusNotRunningError(), true);
  const params = new URLSearchParams({
    name: input.name,
    scope: input.scope ?? 'project',
    path: input.path,
  });
  if (input.summary !== undefined) params.set('summary', input.summary);
  appendIdentityParams(params, input.identity);
  const result = await httpDelete(url, `/api/skill-file?${params.toString()}`);
  if (!result.ok) return textResult(`Error: ${result.error}`, true);
  const existed = result.existed === true;
  return textPlusStructured(
    existed
      ? `Deleted skill file "${input.path}" from "${input.name}".`
      : `Skill file "${input.path}" did not exist in "${input.name}" — nothing to delete.`,
    { skill: { ok: true, file: { path: input.path, existed } } },
  );
}

export async function deleteSkill(
  url: string | undefined,
  input: { scope?: SkillScope; name: string } & SkillIdentity,
) {
  const resolved = resolveSkillName(input.name);
  if (!resolved.ok) return textResult(`Error: ${resolved.error}`, true);
  if (!url) return textResult(hocuspocusNotRunningError(), true);
  const params = new URLSearchParams({ name: input.name, scope: input.scope ?? 'project' });
  if (input.summary !== undefined) params.set('summary', input.summary);
  appendIdentityParams(params, input.identity);
  const result = await httpDelete(url, `/api/skill?${params.toString()}`);
  if (!result.ok) return textResult(`Error: ${result.error}`, true);
  const existed = result.existed === true;
  const warnings = normalizeApiWarnings(result.warnings);
  const lines = [
    existed
      ? `Deleted skill "${input.name}".`
      : `Skill "${input.name}" did not exist — nothing to delete.`,
    ...warnings,
  ];
  return textPlusStructured(lines.join('\n'), {
    skill: { ok: true, existed, ...(warnings.length > 0 ? { warnings } : {}) },
  });
}

export async function moveSkill(
  url: string | undefined,
  input: { scope?: SkillScope; fromName: string; toName: string } & SkillIdentity,
) {
  const rf = resolveSkillName(input.fromName);
  if (!rf.ok) return textResult(`Error: ${rf.error}`, true);
  const rt = resolveSkillName(input.toName);
  if (!rt.ok) return textResult(`Error: ${rt.error}`, true);
  if (!url) return textResult(hocuspocusNotRunningError(), true);
  const result = await httpPost(url, '/api/skill', {
    ...(input.scope !== undefined ? { scope: input.scope } : {}),
    fromName: input.fromName,
    toName: input.toName,
    ...(input.summary !== undefined ? { summary: input.summary } : {}),
    ...agentIdentityFields(input.identity),
  });
  if (!result.ok) {
    const error = typeof result.error === 'string' ? result.error : 'Skill move failed';
    return textPlusStructured(
      errorTextWithDetail({ ...result, error }),
      { ok: false, kind: 'skill', error },
      true,
    );
  }
  const committed = result.committed === true;
  const from = typeof result.from === 'string' ? result.from : input.fromName;
  const to = typeof result.to === 'string' ? result.to : input.toName;
  return textPlusStructured(
    `${committed ? 'Renamed' : 'Moved'} skill ${from} → ${to}.${
      committed ? '' : ' (Untracked `.ok/` — moved on disk without git history.)'
    } Every location it occupied now holds the new name.`,
    { ok: true, kind: 'skill', committed },
  );
}

function destinationSkillRoot(entry: string, scope: SkillScope): string | null | undefined {
  if (!(ALL_EDITOR_IDS as readonly string[]).includes(entry)) return undefined;
  const roots = scope === 'global' ? EDITOR_USER_SKILL_ROOT : EDITOR_PROJECT_SKILL_ROOT;
  return roots[entry as EditorId];
}

function readsHubAt(entry: string, scope: SkillScope): boolean {
  return HUB_READER_EDITORS.some((reader) => reader.editorId === entry && reader.scope === scope);
}

export function crossScopeMoveSuccessText(input: {
  fromName: string;
  toName: string;
  fromScope: SkillScope;
  toScope: SkillScope;
  droppedLocations: readonly string[];
}): string {
  const fromLabel = input.fromScope === 'global' ? 'Global' : 'Project';
  const toLabel = input.toScope === 'global' ? 'Global' : 'Project';
  const unhostable = input.droppedLocations.filter(
    (entry) => destinationSkillRoot(entry, input.toScope) === null,
  );
  const hubEquivalent = unhostable.filter((entry) => readsHubAt(entry, input.toScope));
  const noPlacement = unhostable.filter((entry) => !readsHubAt(entry, input.toScope));
  const reinstallable = input.droppedLocations.filter((entry) => !unhostable.includes(entry));
  const list = (entries: readonly string[]) => entries.join(', ');
  const verb = (entries: readonly string[]) => (entries.length === 1 ? 'has' : 'have');

  const lead = `Moved skill "${input.fromName}" (${fromLabel}) → "${input.toName}" (${toLabel}) with its references, scripts, and bundle files, and re-projected it into the editor locations the ${toLabel} level can host. History did not transfer; it starts fresh at the ${toLabel} level.`;
  if (input.droppedLocations.length === 0) return lead;

  const parts = [
    `${lead} It also occupied ${list(input.droppedLocations)}; those were removed at the source and not re-created at the destination.`,
  ];
  if (reinstallable.length > 0) {
    const add = reinstallable.map((entry) => `"${entry}"`).join(', ');
    parts.push(
      `Re-add ${list(reinstallable)} with \`install({ name: "${input.toName}", scope: "${input.toScope}", add: [${add}] })\`.`,
    );
    if (reinstallable.some((entry) => entry.includes('/'))) {
      const destinationBase =
        input.toScope === 'global' ? 'your home directory' : 'the project directory';
      parts.push(
        `Custom roots resolve against the destination base — ${destinationBase} — not wherever the root lived before the move.`,
      );
    }
  }
  if (hubEquivalent.length > 0) {
    parts.push(
      `${list(hubEquivalent)} ${verb(hubEquivalent)} no ${toLabel}-level skills root, so \`install\` cannot place the skill there; ${hubEquivalent.length === 1 ? 'it reads' : 'they read'} the \`agents\` hub at that level, so \`install({ name: "${input.toName}", scope: "${input.toScope}", add: ["agents"] })\` is the equivalent.`,
    );
  }
  if (noPlacement.length > 0) {
    parts.push(
      `${list(noPlacement)} ${verb(noPlacement)} no ${toLabel}-level skills root and ${noPlacement.length === 1 ? 'does' : 'do'} not read the \`agents\` hub there, so no ${toLabel}-level placement exists — \`install\` would accept the id and project nothing.`,
    );
  }
  return parts.join(' ');
}

function crossScopeMoveFailureText(detail: string, outcome: SkillMoveFailureOutcome): string {
  if (outcome.kind === 'unverified' || outcome.moveState === undefined) {
    return `${detail}\nThe server returned a missing, unrecognized or inconsistent move outcome. Do not remove either copy before comparing the source and destination. Do not retry until the outcome is verified.`;
  }
  const lines = [detail, `moveState: ${outcome.moveState}.`];
  if (outcome.moveState === 'nothing-written') {
    if (outcome.retentionLedger !== undefined) {
      lines.push(
        `retentionLedger: ${outcome.retentionLedger}. Compare the source and destination before deleting either copy or retrying.`,
      );
    } else {
      lines.push(
        'This call changed neither location. It is safe to retry once the refusal is addressed; this does not rule out damage from an earlier call.',
      );
    }
  } else if (outcome.moveState === 'destination-removed') {
    lines.push(
      'The failed destination copy was removed and the source is intact. It is safe to retry.',
    );
  }
  return lines.join('\n');
}

export async function moveSkillCrossScope(
  url: string | undefined,
  input: {
    fromScope: SkillScope;
    toScope: SkillScope;
    fromName: string;
    toName: string;
  } & SkillIdentity,
) {
  const refuse = (error: string) =>
    textPlusStructured(
      crossScopeMoveFailureText(error, { kind: 'coherent', moveState: 'nothing-written' }),
      { ok: false, kind: 'skill', error, moveState: 'nothing-written' as const },
      true,
    );
  const rf = resolveSkillName(input.fromName);
  if (!rf.ok) return refuse(`Error: ${rf.error}`);
  const rt = resolveSkillName(input.toName);
  if (!rt.ok) return refuse(`Error: ${rt.error}`);
  if (!url) return refuse(hocuspocusNotRunningError());

  const moved = await httpPost(url, '/api/skill/move-scope', {
    name: input.fromName,
    ...(input.toName !== input.fromName ? { toName: input.toName } : {}),
    fromScope: input.fromScope,
    toScope: input.toScope,
    ...(input.summary !== undefined ? { summary: input.summary } : {}),
    ...agentIdentityFields(input.identity),
  });
  const readDroppedLocations = (raw: unknown): string[] =>
    Array.isArray(raw) ? raw.filter((entry): entry is string => typeof entry === 'string') : [];
  if (!moved.ok) {
    const error = typeof moved.error === 'string' ? moved.error : 'Skill move failed';
    const outcome = interpretSkillMoveFailure(moved);
    const detail = errorTextWithDetail({ ...moved, error });
    return textPlusStructured(
      crossScopeMoveFailureText(detail, outcome),
      {
        ok: false,
        kind: 'skill',
        error,
        droppedLocations: readDroppedLocations(moved.droppedLocations),
        ...(outcome.kind === 'coherent'
          ? {
              ...(outcome.moveState ? { moveState: outcome.moveState } : {}),
              ...(outcome.sourceState ? { sourceState: outcome.sourceState } : {}),
              ...(outcome.retentionLedger ? { retentionLedger: outcome.retentionLedger } : {}),
            }
          : {}),
      },
      true,
    );
  }
  const droppedLocations = readDroppedLocations(moved.droppedLocations);
  return textPlusStructured(
    crossScopeMoveSuccessText({
      fromName: input.fromName,
      toName: input.toName,
      fromScope: input.fromScope,
      toScope: input.toScope,
      droppedLocations,
    }),
    {
      ok: true,
      kind: 'skill',
      committed: false,
      crossScope: true,
      droppedLocations,
    },
  );
}