Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { afterEach, describe, expect, test } from 'vitest';
import { hocuspocusNotRunningError, UNREADABLE_WARNINGS_TEXT } from './shared.ts';
import { deleteSkill, moveSkill, moveSkillCrossScope, writeSkill } from './skill-target.ts';
interface ToolResult {
content: Array<{ type: 'text'; text: string }>;
structuredContent?: Record<string, unknown>;
isError?: boolean;
}
const text = (r: ToolResult) => r.content[0]?.text ?? '';
describe('skill verb tools — server-required contract', () => {
test('writeSkill with no server URL returns the not-running error', async () => {
const r = (await writeSkill(undefined, {
name: 'trip-log',
description: 'Use when logging a trip.',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toBe(hocuspocusNotRunningError());
});
test('deleteSkill with no server URL returns the not-running error', async () => {
const r = (await deleteSkill(undefined, { name: 'trip-log' })) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toBe(hocuspocusNotRunningError());
});
test('moveSkill with no server URL returns the not-running error', async () => {
const r = (await moveSkill(undefined, {
fromName: 'trip-log',
toName: 'fishing-log',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toBe(hocuspocusNotRunningError());
});
});
describe('skill verb tools — name grammar short-circuits before the network', () => {
const UNREACHABLE = 'http://127.0.0.1:1';
test('writeSkill rejects an invalid name with the teaching error', async () => {
const r = (await writeSkill(UNREACHABLE, {
name: 'Bad Name!',
description: 'd',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toContain('lowercase letters');
});
test('moveSkill rejects an invalid fromName with the teaching error', async () => {
const r = (await moveSkill(UNREACHABLE, {
fromName: 'Bad From!',
toName: 'fishing-log',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toContain('lowercase letters');
});
test('moveSkillCrossScope with no server URL returns the not-running error', async () => {
const r = (await moveSkillCrossScope(undefined, {
fromScope: 'project',
toScope: 'global',
fromName: 'trip-log',
toName: 'trip-log',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toContain(hocuspocusNotRunningError());
expect(text(r)).toContain('moveState: nothing-written');
expect(text(r)).toContain('safe to retry once the refusal is addressed');
});
test('moveSkillCrossScope rejects an invalid name before the network', async () => {
const r = (await moveSkillCrossScope(UNREACHABLE, {
fromScope: 'project',
toScope: 'global',
fromName: 'Bad Name!',
toName: 'trip-log',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toContain('lowercase letters');
});
});
describe('moveSkill — a same-level rename collision surfaces the RFC 9457 detail', () => {
const realFetch = globalThis.fetch;
afterEach(() => {
globalThis.fetch = realFetch;
});
test('the retained-copy safety prose reaches the text channel, not just the title', async () => {
globalThis.fetch = (async () =>
new Response(
JSON.stringify({
type: 'urn:ok:error:conflict',
title: 'A skill named "fishing-log" already exists.',
status: 409,
detail:
'Do NOT delete it before reconciling it against the source: it may hold the only copy of files that failed removal already deleted.',
}),
{ status: 409, headers: { 'content-type': 'application/problem+json' } },
)) as typeof fetch;
const r = (await moveSkill('http://127.0.0.1:9', {
fromName: 'trip-log',
toName: 'fishing-log',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(text(r)).toContain('A skill named "fishing-log" already exists.');
expect(text(r)).toContain(
'it may hold the only copy of files that failed removal already deleted',
);
expect(r.structuredContent).toMatchObject({
ok: false,
kind: 'skill',
error: 'A skill named "fishing-log" already exists.',
});
});
});
describe('moveSkillCrossScope — delegates to the canonical /api/skill/move-scope endpoint', () => {
const realFetch = globalThis.fetch;
afterEach(() => {
globalThis.fetch = realFetch;
});
interface Call {
method: string;
path: string;
body: Record<string, unknown>;
}
function mockFetch(handler: (call: Call) => Record<string, unknown>) {
const calls: Call[] = [];
globalThis.fetch = (async (input: string, init?: { method?: string; body?: string }) => {
const call: Call = {
method: init?.method ?? 'GET',
path: new URL(input).pathname,
body: init?.body ? (JSON.parse(init.body) as Record<string, unknown>) : {},
};
calls.push(call);
const res = handler(call);
if (res.ok === false) {
return new Response(JSON.stringify({ ...res, error: res.error ?? 'error' }), {
status: typeof res.status === 'number' ? res.status : 500,
headers: { 'content-type': 'application/json' },
});
}
return new Response(JSON.stringify(res), {
status: 200,
headers: { 'content-type': 'application/json' },
});
}) as typeof fetch;
return calls;
}
const move = (toName: string) =>
moveSkillCrossScope('http://127.0.0.1:9', {
fromScope: 'project',
toScope: 'global',
fromName: 'trip-log',
toName,
}) as Promise<ToolResult>;
test.each(['nothing-written', 'destination-removed'])(
'%s names the validated outcome and teaches when retry is safe',
async (moveState) => {
mockFetch(() => ({ ok: false, status: 500, error: 'Move failed.', moveState }));
const result = await move('trip-log');
expect(text(result)).toContain(`moveState: ${moveState}`);
expect(text(result)).toContain('safe to retry');
expect(result.structuredContent).toMatchObject({ moveState });
},
);
test.each(['Delete or rename it first; this move will not overwrite it.', 'SAME_STORAGE'])(
'a verified refusal preserves its detail and permits retry after repair: %s',
async (detail) => {
mockFetch(() => ({
ok: false,
status: 409,
type: 'urn:ok:error:doc-already-exists',
error: 'A global skill named "trip-log" already exists.',
detail,
moveState: 'nothing-written',
}));
const result = await move('trip-log');
expect(text(result)).toContain('moveState: nothing-written');
expect(text(result)).toContain(detail);
expect(text(result)).toContain('safe to retry once the refusal is addressed');
expect(text(result)).not.toContain('occupant is unverified');
},
);
test.each([400, 409, 500])('a missing state stays unknown even with HTTP %s', async (status) => {
mockFetch(() => ({ ok: false, status, error: 'Move failed.' }));
const result = await move('trip-log');
expect(text(result)).toContain('Do not remove either copy before comparing');
expect(text(result)).not.toContain('safe to retry');
expect(result.structuredContent).not.toHaveProperty('moveState');
});
test.each([
{ moveState: 'destination-stray', detail: 'Remove the stray destination before retrying.' },
{
moveState: 'destination-retained',
sourceState: 'intact',
detail: 'The source was intact at removal. Remove the duplicate destination before retrying.',
},
{
moveState: 'destination-retained',
sourceState: 'lossy',
detail: 'Recover missing source files from the retained copy before removing either copy.',
},
{
moveState: 'destination-retained',
sourceState: 'unknown',
detail: 'Compare both locations before removing either.',
},
{
moveState: 'destination-retained-blocking',
sourceState: 'intact',
detail:
'The source was intact at the earlier failed removal; compare current contents before removing the duplicate.',
},
{
moveState: 'destination-retained-blocking',
sourceState: 'lossy',
detail: 'Recover missing source files from the retained copy before removing either copy.',
},
{
moveState: 'destination-retained-blocking',
sourceState: 'unknown',
detail: 'Compare both locations before removing either.',
},
{
moveState: 'nothing-written',
retentionLedger: 'unreadable',
detail: 'The retention ledger is unreadable; compare both copies before deleting anything.',
},
{
moveState: 'nothing-written',
retentionLedger: 'occupant-unverifiable',
detail: 'The occupant is unverifiable; compare both copies before deleting anything.',
},
{
moveState: 'destination-unreadable',
detail: 'Do not retry. Restore the skill from a backup or project history.',
},
{
moveState: 'partially-applied',
detail:
'Inspect source and destination; preserve remaining copies and recover missing files.',
},
])(
'preserves the guarded recovery for $moveState / $sourceState / $retentionLedger',
async (outcome) => {
mockFetch(() => ({ ok: false, status: 500, error: 'Move failed.', ...outcome }));
const result = await move('trip-log');
expect(text(result)).toContain(`moveState: ${outcome.moveState}`);
expect(text(result)).toContain(outcome.detail);
expect(text(result).split(outcome.detail)).toHaveLength(2);
expect(text(result)).not.toContain('safe to retry');
const { detail: _, ...fields } = outcome;
expect(result.structuredContent).toMatchObject(fields);
},
);
test.each(['unreadable', 'future-ledger-reason'])(
'an inconsistent retained result cannot advertise an intact source: %s',
async (retentionLedger) => {
mockFetch(() => ({
ok: false,
status: 409,
error: 'Move did not complete.',
detail: 'The destination must be compared with the source.',
moveState: 'destination-retained',
sourceState: 'intact',
retentionLedger,
droppedLocations: ['agents'],
}));
const result = await move('trip-log');
expect(result.isError).toBe(true);
expect(text(result)).toContain('The destination must be compared with the source.');
expect(text(result)).toContain('Do not remove either copy before comparing');
expect(result.structuredContent).toMatchObject({ droppedLocations: ['agents'] });
expect(result.structuredContent).not.toHaveProperty('sourceState');
expect(result.structuredContent).not.toHaveProperty('moveState');
expect(result.structuredContent).not.toHaveProperty('retentionLedger');
},
);
test('a name-preserving move is one canonical request and reports editor re-projection', async () => {
const calls = mockFetch(() => ({ ok: true, scope: 'global', path: '.agents/skills/trip-log' }));
const r = await move('trip-log');
expect(r.isError).toBeUndefined();
expect(calls).toEqual([
{
method: 'POST',
path: '/api/skill/move-scope',
body: { name: 'trip-log', fromScope: 'project', toScope: 'global' },
},
]);
expect(text(r)).toContain('editor locations the Global level can host');
expect(text(r)).not.toContain('install(');
expect(text(r)).toContain('(Global)');
expect(r.structuredContent).toMatchObject({
ok: true,
kind: 'skill',
crossScope: true,
committed: false,
droppedLocations: [],
});
});
test('a renaming move is still ONE request, carrying the destination name', async () => {
const calls = mockFetch(() => ({ ok: true, scope: 'global' }));
const r = await move('fishing-log');
expect(r.isError).toBeUndefined();
expect(calls.map((c) => [c.path, c.body])).toEqual([
[
'/api/skill/move-scope',
{ name: 'trip-log', toName: 'fishing-log', fromScope: 'project', toScope: 'global' },
],
]);
expect(text(r)).toContain('"fishing-log" (Global)');
expect(r.structuredContent).toMatchObject({ ok: true, crossScope: true });
});
test('dropped locations are named with the install call that restores them', async () => {
mockFetch(() => ({
ok: true,
scope: 'global',
path: '.agents/skills/trip-log',
droppedLocations: ['.team/skills', 'agents'],
}));
const r = await move('trip-log');
expect(r.isError).toBeUndefined();
expect(text(r)).toContain('.team/skills, agents');
expect(text(r)).toContain(
'install({ name: "trip-log", scope: "global", add: [".team/skills", "agents"] })',
);
expect(r.structuredContent).toMatchObject({
droppedLocations: ['.team/skills', 'agents'],
});
});
test('the custom-root caveat names the destination base for the direction moved', async () => {
const dropped = () => ({ ok: true, scope: 'global', droppedLocations: ['.team/skills'] });
const crossScope = (fromScope: 'project' | 'global', toScope: 'project' | 'global') =>
moveSkillCrossScope('http://127.0.0.1:9', {
fromScope,
toScope,
fromName: 'trip-log',
toName: 'trip-log',
}) as Promise<ToolResult>;
mockFetch(dropped);
const toGlobal = await crossScope('project', 'global');
expect(text(toGlobal)).toContain('destination base — your home directory —');
expect(text(toGlobal)).not.toContain('the project directory');
mockFetch(dropped);
const toProject = await crossScope('global', 'project');
expect(text(toProject)).toContain('destination base — the project directory —');
expect(text(toProject)).not.toContain('your home directory');
});
test('a failure that destroyed the source ledger still carries the dropped locations', async () => {
mockFetch(() => ({
ok: false,
status: 500,
error: 'The source was removed, but the destination skill is unreadable.',
moveState: 'destination-unreadable',
droppedLocations: ['.team/skills', 'agents'],
}));
const r = await move('trip-log');
expect(r.isError).toBe(true);
expect(r.structuredContent).toMatchObject({
ok: false,
moveState: 'destination-unreadable',
droppedLocations: ['.team/skills', 'agents'],
});
});
test('a retained destination from an earlier failure is not reported as safe to retry', async () => {
mockFetch(() => ({
ok: false,
status: 409,
error: 'A global skill named "trip-log" already exists.',
moveState: 'destination-retained-blocking',
sourceState: 'intact',
}));
const r = await move('trip-log');
expect(r.isError).toBe(true);
expect(r.structuredContent).toMatchObject({
moveState: 'destination-retained-blocking',
sourceState: 'intact',
});
});
test('a retained destination with no source state is withheld rather than half-reported', async () => {
mockFetch(() => ({
ok: false,
status: 409,
error: 'A global skill named "trip-log" already exists.',
moveState: 'destination-retained-blocking',
}));
const r = await move('trip-log');
expect(r.isError).toBe(true);
expect(text(r)).toContain('Do not remove either copy before comparing');
expect(r.structuredContent).not.toHaveProperty('moveState');
expect(r.structuredContent).not.toHaveProperty('sourceState');
expect(r.structuredContent).not.toHaveProperty('retentionLedger');
});
test('a refusal before the request is made reports that nothing was written', async () => {
const calls = mockFetch(() => ({ ok: true, scope: 'global' }));
const r = (await moveSkillCrossScope(undefined, {
fromScope: 'project',
toScope: 'global',
fromName: 'trip-log',
toName: 'trip-log',
})) as ToolResult;
expect(r.isError).toBe(true);
expect(calls).toHaveLength(0);
expect(r.structuredContent).toMatchObject({
ok: false,
kind: 'skill',
moveState: 'nothing-written',
});
});
test('an endpoint refusal surfaces its message and attempts nothing else', async () => {
const calls = mockFetch(() => ({
ok: false,
status: 409,
error: 'A global skill named "trip-log" already exists.',
moveState: 'nothing-written',
}));
const r = await move('fishing-log');
expect(r.isError).toBe(true);
expect(text(r)).toContain('already exists');
expect(calls).toHaveLength(1);
expect(r.structuredContent).toMatchObject({
ok: false,
kind: 'skill',
moveState: 'nothing-written',
});
});
test.each(['unreadable', 'occupant-unverifiable'] as const)(
'a %s retention ledger survives the adapter, so the caller can see the occupant is unverified',
async (retentionLedger) => {
mockFetch(() => ({
ok: false,
status: 409,
error: 'A global skill named "trip-log" already exists.',
moveState: 'nothing-written',
retentionLedger,
}));
const r = await move('trip-log');
expect(r.isError).toBe(true);
expect(r.structuredContent).toMatchObject({
moveState: 'nothing-written',
retentionLedger,
});
},
);
test('a retentionLedger outside the advertised enum is dropped rather than forwarded', async () => {
mockFetch(() => ({
ok: false,
status: 409,
error: 'A global skill named "trip-log" already exists.',
moveState: 'nothing-written',
retentionLedger: 'some-future-ledger-state',
}));
const r = await move('trip-log');
expect(r.isError).toBe(true);
expect(r.structuredContent).not.toHaveProperty('retentionLedger');
});
test('a moveState outside the advertised enum is dropped rather than forwarded', async () => {
mockFetch(() => ({
ok: false,
status: 500,
error: 'Failed to move skill across scopes.',
moveState: 'some-future-state',
}));
const r = await move('fishing-log');
expect(r.isError).toBe(true);
expect(r.structuredContent).not.toHaveProperty('moveState');
});
test('endpoint details stay in the text channel while the structured error stays the title', async () => {
const error = 'Cannot move to project scope.';
mockFetch(() => ({ ok: false, status: 400, error, detail: 'NO_PROJECT_ROOT' }));
const result = await move('fishing-log');
expect(text(result)).toContain(`Error: ${error} (NO_PROJECT_ROOT)`);
expect(text(result)).toContain('missing, unrecognized or inconsistent move outcome');
expect(result.structuredContent).toMatchObject({ ok: false, error });
});
});
describe('writeSkill — an unreadable warnings payload reaches BOTH channels', () => {
const realFetch = globalThis.fetch;
afterEach(() => {
globalThis.fetch = realFetch;
});
test('a non-array `warnings` is rendered in the text, not only in the structured field', async () => {
globalThis.fetch = (async () =>
new Response(
JSON.stringify({
ok: true,
created: true,
path: '.agents/skills/trip-log/SKILL.md',
warnings: 'Skill name contains "claude".',
warningCodes: ['skill-name-vendor-word'],
}),
{ status: 200, headers: { 'content-type': 'application/json' } },
)) as typeof fetch;
const r = (await writeSkill('http://127.0.0.1:9', {
name: 'trip-log',
description: 'Use when logging a trip.',
})) as ToolResult;
expect(r.isError).toBeUndefined();
expect(text(r)).toContain('treat this result as unverified');
expect((r.structuredContent?.skill as { warnings?: unknown })?.warnings).toEqual([
UNREADABLE_WARNINGS_TEXT,
]);
});
});