Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Accept non-ASCII names, paths, links and titles (PRD-9410) (#6413)

Andrew Mikofalvyc1f5630fcf26
diff --git a/.changeset/unicode-names-links-titles.md b/.changeset/unicode-names-links-titles.md
new file mode 100644
index 000000000..6a8658a84
--- /dev/null
+++ b/.changeset/unicode-names-links-titles.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Template names, doc paths in agent chat, typed or pasted links with non-Latin domains, and agent names in thread titles now work in any script, and shortened titles and previews no longer cut an emoji or character in half.
diff --git a/docs/content/advanced/folders-and-templates.mdx b/docs/content/advanced/folders-and-templates.mdx
index a352641fb..e1dd1d060 100644
--- a/docs/content/advanced/folders-and-templates.mdx
+++ b/docs/content/advanced/folders-and-templates.mdx
@@ -39,7 +39,7 @@ There are two places to create a template, depending on how widely you want it t
Either way, the **New template** dialog asks for:
- **Title**: the human-readable name, shown wherever a template is picked. Required.
-- **Filename**: derived automatically from the title (`Blog post` → `blog-post.md`). Click **Edit** to set it yourself. The filename is the id agents use.
+- **Filename**: derived automatically from the title (`Blog post` → `blog-post.md`, `議事録` → `議事録.md`). Click **Edit** to set it yourself. It may use letters and digits in any script, `_` and `-`, but no spaces, dots, slashes or invisible characters. The filename is the id agents use.
- **Description**: an optional one-line summary shown under the title.
- **Type** and **Default properties**: the starting properties the new document gets (below).
- **Starter content**: the markdown that becomes the new document's content.
diff --git a/packages/app/src/comments/comment-chips.tsx b/packages/app/src/comments/comment-chips.tsx
index a90554c38..d1f1fa198 100644
--- a/packages/app/src/comments/comment-chips.tsx
+++ b/packages/app/src/comments/comment-chips.tsx
@@ -1,5 +1,6 @@
// oxlint-disable ok/no-physical-direction-utility -- pre-rule backlog — physical margin/padding/inset utilities predate the rule; drain by swapping ml/mr → ms/me, pl/pr → ps/pe, left/right → start/end, then deleting this line. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-physical-direction-utility
+import { graphemePrefix, graphemeSuffix } from '@inkeep/open-knowledge-core/utils/grapheme-clip';
import { Plural, Trans, useLingui } from '@lingui/react/macro';
import { MessageSquare, X } from 'lucide-react';
import { Button } from '@/components/ui/button';
@@ -172,12 +173,12 @@ const CONTEXT_CHARS = 48;
function trimTail(text: string): string {
const flat = text.replace(/\s+/g, ' ').trimStart();
- return flat.length > CONTEXT_CHARS ? `…${flat.slice(-CONTEXT_CHARS)}` : flat;
+ return flat.length > CONTEXT_CHARS ? `…${graphemeSuffix(flat, CONTEXT_CHARS)}` : flat;
}
function trimHead(text: string): string {
const flat = text.replace(/\s+/g, ' ').trimEnd();
- return flat.length > CONTEXT_CHARS ? `${flat.slice(0, CONTEXT_CHARS)}…` : flat;
+ return flat.length > CONTEXT_CHARS ? `${graphemePrefix(flat, CONTEXT_CHARS)}…` : flat;
}
function locatingNote(item: CommentBatchItem): string | null {
diff --git a/packages/app/src/comments/dispatch-batch.test.ts b/packages/app/src/comments/dispatch-batch.test.ts
index 40bd81269..3478d942c 100644
--- a/packages/app/src/comments/dispatch-batch.test.ts
+++ b/packages/app/src/comments/dispatch-batch.test.ts
@@ -366,3 +366,23 @@ describe('the composed instruction for a property comment', () => {
expect(out).toContain(' > Whisk the peanut sauce');
});
});
+
+describe('composeCommentBatchInstruction — locating context keeps characters whole', () => {
+ test('context cut at an emoji drops the whole emoji on either side', () => {
+ const prompt = composeCommentBatchInstruction(
+ [
+ {
+ docName: 'notes/one',
+ body: 'fix this',
+ quote: 'repeated',
+ anchorLost: false,
+ repeats: true,
+ prefix: `\u{1F600}${'a'.repeat(47)}`,
+ suffix: `${'b'.repeat(47)}\u{1F600}`,
+ },
+ ],
+ '',
+ );
+ expect(prompt).toContain(`between "…${'a'.repeat(47)}" and "${'b'.repeat(47)}…"`);
+ });
+});
diff --git a/packages/app/src/components/TemplateForm.dom.test.tsx b/packages/app/src/components/TemplateForm.dom.test.tsx
index 87927eee6..10991fd49 100644
--- a/packages/app/src/components/TemplateForm.dom.test.tsx
+++ b/packages/app/src/components/TemplateForm.dom.test.tsx
@@ -79,17 +79,32 @@ describe('slugifyTemplateName', () => {
expect(slugifyTemplateName('blog-post')).toBe('blog-post');
});
+ test('keeps letters and digits from any script', () => {
+ expect(slugifyTemplateName('議事録')).toBe('議事録');
+ expect(slugifyTemplateName('Notas de reunión')).toBe('notas-de-reunión');
+ expect(slugifyTemplateName('Заметки 2')).toBe('заметки-2');
+ });
+
+ test('composes decomposed accents and drops invisible characters', () => {
+ expect(slugifyTemplateName('Cafe\u0301')).toBe('café');
+ expect(slugifyTemplateName('a\u200bb\u3164c')).toBe('a-b-c');
+ });
+
test('returns empty when the name has no alphanumeric content', () => {
expect(slugifyTemplateName('!!!')).toBe('');
});
});
-function CreateFormHarness() {
+function CreateFormHarness({
+ existingNames = new Set<string>(),
+}: {
+ existingNames?: ReadonlySet<string>;
+}) {
const form = useTemplateForm({
mode: 'create',
folderPath: '',
initial: { name: '', title: '', description: '', body: '' },
- existingNames: new Set(),
+ existingNames,
onCommitted: () => {},
});
return <TemplateFormFields form={form} />;
@@ -107,6 +122,31 @@ describe('TemplateFormFields — create mode', () => {
expect(screen.getByText('my-release-notes.md')).toBeDefined();
});
+ test('a name in a non-Latin script derives a valid filename', async () => {
+ const user = userEvent.setup();
+ render(<CreateFormHarness />);
+ await user.type(screen.getByTestId('template-name-input'), '議事録');
+ await user.tab();
+ expect(screen.getByText('議事録.md')).toBeDefined();
+ expect(screen.queryByText(/Use letters, digits/)).toBeNull();
+ });
+
+ test('a name with no letters or digits shows the filename rule once blurred', async () => {
+ const user = userEvent.setup();
+ render(<CreateFormHarness />);
+ await user.type(screen.getByTestId('template-name-input'), '!!!');
+ await user.tab();
+ expect(screen.getByText(/Use letters, digits/)).toBeDefined();
+ });
+
+ test('a decomposed name derives the composed filename and finds the existing template', async () => {
+ const user = userEvent.setup();
+ render(<CreateFormHarness existingNames={new Set(['café'])} />);
+ await user.type(screen.getByTestId('template-name-input'), 'Cafe\u{0301}');
+ await user.tab();
+ expect(screen.getByText(/already exists here/)).toBeDefined();
+ });
+
test('shows the required-name error only after the field is blurred empty', async () => {
const user = userEvent.setup();
render(<CreateFormHarness />);
diff --git a/packages/app/src/components/TemplateForm.rename.dom.test.tsx b/packages/app/src/components/TemplateForm.rename.dom.test.tsx
new file mode 100644
index 000000000..f7cc041dc
--- /dev/null
+++ b/packages/app/src/components/TemplateForm.rename.dom.test.tsx
@@ -0,0 +1,57 @@
+import { act, renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const api = vi.hoisted(() => ({
+ saveTemplate: vi.fn(async (_input: { name: string }) => ({ ok: true as const, warnings: [] })),
+ moveTemplate: vi.fn(async (_input: { toName: string }) => ({ ok: true as const })),
+}));
+
+vi.mock('@/lib/folder-config-api', () => api);
+
+const { useTemplateForm } = await import('./TemplateForm');
+
+function renderEditForm(name: string) {
+ return renderHook(() =>
+ useTemplateForm({
+ mode: 'edit',
+ folderPath: 'notes',
+ scope: 'local',
+ initial: { name, title: 'Menu', description: '', body: '# Menu\n' },
+ onCommitted: () => {},
+ }),
+ );
+}
+
+describe('useTemplateForm edit save', () => {
+ beforeEach(() => {
+ api.saveTemplate.mockClear();
+ api.moveTemplate.mockClear();
+ });
+
+ test('a title-only save of a decomposed template saves under the stored name', async () => {
+ const { result } = renderEditForm('cafe\u{0301}');
+ act(() => result.current.setTitle('Specials'));
+ await act(() => result.current.submit());
+ expect(api.moveTemplate).not.toHaveBeenCalled();
+ expect(api.saveTemplate).toHaveBeenCalledWith(
+ expect.objectContaining({ name: 'cafe\u{0301}' }),
+ );
+ });
+
+ test('re-entering a composed name in decomposed form saves instead of moving', async () => {
+ const { result } = renderEditForm('caf\u{00E9}');
+ act(() => result.current.setSlug('cafe\u{0301}'));
+ await act(() => result.current.submit());
+ expect(api.moveTemplate).not.toHaveBeenCalled();
+ expect(api.saveTemplate).toHaveBeenCalledWith(expect.objectContaining({ name: 'caf\u{00E9}' }));
+ });
+
+ test('a new name moves the template to its composed spelling', async () => {
+ const { result } = renderEditForm('meeting');
+ act(() => result.current.setSlug('cafe\u{0301}'));
+ await act(() => result.current.submit());
+ expect(api.moveTemplate).toHaveBeenCalledWith(
+ expect.objectContaining({ fromName: 'meeting', toName: 'caf\u{00E9}' }),
+ );
+ });
+});
diff --git a/packages/app/src/components/TemplateForm.tsx b/packages/app/src/components/TemplateForm.tsx
index 991c563ad..7c52b166e 100644
--- a/packages/app/src/components/TemplateForm.tsx
+++ b/packages/app/src/components/TemplateForm.tsx
@@ -2,6 +2,11 @@ import {
stripFrontmatter,
unwrapFrontmatterFences,
} from '@inkeep/open-knowledge-core/extensions/frontmatter';
+import {
+ canonicalTemplateName,
+ TEMPLATE_NAME_REGEX,
+ templateRenameTarget,
+} from '@inkeep/open-knowledge-core/schemas/api';
import { t } from '@lingui/core/macro';
import { Trans, useLingui } from '@lingui/react/macro';
import { X } from 'lucide-react';
@@ -14,12 +19,10 @@ import { Input } from '@/components/ui/input';
import { Textarea } from '@/components/ui/textarea';
import { moveTemplate, saveTemplate } from '@/lib/folder-config-api';
-const NAME_RE = /^[A-Za-z0-9_-]+$/;
-
export function slugifyTemplateName(name: string): string {
- return name
+ return canonicalTemplateName(name)
.toLowerCase()
- .replace(/[^a-z0-9]+/g, '-')
+ .replace(/(?:[^\p{L}\p{M}\p{N}]|\p{DI})+/gu, '-')
.replace(/^-+|-+$/g, '');
}
@@ -191,9 +194,10 @@ export function useTemplateForm({
const slugEditable = mode === 'create' || canRename;
const trimmedTitle = title.trim();
- const trimmedSlug = slug.trim();
+ const trimmedSlug = canonicalTemplateName(slug.trim());
const titleInvalid = trimmedTitle === '';
- const slugInvalid = slugEditable && (trimmedSlug === '' || !NAME_RE.test(trimmedSlug));
+ const slugInvalid =
+ slugEditable && (trimmedSlug === '' || !TEMPLATE_NAME_REGEX.test(trimmedSlug));
const slugShadows =
mode === 'create' && !slugInvalid && (existingNames?.has(trimmedSlug) ?? false);
const canSubmit = !saving && !titleInvalid && !slugInvalid;
@@ -206,7 +210,7 @@ export function useTemplateForm({
setSaving(true);
const frontmatter = buildTemplateFrontmatter({ title, description });
const composedBody = composeDocBody({ type, properties, markdown: body });
- const renaming = canRename && trimmedSlug !== initial.name;
+ const renaming = canRename && templateRenameTarget(initial.name, slug) !== null;
const result = renaming
? await moveTemplate({
fromFolder: folderPath,
diff --git a/packages/app/src/components/TemplateProperties.dom.test.tsx b/packages/app/src/components/TemplateProperties.dom.test.tsx
index 3cb201b1e..4ce18132b 100644
--- a/packages/app/src/components/TemplateProperties.dom.test.tsx
+++ b/packages/app/src/components/TemplateProperties.dom.test.tsx
@@ -55,4 +55,48 @@ describe('TemplateProperties (CRDT)', () => {
expect(onRename).toHaveBeenCalledWith('standup');
expect(ytext.toString()).toContain('# Agenda');
});
+
+ test('blurring an unedited decomposed name does not fire onRename', () => {
+ const { provider } = makeProvider(SOURCE);
+ const onRename = vi.fn((_next: string) => {});
+ render(
+ <TemplateProperties
+ provider={provider}
+ name={'cafe\u{0301}'}
+ folder="notes"
+ onRename={onRename}
+ />,
+ );
+ fireEvent.blur(screen.getByTestId('template-name-input'));
+ expect(onRename).not.toHaveBeenCalled();
+ });
+
+ test('re-entering a composed name in decomposed form does not fire onRename', () => {
+ const { provider } = makeProvider(SOURCE);
+ const onRename = vi.fn((_next: string) => {});
+ render(
+ <TemplateProperties
+ provider={provider}
+ name={'caf\u{00E9}'}
+ folder="notes"
+ onRename={onRename}
+ />,
+ );
+ const nameInput = screen.getByTestId('template-name-input');
+ fireEvent.change(nameInput, { target: { value: 'cafe\u{0301}' } });
+ fireEvent.blur(nameInput);
+ expect(onRename).not.toHaveBeenCalled();
+ });
+
+ test('renaming to a decomposed name sends its composed spelling', () => {
+ const { provider } = makeProvider(SOURCE);
+ const onRename = vi.fn((_next: string) => {});
+ render(
+ <TemplateProperties provider={provider} name="meeting" folder="notes" onRename={onRename} />,
+ );
+ const nameInput = screen.getByTestId('template-name-input');
+ fireEvent.change(nameInput, { target: { value: 'cafe\u{0301}' } });
+ fireEvent.blur(nameInput);
+ expect(onRename).toHaveBeenCalledWith('caf\u{00E9}');
+ });
});
diff --git a/packages/app/src/components/TemplateProperties.tsx b/packages/app/src/components/TemplateProperties.tsx
index 42d70b7a4..bea853ad0 100644
--- a/packages/app/src/components/TemplateProperties.tsx
+++ b/packages/app/src/components/TemplateProperties.tsx
@@ -1,5 +1,9 @@
import type { HocuspocusProvider } from '@hocuspocus/provider';
-import { TEMPLATE_NAME_REGEX } from '@inkeep/open-knowledge-core/schemas/api';
+import {
+ canonicalTemplateName,
+ TEMPLATE_NAME_REGEX,
+ templateRenameTarget,
+} from '@inkeep/open-knowledge-core/schemas/api';
import { Trans, useLingui } from '@lingui/react/macro';
import { FolderGit2, Type } from 'lucide-react';
import { useEffect, useId, useState } from 'react';
@@ -33,12 +37,13 @@ export function TemplateProperties({
const [nameDraft, setNameDraft] = useState(name);
useEffect(() => setNameDraft(name), [name]);
- const trimmedName = nameDraft.trim();
+ const trimmedName = canonicalTemplateName(nameDraft.trim());
const nameInvalid = trimmedName !== '' && !TEMPLATE_NAME_REGEX.test(trimmedName);
function commitName() {
if (!onRename) return;
- if (nameInvalid || trimmedName === '' || trimmedName === name) return;
- onRename(trimmedName);
+ if (nameInvalid || trimmedName === '') return;
+ const target = templateRenameTarget(name, nameDraft);
+ if (target !== null) onRename(target);
}
const showNameError = nameInvalid || Boolean(nameError);
diff --git a/packages/app/src/components/acp/doc-path-links.test.ts b/packages/app/src/components/acp/doc-path-links.test.ts
index 04eea811e..b9453d555 100644
--- a/packages/app/src/components/acp/doc-path-links.test.ts
+++ b/packages/app/src/components/acp/doc-path-links.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, test } from 'vitest';
+import { hashFromDocName } from '@/lib/doc-hash';
import type { Workspace } from '@/lib/workspace-paths';
import { buildDocPathResolver, remarkDocPathLinks, setDocPathResolver } from './doc-path-links';
@@ -633,3 +634,52 @@ describe('remarkDocPathLinks', () => {
expect(kids[2]?.url).toBe('#/reports/foo/REPORT');
});
});
+
+describe('remarkDocPathLinks — paths in any script', () => {
+ const resolveUnicode = buildDocPathResolver({
+ workspace,
+ pages: new Set(['notes/会議', 'docs/日報', 'café', 'notes/plain']),
+ });
+
+ function linkify(value: string): MdastNode[] {
+ const tree = makeTree([{ type: 'paragraph', children: [{ type: 'text', value }] }]);
+ setDocPathResolver(resolveUnicode);
+ remarkDocPathLinks()()(tree);
+ return tree.children?.[0]?.children ?? [];
+ }
+
+ test('links a path whose segments are not ASCII', () => {
+ const kids = linkify('Updated notes/会議.md just now');
+ expect(kids).toHaveLength(3);
+ expect(kids[0]).toEqual({ type: 'text', value: 'Updated ' });
+ expect(kids[1]).toMatchObject({
+ type: 'link',
+ url: hashFromDocName('notes/会議'),
+ children: [{ type: 'text', value: 'notes/会議.md' }],
+ });
+ expect(kids[2]).toEqual({ type: 'text', value: ' just now' });
+ });
+
+ test('keeps a non-ASCII heading anchor on the link', () => {
+ const kids = linkify('See docs/日報.md#概要 for the summary');
+ expect(kids[1]).toMatchObject({
+ type: 'link',
+ url: hashFromDocName('docs/日報', '概要'),
+ children: [{ type: 'text', value: 'docs/日報.md#概要' }],
+ });
+ });
+
+ test('links an accented file name', () => {
+ const kids = linkify('Wrote café.md.');
+ expect(kids[1]).toMatchObject({
+ type: 'link',
+ url: hashFromDocName('café'),
+ children: [{ type: 'text', value: 'café.md' }],
+ });
+ });
+
+ test('does not link a path glued to a following letter', () => {
+ expect(linkify('notes/plain.mdé')).toEqual([{ type: 'text', value: 'notes/plain.mdé' }]);
+ expect(linkify('xnotes/会議.md')).toEqual([{ type: 'text', value: 'xnotes/会議.md' }]);
+ });
+});
diff --git a/packages/app/src/components/acp/doc-path-links.ts b/packages/app/src/components/acp/doc-path-links.ts
index ae79cc78b..7647e7214 100644
--- a/packages/app/src/components/acp/doc-path-links.ts
+++ b/packages/app/src/components/acp/doc-path-links.ts
@@ -9,7 +9,13 @@ import type { Workspace } from '@/lib/workspace-paths';
export type DocPathResolver = (candidate: string) => string | null;
-const DOC_PATH_REGEX = /(?<![A-Za-z0-9_./@-])[A-Za-z0-9_./@-]+\.(?:md|mdx)\b(?:#[A-Za-z0-9_-]+)?/g;
+const PATH_CHAR = String.raw`(?:(?!\p{DI})[\p{L}\p{M}\p{N}_./@-])`;
+const ANCHOR_CHAR = String.raw`(?:(?!\p{DI})[\p{L}\p{M}\p{N}_-])`;
+const WORD_CHAR = String.raw`[\p{L}\p{M}\p{N}_]`;
+const DOC_PATH_REGEX = new RegExp(
+ `(?<!${PATH_CHAR})${PATH_CHAR}+\\.(?:md|mdx)(?!${WORD_CHAR})(?:#${ANCHOR_CHAR}+)?`,
+ 'gu',
+);
const LEADING_DOT_SEGMENTS_RE = /^(?:\.[\\/])+/;
export interface BuildDocPathResolverInput {
diff --git a/packages/app/src/editor/gfm-link-detector.test.ts b/packages/app/src/editor/gfm-link-detector.test.ts
index 3554b7286..99971ce65 100644
--- a/packages/app/src/editor/gfm-link-detector.test.ts
+++ b/packages/app/src/editor/gfm-link-detector.test.ts
@@ -69,6 +69,22 @@ const MATRIX: Array<{ token: string; expected: GfmLinkToken | null }> = [
token: 'www.a_b.example.com',
expected: { href: 'http://www.a_b.example.com', text: 'www.a_b.example.com' },
},
+ {
+ token: 'https://例え.jp',
+ expected: { href: 'https://例え.jp', text: 'https://例え.jp' },
+ },
+ {
+ token: 'https://bücher.de/straße',
+ expected: { href: 'https://bücher.de/straße', text: 'https://bücher.de/straße' },
+ },
+ {
+ token: 'www.例え.jp',
+ expected: { href: 'http://www.例え.jp', text: 'www.例え.jp' },
+ },
+ {
+ token: 'https://пример.рф.',
+ expected: { href: 'https://пример.рф', text: 'https://пример.рф' },
+ },
];
describe('detectGfmLinkToken — acceptance matrix', () => {
@@ -88,6 +104,8 @@ describe('detectGfmLinkToken — parity with MarkdownManager.parse', () => {
'ftp://files.example.com',
'https://en.wikipedia.org/wiki/Foo_(bar)',
+ 'https://ab\u200Ccd.example',
+ 'https://ab\u200Ccd.ex\u200Cample',
];
for (const token of parityTokens) {
test(`agrees with the pipeline for ${token}`, () => {
diff --git a/packages/app/src/editor/gfm-link-detector.ts b/packages/app/src/editor/gfm-link-detector.ts
index 0a0226a40..abfbf27d1 100644
--- a/packages/app/src/editor/gfm-link-detector.ts
+++ b/packages/app/src/editor/gfm-link-detector.ts
@@ -5,9 +5,10 @@ export type GfmLinkToken = {
text: string;
};
-const URL_HEAD = /^(https?:\/\/|www(?=\.))([-.\w]+)([^ \t\r\n]*)/i;
+const URL_HEAD = /^(https?:\/\/|www(?=\.))((?:[-.\w]|[^\s\p{P}\p{S}\p{Cc}])+)([^ \t\r\n]*)/iu;
const EMAIL_HEAD = /^([-.\w+]+)@([-\w]+(?:\.[-\w]+)+)/;
const EMAIL_LABEL_BAD_TAIL = /[-\d_]$/;
+const DOMAIN_LABEL_ALNUM = /[\p{L}\p{N}]/u;
const ALLOWED_SCHEME_PREFIXES = SAFE_URL_SCHEMES.map((scheme) => `${scheme}:`);
@@ -28,8 +29,8 @@ function hasCorrectDomainLabels(domain: string): boolean {
const parts = domain.split('.');
const last = parts[parts.length - 1];
const penultimate = parts[parts.length - 2];
- if (last && (/_/.test(last) || !/[a-zA-Z\d]/.test(last))) return false;
- if (penultimate && (/_/.test(penultimate) || !/[a-zA-Z\d]/.test(penultimate))) return false;
+ if (last && (/_/.test(last) || !DOMAIN_LABEL_ALNUM.test(last))) return false;
+ if (penultimate && (/_/.test(penultimate) || !DOMAIN_LABEL_ALNUM.test(penultimate))) return false;
return true;
}
diff --git a/packages/app/src/editor/link-preview/doc-excerpt.test.ts b/packages/app/src/editor/link-preview/doc-excerpt.test.ts
index 4921741a7..09c4a8d84 100644
--- a/packages/app/src/editor/link-preview/doc-excerpt.test.ts
+++ b/packages/app/src/editor/link-preview/doc-excerpt.test.ts
@@ -131,3 +131,15 @@ describe('extractDocExcerpt', () => {
expect(excerpt).toContain('handle_document_read');
});
});
+
+describe('extractDocExcerpt — truncation keeps characters whole', () => {
+ test('an excerpt cut at an emoji drops the whole emoji', () => {
+ expect(extractDocExcerpt(`${'a'.repeat(9)}\u{1F600}bbb`, { maxChars: 10 })).toBe(
+ `${'a'.repeat(9)}…`,
+ );
+ });
+
+ test('an excerpt cut at a rare Han character drops the whole character', () => {
+ expect(extractDocExcerpt('會議\u{20BB7}記錄', { maxChars: 3 })).toBe('會議…');
+ });
+});
diff --git a/packages/app/src/editor/link-preview/doc-excerpt.ts b/packages/app/src/editor/link-preview/doc-excerpt.ts
index ed697280b..c8d53bafb 100644
--- a/packages/app/src/editor/link-preview/doc-excerpt.ts
+++ b/packages/app/src/editor/link-preview/doc-excerpt.ts
@@ -1,5 +1,6 @@
import { stripFrontmatter } from '@inkeep/open-knowledge-core/extensions/frontmatter';
import { createCodeFenceTracker } from '@inkeep/open-knowledge-core/utils/code-fence-tracker';
+import { graphemePrefix } from '@inkeep/open-knowledge-core/utils/grapheme-clip';
import { getHeadingSlug, toWikiLinkSlug } from '@inkeep/open-knowledge-core/utils/slug';
export interface DocExcerptOptions {
@@ -28,7 +29,7 @@ export function extractDocExcerpt(markdown: string, options: DocExcerptOptions =
const joined = collected.join(' ').replace(/\s+/g, ' ').trim();
if (joined.length <= maxChars) return joined;
- return `${joined.slice(0, maxChars).trimEnd()}…`;
+ return `${graphemePrefix(joined, maxChars).trimEnd()}…`;
}
function stripCarriageReturn(line: string): string {
diff --git a/packages/app/src/lib/acp/tool-call-display.test.ts b/packages/app/src/lib/acp/tool-call-display.test.ts
index d40168268..e78fae21b 100644
--- a/packages/app/src/lib/acp/tool-call-display.test.ts
+++ b/packages/app/src/lib/acp/tool-call-display.test.ts
@@ -384,6 +384,23 @@ describe('describeToolCall — everything that is not an OK tool', () => {
expect(display.preview).not.toContain('second line');
});
+ test('a long preview cut at an emoji drops the whole emoji', () => {
+ const command = `${'x'.repeat(59)}\u{1F600}${'y'.repeat(10)}`;
+ const display = describeToolCall({ title: 'bash', toolKind: 'execute', rawInput: { command } });
+ expect(display.preview).toBe(`${'x'.repeat(59)}…`);
+ });
+
+ test('a long inline argument cut at an emoji drops the whole emoji', () => {
+ const query = `${'q'.repeat(118)}\u{1F600}${'r'.repeat(10)}`;
+ expect(
+ describeToolCall({
+ title: 'mcp__open-knowledge__search',
+ toolKind: 'other',
+ rawInput: { cwd: '/repo', query },
+ }).text,
+ ).toBe(`OpenKnowledge searched for ${'q'.repeat(118)}…`);
+ });
+
test('a long command that is already the label does not get repeated beside it', () => {
const command =
'ps -p 51625 -o pid,command | tail -n +1; echo "----"; curl -s localhost:3000/health';
diff --git a/packages/app/src/lib/acp/tool-call-display.ts b/packages/app/src/lib/acp/tool-call-display.ts
index ef4b16448..7aea84836 100644
--- a/packages/app/src/lib/acp/tool-call-display.ts
+++ b/packages/app/src/lib/acp/tool-call-display.ts
@@ -5,6 +5,7 @@ import {
stringField,
unwrapMcpInput,
} from '@inkeep/open-knowledge-core/acp/tool-call-input';
+import { graphemePrefix } from '@inkeep/open-knowledge-core/utils/grapheme-clip';
import { plural, t } from '@lingui/core/macro';
export type ToolCallGlyph =
@@ -55,7 +56,7 @@ function argumentValue(rawInput: unknown): string | undefined {
}
function ellipsize(line: string): string {
- return line.length > PREVIEW_LIMIT ? `${line.slice(0, PREVIEW_LIMIT).trimEnd()}…` : line;
+ return line.length > PREVIEW_LIMIT ? `${graphemePrefix(line, PREVIEW_LIMIT).trimEnd()}…` : line;
}
const MCP_TITLE = /^mcp([^a-zA-Z0-9]+)([a-zA-Z0-9][a-zA-Z0-9_-]*?)\1([a-zA-Z0-9][a-zA-Z0-9_-]*)$/;
@@ -106,7 +107,9 @@ function inlineText(value: unknown): string | null {
if (typeof value !== 'string') return null;
const collapsed = value.replace(/\s+/g, ' ').trim();
if (collapsed === '') return null;
- return collapsed.length > INLINE_MAX ? `${collapsed.slice(0, INLINE_MAX - 1)}…` : collapsed;
+ return collapsed.length > INLINE_MAX
+ ? `${graphemePrefix(collapsed, INLINE_MAX - 1)}…`
+ : collapsed;
}
function openKnowledgeDisplay(tool: string, args: Record<string, unknown>): ToolCallDisplay {
diff --git a/packages/app/tests/integration/create-page.test.ts b/packages/app/tests/integration/create-page.test.ts
index 9105cebba..79072b6c9 100644
--- a/packages/app/tests/integration/create-page.test.ts
+++ b/packages/app/tests/integration/create-page.test.ts
@@ -194,6 +194,6 @@ describe('/api/create-page — template seeding', () => {
const { status, body } = await createPageWithTemplate('bad-tpl-name.md', 'bad name!');
expect(status).toBe(400);
expect(body.type).toBe('urn:ok:error:invalid-request');
- expect(body.title).toMatch(/must match/i);
+ expect(body.title).toMatch(/letters and digits/i);
});
});
diff --git a/packages/app/tests/integration/template-delete-move-import.test.ts b/packages/app/tests/integration/template-delete-move-import.test.ts
index 656374577..ca7d63396 100644
--- a/packages/app/tests/integration/template-delete-move-import.test.ts
+++ b/packages/app/tests/integration/template-delete-move-import.test.ts
@@ -1,5 +1,5 @@
import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { HocuspocusProvider } from '@hocuspocus/provider';
import { parseAuthRejectionWire } from '@inkeep/open-knowledge-server';
@@ -319,4 +319,75 @@ describe('template delete/move/import — content-doc lifecycle', () => {
},
HARNESS_BOOT_TIMEOUT_MS + 30_000,
);
+
+ test(
+ 'import without a name keeps non-Latin letters of the source file name',
+ async () => {
+ const rig = server;
+ const suffix = randomUUID().slice(0, 8);
+ const sourceName = `会議メモ-${suffix}`;
+ await writeSource(rig.port, rig.contentDir, sourceName, '# 会議\n\nBody.\n');
+ const folder = `unicode-imp-${suffix}`;
+ const imp = await importTemplate(rig.port, { sourcePath: sourceName, targetFolder: folder });
+ expect(imp.status).toBe(200);
+ expect(existsSync(join(rig.contentDir, folder, '.ok', 'templates', `${sourceName}.md`))).toBe(
+ true,
+ );
+ },
+ HARNESS_BOOT_TIMEOUT_MS + 30_000,
+ );
+
+ test(
+ 'import without a name derives the composed spelling from a decomposed file name',
+ async () => {
+ const rig = server;
+ const suffix = randomUUID().slice(0, 8);
+ const sourceName = `cafe\u{0301}-${suffix}`;
+ await writeSource(rig.port, rig.contentDir, sourceName, '# Café\n\nBody.\n');
+ const folder = `nfc-imp-${suffix}`;
+ const imp = await importTemplate(rig.port, { sourcePath: sourceName, targetFolder: folder });
+ expect(imp.status).toBe(200);
+ expect(((await imp.json()) as { path?: string }).path).toBe(
+ `${folder}/.ok/templates/café-${suffix}.md`,
+ );
+ },
+ HARNESS_BOOT_TIMEOUT_MS + 30_000,
+ );
+
+ test(
+ 'a decomposed template name is stored, read, moved and deleted in the spelling given',
+ async () => {
+ const rig = server;
+ const suffix = randomUUID().slice(0, 8);
+ const folder = `nfd-routes-${suffix}`;
+ const fromName = `cafe\u{0301}-${suffix}`;
+ const toName = `cre\u{0300}me-${suffix}`;
+ const templatesDir = join(rig.contentDir, folder, '.ok', 'templates');
+
+ const put = await putTemplate(rig.port, folder, fromName, '# Menu\n', { title: 'Menu' });
+ expect(put.status).toBe(200);
+ await pollUntil(() => existsSync(join(templatesDir, `${fromName}.md`)), 8000);
+ expect(readdirSync(templatesDir)).toEqual([`${fromName}.md`]);
+
+ const qs = new URLSearchParams({ folder, name: fromName });
+ const get = await fetch(`http://127.0.0.1:${rig.port}/api/template?${qs.toString()}`);
+ expect(get.status).toBe(200);
+
+ const move = await moveTemplate(rig.port, {
+ fromFolder: folder,
+ fromName,
+ toFolder: folder,
+ toName,
+ });
+ expect(move.status).toBe(200);
+ await pollUntil(() => existsSync(join(templatesDir, `${toName}.md`)), 8000);
+ expect(readdirSync(templatesDir)).toEqual([`${toName}.md`]);
+
+ const del = await deleteTemplate(rig.port, folder, toName);
+ expect(del.status).toBe(200);
+ expect(((await del.json()) as { existed?: boolean }).existed).toBe(true);
+ expect(existsSync(join(templatesDir, `${toName}.md`))).toBe(false);
+ },
+ HARNESS_BOOT_TIMEOUT_MS + 30_000,
+ );
});
diff --git a/packages/app/tests/integration/template-import-collision.test.ts b/packages/app/tests/integration/template-import-collision.test.ts
index f54454e18..53cfcb8ad 100644
--- a/packages/app/tests/integration/template-import-collision.test.ts
+++ b/packages/app/tests/integration/template-import-collision.test.ts
@@ -63,33 +63,56 @@ async function waitForRemoval(docName: string): Promise<void> {
}
describe('template import never overwrites an existing template', () => {
- test('two pages named only in non-Latin script land as separate templates', async () => {
+ test('two pages with the same non-Latin name keep it and land as separate templates', async () => {
const folder = `jp-${randomUUID().slice(0, 8)}`;
const firstMarker = `minutes-${randomUUID().slice(0, 8)}`;
- const secondMarker = `daily-${randomUUID().slice(0, 8)}`;
- await writeSource(`${folder}/議事録`, `# 議事録\n\n${firstMarker}\n`);
- await writeSource(`${folder}/日報`, `# 日報\n\n${secondMarker}\n`);
+ const secondMarker = `minutes-${randomUUID().slice(0, 8)}`;
+ await writeSource(`${folder}/sales/議事録`, `# 議事録\n\n${firstMarker}\n`);
+ await writeSource(`${folder}/eng/議事録`, `# 議事録\n\n${secondMarker}\n`);
const firstPath = await importedPath(
- await importTemplate({ sourcePath: `${folder}/議事録`, targetFolder: folder }),
+ await importTemplate({ sourcePath: `${folder}/sales/議事録`, targetFolder: folder }),
);
const secondPath = await importedPath(
await importTemplate({
- sourcePath: `${folder}/日報`,
+ sourcePath: `${folder}/eng/議事録`,
targetFolder: folder,
deleteSource: true,
}),
);
- expect(firstPath).toBe(`${folder}/.ok/templates/imported-template.md`);
- expect(secondPath).toBe(`${folder}/.ok/templates/imported-template-2.md`);
- expect(templateBytes(folder, 'imported-template')).toContain(firstMarker);
- expect(templateBytes(folder, 'imported-template')).not.toContain(secondMarker);
- expect(templateBytes(folder, 'imported-template-2')).toContain(secondMarker);
+ expect(firstPath).toBe(`${folder}/.ok/templates/議事録.md`);
+ expect(secondPath).toBe(`${folder}/.ok/templates/議事録-2.md`);
+ expect(templateBytes(folder, '議事録')).toContain(firstMarker);
+ expect(templateBytes(folder, '議事録')).not.toContain(secondMarker);
+ expect(templateBytes(folder, '議事録-2')).toContain(secondMarker);
- await waitForRemoval(`${folder}/日報`);
- expect(existsSync(join(server.contentDir, folder, '日報.md'))).toBe(false);
- expect(existsSync(join(server.contentDir, folder, '議事録.md'))).toBe(true);
+ await waitForRemoval(`${folder}/eng/議事録`);
+ expect(existsSync(join(server.contentDir, folder, 'eng', '議事録.md'))).toBe(false);
+ expect(existsSync(join(server.contentDir, folder, 'sales', '議事録.md'))).toBe(true);
+ });
+
+ test('pages named only in symbols fall back to a numbered default name', async () => {
+ const folder = `sym-${randomUUID().slice(0, 8)}`;
+ const markers = [0, 1].map((i) => `s${i}-${randomUUID().slice(0, 8)}`);
+ await writeSource(`${folder}/★★★`, `# A\n\n${markers[0]}\n`);
+ await writeSource(`${folder}/☆☆☆`, `# B\n\n${markers[1]}\n`);
+
+ const paths = [
+ await importedPath(
+ await importTemplate({ sourcePath: `${folder}/★★★`, targetFolder: folder }),
+ ),
+ await importedPath(
+ await importTemplate({ sourcePath: `${folder}/☆☆☆`, targetFolder: folder }),
+ ),
+ ];
+
+ expect(paths).toEqual([
+ `${folder}/.ok/templates/imported-template.md`,
+ `${folder}/.ok/templates/imported-template-2.md`,
+ ]);
+ expect(templateBytes(folder, 'imported-template')).toContain(markers[0]);
+ expect(templateBytes(folder, 'imported-template-2')).toContain(markers[1]);
});
test('ASCII names that derive the same slug walk to the next free suffix', async () => {
@@ -123,20 +146,25 @@ describe('template import never overwrites an existing template', () => {
test('concurrent unnamed imports of colliding pages each get their own template', async () => {
const folder = `race-${randomUUID().slice(0, 8)}`;
- const names = ['Привет', 'Мир', 'Тест'];
+ const names = ['one', 'two', 'three'];
for (const name of names) {
- await writeSource(`${folder}/${name}`, `# ${name}\n\nbody-${name}\n`);
+ await writeSource(`${folder}/${name}/Привет`, `# Привет\n\nbody-${name}\n`);
}
const paths = await Promise.all(
names.map(async (name) =>
importedPath(
- await importTemplate({ sourcePath: `${folder}/${name}`, targetFolder: folder }),
+ await importTemplate({ sourcePath: `${folder}/${name}/Привет`, targetFolder: folder }),
),
),
);
expect(new Set(paths).size).toBe(names.length);
+ expect([...paths].sort()).toEqual([
+ `${folder}/.ok/templates/привет-2.md`,
+ `${folder}/.ok/templates/привет-3.md`,
+ `${folder}/.ok/templates/привет.md`,
+ ]);
const contents = paths.map((p) => readFileSync(join(server.contentDir, p), 'utf-8'));
for (const name of names) {
expect(contents.filter((c) => c.includes(`body-${name}`))).toHaveLength(1);
diff --git a/packages/core/package.json b/packages/core/package.json
index c02c9f295..0018b7514 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -731,6 +731,12 @@
"types": "./dist/utils-github-stars.d.mts",
"default": "./dist/utils-github-stars.mjs"
},
+ "./utils/grapheme-clip": {
+ "@inkeep/source": "./src/utils/grapheme-clip.ts",
+ "development": "./src/utils/grapheme-clip.ts",
+ "types": "./dist/utils-grapheme-clip.d.mts",
+ "default": "./dist/utils-grapheme-clip.mjs"
+ },
"./utils/heading-scan": {
"@inkeep/source": "./src/utils/heading-scan.ts",
"development": "./src/utils/heading-scan.ts",
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index b72c2977f..45606e0f3 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1303,6 +1303,7 @@ export {
CreatePageRequestSchema,
type CreatePageSuccess,
CreatePageSuccessSchema,
+ canonicalTemplateName,
classifyGitAuthError,
classifySemanticProviderError,
containsXmlTag,
@@ -1363,6 +1364,7 @@ export {
FrontmatterPatchRequestSchema,
type FrontmatterPatchSuccess,
FrontmatterPatchSuccessSchema,
+ findTemplateByName,
GIT_STATUS_CODES,
type GitAuthFailureSubclass,
type GitHubReferencePreview,
@@ -1800,6 +1802,7 @@ export {
type TagsListSuccess,
TagsListSuccessSchema,
TEMPLATE_NAME_REGEX,
+ TEMPLATE_NAME_RULE,
type TemplateDeleteSuccess,
TemplateDeleteSuccessSchema,
type TemplateFrontmatter,
@@ -1837,6 +1840,7 @@ export {
TrashCleanupRequestSchema,
type TrashCleanupSuccess,
TrashCleanupSuccessSchema,
+ templateRenameTarget,
UNREADABLE_WARNINGS_TEXT,
type UploadAssetSuccess,
UploadAssetSuccessSchema,
@@ -2126,6 +2130,7 @@ export { isEmbedUrlRewritable, rewriteEmbedUrl } from './utils/embed-url-rewrite
export { extensionOf } from './utils/extension.ts';
export { formatFileSize } from './utils/file-size.ts';
export { getGitHubStars } from './utils/github-stars.ts';
+export { graphemePrefix, graphemeSuffix } from './utils/grapheme-clip.ts';
export { scanHeadingLine } from './utils/heading-scan.ts';
export {
AGENT_COLORS,
diff --git a/packages/core/src/schemas/api/tags-search.test.ts b/packages/core/src/schemas/api/tags-search.test.ts
index ed28f2fd9..21f5ccdd9 100644
--- a/packages/core/src/schemas/api/tags-search.test.ts
+++ b/packages/core/src/schemas/api/tags-search.test.ts
@@ -1,6 +1,8 @@
import { describe, expect, test } from 'vitest';
import {
+ canonicalTemplateName,
classifySemanticProviderError,
+ findTemplateByName,
interpretSkillMoveFailure,
isSkillMoveRetainedDestinationCode,
isSkillMoveStateCode,
@@ -14,8 +16,10 @@ import {
SKILL_RETENTION_LEDGER_CODES,
SKILL_SOURCE_STATE_CODES,
semanticProviderErrorBlocks,
+ TEMPLATE_NAME_REGEX,
TemplateGetSuccessSchema,
TemplatePayloadSchema,
+ templateRenameTarget,
} from './tags-search.ts';
const validPayload = (scope: 'local' | 'inherited') => ({
@@ -243,3 +247,96 @@ describe('skill move-state, source-state and retention-ledger code guards', () =
expect(new Set(all).size).toBe(all.length);
});
});
+
+describe('TEMPLATE_NAME_REGEX', () => {
+ test.each([
+ 'daily-journal',
+ 'Weekly_1',
+ '議事録',
+ 'café',
+ 'cafe\u0301',
+ 'notas-reunión',
+ 'заметки_1',
+ 'ملاحظات',
+ 'मीटिंग-नोट्स',
+ '회의록',
+ ])('accepts %s', (name) => {
+ expect(TEMPLATE_NAME_REGEX.test(name)).toBe(true);
+ });
+
+ test.each([
+ '',
+ 'a b',
+ 'a.b',
+ 'a/b',
+ 'a\\b',
+ 'a:b',
+ 'a*b',
+ 'a?b',
+ 'a"b',
+ 'a<b',
+ 'a|b',
+ 'notes.md',
+ 'a\u200bb',
+ 'a\u3164b',
+ 'a\u034fb',
+ '\u115f',
+ ])('rejects %j', (name) => {
+ expect(TEMPLATE_NAME_REGEX.test(name)).toBe(false);
+ });
+});
+
+describe('canonicalTemplateName', () => {
+ test('a decomposed name becomes its composed spelling', () => {
+ expect(canonicalTemplateName('cafe\u0301')).toBe('café');
+ expect(canonicalTemplateName('\u30C6\u3099\u30FC\u30BF')).toBe('データ');
+ });
+
+ test('an already composed or ASCII name is unchanged', () => {
+ expect(canonicalTemplateName('café')).toBe('café');
+ expect(canonicalTemplateName('daily-journal')).toBe('daily-journal');
+ });
+});
+
+describe('findTemplateByName', () => {
+ const composed = { name: 'caf\u{00E9}' };
+ const decomposed = { name: 'cafe\u{0301}' };
+
+ test('a composed request finds a listed decomposed template', () => {
+ expect(findTemplateByName([decomposed], 'caf\u{00E9}')).toBe(decomposed);
+ });
+
+ test('a decomposed request finds a listed composed template', () => {
+ expect(findTemplateByName([composed], 'cafe\u{0301}')).toBe(composed);
+ });
+
+ test('an exact spelling wins over another spelling of the same name', () => {
+ expect(findTemplateByName([composed, decomposed], 'cafe\u{0301}')).toBe(decomposed);
+ expect(findTemplateByName([decomposed, composed], 'caf\u{00E9}')).toBe(composed);
+ });
+
+ test('a different name finds nothing', () => {
+ expect(findTemplateByName([composed], 'cafe')).toBeUndefined();
+ });
+});
+
+describe('templateRenameTarget', () => {
+ test('an unedited name, in any spelling, is not a rename', () => {
+ expect(templateRenameTarget('cafe\u{0301}', 'cafe\u{0301}')).toBeNull();
+ expect(templateRenameTarget('caf\u{00E9}', 'caf\u{00E9}')).toBeNull();
+ expect(templateRenameTarget('meeting', ' meeting ')).toBeNull();
+ });
+
+ test('re-entering a composed name in decomposed form is not a rename', () => {
+ expect(templateRenameTarget('caf\u{00E9}', 'cafe\u{0301}')).toBeNull();
+ });
+
+ test('a new name is a rename to its composed spelling', () => {
+ expect(templateRenameTarget('meeting', 'cafe\u{0301}')).toBe('caf\u{00E9}');
+ expect(templateRenameTarget('meeting', ' standup ')).toBe('standup');
+ });
+
+ test('a decomposed name can be renamed to its composed spelling', () => {
+ expect(templateRenameTarget('cafe\u{0301}', 'caf\u{00E9}')).toBe('caf\u{00E9}');
+ });
+});
diff --git a/packages/core/src/schemas/api/tags-search.ts b/packages/core/src/schemas/api/tags-search.ts
index 1b8831397..261f485cd 100644
--- a/packages/core/src/schemas/api/tags-search.ts
+++ b/packages/core/src/schemas/api/tags-search.ts
@@ -215,7 +215,32 @@ export function containsXmlTag(s: string): boolean {
return XML_TAG_REGEX.test(s);
}
-export const TEMPLATE_NAME_REGEX = /^[A-Za-z0-9_-]+$/;
+export const TEMPLATE_NAME_REGEX = /^(?:(?!\p{DI})[\p{L}\p{M}\p{N}_-])+$/u;
+
+export const TEMPLATE_NAME_RULE =
+ 'letters and digits in any script, `_` or `-` only (no spaces, dots, slashes or invisible characters)';
+
+export function canonicalTemplateName(name: string): string {
+ return name.normalize('NFC');
+}
+
+export function templateRenameTarget(storedName: string, draft: string): string | null {
+ const trimmed = draft.trim();
+ if (trimmed === storedName) return null;
+ const target = canonicalTemplateName(trimmed);
+ return target === storedName ? null : target;
+}
+
+export function findTemplateByName<T extends { name: string }>(
+ templates: readonly T[],
+ requested: string,
+): T | undefined {
+ const key = canonicalTemplateName(requested);
+ return (
+ templates.find((t) => t.name === requested) ??
+ templates.find((t) => canonicalTemplateName(t.name) === key)
+ );
+}
export const SkillFrontmatterSchema = z
.object({
diff --git a/packages/core/src/shadow-repo-layout.test.ts b/packages/core/src/shadow-repo-layout.test.ts
index e9994bb96..57ef7912f 100644
--- a/packages/core/src/shadow-repo-layout.test.ts
+++ b/packages/core/src/shadow-repo-layout.test.ts
@@ -1665,3 +1665,20 @@ describe('resolveProjectIdentity', () => {
expect(resolveProjectIdentity(wt)).toBe(wt);
});
});
+
+describe('composeCommitSubject — truncation keeps characters whole', () => {
+ test('a summary cut at an emoji drops the whole emoji', () => {
+ const base = 'wip: notes.md';
+ const prefix = `${base} — `;
+ const budget = COMMIT_SUBJECT_MAX_LEN - prefix.length - 1;
+ const summary = `${'a'.repeat(budget - 1)}\u{1F600}${'b'.repeat(20)}`;
+ expect(composeCommitSubject(base, [summary])).toBe(`${prefix}${'a'.repeat(budget - 1)}…`);
+ });
+
+ test('an over-long base cut at an emoji drops the whole emoji', () => {
+ const base = `wip: ${'n'.repeat(COMMIT_SUBJECT_MAX_LEN - 6)}\u{1F600}${'m'.repeat(10)}`;
+ expect(composeCommitSubject(base, ['why'])).toBe(
+ `wip: ${'n'.repeat(COMMIT_SUBJECT_MAX_LEN - 6)}`,
+ );
+ });
+});
diff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.ts
index 068b69cd6..8419f1cf4 100644
--- a/packages/core/src/shadow-repo-layout.ts
+++ b/packages/core/src/shadow-repo-layout.ts
@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
import { dirname, join, resolve, sep } from 'node:path';
import { fnv1aDigest } from './bridge/hash-util.ts';
import { discoverGitRepository, isMissing } from './git-repository.ts';
+import { graphemePrefix } from './utils/grapheme-clip.ts';
/** Writer-ID taxonomy (precedent #25). */
export type WriterClassification =
@@ -533,8 +534,8 @@ export function composeCommitSubject(base: string, summaries: readonly string[])
if (full.length <= COMMIT_SUBJECT_MAX_LEN) return full;
const prefix = `${safeBase} — `;
const budget = COMMIT_SUBJECT_MAX_LEN - prefix.length - 1;
- if (budget <= 0) return full.slice(0, COMMIT_SUBJECT_MAX_LEN);
- return `${prefix}${summary.slice(0, budget)}…`;
+ if (budget <= 0) return graphemePrefix(full, COMMIT_SUBJECT_MAX_LEN);
+ return `${prefix}${graphemePrefix(summary, budget)}…`;
}
export function parseWriterId(id: string): ParsedWriter {
diff --git a/packages/core/src/utils/grapheme-clip.test.ts b/packages/core/src/utils/grapheme-clip.test.ts
new file mode 100644
index 000000000..c63a97be5
--- /dev/null
+++ b/packages/core/src/utils/grapheme-clip.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, test, vi } from 'vitest';
+import { graphemePrefix, graphemeSuffix } from './grapheme-clip.ts';
+
+const GRINNING = '\u{1F600}';
+const FAMILY = '\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}';
+const FLAG_JP = '\u{1F1EF}\u{1F1F5}';
+const E_ACUTE_DECOMPOSED = 'e\u{0301}';
+const RARE_HAN = '\u{20BB7}';
+
+describe('graphemePrefix', () => {
+ test('returns text that already fits unchanged', () => {
+ expect(graphemePrefix('hello', 5)).toBe('hello');
+ expect(graphemePrefix('', 0)).toBe('');
+ });
+
+ test('cuts plain text at the budget', () => {
+ expect(graphemePrefix('hello world', 5)).toBe('hello');
+ });
+
+ test('never splits a surrogate pair', () => {
+ expect(graphemePrefix(`ab${GRINNING}cd`, 3)).toBe('ab');
+ expect(graphemePrefix(`ab${RARE_HAN}`, 3)).toBe('ab');
+ expect(graphemePrefix(`ab${GRINNING}cd`, 4)).toBe(`ab${GRINNING}`);
+ });
+
+ test('keeps a whole grapheme cluster or drops it', () => {
+ expect(graphemePrefix(`x${FAMILY}y`, 5)).toBe('x');
+ expect(graphemePrefix(`x${FAMILY}y`, 1 + FAMILY.length)).toBe(`x${FAMILY}`);
+ expect(graphemePrefix(`x${FLAG_JP}`, 4)).toBe('x');
+ expect(graphemePrefix(`caf${E_ACUTE_DECOMPOSED}s`, 4)).toBe('caf');
+ });
+
+ test('a budget of zero or less yields an empty string', () => {
+ expect(graphemePrefix('abc', 0)).toBe('');
+ expect(graphemePrefix('abc', -3)).toBe('');
+ });
+});
+
+describe('graphemeSuffix', () => {
+ test('returns text that already fits unchanged', () => {
+ expect(graphemeSuffix('hello', 5)).toBe('hello');
+ });
+
+ test('keeps the last characters within the budget', () => {
+ expect(graphemeSuffix('hello world', 5)).toBe('world');
+ });
+
+ test('never starts on the second half of a surrogate pair', () => {
+ expect(graphemeSuffix(`ab${GRINNING}cd`, 3)).toBe('cd');
+ expect(graphemeSuffix(`ab${GRINNING}cd`, 4)).toBe(`${GRINNING}cd`);
+ });
+
+ test('keeps a whole grapheme cluster or drops it', () => {
+ expect(graphemeSuffix(`x${FAMILY}y`, 5)).toBe('y');
+ expect(graphemeSuffix(`${E_ACUTE_DECOMPOSED}tc`, 3)).toBe('tc');
+ });
+
+ test('a budget of zero or less yields an empty string', () => {
+ expect(graphemeSuffix('abc', 0)).toBe('');
+ });
+});
+
+describe('without Intl.Segmenter', () => {
+ async function loadWithoutSegmenter(): Promise<typeof import('./grapheme-clip.ts')> {
+ const descriptor = Object.getOwnPropertyDescriptor(Intl, 'Segmenter');
+ Reflect.deleteProperty(Intl, 'Segmenter');
+ vi.resetModules();
+ try {
+ return await import('./grapheme-clip.ts');
+ } finally {
+ if (descriptor) Object.defineProperty(Intl, 'Segmenter', descriptor);
+ vi.resetModules();
+ }
+ }
+
+ test('a prefix still never splits a surrogate pair', async () => {
+ const mod = await loadWithoutSegmenter();
+ expect(mod.graphemePrefix(`ab${GRINNING}cd`, 3)).toBe('ab');
+ expect(mod.graphemePrefix(`ab${GRINNING}cd`, 4)).toBe(`ab${GRINNING}`);
+ expect(mod.graphemePrefix('hello world', 5)).toBe('hello');
+ });
+
+ test('a suffix still never starts on the second half of a surrogate pair', async () => {
+ const mod = await loadWithoutSegmenter();
+ expect(mod.graphemeSuffix(`ab${GRINNING}cd`, 3)).toBe('cd');
+ expect(mod.graphemeSuffix(`ab${GRINNING}cd`, 4)).toBe(`${GRINNING}cd`);
+ expect(mod.graphemeSuffix('hello world', 5)).toBe('world');
+ });
+});
diff --git a/packages/core/src/utils/grapheme-clip.ts b/packages/core/src/utils/grapheme-clip.ts
new file mode 100644
index 000000000..2e26d8582
--- /dev/null
+++ b/packages/core/src/utils/grapheme-clip.ts
@@ -0,0 +1,45 @@
+const GRAPHEME_SEGMENTER = (() => {
+ const Ctor = (globalThis as { Intl: { Segmenter?: typeof Intl.Segmenter } }).Intl.Segmenter;
+ return Ctor ? new Ctor(undefined, { granularity: 'grapheme' }) : null;
+})();
+
+function isLowSurrogate(code: number): boolean {
+ return code >= 0xdc00 && code <= 0xdfff;
+}
+
+function isHighSurrogate(code: number): boolean {
+ return code >= 0xd800 && code <= 0xdbff;
+}
+
+function boundaryAtOrBefore(text: string, index: number): number {
+ if (GRAPHEME_SEGMENTER) {
+ const segment = GRAPHEME_SEGMENTER.segment(text).containing(index);
+ return segment === undefined ? index : segment.index;
+ }
+ return isLowSurrogate(text.charCodeAt(index)) && isHighSurrogate(text.charCodeAt(index - 1))
+ ? index - 1
+ : index;
+}
+
+function boundaryAtOrAfter(text: string, index: number): number {
+ if (GRAPHEME_SEGMENTER) {
+ const segment = GRAPHEME_SEGMENTER.segment(text).containing(index);
+ if (segment === undefined || segment.index === index) return index;
+ return segment.index + segment.segment.length;
+ }
+ return isLowSurrogate(text.charCodeAt(index)) && isHighSurrogate(text.charCodeAt(index - 1))
+ ? index + 1
+ : index;
+}
+
+export function graphemePrefix(text: string, maxLength: number): string {
+ if (text.length <= maxLength) return text;
+ if (maxLength <= 0) return '';
+ return text.slice(0, boundaryAtOrBefore(text, maxLength));
+}
+
+export function graphemeSuffix(text: string, maxLength: number): string {
+ if (text.length <= maxLength) return text;
+ if (maxLength <= 0) return '';
+ return text.slice(boundaryAtOrAfter(text, text.length - maxLength));
+}
diff --git a/packages/core/tests/contract/module-subpaths.test.ts b/packages/core/tests/contract/module-subpaths.test.ts
index 050236e43..dee8fa02c 100644
--- a/packages/core/tests/contract/module-subpaths.test.ts
+++ b/packages/core/tests/contract/module-subpaths.test.ts
@@ -107,6 +107,7 @@ import * as utilsEmbedUrlRewriteSubpath from '@inkeep/open-knowledge-core/utils/
import * as utilsExtensionSubpath from '@inkeep/open-knowledge-core/utils/extension';
import * as utilsFileSizeSubpath from '@inkeep/open-knowledge-core/utils/file-size';
import * as utilsGithubStarsSubpath from '@inkeep/open-knowledge-core/utils/github-stars';
+import * as utilsGraphemeClipSubpath from '@inkeep/open-knowledge-core/utils/grapheme-clip';
import * as utilsHeadingScanSubpath from '@inkeep/open-knowledge-core/utils/heading-scan';
import * as utilsIdentitySubpath from '@inkeep/open-knowledge-core/utils/identity';
import * as utilsLinkTargetsSubpath from '@inkeep/open-knowledge-core/utils/link-targets';
@@ -249,6 +250,7 @@ const MODULE_SUBPATHS: Record<string, object> = {
'./utils/extension': utilsExtensionSubpath,
'./utils/file-size': utilsFileSizeSubpath,
'./utils/github-stars': utilsGithubStarsSubpath,
+ './utils/grapheme-clip': utilsGraphemeClipSubpath,
'./utils/heading-scan': utilsHeadingScanSubpath,
'./utils/identity': utilsIdentitySubpath,
'./utils/link-targets': utilsLinkTargetsSubpath,
diff --git a/packages/core/tests/contract/subpath-types/consumer.ts b/packages/core/tests/contract/subpath-types/consumer.ts
index ec2b7ba15..a87e1a8e0 100644
--- a/packages/core/tests/contract/subpath-types/consumer.ts
+++ b/packages/core/tests/contract/subpath-types/consumer.ts
@@ -772,6 +772,10 @@ export type { rewriteEmbedUrl } from '@inkeep/open-knowledge-core/utils/embed-ur
export type { extensionOf } from '@inkeep/open-knowledge-core/utils/extension';
export type { formatFileSize } from '@inkeep/open-knowledge-core/utils/file-size';
export type { getGitHubStars } from '@inkeep/open-knowledge-core/utils/github-stars';
+export type {
+ graphemePrefix,
+ graphemeSuffix,
+} from '@inkeep/open-knowledge-core/utils/grapheme-clip';
export type { scanHeadingLine } from '@inkeep/open-knowledge-core/utils/heading-scan';
export type {
AGENT_ICON_COLORS,
diff --git a/packages/core/tsdown.config.ts b/packages/core/tsdown.config.ts
index 69eaeb9cb..03ff0e997 100644
--- a/packages/core/tsdown.config.ts
+++ b/packages/core/tsdown.config.ts
@@ -122,6 +122,7 @@ const entry = {
'utils-extension': 'src/utils/extension.ts',
'utils-file-size': 'src/utils/file-size.ts',
'utils-github-stars': 'src/utils/github-stars.ts',
+ 'utils-grapheme-clip': 'src/utils/grapheme-clip.ts',
'utils-heading-scan': 'src/utils/heading-scan.ts',
'utils-identity': 'src/utils/identity.ts',
'utils-link-targets': 'src/utils/link-targets.ts',
diff --git a/packages/server/src/acp/thread-title.test.ts b/packages/server/src/acp/thread-title.test.ts
index fe867e13a..69aecef75 100644
--- a/packages/server/src/acp/thread-title.test.ts
+++ b/packages/server/src/acp/thread-title.test.ts
@@ -1,6 +1,8 @@
import { describe, expect, test } from 'vitest';
import { clampThreadTitle, deriveThreadTitle, TITLE_MAX_CHARS } from './thread-title.ts';
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
describe('deriveThreadTitle', () => {
test('passes a plain imperative line through unchanged', () => {
expect(deriveThreadTitle('Fix the login bug')).toBe('Fix the login bug');
@@ -152,3 +154,35 @@ describe('clampThreadTitle', () => {
expect(clamped.endsWith('…')).toBe(true);
});
});
+
+describe('thread titles outside ASCII', () => {
+ test('strips a leading agent name that ends in a non-ASCII letter', () => {
+ expect(deriveThreadTitle('Café, fix the parser', 'Café')).toBe('Fix the parser');
+ expect(deriveThreadTitle('@Café fix the parser', 'Café')).toBe('Fix the parser');
+ expect(deriveThreadTitle('@助手 请帮我修复解析器里的这个错误', '助手')).toBe(
+ '请帮我修复解析器里的这个错误',
+ );
+ });
+
+ test('leaves a longer word that starts with the agent name alone', () => {
+ expect(deriveThreadTitle('@Caféteria menu needs updating', 'Café')).toBe(
+ '@Caféteria menu needs updating',
+ );
+ });
+
+ test('clamping never leaves half of an emoji behind', () => {
+ const clamped = clampThreadTitle(
+ `${'x'.repeat(TITLE_MAX_CHARS - 2)}\u{1F600}${'y'.repeat(20)}`,
+ );
+ expect(clamped).toBe(`${'x'.repeat(TITLE_MAX_CHARS - 2)}…`);
+ expect(LONE_SURROGATE.test(clamped)).toBe(false);
+ });
+
+ test('clamping keeps a joined emoji whole or drops it', () => {
+ const family = '\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}';
+ const clamped = clampThreadTitle(
+ `${'x'.repeat(TITLE_MAX_CHARS - 4)}${family}${'y'.repeat(20)}`,
+ );
+ expect(clamped).toBe(`${'x'.repeat(TITLE_MAX_CHARS - 4)}…`);
+ });
+});
diff --git a/packages/server/src/acp/thread-title.ts b/packages/server/src/acp/thread-title.ts
index b6e55e20b..c11a29ffe 100644
--- a/packages/server/src/acp/thread-title.ts
+++ b/packages/server/src/acp/thread-title.ts
@@ -1,5 +1,9 @@
+import { graphemePrefix } from '@inkeep/open-knowledge-core/utils/grapheme-clip';
+
export const TITLE_MAX_CHARS = 48;
+const WORD_END = String.raw`(?![\p{L}\p{M}\p{N}_])`;
+
const FILLER_PREFIXES = [
'do you mind',
'i would like you to',
@@ -51,8 +55,8 @@ const FILLER_PREFIXES = [
];
const FILLER_RE = new RegExp(
- `^(?:${FILLER_PREFIXES.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\b(?:[\\s,:;!.\\-–—]+|$)`,
- 'i',
+ `^(?:${FILLER_PREFIXES.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})${WORD_END}(?:[\\s,:;!.\\-–—]+|$)`,
+ 'iu',
);
const MARKDOWN_LEAD_RE = /^(?:[#>]+\s*|[-*]\s+|\d+[.)]\s+)+/;
@@ -72,7 +76,7 @@ function firstLine(raw: string): string {
export function clampThreadTitle(raw: string): string {
const line = firstLine(raw);
if (line.length <= TITLE_MAX_CHARS) return line;
- const hard = line.slice(0, TITLE_MAX_CHARS - 1);
+ const hard = graphemePrefix(line, TITLE_MAX_CHARS - 1);
const lastSpace = hard.lastIndexOf(' ');
const cut = lastSpace >= TITLE_MAX_CHARS / 2 ? hard.slice(0, lastSpace) : hard;
return `${cut.trimEnd()}…`;
@@ -85,8 +89,8 @@ export function deriveThreadTitle(prompt: string, agentName?: string): string {
const name = escapeRegExp(agentName.trim());
const delim = String.raw`[,:;!.?\-–—•|]`;
const nameRe = new RegExp(
- `^(?:@${name}\\b(?:\\s+|${delim}+(?:\\s+|$)|$)|${name}\\b\\s*${delim}+(?:\\s+|$)|@?${name}\\b$)`,
- 'i',
+ `^(?:@${name}${WORD_END}(?:\\s+|${delim}+(?:\\s+|$)|$)|${name}${WORD_END}\\s*${delim}+(?:\\s+|$)|@?${name}${WORD_END}$)`,
+ 'iu',
);
stripped = stripped.replace(nameRe, '');
}
diff --git a/packages/server/src/api-file-ops-composition.test.ts b/packages/server/src/api-file-ops-composition.test.ts
index 4eb092386..46e1b2058 100644
--- a/packages/server/src/api-file-ops-composition.test.ts
+++ b/packages/server/src/api-file-ops-composition.test.ts
@@ -3,6 +3,7 @@ import {
mkdirSync,
mkdtempSync,
readdirSync,
+ readFileSync,
symlinkSync,
writeFileSync,
} from 'node:fs';
@@ -115,6 +116,56 @@ describe('file-ops group over the composed listener — served natively', () =>
expect(existsSync(resolve(contentDir, 'leaky', 'from-leak.md'))).toBe(false);
});
+ test('create-page instantiates a template whose name uses non-Latin letters', async () => {
+ const tplDir = resolve(contentDir, 'minutes', '.ok', 'templates');
+ mkdirSync(tplDir, { recursive: true });
+ writeFileSync(
+ resolve(tplDir, '議事録.md'),
+ '---\ntemplate:\n title: 議事録\n---\n## 出席者\n',
+ 'utf-8',
+ );
+ const res = await postJson('/api/create-page', {
+ path: 'minutes/2026-10-13.md',
+ template: '議事録',
+ });
+ expect(res.status).toBe(200);
+ expect(readFileSync(resolve(contentDir, 'minutes', '2026-10-13.md'), 'utf-8')).toContain(
+ '## 出席者',
+ );
+ });
+
+ test('create-page resolves a decomposed template name to its composed spelling', async () => {
+ const tplDir = resolve(contentDir, 'nfc', '.ok', 'templates');
+ mkdirSync(tplDir, { recursive: true });
+ writeFileSync(
+ resolve(tplDir, 'café.md'),
+ '---\ntemplate:\n title: Café\n---\n## Menu\n',
+ 'utf-8',
+ );
+ const res = await postJson('/api/create-page', {
+ path: 'nfc/today.md',
+ template: 'cafe\u0301',
+ });
+ expect(res.status).toBe(200);
+ expect(readFileSync(resolve(contentDir, 'nfc', 'today.md'), 'utf-8')).toContain('## Menu');
+ });
+
+ test('create-page finds a decomposed template file from its composed spelling', async () => {
+ const tplDir = resolve(contentDir, 'nfd', '.ok', 'templates');
+ mkdirSync(tplDir, { recursive: true });
+ writeFileSync(
+ resolve(tplDir, 'cafe\u{0301}.md'),
+ '---\ntemplate:\n title: Cafe\n---\n## Specials\n',
+ 'utf-8',
+ );
+ const res = await postJson('/api/create-page', {
+ path: 'nfd/today.md',
+ template: 'caf\u{00E9}',
+ });
+ expect(res.status).toBe(200);
+ expect(readFileSync(resolve(contentDir, 'nfd', 'today.md'), 'utf-8')).toContain('## Specials');
+ });
+
test('create-page refuses a target routed into .ok through a symlinked directory', async () => {
symlinkSync(resolve(contentDir, '.ok'), resolve(contentDir, 'escape-hatch'), 'dir');
const res = await postJson('/api/create-page', {
diff --git a/packages/server/src/content/templates-write.test.ts b/packages/server/src/content/templates-write.test.ts
index 8b5b1169d..98aad4b7f 100644
--- a/packages/server/src/content/templates-write.test.ts
+++ b/packages/server/src/content/templates-write.test.ts
@@ -135,6 +135,31 @@ describe('applyTemplateWrite', () => {
expect(result.warnings.some((w) => w.match(/description is missing/))).toBe(true);
});
+ test('writes a template whose name uses non-Latin letters', () => {
+ const result = applyTemplateWrite({
+ projectDir,
+ folder: 'meetings',
+ name: '議事録',
+ body: 'body',
+ frontmatter: { title: '議事録', description: 'Minutes' },
+ });
+ expect(result.ok).toBe(true);
+ expect(existsSync(join(projectDir, 'meetings', '.ok', 'templates', '議事録.md'))).toBe(true);
+ });
+
+ test('rejects a name hidden behind an invisible character (BAD_NAME)', () => {
+ const result = applyTemplateWrite({
+ projectDir,
+ folder: 'meetings',
+ name: 'notes\u200b',
+ body: 'body',
+ frontmatter: { title: 'X', description: 'X' },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(result.error.code).toBe('BAD_NAME');
+ });
+
test('rejects bad name (BAD_NAME)', () => {
const result = applyTemplateWrite({
projectDir,
diff --git a/packages/server/src/content/templates-write.ts b/packages/server/src/content/templates-write.ts
index 57fc17492..94b826a5a 100644
--- a/packages/server/src/content/templates-write.ts
+++ b/packages/server/src/content/templates-write.ts
@@ -13,6 +13,7 @@ import {
stripFrontmatter,
TEMPLATE_IDENTITY_KEY,
TEMPLATE_NAME_REGEX,
+ TEMPLATE_NAME_RULE,
type TemplateIdentity,
unwrapFrontmatterFences,
} from '@inkeep/open-knowledge-core';
@@ -79,7 +80,7 @@ export function composeTemplateContent(input: {
ok: false,
error: {
code: 'BAD_NAME',
- message: `Template name must match /^[A-Za-z0-9_-]+$/ (got: ${JSON.stringify(input.name)}). Use letters, digits, underscores, or hyphens — no slashes, dots, or spaces.`,
+ message: `Template name must use ${TEMPLATE_NAME_RULE} (got: ${JSON.stringify(input.name)}).`,
},
};
}
@@ -334,7 +335,7 @@ function validateInputs(
ok: false,
error: {
code: 'BAD_NAME',
- message: `Template name must match /^[A-Za-z0-9_-]+$/ (got: ${JSON.stringify(name)}). Use letters, digits, underscores, or hyphens — no slashes, dots, or spaces.`,
+ message: `Template name must use ${TEMPLATE_NAME_RULE} (got: ${JSON.stringify(name)}).`,
},
};
}
diff --git a/packages/server/src/http/file-ops-routes.ts b/packages/server/src/http/file-ops-routes.ts
index 2850628bd..746a1a091 100644
--- a/packages/server/src/http/file-ops-routes.ts
+++ b/packages/server/src/http/file-ops-routes.ts
@@ -18,6 +18,7 @@ import {
DeletePathSuccessSchema,
DuplicatePathRequestSchema,
DuplicatePathSuccessSchema,
+ findTemplateByName,
instantiateDoc,
isManagedArtifactDocName,
LINKABLE_ASSET_EXTENSIONS,
@@ -25,6 +26,8 @@ import {
type ProblemType,
RenamePathRequestSchema,
RenamePathSuccessSchema,
+ TEMPLATE_NAME_REGEX,
+ TEMPLATE_NAME_RULE,
TrashCleanupRequestSchema,
TrashCleanupSuccessSchema,
UploadAssetSuccessSchema,
@@ -547,12 +550,12 @@ export function createFileOpsRoutes(deps: FileOpsRouteDeps): ApiRouteGroup {
let initialContent = '';
let templateScopeForLog: 'local' | 'inherited' | undefined;
if (templateName.length > 0) {
- if (!/^[A-Za-z0-9_-]+$/.test(templateName)) {
+ if (!TEMPLATE_NAME_REGEX.test(templateName)) {
errorResponse(
res,
400,
'urn:ok:error:invalid-request',
- 'Template name must match [A-Za-z0-9_-]+.',
+ `Template name must use ${TEMPLATE_NAME_RULE}.`,
{ handler: 'create-page' },
);
return;
@@ -561,7 +564,7 @@ export function createFileOpsRoutes(deps: FileOpsRouteDeps): ApiRouteGroup {
? filePath.slice(0, filePath.lastIndexOf('/'))
: '';
const available = resolveTemplatesAvailable(resolvedContentDir, parentFolder);
- const matched = available.find((t) => t.name === templateName);
+ const matched = findTemplateByName(available, templateName);
if (!matched) {
const availableLabel =
available.length === 0
diff --git a/packages/server/src/http/folder-template-routes.ts b/packages/server/src/http/folder-template-routes.ts
index b1e5ecd81..b87599a30 100644
--- a/packages/server/src/http/folder-template-routes.ts
+++ b/packages/server/src/http/folder-template-routes.ts
@@ -4,6 +4,7 @@ import type { ServerResponse } from 'node:http';
import { relative, resolve, sep } from 'node:path';
import type { Hocuspocus } from '@hocuspocus/server';
import {
+ canonicalTemplateName,
EmptyRequestSchema,
FolderConfigGetSuccessSchema,
FolderConfigPutRequestSchema,
@@ -15,6 +16,7 @@ import {
parseTemplateFile,
stripFrontmatter,
TEMPLATE_NAME_REGEX,
+ TEMPLATE_NAME_RULE,
TemplateDeleteSuccessSchema,
TemplateGetSuccessSchema,
TemplateImportRequestSchema,
@@ -176,7 +178,7 @@ export function createFolderTemplateRoutes(deps: FolderTemplateRouteDeps): ApiRo
res,
400,
'urn:ok:error:invalid-request',
- 'Invalid name: must be letters / digits / `_` / `-` only (no `.md` extension).',
+ `Invalid name: must use ${TEMPLATE_NAME_RULE}, without the \`.md\` extension.`,
{ handler },
);
return false;
@@ -1187,7 +1189,9 @@ export function createFolderTemplateRoutes(deps: FolderTemplateRouteDeps): ApiRo
if (!name) {
const { basename } = splitContentPath(sourcePath);
const nameWithoutExt = basename.replace(/\.(md|mdx)$/i, '');
- name = nameWithoutExt.replace(/[^A-Za-z0-9_-]/g, '-').toLowerCase();
+ name = canonicalTemplateName(nameWithoutExt)
+ .replace(/[^\p{L}\p{M}\p{N}_-]|\p{DI}/gu, '-')
+ .toLowerCase();
name = name.replace(/^[-_]+|[-_]+$/g, '');
name ||= 'imported-template';
}
diff --git a/packages/server/src/mcp/tools/verb-schemas.test.ts b/packages/server/src/mcp/tools/verb-schemas.test.ts
index 289792341..dad04a6c6 100644
--- a/packages/server/src/mcp/tools/verb-schemas.test.ts
+++ b/packages/server/src/mcp/tools/verb-schemas.test.ts
@@ -1,6 +1,11 @@
import { describe, expect, test } from 'vitest';
import { SUPPORTED_DOC_EXTENSIONS } from '../../doc-extensions.ts';
-import { DocExtensionArg, FrontmatterArg, resolveSkillFilePath } from './verb-schemas.ts';
+import {
+ DocExtensionArg,
+ FrontmatterArg,
+ resolveSkillFilePath,
+ resolveTemplatePath,
+} from './verb-schemas.ts';
describe('FrontmatterArg — recursive value contract (PRD-6947)', () => {
test('flat scalar values still parse (regression guard for the pre-PRD-6947 contract)', () => {
@@ -146,3 +151,32 @@ describe('resolveSkillFilePath — bundle-file path allowlist', () => {
if (b.ok) expect(b.path).toBe('scripts/run.sh');
});
});
+
+describe('resolveTemplatePath — template name grammar', () => {
+ test('accepts a name written in any script', () => {
+ expect(resolveTemplatePath('meetings/議事録')).toEqual({
+ ok: true,
+ folder: 'meetings',
+ name: '議事録',
+ });
+ expect(resolveTemplatePath('notas-reunión')).toEqual({
+ ok: true,
+ folder: '',
+ name: 'notas-reunión',
+ });
+ });
+
+ test('keeps the spelling the caller wrote', () => {
+ expect(resolveTemplatePath('menus/cafe\u{0301}')).toEqual({
+ ok: true,
+ folder: 'menus',
+ name: 'cafe\u{0301}',
+ });
+ });
+
+ test('rejects dots, spaces and invisible characters in the name', () => {
+ for (const path of ['x/a.b', 'x/a b', 'x/a\u200bb']) {
+ expect(resolveTemplatePath(path).ok, path).toBe(false);
+ }
+ });
+});
diff --git a/packages/server/src/mcp/tools/verb-schemas.ts b/packages/server/src/mcp/tools/verb-schemas.ts
index 33b822c65..9398af158 100644
--- a/packages/server/src/mcp/tools/verb-schemas.ts
+++ b/packages/server/src/mcp/tools/verb-schemas.ts
@@ -5,6 +5,7 @@ import {
SKILL_NAME_REGEX,
skillFilePathSegments,
TEMPLATE_NAME_REGEX,
+ TEMPLATE_NAME_RULE,
} from '@inkeep/open-knowledge-core';
import { z } from 'zod';
import { SUPPORTED_DOC_EXTENSIONS } from '../../doc-extensions.ts';
@@ -67,8 +68,7 @@ export function splitTargetPath(path: string): { folder: string; name: string }
: { folder: clean.slice(0, idx), name: clean.slice(idx + 1) };
}
-export const TEMPLATE_PATH_DESCRIBE =
- 'Template path = `<folder>/<name>` (e.g. "fishing-log/trip-log"). The slashes are the folder it belongs to; the final segment is the template name (letters, digits, `_`, `-` only — no dots/spaces). Stored at `<folder>/.ok/templates/<name>.md`.';
+export const TEMPLATE_PATH_DESCRIBE = `Template path = \`<folder>/<name>\` (e.g. "fishing-log/trip-log"). The slashes are the folder it belongs to; the final segment is the template name, which must use ${TEMPLATE_NAME_RULE}. Stored at \`<folder>/.ok/templates/<name>.md\`.`;
export const TEMPLATE_CONTENT_DESCRIBE =
"Starter content — the Markdown a new document becomes. A leading `---…---` frontmatter block here sets the STARTING PROPERTIES every doc created from this template gets (e.g. `type`, `status`, `tags`); the markdown below it is the body. The template's own picker identity (title/description) is the separate `frontmatter` field, NOT this block — it is stripped at instantiation and never copied onto created docs. (On disk this composes to one frontmatter block with the identity under a reserved `template:` key; you don't author that — just give the starter content here.) Only the `{{date}}` and `{{user}}` substitution tokens are allowed; any other `{{...}}` token hard-errors at write time.";
@@ -79,7 +79,7 @@ export function resolveTemplatePath(
if (!TEMPLATE_NAME_REGEX.test(name)) {
return {
ok: false,
- error: `the final segment of a template path is its name — "${name}" must be letters, digits, \`_\`, \`-\` only (no dots/spaces). e.g. { template: { path: "fishing-log/trip-log" } }.`,
+ error: `the final segment of a template path is its name — "${name}" must use ${TEMPLATE_NAME_RULE}. e.g. { template: { path: "fishing-log/trip-log" } }.`,
};
}
return { ok: true, folder, name };
diff --git a/packages/server/src/mcp/tools/verb-tools.test.ts b/packages/server/src/mcp/tools/verb-tools.test.ts
index 265d370fa..81f19ad2c 100644
--- a/packages/server/src/mcp/tools/verb-tools.test.ts
+++ b/packages/server/src/mcp/tools/verb-tools.test.ts
@@ -177,7 +177,7 @@ describe('write/edit/delete({ template }) — server-routed for attribution (PRD
template: { path: 'x/a.b', content: 'ok', frontmatter: { title: 'A' } },
});
expect(r.isError).toBe(true);
- expect(textOf(r)).toContain('must be letters, digits');
+ expect(textOf(r)).toContain('must use letters and digits');
expect(existsSync(join(cwd, 'x', '.ok', 'templates', 'a.b.md'))).toBe(false);
});
});
@@ -299,6 +299,19 @@ describe('write({ document }) — template-availability nudge on create', () =>
});
});
+ test('a decomposed template name finds the composed template', async () => {
+ const cwd = newProject();
+ mkdirSync(join(cwd, 'menus', '.ok', 'templates'), { recursive: true });
+ writeFileSync(
+ join(cwd, 'menus', '.ok', 'templates', 'café.md'),
+ '---\ntitle: Café\ndescription: A menu\n---\n\n## Menu\n',
+ );
+ await withWriteStub(cwd, async (write) => {
+ const r = await write({ document: { path: 'menus/today', template: 'cafe\u0301' } });
+ expect(r.isError).toBeUndefined();
+ });
+ });
+
test('create in a folder with no templates does not nudge', async () => {
const cwd = newProject();
mkdirSync(join(cwd, 'scratch'), { recursive: true });
diff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.ts
index af9a436ae..283096a5b 100644
--- a/packages/server/src/mcp/tools/write.ts
+++ b/packages/server/src/mcp/tools/write.ts
@@ -4,6 +4,7 @@ import {
type DocExtension,
type FrontmatterMap,
type FrontmatterPatch,
+ findTemplateByName,
instantiateDoc,
normalizeBridge,
type ProblemType,
@@ -274,7 +275,7 @@ async function writeOneDoc(
if (spec.template !== undefined) {
const parentFolder = parentFolderOf(docName);
const available = resolveTemplatesAvailable(cwd, parentFolder);
- const matched = available.find((t) => t.name === spec.template);
+ const matched = findTemplateByName(available, spec.template);
if (!matched) {
return {
docName,