Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { readFileSync } from 'node:fs';
import { resolve as resolvePath } from 'node:path';
import {
type DocExtension,
type FrontmatterMap,
type FrontmatterPatch,
findTemplateByName,
instantiateDoc,
localIsoDate,
normalizeBridge,
type ProblemType,
parseFrontmatterYaml,
SKILL_AUTHORING_WARNING_CODES,
serializeFrontmatterMap,
stripFrontmatter,
UploadAssetSuccessSchema,
type UploadRequest,
unwrapFrontmatterFences,
withFences,
} from '@inkeep/open-knowledge-core';
import { z } from 'zod';
import {
formatBrokenLinkSuppressionBrief,
formatBrokenLinkSuppressionLine,
} from '../../broken-link-suppression.ts';
import { CONCURRENT_OVERWRITE_REFUSED_TYPE } from '../../concurrent-overwrite-refused-error.ts';
import { resolveContentDir, resolveLockDir } from '../../config/paths.ts';
import { mergePatch } from '../../content/frontmatter-merge.ts';
import { parentFolderOf } from '../../content/nested-folder-rules.ts';
import { applySubstitution } from '../../content/substitution.ts';
import { resolveTemplatesAvailable } from '../../content/templates-resolver.ts';
import type { LocalApiDispatch } from '../../http/local-api-dispatch.ts';
import { splitPayloadFrontmatter } from '../../payload-frontmatter.ts';
import type { AgentIdentity } from '../agent-identity.ts';
import {
formatAdvisoryBriefs,
formatAdvisoryLines,
formatBrokenLinkBrief,
formatBrokenLinkLines,
parseAdvisoryWarnings,
parseBrokenLinkSuppression,
parseBrokenLinks,
} from './advisory-warnings.ts';
import { buildPreviewAttachWarning, resolvePreviewUrl, startUiTextHint } from './preview-url.ts';
import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';
import {
AUTHORING_WARNING_CODE_GLOSS,
agentIdentityFields,
apiTarget,
CANONICAL_COMPONENT_GUIDANCE,
docExtensionOnDisk,
documentResultBaseShape,
errorTextWithDetail,
hocuspocusNotRunningError,
httpPost,
httpPut,
looseObjectArray,
nestDocResult,
normalizeDocName,
okReservedPathRedirect,
outputSchemaWithText,
previewAttachWarningField,
previewUrlOutputField,
previewUrlSourceField,
ROUTED_CWD_DESCRIPTION,
requestFailureText,
resolveProjectServerContext,
serverRequestFailure,
summaryArgSchema,
textPlusStructured,
textResult,
WARNING_CODES_CONTRACT,
WARNINGS_FIELD_CONTRACT,
} from './shared.ts';
import { writeSkill, writeSkillFile } from './skill-target.ts';
import {
DocExtensionArg,
exactlyOneTargetError,
FrontmatterArg,
PositionArg,
resolveSkillFilePath,
resolveTemplatePath,
SKILL_BODY_DESCRIBE,
SKILL_DESCRIPTION_DESCRIBE,
SKILL_FILES_DESCRIBE,
SKILL_NAME_DESCRIBE,
SkillScopeArg,
splitTargetPath,
TEMPLATE_CONTENT_DESCRIBE,
TEMPLATE_PATH_DESCRIBE,
} from './verb-schemas.ts';
import {
failedWriteResult,
landedLead,
landedWithoutSuccess,
leadFor,
needsAttention,
REFUSED_WITHOUT_ERROR_STATUS,
refusedDespiteSuccess,
refusedWriteResult,
rereadAfterLanding,
type WriteOutcome,
weightierOutcome,
writeOutcomeFields,
writeOutcomeLine,
writeOutcomeOf,
writeOutcomeOutputShape,
} from './write-outcome.ts';
const DESCRIPTION = [
'Create/replace exactly one `document`, `folder`, `template`, `skill`, or `asset`; use `documents` for an ordered batch. Requires the Hocuspocus server.',
'Nested paths such as `guides/overview` can be documents; put all requested blocks in one `document.content`. Use `folder` only for separate pages.',
'`document: {path, content|template, frontmatter?, position?}`: content and template are exclusive. Existing docs require position: replace/append/prepend; new docs default replace. frontmatter with literal content forces replace, even with append/prepend. Recent edits by another writer can refuse replace; follow the recovery response; append/prepend/edit bypass this refusal. Peers are per MCP connection; own writes and writers sharing a connection do not refuse each other; connected editors can. No agentId is needed.',
"`folder: {path, frontmatter?}` creates NEW folders; edit existing ones. `template: {path: '<folder>/<name>', content, frontmatter: {title, description?, tags?}}` creates reusable doc templates.",
'`skill: {name, description, body, scope?}` writes agent guidance; lowercase letters/digits/hyphens name is identity, description is when to use it. New skills use the default skill home; existing ones keep their real folder. Use install for editors.',
'`asset: {path, content|source}` uploads binary image/file: base64 content or local source path. `documents` takes document specs and reports each result.',
'Optional summary: one-line outcome ≤80 chars, persisted to git history; avoid secrets or PII. Batches need per-entry summary; top-level is ignored.',
'Follow nextStep: retry|re-read|none. Outcomes merged-first, both-kept, projection-held landed: never retry. mermaid-parse-error: fix the fence.',
CANONICAL_COMPONENT_GUIDANCE,
].join('\n');
interface WriteDeps {
serverUrl: ServerUrlOrResolver;
config: ConfigOrResolver;
resolveCwd: (explicit?: string) => Promise<string>;
identityRef?: { current: AgentIdentity };
localApi?: LocalApiDispatch;
}
interface DocSpec {
path: string;
content?: string;
template?: string;
frontmatter?: FrontmatterPatch;
position?: string;
summary?: string;
extension?: DocExtension;
}
type WriteApiResult = Awaited<ReturnType<typeof httpPost>>;
type WriteOneResult =
| {
docName: string;
ok: true;
position: string;
fromTemplate?: string;
extensionNote?: string;
createdByPosition?: 'append' | 'prepend';
templateHint?: readonly { name: string; description?: string }[];
outcome?: WriteOutcome;
frontmatterNote?: string;
raw: WriteApiResult;
}
| { docName: string; ok: false; error: string; outcome?: WriteOutcome };
export function frontmatterIgnoredNote(
position: string,
markdown: string | undefined,
): string | null {
if ((position !== 'prepend' && position !== 'append') || !markdown) return null;
const claimed = stripFrontmatter(markdown).frontmatter.trim() !== '';
if (!claimed) return null;
if (splitPayloadFrontmatter(markdown).frontmatter.trim() !== '') {
return `Note: a \`---\` frontmatter block in this \`${position}\` payload was ignored — frontmatter is written only with \`position: "replace"\`. To change frontmatter, use \`edit({ document: { path, frontmatter } })\` (patch) or \`write({ document: { path, content, position: "replace" } })\` (full rewrite).`;
}
return `Note: this \`${position}\` payload opens with a \`---\` fence pair, but what is between the fences is not a YAML mapping, so it was written as BODY text (fence lines included) rather than treated as frontmatter. If you meant a thematic break, that is the correct outcome — \`***\` or \`___\` avoids the ambiguity. If you meant to set frontmatter, the YAML did not parse: use \`edit({ document: { path, frontmatter } })\` (patch) or \`write({ document: { path, content, position: "replace" } })\` (full rewrite).`;
}
function createdByPositionNote(docName: string, position: 'append' | 'prepend'): string {
return `Created new document "${docName}" — no document existed at this path, so \`${position}\` started a new one. If you meant to add to an existing document, the path is wrong (paths are relative to the content root): remove this one with \`delete({ document: "${docName}" })\` and retry at the intended path.`;
}
function emptyAppendNoOpNote(position: string, markdown: string | undefined): string | null {
if ((position !== 'prepend' && position !== 'append') || markdown === undefined) return null;
if (splitPayloadFrontmatter(markdown).body !== '') return null;
return `No content to ${position} — document unchanged. To clear a document, use \`position: "replace"\` with empty \`content\`.`;
}
function requestedDocExtension(rawDocName: string): '.md' | '.mdx' | null {
const lower = rawDocName.toLowerCase();
if (lower.endsWith('.mdx')) return '.mdx';
if (lower.endsWith('.md')) return '.md';
return null;
}
function extensionIgnoredNote(
requestedExt: '.md' | '.mdx' | null,
existingExt: '.md' | '.mdx' | null,
docName: string,
): string | null {
if (requestedExt === null || existingExt === null || requestedExt === existingExt) return null;
return `Note: "${docName}" already exists as \`${docName}${existingExt}\`, so the requested \`${requestedExt}\` extension was not applied — the write went to \`${docName}${existingExt}\`. Changing a doc's on-disk extension in place isn't available via the MCP today.`;
}
export function composeWithFrontmatter(
frontmatter: FrontmatterPatch,
body: string,
): { ok: true; markdown: string } | { ok: false; error: string } {
const { frontmatter: embeddedFenced, body: cleanBody } = stripFrontmatter(body);
let base: FrontmatterMap = {};
if (embeddedFenced !== '') {
const parsed = parseFrontmatterYaml(unwrapFrontmatterFences(embeddedFenced));
if (parsed.map === null) {
return {
ok: false,
error: `EMBEDDED_FRONTMATTER_MALFORMED — \`content\` opens with a \`---\` block whose YAML failed to parse (${parsed.parseError}), so it can't be merged with the \`frontmatter\` param. Fix the embedded YAML, or supply the frontmatter only via the \`frontmatter\` param (not also inline in \`content\`).`,
};
}
let unsupportedKey = false;
parsed.doc.toJS({
reviver(key: unknown, value: unknown) {
if (key === '__proto__') unsupportedKey = true;
return value;
},
});
if (unsupportedKey) {
return {
ok: false,
error:
'EMBEDDED_FRONTMATTER_UNSUPPORTED_KEY — `content` opens with a `---` block containing a field named `__proto__` (written literally, escaped, or reached through a YAML alias), which frontmatter cannot store, so the block cannot be merged with the `frontmatter` param. Nothing was written. Rename or remove that field in the embedded YAML.',
};
}
base = parsed.map;
}
const merged = mergePatch(base, frontmatter as Record<string, unknown>) as FrontmatterMap;
const yamlBody = serializeFrontmatterMap(merged);
if (yamlBody === '') return { ok: true, markdown: cleanBody };
return { ok: true, markdown: withFences(yamlBody) + cleanBody };
}
const FRONTMATTER_PATCH_REJECTED_BEFORE_APPLY: ReadonlySet<unknown> = new Set<ProblemType>([
'urn:ok:error:invalid-request',
'urn:ok:error:invalid-frontmatter-patch',
]);
function frontmatterPatchAppliedNothing(result: { [key: string]: unknown }): boolean {
return result.committed === false || FRONTMATTER_PATCH_REJECTED_BEFORE_APPLY.has(result.type);
}
async function writeOneDoc(
spec: DocSpec,
cwd: string,
contentDir: string,
url: string,
deps: WriteDeps,
): Promise<WriteOneResult> {
const normalized = normalizeDocName(spec.path);
if (!normalized.ok) {
return {
docName: spec.path,
ok: false,
error: okReservedPathRedirect(spec.path) ?? normalized.error,
};
}
const docName = normalized.docName;
const identity = deps.identityRef?.current;
if (spec.template === undefined && spec.content === undefined) {
return {
docName,
ok: false,
error:
'either `content` or `template` must be provided — omitting both would write empty content.',
};
}
if (spec.template !== undefined && spec.content !== undefined) {
return {
docName,
ok: false,
error:
'TEMPLATE_AND_CONTENT_BOTH_SET — `template` and `content` are mutually exclusive. Pass one; fill placeholders via subsequent `edit` calls.',
};
}
let effectiveMarkdown = spec.content ?? '';
const hasFrontmatter = spec.frontmatter !== undefined && Object.keys(spec.frontmatter).length > 0;
const existingExt = docExtensionOnDisk(contentDir, docName) ?? null;
const docExists = existingExt !== null;
const requestedExt = spec.extension ?? requestedDocExtension(spec.path);
let effectivePosition: string;
if (spec.position !== undefined) {
effectivePosition = spec.position;
} else if (docExists) {
return {
docName,
ok: false,
error: `"${docName}" already exists — pass \`position\` (\`append\` | \`prepend\` | \`replace\`), or use \`edit\` for a targeted change.`,
};
} else {
effectivePosition = 'replace';
}
let templateHint: readonly { name: string; description?: string }[] | undefined;
if (spec.template === undefined && !docExists) {
const available = resolveTemplatesAvailable(cwd, parentFolderOf(docName));
if (available.length > 0) {
templateHint = available.map((t) => ({
name: t.name,
...(t.description ? { description: t.description } : {}),
}));
}
}
if (spec.template !== undefined) {
const parentFolder = parentFolderOf(docName);
const available = resolveTemplatesAvailable(cwd, parentFolder);
const matched = findTemplateByName(available, spec.template);
if (!matched) {
return {
docName,
ok: false,
error: `template "${spec.template}" not found for folder "${parentFolder || '.'}". Available: ${
available.length === 0
? '(none)'
: available.map((t) => `${t.name} [${t.scope}]`).join(', ')
}. Templates are resolved by walk-up; check the parent folder's exec listing to see the menu.`,
};
}
let templateContent: string;
try {
templateContent = readFileSync(resolvePath(cwd, matched.path), 'utf-8');
} catch (err) {
return {
docName,
ok: false,
error: `failed to read template at ${matched.path}: ${(err as Error).message}`,
};
}
const templateBody = instantiateDoc(templateContent);
effectiveMarkdown = applySubstitution(templateBody, {
date: localIsoDate(),
user: identity?.displayName ?? '',
});
effectivePosition = 'replace';
} else if (hasFrontmatter) {
const composed = composeWithFrontmatter(
spec.frontmatter as FrontmatterPatch,
effectiveMarkdown,
);
if (!composed.ok) return { docName, ok: false, error: composed.error };
effectiveMarkdown = composed.markdown;
effectivePosition = 'replace';
}
if (!docExists && normalizeBridge(effectiveMarkdown) === '') {
return {
docName,
ok: false,
error: `"${docName}" does not exist and the content is empty — provide non-empty content to create the document.`,
};
}
const result = await httpPost(url, '/api/agent-write-md', {
docName,
markdown: effectiveMarkdown,
position: effectivePosition,
...(requestedExt !== null && !docExists ? { extension: requestedExt } : {}),
...(spec.summary !== undefined ? { summary: spec.summary } : {}),
...agentIdentityFields(identity),
});
const outcome = writeOutcomeOf(result);
if (result.ok && refusedDespiteSuccess(outcome)) {
return { docName, ok: false, error: REFUSED_WITHOUT_ERROR_STATUS, outcome };
}
if (!result.ok && !landedWithoutSuccess(outcome)) {
const offsetBasis =
result.type === 'urn:ok:error:invalid-request' && result.contentControlAdmission === true
? spec.template !== undefined
? ' Any markdown offset refers to generated template Markdown after substitution.'
: hasFrontmatter
? ' Any markdown offset refers to composed Markdown including frontmatter.'
: ' Any markdown offset refers to document.content as forwarded.'
: '';
const recovery =
result.type === CONCURRENT_OVERWRITE_REFUSED_TYPE
? ' Wait and retry, or use edit for a targeted change.'
: '';
return {
docName,
ok: false,
error: `${requestFailureText(result)}${offsetBasis}${recovery}`,
...(outcome ? { outcome } : {}),
};
}
const templateFrontmatterHeld =
spec.template !== undefined && hasFrontmatter && !result.ok && outcome?.outcome !== 'both-kept';
let entryOutcome = outcome;
if (spec.template !== undefined && hasFrontmatter && !templateFrontmatterHeld) {
const fmResult = await httpPost(url, '/api/frontmatter-patch', {
docName,
patch: spec.frontmatter,
...agentIdentityFields(identity),
});
const fmOutcome = writeOutcomeOf(fmResult);
if ((!fmResult.ok && !landedWithoutSuccess(fmOutcome)) || refusedDespiteSuccess(fmOutcome)) {
return {
docName,
ok: false,
error:
frontmatterPatchAppliedNothing(fmResult) || fmOutcome?.outcome === 'refused'
? `document created from template "${spec.template}"; its body landed, but its frontmatter patch was refused, so the frontmatter was not applied: ${requestFailureText(fmResult)} Re-read the document, then apply the frontmatter alone with edit({ document: { path: "${docName}", frontmatter } }); do not repeat the templated write.`
: `document created from template "${spec.template}"; its body landed, but its frontmatter patch failed, and this response does not show whether the frontmatter was applied: ${requestFailureText(fmResult)} Re-read the document, then apply only the missing frontmatter with edit({ document: { path: "${docName}", frontmatter } }); do not repeat the templated write.`,
...(outcome ? { outcome: rereadAfterLanding(outcome) } : {}),
};
}
entryOutcome = weightierOutcome(outcome, fmOutcome);
}
const extensionNote = extensionIgnoredNote(requestedExt, existingExt, docName);
const createdByPosition =
!docExists && (effectivePosition === 'append' || effectivePosition === 'prepend')
? effectivePosition
: undefined;
return {
docName,
ok: true,
position: effectivePosition,
...(createdByPosition ? { createdByPosition } : {}),
...(spec.template !== undefined ? { fromTemplate: spec.template } : {}),
...(extensionNote ? { extensionNote } : {}),
...(templateHint ? { templateHint } : {}),
...(entryOutcome ? { outcome: entryOutcome } : {}),
...(templateFrontmatterHeld
? {
frontmatterNote: `The frontmatter you passed with the template was not applied, because the document's save is held. Re-read the document, then apply it with edit({ document: { path: "${docName}", frontmatter } }).`,
}
: {}),
raw: result,
};
}
function formatTemplateHintLine(hint: readonly { name: string; description?: string }[]): string {
const list = hint
.map((t) => (t.description ? `${t.name} (${t.description})` : t.name))
.join(', ');
return `ℹ This folder has templates you can start from: ${list}. Pass \`template: "${hint[0]?.name ?? ''}"\` next time to match the folder's shape (the doc still landed).`;
}
async function handleFolder(
folder: { path: string; frontmatter?: FrontmatterPatch },
summary: string | undefined,
url: string | undefined,
deps: WriteDeps,
) {
if (!url) return textResult(hocuspocusNotRunningError(), true);
const identity = deps.identityRef?.current;
const result = await httpPost(apiTarget(url, deps.localApi), '/api/create-folder', {
path: folder.path,
...(summary !== undefined ? { summary } : {}),
...agentIdentityFields(identity),
});
if (!result.ok) {
const detail =
typeof result.detail === 'string' && result.detail.length > 0 ? result.detail : '';
return textResult(
detail ? `Error: ${result.error} (${detail})` : `Error: ${result.error}`,
true,
);
}
const lines = [`Created folder ${folder.path}.`];
if (folder.frontmatter !== undefined && Object.keys(folder.frontmatter).length > 0) {
const fm = await httpPut(url, '/api/folder-config', {
path: folder.path,
frontmatter: folder.frontmatter,
...(summary !== undefined ? { summary } : {}),
...agentIdentityFields(identity),
});
if (!fm.ok) {
return textPlusStructured(
`Created folder ${folder.path}, but writing its properties failed: ${fm.error}. Use edit({ folder: { path: "${folder.path}", frontmatter } }) to retry the properties.`,
{ folder: { ok: true, path: folder.path, frontmatterError: String(fm.error) } },
);
}
lines.push(`Set folder properties (${folder.path}/.ok/frontmatter.yml).`);
}
return textPlusStructured(lines.join('\n'), { folder: { ok: true, path: folder.path } });
}
async function handleTemplate(
template: {
path: string;
content: string;
frontmatter: { title: string } & Record<string, unknown>;
},
summary: string | undefined,
url: string | undefined,
deps: WriteDeps,
) {
const resolved = resolveTemplatePath(template.path);
if (!resolved.ok) return textResult(`Error: ${resolved.error}`, true);
const { folder, name } = resolved;
if (!url) return textResult(hocuspocusNotRunningError(), true);
const result = await httpPut(url, '/api/template', {
folder,
name,
body: template.content,
frontmatter: {
title: template.frontmatter.title,
...(typeof template.frontmatter.description === 'string'
? { description: template.frontmatter.description }
: {}),
...(Array.isArray(template.frontmatter.tags)
? { tags: template.frontmatter.tags as string[] }
: {}),
},
...(summary !== undefined ? { summary } : {}),
...agentIdentityFields(deps.identityRef?.current),
});
const outcome = writeOutcomeOf(result);
if (!result.ok) {
return failedWriteResult(
errorTextWithDetail(result, 'Any body offset refers to the full submitted template.content.'),
outcome,
);
}
if (refusedDespiteSuccess(outcome)) {
return refusedWriteResult(`The write of template "${name}"`, outcome);
}
const created = result.created === true;
const path = typeof result.path === 'string' ? result.path : undefined;
const outcomeLine = outcome?.outcome === 'applied' ? null : writeOutcomeLine(outcome);
return textPlusStructured(
[
leadFor(
outcome,
`${created ? 'Created' : 'Updated'} template "${name}"`,
`${created ? 'Created' : 'Updated'} template "${name}" in ${folder || '(root)'}${path ? ` (${path})` : ''}.`,
),
...(outcomeLine ? [outcomeLine] : []),
].join('\n'),
{ template: { ok: true, path, created }, ...writeOutcomeFields(outcome) },
needsAttention(outcome),
);
}
async function handleAsset(
asset: { path: string; content?: string; source?: string },
cwd: string,
url: string | undefined,
deps: WriteDeps,
) {
if (!url) return textResult(hocuspocusNotRunningError(), true);
if ((asset.content === undefined) === (asset.source === undefined)) {
return textResult(
'Error: provide exactly one of `content` (base64) or `source` (local file path) for an asset.',
true,
);
}
let bytes: Buffer;
try {
bytes =
asset.content !== undefined
? Buffer.from(asset.content, 'base64')
: readFileSync(resolvePath(cwd, asset.source as string));
} catch (err) {
return textResult(`Error: could not read asset bytes: ${(err as Error).message}`, true);
}
if (bytes.byteLength === 0) {
return textResult('Error: asset is empty (0 bytes).', true);
}
const { folder, name: fileName } = splitTargetPath(asset.path);
const parentDocName = folder ? `${folder}/${fileName}` : fileName;
const identity = deps.identityRef?.current;
const query = new URLSearchParams();
if (identity?.connectionId) query.set('agentId', identity.connectionId);
if (identity?.displayName) query.set('agentName', identity.displayName);
const qs = query.toString();
const form = new FormData();
form.append('parentDocName', parentDocName);
if (folder) form.append('placement', 'parent-dir' satisfies UploadRequest['placement']);
form.append('file', new Blob([new Uint8Array(bytes)]), fileName);
const uploadPath = `/api/upload${qs ? `?${qs}` : ''}`;
const localApi = deps.localApi;
let localRequest: Parameters<LocalApiDispatch>[2] | null = null;
if (localApi) {
try {
const encoded = new Request('http://localhost/api/upload', { method: 'POST', body: form });
const contentType = encoded.headers.get('content-type') ?? 'multipart/form-data';
localRequest = { body: new Uint8Array(await encoded.arrayBuffer()), contentType };
} catch (err) {
return textResult(`Error: upload request failed: ${(err as Error).message}`, true);
}
}
let status: number;
let bodyText: string;
try {
const local =
localApi && localRequest ? await localApi('POST', uploadPath, localRequest) : null;
if (local !== null) {
status = local.status;
bodyText = local.bodyText;
} else {
const res = await fetch(`${url}${uploadPath}`, {
method: 'POST',
body: form,
signal: AbortSignal.timeout(30_000),
});
status = res.status;
bodyText = await res.text();
}
} catch (err) {
return textResult(`Error: ${serverRequestFailure(err)}`, true);
}
const ok = status >= 200 && status <= 299;
let data: Record<string, unknown> | null;
try {
data = JSON.parse(bodyText) as Record<string, unknown>;
} catch (parseErr) {
const detail = parseErr instanceof Error ? parseErr.message : String(parseErr);
return textResult(
ok
? `Error: Server returned 2xx response with non-JSON body: ${detail}`
: `Error: Server returned HTTP ${status} with non-JSON body: ${detail}`,
true,
);
}
const resBody: { ok: boolean; status: number; data?: Record<string, unknown>; error?: string } =
ok
? { ok: true, status, data: data ?? {} }
: {
ok: false,
status,
error: requestFailureText({
error:
(data && (typeof data.title === 'string' ? data.title : (data.error as string))) ||
`Upload failed (HTTP ${status}).`,
detail: data?.detail,
}),
};
if (!resBody.ok) return textResult(`Error: ${resBody.error}`, true);
const success = UploadAssetSuccessSchema.safeParse(resBody.data);
if (!success.success) {
return textResult(
`Error: Server returned 2xx response with malformed upload body: ${z.prettifyError(success.error)}`,
true,
);
}
const { src, path, deduped } = success.data;
const text = [
`Uploaded asset${path ? ` to ${path}` : ''}${deduped ? ' (deduplicated — identical bytes already present)' : ''}.`,
`Reference it in a doc with: `,
].join('\n');
return textPlusStructured(text, {
asset: {
ok: true,
src,
...(path ? { path } : {}),
...(deduped ? { deduped } : {}),
},
});
}
async function handleSkillWrite(
skill: {
name: string;
scope?: 'project' | 'global';
description?: string;
body?: string;
files?: Array<{ path: string; content: string }>;
},
summary: string | undefined,
url: string | undefined,
deps: WriteDeps,
lockDir: string,
) {
const identity = deps.identityRef?.current;
const hasSkillMd = skill.description !== undefined;
const files = skill.files ?? [];
if (!hasSkillMd && files.length === 0) {
return textResult(
'Error: provide `description` (to author SKILL.md) and/or `files` (to write references/scripts) — a skill write with neither does nothing.',
true,
);
}
if (skill.body !== undefined && !hasSkillMd) {
return textResult(
'Error: `body` updates SKILL.md, so it needs a `description` too. To write a reference, use `files: [{ path: "references/...", content }]` instead.',
true,
);
}
const normalizedFiles: typeof files = [];
for (const f of files) {
const resolved = resolveSkillFilePath(f.path);
if (!resolved.ok) return textResult(`Error: ${resolved.error}`, true);
normalizedFiles.push({ ...f, path: resolved.path });
}
const fileResults: Array<{
path: string;
ok: boolean;
kind?: string;
created?: boolean;
error?: string;
outcome?: string;
saved?: boolean;
nextStep?: string;
landedNote?: string;
}> = [];
let skillMdResult: Awaited<ReturnType<typeof writeSkill>> | null = null;
if (hasSkillMd) {
skillMdResult = await writeSkill(url, {
name: skill.name,
scope: skill.scope,
description: skill.description as string,
body: skill.body,
summary,
identity,
lockDir,
});
const skillMdStructured = (skillMdResult as { structuredContent?: Record<string, unknown> })
.structuredContent;
if (skillMdResult.isError && skillMdStructured?.skill === undefined) return skillMdResult;
}
for (const f of normalizedFiles) {
const r = await writeSkillFile(url, {
name: skill.name,
scope: skill.scope,
path: f.path,
content: f.content,
summary,
identity,
});
const struct = (
r as {
structuredContent?: { skill?: { file?: Record<string, unknown> } } & Record<
string,
unknown
>;
}
).structuredContent;
const fileOutcome = writeOutcomeFields(struct ? writeOutcomeOf(struct) : undefined);
const file = struct?.skill?.file;
if (r.isError && file === undefined) {
fileResults.push({
path: f.path,
ok: false,
error: r.content[0]?.text ?? 'write failed',
...fileOutcome,
});
} else {
const landedNote = landedWithoutSuccess(struct ? writeOutcomeOf(struct) : undefined)
? r.content[0]?.text
: undefined;
fileResults.push({
path: f.path,
ok: true,
...(typeof file?.kind === 'string' ? { kind: file.kind } : {}),
...(typeof file?.created === 'boolean' ? { created: file.created } : {}),
...fileOutcome,
...(landedNote === undefined ? {} : { landedNote }),
});
}
}
const fileOk = fileResults.filter((r) => r.ok).length;
const anyFileFailed = fileResults.some(
(r) =>
!r.ok ||
r.outcome === 'refused' ||
r.outcome === 'both-kept' ||
r.outcome === 'projection-held',
);
const skillMdNeedsAttention = skillMdResult?.isError === true;
const baseStructured =
((skillMdResult as { structuredContent?: Record<string, unknown> } | null)?.structuredContent as
| Record<string, unknown>
| undefined) ?? {};
const baseSkill = (baseStructured.skill as Record<string, unknown> | undefined) ?? { ok: true };
const { text: _skillMdOnlyText, ...baseWithoutText } = baseStructured;
const structured: Record<string, unknown> = {
...baseWithoutText,
skill: {
...baseSkill,
...(files.length > 0
? { files: fileResults.map(({ landedNote: _landedNote, ...entry }) => entry) }
: {}),
},
};
const lines: string[] = [];
if (hasSkillMd && skillMdResult) lines.push(skillMdResult.content[0]?.text ?? '');
if (files.length > 0) {
lines.push(`${fileOk}/${files.length} bundle file(s) written.`);
for (const r of fileResults) {
lines.push(
r.ok
? ` ${r.path} (${r.kind ?? 'file'})${r.landedNote ? `: ${r.landedNote}` : ''}`
: ` Failed ${r.path}: ${r.error}`,
);
}
}
return textPlusStructured(
lines.filter(Boolean).join('\n'),
structured,
anyFileFailed || skillMdNeedsAttention,
);
}
async function handleBatch(
documents: DocSpec[],
cwd: string,
contentDir: string,
url: string,
deps: WriteDeps,
lockDir: string,
autoOpen: boolean,
) {
const results: WriteOneResult[] = [];
for (const spec of documents) {
results.push(await writeOneDoc(spec, cwd, contentDir, url, deps));
}
const docOut = results.map((r) => {
if (!r.ok) {
return {
docName: r.docName,
ok: false as const,
error: r.error,
...writeOutcomeFields(r.outcome),
};
}
const preview = resolvePreviewUrl(r.docName, { lockDir });
const warnings = parseAdvisoryWarnings(r.raw.warnings);
const linksChecked = r.outcome?.outcome !== 'projection-held';
const brokenLinks = linksChecked ? parseBrokenLinks(r.raw.brokenLinks) : undefined;
const brokenLinkSuppression = parseBrokenLinkSuppression(r.raw.brokenLinkSuppression);
return {
docName: r.docName,
ok: true as const,
position: r.position,
...writeOutcomeFields(r.outcome),
...(preview ? { previewUrl: preview.url } : {}),
...(warnings ? { warnings } : {}),
...(r.templateHint ? { templateHint: r.templateHint } : {}),
...(brokenLinks ? { brokenLinks } : {}),
...(brokenLinkSuppression ? { brokenLinkSuppression } : {}),
};
});
const okCount = docOut.filter((d) => d.ok).length;
const allOk = results.every((r) => r.ok && !needsAttention(r.outcome));
const lines = documents.map((spec, i) => {
const r = results[i];
if (!r?.ok) {
const outcomeLine = writeOutcomeLine(r?.outcome);
return `Failed ${spec.path}: ${r?.error ?? 'unknown error'}${outcomeLine ? ` ${outcomeLine}` : ''}`;
}
if (emptyAppendNoOpNote(r.position, spec.content)) {
return `No change to ${spec.path} — empty ${r.position}, document unchanged.`;
}
const d = docOut[i];
const baseParts = [
r.outcome && landedWithoutSuccess(r.outcome)
? landedLead(r.outcome, `Wrote ${spec.path} (${r.position})`)
: r.createdByPosition
? createdByPositionNote(r.docName, r.createdByPosition)
: `Wrote ${spec.path} (${r.position}).`,
];
if (r.outcome?.outcome === 'projection-held' && typeof r.raw.detail === 'string') {
baseParts.push(r.raw.detail);
}
const entryOutcomeLine = r.outcome?.outcome === 'applied' ? null : writeOutcomeLine(r.outcome);
if (entryOutcomeLine) baseParts.push(entryOutcomeLine);
if (d?.ok && d.warnings) {
baseParts.push(...formatAdvisoryBriefs(d.warnings));
}
if (d?.ok && d.brokenLinks) {
const brokenBrief = formatBrokenLinkBrief(d.brokenLinks);
if (brokenBrief) baseParts.push(brokenBrief);
if (d.brokenLinkSuppression) {
baseParts.push(formatBrokenLinkSuppressionBrief(d.brokenLinkSuppression));
}
}
if (r.ok && r.templateHint) {
baseParts.push(
`ℹ ${r.templateHint.length} template${r.templateHint.length === 1 ? '' : 's'} available here (pass \`template\`).`,
);
}
return baseParts.join(' ');
});
const perDocNotes = documents.flatMap((spec, i) => {
const r = results[i];
if (!r?.ok) return [];
const fmNote = frontmatterIgnoredNote(r.position, spec.content);
const notes = [
...(fmNote ? [fmNote] : []),
...(r.frontmatterNote ? [r.frontmatterNote] : []),
...(r.extensionNote ? [r.extensionNote] : []),
];
return notes.map((n) => `${spec.path} — ${n}`);
});
const text = [`${okCount}/${docOut.length} written.`, ...lines, ...perDocNotes].join('\n');
const structured: Record<string, unknown> = { documents: docOut };
const firstOk = results.find((r): r is Extract<WriteOneResult, { ok: true }> => r.ok);
if (firstOk && firstOk.raw.systemSubscriberCount === 0) {
const firstPreview = resolvePreviewUrl(firstOk.docName, { lockDir });
structured.warning = buildPreviewAttachWarning(firstPreview, autoOpen);
}
return textPlusStructured(text, structured, !allOk);
}
async function handleSingleDoc(
spec: DocSpec,
cwd: string,
contentDir: string,
url: string,
deps: WriteDeps,
lockDir: string,
autoOpen: boolean,
) {
const w = await writeOneDoc(spec, cwd, contentDir, url, deps);
if (!w.ok) return failedWriteResult(`Error: ${w.error}`, w.outcome);
const result = w.raw;
const landedOnly = w.outcome !== undefined && landedWithoutSuccess(w.outcome);
const preview = resolvePreviewUrl(w.docName, { lockDir });
const systemSubscriberCount =
typeof result.systemSubscriberCount === 'number' ? result.systemSubscriberCount : undefined;
const noPreviewAnywhere = systemSubscriberCount === 0;
const hints = Array.isArray(result.hints) ? result.hints : undefined;
const summaryResult =
result.summary && typeof result.summary === 'object'
? (result.summary as { value: string; truncatedFrom?: number; hint?: string })
: undefined;
const summaryHint = typeof summaryResult?.hint === 'string' ? summaryResult.hint : undefined;
const advisoryWarnings = parseAdvisoryWarnings(result.warnings);
const brokenLinks = parseBrokenLinks(result.brokenLinks);
const brokenLinkSuppression = parseBrokenLinkSuppression(result.brokenLinkSuppression);
const noOpNote = emptyAppendNoOpNote(w.position, spec.content);
const lines: string[] = [
w.outcome && landedOnly
? landedLead(w.outcome, `Written (${w.position})`)
: w.createdByPosition
? createdByPositionNote(w.docName, w.createdByPosition)
: (noOpNote ??
(w.fromTemplate !== undefined
? `Written successfully (instantiated from template "${w.fromTemplate}").`
: `Written successfully (${w.position}).`)),
];
if (w.outcome?.outcome === 'projection-held' && typeof result.detail === 'string') {
lines.push(result.detail);
}
const fmNote = frontmatterIgnoredNote(w.position, spec.content);
if (fmNote) lines.push(fmNote);
if (w.frontmatterNote) lines.push(w.frontmatterNote);
if (w.extensionNote) lines.push(w.extensionNote);
if (noPreviewAnywhere && !preview) lines.push(startUiTextHint());
if (summaryHint) lines.push(summaryHint);
if (hints) {
for (const hint of hints) {
if (hint.message) lines.push(hint.message);
}
}
if (advisoryWarnings) {
lines.push(...formatAdvisoryLines(advisoryWarnings));
}
lines.push(...formatBrokenLinkLines(brokenLinks));
if (brokenLinkSuppression) lines.push(formatBrokenLinkSuppressionLine(brokenLinkSuppression));
if (w.templateHint) lines.push(formatTemplateHintLine(w.templateHint));
const outcomeLine = w.outcome?.outcome === 'applied' ? null : writeOutcomeLine(w.outcome);
if (outcomeLine) lines.push(outcomeLine);
const text = lines.join('\n');
const document: Record<string, unknown> = {
brokenLinks,
};
if (brokenLinkSuppression) document.brokenLinkSuppression = brokenLinkSuppression;
if (hints) document.hints = hints;
if (summaryResult) document.summary = summaryResult;
if (advisoryWarnings) document.warnings = advisoryWarnings;
if (w.templateHint) document.templateHint = w.templateHint;
const warning = noPreviewAnywhere ? buildPreviewAttachWarning(preview, autoOpen) : undefined;
return textPlusStructured(
text,
{
...nestDocResult(preview, warning, w.outcome?.outcome === 'projection-held' ? {} : document),
...writeOutcomeFields(w.outcome),
},
needsAttention(w.outcome),
);
}
export function register(server: ServerInstance, deps: WriteDeps): void {
const docTargetShape = {
path: z
.string()
.describe(
'Document path. The slashes are the folder it lands in; missing parent folders are created. ' +
'Example: "meetings/2026-06-03-standup". An optional `.md`/`.mdx` suffix selects the file format ' +
'(default `.md`); prefer the `extension` field for that. The docName itself is always extension-less.',
),
content: z
.string()
.optional()
.describe(
'The full Markdown body. C0 controls allow only TAB, LF and CR; remove others or use printable escapes. Mutually exclusive with `template`.',
),
extension: DocExtensionArg.optional(),
template: z
.string()
.min(1)
.optional()
.describe(
"Instantiate the new doc from a folder template (resolved against the parent folder's templates_available, leaf→root walk-up; closest-wins). Mutually exclusive with `content`. Inspect the menu with an `exec` listing of the folder.",
),
frontmatter: FrontmatterArg.optional().describe(
"The doc's OWN frontmatter (YAML). Written inline on create; for an existing doc prefer `edit`.",
),
position: PositionArg.optional(),
};
server.registerTool(
'write',
{
description: DESCRIPTION,
inputSchema: {
document: z
.object(docTargetShape)
.optional()
.describe(
'Create or overwrite a DOCUMENT. Example: { document: { path: "meetings/standup", content: "# Standup\\n..." } }',
),
folder: z
.object({
path: z.string().describe('Folder path. Example: "meetings".'),
frontmatter: FrontmatterArg.optional().describe(
"The folder's OWN frontmatter (open-shape; `title`/`description`/`tags` are the conventional keys). Describes the folder only — does NOT flow into docs inside it.",
),
})
.optional()
.describe(
'Create a NEW folder (errors with 409 if it exists — use `edit` to change an existing folder). Example: { folder: { path: "ideas" } }',
),
template: z
.object({
path: z.string().describe(TEMPLATE_PATH_DESCRIBE),
content: z
.string()
.describe(
`${TEMPLATE_CONTENT_DESCRIBE} C0 controls allow only TAB, LF and CR; remove others or use printable escapes.`,
),
frontmatter: z
.object({
title: z
.string()
.min(1)
.describe('Required — the label shown when an agent picks this template.'),
description: z
.string()
.optional()
.describe('Optional — shown beside the title in the template menu.'),
tags: z.array(z.string()).optional().describe('Optional — tags for the template.'),
})
.describe(
'Template metadata. Only `title` (required), `description`, and `tags` are persisted (unlike open-shape doc/folder frontmatter).',
),
})
.optional()
.describe(
'Create a TEMPLATE (a reusable starting shape for new docs in a folder). Example: { template: { path: "fishing-log/trip-log", content: "# {{date}}\\n", frontmatter: { title: "Trip Log" } } }',
),
skill: z
.object({
name: z.string().describe(SKILL_NAME_DESCRIBE),
description: z
.string()
.optional()
.describe(
`${SKILL_DESCRIPTION_DESCRIBE} Optional when writing ONLY \`files\` into an existing skill (omit to leave SKILL.md untouched).`,
),
body: z
.string()
.optional()
.describe(
`${SKILL_BODY_DESCRIBE} C0 controls allow only TAB, LF and CR; remove others or use printable escapes.`,
),
files: z
.array(
z.object({
path: z
.string()
.describe(
'Skill-relative path, e.g. "references/tiers.md" or "assets/logo.svg". Must stay inside the skill dir.',
),
content: z
.string()
.describe(
'Full text of the bundle file, including any frontmatter. For .md/.mdx paths, C0 controls allow only TAB, LF and CR; remove others or use printable escapes.',
),
}),
)
.optional()
.describe(SKILL_FILES_DESCRIBE),
scope: SkillScopeArg.optional(),
})
.optional()
.describe(
'Create or overwrite an agent SKILL bundle (a NEW skill lands at the project\'s default skill home, e.g. `.agents/skills/<name>/`). SKILL.md is authored via `description`+`body`; bundle files via the `files` array — any skill-relative path that stays inside the skill dir (`references/**` and `scripts/**` are the conventional homes; `assets/` and per-harness dirs are accepted because published skills ship them). Example: { skill: { name: "trip-log", description: "Use when logging a fishing trip.", body: "# Steps\\n...", files: [{ path: "references/gear.md", content: "..." }] } }',
),
asset: z
.object({
path: z
.string()
.describe(
'Asset path incl. extension — the slashes are the folder. Example: "images/diagram.png". A bare file name (no folder) goes to the attachment folder (`content.attachmentFolderPath`; by default the content root). It has no parent document, so a setting that uses `{{filename}}` puts it in the content root.',
),
content: z.string().optional().describe('Base64 of the binary. Use for small files.'),
source: z
.string()
.optional()
.describe('Local filesystem path the server reads. Use for large files.'),
})
.optional()
.describe(
'Upload a binary asset (image/file) via the media route. Exactly one of `content` | `source`.',
),
documents: z
.array(z.object({ ...docTargetShape, summary: summaryArgSchema }))
.min(1)
.optional()
.describe(
'Batch: documents to write in one call. Mutually exclusive with the single targets. Each entry may carry its own `summary`.',
),
summary: summaryArgSchema,
cwd: z.string().optional().describe(ROUTED_CWD_DESCRIPTION),
},
outputSchema: outputSchemaWithText({
...writeOutcomeOutputShape,
document: z
.object({
hints: looseObjectArray.optional().describe('Server-provided write hints, when any.'),
...documentResultBaseShape,
})
.optional()
.describe(
'Single-document write result. Present on every saved single-doc write (absent when the outcome is projection-held, whose links were not checked) — it carries `brokenLinks` (possibly `[]`) plus any `brokenLinkSuppression`/`summary`/`hints`/`warnings`. Read `brokenLinkSuppression` and `warnings` before concluding anything from an empty `brokenLinks`: a suppression means a project policy withheld findings that are not yours to repair; a `link-check-deferred` warning means links were not checked yet.',
),
folder: z
.object({
ok: z.boolean(),
path: z.string(),
frontmatterError: z
.string()
.optional()
.describe(
'Present when the folder was created but its frontmatter write failed — retry only the properties via `edit({ folder: { frontmatter } })`.',
),
})
.optional()
.describe('Folder-create result.'),
template: z
.object({
ok: z.boolean(),
path: z.string(),
created: z
.boolean()
.describe('true if created, false if an existing template updated.'),
})
.optional()
.describe('Template-create result.'),
skill: z
.object({
ok: z.boolean(),
path: z.string().optional(),
created: z
.boolean()
.optional()
.describe('true if created, false if an existing skill was overwritten.'),
files: looseObjectArray
.optional()
.describe('Per-bundle-file results `{ path, kind, created, ok, error? }`.'),
warnings: z
.array(z.string())
.optional()
.describe(
`Non-fatal authoring warnings for the SKILL.md that was written. ${WARNINGS_FIELD_CONTRACT}`,
),
warningCodes: z
.array(z.enum(SKILL_AUTHORING_WARNING_CODES))
.optional()
.describe(`${WARNING_CODES_CONTRACT} ${AUTHORING_WARNING_CODE_GLOSS}`),
})
.optional()
.describe('Skill-create result (SKILL.md and/or bundle files).'),
asset: z
.object({
ok: z.boolean(),
src: z.string().describe('The reference src to embed in a doc.'),
path: z
.string()
.optional()
.describe(
'Content-root-relative path the server reports holding the asset (the existing file when `deduped`). Absent when the server reports none.',
),
deduped: z
.boolean()
.optional()
.describe('true when identical bytes already existed (no new file written).'),
})
.optional()
.describe('Asset-upload result.'),
documents: looseObjectArray
.optional()
.describe(
'Batch write: per-doc result `{ docName, ok, outcome?, saved?, nextStep?, position?, previewUrl?, warnings?, brokenLinks, brokenLinkSuppression?, error? }`, each entry with its own outcome fields (the top-level ones are absent). `brokenLinks` (possibly `[]`) is present on each successful entry whose outcome is not projection-held (the links of a held entry were not checked, and its text carries the server detail instead), same as a single-doc write — and, same as a single-doc write, an empty list means every link resolves only on entries carrying no `brokenLinkSuppression` and no `link-check-deferred` warning (links not checked yet because the server is still starting or busy).',
),
previewUrl: previewUrlOutputField.optional(),
previewUrlSource: previewUrlSourceField,
warning: previewAttachWarningField,
}),
},
async (args: {
document?: Omit<DocSpec, 'summary'>;
folder?: { path: string; frontmatter?: FrontmatterPatch };
template?: {
path: string;
content: string;
frontmatter: { title: string } & Record<string, unknown>;
};
skill?: {
name: string;
scope?: 'project' | 'global';
description?: string;
body?: string;
files?: Array<{ path: string; content: string }>;
};
asset?: { path: string; content?: string; source?: string };
documents?: DocSpec[];
summary?: string;
cwd?: string;
}) => {
const context = await resolveProjectServerContext(
deps.resolveCwd,
deps.config,
deps.serverUrl,
args.cwd,
);
if (!context.ok) return textResult(`Error: ${context.error}`, true);
const { cwd, config, url } = context;
const lockDir = resolveLockDir(cwd);
const contentDir = resolveContentDir(config, cwd);
const autoOpen = config.appearance.preview.autoOpen;
if (args.documents !== undefined) {
const teaching = exactlyOneTargetError(args as Record<string, unknown>, [
'document',
'folder',
'template',
'skill',
'asset',
'documents',
]);
if (teaching) return textResult(`Error: ${teaching}`, true);
if (!url) return textResult(hocuspocusNotRunningError(), true);
return handleBatch(args.documents, cwd, contentDir, url, deps, lockDir, autoOpen);
}
const teaching = exactlyOneTargetError(args as Record<string, unknown>, [
'document',
'folder',
'template',
'skill',
'asset',
]);
if (teaching) return textResult(`Error: ${teaching}`, true);
if (args.document !== undefined) {
if (!url) return textResult(hocuspocusNotRunningError(), true);
return handleSingleDoc(
{ ...args.document, summary: args.summary },
cwd,
contentDir,
url,
deps,
lockDir,
autoOpen,
);
}
if (args.folder !== undefined) return handleFolder(args.folder, args.summary, url, deps);
if (args.template !== undefined)
return handleTemplate(args.template, args.summary, url, deps);
if (args.skill !== undefined)
return handleSkillWrite(args.skill, args.summary, url, deps, lockDir);
return handleAsset(args.asset as NonNullable<typeof args.asset>, cwd, url, deps);
},
);
}